lws-blacklist Middleware

Common errors

• Error: Middleware 'lws-blacklist' not found or invalid.

  cause The lws server could not locate or correctly load the `lws-blacklist` module, either due to incorrect installation, a typo in the stack name, or an incompatible version.
  fix Ensure `lws-blacklist` is installed (`npm install lws-blacklist`). If using the CLI `--stack` option, ensure `lws-blacklist` is spelled correctly. For programmatic use, verify the import path and that the module exports a valid middleware factory function.

• Request to '/admin/dashboard' was not blocked as expected.

  cause The regular expression provided for blacklisting did not correctly match the intended route, or the blacklist middleware is not correctly ordered in the `lws` stack.
  fix Double-check your regex patterns for accuracy. Use a regex testing tool to confirm they match your target paths. In `lws`, middleware order matters; ensure `lws-blacklist` is positioned early enough in your middleware stack to intercept requests before other middleware might process or serve them.

• TypeError: Cannot read properties of undefined (reading 'blacklist')

  cause This error typically occurs if `lws-blacklist` is being used programmatically but its configuration object is missing or malformed, or if the `lws` instance is not correctly passing options to the middleware.
  fix When using `lws-blacklist` programmatically, ensure you pass the `blacklist` array of patterns as expected by its API. For CLI usage, verify the `--blacklist` option is correctly formatted with valid path arguments.

Warnings

• gotcha The `lws-blacklist` package name and its core functionality utilize the term 'blacklist', which is increasingly being deprecated in favor of 'denylist' or 'blocklist' across the tech industry for reasons of inclusivity. While the functionality remains, newer projects might prefer alternative terminology.
  Fix: Consider documenting usage with 'denylist' or 'blocklist' in your own project's context, or explore alternative middleware if this terminology is a concern.
• breaking The lws ecosystem uses Koa for its middleware. If there were changes in how lws expects middleware to be structured (e.g., from an Express-style to a Koa-style signature, or changes in context object properties), older versions of lws-blacklist might not be compatible with newer lws versions.
  Fix: Always check the lws documentation and lws-blacklist release notes for compatibility when upgrading major versions of either package. Ensure your middleware functions conform to the Koa (ctx, next) => {} signature.
• gotcha Regular expressions provided to `--blacklist` are matched against the request path. Misconfigured or overly broad regexes can block legitimate routes, while overly specific ones can fail to block intended targets. Ensure correct regex syntax and test thoroughly.
  Fix: Test your blacklist patterns thoroughly with expected valid and invalid URLs. Online regex testers can help in validating patterns. Remember that regex special characters (e.g., '.', '*', '?', '+') need to be escaped if you mean them literally.
• gotcha The `lws-blacklist` package has an `npm audit` warning due to its transitive dependency on `path-to-regexp` (GHSA-9wv6-86v2-598j). This indicates a potential security vulnerability in a sub-dependency, though its direct impact on lws-blacklist's specific use case might vary.
  Fix: Regularly run `npm audit fix` and `npm update` to ensure all dependencies are at their latest, patched versions. If the vulnerability persists, consult the `lws-blacklist` GitHub issues for official patches or recommended workarounds.
• gotcha The package `lws-blacklist` version `3.0.0` was last published approximately six years ago, and its core dependency `lws` also has a noted 'not healthy version release cadence'. This implies a potentially slower maintenance cycle and a reduced likelihood of new feature development or rapid vulnerability patches.
  Fix: Evaluate the project's long-term maintenance status and community activity if active development or immediate patching of issues is critical for your application. Consider contributing to the project or forking it if specific needs arise.

Install

• npm install lws-blacklist npm
• yarn add lws-blacklist yarn
• pnpm add lws-blacklist pnpm

Imports

• Lws
  wrong:

  const Lws = require('lws')

  correct:

  import Lws from 'lws';

  lws supports both ESM and CJS; programmatic use often starts with importing the Lws class.
• blacklistMiddleware
  wrong:

  import { blacklistMiddleware } from 'lws-blacklist';

  correct:

  import blacklistMiddleware from 'lws-blacklist';

  Assuming lws-blacklist exports a default function that returns the middleware; direct symbol names might vary if it's a class or named export.

Quickstart

Demonstrates programmatic setup of an lws server with lws-blacklist, blocking specific URL patterns like '/admin/(.*)' and '/secret-page.html' using the `--blacklist` option equivalent.

import Lws from 'lws';
import blacklistMiddleware from 'lws-blacklist';

const server = new Lws();

async function startServer() {
  try {
    const options = {
      port: 8000,
      stack: ['lws-static'], // Ensure static serving is also enabled
      directory: './public', // Serve files from a 'public' directory
      blacklist: ['/admin/(.*)', '/secret-page.html'], // Routes to forbid
      // For programmatic use, the middleware itself is added to the stack
      // but the configuration comes via options that lws-blacklist processes.
      // If lws-blacklist exported a direct Koa middleware, it would look like:
      // middleware: [blacklistMiddleware({ blacklist: ['/admin/(.*)'] })]
    };

    await server.start(options);
    console.log(`lws-blacklist example server running at http://localhost:${options.port}`);
    console.log('Try accessing http://localhost:8000/secret-page.html or http://localhost:8000/admin/dashboard.html');
    console.log('Serving static files from ./public');
  } catch (error) {
    console.error('Failed to start lws server:', error);
  }
}

// Create a public directory and some test files
import fs from 'fs';
if (!fs.existsSync('./public')) fs.mkdirSync('./public');
fs.writeFileSync('./public/index.html', '<h1>Hello from lws!</h1><p>Public page.</p>');
fs.writeFileSync('./public/secret-page.html', '<h1>ACCESS DENIED</h1><p>This page should be blocked.</p>');
fs.writeFileSync('./public/admin/dashboard.html', '<h1>Admin Dashboard</h1><p>This page should be blocked.</p>');

startServer();