lws-basic-auth Middleware

2.0.0 · maintenance · verified Sun Apr 19

lws-basic-auth is a middleware plugin designed to password-protect local-web-server (lws) instances using HTTP Basic Authentication. It integrates directly into the `lws` command-line and programmatic configuration, allowing users to define a username and password to restrict access to the served content. The current stable version is 2.0.0. While `lws` itself has seen infrequent updates, this middleware provides a focused and lightweight solution specifically for the `lws` ecosystem. It differentiates itself from general-purpose basic authentication libraries by being tightly coupled with `lws`'s plugin architecture, offering a streamlined setup for securing local development servers. Its release cadence is infrequent, suggesting it is a stable package in maintenance mode, receiving minimal updates.

Common errors

```
Error: Cannot find module 'lws'
```
cause The main `lws` package is not installed as a dependency alongside `lws-basic-auth`.

fix Install `lws` globally or as a project dependency: `npm install lws` or `npm install --save-dev lws`.
```
401 Unauthorized
```
cause The browser or client did not send the correct Basic Authentication credentials (username and password) or sent no credentials at all for a protected resource.

fix Ensure the client is configured to send the correct `Authorization: Basic <base64-encoded-credentials>` header. For browsers, a prompt should appear; ensure correct credentials are entered. For `curl`, use `curl -u username:password http://localhost:8000`.
```
Error: 'auth.user' and 'auth.pass' options are required when using lws-basic-auth.
```
cause The `lws-basic-auth` middleware was added to the stack, but the necessary `auth.user` or `auth.pass` configuration options were not provided to `lws`.

fix Provide both `--auth.user <username>` and `--auth.pass <password>` via the command line, or `auth: { user: '...', pass: '...' }` in your programmatic `lws` configuration object.

Warnings

breaking Explicit breaking changes between `lws-basic-auth` v1.x and v2.x are not extensively documented within the project's GitHub releases or changelog. Developers upgrading between major versions should review the upstream `lws` changes and test thoroughly, as API shifts are common with major version increments.
Fix: Thoroughly test existing integrations when upgrading from 1.x to 2.x. Consult the main `lws` project's changelog and relevant middleware documentation for any related breaking changes or updated configuration patterns.
gotcha Basic Authentication transmits credentials in base64 encoding, which is easily reversible. It is NOT secure for sensitive information over unencrypted HTTP. Always use Basic Authentication over HTTPS (TLS/SSL) to prevent credentials from being intercepted in plain text.
Fix: Deploy your `lws` server with HTTPS enabled when using `lws-basic-auth` in any environment beyond local development. Consider more robust authentication mechanisms for production applications handling sensitive data.
gotcha Basic Authentication, by default, sends credentials with every request in the Authorization header. This can lead to issues if the username/password pair is easily guessable or if sessions are not properly managed, potentially exposing resources to brute-force attacks.
Fix: Use strong, unique credentials. Implement rate limiting or IP blocking at a higher level (e.g., reverse proxy, firewall) to mitigate brute-force attempts if `lws` is exposed directly to the internet.
gotcha The `lws-basic-auth` middleware must be placed correctly in the `lws` middleware stack. If other middlewares that serve content (e.g., `lws-static`) are placed before `lws-basic-auth`, they may serve content without requiring authentication, bypassing the protection.
Fix: Ensure `lws-basic-auth` is listed before any middleware that serves static files or routes that need protection in your `lws` `stack` configuration.

Install

npm install lws-basic-auth npm
yarn add lws-basic-auth yarn
pnpm add lws-basic-auth pnpm

Imports

BasicAuth
wrong:
```
import { BasicAuth } from 'lws-basic-auth';
```
correct:
```
import BasicAuth from 'lws-basic-auth'; // ESM
// OR
const BasicAuth = require('lws-basic-auth'); // CommonJS
```
The package primarily exports a default function (or a class constructor) that `lws` uses. It is designed to be loaded by `lws` either via its `--stack` option or programmatically as a plugin instance. As of v2.0.0, it likely uses CommonJS exports due to its age and Node.js >=10 requirement, but ESM import syntax is provided for completeness with bundlers.

Quickstart

This quickstart sets up an `lws` server with `lws-basic-auth` middleware, protecting a static HTML file. It demonstrates both programmatic setup with environment variables for credentials and accessing the protected resource.

import Lws from 'lws';
import BasicAuth from 'lws-basic-auth'; // Assuming ESM compatibility or transpilation
import path from 'path';
import fs from 'fs';

// Create a dummy file to serve
const publicDir = path.join(process.cwd(), 'public');
const secretFile = path.join(publicDir, 'secret.html');

if (!fs.existsSync(publicDir)) {
  fs.mkdirSync(publicDir);
}
fs.writeFileSync(secretFile, '<h1>This is a secret page!</h1>', 'utf8');

const username = process.env.AUTH_USER ?? 'testuser';
const password = process.env.AUTH_PASS ?? 'testpass';

const lws = new Lws();

lws.start({
  stack: [BasicAuth, 'lws-static'], // Order matters: auth first, then static to protect files
  directory: publicDir,
  port: 8000,
  auth: {
    user: username,
    pass: password,
  },
}).then(() => {
  console.log(`lws-basic-auth server running on http://localhost:8000`);
  console.log(`Access with username: ${username}, password: ${password}`);
  console.log(`Try http://localhost:8000/secret.html`);
  console.log(`
To stop the server, press Ctrl+C`);
}).catch(err => {
  console.error('Failed to start lws:', err);
  process.exit(1);
});

view raw JSON →