{"id":16709,"library":"basic","title":"HTTP Basic Auth for Node.js","description":"The `basic` package provides a minimalist HTTP Basic Authentication middleware for Node.js applications. It abstracts the process of parsing the `Authorization` header and validating user credentials against a provided callback function. As of its latest stable version, 2.0.3 (published over seven years ago), the package is primarily designed for CommonJS environments and integrates directly with Node.js's native `http` module. It follows a callback-based asynchronous pattern for credential verification. Its primary differentiation lies in its extreme simplicity and lack of external dependencies, making it a lightweight option for adding basic authentication to a server. Due to its age, it receives infrequent updates and may not natively support modern JavaScript features like Promises or ES Modules without additional wrappers.","status":"maintenance","version":"2.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/thisandagain/basic","tags":["javascript"],"install":[{"cmd":"npm install basic","lang":"bash","label":"npm"},{"cmd":"yarn add basic","lang":"bash","label":"yarn"},{"cmd":"pnpm add basic","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is CommonJS-only. Attempting to use ES Module import syntax will result in a runtime error.","wrong":"import basic from 'basic'; // Does not support ES Modules","symbol":"basic","correct":"const basic = require('basic');"},{"note":"The primary export is a factory function that takes a callback-based authentication function as its argument, returning the middleware.","symbol":"authFunction","correct":"const auth = basic(function (user, pass, callback) { /* ... */ });"}],"quickstart":{"code":"const http = require('http');\nconst basic = require('basic');\n\nconst auth = basic(function (user, pass, callback) {\n    // In a real application, you'd verify credentials against a database\n    if (user === 'let' && pass === 'me in') {\n        // Credentials are valid, proceed\n        return callback(null);\n    }\n    // Credentials invalid, respond with 401\n    callback(401);\n});\n\nconst server = http.createServer(function (req, res) {\n    auth(req, res, function (err) {\n        // err will be 401 if authentication failed\n        const headers = (err) ? {'WWW-Authenticate': 'Basic realm=\"Secure Area\"'} : {};\n        res.writeHead(err || 200, headers);\n        res.end(err ? 'Unauthorized' : 'Welcome to the secure area!');\n    });\n});\n\nserver.listen(8000, () => {\n    console.log('Server running on http://localhost:8000');\n    console.log('Test with: curl --head -H \"Authorization:Basic bGV0Om1lIGlu\" http://localhost:8000');\n    console.log('Test with invalid credentials: curl --head -H \"Authorization:Basic d3Jvbmc6Y3JlZGVudGlhbHM=\" http://localhost:8000');\n});","lang":"javascript","description":"Demonstrates setting up a basic HTTP server with basic authentication using the `basic` package, handling success and 401 responses."},"warnings":[{"fix":"Use `const basic = require('basic');` for importing the module.","message":"The `basic` package is CJS-only and does not support ES Modules natively. Attempting to use `import` statements will result in runtime errors.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Ensure `res.writeHead(401, {'WWW-Authenticate': 'Basic realm=\"Secure Area\"'});` is called when authentication fails, replacing 'Secure Area' with your desired realm.","message":"This package requires manual handling of the `WWW-Authenticate` header for 401 Unauthorized responses. Failing to set this header will prevent browsers and clients from prompting for credentials.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Consider wrapping the authentication function in a Promise for easier integration with async/await patterns, or use a more modern authentication middleware for new projects.","message":"The package uses an older callback-based asynchronous pattern. It does not natively support Promises or async/await syntax, which might require wrapping the authentication function for use in modern async codebases.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change your import to `const basic = require('basic');` as the package is CommonJS-only.","cause":"Attempting to use ES Module `import basic from 'basic';` syntax, or incorrect `require` usage.","error":"TypeError: basic is not a function"},{"fix":"On authentication failure, ensure you set the `WWW-Authenticate` header: `res.writeHead(401, {'WWW-Authenticate': 'Basic realm=\"Secure Area\"'});`","cause":"The `WWW-Authenticate` header was not correctly set in the HTTP response when authentication failed.","error":"401 Unauthorized (but no login prompt in browser)"},{"fix":"Double-check your `user` and `pass` comparison logic and ensure `callback(null)` is called when credentials are valid, and `callback(401)` (or another error code) when invalid.","cause":"The callback function provided to `basic()` is not correctly invoking `callback(null)` on success or `callback(401)` on failure, or the credential verification logic is flawed.","error":"Authentication always fails / user and pass are always incorrect"}],"ecosystem":"npm"}