@c9up/warden 0.1.4 → 0.1.6

package/src/config.ts

@@ -16,7 +16,23 @@
  */
 
 import type { UserPayload } from "./AuthManager.js";
-import type { RightsStore } from "./rights/types.js";
+import type { BasePolicy } from "./bouncer/BasePolicy.js";
+import type { Ability } from "./bouncer/types.js";
+import type { MfaManager } from "./mfa/MfaManager.js";
+import type { RightsStore, Scope } from "./rights/types.js";
+import type { ApiKeyConfig } from "./strategies/ApiKeyStrategy.js";
+import type { SessionStrategyConfig } from "./strategies/SessionStrategy.js";
+import type { TokenBlacklist } from "./TokenBlacklist.js";
+
+/**
+ * Minimal request shape passed to `resolveScope` — enough to derive a tenant
+ * from a header or the authenticated user, without coupling config to the full
+ * HTTP context type (keeps Warden agnostic of the host framework).
+ */
+export interface ScopeRequestContext {
+	request: { headers: Record<string, string> };
+	auth?: { user?: UserPayload | null };
+}
 
 export interface JwtConfig {
 	secret: string;
@@ -26,6 +42,12 @@ export interface JwtConfig {
 		email: string,
 		password: string,
 	) => Promise<UserPayload | null>;
+	/**
+	 * Optional revocation list. Supply a `TokenBlacklist` (Memory/Redis-backed) to
+	 * enable `revoke()`/early-rejection of JWTs before expiry. Without it, `revoke()`
+	 * throws (the call would be a silent no-op).
+	 */
+	blacklist?: TokenBlacklist;
 }
 
 export interface WardenConfig {
@@ -33,6 +55,18 @@ export interface WardenConfig {
 	defaultStrategy?: string;
 	/** JWT strategy configuration. */
 	jwt?: JwtConfig;
+	/**
+	 * Session strategy configuration. Supply `findUser` so `@Guard('session')`
+	 * routes resolve the authenticated user from the session id. Without this,
+	 * the `session` strategy is unregistered and `@Guard('session')` throws.
+	 */
+	session?: SessionStrategyConfig;
+	/**
+	 * API-key strategy configuration. Supply `findByKey` so `@Guard('api-key')`
+	 * routes resolve the user (and scopes) from the request header. Without this,
+	 * the `api-key` strategy is unregistered and `@Guard('api-key')` throws.
+	 */
+	apiKey?: ApiKeyConfig;
 	/**
 	 * Rights layer configuration (Epic 56). Supply a custom `store` to back the
 	 * unified resolver with a DB-backed driver; when omitted, an in-memory
@@ -40,6 +74,31 @@ export interface WardenConfig {
 	 * in-memory shipped).
 	 */
 	rights?: { store?: RightsStore };
+	/**
+	 * Standalone abilities the per-request Bouncer knows by name (Epic 56.6).
+	 * Keyed by the string passed to `ctx.bouncer.authorize('post.edit', …)`.
+	 * Define with `Bouncer.ability((user, post) => …)`.
+	 */
+	abilities?: Record<string, Ability<never[]>>;
+	/**
+	 * Class-based policies the per-request Bouncer knows by name (Epic 56.6).
+	 * Reachable via `ctx.bouncer.with('PostPolicy')`. Each entry is the policy
+	 * constructor; a fresh instance is created per check.
+	 */
+	policies?: Record<string, new () => BasePolicy>;
+	/**
+	 * Derive the authorization scope for a request (AD4 — scope-first). Return
+	 * `{ tenant }` to scope rights to a tenant (e.g. from a subdomain or header),
+	 * or `"global"`. Omitted ⇒ every request runs in the implicit `global` scope
+	 * (zero config for single-tenant apps).
+	 */
+	resolveScope?: (ctx: ScopeRequestContext) => Scope | Promise<Scope>;
+	/**
+	 * Multi-factor authentication. Supply a configured `MfaManager` (built with
+	 * your persistent stores + providers) to register it in the container as
+	 * `MfaManager` / `"mfa"`. Required to use `@RequireMfa` step-up flows.
+	 */
+	mfa?: { manager: MfaManager };
 }
 
 /** Typed config helper — identity function for editor inference. */

package/src/index.ts

@@ -44,10 +44,63 @@ export {
 	Guard,
 	getGuardMetadata,
 	getPermissionMetadata,
+	getRequireMfaMetadata,
 	getRoleMetadata,
 	Permission,
+	RequireMfa,
 	Role,
 } from "./Guard.js";
+export type {
+	BackupCodesConfig,
+	BackupCodesResult,
+	BackupCodeVerification,
+} from "./mfa/BackupCodesProvider.js";
+export { BackupCodesProvider } from "./mfa/BackupCodesProvider.js";
+export type {
+	MfaFactor,
+	MfaFactorKind,
+	MfaFactorStore,
+	MfaFactorSummary,
+	MfaManagerConfig,
+} from "./mfa/MfaManager.js";
+export { MemoryMfaFactorStore, MfaManager } from "./mfa/MfaManager.js";
+export type {
+	OtpChallenge,
+	OtpChallengeStore,
+	OtpConfig,
+	OtpDeliveryChannel,
+	OtpFailureReason,
+	OtpStartResult,
+	OtpVerification,
+} from "./mfa/OtpProvider.js";
+export { MemoryOtpChallengeStore, OtpProvider } from "./mfa/OtpProvider.js";
+export type {
+	TotpAlgorithm,
+	TotpConfig,
+	TotpEnrollment,
+} from "./mfa/TotpProvider.js";
+export { TotpProvider } from "./mfa/TotpProvider.js";
+export type {
+	AuthenticationOptionsJSON,
+	AuthenticationResponseJSON,
+	RegistrationOptionsJSON,
+	RegistrationResponseJSON,
+	StoredPasskey,
+	WebauthnChallengeStore,
+	WebauthnConfig,
+	WebauthnCredentialStore,
+	WebauthnUser,
+} from "./mfa/WebauthnProvider.js";
+export {
+	MemoryWebauthnChallengeStore,
+	MemoryWebauthnCredentialStore,
+	WebauthnProvider,
+} from "./mfa/WebauthnProvider.js";
+export type {
+	RedisBlacklistConfig,
+	RedisLikeClient,
+} from "./RedisBlacklistDriver.js";
+export { RedisBlacklistDriver } from "./RedisBlacklistDriver.js";
 export type {
 	RefreshTokenDriver,
 	StoredRefreshToken,
@@ -56,6 +109,11 @@ export {
 	generateRefreshToken,
 	MemoryRefreshTokenDriver,
 } from "./RefreshTokenStore.js";
+export type {
+	BlacklistDegradeEvent,
+	ResilientBlacklistConfig,
+} from "./ResilientBlacklistDriver.js";
+export { ResilientBlacklistDriver } from "./ResilientBlacklistDriver.js";
 export { MemoryRightsStore } from "./rights/MemoryRightsStore.js";
 export { RightsResolver } from "./rights/RightsResolver.js";
 export type {

package/src/mfa/BackupCodesProvider.ts

@@ -0,0 +1,125 @@
+/**
+ * BackupCodesProvider — single-use recovery codes for when a user loses their
+ * authenticator. Codes are shown to the user exactly once at generation time;
+ * only salted hashes are persisted. Verifying a code consumes it.
+ *
+ * Codes are high-entropy random tokens (default ~50 bits), so a single salted
+ * SHA-256 is the right primitive here — not an expensive password KDF.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { WardenError } from "../errors.js";
+import { base32Encode } from "./base32.js";
+
+export interface BackupCodesConfig {
+	/** How many codes to generate. Default `10`. */
+	count?: number;
+	/** Characters per code (base32, excludes the separator). Default `10`. */
+	length?: number;
+}
+
+export interface BackupCodesResult {
+	/** Plaintext codes — display ONCE, never persist. */
+	codes: string[];
+	/** Salted hashes (`salt$digest`) to persist against the user. */
+	hashes: string[];
+}
+
+export interface BackupCodeVerification {
+	ok: boolean;
+	/** The hash list with the consumed code removed (persist this on success). */
+	remaining: string[];
+}
+
+const DEFAULTS = { count: 10, length: 10 };
+
+export class BackupCodesProvider {
+	readonly kind = "backup_codes" as const;
+	readonly #cfg: Required<BackupCodesConfig>;
+
+	constructor(config: BackupCodesConfig = {}) {
+		this.#cfg = { ...DEFAULTS, ...config };
+		if (this.#cfg.count < 1) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				`backup code count must be >= 1, got ${this.#cfg.count}`,
+			);
+		}
+		if (this.#cfg.length < 8) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				`backup code length must be >= 8 for adequate entropy, got ${this.#cfg.length}`,
+			);
+		}
+	}
+
+	/** Generate a fresh batch of codes plus the hashes to persist. */
+	generate(): BackupCodesResult {
+		const codes: string[] = [];
+		const hashes: string[] = [];
+		for (let i = 0; i < this.#cfg.count; i++) {
+			const raw = base32Encode(randomBytes(this.#cfg.length)).slice(
+				0,
+				this.#cfg.length,
+			);
+			// Split in the middle for readability: "ABCDE-FGHIJ".
+			const half = Math.floor(this.#cfg.length / 2);
+			codes.push(`${raw.slice(0, half)}-${raw.slice(half)}`);
+			hashes.push(saltedHash(raw));
+		}
+		return { codes, hashes };
+	}
+
+	/**
+	 * Verify a user-supplied code against the stored hashes. On a match the
+	 * code is consumed: `remaining` excludes it and must be persisted. Input is
+	 * normalized (separators stripped, upper-cased) before comparison.
+	 */
+	verify(hashes: string[], code: string): BackupCodeVerification {
+		const candidate = normalize(code);
+		let matchedIndex = -1;
+		// Scan every entry (no early exit) so timing doesn't leak position.
+		for (let i = 0; i < hashes.length; i++) {
+			if (matchesStored(hashes[i], candidate)) {
+				matchedIndex = i;
+			}
+		}
+		if (matchedIndex === -1) {
+			return { ok: false, remaining: hashes };
+		}
+		return {
+			ok: true,
+			remaining: hashes.filter((_, i) => i !== matchedIndex),
+		};
+	}
+}
+
+function normalize(code: string): string {
+	return code.replace(/[\s-]/g, "").toUpperCase();
+}
+
+/** Hash a normalized code under a fresh random salt → `salt$digest` (hex). */
+function saltedHash(normalized: string): string {
+	const salt = randomBytes(8);
+	const digest = digestWith(salt, normalized);
+	return `${salt.toString("hex")}$${digest.toString("hex")}`;
+}
+
+/** Re-hash the candidate under the stored entry's salt and compare. */
+function matchesStored(stored: string, candidate: string): boolean {
+	const sep = stored.indexOf("$");
+	if (sep === -1) {
+		return false;
+	}
+	const salt = Buffer.from(stored.slice(0, sep), "hex");
+	const expected = Buffer.from(stored.slice(sep + 1), "hex");
+	const actual = digestWith(salt, candidate);
+	if (actual.length !== expected.length) {
+		return false;
+	}
+	return timingSafeEqual(actual, expected);
+}
+
+function digestWith(salt: Buffer, normalized: string): Buffer {
+	return createHash("sha256").update(salt).update(normalized).digest();
+}

package/src/mfa/MfaManager.ts

@@ -0,0 +1,307 @@
+/**
+ * MfaManager — orchestrates the stateful "enable 2FA" lifecycle for a user:
+ * TOTP enrollment (pending → confirmed) and single-use backup codes, over a
+ * pluggable factor store (in-memory default).
+ *
+ * OTP (email/SMS) and WebAuthn are NOT folded in here: OTP is ephemeral
+ * (challenge/response, no enrollment) and WebAuthn already persists its own
+ * passkeys in its credential store. Use `OtpProvider` / `WebauthnProvider`
+ * directly for those, alongside this manager.
+ */
+
+import { randomBytes } from "node:crypto";
+import { WardenError } from "../errors.js";
+import type { BackupCodesProvider } from "./BackupCodesProvider.js";
+import type { TotpProvider } from "./TotpProvider.js";
+
+export type MfaFactorKind = "totp" | "backup_codes";
+
+export interface MfaFactor {
+	id: string;
+	userId: string;
+	kind: MfaFactorKind;
+	label?: string;
+	/** TOTP shared secret (base32), present for `totp` factors. */
+	secret?: string;
+	/** Salted hashes of the remaining backup codes, for `backup_codes` factors. */
+	backupHashes?: string[];
+	/** Epoch ms when the factor became usable; absent while pending. */
+	confirmedAt?: number;
+	createdAt: number;
+}
+
+/** Public, secret-free view of an enrolled factor. */
+export interface MfaFactorSummary {
+	id: string;
+	kind: MfaFactorKind;
+	label?: string;
+	confirmed: boolean;
+}
+
+export interface MfaFactorStore {
+	save(factor: MfaFactor): Promise<void>;
+	findById(id: string): Promise<MfaFactor | null>;
+	findByUser(userId: string): Promise<MfaFactor[]>;
+	delete(id: string): Promise<void>;
+}
+
+export class MemoryMfaFactorStore implements MfaFactorStore {
+	#store = new Map<string, MfaFactor>();
+	async save(factor: MfaFactor): Promise<void> {
+		this.#store.set(factor.id, factor);
+	}
+	async findById(id: string): Promise<MfaFactor | null> {
+		return this.#store.get(id) ?? null;
+	}
+	async findByUser(userId: string): Promise<MfaFactor[]> {
+		return [...this.#store.values()].filter((f) => f.userId === userId);
+	}
+	async delete(id: string): Promise<void> {
+		this.#store.delete(id);
+	}
+}
+
+export interface MfaRateLimitConfig {
+	/** Failed verifications allowed per user before lockout. Default `5`. */
+	maxAttempts?: number;
+	/** Lockout / counter window in seconds. Default `900` (15 min). */
+	windowSeconds?: number;
+}
+
+export interface MfaManagerConfig {
+	/** App/brand name shown in the authenticator (the TOTP issuer). */
+	issuer: string;
+	totp?: TotpProvider;
+	backupCodes?: BackupCodesProvider;
+	store?: MfaFactorStore;
+	/** Per-user brute-force protection on `verify()`. Defaults to 5 / 15 min. */
+	rateLimit?: MfaRateLimitConfig;
+}
+
+interface AttemptEntry {
+	count: number;
+	resetAt: number;
+}
+
+export class MfaManager {
+	readonly #issuer: string;
+	readonly #totp?: TotpProvider;
+	readonly #backupCodes?: BackupCodesProvider;
+	readonly #store: MfaFactorStore;
+	readonly #maxAttempts: number;
+	readonly #windowMs: number;
+	readonly #attempts = new Map<string, AttemptEntry>();
+
+	constructor(config: MfaManagerConfig) {
+		if (!config?.issuer) {
+			throw new WardenError("INVALID_CONFIG", "MfaManager requires an issuer");
+		}
+		this.#issuer = config.issuer;
+		this.#totp = config.totp;
+		this.#backupCodes = config.backupCodes;
+		this.#store = config.store ?? new MemoryMfaFactorStore();
+		this.#maxAttempts = config.rateLimit?.maxAttempts ?? 5;
+		this.#windowMs = (config.rateLimit?.windowSeconds ?? 900) * 1000;
+	}
+
+	// ── TOTP enrollment ──────────────────────────────────────────────
+
+	/**
+	 * Begin TOTP enrollment: persist a pending factor and return the secret +
+	 * `otpauth://` URI to show as a QR code. The factor is unusable until
+	 * `confirmTotp()` succeeds.
+	 */
+	async enrollTotp(
+		user: { id: string; name: string },
+		label?: string,
+	): Promise<{ factorId: string; secret: string; uri: string }> {
+		const totp = this.#requireTotp();
+		const { secret, uri } = totp.enroll(user.name, this.#issuer);
+		const factor: MfaFactor = {
+			id: newId(),
+			userId: user.id,
+			kind: "totp",
+			label,
+			secret,
+			createdAt: Date.now(),
+		};
+		await this.#store.save(factor);
+		return { factorId: factor.id, secret, uri };
+	}
+
+	/** Confirm a pending TOTP factor by verifying a first code. */
+	async confirmTotp(factorId: string, code: string): Promise<boolean> {
+		const totp = this.#requireTotp();
+		const factor = await this.#store.findById(factorId);
+		if (!factor || factor.kind !== "totp" || !factor.secret) {
+			return false;
+		}
+		if (!totp.verify(factor.secret, code)) {
+			return false;
+		}
+		await this.#store.save({ ...factor, confirmedAt: Date.now() });
+		return true;
+	}
+
+	/** Verify a TOTP code against the user's confirmed authenticator factors. */
+	async verifyTotp(userId: string, code: string): Promise<boolean> {
+		const totp = this.#requireTotp();
+		const factors = await this.#store.findByUser(userId);
+		return factors.some(
+			(f) =>
+				f.kind === "totp" &&
+				f.confirmedAt !== undefined &&
+				f.secret !== undefined &&
+				totp.verify(f.secret, code),
+		);
+	}
+
+	// ── Backup codes ─────────────────────────────────────────────────
+
+	/**
+	 * Generate (or regenerate) the user's backup codes. Returns the plaintext
+	 * codes to display ONCE; only hashes are stored. Any prior backup-code
+	 * factor is replaced.
+	 */
+	async createBackupCodes(userId: string, label?: string): Promise<string[]> {
+		const provider = this.#requireBackupCodes();
+		const existing = await this.#store.findByUser(userId);
+		for (const f of existing) {
+			if (f.kind === "backup_codes") {
+				await this.#store.delete(f.id);
+			}
+		}
+		const { codes, hashes } = provider.generate();
+		await this.#store.save({
+			id: newId(),
+			userId,
+			kind: "backup_codes",
+			label,
+			backupHashes: hashes,
+			// Backup codes are usable as soon as they are shown.
+			confirmedAt: Date.now(),
+			createdAt: Date.now(),
+		});
+		return codes;
+	}
+
+	/** Verify and consume one backup code for the user. */
+	async verifyBackupCode(userId: string, code: string): Promise<boolean> {
+		const provider = this.#requireBackupCodes();
+		const factors = await this.#store.findByUser(userId);
+		for (const factor of factors) {
+			if (factor.kind !== "backup_codes" || !factor.backupHashes) {
+				continue;
+			}
+			const result = provider.verify(factor.backupHashes, code);
+			if (result.ok) {
+				await this.#store.save({ ...factor, backupHashes: result.remaining });
+				return true;
+			}
+		}
+		return false;
+	}
+
+	// ── Unified verify + status ──────────────────────────────────────
+
+	/**
+	 * Verify a code entered in a single "2FA code" field: tries the user's TOTP
+	 * factors first, then falls back to consuming a backup code.
+	 */
+	async verify(userId: string, code: string): Promise<boolean> {
+		if (this.#isLocked(userId)) {
+			return false;
+		}
+		let ok = false;
+		if (this.#totp && (await this.verifyTotp(userId, code))) {
+			ok = true;
+		} else if (
+			this.#backupCodes &&
+			(await this.verifyBackupCode(userId, code))
+		) {
+			ok = true;
+		}
+		if (ok) {
+			this.#attempts.delete(userId);
+		} else {
+			this.#recordFailure(userId);
+		}
+		return ok;
+	}
+
+	/**
+	 * Whether the user is currently locked out of `verify()` after too many
+	 * failed attempts. Use it to surface a "try again later" message.
+	 */
+	isLocked(userId: string): boolean {
+		return this.#isLocked(userId);
+	}
+
+	/** List the user's factors without exposing any secret material. */
+	async listFactors(userId: string): Promise<MfaFactorSummary[]> {
+		const factors = await this.#store.findByUser(userId);
+		return factors.map((f) => ({
+			id: f.id,
+			kind: f.kind,
+			label: f.label,
+			confirmed: f.confirmedAt !== undefined,
+		}));
+	}
+
+	/** Whether the user has at least one confirmed factor. */
+	async isEnabled(userId: string): Promise<boolean> {
+		const factors = await this.#store.findByUser(userId);
+		return factors.some((f) => f.confirmedAt !== undefined);
+	}
+
+	/** Remove a factor (e.g. the user disables their authenticator). */
+	async disableFactor(factorId: string): Promise<void> {
+		await this.#store.delete(factorId);
+	}
+
+	#isLocked(userId: string): boolean {
+		const entry = this.#attempts.get(userId);
+		if (!entry) {
+			return false;
+		}
+		if (entry.resetAt < Date.now()) {
+			this.#attempts.delete(userId);
+			return false;
+		}
+		return entry.count >= this.#maxAttempts;
+	}
+
+	#recordFailure(userId: string): void {
+		const now = Date.now();
+		let entry = this.#attempts.get(userId);
+		if (!entry || entry.resetAt < now) {
+			entry = { count: 0, resetAt: now + this.#windowMs };
+			this.#attempts.set(userId, entry);
+		}
+		entry.count++;
+	}
+
+	#requireTotp(): TotpProvider {
+		if (!this.#totp) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				"MfaManager has no TotpProvider configured",
+			);
+		}
+		return this.#totp;
+	}
+
+	#requireBackupCodes(): BackupCodesProvider {
+		if (!this.#backupCodes) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				"MfaManager has no BackupCodesProvider configured",
+			);
+		}
+		return this.#backupCodes;
+	}
+}
+
+function newId(): string {
+	return randomBytes(16).toString("hex");
+}