@cairs-npm/express-auth-2fa 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @cairs-npm/express-auth-2fa
 
-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.
+Private Express + MongoDB module that adds password sign-in with 2-Step
+Verification (TOTP authenticator apps + SMS codes), verification-method
+management, session handling and a security audit log to any Express app.
+
+## Install & mount
+
+```ts
+import express from "express";
+import { MongoClient } from "mongodb";
+import { createAuthRouter, migrate, twilioSms } from "@cairs-npm/express-auth-2fa";
+
+const db = new MongoClient(process.env.MONGO_URI!).db("app");
+await migrate(db); // creates auth_* collections, validators, indexes, TTLs
+
+const app = express();
+app.use(express.json());
+app.use(
+  createAuthRouter({
+    db,
+    issuer: "YourApp",
+    jwtPrivateKey: process.env.JWT_PRIVATE_KEY!, // PKCS8 PEM, Ed25519 or RSA
+    encryptionKey: process.env.AUTH_ENC_KEY!,   // 32 bytes (raw or base64)
+    userAdapter: {
+      findByLogin: (login) => db.collection("users").findOne({ email: login }),
+      findById: (id) => db.collection("users").findOne({ _id: id }),
+    },
+    smsProvider: twilioSms({ sid, token, from }), // or consoleSms() in dev
+  }),
+);
+```
+
+One install, one line to mount. All endpoints live under `/auth/*` and
+`/account/security*`, implementing the shared `@cairs-npm/auth-2fa-contract`.
+
+## Config
+
+| Field | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `db` | yes | — | `mongodb` `Db`; the module owns `auth_*` collections only |
+| `issuer` | yes | — | JWT issuer + otpauth issuer |
+| `jwtPrivateKey` | yes | — | PKCS8 PEM; Ed25519 → EdDSA, RSA → RS256 |
+| `encryptionKey` | yes | — | 32-byte AES-256-GCM key (raw string or base64) |
+| `keyId` | no | `"v1"` | written on each encrypted field for rotation |
+| `userAdapter` | yes | — | `findByLogin`, `findById` |
+| `smsProvider` | yes | — | `{ send(phoneE164, message) }` |
+| `logger` | no | noop | pino-compatible; output is redacted (NFR-B1) |
+| `hooks.onSecurityEvent` | no | — | called for every audit event (BR-20) |
+| `clock` | no | `Date.now` | inject for tests |
+| `collectionPrefix` | no | `"auth_"` | |
+| `limits` | no | spec | lockout, SMS resend/caps, per-IP rate limits |
+| `argon2` | no | 64MB/3it/4p | Argon2id params |
+| `cookies` | no | secure/lax | refresh + trusted-device + CSRF cookies |
+| `ttl` | no | spec | access 15m, refresh/trusted 30d, challenge/stepUp 5m |
+| `exposeDocs` | no | false | serves `GET /auth/openapi.json` |
+
+## Data model
+
+Six+ collections (`auth_credentials`, `auth_mfa_methods`, `auth_challenges`,
+`auth_sessions`, `auth_trusted_devices`, `auth_events`, `auth_rate_limits`),
+created by `migrate(db)` with JSON-schema validators, indexes and TTLs.
+TOTP secrets and phone numbers are AES-256-GCM encrypted; SMS codes, refresh
+tokens and trusted-device tokens are stored as SHA-256 hashes only.
+
+## Security highlights
+
+- Argon2id passwords; equal `INVALID_CREDENTIALS` timing for unknown users.
+- Lockout after 5 failed passwords; challenge lockout after 5 wrong codes.
+- TOTP RFC 6238 (±1 step) with per-method replay guard.
+- Rotating refresh tokens; reuse of a rotated token revokes the whole family.
+- CSRF double-submit token on the cookie-authenticated refresh route.
+- Per-IP and per-user rate limits backed by MongoDB (stateless across instances).
+- One error shape: `{ error, message, attemptsLeft?, retryAt? }`.
+
+## Development
+
+```sh
+npm install
+npm test          # vitest + mongodb-memory-server (replica set)
+npm run build     # tsup → ESM + CJS + d.ts
+npm run typecheck && npm run lint
+```
+
+`examples/express-app` is a runnable dev server for E2E testing.

package/dist/chunk-PQPLAWOZ.js

@@ -0,0 +1,44 @@
+// src/crypto/hash.ts
+import crypto from "crypto";
+import argon2 from "argon2";
+function hashPassword(plain, params) {
+  return argon2.hash(plain, {
+    type: argon2.argon2id,
+    memoryCost: params.memoryKiB,
+    timeCost: params.iterations,
+    parallelism: params.parallelism
+  });
+}
+function verifyPassword(hash, plain) {
+  return argon2.verify(hash, plain).catch(() => false);
+}
+var DUMMY_HASH = "$argon2id$v=19$m=65536,t=3,p=4$AAAAAAAAAAAAAAAAAAAAAA$1AkBK4sQubUqG5fSG5+0E4yP+4DpVXq3sfJv4boqK3k";
+function sha256Hex(value) {
+  return crypto.createHash("sha256").update(value, "utf8").digest("hex");
+}
+function timingSafeEqualStr(a, b) {
+  const ha = crypto.createHash("sha256").update(a).digest();
+  const hb = crypto.createHash("sha256").update(b).digest();
+  return crypto.timingSafeEqual(ha, hb);
+}
+function randomToken() {
+  return crypto.randomBytes(32).toString("base64url");
+}
+function randomSmsCode() {
+  return crypto.randomInt(0, 1e6).toString().padStart(6, "0");
+}
+function randomId(prefix) {
+  return `${prefix}_${crypto.randomBytes(9).toString("base64url")}`;
+}
+
+export {
+  hashPassword,
+  verifyPassword,
+  DUMMY_HASH,
+  sha256Hex,
+  timingSafeEqualStr,
+  randomToken,
+  randomSmsCode,
+  randomId
+};
+//# sourceMappingURL=chunk-PQPLAWOZ.js.map

package/dist/chunk-PQPLAWOZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/crypto/hash.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport argon2 from \"argon2\";\n\nexport interface Argon2Params {\n  memoryKiB: number;\n  iterations: number;\n  parallelism: number;\n}\n\nexport function hashPassword(plain: string, params: Argon2Params): Promise<string> {\n  return argon2.hash(plain, {\n    type: argon2.argon2id,\n    memoryCost: params.memoryKiB,\n    timeCost: params.iterations,\n    parallelism: params.parallelism,\n  });\n}\n\nexport function verifyPassword(hash: string, plain: string): Promise<boolean> {\n  return argon2.verify(hash, plain).catch(() => false);\n}\n\n// Dummy hash used to equalize timing for unknown users (BR-1). Argon2id format.\nexport const DUMMY_HASH =\n  \"$argon2id$v=19$m=65536,t=3,p=4$AAAAAAAAAAAAAAAAAAAAAA$1AkBK4sQubUqG5fSG5+0E4yP+4DpVXq3sfJv4boqK3k\";\n\nexport function sha256Hex(value: string): string {\n  return crypto.createHash(\"sha256\").update(value, \"utf8\").digest(\"hex\");\n}\n\n/** Constant-time string comparison via SHA-256 (BR-8). */\nexport function timingSafeEqualStr(a: string, b: string): boolean {\n  const ha = crypto.createHash(\"sha256\").update(a).digest();\n  const hb = crypto.createHash(\"sha256\").update(b).digest();\n  return crypto.timingSafeEqual(ha, hb);\n}\n\nexport function randomToken(): string {\n  return crypto.randomBytes(32).toString(\"base64url\");\n}\n\nexport function randomSmsCode(): string {\n  return crypto.randomInt(0, 1_000_000).toString().padStart(6, \"0\");\n}\n\nexport function randomId(prefix: string): string {\n  return `${prefix}_${crypto.randomBytes(9).toString(\"base64url\")}`;\n}\n"],"mappings":";AAAA,OAAO,YAAY;AACnB,OAAO,YAAY;AAQZ,SAAS,aAAa,OAAe,QAAuC;AACjF,SAAO,OAAO,KAAK,OAAO;AAAA,IACxB,MAAM,OAAO;AAAA,IACb,YAAY,OAAO;AAAA,IACnB,UAAU,OAAO;AAAA,IACjB,aAAa,OAAO;AAAA,EACtB,CAAC;AACH;AAEO,SAAS,eAAe,MAAc,OAAiC;AAC5E,SAAO,OAAO,OAAO,MAAM,KAAK,EAAE,MAAM,MAAM,KAAK;AACrD;AAGO,IAAM,aACX;AAEK,SAAS,UAAU,OAAuB;AAC/C,SAAO,OAAO,WAAW,QAAQ,EAAE,OAAO,OAAO,MAAM,EAAE,OAAO,KAAK;AACvE;AAGO,SAAS,mBAAmB,GAAW,GAAoB;AAChE,QAAM,KAAK,OAAO,WAAW,QAAQ,EAAE,OAAO,CAAC,EAAE,OAAO;AACxD,QAAM,KAAK,OAAO,WAAW,QAAQ,EAAE,OAAO,CAAC,EAAE,OAAO;AACxD,SAAO,OAAO,gBAAgB,IAAI,EAAE;AACtC;AAEO,SAAS,cAAsB;AACpC,SAAO,OAAO,YAAY,EAAE,EAAE,SAAS,WAAW;AACpD;AAEO,SAAS,gBAAwB;AACtC,SAAO,OAAO,UAAU,GAAG,GAAS,EAAE,SAAS,EAAE,SAAS,GAAG,GAAG;AAClE;AAEO,SAAS,SAAS,QAAwB;AAC/C,SAAO,GAAG,MAAM,IAAI,OAAO,YAAY,CAAC,EAAE,SAAS,WAAW,CAAC;AACjE;","names":[]}

package/dist/contract/index.cjs

@@ -0,0 +1,25 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/contract/index.ts
+var contract_exports = {};
+module.exports = __toCommonJS(contract_exports);
+__reExport(contract_exports, require("@cairs-npm/auth-2fa-contract"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("@cairs-npm/auth-2fa-contract")
+});
+//# sourceMappingURL=index.cjs.map

package/dist/contract/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/contract/index.ts"],"sourcesContent":["// Re-export the shared contract so backend consumers get it transitively.\nexport * from \"@cairs-npm/auth-2fa-contract\";\n"],"mappings":";;;;;;;;;;;;;;;;;AAAA;AAAA;AACA,6BAAc,yCADd;","names":[]}

package/dist/contract/index.d.cts

@@ -0,0 +1 @@
+export * from '@cairs-npm/auth-2fa-contract';

package/dist/contract/index.d.ts

@@ -0,0 +1 @@
+export * from '@cairs-npm/auth-2fa-contract';

package/dist/contract/index.js

@@ -0,0 +1,3 @@
+// src/contract/index.ts
+export * from "@cairs-npm/auth-2fa-contract";
+//# sourceMappingURL=index.js.map

package/dist/contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/contract/index.ts"],"sourcesContent":["// Re-export the shared contract so backend consumers get it transitively.\nexport * from \"@cairs-npm/auth-2fa-contract\";\n"],"mappings":";AACA,cAAc;","names":[]}

package/dist/hash-GKCJDZLH.js

@@ -0,0 +1,21 @@
+import {
+  DUMMY_HASH,
+  hashPassword,
+  randomId,
+  randomSmsCode,
+  randomToken,
+  sha256Hex,
+  timingSafeEqualStr,
+  verifyPassword
+} from "./chunk-PQPLAWOZ.js";
+export {
+  DUMMY_HASH,
+  hashPassword,
+  randomId,
+  randomSmsCode,
+  randomToken,
+  sha256Hex,
+  timingSafeEqualStr,
+  verifyPassword
+};
+//# sourceMappingURL=hash-GKCJDZLH.js.map

package/dist/hash-GKCJDZLH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}