{"id":11261,"library":"lws-basic-auth","title":"lws-basic-auth Middleware","description":"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.","status":"maintenance","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/lwsjs/basic-auth","tags":["javascript","lws","lws-middleware","local-web-server","web"],"install":[{"cmd":"npm install lws-basic-auth","lang":"bash","label":"npm"},{"cmd":"yarn add lws-basic-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add lws-basic-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is an `lws` middleware plugin and requires `lws` to function. `lws` acts as its host server.","package":"lws","optional":false}],"imports":[{"note":"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.","wrong":"import { BasicAuth } from 'lws-basic-auth';","symbol":"BasicAuth","correct":"import BasicAuth from 'lws-basic-auth'; // ESM\n// OR\nconst BasicAuth = require('lws-basic-auth'); // CommonJS"}],"quickstart":{"code":"import Lws from 'lws';\nimport BasicAuth from 'lws-basic-auth'; // Assuming ESM compatibility or transpilation\nimport path from 'path';\nimport fs from 'fs';\n\n// Create a dummy file to serve\nconst publicDir = path.join(process.cwd(), 'public');\nconst secretFile = path.join(publicDir, 'secret.html');\n\nif (!fs.existsSync(publicDir)) {\n  fs.mkdirSync(publicDir);\n}\nfs.writeFileSync(secretFile, '<h1>This is a secret page!</h1>', 'utf8');\n\nconst username = process.env.AUTH_USER ?? 'testuser';\nconst password = process.env.AUTH_PASS ?? 'testpass';\n\nconst lws = new Lws();\n\nlws.start({\n  stack: [BasicAuth, 'lws-static'], // Order matters: auth first, then static to protect files\n  directory: publicDir,\n  port: 8000,\n  auth: {\n    user: username,\n    pass: password,\n  },\n}).then(() => {\n  console.log(`lws-basic-auth server running on http://localhost:8000`);\n  console.log(`Access with username: ${username}, password: ${password}`);\n  console.log(`Try http://localhost:8000/secret.html`);\n  console.log(`\nTo stop the server, press Ctrl+C`);\n}).catch(err => {\n  console.error('Failed to start lws:', err);\n  process.exit(1);\n});\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `lws-basic-auth` is listed before any middleware that serves static files or routes that need protection in your `lws` `stack` configuration.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `lws` globally or as a project dependency: `npm install lws` or `npm install --save-dev lws`.","cause":"The main `lws` package is not installed as a dependency alongside `lws-basic-auth`.","error":"Error: Cannot find module 'lws'"},{"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`.","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.","error":"401 Unauthorized"},{"fix":"Provide both `--auth.user <username>` and `--auth.pass <password>` via the command line, or `auth: { user: '...', pass: '...' }` in your programmatic `lws` configuration object.","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`.","error":"Error: 'auth.user' and 'auth.pass' options are required when using lws-basic-auth."}],"ecosystem":"npm"}