@astram/guard 0.6.0 → 0.8.0

package/dist/auth/auth.controller.js

@@ -15,10 +15,13 @@
  * ── OUTCOME → HTTP STATUS MAP (the security contract) ────────────────────────
  *   login authenticated        → 200  SessionSuccess { session(no-secret), tokens }
  *   login mfa_required          → 200  MfaChallengeResponse { mfaRequired, challengeToken }
+ *                                      (a Redis challenge: principal + hint + credential
+ *                                      fingerprint, never the password — M6)
  *   login invalid_credentials   → 401  GENERIC   ← unknown-user AND wrong-password IDENTICAL
  *   login auth_unavailable      → 503  RETRYABLE ← transient blip is NOT a credential deny
  *   mfa   success               → 200  SessionSuccess
  *   mfa   wrong/expired/forged   → 401  GENERIC   ← indistinguishable from a bad code
+ *   mfa   TOTP step locked (#9) → 401  GENERIC   (5 wrong codes / 15 min per account)
  *   mfa   auth_unavailable      → 503  RETRYABLE
  *   refresh ok                  → 200  SessionSuccess (new tokens, rotated session)
  *   refresh reuse/invalid       → 401  GENERIC   session_rejected (lineage-kill is the engine's)
@@ -69,8 +72,15 @@ const node_crypto_1 = require("node:crypto");
 const common_2 = require("@nestjs/common");
 const classification_decorator_js_1 = require("../enforcement/classification.decorator.js");
 const tokens_js_1 = require("./tokens.js");
+const mariadb_session_record_store_js_1 = require("../session/mariadb-session-record-store.js");
+const crypto_adapters_js_1 = require("../session/crypto-adapters.js");
+const session_lifetimes_js_1 = require("../session/session-lifetimes.js");
+const mfa_step_up_js_1 = require("./mfa-step-up.js");
+const canonical_hint_js_1 = require("./rate-limit/canonical-hint.js");
+const trust_proxy_check_js_1 = require("./rate-limit/trust-proxy-check.js");
 const pending_mfa_store_js_1 = require("./pending-mfa-store.js");
 const tokens_js_2 = require("../request-auth/tokens.js");
+const session_token_binder_js_1 = require("../request-auth/session-token-binder.js");
 const request_principal_js_1 = require("../request-auth/request-principal.js");
 const tokens_js_3 = require("./tokens.js");
 /**
@@ -172,6 +182,8 @@ let AuthController = class AuthController {
     resetLinkBaseUrl;
     recoveryCodes;
     loginLimiter;
+    loginIpLimiter;
+    trustProxyCheck;
     recoveryLimiter;
     forgotLimiter;
     forgotHintLimiter;
@@ -181,7 +193,14 @@ let AuthController = class AuthController {
     scopeSubtreeResolver;
     membershipChecker;
     permissionFacts;
-    constructor(authenticator, sessionAuthority, pendingMfa, tokenBinder, profileResolver, credentialResolver, resetTokenStore, emailSender, credentialWriter, sessionSweeper, passwordHasher, resetLinkBaseUrl, recoveryCodes, loginLimiter, recoveryLimiter, forgotLimiter, forgotHintLimiter, resetLimiter, auditSink, sessionFactsProjector, scopeSubtreeResolver, membershipChecker, permissionFacts) {
+    mfaLimiter;
+    mfaStepUp;
+    clock;
+    lifetimes;
+    rootIds;
+    sessionRecords;
+    sessionRestrictions;
+    constructor(authenticator, sessionAuthority, pendingMfa, tokenBinder, profileResolver, credentialResolver, resetTokenStore, emailSender, credentialWriter, sessionSweeper, passwordHasher, resetLinkBaseUrl, recoveryCodes, loginLimiter, loginIpLimiter, trustProxyCheck, recoveryLimiter, forgotLimiter, forgotHintLimiter, resetLimiter, auditSink, sessionFactsProjector, scopeSubtreeResolver, membershipChecker, permissionFacts, mfaLimiter, mfaStepUp, clock, lifetimes, rootIds, sessionRecords, sessionRestrictions) {
         this.authenticator = authenticator;
         this.sessionAuthority = sessionAuthority;
         this.pendingMfa = pendingMfa;
@@ -196,6 +215,8 @@ let AuthController = class AuthController {
         this.resetLinkBaseUrl = resetLinkBaseUrl;
         this.recoveryCodes = recoveryCodes;
         this.loginLimiter = loginLimiter;
+        this.loginIpLimiter = loginIpLimiter;
+        this.trustProxyCheck = trustProxyCheck;
         this.recoveryLimiter = recoveryLimiter;
         this.forgotLimiter = forgotLimiter;
         this.forgotHintLimiter = forgotHintLimiter;
@@ -205,34 +226,63 @@ let AuthController = class AuthController {
         this.scopeSubtreeResolver = scopeSubtreeResolver;
         this.membershipChecker = membershipChecker;
         this.permissionFacts = permissionFacts;
+        this.mfaLimiter = mfaLimiter;
+        this.mfaStepUp = mfaStepUp;
+        this.clock = clock;
+        this.lifetimes = lifetimes;
+        this.rootIds = rootIds;
+        this.sessionRecords = sessionRecords;
+        this.sessionRestrictions = sessionRestrictions;
+    }
+    /**
+     * The access-token binding TTL for an establishment (security hardening #8):
+     * `clamp(session.expiresAtMs − now, 1, accessTtlMs)` — on login AND refresh. Never derived
+     * from `issuedAtMs` (the original login), which made refresh-minted tokens live for the
+     * session's age.
+     */
+    accessTtlFor(est) {
+        const now = this.clock?.nowMs() ?? Date.now();
+        return (0, session_lifetimes_js_1.accessBindingTtlMs)(est.session.expiresAtMs, now, this.lifetimes?.accessTtlMs ?? session_lifetimes_js_1.DEFAULT_ACCESS_TTL_MS);
     }
     /**
      * Bind the established session's access token to the principal's claims (the
-     * request-auth layer). The access-token TTL is `expiresAtMs - issuedAtMs` from the
-     * session. Best-effort: a binding failure must not fail the login (the caller still
+     * request-auth layer). The access-token TTL is {@link accessTtlFor} (≤ the access TTL).
+     * Best-effort: a binding failure must not fail the login (the caller still
      * gets valid tokens); the guard fails closed if the binding is absent.
      */
     async bindSession(est, principal, mustReenroll = false) {
         if (this.tokenBinder === undefined)
             return;
-        const ttlMs = Math.max(est.session.expiresAtMs - est.session.issuedAtMs, 1);
+        const ttlMs = this.accessTtlFor(est);
         // EAGER session-facts projection (ADR-0011): compute the principal's coarse grants
         // NOW so the guard can serve gate 5 from the request's `cachedFacts`. Absent projector
         // / a null result → `cachedFacts` stays undefined → gate 5 DB-reloads (today's
         // behavior). Best-effort inside projectFacts (a failure → undefined, never throws).
-        const cachedFacts = await this.projectFacts(principal);
+        const projected = await this.projectFactsFor(principal.id, principal.tenantId);
+        const cachedFacts = projected ?? undefined;
         // EAGER active-scope-subtree resolution (Task 2.2, ADR-0027 / ADR-0024): resolve the
         // principal's closure subtree (self node + descendants) NOW so the per-request tenant gate
         // reads it from the binding with zero DB (the parity guarantee — the closure query happens
         // ONLY here, at login). Absent resolver / empty result / a thrown resolver → undefined →
         // `scopeSubtreeNodeIds` stays absent → the per-request path falls back to the self-node.
         // Best-effort inside resolveScopeSubtree (a failure → undefined, never throws).
+        // The version is read FIRST (Phase 1C) so the stamp can only be older than the subtree.
+        const scopeSubtreeVersion = await this.subtreeVersionFor(principal.tenantId);
         const scopeSubtreeNodeIds = await this.resolveScopeSubtree(principal);
+        // LIVE ROLES (ADR-0035, GAPS #4): the in-effect posting roles from the SAME projection as the
+        // cached facts, not the credential's login-time `ic_roles`.
+        //  - projection reported roles            → those roles;
+        //  - an active projector failed / yielded nothing (null) → `[]` (review P2-d: never widen to
+        //    the `ic_roles` snapshot; no facts are cached, so the first request's gate-5 reload binds
+        //    the live roles before any handler runs);
+        //  - a projection without `roleIds` (a port that does not report roles) or no projector at all
+        //    → the authenticated principal's roles (back-compat for apps that own their roles).
+        const roleIds = projected === null ? [] : ((0, session_token_binder_js_1.liveRoleIds)(projected) ?? [...principal.roleIds]);
         try {
             await this.tokenBinder.bind(est.tokens.accessToken, {
                 id: principal.id,
                 tenantId: principal.tenantId,
-                roleIds: [...principal.roleIds],
+                roleIds,
                 kind: principal.kind,
                 isRoot: principal.isRoot === true,
                 sessionId: est.session.sessionId,
@@ -242,11 +292,15 @@ let AuthController = class AuthController {
                 // Only include the key when a projection produced facts — under
                 // exactOptionalPropertyTypes an explicit `undefined` is not assignable to the
                 // optional field; a spread keeps it truly absent (→ gate 5 DB-reloads).
-                ...(cachedFacts ? { cachedFacts } : {}),
+                ...(cachedFacts ? { cachedFacts: (0, session_token_binder_js_1.factsSlot)(cachedFacts) } : {}),
                 // Same spread discipline for the resolved subtree: present only when the resolver
                 // produced a non-empty set (→ the per-request tenant gate reads the real subtree);
                 // absent otherwise (→ the per-request path falls back to the self-node, non-widening).
                 ...(scopeSubtreeNodeIds ? { scopeSubtreeNodeIds } : {}),
+                // The version the subtree was resolved at (Phase 1C) — only beside a subtree.
+                ...(scopeSubtreeNodeIds && scopeSubtreeVersion !== undefined
+                    ? { scopeSubtreeVersion }
+                    : {}),
             }, ttlMs);
         }
         catch {
@@ -254,21 +308,6 @@ let AuthController = class AuthController {
             // binding is missing, so this degrades safely (the user re-logs in).
         }
     }
-    /**
-     * Project the principal's coarse grants for the session binding (ADR-0011), via the
-     * OPTIONAL {@link SessionFactsProjector} seam. Returns the {@link CoarseGrants} to
-     * cache, or `undefined` when there is no projector, the projection yielded nothing,
-     * OR it threw — every "no facts" path collapses to `undefined` so the caller simply
-     * omits `cachedFacts` and the request DB-reloads (fail-closed; a projection failure
-     * NEVER fails the login/refresh and never fabricates a grant).
-     */
-    async projectFacts(principal) {
-        const facts = await this.projectFactsFor(principal.id, principal.tenantId);
-        // At LOGIN there is no prior cache, so "no projector" (undefined) and "yielded
-        // nothing" (null) BOTH mean "omit cachedFacts" → gate 5 DB-reloads. Collapse to
-        // undefined for the bind() spread.
-        return facts ?? undefined;
-    }
     /**
      * Project coarse grants for a principal id + tenant (ADR-0011), distinguishing THREE
      * outcomes for the REFRESH path (which must know whether to carry the existing cache
@@ -284,6 +323,9 @@ let AuthController = class AuthController {
         const projector = this.sessionFactsProjector;
         if (projector === undefined || projector === null)
             return undefined;
+        // The framework's deferred default projector before its port is attached = no projector.
+        if (typeof projector.isActive === 'function' && projector.isActive() !== true)
+            return undefined;
         try {
             return await projector.project(principalId, tenantId);
         }
@@ -317,6 +359,30 @@ let AuthController = class AuthController {
      * bumped by moveNode/deleteNode) re-derives its CORRECT subtree here, closing the
      * stale-subtree-after-move window (bounded by the access-token lifetime — ADR-0011).
      */
+    /**
+     * The permission version of `tenantId`, read just BEFORE its subtree is resolved, to stamp the
+     * binding (`scopeSubtreeVersion`, security hardening Phase 1C): when gate 5 later reloads facts
+     * at a newer version, the enforcement guard re-derives the subtree. Read before the resolve so a
+     * racing bump leaves the stamp too old (one extra re-derive), never too new. Only when a
+     * subtree resolver is wired (no subtree → nothing to stamp, no extra read). Best-effort: no
+     * facts adapter, a non-integer, or a throw → `undefined` (unstamped → the guard re-derives once
+     * at the next reload). One indexed read at login/refresh/scope-switch, never per request.
+     */
+    async subtreeVersionFor(tenantId) {
+        if (this.scopeSubtreeResolver === undefined || this.scopeSubtreeResolver === null) {
+            return undefined;
+        }
+        const facts = this.permissionFacts;
+        if (facts === undefined || facts === null)
+            return undefined;
+        try {
+            const v = await facts.currentVersionFor('', tenantId);
+            return Number.isSafeInteger(v) && v >= 0 ? v : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     async resolveScopeSubtreeFor(tenantId) {
         const resolver = this.scopeSubtreeResolver;
         if (resolver === undefined || resolver === null)
@@ -403,21 +469,70 @@ let AuthController = class AuthController {
             isRoot: false,
         };
     }
+    /**
+     * The account (principal id) a typed hint resolves to, for keying the per-account
+     * limiters (review F1). Goes through the SAME injected {@link CredentialResolver} the
+     * composed authenticator uses — the default is the indexed
+     * `WHERE ic_identity_hint = ? LIMIT 1` on the `utf8mb4_unicode_ci` column — so the DB
+     * collation, not client-side normalisation, decides which spellings are one account.
+     * No new access path. The RAW hint is passed (never normalised).
+     *
+     * Returns `null` for an unknown hint, a blank hint, or when no resolver is wired (→ the
+     * canonical-hash fallback key). A store ERROR propagates (the caller fails closed).
+     */
+    /**
+     * The ONE gate for every per-IP limiter (login failures, forgot-password, reset-password):
+     * returns the limiter only when bootstrap confirmed an explicit Express `trust proxy`
+     * ({@link TrustProxyBootCheck.perIpLimitingEnabled}); otherwise `null` (limiter OFF).
+     * Without it every client behind a proxy shares one `req.ip`, so enforcing a per-IP
+     * limit would block everyone (an unauthenticated global DoS). Per-account limits are
+     * never routed through here.
+     */
+    perIp(limiter) {
+        return this.trustProxyCheck?.perIpLimitingEnabled === true ? (limiter ?? null) : null;
+    }
+    async lookupAccount(rawHint) {
+        const resolver = this.credentialResolver;
+        if (resolver == null || rawHint === '')
+            return null;
+        return resolver.resolve(rawHint);
+    }
     /**
      * `POST /auth/login` — verify a password credential and either establish a
      * session, issue an MFA challenge, deny generically, or signal a transient
      * outage. NEVER logs the request body.
      */
-    async login(body) {
+    async login(body, ip) {
+        // F5: the hint goes to the store EXACTLY as typed — the DB collation
+        // (utf8mb4_unicode_ci) decides which spellings are the same account. Never rewritten.
         const identityHint = typeof body?.identityHint === 'string' ? body.identityHint : '';
         const password = typeof body?.password === 'string' ? body.password : '';
-        // Rate-limit gate (spec §5 / H1): after M failed attempts within the window,
-        // reject BEFORE consulting the authenticator — the SAME generic 401 as a wrong
-        // password (anti-enumeration: a locked-out account is indistinguishable). Keyed
-        // on the presented hint (the resolver isn't run pre-auth). Fails OPEN on a Redis
-        // blip (the limiter's own posture — never a lockout from an outage).
-        const loginKey = `login:${identityHint}`;
-        if (this.loginLimiter != null && !(await this.loginLimiter.check(loginKey))) {
+        // Rate-limit gate (spec §5 / H1 + #5): after M failed attempts within the window —
+        // for this ACCOUNT, or from this client IP when per-IP limiting is on — reject BEFORE
+        // consulting the authenticator, with the SAME generic 401 as a wrong password
+        // (anti-enumeration: a locked-out account is indistinguishable). Each limiter fails
+        // OPEN on a Redis blip (its own posture — never a lockout from an outage).
+        //
+        // Per-IP first (cheap, no DB): a locked IP never reaches the account lookup.
+        const ipLimiter = this.perIp(this.loginIpLimiter);
+        const ipKey = (0, canonical_hint_js_1.loginIpKey)(ip);
+        if (ipLimiter != null && !(await ipLimiter.check(ipKey))) {
+            genericUnauthorized();
+        }
+        // F1: key the per-account budget on the account the store resolves for this hint
+        // (`login:pid:<id>`; unknown → canonical-hash fallback). A store ERROR fails CLOSED
+        // (503), consistent with the authenticator's treatment of a resolver outage.
+        let account;
+        try {
+            account = await this.lookupAccount(identityHint);
+        }
+        catch {
+            retryableUnavailable();
+        }
+        const accountId = (0, canonical_hint_js_1.principalIdOf)(account);
+        const loginKey = (0, canonical_hint_js_1.loginHintKey)(identityHint, accountId);
+        const hintAllowed = this.loginLimiter == null || (await this.loginLimiter.check(loginKey));
+        if (!hintAllowed) {
             // Already locked → generic 401. We do NOT audit here: `check()` returns false on
             // EVERY attempt once locked, so auditing at this gate would flood one event per
             // attempt. The lockout is audited ONCE on the TRANSITION instead — in the
@@ -425,7 +540,9 @@ let AuthController = class AuthController {
             // (feature #140 audit-on-the-edge, anti-flood).
             genericUnauthorized();
         }
-        const result = await this.authenticator.authenticate(identityHint, [passwordCredential(password)]);
+        const result = await this.authenticator.authenticate(identityHint, [
+            passwordCredential(password),
+        ]);
         if (result.outcome === 'authenticated') {
             // Correct password → clear the login counter (do not carry earlier failures).
             await this.loginLimiter?.reset(loginKey);
@@ -437,13 +554,29 @@ let AuthController = class AuthController {
             return this.sessionSuccessWithFacts(est, principal);
         }
         if (result.outcome === 'mfa_required') {
-            // Password verified, a second factor is outstanding. The PASSWORD was correct,
-            // so this is NOT a login failure — reset the login limiter (spec §5: reset on
-            // authenticated OR mfa_required). Then hold the pending credentials server-side
-            // and hand back an OPAQUE, unforgeable challenge handle. NO session yet; the
-            // handle carries nothing about the user.
-            await this.loginLimiter?.reset(loginKey);
-            const challengeToken = this.pendingMfa.store(identityHint, password);
+            // Password verified, a second factor is outstanding. NOT a failure — but NOT a
+            // success either (#9): the login counter is reset only once `/auth/mfa` completes,
+            // so a stolen password cannot loop login→mfa to guess TOTP codes for free.
+            //
+            // M6: record the password step's SUCCESS — the resolved principal, the typed hint,
+            // and a fingerprint of the credential it was checked against — NEVER the password.
+            // `/auth/mfa` verifies only the second factor against that principal. No resolved
+            // account here (no resolver wired / the account vanished mid-login) → fail closed.
+            if (account === null || accountId === null)
+                genericUnauthorized();
+            const challenge = {
+                principalId: accountId,
+                identityHint,
+                credentialFingerprint: (0, mfa_step_up_js_1.credentialFingerprint)(account),
+            };
+            let challengeToken;
+            try {
+                challengeToken = await this.pendingMfa.store(challenge);
+            }
+            catch {
+                // The challenge store (Redis) is down: a transient outage, not a credential deny.
+                retryableUnavailable();
+            }
             return { mfaRequired: true, challengeToken };
         }
         // outcome === 'rejected'. Distinguish ONLY transient-vs-deny (never which
@@ -458,9 +591,9 @@ let AuthController = class AuthController {
         // returns the NEW count; when it first equals the limiter's threshold this attempt
         // is the one that TRIPPED the lockout — audit `auth.login.locked` exactly ONCE here
         // (the edge), never on the already-locked check-gate above (which would flood).
-        // NO notify: this is pre-auth (keyed on the typed hint; the resolver hasn't run), so
-        // we cannot resolve the real owner's email — mailing a bare hint could reach a
-        // non-owner / confirm the account exists (recordSecurityEvent enforces this too).
+        // NO notify: this is pre-auth (the caller has not proven ownership), and mailing the
+        // account on every lockout would let anyone email-bomb it / confirm it exists
+        // (recordSecurityEvent enforces this too).
         if (this.loginLimiter != null) {
             const count = await this.loginLimiter.recordFailure(loginKey);
             if (count === this.loginLimiter.maxAttempts) {
@@ -472,6 +605,20 @@ let AuthController = class AuthController {
                 });
             }
         }
+        // #5: count the failure against the client IP too (failures only — a success never
+        // touches this counter, so an attacker's own valid login cannot reset the budget).
+        // Audited once on the edge, with no hint (the IP budget spans many accounts).
+        if (ipLimiter != null) {
+            const ipCount = await ipLimiter.recordFailure(ipKey);
+            if (ipCount === ipLimiter.maxAttempts) {
+                this.recordSecurityEvent({
+                    action: 'auth.login.ip_locked',
+                    identityHint: null,
+                    attributes: { reason: 'rate_limit' },
+                    notify: false,
+                });
+            }
+        }
         genericUnauthorized();
     }
     /**
@@ -600,6 +747,8 @@ let AuthController = class AuthController {
         }
         // 4) Re-resolve the subtree for the NEW active node (self-node fallback if unwired /
         //    empty / thrown — non-widening, mirrors login). The new subtree REPLACES the old.
+        //    The target node's version is read first and stamped beside it (Phase 1C).
+        const subtreeVersion = await this.subtreeVersionFor(targetNodeId);
         const resolved = await this.resolveScopeSubtree({
             kind: 'user',
             id: claims.id,
@@ -610,12 +759,18 @@ let AuthController = class AuthController {
             isRoot: false,
         });
         const subtree = resolved ?? [targetNodeId];
+        // ADR-0035: the TARGET node's coarse grants + live roles (roles are per node). No projection
+        // → the facts are stripped and the first request under the new scope reloads them (and the
+        // roles with them).
+        const targetFacts = await this.projectFactsFor(claims.id, targetNodeId);
         // 5) RE-BIND the current session in place (same token — no rotate). The bound tenantId
         //    becomes targetNodeId (→ activeScopeNodeId) + scopeSubtreeNodeIds becomes the NEW
         //    subtree; the OLD node's subtree + cachedFacts are DROPPED (stale authority gone).
         //    A failed re-bind (session gone / Redis down) → deny (fail-closed, the old binding
         //    already effectively dead).
-        const ok = await this.tokenBinder.rebindActiveScope(token, claims.sessionId, targetNodeId, subtree);
+        const ok = await this.tokenBinder.rebindActiveScope(token, claims.sessionId, targetNodeId, subtree, 
+        // Stamp only a RESOLVED subtree; the self-node fallback stays unstamped.
+        resolved !== undefined ? subtreeVersion : undefined, targetFacts ?? null, (0, session_token_binder_js_1.liveRoleIds)(targetFacts));
         if (!ok) {
             throw new common_1.HttpException({ error: 'scope_switch_denied' }, common_1.HttpStatus.FORBIDDEN);
         }
@@ -642,29 +797,27 @@ let AuthController = class AuthController {
      *   501 here, which would itself be an enumeration signal on hint validity).
      */
     async forgotPassword(body, ip) {
+        // F5: the hint is looked up EXACTLY as typed — the DB collation (utf8mb4_unicode_ci)
+        // decides which spellings are one account. Never rewritten.
         const hint = typeof body?.identityHint === 'string' ? body.identityHint : '';
-        const resolver = this.credentialResolver;
-        const store = this.resetTokenStore;
-        const sender = this.emailSender;
         // ── Rate-limit gate (feature #141) — a REQUEST-RATE cap, NOT a failure cap. ──────
         // forgot-password is ALWAYS 204 (a 429 would itself leak account existence), so we
         // COUNT every forgot request against two budgets and, when EITHER is exceeded,
         // SILENTLY skip the email-send while STILL returning 204. Two keys: the client IP
-        // (stops one host spraying many hints) and the presented hint (stops one account
-        // being email-bombed across a rotating IP pool). Each limiter fails OPEN on a Redis
-        // blip (its own posture) so an outage never silently drops a legitimate reset email.
+        // (stops one host spraying many hints) and the ACCOUNT the hint resolves to (stops one
+        // account being email-bombed across a rotating IP pool and across spelling variants —
+        // review F1). Each limiter fails OPEN on a Redis blip (its own posture) so an outage
+        // never silently drops a legitimate reset email.
         // Defense-in-depth: a normal Express `req.ip` is always populated, but an empty ip
         // (a non-standard adapter/harness) would collapse EVERY client into one shared
         // `forgot:ip:` bucket → a global lockout. Fall back to a fixed sentinel so a blank ip
-        // is its own bucket, never a shared one (mirrors the `hint === ''` guard below).
+        // is its own bucket, never a shared one.
         const ipKey = `forgot:ip:${ip || 'unknown-ip'}`;
-        const hintKey = `forgot:${hint}`;
-        // Check BOTH budgets first (a `false` from either = over budget = skip the send).
-        // Both checks run so both counters see this request (below), independent of order.
-        const ipAllowed = this.forgotLimiter == null || (await this.forgotLimiter.check(ipKey));
-        // Only meter the hint budget when there IS a hint (an empty hint is the unknown-user
-        // path — it never sends anyway, and we must not let a blank hint burn a shared key).
-        const hintAllowed = this.forgotHintLimiter == null || hint === '' || (await this.forgotHintLimiter.check(hintKey));
+        // The IP budget applies only when bootstrap confirmed an explicit `trust proxy`
+        // (otherwise every client shares the proxy's IP and 5 requests would silently drop
+        // EVERY reset email). The per-account budget below is unaffected.
+        const forgotIpLimiter = this.perIp(this.forgotLimiter);
+        const ipAllowed = forgotIpLimiter == null || (await forgotIpLimiter.check(ipKey));
         // Count THIS request toward each budget (there is no pass/fail signal — every forgot
         // call is an "attempt"; the counter is what trips the silent skip). Best-effort +
         // detached from the 204 (never awaited into the response timing; a throw is swallowed
@@ -681,10 +834,10 @@ let AuthController = class AuthController {
         // itself confirm the account exists AND could be used to email-bomb the owner; the
         // event is audit-only. NO secret in attributes (a reason code only; the hint is the
         // actor identity, acceptable in the audit row, added by recordSecurityEvent).
-        void this.forgotLimiter
+        void forgotIpLimiter
             ?.recordFailure(ipKey)
             .then((count) => {
-            if (this.forgotLimiter != null && count === this.forgotLimiter.maxAttempts) {
+            if (count === forgotIpLimiter.maxAttempts) {
                 this.recordSecurityEvent({
                     action: 'auth.forgot_password.throttled',
                     identityHint: hint || null,
@@ -694,53 +847,75 @@ let AuthController = class AuthController {
             }
         })
             .catch(() => { });
-        // Same edge-audit for the per-HINT budget (only when there IS a hint — never audit
-        // an empty-hint edge, mirroring the `hint !== ''` gate on the hint limiter itself).
-        // A DISTINCT action key (`hint_throttled` vs the IP site's `throttled`) so the two
-        // abuse shapes are distinguishable in the audit log: the per-hint edge catches ONE
-        // account being email-bombed across ROTATING IPs (each IP staying under its own
-        // budget), which the per-IP audit would NEVER see. Detached + swallowed, 204
-        // unchanged, no notify (a hint-throttle notice would confirm the account + could
-        // itself be the email-bomb).
+        // The per-ACCOUNT budget and the found-path delivery run DETACHED (no await): resolving
+        // the account and minting/sending must never leak into the response timing. Only when
+        // there IS a hint (an empty hint never sends, and must not burn a shared key).
         if (hint !== '') {
-            void this.forgotHintLimiter
-                ?.recordFailure(hintKey)
-                .then((count) => {
-                if (this.forgotHintLimiter != null && count === this.forgotHintLimiter.maxAttempts) {
-                    this.recordSecurityEvent({
-                        action: 'auth.forgot_password.hint_throttled',
-                        identityHint: hint,
-                        attributes: { reason: 'rate_limit' },
-                        notify: false,
-                    });
-                }
-            })
-                .catch(() => { });
-        }
-        // Only the matching branch does work — but do it DETACHED (no await) so its
-        // duration never leaks into the response timing. Absent seams → skip entirely.
-        // Throttled (either budget exceeded) → SILENTLY skip the send (still 204 below).
-        if (ipAllowed && hintAllowed && hint && resolver && store && sender) {
-            // Fire-and-forget: never awaited before the 204. `.catch` swallows any
-            // store/email failure (anti-enumeration — a failure must NOT change the
-            // response, and must never surface as an unhandled rejection).
-            void this.deliverResetLink(hint, resolver, store, sender).catch(() => {
+            void this.meterAndDeliverReset(hint, ipAllowed).catch(() => {
                 /* swallow — anti-enumeration: never let a store/email failure be observable */
             });
         }
         // ALWAYS 204, immediately, identical body for every branch (found/unknown/throttled).
     }
+    /**
+     * The detached per-account half of {@link forgotPassword} (review F1):
+     *  1. resolve the RAW hint through the same {@link CredentialResolver} the authenticator
+     *     uses (the DB collation decides which spellings are one account);
+     *  2. meter the per-account budget — `forgot:pid:<principalId>`, or the canonical-hash
+     *     fallback key for an unknown hint — and audit `auth.forgot_password.hint_throttled`
+     *     ONCE on the edge (distinct from the IP site's `throttled`, so "one account bombed
+     *     across rotating IPs" is visible). No notify (it would itself be the email-bomb);
+     *  3. send only when both budgets allow, the account resolved, and the reset seams exist.
+     * A lookup error still meters (fallback key) and skips the send (still 204).
+     */
+    async meterAndDeliverReset(hint, ipAllowed) {
+        const resolver = this.credentialResolver;
+        let resolved = null;
+        let lookupFailed = false;
+        if (resolver != null) {
+            try {
+                resolved = await resolver.resolve(hint);
+            }
+            catch {
+                lookupFailed = true;
+            }
+        }
+        const principalId = (0, canonical_hint_js_1.principalIdOf)(resolved);
+        const hintKey = (0, canonical_hint_js_1.forgotHintKey)(hint, principalId);
+        let hintAllowed = true;
+        const limiter = this.forgotHintLimiter;
+        if (limiter != null) {
+            // Fail OPEN on a (consumer) limiter rejection, like AttemptLimiter itself.
+            hintAllowed = await limiter.check(hintKey).catch(() => true);
+            const count = await limiter.recordFailure(hintKey).catch(() => 0);
+            if (count === limiter.maxAttempts) {
+                this.recordSecurityEvent({
+                    action: 'auth.forgot_password.hint_throttled',
+                    identityHint: hint,
+                    attributes: { reason: 'rate_limit' },
+                    notify: false,
+                });
+            }
+        }
+        const store = this.resetTokenStore;
+        const sender = this.emailSender;
+        if (!ipAllowed || !hintAllowed || lookupFailed || resolved === null || !principalId)
+            return;
+        if (!store || !sender)
+            return; // absent seams → never sends (still 204)
+        await this.deliverResetLink(resolved, store, sender);
+    }
     /**
      * The detached found-path work for {@link forgotPassword}: mint a raw token, issue
      * its SHA-256 hash to the store (30-min TTL), resolve the recipient email via the
      * profile resolver, and send the framework-composed reset link. Runs OUTSIDE the
-     * request/response timing (fire-and-forget) so it cannot form a timing oracle. Never
-     * logs the token or the email.
+     * request/response timing (fire-and-forget) so it cannot form a timing oracle. This
+     * method itself writes no log line — but the raw token and the email ARE handed to the
+     * bound {@link EmailSender}, and the dev-only `LogEmailSender` (the default ONLY when
+     * NODE_ENV is `development`/`test`) prints the whole message, link included, to stdout.
+     * Any other environment must supply a real sender or `emailSender: 'disabled'`.
      */
-    async deliverResetLink(hint, resolver, store, sender) {
-        const resolved = await resolver.resolve(hint);
-        if (resolved === null)
-            return; // unknown hint — no token, no email (still 204)
+    async deliverResetLink(resolved, store, sender) {
         const claims = resolved.claims;
         const principalId = typeof claims.id === 'string' ? claims.id : '';
         if (!principalId)
@@ -800,7 +975,10 @@ let AuthController = class AuthController {
         // Defense-in-depth empty-ip fallback (see forgotPassword): a blank ip must be its
         // own bucket, never collapse all callers into one shared `reset:ip:` lockout bucket.
         const resetKey = `reset:ip:${ip || 'unknown-ip'}`;
-        if (this.resetLimiter != null && !(await this.resetLimiter.check(resetKey))) {
+        // Enforced only when bootstrap confirmed an explicit `trust proxy`; otherwise every
+        // client shares the proxy's IP and 10 bad tokens would 429 EVERY reset.
+        const resetIpLimiter = this.perIp(this.resetLimiter);
+        if (resetIpLimiter != null && !(await resetIpLimiter.check(resetKey))) {
             // Already locked → generic 429. We do NOT audit here: check() returns false on
             // EVERY attempt once locked, so this gate would flood one event per attempt. The
             // lockout is audited ONCE on the TRANSITION instead — in the invalid-token branch
@@ -814,7 +992,11 @@ let AuthController = class AuthController {
         const store = this.resetTokenStore;
         const writer = this.credentialWriter;
         const hasher = this.passwordHasher;
-        if (store === undefined || store === null || writer === undefined || writer === null || hasher === undefined) {
+        if (store === undefined ||
+            store === null ||
+            writer === undefined ||
+            writer === null ||
+            hasher === undefined) {
             throw new common_1.HttpException({ error: 'not_available' }, common_1.HttpStatus.NOT_IMPLEMENTED);
         }
         // Consume the token (single-use, TTL-checked). Unknown/expired/consumed → 400.
@@ -828,9 +1010,9 @@ let AuthController = class AuthController {
             // invalid-token attempt, only the transition). No hint/principal is available from a
             // bare token — that's fine, the event is audited without one. NO notify (no
             // resolvable owner from a token) and NO secret in attributes (a reason code only).
-            if (this.resetLimiter != null) {
-                const count = await this.resetLimiter.recordFailure(resetKey);
-                if (count === this.resetLimiter.maxAttempts) {
+            if (resetIpLimiter != null) {
+                const count = await resetIpLimiter.recordFailure(resetKey);
+                if (count === resetIpLimiter.maxAttempts) {
                     this.recordSecurityEvent({
                         action: 'auth.password_reset.locked',
                         attributes: { reason: 'rate_limit' },
@@ -844,21 +1026,28 @@ let AuthController = class AuthController {
         await writer.setPassword(principalId, newHash);
         // A SUCCESSFUL reset clears the IP counter (do not carry earlier bad-token attempts
         // forward — the caller proved a valid single-use token).
-        await this.resetLimiter?.reset(resetKey);
+        await resetIpLimiter?.reset(resetKey);
         // Reset kills ALL sessions (unlike change-password, which keeps the current one).
+        // The sweeper now SURFACES a failed Redis unbind (Phase 3 review P1); the other reset tokens
+        // are still burned before that error propagates.
+        let sweepError;
         if (this.sessionSweeper !== undefined && this.sessionSweeper !== null) {
-            await this.sessionSweeper.revokeAllForPrincipal(principalId);
+            await this.sessionSweeper.revokeAllForPrincipal(principalId).catch((err) => {
+                sweepError = err;
+            });
         }
         // Burn any other outstanding reset tokens for the principal (single active reset).
         await store.invalidateAllForPrincipal(principalId);
+        if (sweepError !== undefined)
+            throw sweepError;
     }
     /**
      * `POST /auth/mfa` — complete a pending MFA login. Consumes the single-use
      * challenge handle (unknown/expired/forged → same generic 401 as a bad code),
      * then BRANCHES on the presented factor:
-     *   • `'totp'` → RE-RUNS `authenticate(hint, [password, totp])` with the code
-     *     (the authenticator has no standalone factor-verify seam — the full attempt
-     *     IS the verify). Success → establish + tokens.
+     *   • `'totp'` → the MFA STEP-UP (M6): verify ONLY the code against the principal the
+     *     password step recorded (no password is held or re-run). Rate-limited per account
+     *     (#9). See {@link completeViaTotp}.
      *   • `'recovery_code'` → the lost-device escape hatch: verify a one-time
      *     recovery code (a separate branch, NOT the core factor loop — recovery codes
      *     are N single-use Argon2 hashes, incompatible with the pure one-secret
@@ -866,7 +1055,8 @@ let AuthController = class AuthController {
      *   • any other factor → generic 401 (no leak of "unsupported factor").
      *
      * Anti-enumeration: unknown/forged/expired challenge, unknown hint, wrong code,
-     * and wrong recovery code ALL return the identical generic 401.
+     * a locked TOTP step, and a wrong recovery code ALL return the identical generic 401.
+     * A challenge-store outage is a retryable 503.
      */
     async mfa(body) {
         const challengeToken = typeof body?.challengeToken === 'string' ? body.challengeToken : '';
@@ -876,32 +1066,76 @@ let AuthController = class AuthController {
         // is indistinguishable from a wrong code — generic 401, no leak. Consumed ONCE
         // here, up front, so BOTH branches (totp + recovery) share the single-use
         // semantics (a spent/forged challenge never reaches either verify path).
-        const pending = this.pendingMfa.consume(challengeToken);
+        let pending;
+        try {
+            pending = await this.pendingMfa.consume(challengeToken);
+        }
+        catch {
+            retryableUnavailable(); // challenge store (Redis) unavailable — transient, not a deny
+        }
         if (pending === null)
             genericUnauthorized();
         // Recovery-code branch — the lost-device escape hatch (a separate verify path).
         if (factor === 'recovery_code') {
             return this.completeViaRecoveryCode(pending, code);
         }
-        // Phase 0b: only 'totp' is a real re-authenticate factor. Any other → generic
-        // 401 (no leak of "unsupported factor").
+        // Only 'totp' is a step-up factor. Any other → generic 401 (no "unsupported" leak).
         if (factor !== 'totp')
             genericUnauthorized();
-        const result = await this.authenticator.authenticate(pending.identityHint, [passwordCredential(pending.password), totpCredential(code)]);
-        if (result.outcome === 'authenticated') {
-            const principal = requirePrincipal(result);
-            const est = await this.establishOrReject(principal);
-            await this.bindSession(est, principal);
-            // Same inline-facts enrichment as the password-login success (one round-trip).
-            return this.sessionSuccessWithFacts(est, principal);
+        return this.completeViaTotp(pending, code);
+    }
+    /**
+     * The `/auth/mfa` TOTP branch (M6 + #9). The consumed challenge proves the password
+     * step passed for `pending.principalId`; this verifies ONLY the code, through the
+     * {@link MfaStepUp} (same `OrTotpVerifier` + replay guard as the authenticator, principal
+     * minted by the identity broker).
+     *
+     *  - `mfa:pid:<principalId>` is checked BEFORE verifying: locked → generic 401 and the
+     *    step-up is never consulted.
+     *  - a rejected code records a failure; the edge where the count first reaches the
+     *    threshold audits `auth.mfa.locked` ONCE (no notify — pre-auth, see recovery lockout).
+     *  - a transient outage → 503, never counted.
+     *  - success → establish + bind, then reset the TOTP counter AND the login counter (the
+     *    login counter is reset only here, once authentication fully succeeded).
+     */
+    async completeViaTotp(pending, code) {
+        const mfaKey = `mfa:pid:${pending.principalId}`;
+        if (this.mfaLimiter != null && !(await this.mfaLimiter.check(mfaKey))) {
+            genericUnauthorized();
         }
-        // Anything else (wrong code → rejected; still-outstanding → mfa_required) is a
-        // failure. A transient blip is retryable; everything else is a generic 401.
-        // (A repeat mfa_required here means the code did not satisfy the factor.)
-        if (result.reason === REASON_AUTH_UNAVAILABLE) {
+        const stepUp = this.mfaStepUp;
+        if (stepUp == null)
+            genericUnauthorized(); // not wired → fail closed
+        let outcome;
+        try {
+            outcome = await stepUp.verify(pending, totpCredential(code));
+        }
+        catch {
             retryableUnavailable();
         }
-        genericUnauthorized();
+        if (outcome.outcome === 'unavailable')
+            retryableUnavailable();
+        if (outcome.outcome !== 'authenticated' || outcome.principal.id !== pending.principalId) {
+            if (this.mfaLimiter != null) {
+                const count = await this.mfaLimiter.recordFailure(mfaKey);
+                if (count === this.mfaLimiter.maxAttempts) {
+                    this.recordSecurityEvent({
+                        action: 'auth.mfa.locked',
+                        actorId: pending.principalId,
+                        attributes: { reason: 'rate_limit' },
+                        notify: false,
+                    });
+                }
+            }
+            genericUnauthorized();
+        }
+        const principal = outcome.principal;
+        const est = await this.establishOrReject(principal);
+        await this.bindSession(est, principal);
+        await this.mfaLimiter?.reset(mfaKey);
+        await this.loginLimiter?.reset((0, canonical_hint_js_1.loginHintKey)(pending.identityHint, pending.principalId));
+        // Same inline-facts enrichment as the password-login success (one round-trip).
+        return this.sessionSuccessWithFacts(est, principal);
     }
     /**
      * The `/auth/mfa` RECOVERY-CODE branch (spec §3). The lost-device user completes
@@ -930,6 +1164,10 @@ let AuthController = class AuthController {
         const resolved = await this.credentialResolver.resolve(pending.identityHint).catch(() => null);
         if (resolved == null)
             genericUnauthorized();
+        // M6: the credential must still be the one the password step was checked against
+        // (same principal, same stored credential hash) — else the challenge is void.
+        if (!(0, mfa_step_up_js_1.challengeMatches)(resolved, pending))
+            genericUnauthorized();
         const claims = resolved.claims;
         const principalId = typeof claims.id === 'string' ? claims.id : '';
         if (!principalId)
@@ -969,14 +1207,30 @@ let AuthController = class AuthController {
             }
             genericUnauthorized();
         }
-        // A correct recovery code → clear the counter (do not carry earlier failures).
+        // A correct recovery code → clear the counter (do not carry earlier failures), and —
+        // authentication being complete — the login counter too (#9).
         await this.recoveryLimiter?.reset(recoveryKey);
+        await this.loginLimiter?.reset((0, canonical_hint_js_1.loginHintKey)(pending.identityHint, principalId));
         // The pending challenge is proof the password already passed (§3) — no password
         // re-verify. Mint the Principal directly from the resolved claims.
         const principal = this.principalFromClaims(claims);
         if (principal === null)
             genericUnauthorized();
         const est = await this.establishOrReject(principal);
+        // Phase 3B review P1: persist the restriction on the DURABLE session BEFORE any token leaves,
+        // so a binding rebuilt after a Redis loss is restricted too. A failed mark → the session is
+        // revoked and the login answers a retryable 503 (fail closed: an unmarked recovery session
+        // could later be rebuilt unrestricted). No store wired → no rebuild is possible either.
+        const restrictions = this.sessionRestrictions;
+        if (restrictions !== undefined && restrictions !== null) {
+            try {
+                await restrictions.markMustReenroll(est.session.sessionId);
+            }
+            catch {
+                await this.sessionAuthority.revoke(est.session.sessionId).catch(() => undefined);
+                retryableUnavailable();
+            }
+        }
         // Enforced re-enroll (spec §4): a recovery-code login is lower-assurance, so the
         // session is bound with mustReenroll:true — the enforcement gate then restricts it
         // to the re-secure allowlist until a fresh device is confirmed.
@@ -1118,18 +1372,31 @@ let AuthController = class AuthController {
     /**
      * `POST /auth/refresh` — rotate the refresh token. Reuse/invalid/expired →
      * generic 401 (`session_rejected`; the engine already killed the lineage,
-     * ADR-0015). ⚠ See the class header: the engine's rotate collapses a transient
+     * ADR-0015, and `HotRevokingSessionRecordStore` unbinds it in Redis so the live access
+     * token dies on its next request — M-A). The new access token is bound for ≤ the access
+     * TTL; the previous one keeps a 30 s grace (#8, D7). If the session's claims cannot be
+     * carried forward (`rebindOnRotate` → false) the refresh is a generic 401 — never an
+     * unbound token. ⚠ See the class header: the engine's rotate collapses a transient
      * store outage into the SAME reject, so refresh cannot emit the ADR-0016 503 from
      * this seam today (flagged core-API gap).
      */
     async refresh(body) {
         const refreshToken = typeof body?.refreshToken === 'string' ? body.refreshToken : '';
+        // Phase 2 review F1 (ADR-0035): ask Redis BEFORE the durable rotate spends the refresh token.
+        // Unreachable → retryable 503 (ADR-0016) and the token stays valid for the client's retry.
+        const probe = this.tokenBinder;
+        if (typeof probe?.isAvailable === 'function' && !(await probe.isAvailable())) {
+            retryableUnavailable();
+        }
         try {
             const est = await this.sessionAuthority.rotate(refreshToken);
             // Carry the principal claims forward to the NEW access token (the durable
             // session row lacks roles/kind — the session-claims entry has them).
             if (this.tokenBinder !== undefined) {
-                const ttlMs = Math.max(est.session.expiresAtMs - est.session.issuedAtMs, 1);
+                // #8: ≤ the access TTL (`clamp(expiresAtMs − now, 1, accessTtlMs)`), NOT
+                // `expiresAtMs − issuedAtMs` — issuedAtMs is the original LOGIN, so that grew with
+                // the session's age (a day-10 refresh minted a ~10-day token).
+                const ttlMs = this.accessTtlFor(est);
                 // EAGER re-projection at REFRESH (ADR-0011): re-read the principal's coarse grants
                 // so the cache stays warm past the version the LOGIN projected at (a role change
                 // between login and this refresh is picked up here). The rotated session carries
@@ -1137,15 +1404,28 @@ let AuthController = class AuthController {
                 // rebindOnRotate carries the existing `cachedFacts` forward unchanged (today's
                 // behavior); a fresh CoarseGrants → replaces it; `null` (projection yielded
                 // nothing) → strips it (→ next request DB-reloads; fail-closed).
-                const freshFacts = await this.projectFactsFor(est.session.principalId, est.session.tenantId);
-                // EAGER subtree RE-RESOLUTION at REFRESH (the stale-subtree-after-move fix): re-read the
-                // principal's closure subtree so a session whose node was re-parented (moveNode/deleteNode
-                // bumped its version) gets its CORRECT, possibly-smaller subtree — REPLACING the stale one
-                // carried from login. One indexed closure query at refresh (NOT per request — parity
-                // preserved). `undefined` (no resolver / empty / threw) → rebindOnRotate carries the
-                // existing subtree forward (fail-safe, non-widening — never fails the refresh).
-                const freshSubtree = await this.resolveScopeSubtreeFor(est.session.tenantId);
-                await this.tokenBinder.rebindOnRotate(est.tokens.accessToken, est.session.sessionId, ttlMs, freshFacts, freshSubtree);
+                //
+                // ACTIVE NODE (review follow-up): after a scope-switch the session acts under the node in
+                // its claims, not the durable login tenant. Project facts, roles and subtree for THAT node
+                // (rebindOnRotate applies them only if the claims are still on it). No claims (Redis loss)
+                // → the durable tenant, which is what a rebuild binds.
+                const peek = this.tokenBinder;
+                const activeTenant = (typeof peek.sessionTenant === 'function'
+                    ? await peek.sessionTenant(est.session.sessionId)
+                    : null) ?? est.session.tenantId;
+                const fresh = await this.projectForNode(est.session.principalId, activeTenant);
+                const rebound = await this.tokenBinder.rebindOnRotate(est.tokens.accessToken, est.session.sessionId, ttlMs, fresh.facts, fresh.subtree, fresh.subtreeVersion, fresh.roles, activeTenant);
+                // The claims were gone (Redis loss) or a logout won the race (`SET XX` refused):
+                // SILENT RECOVERY (invariant #12, ADR-0013/0035) rebuilds them from durable state; a
+                // rebuild that cannot be proven safe is a generic 401 — never an unbound token.
+                if (rebound !== true) {
+                    const durableFresh = activeTenant === est.session.tenantId
+                        ? fresh
+                        : await this.projectForNode(est.session.principalId, est.session.tenantId);
+                    const recovered = await this.rebuildBinding(est, ttlMs, durableFresh);
+                    if (!recovered)
+                        genericUnauthorized();
+                }
             }
             return toSessionSuccess(est);
         }
@@ -1156,6 +1436,101 @@ let AuthController = class AuthController {
             genericUnauthorized();
         }
     }
+    /**
+     * The refresh-time projection for one node: coarse grants + live roles (ADR-0035) and the
+     * subtree with its version stamp (Phase 1C: the version is read FIRST). Each part is best-effort
+     * exactly as at login (`undefined` = carry / omit, `null` facts = strip).
+     */
+    async projectForNode(principalId, tenantId) {
+        const facts = await this.projectFactsFor(principalId, tenantId);
+        const subtreeVersion = await this.subtreeVersionFor(tenantId);
+        const subtree = await this.resolveScopeSubtreeFor(tenantId);
+        return { facts, roles: (0, session_token_binder_js_1.liveRoleIds)(facts), subtree, subtreeVersion };
+    }
+    /**
+     * SILENT RECOVERY of a lost session binding (invariant #12, ADR-0013, ADR-0035, GAPS #5).
+     * `rotate()` has already proved the durable session is active and inside its idle and absolute
+     * windows, and returned its principal + tenant. The rebuilt claims NEVER carry more authority
+     * than the session had (Phase 3B review P1); they come from durable sources only:
+     *  - principal + tenant: the durable session record (the LOGIN node; a scope-switch is not
+     *    durable, so a rebuilt session returns to the node it was opened on);
+     *  - the RE-ENROLL restriction: `shield_identity.session.s_must_reenroll`, set at a
+     *    recovery-code login. A restricted session rebuilds `mustReenroll: true` and NEVER root
+     *    (exactly how the recovery login bound it);
+     *  - the account status: a disabled user gets no rebuild;
+     *  - roles: the live projection (ADR-0035) — `[]` when none is available (non-widening; the
+     *    first request's gate-5 reload fills them, because no facts are cached then);
+     *  - `isRoot` (unrestricted sessions only): the server-side root allowlist, never a claim;
+     *  - subtree: the resolver (absent → the self-node fallback, non-widening);
+     *  - kind `user` (sessions are human; service accounts authenticate with keys).
+     * No restriction store, or any error reading it → no rebuild (fail closed). The claims entry is
+     * written with `NX`, then the durable session is READ AGAIN: if a logout or revoke landed
+     * meanwhile, the rebuilt binding is dropped and the refresh fails. Returns `true` when the
+     * session is bound and still active. Any error → `false` (the caller answers 401).
+     */
+    async rebuildBinding(est, ttlMs, fresh) {
+        const binder = this.tokenBinder;
+        const records = this.sessionRecords;
+        const restrictions = this.sessionRestrictions;
+        if (binder === undefined || records === undefined || records === null)
+            return false;
+        if (restrictions === undefined || restrictions === null)
+            return false;
+        if (typeof binder.bindRecovered !== 'function')
+            return false;
+        const { sessionId, principalId, tenantId } = est.session;
+        if (!sessionId || !principalId || !tenantId)
+            return false;
+        let durableFacts;
+        try {
+            durableFacts = await restrictions.rebuildFacts(sessionId, principalId);
+        }
+        catch {
+            return false; // cannot prove the session's restriction → no rebuild (fail closed)
+        }
+        if (durableFacts.accountActive !== true)
+            return false;
+        const restricted = durableFacts.mustReenroll !== false;
+        const claims = {
+            id: principalId,
+            tenantId,
+            roleIds: fresh.roles !== undefined ? [...fresh.roles] : [],
+            kind: 'user',
+            isRoot: !restricted && Array.isArray(this.rootIds) && this.rootIds.includes(principalId),
+            sessionId,
+            mustReenroll: restricted,
+            ...(fresh.facts ? { cachedFacts: (0, session_token_binder_js_1.factsSlot)(fresh.facts) } : {}),
+            ...(fresh.subtree !== undefined && fresh.subtree.length > 0
+                ? { scopeSubtreeNodeIds: [...fresh.subtree] }
+                : {}),
+            ...(fresh.subtree !== undefined &&
+                fresh.subtree.length > 0 &&
+                fresh.subtreeVersion !== undefined
+                ? { scopeSubtreeVersion: fresh.subtreeVersion }
+                : {}),
+        };
+        try {
+            const written = await binder.bindRecovered(est.tokens.accessToken, claims, ttlMs);
+            if (!written)
+                return false;
+            const durable = await records.findSessionById(sessionId);
+            if (durable === null || durable === undefined || durable.status !== 'active') {
+                await binder.unbindSession(sessionId);
+                return false;
+            }
+            return true;
+        }
+        catch {
+            // Redis or the durable store failed mid-rebuild → leave nothing bound (best-effort), refuse.
+            try {
+                await binder.unbindSession(sessionId);
+            }
+            catch {
+                // best-effort
+            }
+            return false;
+        }
+    }
     /**
      * `POST /auth/logout` — revoke the session. Idempotent + leak-free: revoking an
      * unknown or already-revoked session still returns 204 (the engine's `revoke`
@@ -1198,8 +1573,9 @@ __decorate([
     (0, common_1.Post)('login'),
     (0, common_1.HttpCode)(common_1.HttpStatus.OK),
     __param(0, (0, common_1.Body)()),
+    __param(1, (0, common_1.Ip)()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
+    __metadata("design:paramtypes", [Object, String]),
     __metadata("design:returntype", Promise)
 ], AuthController.prototype, "login", null);
 __decorate([
@@ -1295,24 +1671,42 @@ exports.AuthController = AuthController = __decorate([
     __param(13, (0, common_2.Optional)()),
     __param(13, (0, common_1.Inject)(tokens_js_1.SHIELD_LOGIN_LIMITER)),
     __param(14, (0, common_2.Optional)()),
-    __param(14, (0, common_1.Inject)(tokens_js_1.SHIELD_RECOVERY_LIMITER)),
+    __param(14, (0, common_1.Inject)(tokens_js_1.SHIELD_LOGIN_IP_LIMITER)),
     __param(15, (0, common_2.Optional)()),
-    __param(15, (0, common_1.Inject)(tokens_js_1.SHIELD_FORGOT_LIMITER)),
+    __param(15, (0, common_1.Inject)(trust_proxy_check_js_1.TrustProxyBootCheck)),
     __param(16, (0, common_2.Optional)()),
-    __param(16, (0, common_1.Inject)(tokens_js_1.SHIELD_FORGOT_HINT_LIMITER)),
+    __param(16, (0, common_1.Inject)(tokens_js_1.SHIELD_RECOVERY_LIMITER)),
     __param(17, (0, common_2.Optional)()),
-    __param(17, (0, common_1.Inject)(tokens_js_1.SHIELD_RESET_LIMITER)),
+    __param(17, (0, common_1.Inject)(tokens_js_1.SHIELD_FORGOT_LIMITER)),
     __param(18, (0, common_2.Optional)()),
-    __param(18, (0, common_1.Inject)(tokens_js_1.SHIELD_AUDIT_SINK)),
+    __param(18, (0, common_1.Inject)(tokens_js_1.SHIELD_FORGOT_HINT_LIMITER)),
     __param(19, (0, common_2.Optional)()),
-    __param(19, (0, common_1.Inject)(tokens_js_1.SHIELD_SESSION_FACTS_PROJECTOR)),
+    __param(19, (0, common_1.Inject)(tokens_js_1.SHIELD_RESET_LIMITER)),
     __param(20, (0, common_2.Optional)()),
-    __param(20, (0, common_1.Inject)(tokens_js_1.SHIELD_SCOPE_SUBTREE_RESOLVER)),
+    __param(20, (0, common_1.Inject)(tokens_js_1.SHIELD_AUDIT_SINK)),
     __param(21, (0, common_2.Optional)()),
-    __param(21, (0, common_1.Inject)(tokens_js_1.SHIELD_MEMBERSHIP_CHECKER)),
+    __param(21, (0, common_1.Inject)(tokens_js_1.SHIELD_SESSION_FACTS_PROJECTOR)),
     __param(22, (0, common_2.Optional)()),
-    __param(22, (0, common_1.Inject)(tokens_js_1.SHIELD_PERMISSION_FACTS)),
-    __metadata("design:paramtypes", [Object, Object, pending_mfa_store_js_1.PendingMfaStore, Function, Object, Object, Object, Object, Object, Object, Object, String, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object])
+    __param(22, (0, common_1.Inject)(tokens_js_1.SHIELD_SCOPE_SUBTREE_RESOLVER)),
+    __param(23, (0, common_2.Optional)()),
+    __param(23, (0, common_1.Inject)(tokens_js_1.SHIELD_MEMBERSHIP_CHECKER)),
+    __param(24, (0, common_2.Optional)()),
+    __param(24, (0, common_1.Inject)(tokens_js_1.SHIELD_PERMISSION_FACTS)),
+    __param(25, (0, common_2.Optional)()),
+    __param(25, (0, common_1.Inject)(tokens_js_1.SHIELD_MFA_LIMITER)),
+    __param(26, (0, common_2.Optional)()),
+    __param(26, (0, common_1.Inject)(tokens_js_1.SHIELD_MFA_STEP_UP)),
+    __param(27, (0, common_2.Optional)()),
+    __param(27, (0, common_1.Inject)(crypto_adapters_js_1.SHIELD_CLOCK)),
+    __param(28, (0, common_2.Optional)()),
+    __param(28, (0, common_1.Inject)(session_lifetimes_js_1.SHIELD_SESSION_LIFETIMES)),
+    __param(29, (0, common_2.Optional)()),
+    __param(29, (0, common_1.Inject)(tokens_js_1.SHIELD_ROOT_IDS)),
+    __param(30, (0, common_2.Optional)()),
+    __param(30, (0, common_1.Inject)(mariadb_session_record_store_js_1.SHIELD_SESSION_RECORD_STORE)),
+    __param(31, (0, common_2.Optional)()),
+    __param(31, (0, common_1.Inject)(tokens_js_1.SHIELD_SESSION_RESTRICTIONS)),
+    __metadata("design:paramtypes", [Object, Object, pending_mfa_store_js_1.PendingMfaStore, Function, Object, Object, Object, Object, Object, Object, Object, String, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object])
 ], AuthController);
 /**
  * Narrow an `authenticated` result to its guaranteed principal. The core engine