@astram/guard 0.7.0 → 0.8.0

package/dist/auth/mfa-step-up.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CredentialMfaStepUp = void 0;
+exports.credentialFingerprint = credentialFingerprint;
+exports.challengeMatches = challengeMatches;
+/**
+ * The MFA **step-up** — `/auth/mfa` verifies ONLY the second factor, against the
+ * principal whose password step already passed (security hardening M6, plan D8).
+ *
+ * WHY HERE (no core change): core's `Authenticator.authenticate(hint, credentials)` always
+ * verifies the password first, so completing MFA through it required holding the
+ * plaintext password between the two requests. Instead, `/auth/login` records the password
+ * step's success as a {@link PendingMfaChallenge} (principal + hint + credential
+ * fingerprint), and this class finishes the login from that challenge using only existing
+ * core ports: the {@link CredentialResolver} (re-resolve), the registered
+ * {@link FactorVerifier}s (the same `OrTotpVerifier` the authenticator uses, replay guard
+ * included) and the {@link IdentityBroker} (the principal is minted exactly as the
+ * authenticator mints it — tenant binding + root allowlist, never fabricated here).
+ *
+ * The verification mirrors the authenticator's factor loop, fail-closed:
+ *  - unknown hint, a different principal, or a changed credential (fingerprint) → rejected;
+ *  - no required factor any more (device removed) → rejected (never a password-less login
+ *    through the MFA endpoint — the user logs in again);
+ *  - every required factor must have a registered verifier, be the presented factor, and
+ *    verify to a STRICT `true`;
+ *  - any resolver / verifier / broker throw → `unavailable` (503, never counted as a guess).
+ */
+const node_crypto_1 = require("node:crypto");
+/** SHA-256 of the stored credential hash — binds a challenge to the credential state. */
+function credentialFingerprint(resolved) {
+    return (0, node_crypto_1.createHash)('sha256')
+        .update(String(resolved.passwordHash ?? ''))
+        .digest('hex');
+}
+/** The principal id a resolved credential carries, or `null`. */
+function principalIdOf(resolved) {
+    const id = resolved.claims?.id;
+    return typeof id === 'string' && id !== '' ? id : null;
+}
+/**
+ * `true` iff `resolved` is still the credential the challenge was issued for: same
+ * principal, same stored credential hash. Shared by the TOTP step-up and the
+ * recovery-code branch.
+ */
+function challengeMatches(resolved, challenge) {
+    return (principalIdOf(resolved) === challenge.principalId &&
+        credentialFingerprint(resolved) === challenge.credentialFingerprint);
+}
+const REJECTED = Object.freeze({ outcome: 'rejected' });
+const UNAVAILABLE = Object.freeze({ outcome: 'unavailable' });
+/** The framework-default {@link MfaStepUp} over the injected core ports. */
+class CredentialMfaStepUp {
+    resolver;
+    broker;
+    verifiers = new Map();
+    constructor(resolver, factorVerifiers, broker) {
+        this.resolver = resolver;
+        this.broker = broker;
+        for (const v of factorVerifiers) {
+            if (this.verifiers.has(v.factor)) {
+                throw new Error(`CredentialMfaStepUp: duplicate verifier for factor "${v.factor}"`);
+            }
+            this.verifiers.set(v.factor, v);
+        }
+    }
+    async verify(challenge, credential) {
+        let resolved;
+        try {
+            resolved = await this.resolver.resolve(challenge.identityHint);
+        }
+        catch {
+            return UNAVAILABLE;
+        }
+        if (resolved === null || resolved === undefined)
+            return REJECTED;
+        if (!challengeMatches(resolved, challenge))
+            return REJECTED;
+        const required = resolved.requiredFactors ?? [];
+        if (required.length === 0)
+            return REJECTED;
+        for (const req of required) {
+            const verifier = this.verifiers.get(req.factor);
+            if (verifier === undefined || credential?.factor !== req.factor)
+                return REJECTED;
+            let satisfied;
+            try {
+                satisfied = (await verifier.verify(credential, req.secret))?.satisfied;
+            }
+            catch {
+                return UNAVAILABLE;
+            }
+            if (satisfied !== true)
+                return REJECTED;
+        }
+        try {
+            const principal = await this.broker.normalize({
+                source: 'internal',
+                claims: resolved.claims,
+            });
+            return principal.id === challenge.principalId
+                ? { outcome: 'authenticated', principal }
+                : REJECTED;
+        }
+        catch {
+            return UNAVAILABLE;
+        }
+    }
+}
+exports.CredentialMfaStepUp = CredentialMfaStepUp;

package/dist/auth/pending-mfa-store.d.ts

@@ -1,72 +1,70 @@
 /**
- * Phase 0b Auth-surface — the **pending-MFA challenge store** backing
- * `/auth/login` (mfa branch) → `/auth/mfa`.
+ * The **pending-MFA challenge store** backing `/auth/login` (mfa branch) → `/auth/mfa`
+ * (security hardening M6, plan decision D8).
  *
- * ── WHY THIS EXISTS ──────────────────────────────────────────────────────────
- * The core `Authenticator` has NO separate "verify one more factor" entry point:
- * `authenticate(hint, credentials[])` is the ONLY seam (see
- * `../../core/authentication/authenticator.ts`). To COMPLETE an MFA login the
- * controller must RE-CALL `authenticate(hint, [password, totp])` with BOTH the
- * original password AND the freshly-presented TOTP code. So between the login that
- * returned `mfa_required` and the `/auth/mfa` that finishes it, the server must
- * hold the ORIGINAL `identityHint` + `password` (the "pending authentication").
+ * ── WHAT A CHALLENGE HOLDS (never the password) ─────────────────────────────────
+ * When the password step succeeds but a second factor is outstanding, the controller
+ * records THAT SUCCESS as a {@link PendingMfaChallenge}: the resolved principal id, the
+ * typed identity hint, and a fingerprint (SHA-256) of the stored credential hash the
+ * password was verified against. `/auth/mfa` then verifies ONLY the second factor against
+ * that principal (see `mfa-step-up.ts`); it never re-runs the password. The plaintext
+ * password is never stored — not in memory, not in Redis. A credential change between the
+ * two steps (password reset) changes the fingerprint and voids the challenge.
  *
- * ── THE NON-FORGEABILITY DESIGN (the security decision) ──────────────────────
- * The `challengeToken` handed to the client is a **cryptographically-random opaque
- * handle** (`node:crypto.randomBytes`), NOT a signed/encrypted blob carrying the
- * credentials. The pending `{ identityHint, password }` state lives ONLY
- * server-side, keyed by that random token. Consequences:
- *   • FORGERY-PROOF BY CONSTRUCTION — a hand-crafted token maps to no entry, so it
- *     is rejected. There is no signature to strip, no payload to tamper with, and
- *     the client is never given the credentials (even encrypted) to hold.
- *   • SHORT-LIVED — each entry has an expiry (default 5 min). An expired handle is
- *     treated as unknown (same generic 401 as a forged one — anti-enumeration).
- *   • SINGLE-USE — `consume()` DELETES the entry as it reads it, so a
- *     challengeToken cannot be replayed to brute-force TOTP codes indefinitely on
- *     one handle. (A caller that fails still burns the handle → must re-login. This
- *     is the built-in anti-brute-force cooldown for THIS layer; the resolver/engine
- *     add no separate one.)
- *   • NEVER LOGGED — the stored password + the token are never logged.
+ * ── THE HANDLE ── the `challengeToken` returned to the client is a cryptographically
+ * random opaque handle (256-bit, hex). The state lives server-side under
+ * `sha256(token)`; a hand-crafted token maps to nothing (forgery-proof by construction).
+ * SHORT-LIVED (default 5 min) and SINGLE-USE (`consume` deletes as it reads, so a failed
+ * attempt burns the handle and forces a fresh login).
  *
- * TRADE-OFF (documented): server-side state is process-local (an in-memory `Map`).
- * For the single-instance framework scope of Phase 0b this is correct and the
- * safest option (the password never reaches the client). A multi-instance
- * deployment would swap this `Map` for a shared TTL store (Redis) behind the SAME
- * interface — the controller depends only on `store/consume`, not on the backing.
- *
- * ADR-0003 note: this file DOES use `node:crypto` (guard owns node builtins; core
- * does not). It holds NO framework/HTTP coupling — a plain injectable class.
+ * ── TWO BACKINGS, ONE INTERFACE ─────────────────────────────────────────────────
+ *  - {@link RedisPendingMfaStore} — the `AuthModule` default: `SET … PX` + `GETDEL`, so
+ *    the MFA step works on ANY instance (PM2 cluster, blue/green). A Redis error
+ *    propagates; the controller answers a retryable 503 (never a challenge it cannot keep).
+ *  - {@link PendingMfaStore} — the in-process base (single-instance / tests).
+ * The controller depends on the {@link PendingMfaStore} class token only.
  */
+import type Redis from 'ioredis';
+/** What the password step proved — everything `/auth/mfa` needs, and nothing secret. */
+export interface PendingMfaChallenge {
+    /** The principal the password was verified for (from the resolved credential). */
+    readonly principalId: string;
+    /** The hint exactly as typed (the step-up re-resolves the credential through it). */
+    readonly identityHint: string;
+    /** SHA-256 of the stored credential hash at password time (credential-change guard). */
+    readonly credentialFingerprint: string;
+}
 /**
- * A minimal server-side, single-use, TTL'd store of pending MFA challenges.
- * Injected into the auth controller. Deliberately depends on nothing framework-y.
+ * The in-process challenge store (single instance / tests) and the class token the
+ * controller injects. {@link RedisPendingMfaStore} overrides both methods.
  */
 export declare class PendingMfaStore {
-    private readonly ttlMs;
+    protected readonly ttlMs: number;
     /** Clock (UTC epoch ms) — injectable for deterministic tests. */
     private readonly nowMs;
     private readonly pending;
     constructor(ttlMs?: number, 
     /** Clock (UTC epoch ms) — injectable for deterministic tests. */
     nowMs?: () => number);
+    /** Record a passed password step; returns the opaque handle the client re-presents. */
+    store(challenge: PendingMfaChallenge): Promise<string>;
     /**
-     * Store a pending authentication and return the opaque, unguessable
-     * `challengeToken` the client re-presents to `/auth/mfa`. The token carries NO
-     * information about the user — it is a random handle only.
-     */
-    store(identityHint: string, password: string): string;
-    /**
-     * Look up + SINGLE-USE consume a pending challenge. Returns the held credentials
-     * for a live, known token; `null` for an unknown, forged, or expired token (the
-     * controller maps `null` to the SAME generic 401 as a wrong code — no leak of
-     * WHY it failed). The entry is DELETED whether or not it was live, so a handle
-     * is never replayable.
+     * SINGLE-USE consume: the challenge for a live, known handle, else `null` (unknown,
+     * forged, expired). The entry is deleted whether or not it was live.
      */
-    consume(token: string): {
-        identityHint: string;
-        password: string;
-    } | null;
+    consume(token: string): Promise<PendingMfaChallenge | null>;
     /** Drop expired entries so the map cannot grow unbounded from abandoned logins. */
     private sweep;
 }
+/**
+ * The Redis-backed challenge store — the `AuthModule` default (M6). `SET key value PX ttl`
+ * on store, `GETDEL` on consume (atomic single use across instances). Redis errors
+ * propagate to the controller (→ 503).
+ */
+export declare class RedisPendingMfaStore extends PendingMfaStore {
+    private readonly redis;
+    constructor(redis: Pick<Redis, 'set' | 'getdel'>, ttlMs?: number);
+    store(challenge: PendingMfaChallenge): Promise<string>;
+    consume(token: string): Promise<PendingMfaChallenge | null>;
+}
 //# sourceMappingURL=pending-mfa-store.d.ts.map

package/dist/auth/pending-mfa-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pending-mfa-store.d.ts","sourceRoot":"","sources":["../../src/auth/pending-mfa-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAmBH;;;GAGG;AACH,qBAAa,eAAe;IAIxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK;IALxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;gBAGxC,KAAK,GAAE,MAAuB;IAC/C,iEAAiE;IAChD,KAAK,GAAE,MAAM,MAAiB;IAGjD;;;;OAIG;IACH,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAWrD;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAWzE,mFAAmF;IACnF,OAAO,CAAC,KAAK;CAMd"}
+{"version":3,"file":"pending-mfa-store.d.ts","sourceRoot":"","sources":["../../src/auth/pending-mfa-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC,wFAAwF;AACxF,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,wFAAwF;IACxF,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AA2CD;;;GAGG;AACH,qBAAa,eAAe;IAIxB,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM;IAChC,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK;IALxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;gBAGrC,KAAK,GAAE,MAAuB;IACjD,iEAAiE;IAChD,KAAK,GAAE,MAAM,MAAiB;IAGjD,uFAAuF;IACjF,KAAK,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAU5D;;;OAGG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAUjE,mFAAmF;IACnF,OAAO,CAAC,KAAK;CAMd;AAKD;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,eAAe;IAErD,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC,EACrD,KAAK,GAAE,MAAuB;IAKjB,KAAK,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAWtD,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;CAU3E"}

package/dist/auth/pending-mfa-store.js

@@ -1,53 +1,66 @@
 "use strict";
 /**
- * Phase 0b Auth-surface — the **pending-MFA challenge store** backing
- * `/auth/login` (mfa branch) → `/auth/mfa`.
+ * The **pending-MFA challenge store** backing `/auth/login` (mfa branch) → `/auth/mfa`
+ * (security hardening M6, plan decision D8).
  *
- * ── WHY THIS EXISTS ──────────────────────────────────────────────────────────
- * The core `Authenticator` has NO separate "verify one more factor" entry point:
- * `authenticate(hint, credentials[])` is the ONLY seam (see
- * `../../core/authentication/authenticator.ts`). To COMPLETE an MFA login the
- * controller must RE-CALL `authenticate(hint, [password, totp])` with BOTH the
- * original password AND the freshly-presented TOTP code. So between the login that
- * returned `mfa_required` and the `/auth/mfa` that finishes it, the server must
- * hold the ORIGINAL `identityHint` + `password` (the "pending authentication").
+ * ── WHAT A CHALLENGE HOLDS (never the password) ─────────────────────────────────
+ * When the password step succeeds but a second factor is outstanding, the controller
+ * records THAT SUCCESS as a {@link PendingMfaChallenge}: the resolved principal id, the
+ * typed identity hint, and a fingerprint (SHA-256) of the stored credential hash the
+ * password was verified against. `/auth/mfa` then verifies ONLY the second factor against
+ * that principal (see `mfa-step-up.ts`); it never re-runs the password. The plaintext
+ * password is never stored — not in memory, not in Redis. A credential change between the
+ * two steps (password reset) changes the fingerprint and voids the challenge.
  *
- * ── THE NON-FORGEABILITY DESIGN (the security decision) ──────────────────────
- * The `challengeToken` handed to the client is a **cryptographically-random opaque
- * handle** (`node:crypto.randomBytes`), NOT a signed/encrypted blob carrying the
- * credentials. The pending `{ identityHint, password }` state lives ONLY
- * server-side, keyed by that random token. Consequences:
- *   • FORGERY-PROOF BY CONSTRUCTION — a hand-crafted token maps to no entry, so it
- *     is rejected. There is no signature to strip, no payload to tamper with, and
- *     the client is never given the credentials (even encrypted) to hold.
- *   • SHORT-LIVED — each entry has an expiry (default 5 min). An expired handle is
- *     treated as unknown (same generic 401 as a forged one — anti-enumeration).
- *   • SINGLE-USE — `consume()` DELETES the entry as it reads it, so a
- *     challengeToken cannot be replayed to brute-force TOTP codes indefinitely on
- *     one handle. (A caller that fails still burns the handle → must re-login. This
- *     is the built-in anti-brute-force cooldown for THIS layer; the resolver/engine
- *     add no separate one.)
- *   • NEVER LOGGED — the stored password + the token are never logged.
+ * ── THE HANDLE ── the `challengeToken` returned to the client is a cryptographically
+ * random opaque handle (256-bit, hex). The state lives server-side under
+ * `sha256(token)`; a hand-crafted token maps to nothing (forgery-proof by construction).
+ * SHORT-LIVED (default 5 min) and SINGLE-USE (`consume` deletes as it reads, so a failed
+ * attempt burns the handle and forces a fresh login).
  *
- * TRADE-OFF (documented): server-side state is process-local (an in-memory `Map`).
- * For the single-instance framework scope of Phase 0b this is correct and the
- * safest option (the password never reaches the client). A multi-instance
- * deployment would swap this `Map` for a shared TTL store (Redis) behind the SAME
- * interface — the controller depends only on `store/consume`, not on the backing.
- *
- * ADR-0003 note: this file DOES use `node:crypto` (guard owns node builtins; core
- * does not). It holds NO framework/HTTP coupling — a plain injectable class.
+ * ── TWO BACKINGS, ONE INTERFACE ─────────────────────────────────────────────────
+ *  - {@link RedisPendingMfaStore} — the `AuthModule` default: `SET … PX` + `GETDEL`, so
+ *    the MFA step works on ANY instance (PM2 cluster, blue/green). A Redis error
+ *    propagates; the controller answers a retryable 503 (never a challenge it cannot keep).
+ *  - {@link PendingMfaStore} — the in-process base (single-instance / tests).
+ * The controller depends on the {@link PendingMfaStore} class token only.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PendingMfaStore = void 0;
+exports.RedisPendingMfaStore = exports.PendingMfaStore = void 0;
 const node_crypto_1 = require("node:crypto");
 /** Default challenge lifetime — short, per spec §2 ("a short TTL"). */
 const DEFAULT_TTL_MS = 5 * 60 * 1000;
-/** How many random bytes back a challenge handle (256-bit, url-safe hex → 64 chars). */
+/** How many random bytes back a challenge handle (256-bit, hex → 64 chars). */
 const TOKEN_BYTES = 32;
+/** Mint a fresh opaque handle. */
+function mintToken() {
+    return (0, node_crypto_1.randomBytes)(TOKEN_BYTES).toString('hex');
+}
+/** The storage key for a handle: its SHA-256 (the raw handle is never a key name). */
+function tokenDigest(token) {
+    return (0, node_crypto_1.createHash)('sha256').update(token).digest('hex');
+}
+/** Structurally validate a stored challenge (an untrusted payload). */
+function parseChallenge(value) {
+    if (value === null || typeof value !== 'object')
+        return null;
+    const v = value;
+    if (typeof v.principalId !== 'string' ||
+        v.principalId === '' ||
+        typeof v.identityHint !== 'string' ||
+        typeof v.credentialFingerprint !== 'string' ||
+        v.credentialFingerprint === '') {
+        return null;
+    }
+    return {
+        principalId: v.principalId,
+        identityHint: v.identityHint,
+        credentialFingerprint: v.credentialFingerprint,
+    };
+}
 /**
- * A minimal server-side, single-use, TTL'd store of pending MFA challenges.
- * Injected into the auth controller. Deliberately depends on nothing framework-y.
+ * The in-process challenge store (single instance / tests) and the class token the
+ * controller injects. {@link RedisPendingMfaStore} overrides both methods.
  */
 class PendingMfaStore {
     ttlMs;
@@ -59,48 +72,77 @@ class PendingMfaStore {
         this.ttlMs = ttlMs;
         this.nowMs = nowMs;
     }
-    /**
-     * Store a pending authentication and return the opaque, unguessable
-     * `challengeToken` the client re-presents to `/auth/mfa`. The token carries NO
-     * information about the user — it is a random handle only.
-     */
-    store(identityHint, password) {
+    /** Record a passed password step; returns the opaque handle the client re-presents. */
+    async store(challenge) {
         this.sweep();
-        const token = (0, node_crypto_1.randomBytes)(TOKEN_BYTES).toString('hex');
-        this.pending.set(token, {
-            identityHint,
-            password,
+        const token = mintToken();
+        this.pending.set(tokenDigest(token), {
+            challenge: { ...challenge },
             expiresAtMs: this.nowMs() + this.ttlMs,
         });
         return token;
     }
     /**
-     * Look up + SINGLE-USE consume a pending challenge. Returns the held credentials
-     * for a live, known token; `null` for an unknown, forged, or expired token (the
-     * controller maps `null` to the SAME generic 401 as a wrong code — no leak of
-     * WHY it failed). The entry is DELETED whether or not it was live, so a handle
-     * is never replayable.
+     * SINGLE-USE consume: the challenge for a live, known handle, else `null` (unknown,
+     * forged, expired). The entry is deleted whether or not it was live.
      */
-    consume(token) {
+    async consume(token) {
         if (typeof token !== 'string' || token.length === 0)
             return null;
-        const entry = this.pending.get(token);
-        // Single-use: remove on read regardless of validity (a spent/expired handle
-        // can never be retried → forces a fresh login, the anti-brute-force cooldown).
-        this.pending.delete(token);
+        const key = tokenDigest(token);
+        const entry = this.pending.get(key);
+        this.pending.delete(key);
         if (entry === undefined)
             return null;
         if (this.nowMs() >= entry.expiresAtMs)
             return null;
-        return { identityHint: entry.identityHint, password: entry.password };
+        return { ...entry.challenge };
     }
     /** Drop expired entries so the map cannot grow unbounded from abandoned logins. */
     sweep() {
         const now = this.nowMs();
-        for (const [token, entry] of this.pending) {
+        for (const [key, entry] of this.pending) {
             if (now >= entry.expiresAtMs)
-                this.pending.delete(token);
+                this.pending.delete(key);
         }
     }
 }
 exports.PendingMfaStore = PendingMfaStore;
+/** Redis key prefix for pending challenges. */
+const REDIS_PREFIX = 'shield:mfa:challenge:';
+/**
+ * The Redis-backed challenge store — the `AuthModule` default (M6). `SET key value PX ttl`
+ * on store, `GETDEL` on consume (atomic single use across instances). Redis errors
+ * propagate to the controller (→ 503).
+ */
+class RedisPendingMfaStore extends PendingMfaStore {
+    redis;
+    constructor(redis, ttlMs = DEFAULT_TTL_MS) {
+        super(ttlMs);
+        this.redis = redis;
+    }
+    async store(challenge) {
+        const token = mintToken();
+        const value = JSON.stringify({
+            principalId: challenge.principalId,
+            identityHint: challenge.identityHint,
+            credentialFingerprint: challenge.credentialFingerprint,
+        });
+        await this.redis.set(`${REDIS_PREFIX}${tokenDigest(token)}`, value, 'PX', this.ttlMs);
+        return token;
+    }
+    async consume(token) {
+        if (typeof token !== 'string' || token.length === 0)
+            return null;
+        const raw = await this.redis.getdel(`${REDIS_PREFIX}${tokenDigest(token)}`);
+        if (raw === null)
+            return null;
+        try {
+            return parseChallenge(JSON.parse(raw));
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.RedisPendingMfaStore = RedisPendingMfaStore;

package/dist/auth/ports/session-facts-projector.d.ts

@@ -40,5 +40,10 @@ export interface SessionFactsProjector {
      * authority uses.
      */
     project(principalId: string, tenantId: string): Promise<CoarseGrants | null>;
+    /**
+     * OPTIONAL (ADR-0035): `false` ⇒ treat this projector as absent for now (the framework's
+     * deferred default before its facts port is attached). Omitted ⇒ always active.
+     */
+    isActive?(): boolean;
 }
 //# sourceMappingURL=session-facts-projector.d.ts.map

package/dist/auth/ports/session-facts-projector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-facts-projector.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/session-facts-projector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CAC9E"}
+{"version":3,"file":"session-facts-projector.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/session-facts-projector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC7E;;;OAGG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC;CACtB"}

package/dist/auth/rate-limit/canonical-hint.d.ts

@@ -0,0 +1,24 @@
+/** The canonical identity hint (`NFKC → trim → lowercase`) — fallback-key material only. */
+export declare function canonicalHint(hint: string): string;
+/** `sha256(canonicalHint(hint))` as hex — the PII-free unknown-account key component. */
+export declare function hintKeyDigest(hint: string): string;
+/**
+ * The per-account password-login limiter key: `login:pid:<principalId>` when the store
+ * resolved an account, else `login:<sha256(canonical hint)>`.
+ */
+export declare function loginHintKey(hint: string, principalId?: string | null): string;
+/**
+ * The per-account forgot-password limiter key: `forgot:pid:<principalId>` when resolved,
+ * else `forgot:<sha256(canonical hint)>`.
+ */
+export declare function forgotHintKey(hint: string, principalId?: string | null): string;
+/**
+ * The per-client-IP password-login FAILURE limiter key: `login:ip:<ip>`. A blank ip
+ * (non-standard adapter/harness) gets its own sentinel bucket, never a shared one.
+ */
+export declare function loginIpKey(ip: string | undefined): string;
+/** The principal id a resolved credential carries (`claims.id`), or `null`. */
+export declare function principalIdOf(resolved: {
+    claims?: unknown;
+} | null | undefined): string | null;
+//# sourceMappingURL=canonical-hint.d.ts.map

package/dist/auth/rate-limit/canonical-hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-hint.d.ts","sourceRoot":"","sources":["../../../src/auth/rate-limit/canonical-hint.ts"],"names":[],"mappings":"AAsBA,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE9E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE/E;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEzD;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,QAAQ,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAG9F"}

package/dist/auth/rate-limit/canonical-hint.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalHint = canonicalHint;
+exports.hintKeyDigest = hintKeyDigest;
+exports.loginHintKey = loginHintKey;
+exports.forgotHintKey = forgotHintKey;
+exports.loginIpKey = loginIpKey;
+exports.principalIdOf = principalIdOf;
+/**
+ * PII-free limiter keys for the login / forgot-password budgets (security hardening #5,
+ * review F1/F5).
+ *
+ * WHY per ACCOUNT: the credential lookup runs `WHERE ic_identity_hint = ?` on a
+ * `utf8mb4_unicode_ci` column, which is case-, accent-, ignorable-character- and
+ * trailing-space-insensitive. `Alice@x`, `alicé@x`, `ali<ZWSP>ce@x` and `alice@x  ` all
+ * resolve to the SAME row, and no client-side normalisation reproduces that collation.
+ * So the per-hint budget is keyed on the account the store resolved
+ * (`login:pid:<principalId>` / `forgot:pid:<principalId>`): every spelling the DB maps
+ * to one account shares one counter.
+ *
+ * When NO account resolves, the key falls back to the canonical-hint hash
+ * (`login:<sha256(NFKC → trim → lowercase)>`): no account means nothing to take over, but
+ * enumeration is still rate-limited. The canonical form is used ONLY for this fallback
+ * key — the lookup itself always receives the RAW typed hint so the DB collation decides
+ * equality (F5).
+ *
+ * No email/username is ever written into a Redis key name (no PII in the hot tier).
+ */
+const node_crypto_1 = require("node:crypto");
+/** The canonical identity hint (`NFKC → trim → lowercase`) — fallback-key material only. */
+function canonicalHint(hint) {
+    return hint.normalize('NFKC').trim().toLowerCase();
+}
+/** `sha256(canonicalHint(hint))` as hex — the PII-free unknown-account key component. */
+function hintKeyDigest(hint) {
+    return (0, node_crypto_1.createHash)('sha256').update(canonicalHint(hint)).digest('hex');
+}
+/**
+ * The per-account password-login limiter key: `login:pid:<principalId>` when the store
+ * resolved an account, else `login:<sha256(canonical hint)>`.
+ */
+function loginHintKey(hint, principalId) {
+    return principalId ? `login:pid:${principalId}` : `login:${hintKeyDigest(hint)}`;
+}
+/**
+ * The per-account forgot-password limiter key: `forgot:pid:<principalId>` when resolved,
+ * else `forgot:<sha256(canonical hint)>`.
+ */
+function forgotHintKey(hint, principalId) {
+    return principalId ? `forgot:pid:${principalId}` : `forgot:${hintKeyDigest(hint)}`;
+}
+/**
+ * The per-client-IP password-login FAILURE limiter key: `login:ip:<ip>`. A blank ip
+ * (non-standard adapter/harness) gets its own sentinel bucket, never a shared one.
+ */
+function loginIpKey(ip) {
+    return `login:ip:${ip || 'unknown-ip'}`;
+}
+/** The principal id a resolved credential carries (`claims.id`), or `null`. */
+function principalIdOf(resolved) {
+    const claims = resolved?.claims;
+    return typeof claims?.id === 'string' && claims.id !== '' ? claims.id : null;
+}

package/dist/auth/rate-limit/trust-proxy-check.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Boot-time `trust proxy` decision for ALL per-IP limiters (security hardening #5,
+ * review F2/F3): the login failure limiter (`login:ip:`), the forgot-password request cap
+ * (`forgot:ip:`) and the reset-password abuse cap (`reset:ip:`).
+ *
+ * Each keys on `req.ip`. Behind a reverse proxy (Traefik in the Astram stack) `req.ip` is
+ * the PROXY's address unless the app sets `app.set('trust proxy', <hop count>)`. With it
+ * unset every client shares one bucket, so a per-IP limit becomes an unauthenticated
+ * global DoS: 50 failed logins lock ALL logins, 10 bad reset tokens 429 EVERY reset, 5
+ * forgot requests silently drop EVERY reset email. Setting it too high lets a client spoof
+ * `X-Forwarded-For`, so the framework cannot pick a value.
+ *
+ * Decision (made ONCE at bootstrap, never per request):
+ *   - Express `trust proxy` explicitly configured (`app.get('trust proxy') !== false`, so an
+ *     explicit `0` = "no proxy" counts) → {@link TrustProxyBootCheck.perIpLimitingEnabled}
+ *     is `true` and AuthController enforces the per-IP limiters;
+ *   - otherwise (unset, a non-Express adapter, or before bootstrap) → `false`: every per-IP
+ *     limiter is OFF and one boot warning says so. The per-account limiters (login,
+ *     forgot-password) and the recovery-code limiter are unaffected.
+ *
+ * Runs on `onApplicationBootstrap` (inside `app.init()` / `app.listen()`), i.e. after a
+ * typical `main.ts` has called `app.set('trust proxy', …)` on the created app.
+ */
+import { type OnApplicationBootstrap } from '@nestjs/common';
+import { HttpAdapterHost } from '@nestjs/core';
+/**
+ * `true` when the Express app has an explicit `trust proxy` value. Express's default is
+ * `false`; an explicit `0`/`'loopback'`/hop count/subnet list counts as configured.
+ * Returns `null` when the instance is not Express-like (cannot tell).
+ */
+export declare function isTrustProxyConfigured(instance: unknown): boolean | null;
+export declare const TRUST_PROXY_WARNING: string;
+export declare class TrustProxyBootCheck implements OnApplicationBootstrap {
+    private readonly adapterHost?;
+    private static readonly logger;
+    private enabled;
+    constructor(adapterHost?: HttpAdapterHost | undefined);
+    /**
+     * Whether AuthController enforces the per-IP limiters (login failures, forgot-password,
+     * reset-password). `false` until bootstrap has confirmed an explicit Express
+     * `trust proxy` (fail-safe: never a global lockout from a shared proxy IP).
+     */
+    get perIpLimitingEnabled(): boolean;
+    onApplicationBootstrap(): void;
+}
+//# sourceMappingURL=trust-proxy-check.d.ts.map

package/dist/auth/rate-limit/trust-proxy-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-proxy-check.d.ts","sourceRoot":"","sources":["../../../src/auth/rate-limit/trust-proxy-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAgC,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAO/C;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAOxE;AAED,eAAO,MAAM,mBAAmB,QAMG,CAAC;AAEpC,qBACa,mBAAoB,YAAW,sBAAsB;IAIxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAHrD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAA4B;IAC1D,OAAO,CAAC,OAAO,CAAS;gBAEiB,WAAW,CAAC,EAAE,eAAe,YAAA;IAEtE;;;;OAIG;IACH,IAAI,oBAAoB,IAAI,OAAO,CAElC;IAED,sBAAsB,IAAI,IAAI;CAQ/B"}