Node.js Static Server with Basic Auth

Common errors

• TypeError: require is not a function

  cause Attempting to use `require()` in an ECMAScript Module (ESM) context.
  fix Ensure your Node.js file is treated as CommonJS (e.g., `.js` file without `"type": "module"` in `package.json`, or explicitly `.cjs` extension). This package does not support ESM imports.

• Error: Cannot find module 'node-static-auth'

  cause The package has not been installed or the path is incorrect.
  fix Run `npm install node-static-auth` in your project directory.

• ERR_OSSL_EVP_UNSUPPORTED

  cause Modern Node.js versions (e.g., Node.js 17+) have stricter OpenSSL policies that may reject older or insecure cryptographic algorithms used by outdated dependencies (like those potentially bundled here for SSL).
  fix This issue is indicative of the package's age. It's strongly recommended to migrate to an actively maintained solution. As a temporary workaround for development, you might try `NODE_OPTIONS='--openssl-legacy-provider' node your-app.js`, but this is not suitable for production.

Warnings

• breaking The package is abandoned and has not been updated in over 8 years. It is built on outdated Node.js versions (engines >= 0.10.0) and dependencies, making it insecure and incompatible with modern Node.js environments (>=16).
  Fix: Migrate to a actively maintained static file server solution like `serve-static`, `express.static`, or `sirv` combined with modern authentication and logging middleware.
• gotcha Using custom error pages (401, 404, 500) is not supported when HTTP/2 is enabled. The server will fall back to less aesthetically pleasing default pages.
  Fix: If custom error pages are critical, ensure `server.http2` is set to `false` in the configuration.
• gotcha The HTTP/2 support in this package is noted as 'experimental' and might contain bugs or compatibility issues, particularly with other bundled modules.
  Fix: Avoid using the HTTP/2 feature. If HTTP/2 is required, use a modern, actively maintained server framework that provides robust HTTP/2 support.
• breaking Basic Authentication, while provided, is generally insecure when used without HTTPS due to credentials being transmitted in plain text. Relying on this older, abandoned package for security-sensitive applications is extremely risky.
  Fix: Always enforce HTTPS (`ssl.enabled: true`) when using Basic Auth. For new projects, consider modern authentication mechanisms like OAuth2 or token-based authentication with updated libraries.
• gotcha The package is CommonJS-only. Attempting to use `import` syntax will result in errors in an ESM context.
  Fix: Ensure your project uses CommonJS (`require()`) or use a build tool like Webpack/Rollup to transpile CommonJS modules into ESM if absolutely necessary, though this is not recommended for an abandoned package.

Install

• npm install node-static-auth npm
• yarn add node-static-auth yarn
• pnpm add node-static-auth pnpm

Imports

• NodeStaticAuth
  wrong:

  import NodeStaticAuth from 'node-static-auth';

  correct:

  const NodeStaticAuth = require('node-static-auth');

  This package is CommonJS-only, reflecting its age. Direct ESM `import` statements will fail.

Quickstart

This quickstart initializes and starts an HTTPS static server with Basic authentication and access logging, demonstrating common configuration options.

const NodeStaticAuth = require('node-static-auth');

// IMPORTANT: Replace 'path-to-public-directory' with the actual path to your static files.
// For example, if your static files are in a 'public' folder in the project root:
// const PUBLIC_DIR = path.join(process.cwd(), 'public');
// Ensure 'public' directory exists and contains 'index.html', 'your-forbidden.html', etc.

const config = {
    nodeStatic: {
        root: 'path-to-public-directory', // e.g., 'public'
        options: {
            indexFile: 'your-index.html' // e.g., 'index.html'
        },
        customPages: {
            forbidden: 'your-forbidden.html', // e.g., '401.html'
            notFound: 'your-not-found.html',   // e.g., '404.html'
            error: 'your-error.html'         // e.g., '500.html'
        }
    },
    server: {
        port: 3001,
        http2: false, // Set to true if running Node >= 9.x, but note limitations
        ssl: {
            enabled: true,
            httpListener: 3000,
            // Example: Replace with actual paths to your SSL certificate and key
            // key: path.join(process.cwd(), 'ssl', 'server.key'),
            // cert: path.join(process.cwd(), 'ssl', 'server.crt'),
            key: process.env.SSL_KEY_PATH ?? 'path/to/server.key', // Placeholder
            cert: process.env.SSL_CERT_PATH ?? 'path/to/server.crt' // Placeholder
        }
    },
    auth: {
        enabled: true,
        users: {
            admin: 'password123'
        }
    },
    logger: {
        enabled: true,
        path: 'access.log',
        type: 'combined', // Standard Apache combined log format
        rotation: {
            interval: '1d', // Rotate daily
            maxFiles: 10    // Keep a maximum of 10 rotated log files
        }
    }
};

const server = new NodeStaticAuth(config);
console.log(`Server running on HTTPS at https://localhost:${config.server.port} and HTTP listener on http://localhost:${config.server.ssl.httpListener}`);