{"id":16057,"library":"http-auth","title":"HTTP Basic and Digest Authentication for Node.js","description":"The `http-auth` package provides robust HTTP basic and digest access authentication capabilities for Node.js applications. Currently stable at version 4.2.1, it receives infrequent but consistent updates, addressing security and dependency concerns (e.g., uuid updates, security fixes in 4.1.3). It differentiates itself by offering built-in support for both basic and digest authentication schemes, configurable realms, and flexible user credential storage, including file-based methods (e.g., `.htpasswd` format). While primarily designed for CommonJS environments, it offers a straightforward API for integrating authentication into standard Node.js HTTP servers, allowing developers to define custom user stores via file paths or callback functions, and customize authentication parameters like algorithm (MD5, MD5-sess) and Quality of Protection (QOP) for digest authentication.","status":"active","version":"4.2.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/gevorg/http-auth","tags":["javascript","http","basic","digest","access","authentication"],"install":[{"cmd":"npm install http-auth","lang":"bash","label":"npm"},{"cmd":"yarn add http-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-auth","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is CommonJS-only. Direct ESM imports will fail without a transpilation step or a CommonJS wrapper.","wrong":"import auth from 'http-auth';","symbol":"auth","correct":"const auth = require('http-auth');"},{"note":"The `basic` authentication strategy is a method on the `auth` object, not a direct export.","wrong":"import { basic } from 'http-auth';","symbol":"basic","correct":"const basic = auth.basic({...});"},{"note":"The `digest` authentication strategy is a method on the `auth` object, not a direct export.","wrong":"import { digest } from 'http-auth';","symbol":"digest","correct":"const digest = auth.digest({...});"}],"quickstart":{"code":"const http = require(\"http\");\nconst auth = require(\"http-auth\");\nconst path = require('path');\nconst fs = require('fs');\n\n// Create a dummy .htpasswd file for the example\nconst htpasswdPath = path.join(__dirname, \"users.htpasswd\");\nfs.writeFileSync(htpasswdPath, \"gevorg:gpass\\nSarah:testpass\");\n\nconst basicAuth = auth.basic({\n  realm: \"Protected Area.\",\n  file: htpasswdPath // gevorg:gpass, Sarah:testpass\n});\n\nhttp.createServer(\n  basicAuth.check((req, res) => {\n    res.end(`Welcome to the private area - ${req.user} (${req.method} ${req.url})!`);\n  })\n)\n.listen(1337, () => {\n  console.log(\"Server running at http://127.0.0.1:1337/\");\n  console.log(\"Try accessing with 'gevorg' and 'gpass' or 'Sarah' and 'testpass'.\");\n  console.log(\"To stop the server, press Ctrl+C. The users.htpasswd file will be removed.\");\n});\n\n// Clean up the dummy file on exit\nprocess.on('exit', () => {\n  if (fs.existsSync(htpasswdPath)) {\n    fs.unlinkSync(htpasswdPath);\n    console.log(\"Cleaned up users.htpasswd\");\n  }\n});","lang":"javascript","description":"This quickstart sets up a basic HTTP server with HTTP Basic Authentication, reading user credentials from a temporary `.htpasswd` file. It demonstrates how to initialize the `basic` authentication middleware and integrate it into a standard Node.js `http.createServer` callback."},"warnings":[{"fix":"Ensure your project is configured for CommonJS, or use a build tool like Webpack/Rollup that can transpile CommonJS modules for ESM environments. If using Node.js ESM, you must use `createRequire` or a dynamic import (`await import()`) if absolutely necessary, but it's generally recommended for CJS-only packages to stick to `require()` environments.","message":"The package is strictly CommonJS. Attempting to use `import` statements directly in a pure ESM Node.js project will result in a `TypeError: require is not defined` or similar errors. It is not designed for direct ESM consumption.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade to `http-auth` version 4.1.3 or newer to patch known security issues: `npm install http-auth@latest`.","message":"Older versions of `http-auth` (prior to 4.1.3) contained unspecified security vulnerabilities. Users on these versions are at risk and should upgrade immediately.","severity":"breaking","affected_versions":"<4.1.3"},{"fix":"Consider contributing `d.ts` files to the project, providing a `types/http-auth/index.d.ts` file in your project, or looking for community-maintained types (e.g., `@types/http-auth`, though none exist currently).","message":"The `http-auth` package does not ship with official TypeScript declaration files (`.d.ts`). Developers using TypeScript will need to either create their own declaration files or use `@ts-ignore` directives, leading to a less type-safe development experience.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"For production, integrate with more secure authentication backends such as databases with strong hashing (e.g., bcrypt), external identity providers, or OAuth/OIDC systems. If file-based is unavoidable, ensure robust file system permissions and use strong hashing algorithms provided by utilities like `htpasswd` or `htdigest` with modern secure options.","message":"Using file-based authentication (e.g., `.htpasswd` files) for storing user credentials, especially with plaintext or basic hashes, is generally not recommended for production applications due to security risks. Without strong file system permissions and hashing algorithms, credentials can be easily compromised.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change your project's `package.json` to `\"type\": \"commonjs\"` or rename your script file to have a `.cjs` extension. If you must use ESM, consider using a dynamic import: `const auth = await import('http-auth').then(m => m.default || m);` (though this package exports directly, not a default).","cause":"Attempting to use `require()` in a Node.js project configured as an ES Module (`\"type\": \"module\"` in `package.json`).","error":"ReferenceError: require is not defined"},{"fix":"Ensure that `const auth = require(\"http-auth\");` is present and executed correctly before you try to call `auth.basic` or `auth.digest`. This often happens if the `require` statement is conditional or placed incorrectly.","cause":"The `auth` object was not correctly imported or is undefined when attempting to call `auth.basic()`.","error":"TypeError: auth.basic is not a function"},{"fix":"Verify the `file` path is correct and absolute. Use `path.join(__dirname, 'data', 'users.htpasswd')` for relative paths within your project. Ensure the Node.js process has read permissions for the file.","cause":"The file specified in the `file` option for basic or digest authentication does not exist at the given path or the Node.js process lacks read permissions for it.","error":"Error: ENOENT: no such file or directory, open '/path/to/users.htpasswd'"}],"ecosystem":"npm"}