@astram/guard 0.18.0 → 0.20.0

package/dist/auth/captcha-gate.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CaptchaGate = exports.RedisCaptchaCounterStore = exports.CAPTCHA_BUMP_SCRIPT = exports.AUTH_CAPTCHA_FAIL_OPEN = exports.AUTH_CAPTCHA_FAILED = exports.CAPTCHA_WINDOW_MS = void 0;
+/**
+ * The CAPTCHA gate on `/auth/login`, `/auth/forgot-password` and `/auth/reset-password`
+ * (auth capabilities R7.2–R7.5, X2, X3; AC-12, AC-13).
+ *
+ * ── WHEN A CHALLENGE IS REQUIRED ────────────────────────────────────────────
+ *   `always` ⇒ every request to a covered endpoint. `adaptive` ⇒ once ANY of these per-endpoint
+ *   counters reaches `CAPTCHA_THRESHOLD`:
+ *     `captcha:<endpoint>:pid:<principalId>`   the resolved account (every spelling shares it);
+ *     `captcha:<endpoint>:txt:<sha256(canonical typed text)>`   the typed hint, bumped for known
+ *       AND unknown names alike, so the same typed text reaches the threshold at the same attempt
+ *       whether or not an account exists (X2);
+ *     `captcha:<endpoint>:ip:<ip>`   only when per-IP limiting is on (explicit `trust proxy`),
+ *       like every other per-IP limiter (otherwise every client shares the proxy's IP).
+ *   Keys live under `shield:captcha:` with a fixed 15-minute window from the first hit; no
+ *   personal data in a key. Login bumps on a failed password; forgot-password on every request
+ *   (a request-rate cap: it has no failure signal); reset-password on a bad reset token (IP only:
+ *   no account is known before the token is consumed). A success clears the account and
+ *   typed-text keys, never the IP key.
+ *
+ * ── REDIS ── one MGET to decide, one EVAL to bump. A Redis error while deciding REQUIRES the
+ *   challenge (fail closed, Shield #1): the attempt then needs a valid token, and the failure
+ *   response carries `captcha: 'required'`. A bump error is treated the same way for the body flag.
+ *
+ * ── VERIFYING ── the token is checked BEFORE any password hash, code check or reset-token use
+ *   (R7.4). A missing token never calls the provider. Outcomes:
+ *     passed / not required ⇒ proceed;
+ *     rejected ⇒ fail (counter `auth.captcha.failed`; audit row `auth.captcha.failed` for a
+ *       RESOLVED account, at most one per account, endpoint and window — R12.3 bounding);
+ *     provider unavailable ⇒ `CAPTCHA_FAIL_MODE`: `closed` (default) is a failure with reason
+ *       `unavailable`; `open` proceeds, counted `auth.captcha.fail_open` every time and audited
+ *       `auth.captcha.fail_open` when the account resolved (the default sink skips actor-less
+ *       rows, so the counter is the record for unknown names). Lockout and limits still apply.
+ *
+ * Counters are one structured log line each (R12.4 style): fixed keys, no hint, no token.
+ */
+const common_1 = require("@nestjs/common");
+const core_1 = require("@astram/core");
+const auth_audit_js_1 = require("./auth-audit.js");
+const canonical_hint_js_1 = require("./rate-limit/canonical-hint.js");
+/** Fixed counter window (ms). */
+exports.CAPTCHA_WINDOW_MS = 15 * 60 * 1000;
+exports.AUTH_CAPTCHA_FAILED = 'auth.captcha.failed';
+exports.AUTH_CAPTCHA_FAIL_OPEN = 'auth.captcha.fail_open';
+/**
+ * Bump every key and arm the window on the first hit (or a key left without a TTL). Returns the
+ * new counts, in key order. KEYS = the counter keys; ARGV[1] = window ms.
+ */
+exports.CAPTCHA_BUMP_SCRIPT = `local out = {}
+for i, k in ipairs(KEYS) do
+  local n = redis.call('INCR', k)
+  if n == 1 or redis.call('PTTL', k) == -1 then
+    redis.call('PEXPIRE', k, ARGV[1])
+  end
+  out[i] = n
+end
+return out`;
+/** {@link CaptchaCounterStore} over the guard's bounded ioredis client. */
+class RedisCaptchaCounterStore {
+    redis;
+    windowMs;
+    constructor(redis, windowMs = exports.CAPTCHA_WINDOW_MS) {
+        this.redis = redis;
+        this.windowMs = windowMs;
+    }
+    k(key) {
+        return `shield:captcha:${key}`;
+    }
+    async counts(keys) {
+        if (keys.length === 0)
+            return [];
+        const raw = await this.redis.mget(...keys.map((k) => this.k(k)));
+        return raw.map((v) => {
+            const n = v === null ? 0 : Number(v);
+            return Number.isFinite(n) ? n : 0;
+        });
+    }
+    async bump(keys) {
+        if (keys.length === 0)
+            return [];
+        const out = (await this.redis.eval(exports.CAPTCHA_BUMP_SCRIPT, keys.length, ...keys.map((k) => this.k(k)), String(this.windowMs)));
+        if (!Array.isArray(out))
+            throw new Error('captcha counter: unexpected reply');
+        return out.map((n) => Number(n));
+    }
+    async clear(keys) {
+        if (keys.length === 0)
+            return;
+        try {
+            await this.redis.del(...keys.map((k) => this.k(k)));
+        }
+        catch {
+            // Best-effort: the window expires the keys anyway.
+        }
+    }
+    /**
+     * Remove keys and REJECT on a store error (auth capabilities R11.1: an admin unlock clears the
+     * account counters and must not report a success it did not achieve). Not on the port: only the
+     * unlocker uses it.
+     */
+    async clearStrict(keys) {
+        if (keys.length === 0)
+            return;
+        await this.redis.del(...keys.map((k) => this.k(k)));
+    }
+    async firstInWindow(key) {
+        try {
+            return (await this.redis.set(this.k(key), '1', 'PX', this.windowMs, 'NX')) === 'OK';
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.RedisCaptchaCounterStore = RedisCaptchaCounterStore;
+class CaptchaGate {
+    deps;
+    logger;
+    constructor(deps) {
+        this.deps = deps;
+        this.logger = deps.logger ?? new common_1.Logger('ShieldCaptcha');
+    }
+    /** The public part of the config (provider, site key, mode). */
+    get publicOptions() {
+        const { provider, siteKey, mode } = this.deps.config;
+        return { provider, siteKey, mode };
+    }
+    /** True when this endpoint is protected (`CAPTCHA_ENDPOINTS`). */
+    covers(endpoint) {
+        return this.deps.config.endpoints.includes(endpoint);
+    }
+    /** True when the mode is `always` (every attempt is challenged). */
+    get always() {
+        return this.deps.config.mode === 'always';
+    }
+    keys(endpoint, s) {
+        const keys = [];
+        if (s.accountId)
+            keys.push(`${endpoint}:pid:${s.accountId}`);
+        if (typeof s.typedText === 'string' && s.typedText !== '') {
+            keys.push(`${endpoint}:txt:${(0, canonical_hint_js_1.hintKeyDigest)(s.typedText)}`);
+        }
+        if (s.ip)
+            keys.push(`${endpoint}:ip:${s.ip}`);
+        return keys;
+    }
+    overThreshold(counts) {
+        return counts.some((n) => n >= this.deps.config.threshold);
+    }
+    /** Is a challenge required now? A store error ⇒ `true` (fail closed). */
+    async required(endpoint, subject) {
+        if (!this.covers(endpoint))
+            return false;
+        if (this.always)
+            return true;
+        const keys = this.keys(endpoint, subject);
+        if (keys.length === 0)
+            return false;
+        try {
+            return this.overThreshold(await this.deps.counters.counts(keys));
+        }
+        catch {
+            return true;
+        }
+    }
+    /**
+     * Decide and, when required, verify `token`. Call BEFORE any hash / code check. Never throws.
+     */
+    async check(endpoint, subject, token, remoteIp) {
+        if (!(await this.required(endpoint, subject)))
+            return { kind: 'not_required' };
+        const account = subject.accountId ? 'known' : 'unknown';
+        if (typeof token !== 'string' || token.trim() === '') {
+            this.count(exports.AUTH_CAPTCHA_FAILED, endpoint, account, 'missing');
+            return { kind: 'failed' };
+        }
+        let result;
+        try {
+            result = await this.deps.verifier.verify({
+                token,
+                expectedAction: endpoint,
+                ...(remoteIp ? { remoteIp } : {}),
+            });
+        }
+        catch {
+            result = { ok: false, reason: 'unavailable' };
+        }
+        if (result.ok)
+            return { kind: 'passed' };
+        if ((0, core_1.isCaptchaUnavailable)(result) && this.deps.config.failMode === 'open') {
+            this.count(exports.AUTH_CAPTCHA_FAIL_OPEN, endpoint, account);
+            if (subject.accountId && subject.tenantId) {
+                (0, auth_audit_js_1.emitAuthAudit)(this.deps.auditSink, (0, auth_audit_js_1.authEvent)(exports.AUTH_CAPTCHA_FAIL_OPEN, subject.accountId, subject.tenantId, { endpoint }));
+            }
+            return { kind: 'fail_open' };
+        }
+        this.count(exports.AUTH_CAPTCHA_FAILED, endpoint, account, result.reason);
+        if (subject.accountId && subject.tenantId) {
+            const accountId = subject.accountId;
+            const tenantId = subject.tenantId;
+            const reason = result.reason;
+            void this.deps.counters
+                .firstInWindow(`audit:${endpoint}:pid:${accountId}`)
+                .then((first) => {
+                if (first) {
+                    (0, auth_audit_js_1.emitAuthAudit)(this.deps.auditSink, (0, auth_audit_js_1.authEvent)(exports.AUTH_CAPTCHA_FAILED, accountId, tenantId, { endpoint, reason }));
+                }
+            })
+                .catch(() => undefined);
+        }
+        return { kind: 'failed' };
+    }
+    /**
+     * Count one failure (login: wrong password; forgot: every request; reset: bad token). Returns
+     * whether the NEXT attempt needs a challenge (the failure body's `captcha: 'required'` flag). A
+     * store error ⇒ `true` (fail closed, consistent with {@link required}).
+     */
+    async recordFailure(endpoint, subject) {
+        if (!this.covers(endpoint))
+            return false;
+        if (this.always)
+            return true;
+        const keys = this.keys(endpoint, subject);
+        let counts = [];
+        try {
+            counts = await this.deps.counters.bump(keys);
+        }
+        catch {
+            return true;
+        }
+        return this.overThreshold(counts);
+    }
+    /** A success clears the account and typed-text counters (never the IP one). Best-effort. */
+    async recordSuccess(endpoint, subject) {
+        if (!this.covers(endpoint))
+            return;
+        await this.deps.counters.clear(this.keys(endpoint, { ...subject, ip: null }));
+    }
+    count(counter, endpoint, account, reason) {
+        this.logger.log({ counter, endpoint, account, ...(reason ? { reason } : {}) });
+    }
+}
+exports.CaptchaGate = CaptchaGate;

package/dist/auth/dto.d.ts

@@ -102,7 +102,22 @@ export interface LoginRequest {
     /** Username or email — resolved to a principal by the credential resolver. */
     readonly identityHint: string;
     /** ⛔ The plaintext password — verified then discarded; NEVER logged/echoed. */
-    readonly password: string;
+    readonly password: string; /**
+     * Auth capabilities R7: the CAPTCHA widget's response token, required once the server answers
+     * `captcha: 'required'` (or always, in `always` mode). Verified with the provider, never logged.
+     */
+    readonly captchaToken?: string;
+}
+/** `GET /auth/login-options` (auth capabilities R7.3, R13.2): public sign-in page settings. */
+export interface LoginOptionsView {
+    /** Accepted sign-in forms (`['email']` or `['email', 'username']`). */
+    readonly signInWith: readonly ('email' | 'username')[];
+    /** Public CAPTCHA settings, or `null` when CAPTCHA is off. Never the secret. */
+    readonly captcha: {
+        readonly provider: 'turnstile' | 'recaptcha-v3' | 'recaptcha-v2';
+        readonly siteKey: string;
+        readonly mode: 'adaptive' | 'always';
+    } | null;
 }
 /**
  * The MFA-challenge branch of a login/step-up response: the password was correct
@@ -174,6 +189,12 @@ export type RefreshResponse = SessionSuccess;
  */
 export interface LogoutRequest {
     readonly sessionId: string;
+    /**
+     * OPTIONAL proof of ownership (R15.1): a refresh token of the named session. An
+     * `Authorization: Bearer <access token>` bound to the session is the other accepted proof.
+     * Without either, the session is revoked only while `logoutRequiresProof` is `false`.
+     */
+    readonly refreshToken?: string;
 }
 /**
  * `POST /auth/logout` acknowledgement. The endpoint returns HTTP 204 (no body) on

package/dist/auth/dto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../../src/auth/dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC9D,oBAAoB;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oBAAoB;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC,CAAC;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;CACpC;AAMD,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,oBAAoB,CAAC;AAMlE;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC;IAC1C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC;AAMzC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC;AAM7C;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACxB"}
+{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../../src/auth/dto.ts"],"names":[],"mappings":"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"}

package/dist/auth/login-name-count-boot.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Auth capabilities R1.9: when `signInWith` includes `'username'`, log once at boot how many
+ * active users have a login name (`users.u_login_name`). Count only, no names. Read through the
+ * guard's runtime pool. A missing table (errno 1146) or column (1054, migration 103 not applied)
+ * skips with one warning; any other error warns without detail. Never blocks boot.
+ */
+import { type OnApplicationBootstrap } from '@nestjs/common';
+import type { SignInMethod } from '../authentication/sign-in-with.js';
+export type CountQuery = (sql: string) => Promise<unknown[]>;
+export declare class LoginNameCountBoot implements OnApplicationBootstrap {
+    private readonly query;
+    /** Already-qualified `<app>`.`users` (from `qualifiedTableName`). */
+    private readonly usersTable;
+    private readonly signInWith;
+    private readonly logger;
+    constructor(query: CountQuery, 
+    /** Already-qualified `<app>`.`users` (from `qualifiedTableName`). */
+    usersTable: string, signInWith: readonly SignInMethod[], logger?: {
+        log(message: string): void;
+        warn(message: string): void;
+    });
+    onApplicationBootstrap(): Promise<void>;
+}
+//# sourceMappingURL=login-name-count-boot.d.ts.map

package/dist/auth/login-name-count-boot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login-name-count-boot.d.ts","sourceRoot":"","sources":["../../src/auth/login-name-count-boot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAU,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAKtE,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;AAE7D,qBAAa,kBAAmB,YAAW,sBAAsB;IAI7D,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAN7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8D;gBAGlE,KAAK,EAAE,UAAU;IAClC,qEAAqE;IACpD,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,SAAS,YAAY,EAAE,EACpD,MAAM,CAAC,EAAE;QAAE,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;IAKhE,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;CAsB9C"}

package/dist/auth/login-name-count-boot.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoginNameCountBoot = void 0;
+/**
+ * Auth capabilities R1.9: when `signInWith` includes `'username'`, log once at boot how many
+ * active users have a login name (`users.u_login_name`). Count only, no names. Read through the
+ * guard's runtime pool. A missing table (errno 1146) or column (1054, migration 103 not applied)
+ * skips with one warning; any other error warns without detail. Never blocks boot.
+ */
+const common_1 = require("@nestjs/common");
+const ER_BAD_FIELD_ERROR = 1054;
+const ER_NO_SUCH_TABLE = 1146;
+class LoginNameCountBoot {
+    query;
+    usersTable;
+    signInWith;
+    logger;
+    constructor(query, 
+    /** Already-qualified `<app>`.`users` (from `qualifiedTableName`). */
+    usersTable, signInWith, logger) {
+        this.query = query;
+        this.usersTable = usersTable;
+        this.signInWith = signInWith;
+        this.logger = logger ?? new common_1.Logger('ShieldAuth');
+    }
+    async onApplicationBootstrap() {
+        if (!this.signInWith.includes('username'))
+            return;
+        try {
+            const rows = await this.query(`SELECT COUNT(*) AS n FROM ${this.usersTable} ` +
+                `WHERE u_login_name IS NOT NULL AND u_status = 'active'`);
+            const raw = rows[0]?.n;
+            const n = typeof raw === 'bigint' ? raw.toString() : String(Number(raw ?? 0));
+            this.logger.log(`signInWith includes username: ${n} active users have a login name`);
+        }
+        catch (err) {
+            const errno = err?.errno;
+            if (errno === ER_NO_SUCH_TABLE || errno === ER_BAD_FIELD_ERROR) {
+                this.logger.warn('signInWith includes username but users.u_login_name is missing (apply migration 103); ' +
+                    'login-name count skipped');
+                return;
+            }
+            this.logger.warn('signInWith includes username: could not count users with a login name');
+        }
+    }
+}
+exports.LoginNameCountBoot = LoginNameCountBoot;

package/dist/auth/logout-proof.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Logout proof (R15.1, D-9, AC-19). `POST /auth/logout` is `@Public()`, so the session it ends
+ * must be proven by the caller, not just named:
+ *
+ *  - a bearer access token whose bound claims carry the named `sessionId`, OR
+ *  - a refresh token whose keyed hash (`SHIELD_REFRESH_HASHER`) finds a refresh record of that
+ *    session (`SessionRecordStore.findRefreshByHash`). Any record status counts: replaying a
+ *    rotated token already kills the whole lineage through `/auth/refresh`, so accepting it here
+ *    gives a holder no new power, and it keeps logout working across a refresh race.
+ *
+ * Outcomes:
+ *  - `proven`      → a supplied token proves the named session.
+ *  - `mismatch`    → a token was supplied but proves another session, or is unknown / invalid.
+ *  - `none`        → no bearer and no refresh token were supplied (an old frontend).
+ *  - `unavailable` → no token proved the session and a lookup failed (Redis or DB error). The
+ *                    controller treats it like `none`: strict mode revokes nothing (fail closed),
+ *                    compatibility mode revokes as before (today's behaviour, counted).
+ *
+ * Raw tokens are never logged; the unproven counter carries no ids.
+ */
+import { Logger, type Provider } from '@nestjs/common';
+import type { RefreshTokenHasher, SessionRecordStore } from '@astram/core';
+import type { SessionTokenBinder } from '../request-auth/session-token-binder.js';
+/** DI token for the {@link LogoutProofVerifier}. */
+export declare const SHIELD_LOGOUT_PROOF_VERIFIER: unique symbol;
+/** DI token for the `logoutRequiresProof` option (boolean; default `false`). */
+export declare const SHIELD_LOGOUT_REQUIRES_PROOF: unique symbol;
+/** The fixed counter key written for every unproven logout that still revokes (R12.4 style). */
+export declare const LOGOUT_UNPROVEN_COUNTER = "auth.logout.unproven";
+export type LogoutProofOutcome = 'proven' | 'mismatch' | 'none' | 'unavailable';
+export declare class LogoutProofVerifier {
+    private readonly binder;
+    private readonly hasher;
+    private readonly records;
+    constructor(binder: Pick<SessionTokenBinder, 'resolve'> | null, hasher: RefreshTokenHasher | null, records: Pick<SessionRecordStore, 'findRefreshByHash'> | null);
+    /**
+     * Classify the proof a logout request carries for `sessionId`. Never throws.
+     * @param accessToken the bearer token from `Authorization`, or `null`.
+     * @param refreshToken the body's `refreshToken`, or `null`.
+     */
+    verify(sessionId: string, accessToken: string | null, refreshToken: string | null): Promise<LogoutProofOutcome>;
+}
+/** The process-local count of unproven logouts that still revoked (compatibility mode). */
+export declare function unprovenLogoutCount(): number;
+/**
+ * Count one unproven logout that revoked (compatibility mode): a structured log line with the
+ * fixed key {@link LOGOUT_UNPROVEN_COUNTER} and no ids, plus a one-time deprecation warning per
+ * process.
+ */
+export declare function recordUnprovenLogout(logger?: Pick<Logger, 'log' | 'warn'>): void;
+/** The verifier over the bound token binder, refresh hasher and durable record store. */
+export declare const logoutProofVerifierProvider: Provider;
+/** Bind the `logoutRequiresProof` option (absent → `false`, the compatibility default). */
+export declare function makeLogoutRequiresProofProvider(requiresProof?: boolean): Provider;
+//# sourceMappingURL=logout-proof.d.ts.map

package/dist/auth/logout-proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logout-proof.d.ts","sourceRoot":"","sources":["../../src/auth/logout-proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAKlF,oDAAoD;AACpD,eAAO,MAAM,4BAA4B,eAAyC,CAAC;AACnF,gFAAgF;AAChF,eAAO,MAAM,4BAA4B,eAAyC,CAAC;AACnF,gGAAgG;AAChG,eAAO,MAAM,uBAAuB,yBAAyB,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,aAAa,CAAC;AAEhF,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAFP,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,CAAC,GAAG,IAAI,EAClD,MAAM,EAAE,kBAAkB,GAAG,IAAI,EACjC,OAAO,EAAE,IAAI,CAAC,kBAAkB,EAAE,mBAAmB,CAAC,GAAG,IAAI;IAGhF;;;;OAIG;IACG,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,OAAO,CAAC,kBAAkB,CAAC;CAoC/B;AAMD,2FAA2F;AAC3F,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,GAAE,IAAI,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAe,GAAG,IAAI,CAY7F;AAED,yFAAyF;AACzF,eAAO,MAAM,2BAA2B,EAAE,QAazC,CAAC;AAEF,2FAA2F;AAC3F,wBAAgB,+BAA+B,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,QAAQ,CAEjF"}

package/dist/auth/logout-proof.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Logout proof (R15.1, D-9, AC-19). `POST /auth/logout` is `@Public()`, so the session it ends
+ * must be proven by the caller, not just named:
+ *
+ *  - a bearer access token whose bound claims carry the named `sessionId`, OR
+ *  - a refresh token whose keyed hash (`SHIELD_REFRESH_HASHER`) finds a refresh record of that
+ *    session (`SessionRecordStore.findRefreshByHash`). Any record status counts: replaying a
+ *    rotated token already kills the whole lineage through `/auth/refresh`, so accepting it here
+ *    gives a holder no new power, and it keeps logout working across a refresh race.
+ *
+ * Outcomes:
+ *  - `proven`      → a supplied token proves the named session.
+ *  - `mismatch`    → a token was supplied but proves another session, or is unknown / invalid.
+ *  - `none`        → no bearer and no refresh token were supplied (an old frontend).
+ *  - `unavailable` → no token proved the session and a lookup failed (Redis or DB error). The
+ *                    controller treats it like `none`: strict mode revokes nothing (fail closed),
+ *                    compatibility mode revokes as before (today's behaviour, counted).
+ *
+ * Raw tokens are never logged; the unproven counter carries no ids.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logoutProofVerifierProvider = exports.LogoutProofVerifier = exports.LOGOUT_UNPROVEN_COUNTER = exports.SHIELD_LOGOUT_REQUIRES_PROOF = exports.SHIELD_LOGOUT_PROOF_VERIFIER = void 0;
+exports.unprovenLogoutCount = unprovenLogoutCount;
+exports.recordUnprovenLogout = recordUnprovenLogout;
+exports.makeLogoutRequiresProofProvider = makeLogoutRequiresProofProvider;
+const common_1 = require("@nestjs/common");
+const tokens_js_1 = require("../request-auth/tokens.js");
+const mariadb_session_record_store_js_1 = require("../session/mariadb-session-record-store.js");
+const crypto_adapters_js_1 = require("../session/crypto-adapters.js");
+/** DI token for the {@link LogoutProofVerifier}. */
+exports.SHIELD_LOGOUT_PROOF_VERIFIER = Symbol('SHIELD_LOGOUT_PROOF_VERIFIER');
+/** DI token for the `logoutRequiresProof` option (boolean; default `false`). */
+exports.SHIELD_LOGOUT_REQUIRES_PROOF = Symbol('SHIELD_LOGOUT_REQUIRES_PROOF');
+/** The fixed counter key written for every unproven logout that still revokes (R12.4 style). */
+exports.LOGOUT_UNPROVEN_COUNTER = 'auth.logout.unproven';
+class LogoutProofVerifier {
+    binder;
+    hasher;
+    records;
+    constructor(binder, hasher, records) {
+        this.binder = binder;
+        this.hasher = hasher;
+        this.records = records;
+    }
+    /**
+     * Classify the proof a logout request carries for `sessionId`. Never throws.
+     * @param accessToken the bearer token from `Authorization`, or `null`.
+     * @param refreshToken the body's `refreshToken`, or `null`.
+     */
+    async verify(sessionId, accessToken, refreshToken) {
+        if (accessToken === null && refreshToken === null)
+            return 'none';
+        let failed = false;
+        if (accessToken !== null) {
+            if (this.binder === null) {
+                failed = true;
+            }
+            else {
+                try {
+                    const claims = await this.binder.resolve(accessToken);
+                    if (claims !== null && sessionId !== '' && claims.sessionId === sessionId) {
+                        return 'proven';
+                    }
+                }
+                catch {
+                    failed = true;
+                }
+            }
+        }
+        if (refreshToken !== null) {
+            if (this.hasher === null || this.records === null) {
+                failed = true;
+            }
+            else {
+                try {
+                    const record = await this.records.findRefreshByHash(this.hasher.hash(refreshToken));
+                    if (record !== null && sessionId !== '' && record.sessionId === sessionId) {
+                        return 'proven';
+                    }
+                }
+                catch {
+                    failed = true;
+                }
+            }
+        }
+        return failed ? 'unavailable' : 'mismatch';
+    }
+}
+exports.LogoutProofVerifier = LogoutProofVerifier;
+let unprovenCount = 0;
+let deprecationWarned = false;
+const proofLogger = new common_1.Logger('ShieldAuth');
+/** The process-local count of unproven logouts that still revoked (compatibility mode). */
+function unprovenLogoutCount() {
+    return unprovenCount;
+}
+/**
+ * Count one unproven logout that revoked (compatibility mode): a structured log line with the
+ * fixed key {@link LOGOUT_UNPROVEN_COUNTER} and no ids, plus a one-time deprecation warning per
+ * process.
+ */
+function recordUnprovenLogout(logger = proofLogger) {
+    unprovenCount += 1;
+    if (!deprecationWarned) {
+        deprecationWarned = true;
+        logger.warn('POST /auth/logout without proof (no refresh token, no bearer) still revokes the named ' +
+            'session; this is deprecated. Send the refresh token or the access token, then set ' +
+            'ShieldModule.forRoot({ logoutRequiresProof: true }). It becomes the default at the next ' +
+            'guard major.');
+    }
+    logger.log({ counter: exports.LOGOUT_UNPROVEN_COUNTER, count: unprovenCount });
+}
+/** The verifier over the bound token binder, refresh hasher and durable record store. */
+exports.logoutProofVerifierProvider = {
+    provide: exports.SHIELD_LOGOUT_PROOF_VERIFIER,
+    useFactory: (binder, hasher, records) => new LogoutProofVerifier(binder ?? null, hasher ?? null, records ?? null),
+    inject: [
+        { token: tokens_js_1.SHIELD_SESSION_TOKEN_BINDER, optional: true },
+        { token: crypto_adapters_js_1.SHIELD_REFRESH_HASHER, optional: true },
+        { token: mariadb_session_record_store_js_1.SHIELD_SESSION_RECORD_STORE, optional: true },
+    ],
+};
+/** Bind the `logoutRequiresProof` option (absent → `false`, the compatibility default). */
+function makeLogoutRequiresProofProvider(requiresProof) {
+    return { provide: exports.SHIELD_LOGOUT_REQUIRES_PROOF, useValue: requiresProof === true };
+}

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

@@ -33,6 +33,11 @@ export interface PendingMfaChallenge {
     readonly identityHint: string;
     /** SHA-256 of the stored credential hash at password time (credential-change guard). */
     readonly credentialFingerprint: string;
+    /**
+     * The resolved account's tenant at password time (R12.2): the tenant of a failed second-factor
+     * audit row. Optional, so a challenge stored before this field still parses.
+     */
+    readonly tenantId?: string;
 }
 /**
  * The in-process challenge store (single instance / tests) and the class token the

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

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

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

@@ -56,6 +56,7 @@ function parseChallenge(value) {
         principalId: v.principalId,
         identityHint: v.identityHint,
         credentialFingerprint: v.credentialFingerprint,
+        ...(typeof v.tenantId === 'string' && v.tenantId !== '' ? { tenantId: v.tenantId } : {}),
     };
 }
 /**
@@ -127,6 +128,7 @@ class RedisPendingMfaStore extends PendingMfaStore {
             principalId: challenge.principalId,
             identityHint: challenge.identityHint,
             credentialFingerprint: challenge.credentialFingerprint,
+            ...(challenge.tenantId !== undefined ? { tenantId: challenge.tenantId } : {}),
         });
         await this.redis.set(`${REDIS_PREFIX}${tokenDigest(token)}`, value, 'PX', this.ttlMs);
         return token;

package/dist/auth/persistence.module.d.ts

@@ -33,8 +33,8 @@
 import { type DynamicModule } from '@nestjs/common';
 /**
  * The persistence module. `forRoot()` returns the two connection providers (both
- * exported so AuthModule can inject them) plus the shutdown holder. Opt-in: only
- * imported when auth is wired.
+ * exported so AuthModule can inject them), the shutdown holder and the audit sealer.
+ * Opt-in: only imported when auth is wired.
  */
 export declare class PersistenceModule {
     static forRoot(): DynamicModule;

package/dist/auth/persistence.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.module.d.ts","sourceRoot":"","sources":["../../src/auth/persistence.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAU,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AA0C3E;;;;GAIG;AACH,qBACa,iBAAiB;IAC5B,MAAM,CAAC,OAAO,IAAI,aAAa;CAOhC"}
+{"version":3,"file":"persistence.module.d.ts","sourceRoot":"","sources":["../../src/auth/persistence.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAU,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AA2D3E;;;;GAIG;AACH,qBACa,iBAAiB;IAC5B,MAAM,CAAC,OAAO,IAAI,aAAa;CAOhC"}