@c9up/warden 0.1.4 → 0.1.6

package/dist/index.js

@@ -15,8 +15,15 @@ export { WardenError } from "./errors.js";
 export { GitHubDriver } from "./firstcontact/drivers/GitHubDriver.js";
 export { GoogleDriver } from "./firstcontact/drivers/GoogleDriver.js";
 export { FirstContactManager } from "./firstcontact/FirstContactManager.js";
-export { Guard, getGuardMetadata, getPermissionMetadata, getRoleMetadata, Permission, Role, } from "./Guard.js";
+export { Guard, getGuardMetadata, getPermissionMetadata, getRequireMfaMetadata, getRoleMetadata, Permission, RequireMfa, Role, } from "./Guard.js";
+export { BackupCodesProvider } from "./mfa/BackupCodesProvider.js";
+export { MemoryMfaFactorStore, MfaManager } from "./mfa/MfaManager.js";
+export { MemoryOtpChallengeStore, OtpProvider } from "./mfa/OtpProvider.js";
+export { TotpProvider } from "./mfa/TotpProvider.js";
+export { MemoryWebauthnChallengeStore, MemoryWebauthnCredentialStore, WebauthnProvider, } from "./mfa/WebauthnProvider.js";
+export { RedisBlacklistDriver } from "./RedisBlacklistDriver.js";
 export { generateRefreshToken, MemoryRefreshTokenDriver, } from "./RefreshTokenStore.js";
+export { ResilientBlacklistDriver } from "./ResilientBlacklistDriver.js";
 export { MemoryRightsStore } from "./rights/MemoryRightsStore.js";
 export { RightsResolver } from "./rights/RightsResolver.js";
 export { scopeKey } from "./rights/types.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EACN,MAAM,EACN,UAAU,EACV,iBAAiB,GACjB,MAAM,yBAAyB,CAAC;AAQjC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAO5E,OAAO,EACN,KAAK,EACL,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,IAAI,GACJ,MAAM,YAAY,CAAC;AAKpB,OAAO,EACN,oBAAoB,EACpB,wBAAwB,GACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAM5D,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAK7E,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EACN,MAAM,EACN,UAAU,EACV,iBAAiB,GACjB,MAAM,yBAAyB,CAAC;AAQjC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAO5E,OAAO,EACN,KAAK,EACL,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,UAAU,EACV,IAAI,GACJ,MAAM,YAAY,CAAC;AAMpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAQnE,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAUvE,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAM5E,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAYrD,OAAO,EACN,4BAA4B,EAC5B,6BAA6B,EAC7B,gBAAgB,GAChB,MAAM,2BAA2B,CAAC;AAKnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAKjE,OAAO,EACN,oBAAoB,EACpB,wBAAwB,GACxB,MAAM,wBAAwB,CAAC;AAKhC,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAM5D,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAK7E,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/mfa/BackupCodesProvider.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+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[];
+}
+export declare class BackupCodesProvider {
+    #private;
+    readonly kind: "backup_codes";
+    constructor(config?: BackupCodesConfig);
+    /** Generate a fresh batch of codes plus the hashes to persist. */
+    generate(): BackupCodesResult;
+    /**
+     * 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;
+}
+//# sourceMappingURL=BackupCodesProvider.d.ts.map

package/dist/mfa/BackupCodesProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackupCodesProvider.d.ts","sourceRoot":"","sources":["../../src/mfa/BackupCodesProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,iBAAiB;IACjC,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IACjC,qDAAqD;IACrD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,iEAAiE;IACjE,MAAM,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,8EAA8E;IAC9E,SAAS,EAAE,MAAM,EAAE,CAAC;CACpB;AAID,qBAAa,mBAAmB;;IAC/B,QAAQ,CAAC,IAAI,EAAG,cAAc,CAAU;gBAG5B,MAAM,GAAE,iBAAsB;IAgB1C,kEAAkE;IAClE,QAAQ,IAAI,iBAAiB;IAgB7B;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,sBAAsB;CAiB9D"}

package/dist/mfa/BackupCodesProvider.js

@@ -0,0 +1,87 @@
+/**
+ * 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";
+const DEFAULTS = { count: 10, length: 10 };
+export class BackupCodesProvider {
+    kind = "backup_codes";
+    #cfg;
+    constructor(config = {}) {
+        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() {
+        const codes = [];
+        const hashes = [];
+        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, code) {
+        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) {
+    return code.replace(/[\s-]/g, "").toUpperCase();
+}
+/** Hash a normalized code under a fresh random salt → `salt$digest` (hex). */
+function saltedHash(normalized) {
+    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, candidate) {
+    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, normalized) {
+    return createHash("sha256").update(salt).update(normalized).digest();
+}
+//# sourceMappingURL=BackupCodesProvider.js.map

package/dist/mfa/BackupCodesProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackupCodesProvider.js","sourceRoot":"","sources":["../../src/mfa/BackupCodesProvider.ts"],"names":[],"mappings":"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"}

package/dist/mfa/MfaManager.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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 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 declare class MemoryMfaFactorStore implements MfaFactorStore {
+    #private;
+    save(factor: MfaFactor): Promise<void>;
+    findById(id: string): Promise<MfaFactor | null>;
+    findByUser(userId: string): Promise<MfaFactor[]>;
+    delete(id: string): Promise<void>;
+}
+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;
+}
+export declare class MfaManager {
+    #private;
+    constructor(config: MfaManagerConfig);
+    /**
+     * 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.
+     */
+    enrollTotp(user: {
+        id: string;
+        name: string;
+    }, label?: string): Promise<{
+        factorId: string;
+        secret: string;
+        uri: string;
+    }>;
+    /** Confirm a pending TOTP factor by verifying a first code. */
+    confirmTotp(factorId: string, code: string): Promise<boolean>;
+    /** Verify a TOTP code against the user's confirmed authenticator factors. */
+    verifyTotp(userId: string, code: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    createBackupCodes(userId: string, label?: string): Promise<string[]>;
+    /** Verify and consume one backup code for the user. */
+    verifyBackupCode(userId: string, code: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    verify(userId: string, code: string): Promise<boolean>;
+    /**
+     * 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;
+    /** List the user's factors without exposing any secret material. */
+    listFactors(userId: string): Promise<MfaFactorSummary[]>;
+    /** Whether the user has at least one confirmed factor. */
+    isEnabled(userId: string): Promise<boolean>;
+    /** Remove a factor (e.g. the user disables their authenticator). */
+    disableFactor(factorId: string): Promise<void>;
+}
+//# sourceMappingURL=MfaManager.d.ts.map

package/dist/mfa/MfaManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MfaManager.d.ts","sourceRoot":"","sources":["../../src/mfa/MfaManager.ts"],"names":[],"mappings":"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"}

package/dist/mfa/MfaManager.js

@@ -0,0 +1,219 @@
+/**
+ * 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";
+export class MemoryMfaFactorStore {
+    #store = new Map();
+    async save(factor) {
+        this.#store.set(factor.id, factor);
+    }
+    async findById(id) {
+        return this.#store.get(id) ?? null;
+    }
+    async findByUser(userId) {
+        return [...this.#store.values()].filter((f) => f.userId === userId);
+    }
+    async delete(id) {
+        this.#store.delete(id);
+    }
+}
+export class MfaManager {
+    #issuer;
+    #totp;
+    #backupCodes;
+    #store;
+    #maxAttempts;
+    #windowMs;
+    #attempts = new Map();
+    constructor(config) {
+        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, label) {
+        const totp = this.#requireTotp();
+        const { secret, uri } = totp.enroll(user.name, this.#issuer);
+        const factor = {
+            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, code) {
+        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, code) {
+        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, label) {
+        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, code) {
+        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, code) {
+        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) {
+        return this.#isLocked(userId);
+    }
+    /** List the user's factors without exposing any secret material. */
+    async listFactors(userId) {
+        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) {
+        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) {
+        await this.#store.delete(factorId);
+    }
+    #isLocked(userId) {
+        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) {
+        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() {
+        if (!this.#totp) {
+            throw new WardenError("INVALID_CONFIG", "MfaManager has no TotpProvider configured");
+        }
+        return this.#totp;
+    }
+    #requireBackupCodes() {
+        if (!this.#backupCodes) {
+            throw new WardenError("INVALID_CONFIG", "MfaManager has no BackupCodesProvider configured");
+        }
+        return this.#backupCodes;
+    }
+}
+function newId() {
+    return randomBytes(16).toString("hex");
+}
+//# sourceMappingURL=MfaManager.js.map

package/dist/mfa/MfaManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MfaManager.js","sourceRoot":"","sources":["../../src/mfa/MfaManager.ts"],"names":[],"mappings":"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"}

package/dist/mfa/OtpProvider.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+/** 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 declare class MemoryOtpChallengeStore implements OtpChallengeStore {
+    #private;
+    save(c: OtpChallenge): Promise<void>;
+    find(id: string): Promise<OtpChallenge | null>;
+    delete(id: string): Promise<void>;
+}
+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 declare class OtpProvider {
+    #private;
+    readonly kind: "otp";
+    constructor(config: OtpConfig);
+    /** Mint a code, persist the challenge, and deliver it to `recipient`. */
+    start(recipient: string, nowMs?: number): Promise<OtpStartResult>;
+    /**
+     * Verify a submitted code. Wrong codes consume an attempt; the challenge is
+     * deleted on success, on expiry, or once the attempt budget is exhausted.
+     */
+    verify(challengeId: string, code: string, nowMs?: number): Promise<OtpVerification>;
+}
+//# sourceMappingURL=OtpProvider.d.ts.map

package/dist/mfa/OtpProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OtpProvider.d.ts","sourceRoot":"","sources":["../../src/mfa/OtpProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IAClC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IACjC,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,qBAAa,uBAAwB,YAAW,iBAAiB;;IAE1D,IAAI,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAGpC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAG9C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGvC;AAED,MAAM,WAAW,SAAS;IACzB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,wDAAwD;IACxD,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,gBAAgB,GACzB,WAAW,GACX,SAAS,GACT,mBAAmB,GACnB,UAAU,CAAC;AAEd,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAED,qBAAa,WAAW;;IACvB,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;gBAOnB,MAAM,EAAE,SAAS;IAc7B,yEAAyE;IACnE,KAAK,CACV,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,MAAmB,GACxB,OAAO,CAAC,cAAc,CAAC;IAe1B;;;OAGG;IACG,MAAM,CACX,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAmB,GACxB,OAAO,CAAC,eAAe,CAAC;CA0B3B"}