@c9up/warden 0.1.4 → 0.1.5

package/README.md

@@ -29,6 +29,63 @@ class OrderController {
 - RBAC: `hasRole`, `hasPermission`, `hasAllPermissions`
 - Strategy exception safety (catch → AuthResult)
 - Runtime strategy registration
+- **Multi-factor authentication** — TOTP, backup codes, email/SMS OTP, WebAuthn/passkeys, all dependency-free
+- JWT revocation blacklist (Memory / Redis-KeyDB / resilient fallback drivers)
+
+## Multi-factor authentication
+
+Four providers, all implemented on `node:crypto` with **zero third-party dependency**
+(WebAuthn included). Every provider and the manager take pluggable stores, defaulting
+to in-memory — supply persistent stores (Atlas, KeyDB…) in production.
+
+```typescript
+import {
+  MfaManager,
+  TotpProvider,
+  BackupCodesProvider,
+  RequireMfa,
+} from '@c9up/warden'
+
+const mfa = new MfaManager({
+  issuer: 'Fluveo',
+  totp: new TotpProvider(),
+  backupCodes: new BackupCodesProvider(),
+  // store: new AtlasMfaFactorStore(db),   // persistent factors in production
+  rateLimit: { maxAttempts: 5, windowSeconds: 900 }, // per-user brute-force lock
+})
+
+// Enroll (returns the otpauth:// URI to render as a QR code)
+const { factorId, uri } = await mfa.enrollTotp({ id: user.id, name: user.email })
+await mfa.confirmTotp(factorId, codeFromAuthenticatorApp)   // → true once confirmed
+const recoveryCodes = await mfa.createBackupCodes(user.id)  // show once
+
+// At sign-in step-up: TOTP code OR a backup code (rate-limited)
+if (await mfa.verify(user.id, submittedCode)) {
+  // issue a JWT carrying `mfa: true`
+}
+```
+
+Gate sensitive routes — the middleware returns `403 MFA_REQUIRED` unless the
+authenticated user's payload carries a truthy `mfa` claim:
+
+```typescript
+class TransferController {
+  @Guard('jwt')
+  @RequireMfa()
+  async transfer() { /* only reachable after MFA step-up */ }
+}
+```
+
+Wire the manager into the container via config:
+
+```typescript
+// config/auth.ts
+import { defineConfig } from '@c9up/warden/config'
+export default defineConfig({ jwt: { /* … */ }, mfa: { manager: mfa } })
+```
+
+Email/SMS OTP (`OtpProvider`) and WebAuthn/passkeys (`WebauthnProvider`) are used
+directly — OTP needs a delivery channel, WebAuthn persists passkeys in its own store.
 
 ## License
 

package/dist/Guard.d.ts

@@ -23,4 +23,13 @@ export declare function getGuardMetadata(target: object, propertyKey: string | s
 export declare function getPermissionMetadata(target: object, propertyKey: string | symbol): string[];
 /** Get role metadata. */
 export declare function getRoleMetadata(target: object, propertyKey: string | symbol): string[];
+/**
+ * @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 declare function RequireMfa(): MethodDecorator;
+/** Whether the route requires completed MFA. */
+export declare function getRequireMfaMetadata(target: object, propertyKey: string | symbol): boolean;
 //# sourceMappingURL=Guard.d.ts.map

package/dist/Guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Guard.d.ts","sourceRoot":"","sources":["../src/Guard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,kBAAkB,CAAC;AAO1B;;;GAGG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CAKvE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,eAAe,CAIpE;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,eAAe,CAIxD;AAED,0BAA0B;AAC1B,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC1B,MAAM,EAAE,CAEV;AAED,+BAA+B;AAC/B,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC1B,MAAM,EAAE,CAEV;AAED,yBAAyB;AACzB,wBAAgB,eAAe,CAC9B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC1B,MAAM,EAAE,CAEV"}
+{"version":3,"file":"Guard.d.ts","sourceRoot":"","sources":["../src/Guard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,kBAAkB,CAAC;AAQ1B;;;GAGG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CAKvE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,eAAe,CAIpE;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,eAAe,CAIxD;AAED,0BAA0B;AAC1B,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC1B,MAAM,EAAE,CAEV;AAED,+BAA+B;AAC/B,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC1B,MAAM,EAAE,CAEV;AAED,yBAAyB;AACzB,wBAAgB,eAAe,CAC9B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC1B,MAAM,EAAE,CAEV;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,eAAe,CAI5C;AAED,gDAAgD;AAChD,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC1B,OAAO,CAET"}

package/dist/Guard.js

@@ -11,6 +11,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.
  * At least one strategy name is required.
@@ -49,4 +50,19 @@ export function getPermissionMetadata(target, propertyKey) {
 export function getRoleMetadata(target, propertyKey) {
     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() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(MFA_KEY, true, target, propertyKey);
+    };
+}
+/** Whether the route requires completed MFA. */
+export function getRequireMfaMetadata(target, propertyKey) {
+    return Reflect.getOwnMetadata(MFA_KEY, target, propertyKey) ?? false;
+}
 //# sourceMappingURL=Guard.js.map

package/dist/Guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"Guard.js","sourceRoot":"","sources":["../src/Guard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gFAAgF;AAChF,0EAA0E;AAC1E,0EAA0E;AAC1E,OAAO,kBAAkB,CAAC;AAE1B,oFAAoF;AACpF,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AAC7C,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;AACvD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,KAAa,EAAE,GAAG,IAAc;IACrD,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC;IACpC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IACpE,CAAC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,GAAG,WAAqB;IAClD,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,cAAc,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAC1E,CAAC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,IAAI,CAAC,GAAG,KAAe;IACtC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAC9D,CAAC,CAAC;AACH,CAAC;AAED,0BAA0B;AAC1B,MAAM,UAAU,gBAAgB,CAC/B,MAAc,EACd,WAA4B;IAE5B,OAAO,OAAO,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;AACrE,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,qBAAqB,CACpC,MAAc,EACd,WAA4B;IAE5B,OAAO,OAAO,CAAC,cAAc,CAAC,cAAc,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;AAC1E,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,eAAe,CAC9B,MAAc,EACd,WAA4B;IAE5B,OAAO,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;AACpE,CAAC"}
+{"version":3,"file":"Guard.js","sourceRoot":"","sources":["../src/Guard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gFAAgF;AAChF,0EAA0E;AAC1E,0EAA0E;AAC1E,OAAO,kBAAkB,CAAC;AAE1B,oFAAoF;AACpF,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AAC7C,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;AACvD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AAC3C,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAEzC;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,KAAa,EAAE,GAAG,IAAc;IACrD,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC;IACpC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IACpE,CAAC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,GAAG,WAAqB;IAClD,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,cAAc,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAC1E,CAAC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,IAAI,CAAC,GAAG,KAAe;IACtC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAC9D,CAAC,CAAC;AACH,CAAC;AAED,0BAA0B;AAC1B,MAAM,UAAU,gBAAgB,CAC/B,MAAc,EACd,WAA4B;IAE5B,OAAO,OAAO,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;AACrE,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,qBAAqB,CACpC,MAAc,EACd,WAA4B;IAE5B,OAAO,OAAO,CAAC,cAAc,CAAC,cAAc,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;AAC1E,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,eAAe,CAC9B,MAAc,EACd,WAA4B;IAE5B,OAAO,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;AACpE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU;IACzB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAC5D,CAAC,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,qBAAqB,CACpC,MAAc,EACd,WAA4B;IAE5B,OAAO,OAAO,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,KAAK,CAAC;AACtE,CAAC"}

package/dist/RedisBlacklistDriver.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare class RedisBlacklistDriver implements BlacklistDriver {
+    #private;
+    constructor(client: RedisLikeClient, config?: RedisBlacklistConfig);
+    /**
+     * Blacklist a JTI until its natural expiry. Tokens already past `expiresAt`
+     * are skipped — there is nothing left to revoke.
+     */
+    add(jti: string, expiresAt: number): Promise<void>;
+    has(jti: string): Promise<boolean>;
+    /** No-op: Redis/KeyDB evicts expired keys on its own. */
+    cleanup(): Promise<void>;
+}
+//# sourceMappingURL=RedisBlacklistDriver.d.ts.map

package/dist/RedisBlacklistDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisBlacklistDriver.d.ts","sourceRoot":"","sources":["../src/RedisBlacklistDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC/B,GAAG,CACF,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,oBAAoB;IACpC,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,oBAAqB,YAAW,eAAe;;gBAI/C,MAAM,EAAE,eAAe,EAAE,MAAM,GAAE,oBAAyB;IAKtE;;;OAGG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxC,yDAAyD;IACnD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAK9B"}

package/dist/RedisBlacklistDriver.js

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+export class RedisBlacklistDriver {
+    #client;
+    #prefix;
+    constructor(client, config = {}) {
+        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, expiresAt) {
+        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) {
+        return (await this.#client.exists(this.#key(jti))) > 0;
+    }
+    /** No-op: Redis/KeyDB evicts expired keys on its own. */
+    async cleanup() { }
+    #key(jti) {
+        return `${this.#prefix}${jti}`;
+    }
+}
+//# sourceMappingURL=RedisBlacklistDriver.js.map

package/dist/RedisBlacklistDriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisBlacklistDriver.js","sourceRoot":"","sources":["../src/RedisBlacklistDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH,MAAM,OAAO,oBAAoB;IACvB,OAAO,CAAkB;IACzB,OAAO,CAAS;IAEzB,YAAY,MAAuB,EAAE,SAA+B,EAAE;QACrE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,IAAI,mBAAmB,CAAC;IACrD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,SAAiB;QACvC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QAC9D,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;YACrB,OAAO;QACR,CAAC;QACD,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACpB,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxD,CAAC;IAED,yDAAyD;IACzD,KAAK,CAAC,OAAO,KAAmB,CAAC;IAEjC,IAAI,CAAC,GAAW;QACf,OAAO,GAAG,IAAI,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC;IAChC,CAAC;CACD"}

package/dist/ResilientBlacklistDriver.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 } 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;
+}
+export declare class ResilientBlacklistDriver implements BlacklistDriver {
+    #private;
+    constructor(primary: BlacklistDriver, fallback?: BlacklistDriver, config?: ResilientBlacklistConfig);
+    add(jti: string, expiresAt: number): Promise<void>;
+    has(jti: string): Promise<boolean>;
+    cleanup(): Promise<void>;
+}
+//# sourceMappingURL=ResilientBlacklistDriver.d.ts.map

package/dist/ResilientBlacklistDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResilientBlacklistDriver.d.ts","sourceRoot":"","sources":["../src/ResilientBlacklistDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACN,KAAK,eAAe,EAEpB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;IAC9B,KAAK,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACxC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACnD;AASD,qBAAa,wBAAyB,YAAW,eAAe;;gBAM9D,OAAO,EAAE,eAAe,EACxB,QAAQ,GAAE,eAA6C,EACvD,MAAM,GAAE,wBAA6B;IAOhC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASlD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUlC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ9B"}

package/dist/ResilientBlacklistDriver.js

@@ -0,0 +1,61 @@
+/**
+ * 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 { MemoryBlacklistDriver, } from "./TokenBlacklist.js";
+function defaultOnDegrade({ op, error }) {
+    console.warn(`[warden] blacklist primary failed on ${op}; using in-memory fallback:`, error);
+}
+export class ResilientBlacklistDriver {
+    #primary;
+    #fallback;
+    #onDegrade;
+    constructor(primary, fallback = new MemoryBlacklistDriver(), config = {}) {
+        this.#primary = primary;
+        this.#fallback = fallback;
+        this.#onDegrade = config.onDegrade ?? defaultOnDegrade;
+    }
+    async add(jti, expiresAt) {
+        try {
+            await this.#primary.add(jti, expiresAt);
+        }
+        catch (error) {
+            this.#onDegrade({ op: "add", error });
+            await this.#fallback.add(jti, expiresAt);
+        }
+    }
+    async has(jti) {
+        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() {
+        try {
+            await this.#primary.cleanup();
+        }
+        catch (error) {
+            this.#onDegrade({ op: "cleanup", error });
+        }
+        await this.#fallback.cleanup();
+    }
+}
+//# sourceMappingURL=ResilientBlacklistDriver.js.map

package/dist/ResilientBlacklistDriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResilientBlacklistDriver.js","sourceRoot":"","sources":["../src/ResilientBlacklistDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAEN,qBAAqB,GACrB,MAAM,qBAAqB,CAAC;AAY7B,SAAS,gBAAgB,CAAC,EAAE,EAAE,EAAE,KAAK,EAAyB;IAC7D,OAAO,CAAC,IAAI,CACX,wCAAwC,EAAE,6BAA6B,EACvE,KAAK,CACL,CAAC;AACH,CAAC;AAED,MAAM,OAAO,wBAAwB;IAC3B,QAAQ,CAAkB;IAC1B,SAAS,CAAkB;IAC3B,UAAU,CAAyC;IAE5D,YACC,OAAwB,EACxB,WAA4B,IAAI,qBAAqB,EAAE,EACvD,SAAmC,EAAE;QAErC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,SAAS,IAAI,gBAAgB,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,SAAiB;QACvC,IAAI,CAAC;YACJ,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;YACtC,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC1C,CAAC;IACF,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACpB,IAAI,CAAC;YACJ,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;YACtC,wEAAwE;YACxE,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;IACF,CAAC;IAED,KAAK,CAAC,OAAO;QACZ,IAAI,CAAC;YACJ,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QAC/B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IAChC,CAAC;CACD"}

package/dist/WardenProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WardenProvider.d.ts","sourceRoot":"","sources":["../src/WardenProvider.ts"],"names":[],"mappings":"AAQA,UAAU,eAAe;IACxB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;CACjC;AAED,UAAU,iBAAiB;IAC1B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,iBAAiB,CAAC;CAC1B;AAED,MAAM,CAAC,OAAO,OAAO,cAAc;IACtB,SAAS,CAAC,GAAG,EAAE,gBAAgB;gBAArB,GAAG,EAAE,gBAAgB;IAE3C,QAAQ;IAuDF,IAAI;CAGV"}
+{"version":3,"file":"WardenProvider.d.ts","sourceRoot":"","sources":["../src/WardenProvider.ts"],"names":[],"mappings":"AASA,UAAU,eAAe;IACxB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;CACjC;AAED,UAAU,iBAAiB;IAC1B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,iBAAiB,CAAC;CAC1B;AAED,MAAM,CAAC,OAAO,OAAO,cAAc;IACtB,SAAS,CAAC,GAAG,EAAE,gBAAgB;gBAArB,GAAG,EAAE,gBAAgB;IAE3C,QAAQ;IAiEF,IAAI;CAGV"}

package/dist/WardenProvider.js

@@ -1,5 +1,6 @@
 import { AuthManager } from "./AuthManager.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";
@@ -53,6 +54,15 @@ export default class WardenProvider {
         // `container.resolve("auth")` threw and its admin auth gate
         // silently fell back to open-mode.
         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() {
         setAuth(this.app.container.resolve(AuthManager));

package/dist/WardenProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"WardenProvider.js","sourceRoot":"","sources":["../src/WardenProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAgB1D,MAAM,CAAC,OAAO,OAAO,cAAc;IACZ;IAAtB,YAAsB,GAAqB;QAArB,QAAG,GAAH,GAAG,CAAkB;IAAG,CAAC;IAE/C,QAAQ;QACP,4EAA4E;QAC5E,sEAAsE;QACtE,8DAA8D;QAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAe,MAAM,CAAC,CAAC;QAEzD,qEAAqE;QACrE,oEAAoE;QACpE,mEAAmE;QACnE,kEAAkE;QAClE,qEAAqE;QACrE,mBAAmB;QACnB,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC;YAClB,MAAM,IAAI,WAAW,CACpB,uBAAuB,EACvB,8JAA8J,CAC9J,CAAC;QACH,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QAErD,uEAAuE;QACvE,yEAAyE;QACzE,uEAAuE;QACvE,uEAAuE;QACvE,sEAAsE;QACtE,iEAAiE;QACjE,oCAAoC;QACpC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,IAAI,iBAAiB,EAAE,CAAC;QACpE,MAAM,cAAc,GAAG,IAAI,cAAc,CAAC,WAAW,CAAC,CAAC;QACvD,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,CAAC;QACnE,IAAI,WAAW,YAAY,iBAAiB,EAAE,CAAC;YAC9C,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC;QACpE,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,WAAW,EAAE,GAAG,EAAE;YAC9C,MAAM,UAAU,GAAgC,EAAE,GAAG,EAAE,CAAC;YACxD,OAAO,IAAI,WAAW,CAAC;gBACtB,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,KAAK;gBAChD,UAAU;gBACV,MAAM,EAAE,cAAc;aACtB,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;QACH,oEAAoE;QACpE,mEAAmE;QACnE,4DAA4D;QAC5D,8DAA8D;QAC9D,4DAA4D;QAC5D,mCAAmC;QACnC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,CACzC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,CACvC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI;QACT,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,WAAW,CAAgB,CAAC,CAAC;IACjE,CAAC;CACD"}
+{"version":3,"file":"WardenProvider.js","sourceRoot":"","sources":["../src/WardenProvider.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -15,6 +15,7 @@
  *   })
  */
 import type { UserPayload } from "./AuthManager.js";
+import type { MfaManager } from "./mfa/MfaManager.js";
 import type { RightsStore } from "./rights/types.js";
 export interface JwtConfig {
     secret: string;
@@ -36,6 +37,14 @@ export interface WardenConfig {
     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. */
 export declare function defineConfig(config: WardenConfig): WardenConfig;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,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;CACjC;AAED,MAAM,WAAW,YAAY;IAC5B,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kCAAkC;IAClC,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;;OAKG;IACH,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,WAAW,CAAA;KAAE,CAAC;CACjC;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE/D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,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;CACjC;AAED,MAAM,WAAW,YAAY;IAC5B,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kCAAkC;IAClC,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;;OAKG;IACH,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,WAAW,CAAA;KAAE,CAAC;IACjC;;;;OAIG;IACH,GAAG,CAAC,EAAE;QAAE,OAAO,EAAE,UAAU,CAAA;KAAE,CAAC;CAC9B;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE/D"}

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA6BH,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,MAAoB;IAChD,OAAO,MAAM,CAAC;AACf,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAoCH,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,MAAoB;IAChD,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/index.d.ts

@@ -20,9 +20,23 @@ export { GitHubDriver } from "./firstcontact/drivers/GitHubDriver.js";
 export { GoogleDriver } from "./firstcontact/drivers/GoogleDriver.js";
 export { FirstContactManager } from "./firstcontact/FirstContactManager.js";
 export type { FirstContactDriver, OAuthConfig, OAuthToken, OAuthUser, } from "./firstcontact/types.js";
-export { Guard, getGuardMetadata, getPermissionMetadata, getRoleMetadata, Permission, Role, } from "./Guard.js";
+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, } from "./RefreshTokenStore.js";
 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 { EffectivePermissions, RightsStore, Scope, } from "./rights/types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACX,UAAU,EACV,UAAU,EACV,YAAY,EACZ,WAAW,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClE,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;AACjC,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,YAAY,EACX,OAAO,EACP,cAAc,EACd,kBAAkB,EAClB,cAAc,GACd,MAAM,oBAAoB,CAAC;AAC5B,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;AAC5E,YAAY,EACX,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,SAAS,GACT,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACN,KAAK,EACL,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,IAAI,GACJ,MAAM,YAAY,CAAC;AACpB,YAAY,EACX,kBAAkB,EAClB,kBAAkB,GAClB,MAAM,wBAAwB,CAAC;AAChC,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;AAC5D,YAAY,EACX,oBAAoB,EACpB,WAAW,EACX,KAAK,GACL,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,YAAY,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC7E,YAAY,EACX,YAAY,EACZ,qBAAqB,GACrB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

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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"}