@c9up/warden 0.1.4 → 0.1.5

package/dist/mfa/webauthn-codec.d.ts

@@ -0,0 +1,58 @@
+/**
+ * WebAuthn wire-format codec — the parsing and crypto primitives behind
+ * `WebauthnProvider`, implemented from scratch on `node:crypto` so warden
+ * carries no third-party dependency.
+ *
+ * Scope: the subset of CBOR / COSE / authenticator-data that FIDO2 ceremonies
+ * actually use, with public-key algorithms Node can import via JWK:
+ *   - ES256 / ES384 / ES512 (ECDSA, COSE alg -7 / -35 / -36)
+ *   - RS256 / RS384 / RS512 (RSASSA-PKCS1-v1_5, alg -257 / -258 / -259)
+ *   - EdDSA / Ed25519 (alg -8)
+ *
+ * Attestation *statements* are intentionally not verified (see WebauthnProvider).
+ */
+import { type KeyObject } from "node:crypto";
+export type CborValue = number | string | Buffer | CborValue[] | CborMap | boolean | null;
+export type CborMap = Map<number | string, CborValue>;
+export declare function base64urlToBuffer(s: string): Buffer;
+export declare function bufferToBase64url(b: Buffer | Uint8Array): string;
+export declare function sha256(data: Buffer): Buffer;
+interface Decoded {
+    value: CborValue;
+    /** Byte offset immediately after the decoded item. */
+    next: number;
+}
+/**
+ * Decode a single CBOR item starting at `start`. Definite-length only —
+ * indefinite-length items and floats are rejected (WebAuthn uses neither).
+ */
+export declare function decodeCbor(buf: Buffer, start?: number): Decoded;
+export interface AuthenticatorData {
+    rpIdHash: Buffer;
+    flags: {
+        up: boolean;
+        uv: boolean;
+        at: boolean;
+        ed: boolean;
+    };
+    signCount: number;
+    credentialId?: Buffer;
+    cosePublicKey?: CborMap;
+    /** Raw COSE_Key bytes, ready to persist and re-decode at sign-in time. */
+    cosePublicKeyBytes?: Buffer;
+}
+/** Parse the raw authenticator-data structure (§6.1 of the WebAuthn spec). */
+export declare function parseAuthenticatorData(authData: Buffer): AuthenticatorData;
+/** Convert a COSE_Key map into a Node public key plus its COSE algorithm id. */
+export declare function coseToKeyObject(cose: CborMap): {
+    key: KeyObject;
+    alg: number;
+};
+/**
+ * Verify a WebAuthn assertion signature over `data` (= authenticatorData ‖
+ * SHA-256(clientDataJSON)). ECDSA signatures are DER-encoded, matching what
+ * authenticators emit.
+ */
+export declare function verifyWebauthnSignature(alg: number, key: KeyObject, data: Buffer, signature: Buffer): boolean;
+export {};
+//# sourceMappingURL=webauthn-codec.d.ts.map

package/dist/mfa/webauthn-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webauthn-codec.d.ts","sourceRoot":"","sources":["../../src/mfa/webauthn-codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAKN,KAAK,SAAS,EACd,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,SAAS,GAClB,MAAM,GACN,MAAM,GACN,MAAM,GACN,SAAS,EAAE,GACX,OAAO,GACP,OAAO,GACP,IAAI,CAAC;AACR,MAAM,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,SAAS,CAAC,CAAC;AAEtD,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAEhE;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,UAAU,OAAO;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,OAAO,CAwE1D;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CA+B1E;AAmBD,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG;IAC/C,GAAG,EAAE,SAAS,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACZ,CAuCA;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACtC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GACf,OAAO,CAKT"}

package/dist/mfa/webauthn-codec.js

@@ -0,0 +1,221 @@
+/**
+ * WebAuthn wire-format codec — the parsing and crypto primitives behind
+ * `WebauthnProvider`, implemented from scratch on `node:crypto` so warden
+ * carries no third-party dependency.
+ *
+ * Scope: the subset of CBOR / COSE / authenticator-data that FIDO2 ceremonies
+ * actually use, with public-key algorithms Node can import via JWK:
+ *   - ES256 / ES384 / ES512 (ECDSA, COSE alg -7 / -35 / -36)
+ *   - RS256 / RS384 / RS512 (RSASSA-PKCS1-v1_5, alg -257 / -258 / -259)
+ *   - EdDSA / Ed25519 (alg -8)
+ *
+ * Attestation *statements* are intentionally not verified (see WebauthnProvider).
+ */
+import { createHash, createPublicKey, verify as cryptoVerify, } from "node:crypto";
+export function base64urlToBuffer(s) {
+    return Buffer.from(s, "base64url");
+}
+export function bufferToBase64url(b) {
+    return Buffer.from(b).toString("base64url");
+}
+export function sha256(data) {
+    return createHash("sha256").update(data).digest();
+}
+/**
+ * Decode a single CBOR item starting at `start`. Definite-length only —
+ * indefinite-length items and floats are rejected (WebAuthn uses neither).
+ */
+export function decodeCbor(buf, start = 0) {
+    const major = buf[start] >> 5;
+    const info = buf[start] & 0x1f;
+    let len;
+    let p = start + 1;
+    if (info < 24) {
+        len = info;
+    }
+    else if (info === 24) {
+        len = buf[p];
+        p += 1;
+    }
+    else if (info === 25) {
+        len = buf.readUInt16BE(p);
+        p += 2;
+    }
+    else if (info === 26) {
+        len = buf.readUInt32BE(p);
+        p += 4;
+    }
+    else if (info === 27) {
+        len = Number(buf.readBigUInt64BE(p));
+        p += 8;
+    }
+    else {
+        throw new Error("CBOR: indefinite or reserved length is not supported");
+    }
+    switch (major) {
+        case 0: // unsigned int
+            return { value: len, next: p };
+        case 1: // negative int
+            return { value: -1 - len, next: p };
+        case 2: // byte string
+            return { value: buf.subarray(p, p + len), next: p + len };
+        case 3: // text string
+            return { value: buf.toString("utf8", p, p + len), next: p + len };
+        case 4: {
+            // array
+            const arr = [];
+            let cur = p;
+            for (let i = 0; i < len; i++) {
+                const d = decodeCbor(buf, cur);
+                arr.push(d.value);
+                cur = d.next;
+            }
+            return { value: arr, next: cur };
+        }
+        case 5: {
+            // map
+            const map = new Map();
+            let cur = p;
+            for (let i = 0; i < len; i++) {
+                const k = decodeCbor(buf, cur);
+                cur = k.next;
+                const v = decodeCbor(buf, cur);
+                cur = v.next;
+                if (typeof k.value !== "number" && typeof k.value !== "string") {
+                    throw new Error("CBOR: only integer/text map keys are supported");
+                }
+                map.set(k.value, v.value);
+            }
+            return { value: map, next: cur };
+        }
+        case 6: {
+            // tag — decode and surface the tagged content
+            const d = decodeCbor(buf, p);
+            return { value: d.value, next: d.next };
+        }
+        case 7:
+            if (info === 20)
+                return { value: false, next: p };
+            if (info === 21)
+                return { value: true, next: p };
+            if (info === 22)
+                return { value: null, next: p };
+            throw new Error("CBOR: simple/float values are not supported");
+        default:
+            throw new Error(`CBOR: unknown major type ${major}`);
+    }
+}
+/** Parse the raw authenticator-data structure (§6.1 of the WebAuthn spec). */
+export function parseAuthenticatorData(authData) {
+    if (authData.length < 37) {
+        throw new Error("authenticatorData is too short");
+    }
+    const flagsByte = authData[32];
+    const flags = {
+        up: (flagsByte & 0x01) !== 0,
+        uv: (flagsByte & 0x04) !== 0,
+        at: (flagsByte & 0x40) !== 0,
+        ed: (flagsByte & 0x80) !== 0,
+    };
+    const result = {
+        rpIdHash: authData.subarray(0, 32),
+        flags,
+        signCount: authData.readUInt32BE(33),
+    };
+    if (flags.at) {
+        if (authData.length < 55) {
+            throw new Error("attested credential data is truncated");
+        }
+        const credIdLen = authData.readUInt16BE(53);
+        result.credentialId = authData.subarray(55, 55 + credIdLen);
+        const coseStart = 55 + credIdLen;
+        const decoded = decodeCbor(authData, coseStart);
+        if (!(decoded.value instanceof Map)) {
+            throw new Error("COSE public key is not a CBOR map");
+        }
+        result.cosePublicKey = decoded.value;
+        result.cosePublicKeyBytes = authData.subarray(coseStart, decoded.next);
+    }
+    return result;
+}
+// COSE algorithm id → the hash Node should use ( `null` = pre-hashed / Ed25519 ).
+const ALG_HASH = {
+    [-7]: "sha256",
+    [-35]: "sha384",
+    [-36]: "sha512",
+    [-257]: "sha256",
+    [-258]: "sha384",
+    [-259]: "sha512",
+    [-8]: null,
+};
+const EC_CURVES = {
+    1: "P-256",
+    2: "P-384",
+    3: "P-521",
+};
+/** Convert a COSE_Key map into a Node public key plus its COSE algorithm id. */
+export function coseToKeyObject(cose) {
+    const kty = expectNumber(cose.get(1), "COSE kty");
+    const alg = expectNumber(cose.get(3), "COSE alg");
+    let jwk;
+    if (kty === 2) {
+        // EC2
+        const curve = EC_CURVES[expectNumber(cose.get(-1), "EC curve")];
+        if (!curve) {
+            throw new Error("unsupported COSE EC curve");
+        }
+        jwk = {
+            kty: "EC",
+            crv: curve,
+            x: bufferToBase64url(expectBytes(cose.get(-2), "EC x")),
+            y: bufferToBase64url(expectBytes(cose.get(-3), "EC y")),
+        };
+    }
+    else if (kty === 3) {
+        // RSA
+        jwk = {
+            kty: "RSA",
+            n: bufferToBase64url(expectBytes(cose.get(-1), "RSA n")),
+            e: bufferToBase64url(expectBytes(cose.get(-2), "RSA e")),
+        };
+    }
+    else if (kty === 1) {
+        // OKP / Ed25519
+        if (expectNumber(cose.get(-1), "OKP curve") !== 6) {
+            throw new Error("unsupported COSE OKP curve (only Ed25519)");
+        }
+        jwk = {
+            kty: "OKP",
+            crv: "Ed25519",
+            x: bufferToBase64url(expectBytes(cose.get(-2), "OKP x")),
+        };
+    }
+    else {
+        throw new Error(`unsupported COSE key type ${kty}`);
+    }
+    return { key: createPublicKey({ key: jwk, format: "jwk" }), alg };
+}
+/**
+ * Verify a WebAuthn assertion signature over `data` (= authenticatorData ‖
+ * SHA-256(clientDataJSON)). ECDSA signatures are DER-encoded, matching what
+ * authenticators emit.
+ */
+export function verifyWebauthnSignature(alg, key, data, signature) {
+    if (!(alg in ALG_HASH)) {
+        throw new Error(`unsupported COSE algorithm ${alg}`);
+    }
+    return cryptoVerify(ALG_HASH[alg], data, key, signature);
+}
+function expectNumber(v, what) {
+    if (typeof v !== "number") {
+        throw new Error(`${what}: expected an integer`);
+    }
+    return v;
+}
+function expectBytes(v, what) {
+    if (!Buffer.isBuffer(v)) {
+        throw new Error(`${what}: expected a byte string`);
+    }
+    return v;
+}
+//# sourceMappingURL=webauthn-codec.js.map

package/dist/mfa/webauthn-codec.js.map

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

package/dist/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEN,KAAK,UAAU,EAGf,MAAM,kBAAkB,CAAC;AAM1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAcpE,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE;QACR,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC,CAAC;IACF,QAAQ,EAAE;QACT,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAC/B,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;KAC9B,CAAC;IACF,SAAS,EAAE;QACV,OAAO,EAAE,CACR,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,KAC/D,OAAO,CAAC;KACb,CAAC;IACF,4DAA4D;IAC5D,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,mDAAmD;IACnD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,+CAA+C;IAC/C,KAAK,CAAC,EAAE;QACP,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KACzB,CAAC;CACF;AAED,KAAK,UAAU,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE7C;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,iBAoG1E"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEN,KAAK,UAAU,EAGf,MAAM,kBAAkB,CAAC;AAO1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAcpE,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE;QACR,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC,CAAC;IACF,QAAQ,EAAE;QACT,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAC/B,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;KAC9B,CAAC;IACF,SAAS,EAAE;QACV,OAAO,EAAE,CACR,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,KAC/D,OAAO,CAAC;KACb,CAAC;IACF,4DAA4D;IAC5D,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,mDAAmD;IACnD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,+CAA+C;IAC/C,KAAK,CAAC,EAAE;QACP,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KACzB,CAAC;CACF;AAED,KAAK,UAAU,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE7C;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,iBAiH1E"}

package/dist/middleware.js

@@ -16,7 +16,7 @@
  *   }
  */
 import { AuthManager, sanitizePayload, } from "./AuthManager.js";
-import { getGuardMetadata, getPermissionMetadata, getRoleMetadata, } from "./Guard.js";
+import { getGuardMetadata, getPermissionMetadata, getRequireMfaMetadata, getRoleMetadata, } from "./Guard.js";
 function hasVerifyWithContext(strategy) {
     return (typeof strategy.verifyWithContext === "function");
 }
@@ -107,6 +107,18 @@ export async function wardenMiddleware(ctx, next) {
             ctx.response.json({ error: { code: "FORBIDDEN", message: denied } });
             return;
         }
+        // @RequireMfa gate: the user must carry a truthy `mfa` claim, set by the
+        // app's step-up flow once MfaManager.verify() succeeds.
+        if (getRequireMfaMetadata(controller, action) && user.mfa !== true) {
+            ctx.response.status(403);
+            ctx.response.json({
+                error: {
+                    code: "MFA_REQUIRED",
+                    message: "Multi-factor authentication is required for this action.",
+                },
+            });
+            return;
+        }
     }
     // Auth successful — attach to context and continue.
     ctx.auth = result;

package/dist/middleware.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/warden",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Warden — Authentication for the Ream framework",
   "license": "MIT",
   "type": "module",

package/src/Guard.ts

@@ -13,6 +13,7 @@ import "reflect-metadata";
 const GUARD_KEY = Symbol.for("warden:guard");
 const PERMISSION_KEY = Symbol.for("warden:permission");
 const ROLE_KEY = Symbol.for("warden:role");
+const MFA_KEY = Symbol.for("warden:mfa");
 
 /**
  * @Guard('jwt') — require authentication via the named strategy.
@@ -66,3 +67,23 @@ export function getRoleMetadata(
 ): string[] {
 	return Reflect.getOwnMetadata(ROLE_KEY, target, propertyKey) ?? [];
 }
+
+/**
+ * @RequireMfa() — require the authenticated user to have completed multi-factor
+ * authentication. The auth middleware rejects with 403 `MFA_REQUIRED` when the
+ * user payload lacks a truthy `mfa` claim (set by your MFA step-up flow once
+ * `MfaManager.verify()` succeeds).
+ */
+export function RequireMfa(): MethodDecorator {
+	return (target, propertyKey) => {
+		Reflect.defineMetadata(MFA_KEY, true, target, propertyKey);
+	};
+}
+
+/** Whether the route requires completed MFA. */
+export function getRequireMfaMetadata(
+	target: object,
+	propertyKey: string | symbol,
+): boolean {
+	return Reflect.getOwnMetadata(MFA_KEY, target, propertyKey) ?? false;
+}

package/src/RedisBlacklistDriver.ts

@@ -0,0 +1,60 @@
+/**
+ * RedisBlacklistDriver — a persistent JWT blacklist backed by Redis / KeyDB,
+ * so logout revocation survives a process restart (unlike MemoryBlacklistDriver).
+ *
+ * Agnostic by construction: it depends on no Redis package. The caller injects
+ * any ioredis-compatible client (KeyDB, Redis, a mock…) that exposes `set` with
+ * an `"EX"` ttl and `exists`. Native key expiry does the housekeeping, so
+ * `cleanup()` is a no-op.
+ */
+
+import type { BlacklistDriver } from "./TokenBlacklist.js";
+
+/** The minimal ioredis-shaped surface this driver needs. */
+export interface RedisLikeClient {
+	set(
+		key: string,
+		value: string,
+		mode: "EX",
+		ttlSeconds: number,
+	): Promise<unknown>;
+	exists(key: string): Promise<number>;
+}
+
+export interface RedisBlacklistConfig {
+	/** Key prefix for blacklist entries. Default `warden:blacklist:`. */
+	prefix?: string;
+}
+
+export class RedisBlacklistDriver implements BlacklistDriver {
+	readonly #client: RedisLikeClient;
+	readonly #prefix: string;
+
+	constructor(client: RedisLikeClient, config: RedisBlacklistConfig = {}) {
+		this.#client = client;
+		this.#prefix = config.prefix ?? "warden:blacklist:";
+	}
+
+	/**
+	 * Blacklist a JTI until its natural expiry. Tokens already past `expiresAt`
+	 * are skipped — there is nothing left to revoke.
+	 */
+	async add(jti: string, expiresAt: number): Promise<void> {
+		const ttlSeconds = Math.ceil((expiresAt - Date.now()) / 1000);
+		if (ttlSeconds <= 0) {
+			return;
+		}
+		await this.#client.set(this.#key(jti), "1", "EX", ttlSeconds);
+	}
+
+	async has(jti: string): Promise<boolean> {
+		return (await this.#client.exists(this.#key(jti))) > 0;
+	}
+
+	/** No-op: Redis/KeyDB evicts expired keys on its own. */
+	async cleanup(): Promise<void> {}
+
+	#key(jti: string): string {
+		return `${this.#prefix}${jti}`;
+	}
+}

package/src/ResilientBlacklistDriver.ts

@@ -0,0 +1,84 @@
+/**
+ * ResilientBlacklistDriver — wraps a primary blacklist (e.g. KeyDB-backed
+ * `RedisBlacklistDriver`) with an in-memory fallback so a cache outage never
+ * takes the whole app down.
+ *
+ * Policy (fail-open on reads):
+ *   - `add()`  — if the primary throws, the revocation is recorded in the
+ *                fallback so logout stays effective on this instance.
+ *   - `has()`  — if the primary throws, consult the fallback: a token revoked
+ *                during the outage is still caught here; anything else is
+ *                allowed through (fail-open). Access tokens are short-lived, so
+ *                the window a missed revocation survives is bounded by the token
+ *                TTL — the blacklist is defense-in-depth above expiry, not the
+ *                primary boundary.
+ *
+ * Every degradation invokes `onDegrade` (defaults to a stderr warning) so the
+ * outage is observable.
+ */
+
+import {
+	type BlacklistDriver,
+	MemoryBlacklistDriver,
+} from "./TokenBlacklist.js";
+
+export interface BlacklistDegradeEvent {
+	op: "add" | "has" | "cleanup";
+	error: unknown;
+}
+
+export interface ResilientBlacklistConfig {
+	/** Invoked whenever the primary driver fails and the fallback is used. */
+	onDegrade?: (event: BlacklistDegradeEvent) => void;
+}
+
+function defaultOnDegrade({ op, error }: BlacklistDegradeEvent): void {
+	console.warn(
+		`[warden] blacklist primary failed on ${op}; using in-memory fallback:`,
+		error,
+	);
+}
+
+export class ResilientBlacklistDriver implements BlacklistDriver {
+	readonly #primary: BlacklistDriver;
+	readonly #fallback: BlacklistDriver;
+	readonly #onDegrade: (event: BlacklistDegradeEvent) => void;
+
+	constructor(
+		primary: BlacklistDriver,
+		fallback: BlacklistDriver = new MemoryBlacklistDriver(),
+		config: ResilientBlacklistConfig = {},
+	) {
+		this.#primary = primary;
+		this.#fallback = fallback;
+		this.#onDegrade = config.onDegrade ?? defaultOnDegrade;
+	}
+
+	async add(jti: string, expiresAt: number): Promise<void> {
+		try {
+			await this.#primary.add(jti, expiresAt);
+		} catch (error) {
+			this.#onDegrade({ op: "add", error });
+			await this.#fallback.add(jti, expiresAt);
+		}
+	}
+
+	async has(jti: string): Promise<boolean> {
+		try {
+			return await this.#primary.has(jti);
+		} catch (error) {
+			this.#onDegrade({ op: "has", error });
+			// Fail-open: honour in-outage revocations on this instance, allow rest.
+			return this.#fallback.has(jti);
+		}
+	}
+
+	async cleanup(): Promise<void> {
+		try {
+			await this.#primary.cleanup();
+		} catch (error) {
+			this.#onDegrade({ op: "cleanup", error });
+		}
+		await this.#fallback.cleanup();
+	}
+}

package/src/WardenProvider.ts

@@ -1,6 +1,7 @@
 import { AuthManager } from "./AuthManager.js";
 import type { WardenConfig } from "./config.js";
 import { WardenError } from "./errors.js";
+import { MfaManager } from "./mfa/MfaManager.js";
 import { MemoryRightsStore } from "./rights/MemoryRightsStore.js";
 import { RightsResolver } from "./rights/RightsResolver.js";
 import { setAuth } from "./services/main.js";
@@ -76,6 +77,16 @@ export default class WardenProvider {
 		this.app.container.singleton("auth", () =>
 			this.app.container.resolve(AuthManager),
 		);
+
+		// MFA (optional): the app builds an MfaManager with its persistent stores
+		// + providers and passes it via config.mfa. Registered by class and under
+		// the "mfa" string alias (same convention as "auth") so controllers and
+		// agnostic consumers can resolve it.
+		const mfa = config.mfa?.manager;
+		if (mfa) {
+			this.app.container.singleton(MfaManager, () => mfa);
+			this.app.container.singleton("mfa", () => mfa);
+		}
 	}
 
 	async boot() {

package/src/config.ts

@@ -16,6 +16,7 @@
  */
 
 import type { UserPayload } from "./AuthManager.js";
+import type { MfaManager } from "./mfa/MfaManager.js";
 import type { RightsStore } from "./rights/types.js";
 
 export interface JwtConfig {
@@ -40,6 +41,12 @@ export interface WardenConfig {
 	 * in-memory shipped).
 	 */
 	rights?: { store?: RightsStore };
+	/**
+	 * 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. */