@c9up/warden 0.1.4 → 0.1.5

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");
+}

package/src/mfa/OtpProvider.ts

@@ -0,0 +1,177 @@
+/**
+ * OtpProvider — delivered one-time passcodes (email / SMS). Unlike TOTP this is
+ * a challenge/response flow: `start()` mints a code, persists it (hashed, with
+ * an expiry and an attempt budget) and hands it to a delivery channel; the user
+ * later submits it to `verify()`.
+ *
+ * Delivery is pluggable — the app supplies an email or SMS channel. The store
+ * is pluggable too, with an in-memory default mirroring the rest of warden.
+ */
+
+import {
+	createHash,
+	randomBytes,
+	randomInt,
+	timingSafeEqual,
+} from "node:crypto";
+import { WardenError } from "../errors.js";
+
+/** Sends the code to the user. Implemented by the consuming app (email/SMS). */
+export interface OtpDeliveryChannel {
+	send(recipient: string, code: string): Promise<void>;
+}
+
+/** A persisted, pending OTP challenge. */
+export interface OtpChallenge {
+	id: string;
+	recipient: string;
+	/** Salted hash of the code — never the plaintext. */
+	hash: string;
+	expiresAt: number;
+	attempts: number;
+}
+
+/** Storage for pending challenges. */
+export interface OtpChallengeStore {
+	save(challenge: OtpChallenge): Promise<void>;
+	find(id: string): Promise<OtpChallenge | null>;
+	delete(id: string): Promise<void>;
+}
+
+export class MemoryOtpChallengeStore implements OtpChallengeStore {
+	#store = new Map<string, OtpChallenge>();
+	async save(c: OtpChallenge): Promise<void> {
+		this.#store.set(c.id, c);
+	}
+	async find(id: string): Promise<OtpChallenge | null> {
+		return this.#store.get(id) ?? null;
+	}
+	async delete(id: string): Promise<void> {
+		this.#store.delete(id);
+	}
+}
+
+export interface OtpConfig {
+	channel: OtpDeliveryChannel;
+	/** Where pending challenges live. Default in-memory. */
+	store?: OtpChallengeStore;
+	/** Number of digits in the code. Default `6`. */
+	digits?: number;
+	/** How long a code stays valid, in seconds. Default `300` (5 min). */
+	ttlSeconds?: number;
+	/** Max verification attempts before the challenge is burned. Default `5`. */
+	maxAttempts?: number;
+}
+
+export interface OtpStartResult {
+	challengeId: string;
+	expiresAt: number;
+}
+
+export type OtpFailureReason =
+	| "not_found"
+	| "expired"
+	| "too_many_attempts"
+	| "mismatch";
+
+export interface OtpVerification {
+	ok: boolean;
+	reason?: OtpFailureReason;
+}
+
+export class OtpProvider {
+	readonly kind = "otp" as const;
+	readonly #channel: OtpDeliveryChannel;
+	readonly #store: OtpChallengeStore;
+	readonly #digits: number;
+	readonly #ttlMs: number;
+	readonly #maxAttempts: number;
+
+	constructor(config: OtpConfig) {
+		if (!config?.channel) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				"OtpProvider requires a delivery channel (email/SMS)",
+			);
+		}
+		this.#channel = config.channel;
+		this.#store = config.store ?? new MemoryOtpChallengeStore();
+		this.#digits = config.digits ?? 6;
+		this.#ttlMs = (config.ttlSeconds ?? 300) * 1000;
+		this.#maxAttempts = config.maxAttempts ?? 5;
+	}
+
+	/** Mint a code, persist the challenge, and deliver it to `recipient`. */
+	async start(
+		recipient: string,
+		nowMs: number = Date.now(),
+	): Promise<OtpStartResult> {
+		const code = this.#randomCode();
+		const id = randomBytes(16).toString("hex");
+		const expiresAt = nowMs + this.#ttlMs;
+		await this.#store.save({
+			id,
+			recipient,
+			hash: saltedHash(code),
+			expiresAt,
+			attempts: 0,
+		});
+		await this.#channel.send(recipient, code);
+		return { challengeId: id, expiresAt };
+	}
+
+	/**
+	 * Verify a submitted code. Wrong codes consume an attempt; the challenge is
+	 * deleted on success, on expiry, or once the attempt budget is exhausted.
+	 */
+	async verify(
+		challengeId: string,
+		code: string,
+		nowMs: number = Date.now(),
+	): Promise<OtpVerification> {
+		const challenge = await this.#store.find(challengeId);
+		if (!challenge) {
+			return { ok: false, reason: "not_found" };
+		}
+		if (nowMs > challenge.expiresAt) {
+			await this.#store.delete(challengeId);
+			return { ok: false, reason: "expired" };
+		}
+		if (matchesStored(challenge.hash, code.replace(/\s/g, ""))) {
+			await this.#store.delete(challengeId);
+			return { ok: true };
+		}
+		const attempts = challenge.attempts + 1;
+		if (attempts >= this.#maxAttempts) {
+			await this.#store.delete(challengeId);
+			return { ok: false, reason: "too_many_attempts" };
+		}
+		await this.#store.save({ ...challenge, attempts });
+		return { ok: false, reason: "mismatch" };
+	}
+
+	#randomCode(): string {
+		const max = 10 ** this.#digits;
+		return randomInt(0, max).toString().padStart(this.#digits, "0");
+	}
+}
+
+function saltedHash(code: string): string {
+	const salt = randomBytes(8);
+	const digest = createHash("sha256").update(salt).update(code).digest();
+	return `${salt.toString("hex")}$${digest.toString("hex")}`;
+}
+
+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 = createHash("sha256").update(salt).update(candidate).digest();
+	if (actual.length !== expected.length) {
+		return false;
+	}
+	return timingSafeEqual(actual, expected);
+}