Registry / auth-security / lws-basic-auth

lws-basic-auth

library2.0.0jsnpmunverified

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.

auth-security web-framework

npm install lws-basic-auth

github ↗package ↗

INSTALL

IMPORT

SIG · LWS-BASIC-AUTH

lws-basic-auth

auth-securityjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BasicAuth

✓ import BasicAuth from 'lws-basic-auth'; // ESM // OR const BasicAuth = require('lws-basic-auth'); // CommonJS

✗ import { BasicAuth } from 'lws-basic-auth';

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.

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); });

lws --version

Debug

Known issues

breakingExplicit 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.

affects: >=2.0.0

gotchaBasic 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.

affects: >=1.0.0

gotchaBasic 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'lws'

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

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.

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.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

lwsrequiredThis package is an `lws` middleware plugin and requires `lws` to function. `lws` acts as its host server.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lwsjs/basic-auth ↗

packagehttps://www.npmjs.com/package/lws-basic-auth ↗