@astram/guard 0.1.1 → 0.3.0

package/dist/auth/auth.controller.js

@@ -0,0 +1,1091 @@
+"use strict";
+/**
+ * Phase 0b Auth-surface — the framework-owned **`/auth/*` HTTP controllers**
+ * (spec §2). A consumer app gets login + MFA + refresh + logout FOR FREE by
+ * importing `ShieldModule.forRoot()` (which imports `AuthModule`); it writes no
+ * auth code. All four routes are `@Public()` (ADR-0002): they run BEFORE the
+ * caller has a session, so the global deny-by-default guard must NOT gate them.
+ *
+ * This controller is a THIN transport shim over the two composed core engines
+ * (`SHIELD_AUTHENTICATOR` / `SHIELD_SESSION_AUTHORITY`, from Team B). It holds NO
+ * business logic beyond mapping engine outcomes → HTTP status + the frozen DTO
+ * shapes (`./dto.ts`). Every security invariant is enforced here per the DTO
+ * header + the spec:
+ *
+ * ── OUTCOME → HTTP STATUS MAP (the security contract) ────────────────────────
+ *   login authenticated        → 200  SessionSuccess { session(no-secret), tokens }
+ *   login mfa_required          → 200  MfaChallengeResponse { mfaRequired, challengeToken }
+ *   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   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)
+ *   logout                      → 204  (idempotent; unknown/already-revoked → still 204)
+ *
+ * ── ANTI-ENUMERATION ── login + mfa failures are a SINGLE generic 401 with an
+ *   identical body (`{ error: 'invalid_credentials' }`) whether the user is
+ *   unknown, the password is wrong, or the factor is wrong/expired. The core
+ *   authenticator's decoy-verify already equalizes timing; this layer never adds a
+ *   distinguishing field/status.
+ *
+ * ── NO SECRET LEAK ── no password, hash, TOTP secret, raw token (beyond the two a
+ *   success legitimately mints), or challenge internal ever appears in a body or a
+ *   log. Request bodies are NEVER logged. The `SessionView` mapped from the core
+ *   `Session` carries no secret by construction.
+ *
+ * ── TRANSIENT ≠ DENY (ADR-0016) ── a transient `authentication_unavailable` from
+ *   the authenticator becomes a RETRYABLE 503, never a 401 — a dependency blip must
+ *   not look like (or trigger the client to treat it as) a credential failure.
+ *   ⚠ ENGINE-SEAM LIMIT on /auth/refresh: the core `SessionAuthority.rotate`
+ *   collapses BOTH a terminal deny AND a transient store outage into one
+ *   `SessionRejectedError` (its top-level fail-closed catch — see
+ *   session-authority.ts). From THIS seam the two are indistinguishable, so refresh
+ *   maps the generic reject to 401. Surfacing a retryable-503 on a refresh-time
+ *   store outage would require the engine to expose a transient signal it does not
+ *   today — flagged to the architect as a possible core-API gap (NOT worked around
+ *   here; we do not invent a core API).
+ *
+ * ADR-0023: composition is the framework's job — this controller only CONSUMES the
+ * composed engines via DI tokens; it never news-up an engine or an adapter.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthController = void 0;
+const common_1 = require("@nestjs/common");
+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 pending_mfa_store_js_1 = require("./pending-mfa-store.js");
+const tokens_js_2 = require("../request-auth/tokens.js");
+const request_principal_js_1 = require("../request-auth/request-principal.js");
+const tokens_js_3 = require("./tokens.js");
+/**
+ * The core `Authenticator`'s generic transient reason (see authenticator.ts —
+ * `REASON_AUTH_UNAVAILABLE`). A `rejected` result carrying THIS reason is the
+ * ADR-0016 transient signal → 503; any OTHER rejected reason is a credential deny
+ * → generic 401.
+ */
+const REASON_AUTH_UNAVAILABLE = 'authentication_unavailable';
+/**
+ * The SINGLE generic body for EVERY login/mfa/refresh failure. Deliberately
+ * non-distinguishing (anti-enumeration): unknown user, wrong password, wrong/
+ * expired/forged factor, and a rejected refresh ALL return this identical body.
+ * Carries NO reason detail that could leak which check failed.
+ */
+const GENERIC_AUTH_FAILURE = Object.freeze({ error: 'invalid_credentials' });
+/** The generic retryable body for a transient dependency outage (ADR-0016). */
+const RETRYABLE_BODY = Object.freeze({ error: 'authentication_unavailable' });
+/** Password-reset token time-to-live: 30 minutes (spec §4.1). */
+const RESET_TTL_MS = 30 * 60 * 1000;
+/** Minimum acceptable new-password length on reset (matches change-password). */
+const MIN_PASSWORD_LEN = 8;
+/**
+ * SHA-256 of the raw reset token. The token store only ever sees this HASH — the raw
+ * token lives only in the emailed link + the reset request (never persisted).
+ */
+function sha256(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(value).digest('hex');
+}
+/** Throw the generic 401 (indistinguishable across all credential-failure paths). */
+function genericUnauthorized() {
+    throw new common_1.HttpException(GENERIC_AUTH_FAILURE, common_1.HttpStatus.UNAUTHORIZED);
+}
+/** 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);
+}
+/**
+ * The generic 429 for a rate-limited RESET-password (feature #141). Reset is
+ * token-gated (a 256-bit single-use token), NOT enumeration-sensitive, so surfacing
+ * "too many requests" is safe (unlike forgot-password, which stays 204). Carries no
+ * detail beyond the neutral throttle signal.
+ */
+function tooManyRequests() {
+    throw new common_1.HttpException({ error: 'too_many_requests' }, common_1.HttpStatus.TOO_MANY_REQUESTS);
+}
+/**
+ * Map a core `Session` → the client-safe {@link SessionView}. Copies ONLY the
+ * non-secret lifecycle fields the DTO allows — there is no token/hash on `Session`
+ * to begin with, but this explicit projection guarantees no future `Session` field
+ * leaks into a response body by accident.
+ */
+function toSessionView(session) {
+    return {
+        sessionId: session.sessionId,
+        principalId: session.principalId,
+        tenantId: session.tenantId,
+        status: session.status,
+        issuedAtMs: session.issuedAtMs,
+        expiresAtMs: session.expiresAtMs,
+    };
+}
+/** Map a core `SessionEstablishment` → the {@link SessionSuccess} success body. */
+function toSessionSuccess(est) {
+    return {
+        session: toSessionView(est.session),
+        tokens: {
+            accessToken: est.tokens.accessToken,
+            refreshToken: est.tokens.refreshToken,
+        },
+    };
+}
+/** Build the password credential the authenticator expects. */
+function passwordCredential(password) {
+    return { factor: 'password', payload: { password } };
+}
+/** Build the TOTP credential the authenticator's factor verifier expects (payload.code). */
+function totpCredential(code) {
+    return { factor: 'totp', payload: { code } };
+}
+/**
+ * The framework-owned auth endpoints. Registered into `AuthModule`'s `controllers`
+ * by the integration owner / Team B (this controller is EXPORTED for that purpose;
+ * it does NOT edit auth.module.ts itself). Depends on the two composed engines +
+ * the pending-MFA store (provided alongside it).
+ */
+let AuthController = class AuthController {
+    authenticator;
+    sessionAuthority;
+    pendingMfa;
+    tokenBinder;
+    profileResolver;
+    credentialResolver;
+    resetTokenStore;
+    emailSender;
+    credentialWriter;
+    sessionSweeper;
+    passwordHasher;
+    resetLinkBaseUrl;
+    recoveryCodes;
+    loginLimiter;
+    recoveryLimiter;
+    forgotLimiter;
+    forgotHintLimiter;
+    resetLimiter;
+    auditSink;
+    sessionFactsProjector;
+    constructor(authenticator, sessionAuthority, pendingMfa, tokenBinder, profileResolver, credentialResolver, resetTokenStore, emailSender, credentialWriter, sessionSweeper, passwordHasher, resetLinkBaseUrl, recoveryCodes, loginLimiter, recoveryLimiter, forgotLimiter, forgotHintLimiter, resetLimiter, auditSink, sessionFactsProjector) {
+        this.authenticator = authenticator;
+        this.sessionAuthority = sessionAuthority;
+        this.pendingMfa = pendingMfa;
+        this.tokenBinder = tokenBinder;
+        this.profileResolver = profileResolver;
+        this.credentialResolver = credentialResolver;
+        this.resetTokenStore = resetTokenStore;
+        this.emailSender = emailSender;
+        this.credentialWriter = credentialWriter;
+        this.sessionSweeper = sessionSweeper;
+        this.passwordHasher = passwordHasher;
+        this.resetLinkBaseUrl = resetLinkBaseUrl;
+        this.recoveryCodes = recoveryCodes;
+        this.loginLimiter = loginLimiter;
+        this.recoveryLimiter = recoveryLimiter;
+        this.forgotLimiter = forgotLimiter;
+        this.forgotHintLimiter = forgotHintLimiter;
+        this.resetLimiter = resetLimiter;
+        this.auditSink = auditSink;
+        this.sessionFactsProjector = sessionFactsProjector;
+    }
+    /**
+     * 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
+     * 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);
+        // 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);
+        try {
+            await this.tokenBinder.bind(est.tokens.accessToken, {
+                id: principal.id,
+                tenantId: principal.tenantId,
+                roleIds: [...principal.roleIds],
+                kind: principal.kind,
+                isRoot: principal.isRoot === true,
+                sessionId: est.session.sessionId,
+                // Enforced-re-enroll flag (spec §4): TRUE only on the recovery-code login
+                // path (which passes it); all other logins default to FALSE.
+                mustReenroll,
+                // 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 } : {}),
+            }, 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).
+        }
+    }
+    /**
+     * 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
+     * forward, replace it, or strip it):
+     *   - `undefined` → NO projector wired → carry the existing `cachedFacts` forward.
+     *   - `null`      → projector present but yielded nothing (or threw) → STRIP the cache
+     *                   (→ next request DB-reloads; fail-closed).
+     *   - `CoarseGrants` → the fresh grants to cache.
+     * A throw collapses to `null` (fail-closed strip), never a login/refresh failure and
+     * never a fabricated grant.
+     */
+    async projectFactsFor(principalId, tenantId) {
+        const projector = this.sessionFactsProjector;
+        if (projector === undefined || projector === null)
+            return undefined;
+        try {
+            return await projector.project(principalId, tenantId);
+        }
+        catch {
+            // Fail-closed: a projection outage → strip/omit the cache → gate 5 DB-reloads.
+            return null;
+        }
+    }
+    /**
+     * Build a Principal directly from resolved internal claims (recovery/alt-factor
+     * paths that don't run the full authenticate() loop). Equivalent to the identity
+     * broker's internal-source normalize for this case — the credential resolver
+     * already returns canonical Internal-source claims (`id`, `tenantId`, `roleIds`),
+     * the same shape the TOTP success path's `requirePrincipal` yields. Returns
+     * `null` when `id`/`tenantId` are missing/malformed (→ the caller fails closed to
+     * a generic 401). `isRoot` is FORCED false here — a recovery login is
+     * never a source of elevated status (root is a broker/server-side decision,
+     * never a claim), matching the internal adapter's root-safety.
+     */
+    principalFromClaims(claims) {
+        const id = typeof claims.id === 'string' ? claims.id : '';
+        const tenantId = typeof claims.tenantId === 'string' ? claims.tenantId : '';
+        if (!id || !tenantId)
+            return null;
+        const roleIds = Array.isArray(claims.roleIds)
+            ? claims.roleIds.filter((r) => typeof r === 'string')
+            : [];
+        return { kind: 'user', id, tenantId, roleIds, isRoot: false };
+    }
+    /**
+     * `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) {
+        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))) {
+            // 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
+            // wrong-password branch below, when recordFailure's count first hits the threshold
+            // (feature #140 audit-on-the-edge, anti-flood).
+            genericUnauthorized();
+        }
+        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);
+            const principal = requirePrincipal(result);
+            const est = await this.establishOrReject(principal);
+            await this.bindSession(est, principal);
+            return toSessionSuccess(est);
+        }
+        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);
+            return { mfaRequired: true, challengeToken };
+        }
+        // outcome === 'rejected'. Distinguish ONLY transient-vs-deny (never which
+        // credential failed): a transient dependency blip is a retryable 503, anything
+        // else is the generic 401.
+        if (result.reason === REASON_AUTH_UNAVAILABLE) {
+            // A transient outage is NOT a credential failure — do NOT count it toward the
+            // lockout (avoids a Redis/DB blip storm from locking out everyone).
+            retryableUnavailable();
+        }
+        // A genuine wrong-password deny → count it toward the lockout window. recordFailure
+        // 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).
+        if (this.loginLimiter != null) {
+            const count = await this.loginLimiter.recordFailure(loginKey);
+            if (count === this.loginLimiter.maxAttempts) {
+                this.recordSecurityEvent({
+                    action: 'auth.login.locked',
+                    identityHint,
+                    attributes: { reason: 'rate_limit' },
+                    notify: false,
+                });
+            }
+        }
+        genericUnauthorized();
+    }
+    /**
+     * `GET /auth/me` — the signed-in user's **display profile** (name, email, active
+     * company name, role names) for the UI header/card. Fills the flagged gap: login
+     * returns only IDs, so without this a UI would either leak a raw UUID or show only
+     * the login hint.
+     *
+     * AUTH: this route is `@Public()` to the CLASSIFICATION guard (it is not an
+     * object-type permission — "read my own profile" has no typeKey to `decide()` on),
+     * but it authenticates the caller ITSELF: it resolves the bearer access token to a
+     * live `Principal` via the request-auth layer (the SAME liveness-gated path the
+     * enforcement guard uses). No/invalid/expired/revoked token → 401. So it is public
+     * only in the "not object-gated" sense — it is NOT unauthenticated.
+     *
+     * PROFILE: the framework is org-schema-agnostic, so it delegates id→name
+     * resolution to the consumer's {@link ProfileResolver} (the `profileResolver`
+     * seam). The resolver returns display NAMES (never raw UUIDs). Absent seam → 501
+     * (honest "not available"); resolver returns `null` (deleted user) → 404; resolver
+     * throws (store outage) → generic 500 (fail-closed, never a partial profile).
+     */
+    async me(authorization) {
+        // 1) Authenticate: resolve the bearer token → a live Principal (fail-closed).
+        // Reuses the request-auth read path (token binding + session-liveness gate), so a
+        // logged-out/expired/revoked token is rejected here exactly as on a gated route.
+        if (this.tokenBinder === undefined) {
+            // 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) {
+            throw new common_1.HttpException({ error: 'unauthorized' }, common_1.HttpStatus.UNAUTHORIZED);
+        }
+        // 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) {
+            throw new common_1.HttpException({ error: 'profile_unavailable' }, common_1.HttpStatus.NOT_IMPLEMENTED);
+        }
+        let profile;
+        try {
+            profile = await this.profileResolver.resolve(principal);
+        }
+        catch {
+            // Store outage / resolver error → fail-closed generic 500 (never a partial or
+            // id-leaking profile). The UI keeps its interim hint fallback.
+            throw new common_1.HttpException({ error: 'profile_unavailable' }, common_1.HttpStatus.INTERNAL_SERVER_ERROR);
+        }
+        if (profile === null) {
+            // The principal has no resolvable profile (e.g. the user row was deleted since
+            // login). 404 — never fall back to returning the raw ids.
+            throw new common_1.HttpException({ error: 'profile_not_found' }, common_1.HttpStatus.NOT_FOUND);
+        }
+        return profile;
+    }
+    /**
+     * `POST /auth/forgot-password` — request a password-reset link. ALWAYS returns 204
+     * with an identical (empty) body whether or not the hint matches a principal
+     * (ANTI-ENUMERATION, spec §4.1): the response must reveal nothing about whether an
+     * account exists.
+     *
+     * ── TIMING ANTI-ENUMERATION ── a MATCHING hint does extra work (mint + hash token,
+     *   issue it to the store, resolve the email, send it) that an UNKNOWN hint skips —
+     *   a naive `await` of that work would make the matching branch measurably slower, a
+     *   timing oracle. So the found-path work is FIRE-AND-FORGET: `deliverResetLink` is
+     *   invoked WITHOUT `await`, and the handler returns 204 immediately, so BOTH
+     *   branches return in ~constant time. A `.catch` is attached to the detached
+     *   promise so a store/email rejection is swallowed (never an unhandled rejection,
+     *   never a distinguishing error).
+     *
+     * ── SEAMS ── needs the credentialResolver (hint→principalId), the resetTokenStore,
+     *   and the emailSender. Any absent → the whole found-path is skipped and we still
+     *   return 204 (a deployment without the reset seams simply never sends — never a
+     *   501 here, which would itself be an enumeration signal on hint validity).
+     */
+    async forgotPassword(body, ip) {
+        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.
+        // 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).
+        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));
+        // 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
+        // by the limiter's own best-effort recordFailure). NOT reset on "success" — forgot
+        // has no success signal, so the window is a pure rolling request-rate cap.
+        // `.catch` guards the DETACHED counter writes: the framework AttemptLimiter already
+        // swallows its own errors, but a consumer-injected limiter must never surface an
+        // unhandled rejection off this fire-and-forget path (never changes the 204).
+        // Count this request toward the IP budget; when the returned count first equals the
+        // limiter's threshold this request is the one that TRIPPED the throttle → audit
+        // `auth.forgot_password.throttled` exactly ONCE on that edge (feature #140). Detached
+        // + swallowed like the counter write itself: the audit is fire-and-forget and never
+        // changes the 204 (still returned below). NO notify — a forgot-throttle notice would
+        // 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
+            ?.recordFailure(ipKey)
+            .then((count) => {
+            if (this.forgotLimiter != null && count === this.forgotLimiter.maxAttempts) {
+                this.recordSecurityEvent({
+                    action: 'auth.forgot_password.throttled',
+                    identityHint: hint || null,
+                    attributes: { reason: 'rate_limit' },
+                    notify: false,
+                });
+            }
+        })
+            .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).
+        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(() => {
+                /* swallow — anti-enumeration: never let a store/email failure be observable */
+            });
+        }
+        // ALWAYS 204, immediately, identical body for every branch (found/unknown/throttled).
+    }
+    /**
+     * 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.
+     */
+    async deliverResetLink(hint, resolver, store, sender) {
+        const resolved = await resolver.resolve(hint);
+        if (resolved === null)
+            return; // unknown hint — no token, no email (still 204)
+        const claims = resolved.claims;
+        const principalId = typeof claims.id === 'string' ? claims.id : '';
+        if (!principalId)
+            return;
+        const tenantId = typeof claims.tenantId === 'string' ? claims.tenantId : '';
+        // Mint a raw token; the store only ever sees its SHA-256 hash.
+        const rawToken = (0, node_crypto_1.randomBytes)(32).toString('hex');
+        await store.issue(principalId, sha256(rawToken), Date.now() + RESET_TTL_MS);
+        // Resolve the recipient email via the profile resolver (returns display + email).
+        // No resolver / no email on file → issued the token but cannot deliver (still 204).
+        if (this.profileResolver === undefined || this.profileResolver === null)
+            return;
+        const profile = await this.profileResolver.resolve({
+            id: principalId,
+            tenantId,
+            roleIds: [],
+            kind: 'user',
+            isRoot: false,
+        });
+        if (!profile?.email)
+            return;
+        // The framework composes the link (EmailSender stays URL-agnostic).
+        const base = this.resetLinkBaseUrl ?? 'http://localhost:5173/reset-password';
+        const link = `${base}?token=${rawToken}`;
+        await sender.send({
+            to: profile.email,
+            subject: 'Reset your password',
+            text: `Reset your password: ${link}`,
+            html: `<p>Reset your password: <a href="${link}">${link}</a></p>`,
+        });
+    }
+    /**
+     * `POST /auth/reset-password` — complete a password reset with the emailed token.
+     *
+     * Outcomes:
+     *   • newPassword shorter than the minimum        → 422 `{ error: 'weak_password' }`
+     *   • resetTokenStore/credentialWriter/hasher absent → 501 `{ error: 'not_available' }`
+     *   • token unknown / expired / already-consumed  → 400 `{ error: 'invalid_token' }`
+     *   • success                                     → 204 (no body)
+     *
+     * On success: consume the token (single-use), hash + write the new password, then
+     * revoke ALL of the principal's sessions (reset kills every session, spec §5.1/§6)
+     * and invalidate any other outstanding reset tokens for the principal.
+     */
+    async resetPassword(body, ip) {
+        const token = typeof body?.token === 'string' ? body.token : '';
+        const newPassword = typeof body?.newPassword === 'string' ? body.newPassword : '';
+        // ── Rate-limit gate (feature #141) — DoS/abuse throttle, NOT anti-brute-force. ──
+        // Reset is token-gated (a 256-bit single-use token), so this is only to cap abusive
+        // request volume — and because a token-gated endpoint is NOT enumeration-sensitive,
+        // a locked-out caller MAY receive a generic 429 (unlike forgot-password, which stays
+        // 204). Checked BEFORE any token/seam work so a locked IP never touches the store.
+        // Fails OPEN on a Redis blip (a legitimate reset is never blocked by an outage).
+        // 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))) {
+            // 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
+            // below, when recordFailure's count first hits the threshold (audit-on-the-edge).
+            tooManyRequests();
+        }
+        if (newPassword.length < MIN_PASSWORD_LEN) {
+            throw new common_1.HttpException({ error: 'weak_password' }, common_1.HttpStatus.UNPROCESSABLE_ENTITY);
+        }
+        // Fail-closed when the reset seams are unplugged — honest "not available".
+        const store = this.resetTokenStore;
+        const writer = this.credentialWriter;
+        const hasher = this.passwordHasher;
+        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.
+        const principalId = await store.consume(sha256(token));
+        if (principalId === null) {
+            // A bad/invalid token is the ABUSE signal — count it toward the IP lockout, THEN
+            // the existing generic 400. (A valid reset never records a failure.) recordFailure
+            // returns the new count; when it first equals the threshold this bad-token attempt
+            // TRIPPED the lockout → audit `auth.password_reset.locked` exactly ONCE on that edge
+            // (never on the already-locked 429 gate above, which would flood; and NOT on every
+            // 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) {
+                    this.recordSecurityEvent({
+                        action: 'auth.password_reset.locked',
+                        attributes: { reason: 'rate_limit' },
+                        notify: false,
+                    });
+                }
+            }
+            throw new common_1.HttpException({ error: 'invalid_token' }, common_1.HttpStatus.BAD_REQUEST);
+        }
+        const newHash = await hasher.hash(newPassword);
+        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);
+        // Reset kills ALL sessions (unlike change-password, which keeps the current one).
+        if (this.sessionSweeper !== undefined && this.sessionSweeper !== null) {
+            await this.sessionSweeper.revokeAllForPrincipal(principalId);
+        }
+        // Burn any other outstanding reset tokens for the principal (single active reset).
+        await store.invalidateAllForPrincipal(principalId);
+    }
+    /**
+     * `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.
+     *   • `'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
+     *     `FactorVerifier`). See {@link completeViaRecoveryCode}.
+     *   • 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.
+     */
+    async mfa(body) {
+        const challengeToken = typeof body?.challengeToken === 'string' ? body.challengeToken : '';
+        const code = typeof body?.code === 'string' ? body.code : '';
+        const factor = body?.factor;
+        // Consume the pending challenge (single-use). A miss (unknown/forged/expired)
+        // 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);
+        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").
+        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);
+            return toSessionSuccess(est);
+        }
+        // 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) {
+            retryableUnavailable();
+        }
+        genericUnauthorized();
+    }
+    /**
+     * The `/auth/mfa` RECOVERY-CODE branch (spec §3). The lost-device user completes
+     * login with a pre-issued single-use recovery code instead of a TOTP.
+     *
+     * `pending` is the ALREADY-CONSUMED challenge (proof the password passed at
+     * `/auth/login` — §3: "the challenge IS proof of password"), so this branch does
+     * NOT re-verify the password, mirroring exactly how the TOTP branch trusts the
+     * challenge for the password and only checks the code.
+     *
+     * ── ANTI-ENUMERATION ── seam-absent, unknown hint, malformed claims, and a wrong
+     *   recovery code ALL raise the identical generic 401 — no path reveals whether
+     *   the user exists, has recovery codes, or which check failed.
+     *
+     * ── NO SAFEGUARDS YET ── rate-limit (Phase 3), `mustReenroll` (Phase 2), and
+     *   notify+audit (Phase 4) attach at the marked seams below.
+     */
+    async completeViaRecoveryCode(pending, code) {
+        // Seam must be present — no resolver or no recovery store → fail closed.
+        if (this.credentialResolver == null || this.recoveryCodes == null) {
+            genericUnauthorized();
+        }
+        // hint → principalId. A resolver that throws (store outage) OR returns null
+        // (unknown hint) is the SAME generic 401 (anti-enumeration; the resolver never
+        // distinguishes unknown-user from a blip to the caller).
+        const resolved = await this.credentialResolver.resolve(pending.identityHint).catch(() => null);
+        if (resolved == null)
+            genericUnauthorized();
+        const claims = resolved.claims;
+        const principalId = typeof claims.id === 'string' ? claims.id : '';
+        if (!principalId)
+            genericUnauthorized();
+        // Rate-limit gate (spec §5): after N failures within the window, reject BEFORE
+        // consulting the recovery store — the SAME generic 401 as a wrong code (no leak
+        // of "rate-limited"; the store is never even touched when locked). Keyed by the
+        // RESOLVED principalId (recovery codes don't rotate → a lower ceiling than login).
+        // Fails OPEN on a Redis blip (the limiter's own posture — never a lockout).
+        const recoveryKey = `recovery:${principalId}`;
+        if (this.recoveryLimiter != null && !(await this.recoveryLimiter.check(recoveryKey))) {
+            genericUnauthorized();
+        }
+        // Atomic single-use argon2-verify. A throw is swallowed to `false` → generic
+        // 401 (never surface a store error as a distinct outcome).
+        const ok = await this.recoveryCodes.consume(principalId, code).catch(() => false);
+        if (!ok) {
+            // A wrong (or unmatched) recovery code → count it toward the lockout window,
+            // THEN the identical generic 401. recordFailure returns the new count; when it
+            // first equals the threshold this attempt TRIPPED the lockout — audit
+            // `auth.mfa.recovery_locked` exactly ONCE on that edge (never on the already-locked
+            // check-gate above, which returns false on every attempt = flood).
+            // NO notify: a locked-out attacker is (by assumption) NOT the account owner, so
+            // 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) {
+                const count = await this.recoveryLimiter.recordFailure(recoveryKey);
+                if (count === this.recoveryLimiter.maxAttempts) {
+                    this.recordSecurityEvent({
+                        action: 'auth.mfa.recovery_locked',
+                        actorId: principalId,
+                        tenantId: typeof claims.tenantId === 'string' ? claims.tenantId : null,
+                        attributes: { reason: 'rate_limit' },
+                        notify: false,
+                    });
+                }
+            }
+            genericUnauthorized();
+        }
+        // A correct recovery code → clear the counter (do not carry earlier failures).
+        await this.recoveryLimiter?.reset(recoveryKey);
+        // 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);
+        // 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);
+        // 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
+        // (nothing here is awaited into the response, each swallows its own rejection). NO
+        // secret / code / token / uuid appears in either body — the audit carries only the
+        // actor id, tenant, and action; the notice is a neutral security warning.
+        this.recordSecurityEvent({
+            action: 'mfa.recovery_used',
+            actorId: principal.id,
+            tenantId: principal.tenantId,
+            notify: true,
+        });
+        return { ...toSessionSuccess(est), mfaRecoveryUsed: true };
+    }
+    /**
+     * Fire-and-forget security notice for a recovery-code login (spec §6.1). Resolves the
+     * recipient email via the already-injected {@link ProfileResolver} (the same seam
+     * forgot-password uses), then delivers a NEUTRAL "a recovery code was used to sign in"
+     * warning via {@link EmailSender}. Best-effort: NOT awaited by the caller, and it
+     * swallows every rejection so a missing email / resolver throw / send failure never
+     * fails the login. NO code / token / principal uuid is ever placed in the body — only
+     * the neutral notice the account owner needs to act on it.
+     */
+    notifyRecoveryUsed(principalId, tenantId) {
+        const resolver = this.profileResolver;
+        const sender = this.emailSender;
+        if (resolver === undefined || resolver === null || sender === undefined || sender === null) {
+            return; // no recipient lookup or no delivery seam → nothing to send (still logged-in)
+        }
+        void (async () => {
+            const profile = await resolver.resolve({
+                id: principalId,
+                tenantId,
+                roleIds: [],
+                kind: 'user',
+                isRoot: false,
+            });
+            if (!profile?.email)
+                return; // no email on file → cannot notify (login unaffected)
+            await sender.send({
+                to: profile.email,
+                subject: 'A recovery code was used to sign in',
+                text: 'A recovery code was just used to sign in to your account. ' +
+                    'If this was you, you can ignore this message. If this was NOT you, secure ' +
+                    'your account now: change your password and re-enroll a new authenticator device.',
+                html: '<p>A recovery code was just used to sign in to your account.</p>' +
+                    '<p>If this was you, you can ignore this message. If this was <strong>not</strong> ' +
+                    'you, secure your account now: change your password and re-enroll a new ' +
+                    'authenticator device.</p>',
+            });
+        })().catch(() => {
+            /* best-effort: a resolver/email failure never fails the login */
+        });
+    }
+    /**
+     * Record an auth-SECURITY event (best-effort, fire-and-forget) and OPTIONALLY notify
+     * the account owner. The REUSABLE audit+notify primitive (feature #140) — it
+     * generalizes the two inlined blocks that {@link completeViaRecoveryCode} used to
+     * carry (the `auditSink.record(...)` call + the `notifyRecoveryUsed` email) so EVERY
+     * lockout/abuse path records a uniform, secret-free security event through ONE seam.
+     *
+     * ── NEVER THROWS INTO THE REQUEST PATH ── the (already-decided) HTTP response must
+     *   NOT change because an audit/notify failed or is slow: nothing here is awaited by
+     *   the caller, the audit `record` is fire-and-forget with a swallowed `.catch`, and
+     *   the notify runs inside {@link maybeNotifyOwner}'s own detached, swallowed IIFE.
+     *
+     * ── NO SECRET LEAK ── `attributes` carries only non-secret structured detail (a
+     *   reason code, never a password / recovery code / TOTP secret / token / hash). The
+     *   `identityHint` (the email/username the user typed) is acceptable in an AUDIT row
+     *   — it IS the actor identity the event is about — but it is written ONLY to the
+     *   audit attributes, NEVER used as a notify recipient (see the notify rule below).
+     *
+     * ── NOTIFY ONLY WITH A RESOLVED PRINCIPAL ── the owner email is resolved from
+     *   `actorId` + `tenantId` via the profile resolver. When there is NO resolved
+     *   principal (a pre-auth login lockout keys on the typed hint only — the resolver
+     *   has not run), we CANNOT know the real account owner, so we DO NOT notify: mailing
+     *   a bare hint could email a non-owner (the hint may be someone else's address / a
+     *   typo) and would confirm the account exists. In that case the AUDIT still fires;
+     *   only the notify is skipped.
+     */
+    recordSecurityEvent(params) {
+        // ── Audit (always, if the sink is wired) — fire-and-forget, swallowed. ──────────
+        // The identityHint (typed email/username) is the actor identity → acceptable in an
+        // AUDIT attribute; it is NEVER placed in a notify body (only the RESOLVED profile
+        // email is a recipient). No secret ever enters attributes.
+        const attributes = {
+            ...(params.attributes ?? {}),
+            ...(params.identityHint ? { identityHint: params.identityHint } : {}),
+        };
+        void this.auditSink
+            ?.record({
+            type: 'authentication',
+            occurredAtMs: Date.now(),
+            actorId: params.actorId ?? '',
+            ...(params.tenantId ? { tenantId: params.tenantId } : {}),
+            action: params.action,
+            attributes,
+        })
+            .catch(() => {
+            /* best-effort: an audit failure never changes the response */
+        });
+        // ── Notify (ONLY when asked AND a principal is resolvable) ──────────────────────
+        // No actorId/tenantId → pre-auth (login lockout keyed on the typed hint): we cannot
+        // reliably resolve the OWNER's email, so we SKIP the notify (never email a bare
+        // hint — it could reach a non-owner and would confirm account existence). Audit has
+        // already fired above regardless.
+        if (params.notify === true && params.actorId && params.tenantId) {
+            this.maybeNotifyOwner(params.actorId, params.tenantId);
+        }
+    }
+    /**
+     * Fire-and-forget "a security-sensitive event happened on your account" notice to the
+     * resolved owner (the generalized {@link notifyRecoveryUsed} path). Resolves the
+     * recipient email from `principalId` + `tenantId` via the injected profile resolver,
+     * then delivers a NEUTRAL security warning via the email sender. Best-effort: NOT
+     * awaited, and every rejection (missing email / resolver throw / send failure) is
+     * swallowed so it never changes the response. NO code / token / uuid ever enters the
+     * body — only the neutral notice the owner needs to act on it.
+     *
+     * Today the only notify caller is the recovery-code login (which routes through
+     * {@link recordSecurityEvent} with `notify:true`), so this delegates to the existing
+     * {@link notifyRecoveryUsed} message — the exact neutral, no-secret email the recovery
+     * behavior + its tests already assert (the refactor keeps that email byte-for-byte).
+     */
+    maybeNotifyOwner(principalId, tenantId) {
+        this.notifyRecoveryUsed(principalId, tenantId);
+    }
+    /**
+     * `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
+     * 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 : '';
+        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);
+                // 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
+                // the principal id + tenant; project from those. `undefined` (no projector) →
+                // 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);
+                await this.tokenBinder.rebindOnRotate(est.tokens.accessToken, est.session.sessionId, ttlMs, freshFacts);
+            }
+            return toSessionSuccess(est);
+        }
+        catch {
+            // The engine throws only its generic SessionRejectedError (reuse, invalid,
+            // expiry, or a swallowed store outage — all indistinguishable here). Map to a
+            // generic 401; never leak which, never echo the token.
+            genericUnauthorized();
+        }
+    }
+    /**
+     * `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.
+     */
+    async logout(body) {
+        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 {
+            await this.sessionAuthority.revoke(sessionId);
+            // 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)
+                await this.tokenBinder.unbindSession(sessionId);
+        }
+        catch {
+            // Swallow — logout is idempotent + must not leak. 204 regardless.
+        }
+    }
+    /**
+     * Establish a session for an authenticated principal, mapping the engine's
+     * generic `SessionRejectedError` (a malformed principal or a store outage at
+     * establish time) to a generic 401. We never surface a session-establish failure
+     * as a distinct, enumerable outcome.
+     */
+    async establishOrReject(principal) {
+        try {
+            return await this.sessionAuthority.establish(principal);
+        }
+        catch {
+            genericUnauthorized();
+        }
+    }
+};
+exports.AuthController = AuthController;
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('login'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AuthController.prototype, "login", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Get)('me'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], AuthController.prototype, "me", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('forgot-password'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.NO_CONTENT),
+    __param(0, (0, common_1.Body)()),
+    __param(1, (0, common_1.Ip)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", Promise)
+], AuthController.prototype, "forgotPassword", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('reset-password'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.NO_CONTENT),
+    __param(0, (0, common_1.Body)()),
+    __param(1, (0, common_1.Ip)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", Promise)
+], AuthController.prototype, "resetPassword", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('mfa'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AuthController.prototype, "mfa", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('refresh'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AuthController.prototype, "refresh", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('logout'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.NO_CONTENT),
+    __param(0, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AuthController.prototype, "logout", null);
+exports.AuthController = AuthController = __decorate([
+    (0, common_1.Controller)('auth'),
+    __param(0, (0, common_1.Inject)(tokens_js_1.SHIELD_AUTHENTICATOR)),
+    __param(1, (0, common_1.Inject)(tokens_js_1.SHIELD_SESSION_AUTHORITY)),
+    __param(3, (0, common_2.Optional)()),
+    __param(3, (0, common_1.Inject)(tokens_js_2.SHIELD_SESSION_TOKEN_BINDER)),
+    __param(4, (0, common_2.Optional)()),
+    __param(4, (0, common_1.Inject)(tokens_js_3.SHIELD_PROFILE_RESOLVER)),
+    __param(5, (0, common_2.Optional)()),
+    __param(5, (0, common_1.Inject)(tokens_js_1.SHIELD_CREDENTIAL_RESOLVER)),
+    __param(6, (0, common_2.Optional)()),
+    __param(6, (0, common_1.Inject)(tokens_js_1.SHIELD_RESET_TOKEN_STORE)),
+    __param(7, (0, common_2.Optional)()),
+    __param(7, (0, common_1.Inject)(tokens_js_1.SHIELD_EMAIL_SENDER)),
+    __param(8, (0, common_2.Optional)()),
+    __param(8, (0, common_1.Inject)(tokens_js_1.SHIELD_CREDENTIAL_WRITER)),
+    __param(9, (0, common_2.Optional)()),
+    __param(9, (0, common_1.Inject)(tokens_js_1.SHIELD_SESSION_SWEEPER)),
+    __param(10, (0, common_2.Optional)()),
+    __param(10, (0, common_1.Inject)(tokens_js_1.SHIELD_PASSWORD_HASHER)),
+    __param(11, (0, common_2.Optional)()),
+    __param(11, (0, common_1.Inject)(tokens_js_1.SHIELD_RESET_LINK_BASE_URL)),
+    __param(12, (0, common_2.Optional)()),
+    __param(12, (0, common_1.Inject)(tokens_js_1.SHIELD_RECOVERY_CODE_STORE)),
+    __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(15, (0, common_2.Optional)()),
+    __param(15, (0, common_1.Inject)(tokens_js_1.SHIELD_FORGOT_LIMITER)),
+    __param(16, (0, common_2.Optional)()),
+    __param(16, (0, common_1.Inject)(tokens_js_1.SHIELD_FORGOT_HINT_LIMITER)),
+    __param(17, (0, common_2.Optional)()),
+    __param(17, (0, common_1.Inject)(tokens_js_1.SHIELD_RESET_LIMITER)),
+    __param(18, (0, common_2.Optional)()),
+    __param(18, (0, common_1.Inject)(tokens_js_1.SHIELD_AUDIT_SINK)),
+    __param(19, (0, common_2.Optional)()),
+    __param(19, (0, common_1.Inject)(tokens_js_1.SHIELD_SESSION_FACTS_PROJECTOR)),
+    __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])
+], AuthController);
+/**
+ * Narrow an `authenticated` result to its guaranteed principal. The core engine
+ * populates `principal` ONLY on `outcome === 'authenticated'`; this asserts that
+ * invariant so a missing principal fails closed (generic 401) rather than
+ * establishing a session for `undefined`.
+ */
+function requirePrincipal(result) {
+    const principal = result.principal;
+    if (principal === undefined || principal === null) {
+        genericUnauthorized();
+    }
+    return principal;
+}