@nabhiraj/nab-auth 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nabhiraj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,363 @@
-# Temporary Holding Version
+# nab-auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![license](https://img.shields.io/npm/l/@nabhiraj/nab-auth.svg)](LICENSE)
+
+Configurable authentication for Express and MongoDB. `nab-auth` provides
+Argon2id password hashing, RS256 JWTs, refresh-token rotation, roles,
+registration verification, and optional two-factor authentication.
+
+The library does not load environment variables or send email/SMS itself. The
+host application owns configuration and code delivery.
+
+## Features
+
+- Email/password registration and login with Argon2id password hashes
+- Short-lived RS256 access tokens and rotating refresh-token cookies
+- Public-key rotation using JWT `kid` headers
+- Role claims and administrator-protected role management
+- Optional registration-code verification and two-factor authentication
+- MongoDB/Atlas storage with unique and TTL indexes created automatically
+- Verifier-only mode for services that only need to validate access tokens
+
+## Requirements
+
+- Node.js 20 or later
+- Express 5
+- MongoDB or MongoDB Atlas
+- An RSA key pair for RS256 JWT signing
+
+`argon2` is a native dependency. Most supported systems use a prebuilt binary;
+unusual platforms may need standard Node.js native build tools.
+
+## Installation
+
+```bash
+npm install @nabhiraj/nab-auth express
+```
+
+## Quick start
+
+```js
+import express from "express";
+import { createAuthenticationLibrary } from "@nabhiraj/nab-auth";
+
+const app = express();
+app.use(express.json());
+
+const auth = createAuthenticationLibrary({
+  mongo: {
+    uri: process.env.MY_AUTH_MONGO_URI,
+    databaseName: "my_auth_database"
+  },
+  jwt: {
+    issuer: "my-service",
+    audience: "my-client",
+    keys: {
+      privateKeyPath: process.env.MY_JWT_PRIVATE_KEY_PATH,
+      publicKeyPath: process.env.MY_JWT_PUBLIC_KEY_PATH
+    }
+  },
+  defaultAdmin: { enabled: false }
+});
+
+const createTokenPayload = (user) => ({
+  email: user.email,
+  nab_role: user.nab_role || []
+});
+
+app.use(
+  "/auth",
+  auth.createAuthRouter(createTokenPayload, {
+    sendRegistrationCode: async ({ email, verificationCode }) => {
+      await sendEmail(email, `Your verification code is ${verificationCode}`);
+    },
+    sendTwoFactorCode: async ({ email, verificationCode }) => {
+      await sendEmail(email, `Your 2FA code is ${verificationCode}`);
+    }
+  })
+);
+
+app.get("/api/private", auth.requireJwt, (req, res) => {
+  res.json({ userId: req.auth.sub });
+});
+
+app.use(auth.jwtErrorHandler);
+await auth.connectToDatabase();
+app.listen(3000);
+```
+
+`sendEmail` is an application function you provide. Configure a code-delivery
+callback only when registration verification or two-factor authentication is
+enabled.
+
+## Core API
+
+```js
+import {
+  createAuthenticationLibrary,
+  createFileJwtKeyProvider,
+  defaultAuthConfig
+} from "@nabhiraj/nab-auth";
+```
+
+`createAuthenticationLibrary(config)` creates isolated state: its MongoDB
+client, JWT-key cache, middleware, and router do not share state with another
+instance.
+
+| Member | Purpose |
+| --- | --- |
+| `connectToDatabase()` | Connects to MongoDB and creates configured collections/indexes. |
+| `closeDatabase()` | Closes this instance's MongoDB client. |
+| `createAuthRouter(payloadFactory, options)` | Creates the Express authentication router. |
+| `requireJwt` | Verifies access tokens and sets claims on `req.auth`. |
+| `requireNabAdmin` | Requires the configured administrator role. |
+| `jwtErrorHandler` | Express JWT error middleware; mount after protected routes. |
+| `config` | The merged configuration used by this instance. |
+
+`payloadFactory(user)` creates application-specific access-token claims. The
+library adds standard JWT claims, `sub`, and `tokenType: "access"`.
+
+## Configuration
+
+Every setting is optional unless a feature needs it. Omitted values use
+`defaultAuthConfig`.
+
+```js
+const auth = createAuthenticationLibrary({
+  mongo: {
+    uri: process.env.MY_AUTH_MONGO_URI,
+    databaseName: "auth_db",
+    usersCollectionName: "users",
+    potentialUsersCollectionName: "potential_user"
+  },
+  jwt: {
+    issuer: "my-service",
+    audience: "my-client",
+    algorithm: "RS256",
+    accessTokenTtl: "15m",
+    refreshTokenTtl: "7d",
+    keyCacheTtlMs: 15 * 60 * 1000,
+    keys: {
+      privateKeyPath: process.env.MY_PRIVATE_KEY_PATH,
+      publicKeyPath: process.env.MY_PUBLIC_KEY_PATH
+    }
+  },
+  authorization: {
+    adminRole: "nab_admin",
+    userRegistrationRequiresNabAdmin: false,
+    passwordChangeRequiresNabAdmin: false,
+    nabAdminCanChangeOtherUsersPasswords: true
+  },
+  registration: {
+    verificationRequired: false,
+    codeDigits: 6,
+    codeTtlMs: 10 * 60 * 1000
+  },
+  twoFactor: {
+    required: false,
+    codeDigits: 6,
+    codeTtlMs: 10 * 60 * 1000
+  },
+  passwordHash: {
+    memoryCost: 19456,
+    timeCost: 2,
+    parallelism: 1
+  },
+  refreshCookie: {
+    name: "refresh_token",
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+    path: "/auth/refresh",
+    maxAgeMs: 7 * 24 * 60 * 60 * 1000
+  },
+  codeDelivery: {
+    allowCodeInResponseWithoutSender: false
+  },
+  defaultAdmin: {
+    enabled: false,
+    email: "admin@admin.com",
+    password: "change-this",
+    roles: ["nab_admin"]
+  }
+});
+```
+
+Use `refreshCookie.secure: true` for HTTPS production deployments. It defaults
+to `false` only for local HTTP development. `defaultAdmin.enabled` defaults to
+`false`; never enable it with a known or weak password.
+
+### Code delivery callbacks
+
+```js
+auth.createAuthRouter(createTokenPayload, {
+  sendRegistrationCode: async ({
+    email,
+    verificationCode,
+    codeGeneratedAt,
+    codeExpiresAt
+  }) => {
+    await emailProvider.send(email, verificationCode);
+  },
+  sendTwoFactorCode: async ({
+    email,
+    verificationCode,
+    codeGeneratedAt,
+    codeExpiresAt
+  }) => {
+    await smsProvider.send(email, verificationCode);
+  }
+});
+```
+
+`codeDelivery.allowCodeInResponseWithoutSender` controls missing callbacks:
+
+- `true` returns the generated code in the HTTP response. Use only for local
+  development or automated tests.
+- `false` rejects the request when the required sender callback is absent. Use
+  this in production.
+
+Registration codes are stored as Argon2id hashes in `potential_user` and are
+removed by a MongoDB TTL index. 2FA code hashes are stored on the user and are
+atomically consumed after a successful token issue.
+
+## JWT key files and rotation
+
+The built-in key provider loads JSON files lazily and refreshes its cache after
+`jwt.keyCacheTtlMs`.
+
+Private-key JSON has one active signing key:
+
+```json
+{
+  "kid": "101",
+  "privateKey": "-----BEGIN PRIVATE KEY-----..."
+}
+```
+
+Public-key JSON keeps each currently valid verification key:
+
+```json
+{
+  "keys": [
+    {
+      "kid": "101",
+      "publicKey": "-----BEGIN PUBLIC KEY-----..."
+    }
+  ]
+}
+```
+
+Rotation process:
+
+1. Add the new public key and `kid` to the public-key JSON.
+2. Switch the active private-key JSON to the matching new key and `kid`.
+3. Keep the previous public key until all tokens signed by it have expired.
+
+Never commit or publish private keys.
+
+### Custom key provider
+
+Use a key provider for KMS, Vault, or a secret manager:
+
+```js
+const auth = createAuthenticationLibrary({
+  jwt: {
+    keyProvider: {
+      async getActiveSigningKey() {
+        return {
+          keyId: "101",
+          privateKey: await secretManager.getActivePrivateKey()
+        };
+      },
+      async getPublicKey(keyId) {
+        return secretManager.getPublicKey(keyId);
+      }
+    }
+  }
+});
+```
+
+When `jwt.keyProvider` is supplied, the file paths are not used.
+
+## HTTP API
+
+Assume the router is mounted at `/auth`.
+
+| Method and route | Request body | Description |
+| --- | --- | --- |
+| `POST /auth/potential-users` | `email` | Generates or refreshes a registration code for an unregistered email. |
+| `POST /auth/register` | `email`, `password`, optional `verificationCode` | Creates a user. The code is required when verification is enabled. |
+| `POST /auth/token` | `email`, `password`, optional `twoFactorCode` | Issues an access token and refresh-token cookie. |
+| `POST /auth/refresh` | Optional `refresh_token` | Returns a new access token and refresh-token cookie; falls back to cookie. |
+| `POST /auth/2fa/code` | `email`, `password` | Generates or refreshes a 2FA code when 2FA is enabled. |
+| `PATCH /auth/password` | `newPassword`, optional `user_id` or `email` | Changes own password, or another user's if policy allows. |
+| `POST /auth/roles` | `roles`, exactly one of `user_id` or `email` | Adds roles. Requires administrator access token. |
+| `DELETE /auth/roles` | `role`, exactly one of `user_id` or `email` | Removes one role. Requires administrator access token. |
+| `PUT /auth/roles` | `roles`, exactly one of `user_id` or `email` | Replaces all roles. Requires administrator access token. |
+
+Access tokens include the application payload and access-token metadata.
+Refresh tokens contain only the subject and required token metadata, not the
+complete application payload.
+
+## Data stored in MongoDB
+
+The users collection contains documents like:
+
+```json
+{
+  "user_id": "2d6c2f40-0a3f-4b2e-9d8c-8f3b7f6e1a20",
+  "email": "alice@example.com",
+  "passwordHash": "<Argon2id hash>",
+  "nab_role": ["editor"],
+  "createdAt": "2026-01-01T00:00:00.000Z"
+}
+```
+
+The library creates unique indexes for `email` and `user_id`, and creates the
+pending-registration collection plus its TTL index.
+
+## Verifier-only service
+
+A business service that only verifies access tokens does not need MongoDB or a
+private key:
+
+```js
+const auth = createAuthenticationLibrary({
+  jwt: {
+    issuer: "my-service",
+    audience: "my-client",
+    keys: {
+      publicKeyPath: process.env.MY_JWT_PUBLIC_KEY_PATH
+    }
+  }
+});
+
+app.get("/api/business-data", auth.requireJwt, (req, res) => {
+  res.json({ userId: req.auth.sub });
+});
+
+app.use(auth.jwtErrorHandler);
+```
+
+## Production checklist
+
+- Use HTTPS and `refreshCookie.secure: true` in production.
+- Set `codeDelivery.allowCodeInResponseWithoutSender: false` in production.
+- Provide real email/SMS delivery callbacks for codes.
+- Keep private keys and MongoDB credentials outside source control.
+- Add application-level rate limits to login, registration, code-generation,
+  and password-change routes.
+- Configure CORS and cookie `sameSite` settings for your frontend topology.
+- Retain old public keys until tokens signed by them expire.
+
+## Support and contributing
+
+Source code, bug reports, and feature requests are managed in the
+[GitLab project](https://gitlab.com/platforms8851042/nab_authenticate).
+Please use [GitLab Issues](https://gitlab.com/platforms8851042/nab_authenticate/-/issues)
+for reproducible bugs and feature proposals.
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@nabhiraj/nab-auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Configurable Express, MongoDB, JWT, registration verification, and 2FA authentication library",
+  "type": "module",
+  "main": "./src/authenticationLogic/index.js",
+  "exports": {
+    ".": "./src/authenticationLogic/index.js"
+  },
+  "files": [
+    "src/authenticationLogic",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "authentication",
+    "express",
+    "jwt",
+    "mongodb",
+    "argon2",
+    "2fa"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "pack-check": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "argon2": "^0.45.1",
+    "cookie": "^2.0.1",
+    "express-jwt": "^8.5.1",
+    "jsonwebtoken": "^9.0.2",
+    "mongodb": "^7.7.0"
+  },
+  "peerDependencies": {
+    "express": "^5.0.0"
+  },
+  "devDependencies": {
+    "express": "^5.1.0"
+  }
+}

package/src/authenticationLogic/config/createAuthConfig.js

@@ -0,0 +1,94 @@
+import { defaultAuthConfig } from "./defaultAuthConfig.js";
+
+export function createAuthConfig(overrides = {}) {
+  const config = mergeConfig(defaultAuthConfig, overrides);
+
+  validateString(config.jwt.issuer, "jwt.issuer");
+  validateString(config.jwt.audience, "jwt.audience");
+  validateString(config.jwt.algorithm, "jwt.algorithm");
+  validatePositiveNumber(config.jwt.keyCacheTtlMs, "jwt.keyCacheTtlMs");
+  validateCodeConfig(
+    config.registration,
+    "registration",
+    "verificationRequired"
+  );
+  validateCodeConfig(config.twoFactor, "twoFactor", "required");
+  validateString(config.authorization.adminRole, "authorization.adminRole");
+
+  if (typeof config.codeDelivery.allowCodeInResponseWithoutSender !== "boolean") {
+    throw new TypeError(
+      "codeDelivery.allowCodeInResponseWithoutSender must be a boolean"
+    );
+  }
+
+  if (config.jwt.keyProvider !== undefined) {
+    if (
+      typeof config.jwt.keyProvider.getActiveSigningKey !== "function" ||
+      typeof config.jwt.keyProvider.getPublicKey !== "function"
+    ) {
+      throw new TypeError(
+        "jwt.keyProvider must provide getActiveSigningKey and getPublicKey functions"
+      );
+    }
+  }
+
+  return config;
+}
+
+function mergeConfig(defaults, overrides) {
+  const merged = mergeDefined(defaults, overrides);
+
+  for (const key of Object.keys(defaults)) {
+    if (isPlainObject(defaults[key])) {
+      merged[key] = mergeDefined(defaults[key], overrides[key]);
+    }
+  }
+
+  merged.jwt.keys = mergeDefined(defaults.jwt.keys, overrides.jwt?.keys);
+
+  return merged;
+}
+
+function mergeDefined(defaults, overrides) {
+  const merged = { ...defaults };
+
+  if (!isPlainObject(overrides)) {
+    return merged;
+  }
+
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value !== undefined) {
+      merged[key] = value;
+    }
+  }
+
+  return merged;
+}
+
+function validateCodeConfig(config, name, enabledField) {
+  if (typeof config[enabledField] !== "boolean") {
+    throw new TypeError(`${name}.${enabledField} must be a boolean`);
+  }
+
+  if (!Number.isInteger(config.codeDigits) || config.codeDigits < 1 || config.codeDigits > 9) {
+    throw new TypeError(`${name}.codeDigits must be an integer from 1 to 9`);
+  }
+
+  validatePositiveNumber(config.codeTtlMs, `${name}.codeTtlMs`);
+}
+
+function validateString(value, name) {
+  if (typeof value !== "string" || !value) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+}
+
+function validatePositiveNumber(value, name) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive number`);
+  }
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/authenticationLogic/config/defaultAuthConfig.js

@@ -0,0 +1,59 @@
+export const defaultAuthConfig = {
+  mongo: {
+    uri: undefined,
+    databaseName: "jwt_auth_demo",
+    usersCollectionName: "users",
+    potentialUsersCollectionName: "potential_user"
+  },
+  jwt: {
+    issuer: "jwt-express-demo",
+    audience: "jwt-express-demo-client",
+    algorithm: "RS256",
+    accessTokenTtl: "15m",
+    refreshTokenTtl: "7d",
+    keyCacheTtlMs: 15 * 60 * 1000,
+    keys: {
+      privateKeyPath: undefined,
+      publicKeyPath: undefined
+    },
+    keyProvider: undefined
+  },
+  authorization: {
+    adminRole: "nab_admin",
+    userRegistrationRequiresNabAdmin: false,
+    passwordChangeRequiresNabAdmin: false,
+    nabAdminCanChangeOtherUsersPasswords: true
+  },
+  registration: {
+    verificationRequired: false,
+    codeDigits: 6,
+    codeTtlMs: 10 * 60 * 1000
+  },
+  twoFactor: {
+    required: false,
+    codeDigits: 6,
+    codeTtlMs: 10 * 60 * 1000
+  },
+  passwordHash: {
+    memoryCost: 19456,
+    timeCost: 2,
+    parallelism: 1
+  },
+  refreshCookie: {
+    name: "refresh_token",
+    httpOnly: true,
+    secure: false,
+    sameSite: "lax",
+    path: "/auth/refresh",
+    maxAgeMs: 7 * 24 * 60 * 60 * 1000
+  },
+  codeDelivery: {
+    allowCodeInResponseWithoutSender: true
+  },
+  defaultAdmin: {
+    enabled: false,
+    email: "admin@admin.com",
+    password: "admin",
+    roles: ["nab_admin"]
+  }
+};