@astram/guard 0.18.0 → 0.20.0

package/dist/auth/auth.controller.js

@@ -85,8 +85,11 @@ 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");
+const session_restriction_js_1 = require("../session/session-restriction.js");
+const logout_proof_js_1 = require("./logout-proof.js");
 const deliver_email_js_1 = require("../messaging/deliver-email.js");
 const password_reset_message_js_1 = require("./password-reset-message.js");
+const auth_audit_js_1 = require("./auth-audit.js");
 /**
  * The core `Authenticator`'s generic transient reason (see authenticator.ts —
  * `REASON_AUTH_UNAVAILABLE`). A `rejected` result carrying THIS reason is the
@@ -118,6 +121,26 @@ function sha256(value) {
 function genericUnauthorized() {
     throw new common_1.HttpException(GENERIC_AUTH_FAILURE, common_1.HttpStatus.UNAUTHORIZED);
 }
+/**
+ * Auth capabilities R7.3: the generic 401 plus the challenge flag, identical for known and unknown
+ * names (X2). Returned when a challenge is required and was missing or failed, and on a failure
+ * after which the next attempt needs one.
+ */
+const CAPTCHA_REQUIRED_FAILURE = Object.freeze({
+    error: 'invalid_credentials',
+    captcha: 'required',
+});
+/** The login 401: with the challenge flag when the next attempt needs a CAPTCHA token. */
+function loginUnauthorized(captchaRequired) {
+    if (captchaRequired) {
+        throw new common_1.HttpException(CAPTCHA_REQUIRED_FAILURE, common_1.HttpStatus.UNAUTHORIZED);
+    }
+    genericUnauthorized();
+}
+/** The reset-password bad-token 400, with the challenge flag when one is (now) required. */
+function invalidResetToken(captchaRequired) {
+    throw new common_1.HttpException(captchaRequired ? { error: 'invalid_token', captcha: 'required' } : { error: 'invalid_token' }, common_1.HttpStatus.BAD_REQUEST);
+}
 /** Throw the retryable 503 (transient — NOT a deny; the client may retry). */
 function retryableUnavailable() {
     throw new common_1.HttpException(RETRYABLE_BODY, common_1.HttpStatus.SERVICE_UNAVAILABLE);
@@ -221,7 +244,12 @@ let AuthController = class AuthController {
     sessionRestrictions;
     emailChangeTokens;
     messageDispatcher;
-    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, emailChangeTokens, messageDispatcher) {
+    logoutProof;
+    logoutRequiresProof;
+    mfaRequirement;
+    captchaGate;
+    signInWith;
+    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, emailChangeTokens, messageDispatcher, logoutProof, logoutRequiresProof, mfaRequirement, captchaGate, signInWith) {
         this.authenticator = authenticator;
         this.sessionAuthority = sessionAuthority;
         this.pendingMfa = pendingMfa;
@@ -256,6 +284,25 @@ let AuthController = class AuthController {
         this.sessionRestrictions = sessionRestrictions;
         this.emailChangeTokens = emailChangeTokens;
         this.messageDispatcher = messageDispatcher;
+        this.logoutProof = logoutProof;
+        this.logoutRequiresProof = logoutRequiresProof;
+        this.mfaRequirement = mfaRequirement;
+        this.captchaGate = captchaGate;
+        this.signInWith = signInWith;
+    }
+    /** True when bootstrap confirmed an explicit `trust proxy` (per-IP limits and CAPTCHA IP keys). */
+    perIpEnabled() {
+        return this.trustProxyCheck?.perIpLimitingEnabled === true;
+    }
+    /**
+     * R7.3: count one failure toward the CAPTCHA counters and say whether the next attempt needs a
+     * challenge. No gate (or endpoint not covered) ⇒ `false`.
+     */
+    async captchaAfterFailure(endpoint, subject) {
+        const gate = this.captchaGate;
+        if (gate === undefined || gate === null)
+            return false;
+        return gate.recordFailure(endpoint, subject);
     }
     /**
      * The access-token binding TTL for an establishment (security hardening #8):
@@ -275,7 +322,7 @@ let AuthController = class AuthController {
      */
     async bindSession(est, principal, mustReenroll = false) {
         if (this.tokenBinder === undefined)
-            return;
+            return (0, session_restriction_js_1.restrictionOf)({ mustReenroll }, Date.now());
         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
@@ -301,6 +348,11 @@ let AuthController = class AuthController {
         //  - 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]);
+        // MANDATORY 2FA (auth capabilities R2.3, R2.4): evaluated at sign-in (a lifecycle event; DB
+        // reads allowed) over the same projection. FAIL CLOSED: an evaluation that cannot complete, or
+        // a restriction that cannot be made durable, revokes the new session and answers 503 — never an
+        // unrestricted session. No policy feature ⇒ nothing here runs (the binding is unchanged).
+        const mfa = await this.evaluateMfaAtLogin(est, principal, projected);
         try {
             await this.tokenBinder.bind(est.tokens.accessToken, {
                 id: principal.id,
@@ -324,12 +376,46 @@ let AuthController = class AuthController {
                 ...(scopeSubtreeNodeIds && scopeSubtreeVersion !== undefined
                     ? { scopeSubtreeVersion }
                     : {}),
+                // R2.3 / R2.4: the requirement as evaluated at sign-in, and the version it is valid for.
+                ...(mfa ?? {}),
             }, ttlMs);
         }
         catch {
             // Best-effort: never fail a login on a binding hiccup. The guard denies if the
             // binding is missing, so this degrades safely (the user re-logs in).
         }
+        // The restriction the session was bound with (review round 1, item C): a restricted sign-in
+        // gets no inline grants.
+        return (0, session_restriction_js_1.restrictionOf)({ mustReenroll, ...(mfa ?? {}) }, Date.now());
+    }
+    /**
+     * The mandatory-2FA state to bind at sign-in (R2.3, R2.4), or `undefined` when the policy feature
+     * is not wired. `'required'` is also marked on the durable session BEFORE any token leaves, so a
+     * binding rebuilt after a Redis loss stays restricted. Any failure revokes the session and
+     * answers the generic 503 (fail closed).
+     */
+    async evaluateMfaAtLogin(est, principal, projected) {
+        const service = this.mfaRequirement;
+        if (service === undefined || service === null)
+            return undefined;
+        let state;
+        try {
+            state = await service.atLogin(principal, projected);
+            if (state.restriction === 'mfa_enrollment') {
+                const restrictions = this.sessionRestrictions;
+                if (restrictions !== undefined && restrictions !== null) {
+                    if (typeof restrictions.markRestriction !== 'function') {
+                        throw new Error('restriction store cannot record mfa_enrollment');
+                    }
+                    await restrictions.markRestriction(est.session.sessionId, 'mfa_enrollment');
+                }
+            }
+        }
+        catch {
+            await this.sessionAuthority.revoke(est.session.sessionId).catch(() => undefined);
+            retryableUnavailable();
+        }
+        return state;
     }
     /**
      * Project coarse grants for a principal id + tenant (ADR-0011), distinguishing THREE
@@ -454,8 +540,10 @@ let AuthController = class AuthController {
      * exactOptionalPropertyTypes an explicit `undefined` is not assignable to the optional
      * field, so a spread keeps it truly absent.
      */
-    async sessionSuccessWithFacts(est, principal, extra) {
-        const authFacts = await this.projectAuthFacts(principal);
+    async sessionSuccessWithFacts(est, principal, restricted, extra) {
+        // A restricted session (re-enrol or mandatory 2FA, review round 1 item C) gets NO inline
+        // grants: the frontend fetches `/identity/auth-facts`, which answers the restricted shape.
+        const authFacts = restricted === null ? await this.projectAuthFacts(principal) : undefined;
         return {
             ...toSessionSuccess(est),
             ...(extra?.mfaRecoveryUsed ? { mfaRecoveryUsed: true } : {}),
@@ -546,8 +634,10 @@ let AuthController = class AuthController {
         const ipLimiter = this.perIp(this.loginIpLimiter);
         const ipKey = (0, canonical_hint_js_1.loginIpKey)(ip);
         const ipVerdict = await consumeOrUnavailable(ipLimiter, ipKey);
-        if (ipVerdict !== null && !ipVerdict.allowed)
-            genericUnauthorized();
+        // R7.3: an IP over its login budget is far over the CAPTCHA threshold too.
+        if (ipVerdict !== null && !ipVerdict.allowed) {
+            loginUnauthorized(this.captchaGate?.covers('login') === true);
+        }
         /** Give back this attempt's IP count (it was not a password failure). */
         const refundIp = async () => {
             if (ipVerdict !== null)
@@ -565,7 +655,26 @@ let AuthController = class AuthController {
             retryableUnavailable();
         }
         const accountId = (0, canonical_hint_js_1.principalIdOf)(account);
+        const accountTenant = (0, auth_audit_js_1.tenantOfClaims)(account?.claims);
+        const accountLabel = accountId !== null ? 'known' : 'unknown';
         const loginKey = (0, canonical_hint_js_1.loginHintKey)(identityHint, accountId);
+        // ── CAPTCHA (auth capabilities R7.3, R7.4) ── decided on the resolved account, the typed text
+        // and the client IP, and verified BEFORE the account budget is spent and before any password
+        // hash. A missing or failed challenge answers the same 401 + `captcha: 'required'` for known
+        // and unknown names (X2). This attempt stays counted against the client IP (a failed
+        // challenge is a failed attempt from that client); the account budget is untouched, so a
+        // stranger without a token cannot lock the account through this gate.
+        const captchaSubject = {
+            accountId,
+            tenantId: accountTenant,
+            typedText: identityHint,
+            ip: this.perIpEnabled() ? ip : null,
+        };
+        if (this.captchaGate?.covers('login') === true) {
+            const verdict = await this.captchaGate.check('login', captchaSubject, body?.captchaToken, ip);
+            if (verdict.kind === 'failed')
+                loginUnauthorized(true);
+        }
         let hintVerdict;
         try {
             hintVerdict = await consumeOrUnavailable(this.loginLimiter, loginKey);
@@ -580,8 +689,10 @@ let AuthController = class AuthController {
             // is audited ONCE on the TRANSITION instead — in the wrong-password branch below,
             // when the attempt's count equals the threshold (feature #140 audit-on-the-edge).
             // An attempt refused by the account lock is not an IP failure (as before #10).
+            // R12.4: still a failed sign-in for the counter (no row: the lockout row was written once).
             await refundIp();
-            genericUnauthorized();
+            (0, auth_audit_js_1.countLoginFailure)('password', accountLabel);
+            loginUnauthorized(await this.captchaAfterFailure('login', captchaSubject));
         }
         let result;
         try {
@@ -602,12 +713,14 @@ let AuthController = class AuthController {
         if (result.outcome === 'authenticated') {
             // Correct password → clear the login counter (do not carry earlier failures).
             await this.loginLimiter?.reset(loginKey);
+            await this.captchaGate?.recordSuccess('login', captchaSubject);
             const principal = requirePrincipal(result);
             const est = await this.establishOrReject(principal);
-            await this.bindSession(est, principal);
+            const restricted = await this.bindSession(est, principal);
+            this.auditSignIn(principal, 'password');
             // Inline the caller's auth-facts so the permission-gated nav is ready the instant
             // login returns (one round-trip). Best-effort — omitted on any projection failure.
-            return this.sessionSuccessWithFacts(est, principal);
+            return this.sessionSuccessWithFacts(est, principal, restricted);
         }
         if (result.outcome === 'mfa_required') {
             // Password verified, a second factor is outstanding. NOT a failure — but NOT a
@@ -615,6 +728,8 @@ let AuthController = class AuthController {
             // so a stolen password cannot loop login→mfa to guess TOTP codes for free. This
             // attempt's own count is given back (Phase 9 #10), leaving earlier failures intact.
             await this.loginLimiter?.refund(loginKey);
+            // R7.3: the password was right; the CAPTCHA counters track password failures only.
+            await this.captchaGate?.recordSuccess('login', captchaSubject);
             //
             // 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.
@@ -626,6 +741,8 @@ let AuthController = class AuthController {
                 principalId: accountId,
                 identityHint,
                 credentialFingerprint: (0, mfa_step_up_js_1.credentialFingerprint)(account),
+                // R12.2: the tenant of a failed second-factor audit row (resolved server-side).
+                ...(accountTenant !== null ? { tenantId: accountTenant } : {}),
             };
             let challengeToken;
             try {
@@ -649,19 +766,31 @@ let AuthController = class AuthController {
             retryableUnavailable();
         }
         // A genuine wrong-password deny: the attempt was already counted by `consume` and
-        // stays counted. When its count 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 gate above (which would flood).
+        // stays counted (R12.4 counter, known/unknown). R12.3: a resolved account writes ONE
+        // `auth.login.failed` row per limiter window (the attempt that opened it); an unknown name
+        // writes none.
+        (0, auth_audit_js_1.countLoginFailure)('password', accountLabel);
+        if (accountId !== null && accountTenant !== null && (0, auth_audit_js_1.opensFailureWindow)(hintVerdict)) {
+            this.auditFailure(accountId, accountTenant, 'password');
+        }
+        // When its count 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 gate above (which would flood). R12.2/R12.3: the row names the RESOLVED
+        // account, never the typed hint; an unknown name only counts.
         // 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 && hintVerdict?.count === this.loginLimiter.maxAttempts) {
-            this.recordSecurityEvent({
-                action: 'auth.login.locked',
-                identityHint,
-                attributes: { reason: 'rate_limit' },
-                notify: false,
-            });
+            (0, auth_audit_js_1.countLockout)('password', accountLabel);
+            if (accountId !== null && accountTenant !== null) {
+                this.recordSecurityEvent({
+                    action: 'auth.login.locked',
+                    actorId: accountId,
+                    tenantId: accountTenant,
+                    attributes: { reason: 'rate_limit' },
+                    notify: false,
+                });
+            }
         }
         // #5: the failure also stays counted against the client IP (failures only — a success
         // gives its attempt back and never resets this counter, so an attacker's own valid
@@ -669,6 +798,7 @@ let AuthController = class AuthController {
         // spans many accounts).
         if (ipLimiter != null && ipVerdict !== null) {
             if (ipVerdict.count === ipLimiter.maxAttempts) {
+                (0, auth_audit_js_1.countLockout)('password', 'ip');
                 this.recordSecurityEvent({
                     action: 'auth.login.ip_locked',
                     identityHint: null,
@@ -677,7 +807,22 @@ let AuthController = class AuthController {
                 });
             }
         }
-        genericUnauthorized();
+        // R7.3: count the failure toward the CAPTCHA counters; flag the 401 once the next attempt
+        // needs a challenge (same for known and unknown names).
+        loginUnauthorized(await this.captchaAfterFailure('login', captchaSubject));
+    }
+    /**
+     * `GET /auth/login-options` (auth capabilities R7.3, R13.2, AC-23) — what the sign-in page needs
+     * before a session exists: the accepted sign-in forms and the public CAPTCHA settings
+     * (`{ provider, siteKey, mode }`, or `null` when CAPTCHA is off). Never the secret. `@Public()`:
+     * pre-session, reveals nothing about any account.
+     */
+    loginOptions() {
+        const signInWith = this.signInWith ?? ['email'];
+        return {
+            signInWith: [...signInWith],
+            captcha: this.captchaGate ? { ...this.captchaGate.publicOptions } : null,
+        };
     }
     /**
      * `GET /auth/me` — the signed-in user's **display profile** (name, email, active
@@ -706,10 +851,12 @@ let AuthController = class AuthController {
             // Auth surface is up but request-auth isn't wired — cannot authenticate.
             throw new common_1.HttpException({ error: 'unauthorized' }, common_1.HttpStatus.UNAUTHORIZED);
         }
-        const principal = await (0, request_principal_js_1.resolveRequestPrincipal)(authorization, this.tokenBinder);
-        if (principal === null) {
+        // Auth capabilities R2.5: the mandatory-2FA recompute runs here too (a version move only).
+        const resolved = await (0, request_principal_js_1.resolveRequestAuth)(authorization, this.tokenBinder, undefined, this.mfaRequirement);
+        if (resolved === null) {
             throw new common_1.HttpException({ error: 'unauthorized' }, common_1.HttpStatus.UNAUTHORIZED);
         }
+        const { principal, claims } = resolved;
         // 2) Resolve the display profile via the consumer seam. No seam → honest 501.
         // (The provider binds `null` when the consumer supplied none, so check nullish.)
         if (this.profileResolver === undefined || this.profileResolver === null) {
@@ -729,6 +876,12 @@ let AuthController = class AuthController {
             // login). 404 — never fall back to returning the raw ids.
             throw new common_1.HttpException({ error: 'profile_not_found' }, common_1.HttpStatus.NOT_FOUND);
         }
+        // R2.4: the grace deadline for the enrolment banner, as an ISO-8601 instant (UTC), only while
+        // one is bound (a passed one is still returned: the session is restricted from then on).
+        const deadline = claims.mfaEnrollmentDeadlineMs;
+        if (typeof deadline === 'number' && Number.isFinite(deadline)) {
+            return { ...profile, mfaEnrollmentDeadline: new Date(deadline).toISOString() };
+        }
         return profile;
     }
     /**
@@ -772,10 +925,20 @@ let AuthController = class AuthController {
         if (token === null) {
             throw new common_1.HttpException({ error: 'unauthorized' }, common_1.HttpStatus.UNAUTHORIZED);
         }
-        const claims = await this.tokenBinder.resolve(token);
-        if (claims === null) {
+        const resolvedClaims = await this.tokenBinder.resolve(token);
+        if (resolvedClaims === null) {
             throw new common_1.HttpException({ error: 'unauthorized' }, common_1.HttpStatus.UNAUTHORIZED);
         }
+        // Auth capabilities R2.5: the mandatory-2FA recompute (a version move only; 503 on failure).
+        const claims = this.mfaRequirement !== undefined && this.mfaRequirement !== null
+            ? await this.mfaRequirement.refresh(token, resolvedClaims)
+            : resolvedClaims;
+        // R15.2 (F9): a restricted session (re-enrol, or mandatory 2FA: D-2) may not change its scope.
+        // `@Public()` routes are not covered by the guard's gate, so the check lives here (same bodies).
+        const restriction = (0, session_restriction_js_1.restrictionOf)(claims, Date.now());
+        if (restriction !== null) {
+            throw new common_1.HttpException({ error: (0, session_restriction_js_1.restrictionErrorCode)(restriction) }, common_1.HttpStatus.FORBIDDEN);
+        }
         // Phase 11 #1 / KI #79: only a canonical uuid is checked and BOUND. The membership check is SQL
         // (`utf8mb4_unicode_ci` ignores case, trailing spaces and width), so any other spelling would
         // pass the gate and be bound as the session's tenant in the caller's spelling — its
@@ -913,7 +1076,8 @@ let AuthController = class AuthController {
         // 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.meterAndDeliverReset(hint, ipAllowed).catch(() => {
+            const captchaToken = body?.captchaToken;
+            void this.meterAndDeliverReset(hint, ipAllowed, ip, captchaToken).catch(() => {
                 /* swallow — anti-enumeration: never let a store/email failure be observable */
             });
         }
@@ -930,7 +1094,7 @@ let AuthController = class AuthController {
      *  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) {
+    async meterAndDeliverReset(hint, ipAllowed, ip, captchaToken) {
         const resolver = this.credentialResolver;
         let resolved = null;
         let lookupFailed = false;
@@ -959,6 +1123,23 @@ let AuthController = class AuthController {
                 });
             }
         }
+        // R7.2–R7.4: the CAPTCHA gate runs here, detached like the rest of the found-path work, so
+        // neither the challenge decision nor the provider call shows in the 204's timing. Every
+        // request counts toward the forgot counters (a request-rate cap); a missing or failed
+        // challenge does no work (still 204, counted).
+        const gate = this.captchaGate;
+        if (gate !== undefined && gate !== null && gate.covers('forgot_password')) {
+            const subject = {
+                accountId: principalId,
+                tenantId: (0, auth_audit_js_1.tenantOfClaims)(resolved?.claims),
+                typedText: hint,
+                ip: this.perIpEnabled() ? (ip ?? null) : null,
+            };
+            const verdict = await gate.check('forgot_password', subject, captchaToken, ip);
+            await gate.recordFailure('forgot_password', subject);
+            if (verdict.kind === 'failed')
+                return;
+        }
         const store = this.resetTokenStore;
         const sender = this.emailSender;
         if (!ipAllowed || !hintAllowed || lookupFailed || resolved === null || !principalId)
@@ -1057,6 +1238,16 @@ let AuthController = class AuthController {
             hasher === undefined) {
             throw new common_1.HttpException({ error: 'not_available' }, common_1.HttpStatus.NOT_IMPLEMENTED);
         }
+        // R7.2–R7.4: the CAPTCHA gate runs BEFORE the reset token is used (and before any hash). Its
+        // only counter is the client IP (no account is known before the token is consumed), so
+        // adaptive mode needs an explicit `trust proxy`; `always` works without it. A missing or
+        // failed challenge answers the bad-token 400 plus `captcha: 'required'`.
+        const resetSubject = { ip: this.perIpEnabled() ? ip : null };
+        if (this.captchaGate?.covers('reset_password') === true) {
+            const verdict = await this.captchaGate.check('reset_password', resetSubject, body?.captchaToken, ip);
+            if (verdict.kind === 'failed')
+                invalidResetToken(true);
+        }
         // Consume the token (single-use, TTL-checked). Unknown/expired/consumed → 400.
         const principalId = await store.consume(sha256(token));
         if (principalId === null) {
@@ -1078,7 +1269,7 @@ let AuthController = class AuthController {
                     });
                 }
             }
-            throw new common_1.HttpException({ error: 'invalid_token' }, common_1.HttpStatus.BAD_REQUEST);
+            invalidResetToken(await this.captchaAfterFailure('reset_password', resetSubject));
         }
         const newHash = await hasher.hash(newPassword);
         await writer.setPassword(principalId, newHash);
@@ -1184,8 +1375,15 @@ let AuthController = class AuthController {
             retryableUnavailable();
         }
         if (outcome.outcome !== 'authenticated' || outcome.principal.id !== pending.principalId) {
+            // R12.3/R12.4: count it; one `auth.login.failed` row per window (the challenge proves the
+            // password step, so the account is resolved; its tenant came from that step).
+            (0, auth_audit_js_1.countLoginFailure)('totp', 'known');
+            if (pending.tenantId !== undefined && (0, auth_audit_js_1.opensFailureWindow)(verdict)) {
+                this.auditFailure(pending.principalId, pending.tenantId, 'totp');
+            }
             // The attempt stays counted; the edge (count === threshold) audits ONCE.
             if (this.mfaLimiter != null && verdict?.count === this.mfaLimiter.maxAttempts) {
+                (0, auth_audit_js_1.countLockout)('totp', 'known');
                 this.recordSecurityEvent({
                     action: 'auth.mfa.locked',
                     actorId: pending.principalId,
@@ -1197,11 +1395,12 @@ let AuthController = class AuthController {
         }
         const principal = outcome.principal;
         const est = await this.establishOrReject(principal);
-        await this.bindSession(est, principal);
+        const restricted = await this.bindSession(est, principal);
         await this.mfaLimiter?.reset(mfaKey);
         await this.loginLimiter?.reset((0, canonical_hint_js_1.loginHintKey)(pending.identityHint, pending.principalId));
+        this.auditSignIn(principal, 'totp');
         // Same inline-facts enrichment as the password-login success (one round-trip).
-        return this.sessionSuccessWithFacts(est, principal);
+        return this.sessionSuccessWithFacts(est, principal, restricted);
     }
     /**
      * The `/auth/mfa` RECOVERY-CODE branch (spec §3). The lost-device user completes
@@ -1253,6 +1452,12 @@ let AuthController = class AuthController {
         // 401 (never surface a store error as a distinct outcome).
         const ok = await this.recoveryCodes.consume(principalId, code).catch(() => false);
         if (!ok) {
+            // R12.3/R12.4: count it; one `auth.login.failed` row per window for the resolved account.
+            (0, auth_audit_js_1.countLoginFailure)('recovery_code', 'known');
+            const recoveryTenant = (0, auth_audit_js_1.tenantOfClaims)(claims);
+            if (recoveryTenant !== null && (0, auth_audit_js_1.opensFailureWindow)(verdict)) {
+                this.auditFailure(principalId, recoveryTenant, 'recovery_code');
+            }
             // A wrong (or unmatched) recovery code → the attempt stays counted, THEN the
             // identical generic 401. When its count equals the threshold this attempt TRIPPED
             // the lockout — audit `auth.mfa.recovery_locked` exactly ONCE on that edge (never on
@@ -1261,6 +1466,7 @@ let AuthController = class AuthController {
             // emailing on every recovery lockout would let an attacker email-bomb the owner —
             // audit-only is safer; the once-per-window edge already dedups it.
             if (this.recoveryLimiter != null && verdict?.count === this.recoveryLimiter.maxAttempts) {
+                (0, auth_audit_js_1.countLockout)('recovery_code', 'known');
                 this.recordSecurityEvent({
                     action: 'auth.mfa.recovery_locked',
                     actorId: principalId,
@@ -1298,7 +1504,7 @@ let AuthController = class AuthController {
         // 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.
-        await this.bindSession(est, principal, true);
+        const restricted = await this.bindSession(est, principal, true);
         // Notify + audit (spec §6) via the REUSABLE security-event seam (feature #140):
         // records `mfa.recovery_used` AND notifies the account owner, BOTH fire-and-forget +
         // best-effort. A throwing/slow sink or sender NEVER fails the (legitimate) login
@@ -1311,11 +1517,10 @@ let AuthController = class AuthController {
             tenantId: principal.tenantId,
             notify: true,
         });
-        // Inline auth-facts here too (one round-trip), alongside the recovery-used flag. The
-        // session is enforced-re-enroll-restricted, but the frontend still seeds its facts
-        // from this projection (fail-closed: `principalFromClaims` forced isRoot:false, so no
-        // control-plane keys leak into a recovery session).
-        return this.sessionSuccessWithFacts(est, principal, { mfaRecoveryUsed: true });
+        this.auditSignIn(principal, 'recovery_code');
+        // The session is enforced-re-enroll-restricted, so no inline auth-facts (review round 1,
+        // item C): the frontend reads the restricted shape from `/identity/auth-facts`.
+        return this.sessionSuccessWithFacts(est, principal, restricted, { mfaRecoveryUsed: true });
     }
     /**
      * Fire-and-forget security notice for a recovery-code login (spec §6.1). Resolves the
@@ -1360,6 +1565,34 @@ let AuthController = class AuthController {
             /* best-effort: a resolver/email failure never fails the login */
         });
     }
+    /** R12.2: `auth.login.succeeded` for an established session (fire-and-forget). */
+    auditSignIn(principal, method) {
+        (0, auth_audit_js_1.emitAuthAudit)(this.auditSink, (0, auth_audit_js_1.authEvent)(auth_audit_js_1.AUTH_LOGIN_SUCCEEDED, principal.id, principal.tenantId, { method }));
+    }
+    /** R12.2/R12.3: `auth.login.failed` for a RESOLVED account (the caller bounds it per window). */
+    auditFailure(actorId, tenantId, method) {
+        (0, auth_audit_js_1.emitAuthAudit)(this.auditSink, (0, auth_audit_js_1.authEvent)(auth_audit_js_1.AUTH_LOGIN_FAILED, actorId, tenantId, { method }));
+    }
+    /**
+     * The durable session `logout` is about to end, when it is ACTIVE and a sink is bound; else
+     * `null` (no row). A store error → `null` (the logout itself is unaffected).
+     */
+    async activeSessionForAudit(sessionId) {
+        if (this.auditSink === undefined || this.auditSink === null)
+            return null;
+        if (this.sessionRecords === undefined || this.sessionRecords === null || sessionId === '') {
+            return null;
+        }
+        try {
+            const record = await this.sessionRecords.findSessionById(sessionId);
+            return record !== null && record.status === 'active'
+                ? { principalId: record.principalId, tenantId: record.tenantId }
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Record an auth-SECURITY event (best-effort, fire-and-forget) and OPTIONALLY notify
      * the account owner. The REUSABLE audit+notify primitive (feature #140) — it
@@ -1570,7 +1803,11 @@ let AuthController = class AuthController {
         }
         if (durableFacts.accountActive !== true)
             return false;
-        const restricted = durableFacts.mustReenroll !== false;
+        // Decision (1): `s_restriction ?? (s_must_reenroll ? 'reenroll' : null)`.
+        const restricted = durableFacts.mustReenroll !== false || durableFacts.restriction === 'reenroll';
+        // D-2: the mandatory-2FA restriction survives the rebuild. The rebuilt binding carries no
+        // requirement stamp, so its first request re-evaluates (and restores a grace deadline).
+        const mfaRestricted = !restricted && durableFacts.restriction === 'mfa_enrollment';
         const claims = {
             id: principalId,
             tenantId,
@@ -1579,6 +1816,7 @@ let AuthController = class AuthController {
             isRoot: !restricted && Array.isArray(this.rootIds) && this.rootIds.includes(principalId),
             sessionId,
             mustReenroll: restricted,
+            ...(mfaRestricted ? { restriction: 'mfa_enrollment' } : {}),
             ...(fresh.facts ? { cachedFacts: (0, session_token_binder_js_1.factsSlot)(fresh.facts) } : {}),
             ...(fresh.subtree !== undefined && fresh.subtree.length > 0
                 ? { scopeSubtreeNodeIds: [...fresh.subtree] }
@@ -1612,17 +1850,47 @@ let AuthController = class AuthController {
         }
     }
     /**
-     * `POST /auth/logout` — revoke the session. Idempotent + leak-free: revoking an
-     * unknown or already-revoked session still returns 204 (the engine's `revoke`
-     * swallows and returns void either way), so existence is never revealed.
+     * `POST /auth/logout` — revoke the session the caller proves it owns (R15.1, D-9).
+     * Proof is a bearer access token bound to `sessionId` or a refresh token of it
+     * ({@link LogoutProofVerifier}):
+     *  - proven → revoke + unbind;
+     *  - proof for another session, or an unknown/invalid token → revoke nothing;
+     *  - no proof (an old frontend), or a proof lookup outage → revoke only while
+     *    `logoutRequiresProof` is false (counted `auth.logout.unproven`, one deprecation warning);
+     *    strict mode revokes nothing (fail closed).
+     * Always 204 — never a 500, never an existence or ownership signal. Tokens are never logged.
      */
-    async logout(body) {
+    async logout(body, authorization) {
         const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : '';
-        // `revoke` is void + best-effort-idempotent by contract; it never throws a
-        // resource-existence signal. We still guard against an unexpected throw so a
-        // logout never 500s (which could itself be an existence oracle).
         try {
+            const accessToken = (0, request_principal_js_1.extractBearerToken)(authorization);
+            const refreshToken = typeof body?.refreshToken === 'string' && body.refreshToken !== ''
+                ? body.refreshToken
+                : null;
+            const proof = this.logoutProof !== undefined && this.logoutProof !== null
+                ? await this.logoutProof.verify(sessionId, accessToken, refreshToken)
+                : accessToken === null && refreshToken === null
+                    ? 'none'
+                    : 'unavailable';
+            if (proof === 'mismatch')
+                return;
+            if (proof !== 'proven') {
+                // 'none' or 'unavailable': strict mode fails closed; compatibility mode keeps today's revoke.
+                if (this.logoutRequiresProof === true)
+                    return;
+                (0, logout_proof_js_1.recordUnprovenLogout)();
+            }
+            // R12.2: read the session before revoking, so `auth.logout` is written only when an ACTIVE
+            // session ends, attributed to its own principal and tenant (never the request). Only with a
+            // sink bound; logout is a lifecycle event, so this one read is allowed (ADR-0013).
+            const ending = await this.activeSessionForAudit(sessionId);
+            // `revoke` is void + best-effort-idempotent by contract; it never throws a
+            // resource-existence signal. We still guard against an unexpected throw so a
+            // logout never 500s (which could itself be an existence oracle).
             await this.sessionAuthority.revoke(sessionId);
+            if (ending !== null) {
+                (0, auth_audit_js_1.emitAuthAudit)(this.auditSink, (0, auth_audit_js_1.logoutEvent)(ending.principalId, ending.tenantId, proof === 'proven'));
+            }
             // Drop the session-claims cushion so a post-logout rotate can't re-mint a
             // binding (the session is revoked anyway; this is defense-in-depth).
             if (this.tokenBinder !== undefined)
@@ -1658,6 +1926,13 @@ __decorate([
     __metadata("design:paramtypes", [Object, String]),
     __metadata("design:returntype", Promise)
 ], AuthController.prototype, "login", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Get)('login-options'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Object)
+], AuthController.prototype, "loginOptions", null);
 __decorate([
     (0, classification_decorator_js_1.Public)(),
     (0, common_1.Get)('me'),
@@ -1720,8 +1995,9 @@ __decorate([
     (0, common_1.Post)('logout'),
     (0, common_1.HttpCode)(common_1.HttpStatus.NO_CONTENT),
     __param(0, (0, common_1.Body)()),
+    __param(1, (0, common_1.Headers)('authorization')),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
+    __metadata("design:paramtypes", [Object, String]),
     __metadata("design:returntype", Promise)
 ], AuthController.prototype, "logout", null);
 exports.AuthController = AuthController = __decorate([
@@ -1790,7 +2066,17 @@ exports.AuthController = AuthController = __decorate([
     __param(32, (0, common_1.Inject)(tokens_js_1.SHIELD_EMAIL_CHANGE_TOKEN_STORE)),
     __param(33, (0, common_2.Optional)()),
     __param(33, (0, common_1.Inject)(tokens_js_1.SHIELD_MESSAGE_DISPATCHER)),
-    __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, Object, Object])
+    __param(34, (0, common_2.Optional)()),
+    __param(34, (0, common_1.Inject)(logout_proof_js_1.SHIELD_LOGOUT_PROOF_VERIFIER)),
+    __param(35, (0, common_2.Optional)()),
+    __param(35, (0, common_1.Inject)(logout_proof_js_1.SHIELD_LOGOUT_REQUIRES_PROOF)),
+    __param(36, (0, common_2.Optional)()),
+    __param(36, (0, common_1.Inject)(tokens_js_3.SHIELD_MFA_REQUIREMENT)),
+    __param(37, (0, common_2.Optional)()),
+    __param(37, (0, common_1.Inject)(tokens_js_3.SHIELD_CAPTCHA_GATE)),
+    __param(38, (0, common_2.Optional)()),
+    __param(38, (0, common_1.Inject)(tokens_js_3.SHIELD_SIGN_IN_WITH)),
+    __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, Object, Object, Object, Object, Object, Object, Object])
 ], AuthController);
 /**
  * Narrow an `authenticated` result to its guaranteed principal. The core engine