@c9up/warden 0.1.3 → 0.1.5

package/dist/strategies/JwtStrategy.d.ts

@@ -0,0 +1,51 @@
+/**
+ * JwtStrategy — HMAC-SHA256 JWT authentication strategy.
+ * All signing and verification runs through the Rust warden-engine via NAPI.
+ */
+import type { AuthResult, AuthStrategy, UserPayload } from "../AuthManager.js";
+import type { TokenBlacklist } from "../TokenBlacklist.js";
+export interface JwtStrategyConfig {
+    /**
+     * Active signing secret. New tokens are always signed with this key.
+     * For zero-downtime key rotation, also pass `previousSecrets` — verify
+     * tries each entry until one matches, then `revoke()` the rotated key
+     * by removing it from the config on the next deploy.
+     */
+    secret: string;
+    /**
+     * Older secrets accepted at verify time but never used to sign new
+     * tokens. Empty / omitted by default. Order doesn't matter for
+     * correctness but ordering by recency keeps the common path fast.
+     */
+    previousSecrets?: readonly string[];
+    expiresInSeconds?: number;
+    findUser: (id: string) => Promise<UserPayload | null>;
+    verifyCredentials: (email: string, password: string) => Promise<UserPayload | null>;
+    /**
+     * Optional blacklist for revocation. When supplied, `verify` rejects
+     * tokens whose `jti` is present, and `revoke(token)` adds the token's
+     * `jti` to the blacklist for the remainder of its lifetime. Without a
+     * blacklist, `revoke()` throws — the call would be a no-op silently.
+     */
+    blacklist?: TokenBlacklist;
+}
+export declare class JwtStrategy implements AuthStrategy {
+    #private;
+    name: string;
+    constructor(config: JwtStrategyConfig);
+    authenticate(credentials: Record<string, unknown>): Promise<AuthResult>;
+    verify(token: string): Promise<AuthResult>;
+    signToken(user: UserPayload): string;
+    /**
+     * Revoke a token until its `exp` claim. Requires the strategy to be
+     * constructed with a `blacklist` driver — otherwise throws so that a
+     * caller assuming revocation does not silently succeed against
+     * a no-op implementation.
+     *
+     * Returns `true` when the token was added to the blacklist, `false` when
+     * the token is already expired (revocation is unnecessary) or unparseable.
+     */
+    revoke(token: string): Promise<boolean>;
+}
+export declare function generateJwtSecret(): string;
+//# sourceMappingURL=JwtStrategy.d.ts.map

package/dist/strategies/JwtStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JwtStrategy.d.ts","sourceRoot":"","sources":["../../src/strategies/JwtStrategy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAwC3D,MAAM,WAAW,iBAAiB;IACjC;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACtD,iBAAiB,EAAE,CAClB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,KACZ,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACjC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,qBAAa,WAAY,YAAW,YAAY;;IAC/C,IAAI,SAAS;gBAaD,MAAM,EAAE,iBAAiB;IAgC/B,YAAY,CACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,CAAC,UAAU,CAAC;IAkBhB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAgChD,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM;IAepC;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAa7C;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/strategies/JwtStrategy.js

@@ -0,0 +1,150 @@
+/**
+ * JwtStrategy — HMAC-SHA256 JWT authentication strategy.
+ * All signing and verification runs through the Rust warden-engine via NAPI.
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { nativeWarden } from "../native.js";
+function sign(payload, secret) {
+    const rust = nativeWarden();
+    if (!rust) {
+        throw new Error("[WARDEN_NAPI_REQUIRED] The Rust warden-engine binary is required. Build it with `cd packages/warden && pnpm build:napi`.");
+    }
+    return rust.jwtSign(JSON.stringify(payload), secret);
+}
+function verify(token, secret) {
+    const rust = nativeWarden();
+    if (!rust) {
+        throw new Error("[WARDEN_NAPI_REQUIRED] The Rust warden-engine binary is required. Build it with `cd packages/warden && pnpm build:napi`.");
+    }
+    try {
+        const payloadJson = rust.jwtVerify(token, secret);
+        const payload = JSON.parse(payloadJson);
+        if (typeof payload.sub !== "string" || !payload.sub)
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+export class JwtStrategy {
+    name = "jwt";
+    #secret;
+    /**
+     * Verify-only secrets ordered active-first. Mirrors `config.secret` at
+     * index 0 plus any `previousSecrets`. Built once at construction so
+     * `verify()` doesn't re-allocate per call.
+     */
+    #verifySecrets;
+    #expiresIn;
+    #findUser;
+    #verifyCredentials;
+    #blacklist;
+    constructor(config) {
+        if (config.secret.length < 32) {
+            throw new Error("JWT secret must be at least 32 characters");
+        }
+        for (const prev of config.previousSecrets ?? []) {
+            if (prev.length < 32) {
+                throw new Error("JWT previousSecrets entries must be at least 32 characters");
+            }
+        }
+        this.#secret = config.secret;
+        this.#verifySecrets = [config.secret, ...(config.previousSecrets ?? [])];
+        this.#expiresIn = config.expiresInSeconds ?? 3600;
+        this.#findUser = config.findUser;
+        this.#verifyCredentials = config.verifyCredentials;
+        this.#blacklist = config.blacklist;
+    }
+    /**
+     * Try each accepted secret in order. First successful verify wins.
+     * Returns `null` when no secret accepts the token — same semantics as
+     * the single-secret path so callers see "invalid or expired token".
+     */
+    #verifyWithRotation(token) {
+        for (const secret of this.#verifySecrets) {
+            const payload = verify(token, secret);
+            if (payload)
+                return payload;
+        }
+        return null;
+    }
+    async authenticate(credentials) {
+        const email = typeof credentials.email === "string" ? credentials.email : null;
+        const password = typeof credentials.password === "string" ? credentials.password : null;
+        if (!email || !password) {
+            return { authenticated: false, error: "Email and password are required" };
+        }
+        const user = await this.#verifyCredentials(email, password);
+        if (!user) {
+            return { authenticated: false, error: "Invalid credentials" };
+        }
+        const token = this.signToken(user);
+        return { authenticated: true, user: { ...user, token } };
+    }
+    async verify(token) {
+        const payload = this.#verifyWithRotation(token);
+        if (!payload) {
+            return { authenticated: false, error: "Invalid or expired token" };
+        }
+        // Blacklist check runs BEFORE findUser so a revoked token never
+        // triggers a user lookup (cheaper, and avoids leaking user existence
+        // via timing differences between revoked and unknown-user paths).
+        if (this.#blacklist) {
+            // A token with no `jti` cannot be checked against the blacklist
+            // (`isRevoked(undefined)` always returns false), so it could
+            // never be revoked. When revocation is configured we must NOT
+            // trust such a token — reject it rather than let an
+            // unrevocable token through. (signToken always sets a jti;
+            // this guards legacy / externally-signed tokens.)
+            if (typeof payload.jti !== "string" || payload.jti.length === 0) {
+                return { authenticated: false, error: "Token missing jti claim" };
+            }
+            if (await this.#blacklist.isRevoked(payload.jti)) {
+                return { authenticated: false, error: "Token revoked" };
+            }
+        }
+        const user = await this.#findUser(payload.sub);
+        if (!user) {
+            return { authenticated: false, error: "User not found" };
+        }
+        return { authenticated: true, user };
+    }
+    signToken(user) {
+        const now = Math.floor(Date.now() / 1000);
+        return sign({
+            sub: user.id,
+            roles: user.roles,
+            permissions: user.permissions,
+            iat: now,
+            exp: now + this.#expiresIn,
+            jti: randomUUID(),
+        }, this.#secret);
+    }
+    /**
+     * Revoke a token until its `exp` claim. Requires the strategy to be
+     * constructed with a `blacklist` driver — otherwise throws so that a
+     * caller assuming revocation does not silently succeed against
+     * a no-op implementation.
+     *
+     * Returns `true` when the token was added to the blacklist, `false` when
+     * the token is already expired (revocation is unnecessary) or unparseable.
+     */
+    async revoke(token) {
+        if (!this.#blacklist) {
+            throw new Error("JwtStrategy.revoke() requires a `blacklist` driver. Pass `{ blacklist: new TokenBlacklist(driver) }` to the constructor.");
+        }
+        const payload = this.#verifyWithRotation(token);
+        if (!payload)
+            return false;
+        const expMs = payload.exp * 1000;
+        if (expMs <= Date.now())
+            return false;
+        await this.#blacklist.revoke(payload.jti, expMs);
+        return true;
+    }
+}
+export function generateJwtSecret() {
+    return randomBytes(48).toString("base64url");
+}
+//# sourceMappingURL=JwtStrategy.js.map

package/dist/strategies/JwtStrategy.js.map

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

package/dist/strategies/SessionStrategy.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Session-based authentication strategy.
+ *
+ * AdonisJS session guard pattern:
+ *   login stores userId in session, subsequent requests check session.
+ *
+ * @implements MISS-7
+ */
+import type { AuthResult, AuthStrategy, UserPayload } from "../AuthManager.js";
+export interface SessionStore {
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    forget(key: string): void;
+    /**
+     * Rotate the session id while preserving the data. REQUIRED to mitigate
+     * session fixation (CWE-384) at login. Ream's `Session.regenerate()`
+     * implements this; adapters around other session stores MUST too. The
+     * default ream → warden plumbing exposes the `Session` instance
+     * directly so this is wired automatically.
+     */
+    regenerate(): void;
+}
+export interface SessionStrategyConfig {
+    sessionKey?: string;
+    findUser: (id: string | number) => Promise<UserPayload | null>;
+}
+export declare class SessionStrategy implements AuthStrategy {
+    #private;
+    name: string;
+    constructor(config: SessionStrategyConfig);
+    /** Authenticate via email/password — stores user ID in session. */
+    authenticate(_credentials: {
+        email: string;
+        password: string;
+    }, _context?: {
+        session?: SessionStore;
+    }): Promise<AuthResult>;
+    /** Verify session — check if user ID is stored in session. */
+    verify(_token: string): Promise<AuthResult>;
+    /** Verify session with context — check if user ID is stored in session. */
+    verifyWithContext(_token: string, context?: {
+        session?: SessionStore;
+    }): Promise<AuthResult>;
+    /**
+     * Login a user — store their ID in the session.
+     *
+     * Rotates the session id BEFORE writing the authenticated user id, so an
+     * attacker who fed the victim a pre-login session cookie (classic
+     * session-fixation attack, CWE-384) ends up holding a now-discarded id
+     * while the victim continues under a fresh one. The driver-side cookie
+     * migration is handled by Ream's `SessionMiddleware` on the response
+     * path — see `wasRegenerated()` there.
+     */
+    login(user: UserPayload, session: SessionStore): Promise<void>;
+    /** Logout — remove user ID from session. */
+    logout(session: SessionStore): Promise<void>;
+}
+//# sourceMappingURL=SessionStrategy.d.ts.map

package/dist/strategies/SessionStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionStrategy.d.ts","sourceRoot":"","sources":["../../src/strategies/SessionStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAG/E,MAAM,WAAW,YAAY;IAC5B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;;OAMG;IACH,UAAU,IAAI,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC/D;AAED,qBAAa,eAAgB,YAAW,YAAY;;IACnD,IAAI,SAAa;gBAIL,MAAM,EAAE,qBAAqB;IAKzC,mEAAmE;IAC7D,YAAY,CACjB,YAAY,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EACjD,QAAQ,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,YAAY,CAAA;KAAE,GACnC,OAAO,CAAC,UAAU,CAAC;IAgBtB,8DAA8D;IACxD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAQjD,2EAA2E;IACrE,iBAAiB,CACtB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,YAAY,CAAA;KAAE,GAClC,OAAO,CAAC,UAAU,CAAC;IAWtB;;;;;;;;;OASG;IACG,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpE,4CAA4C;IACtC,MAAM,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAGlD"}

package/dist/strategies/SessionStrategy.js

@@ -0,0 +1,70 @@
+/**
+ * Session-based authentication strategy.
+ *
+ * AdonisJS session guard pattern:
+ *   login stores userId in session, subsequent requests check session.
+ *
+ * @implements MISS-7
+ */
+import { WardenError } from "../errors.js";
+export class SessionStrategy {
+    name = "session";
+    #config;
+    #sessionKey;
+    constructor(config) {
+        this.#config = config;
+        this.#sessionKey = config.sessionKey ?? "auth_user_id";
+    }
+    /** Authenticate via email/password — stores user ID in session. */
+    async authenticate(_credentials, _context) {
+        // Session strategy doesn't handle password verification — that's done
+        // by the caller. We throw a typed sentinel WardenError so AuthManager's
+        // try/catch (which swallows generic errors into a soft AuthResult)
+        // re-throws this one — the design boundary stays unmissable even when
+        // a caller routes through `authManager.authenticate()` instead of
+        // `strategy.authenticate()` directly.
+        throw new WardenError("USE_LOGIN", "SessionStrategy.authenticate() requires login() instead. Use authManager.login(user, session).", {
+            hint: "Verify the password yourself (e.g. via @c9up/sigil Hash.verify), then call SessionStrategy.login(user, session).",
+        });
+    }
+    /** Verify session — check if user ID is stored in session. */
+    async verify(_token) {
+        return {
+            authenticated: false,
+            error: "SessionStrategy.verify() requires context. Use verifyWithContext().",
+        };
+    }
+    /** Verify session with context — check if user ID is stored in session. */
+    async verifyWithContext(_token, context) {
+        if (!context?.session)
+            return { authenticated: false, error: "No session" };
+        const userId = context.session.get(this.#sessionKey);
+        if (!userId)
+            return { authenticated: false, error: "No session user" };
+        if (typeof userId !== "string" && typeof userId !== "number")
+            return { authenticated: false, error: "Invalid session data" };
+        const user = await this.#config.findUser(userId);
+        if (!user)
+            return { authenticated: false, error: "User not found" };
+        return { authenticated: true, user };
+    }
+    /**
+     * Login a user — store their ID in the session.
+     *
+     * Rotates the session id BEFORE writing the authenticated user id, so an
+     * attacker who fed the victim a pre-login session cookie (classic
+     * session-fixation attack, CWE-384) ends up holding a now-discarded id
+     * while the victim continues under a fresh one. The driver-side cookie
+     * migration is handled by Ream's `SessionMiddleware` on the response
+     * path — see `wasRegenerated()` there.
+     */
+    async login(user, session) {
+        session.regenerate();
+        session.set(this.#sessionKey, user.id);
+    }
+    /** Logout — remove user ID from session. */
+    async logout(session) {
+        session.forget(this.#sessionKey);
+    }
+}
+//# sourceMappingURL=SessionStrategy.js.map

package/dist/strategies/SessionStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionStrategy.js","sourceRoot":"","sources":["../../src/strategies/SessionStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAqB3C,MAAM,OAAO,eAAe;IAC3B,IAAI,GAAG,SAAS,CAAC;IACjB,OAAO,CAAwB;IAC/B,WAAW,CAAS;IAEpB,YAAY,MAA6B;QACxC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,IAAI,cAAc,CAAC;IACxD,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,YAAY,CACjB,YAAiD,EACjD,QAAqC;QAErC,sEAAsE;QACtE,wEAAwE;QACxE,mEAAmE;QACnE,sEAAsE;QACtE,kEAAkE;QAClE,sCAAsC;QACtC,MAAM,IAAI,WAAW,CACpB,WAAW,EACX,gGAAgG,EAChG;YACC,IAAI,EAAE,kHAAkH;SACxH,CACD,CAAC;IACH,CAAC;IAED,8DAA8D;IAC9D,KAAK,CAAC,MAAM,CAAC,MAAc;QAC1B,OAAO;YACN,aAAa,EAAE,KAAK;YACpB,KAAK,EACJ,qEAAqE;SACtE,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,iBAAiB,CACtB,MAAc,EACd,OAAoC;QAEpC,IAAI,CAAC,OAAO,EAAE,OAAO;YAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;QAC5E,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACrD,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC;QACvE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK,QAAQ;YAC3D,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC;QAChE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;QACpE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACtC,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,KAAK,CAAC,IAAiB,EAAE,OAAqB;QACnD,OAAO,CAAC,UAAU,EAAE,CAAC;QACrB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,4CAA4C;IAC5C,KAAK,CAAC,MAAM,CAAC,OAAqB;QACjC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAClC,CAAC;CACD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/warden",
-  "version": "0.1.3",
+  "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. */