@astram/guard 0.2.0 → 0.4.0

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

@@ -34,7 +34,7 @@
  *        factorVerifiers: [ createTotpFactorVerifier({ hmacSha1 }) ] }).  The TOTP
  *      verifier is wired so MFA works; `hmacSha1` is the {@link hmacSha1} node:crypto
  *      one-liner (guard owns node:crypto, core does not). `createIdentityBroker()`
- *      with no args registers the default Internal adapter with an EMPTY superuser
+ *      with no args registers the default Internal adapter with an EMPTY root
  *      allowlist (default-deny).
  * ─────────────────────────────────────────────────────────────────────────────
  *
@@ -54,7 +54,7 @@
  *
  * An enforcement-only app that does NOT opt in never imports AuthModule → never
  * opens a pool/redis → never calls `assertRefreshHmacKey` → keeps the no-`.env`
- * boot. An auth-enabled app fails LOUD at boot if `SHIELD_REFRESH_HMAC_KEY` is
+ * boot. An auth-enabled app fails LOUD at boot if `REFRESH_HMAC_KEY` is
  * blank — auth can never compose unkeyed. `APP_CONFIG` is already `@Global` from
  * `ShieldModule`, so AuthModule's config-injecting factories resolve. See DONE.md.
  *
@@ -63,7 +63,17 @@
  * node:crypto HMAC live in guard. Core stays zero-dep + unchanged.
  */
 import { type DynamicModule } from '@nestjs/common';
-import type { CredentialResolver, HmacSha1 } from '@astram/core';
+import type { CredentialResolver, HmacSha1, FactorVerifier } from '@astram/core';
+import type { SessionFactsProjector } from './ports/session-facts-projector.js';
+import type { ProfileResolver } from './profile-resolver.js';
+import type { CredentialWriter } from './ports/credential-writer.js';
+import type { ResetTokenStore } from './ports/reset-token-store.js';
+import type { EmailSender } from './ports/email-sender.js';
+import type { RecoveryCodeStore } from './ports/recovery-code-store.js';
+import type { ProfileWriter } from './ports/profile-writer.js';
+import type { SessionSweeper } from './ports/session-sweeper.js';
+import type { MfaDeviceStore } from './ports/mfa-device-store.js';
+import type { AuditSink } from './ports/audit-sink.js';
 /**
  * The injected HMAC-SHA1 primitive the core TOTP verifier needs (Core is zero-dep
  * + node-type-free, so it cannot import `node:crypto`). Guard owns node:crypto and
@@ -71,6 +81,29 @@ import type { CredentialResolver, HmacSha1 } from '@astram/core';
  * digest. Never logs the key or message.
  */
 export declare const hmacSha1: HmacSha1;
+/**
+ * Resolve the login `totp` {@link FactorVerifier}: the consumer's `override` when
+ * supplied, else the framework's `defaultVerifier`. A pure, infra-free `??` — the
+ * ONE decision point of the Phase-2 verifier seam (override wins; absent → the
+ * default RFC-6238 single-secret verify, behavior unchanged).
+ *
+ * The default is passed IN (rather than built here) because the core factory
+ * `createTotpFactorVerifier` is loaded LAZILY via {@link loadCore} (the CJS↔ESM
+ * invariant, see the file header) — only reachable inside an async provider factory.
+ * So the authenticator's async `useFactory` awaits {@link loadCore}, builds the
+ * default, and hands it here alongside the injected override.
+ */
+export declare function resolveTotpVerifier(override: FactorVerifier | null | undefined, defaultVerifier: FactorVerifier): FactorVerifier;
+/**
+ * Build the framework's DEFAULT single-secret TOTP {@link FactorVerifier}
+ * (`createTotpFactorVerifier({ hmacSha1 })`), loading the core factory lazily (the
+ * CJS↔ESM invariant, see the file header). Exported so a CONSUMER can obtain the
+ * framework's base per-secret verifier to WRAP (e.g. an OR-matching multi-device
+ * verifier delegates to it per device secret) WITHOUT importing `@astram/core`
+ * directly — which would become a runtime `require` on the ESM-only core in the
+ * consumer's built CJS dist. Async because of {@link loadCore}.
+ */
+export declare function makeDefaultTotpVerifier(): Promise<FactorVerifier>;
 /**
  * Options for {@link AuthModule.forRoot} — registration-time collaborators the
  * consumer plugs through {@link ShieldModule.forRoot}.
@@ -84,6 +117,71 @@ export interface AuthModuleOptions {
      * schema. Only meaningful here (AuthModule is only imported under `auth: true`).
      */
     readonly credentialResolver?: CredentialResolver;
+    /**
+     * OPTIONAL current-user profile resolver backing `GET /auth/me` (the
+     * {@link ProfileResolver} port). Omit → `/auth/me` returns an honest 501 (the
+     * framework is org-schema-agnostic; it cannot name the user/company/roles without
+     * the consumer's org tables). Supply an implementation to return the signed-in
+     * user's display profile (names, never UUIDs). Only meaningful under `auth: true`.
+     */
+    readonly profileResolver?: ProfileResolver;
+    /**
+     * OPTIONAL account/credential-surface seams (forgot/reset, change-password, MFA
+     * enrollment, profile edit). Each is threaded through exactly like
+     * {@link profileResolver}: supplied → bound app-wide under its token; omitted →
+     * bound `null`, so the route that needs it returns an honest 501. Only meaningful
+     * under `auth: true`. See `./ports/*.ts` for each contract.
+     */
+    readonly credentialWriter?: CredentialWriter;
+    readonly resetTokenStore?: ResetTokenStore;
+    readonly emailSender?: EmailSender;
+    readonly recoveryCodeStore?: RecoveryCodeStore;
+    readonly profileWriter?: ProfileWriter;
+    readonly sessionSweeper?: SessionSweeper;
+    /**
+     * OPTIONAL auth-surface audit sink (the {@link AuditSink} port) — persists the
+     * FIRST auth audit event (the recovery-code login, spec §6.2). Threaded exactly like
+     * the other seams: supplied → bound app-wide under its token; omitted → bound `null`,
+     * so the recovery branch's best-effort audit call is a no-op (login still works,
+     * un-audited). Only meaningful under `auth: true`.
+     */
+    readonly auditSink?: AuditSink;
+    /**
+     * OPTIONAL multi-device MFA store (the {@link MfaDeviceStore} port) — persists the
+     * caller's N TOTP authenticator devices. Threaded exactly like the other seams:
+     * supplied → bound app-wide under its token; omitted → bound `null`, so the device
+     * routes return an honest 501. Only meaningful under `auth: true`.
+     */
+    readonly mfaDeviceStore?: MfaDeviceStore;
+    /**
+     * OPTIONAL login `totp` {@link FactorVerifier} override (the Phase-2 multi-device
+     * seam). Supplied → REPLACES the framework's default single-secret
+     * `createTotpFactorVerifier({ hmacSha1 })` in the composed authenticator's
+     * `factorVerifiers`; omitted → the default (behavior unchanged). A consumer plugs
+     * an OR-matching verifier here so login matches ANY enrolled device (the resolver
+     * bundles the N device secrets into one required-factor). Only meaningful under
+     * `auth: true`.
+     */
+    readonly totpVerifier?: FactorVerifier;
+    /**
+     * OPTIONAL root allowlist — the server-side, trusted set of canonical
+     * principal ids that ARE roots (passed to
+     * `createIdentityBroker({ internalRootIds })`). ROOT SAFETY: this is the
+     * ONLY way a login mints a root — the Internal adapter keys the trusted signal
+     * off THIS list, never off a claim (an attacker-controllable `isPlatformSuperuser`
+     * claim is ignored). Omit → `[]` → default-deny (nobody is a root, historical
+     * behavior unchanged). Only meaningful under `auth: true`.
+     */
+    readonly rootIds?: readonly string[];
+    /**
+     * OPTIONAL eager session-facts projector (ADR-0011, the {@link SessionFactsProjector}
+     * port). Threaded exactly like the other seams: supplied → bound app-wide under
+     * {@link SHIELD_SESSION_FACTS_PROJECTOR}; omitted → bound `null`, so the auth controller
+     * omits `cachedFacts` and gate 5 DB-reloads every request (today's behavior). When
+     * supplied, login/refresh cache the principal's coarse grants on the session binding so
+     * gate 5 serves them from the request's `cachedFacts`. Only meaningful under `auth: true`.
+     */
+    readonly sessionFactsProjector?: SessionFactsProjector;
 }
 /**
  * The auth composition module. Imports {@link PersistenceModule} (the live

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

@@ -1 +1 @@
-{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../../src/auth/auth.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,EAAU,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAa3E,OAAO,KAAK,EAGV,kBAAkB,EAOlB,QAAQ,EACT,MAAM,cAAc,CAAC;AA+BtB;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,QACqE,CAAC;AAiL7F;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CAClD;AAED;;;;;;GAMG;AACH,qBACa,UAAU;IACrB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,iBAAsB,GAAG,aAAa;CA8B/D"}
+{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../../src/auth/auth.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,EAAU,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAa3E,OAAO,KAAK,EAGV,kBAAkB,EAOlB,QAAQ,EACR,cAAc,EACf,MAAM,cAAc,CAAC;AAkDtB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAEhF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAIvD;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,QACqE,CAAC;AAE7F;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,EAC3C,eAAe,EAAE,cAAc,GAC9B,cAAc,CAEhB;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,cAAc,CAAC,CAGvE;AAyUD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IACvC;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;CACxD;AAgED;;;;;;GAMG;AACH,qBACa,UAAU;IACrB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,iBAAsB,GAAG,aAAa;CA6F/D"}

package/dist/auth/auth.module.js

@@ -35,7 +35,7 @@
  *        factorVerifiers: [ createTotpFactorVerifier({ hmacSha1 }) ] }).  The TOTP
  *      verifier is wired so MFA works; `hmacSha1` is the {@link hmacSha1} node:crypto
  *      one-liner (guard owns node:crypto, core does not). `createIdentityBroker()`
- *      with no args registers the default Internal adapter with an EMPTY superuser
+ *      with no args registers the default Internal adapter with an EMPTY root
  *      allowlist (default-deny).
  * ─────────────────────────────────────────────────────────────────────────────
  *
@@ -55,7 +55,7 @@
  *
  * An enforcement-only app that does NOT opt in never imports AuthModule → never
  * opens a pool/redis → never calls `assertRefreshHmacKey` → keeps the no-`.env`
- * boot. An auth-enabled app fails LOUD at boot if `SHIELD_REFRESH_HMAC_KEY` is
+ * boot. An auth-enabled app fails LOUD at boot if `REFRESH_HMAC_KEY` is
  * blank — auth can never compose unkeyed. `APP_CONFIG` is already `@Global` from
  * `ShieldModule`, so AuthModule's config-injecting factories resolve. See DONE.md.
  *
@@ -105,6 +105,8 @@ var __importStar = (this && this.__importStar) || (function () {
 var AuthModule_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthModule = exports.hmacSha1 = void 0;
+exports.resolveTotpVerifier = resolveTotpVerifier;
+exports.makeDefaultTotpVerifier = makeDefaultTotpVerifier;
 const common_1 = require("@nestjs/common");
 const node_crypto_1 = require("node:crypto");
 const app_config_js_1 = require("../config/app-config.js");
@@ -114,8 +116,12 @@ const mariadb_credential_resolver_js_1 = require("../authentication/mariadb-cred
 const index_js_1 = require("../session/index.js");
 const persistence_module_js_1 = require("./persistence.module.js");
 const auth_controller_js_1 = require("./auth.controller.js");
+const account_controller_js_1 = require("./account.controller.js");
 const pending_mfa_store_js_1 = require("./pending-mfa-store.js");
 const tokens_js_1 = require("./tokens.js");
+const attempt_limiter_js_1 = require("./rate-limit/attempt-limiter.js");
+const tokens_js_2 = require("../request-auth/tokens.js");
+const session_token_binder_js_1 = require("../request-auth/session-token-binder.js");
 /**
  * The injected HMAC-SHA1 primitive the core TOTP verifier needs (Core is zero-dep
  * + node-type-free, so it cannot import `node:crypto`). Guard owns node:crypto and
@@ -124,6 +130,34 @@ const tokens_js_1 = require("./tokens.js");
  */
 const hmacSha1 = (key, message) => new Uint8Array((0, node_crypto_1.createHmac)('sha1', Buffer.from(key)).update(Buffer.from(message)).digest());
 exports.hmacSha1 = hmacSha1;
+/**
+ * Resolve the login `totp` {@link FactorVerifier}: the consumer's `override` when
+ * supplied, else the framework's `defaultVerifier`. A pure, infra-free `??` — the
+ * ONE decision point of the Phase-2 verifier seam (override wins; absent → the
+ * default RFC-6238 single-secret verify, behavior unchanged).
+ *
+ * The default is passed IN (rather than built here) because the core factory
+ * `createTotpFactorVerifier` is loaded LAZILY via {@link loadCore} (the CJS↔ESM
+ * invariant, see the file header) — only reachable inside an async provider factory.
+ * So the authenticator's async `useFactory` awaits {@link loadCore}, builds the
+ * default, and hands it here alongside the injected override.
+ */
+function resolveTotpVerifier(override, defaultVerifier) {
+    return override ?? defaultVerifier;
+}
+/**
+ * Build the framework's DEFAULT single-secret TOTP {@link FactorVerifier}
+ * (`createTotpFactorVerifier({ hmacSha1 })`), loading the core factory lazily (the
+ * CJS↔ESM invariant, see the file header). Exported so a CONSUMER can obtain the
+ * framework's base per-secret verifier to WRAP (e.g. an OR-matching multi-device
+ * verifier delegates to it per device secret) WITHOUT importing `@astram/core`
+ * directly — which would become a runtime `require` on the ESM-only core in the
+ * consumer's built CJS dist. Async because of {@link loadCore}.
+ */
+async function makeDefaultTotpVerifier() {
+    const { createTotpFactorVerifier } = await loadCore();
+    return createTotpFactorVerifier({ hmacSha1: exports.hmacSha1 });
+}
 /**
  * A `Function`-wrapped dynamic `import()` that survives the CommonJS **build**.
  * Under `module: commonjs`, `tsc` rewrites a literal `import()` into
@@ -207,6 +241,88 @@ const hotSessionStoreProvider = {
     useFactory: (redis) => new index_js_1.RedisHotSessionStore(redis),
     inject: [tokens_js_1.SHIELD_REDIS],
 };
+/**
+ * The request-auth token binder (the flagged-gap fill): binds an opaque access token
+ * to its principal claims in Redis, so the enforcement guard can turn a later
+ * request's bearer token back into a `Principal`. Provided only under `auth: true`
+ * (it needs the live Redis client); exported so the enforcement guard injects it.
+ */
+const sessionTokenBinderProvider = {
+    provide: tokens_js_2.SHIELD_SESSION_TOKEN_BINDER,
+    useFactory: (redis) => new session_token_binder_js_1.SessionTokenBinder(redis),
+    inject: [tokens_js_1.SHIELD_REDIS],
+};
+/**
+ * The password-login rate limiter (spec §5 / H1) — a Redis-injected
+ * {@link AttemptLimiter}, 10 failures / 15-min window, keyed `login:<hint>`. Same
+ * live-Redis provider pattern as {@link sessionTokenBinderProvider} (a `useFactory`
+ * injecting {@link SHIELD_REDIS}); provided only under `auth: true`. Fail-open on a
+ * Redis outage is the limiter's own behavior (never locks out on a blip).
+ */
+const loginLimiterProvider = {
+    provide: tokens_js_1.SHIELD_LOGIN_LIMITER,
+    useFactory: (redis) => new attempt_limiter_js_1.AttemptLimiter(redis, { maxAttempts: 10, windowMs: 15 * 60 * 1000 }),
+    inject: [tokens_js_1.SHIELD_REDIS],
+};
+/**
+ * The recovery-code rate limiter (spec §5) — a Redis-injected {@link AttemptLimiter},
+ * 5 failures / 15-min window, keyed `recovery:<principalId>` (a lower ceiling than
+ * login: recovery codes don't rotate, so they're higher-value). Same live-Redis
+ * provider pattern as {@link sessionTokenBinderProvider}; provided only under
+ * `auth: true`.
+ */
+const recoveryLimiterProvider = {
+    provide: tokens_js_1.SHIELD_RECOVERY_LIMITER,
+    useFactory: (redis) => new attempt_limiter_js_1.AttemptLimiter(redis, { maxAttempts: 5, windowMs: 15 * 60 * 1000 }),
+    inject: [tokens_js_1.SHIELD_REDIS],
+};
+/**
+ * The forgot-password rate limiter (feature #141) — a Redis-injected
+ * {@link AttemptLimiter}, keyed BY CLIENT IP (`forgot:ip:<ip>`, 5 per 15-min window)
+ * AND, separately, per-hint (`forgot:<hint>`, provided as {@link forgotHintLimiterProvider}).
+ * NOTE the "attempt" semantics here differ from login: forgot-password is ALWAYS 204
+ * (returning 429 would itself be an enumeration signal), so this limiter counts every
+ * forgot REQUEST (a request-rate cap), and once the budget is exceeded the handler
+ * SILENTLY skips the email-send work while still returning 204. Same live-Redis
+ * provider pattern as {@link loginLimiterProvider}; provided only under `auth: true`.
+ * Fail-open on a Redis outage is the limiter's own behavior (never silently drops a
+ * legitimate reset email on a blip). Threshold chosen to stop IP-spray without locking
+ * out a genuine user who requests a couple of resets.
+ */
+const forgotLimiterProvider = {
+    provide: tokens_js_1.SHIELD_FORGOT_LIMITER,
+    useFactory: (redis) => new attempt_limiter_js_1.AttemptLimiter(redis, { maxAttempts: 5, windowMs: 15 * 60 * 1000 }),
+    inject: [tokens_js_1.SHIELD_REDIS],
+};
+/**
+ * The forgot-password PER-HINT rate limiter (feature #141) — a Redis-injected
+ * {@link AttemptLimiter}, keyed by the presented hint (`forgot:<hint>`, 3 per 60-min
+ * window). This caps how often ANY caller (across IPs) can trigger a reset email for
+ * ONE account, so a single victim's inbox can't be email-bombed even from a rotating
+ * IP pool. A GENEROUS per-hint ceiling (a real user rarely needs >3 reset emails/hour)
+ * with a longer window than the IP cap. Same request-rate-cap semantics as
+ * {@link forgotLimiterProvider}: on exceed, SILENTLY skip the send, still 204.
+ */
+const forgotHintLimiterProvider = {
+    provide: tokens_js_1.SHIELD_FORGOT_HINT_LIMITER,
+    useFactory: (redis) => new attempt_limiter_js_1.AttemptLimiter(redis, { maxAttempts: 3, windowMs: 60 * 60 * 1000 }),
+    inject: [tokens_js_1.SHIELD_REDIS],
+};
+/**
+ * The reset-password rate limiter (feature #141) — a Redis-injected
+ * {@link AttemptLimiter}, keyed by CLIENT IP (`reset:ip:<ip>`, 10 per 15-min window).
+ * Reset is token-gated (a 256-bit single-use token), so this is DoS/abuse throttling,
+ * NOT anti-brute-force — and unlike forgot it MAY return a generic 429 on lockout (a
+ * token-gated endpoint is not enumeration-sensitive). `recordFailure` on a bad/invalid
+ * token (the abuse signal), `reset` on a successful reset. Same live-Redis provider
+ * pattern as {@link loginLimiterProvider}; provided only under `auth: true`. Fail-open
+ * on a Redis outage (a legitimate reset is never blocked by a blip).
+ */
+const resetLimiterProvider = {
+    provide: tokens_js_1.SHIELD_RESET_LIMITER,
+    useFactory: (redis) => new attempt_limiter_js_1.AttemptLimiter(redis, { maxAttempts: 10, windowMs: 15 * 60 * 1000 }),
+    inject: [tokens_js_1.SHIELD_REDIS],
+};
 /** Opaque token generator (node:crypto adapter). */
 const tokenGeneratorProvider = {
     provide: index_js_1.SHIELD_TOKEN_GENERATOR,
@@ -252,20 +368,133 @@ const sessionAuthorityProvider = {
         config_module_js_1.APP_CONFIG,
     ],
 };
-/** The composed Authenticator (core) — password + TOTP factor, anti-enumeration. */
+/**
+ * The composed Authenticator (core) — password + TOTP factor, anti-enumeration.
+ *
+ * The `totp` verifier is the Phase-2 SEAM: {@link resolveTotpVerifier} picks the
+ * consumer's `totpOverride` (bound under {@link SHIELD_TOTP_VERIFIER_OVERRIDE}) when
+ * supplied, else the framework's default `createTotpFactorVerifier({ hmacSha1 })`.
+ * The override reaches this async factory via `inject` (not a captured closure) so
+ * the default binding stays exactly as before when no override is plugged.
+ */
 const authenticatorProvider = {
     provide: tokens_js_1.SHIELD_AUTHENTICATOR,
     // async: loads the core factories lazily (CJS→ESM, see loadCore()); Nest awaits it.
-    useFactory: async (hasher, resolver) => {
+    useFactory: async (hasher, resolver, totpOverride, rootIds) => {
         const { createAuthenticator, createIdentityBroker, createTotpFactorVerifier } = await loadCore();
+        const totp = resolveTotpVerifier(totpOverride, createTotpFactorVerifier({ hmacSha1: exports.hmacSha1 }));
         return createAuthenticator({
             hasher,
             resolver,
-            identityBroker: createIdentityBroker(),
-            factorVerifiers: [createTotpFactorVerifier({ hmacSha1: exports.hmacSha1 })],
+            // ROOT SAFETY: the ONLY way a login mints a root is the
+            // server-side allowlist wired here (the Internal adapter keys the trusted
+            // signal off it, never off a claim). Absent → `[]` → default-deny (the
+            // historical `createIdentityBroker()` behavior, exactly unchanged).
+            identityBroker: createIdentityBroker({ internalRootIds: rootIds ?? [] }),
+            factorVerifiers: [totp],
         });
     },
-    inject: [argon2id_password_hasher_js_1.SHIELD_PASSWORD_HASHER, tokens_js_1.SHIELD_CREDENTIAL_RESOLVER],
+    inject: [
+        argon2id_password_hasher_js_1.SHIELD_PASSWORD_HASHER,
+        tokens_js_1.SHIELD_CREDENTIAL_RESOLVER,
+        tokens_js_1.SHIELD_TOTP_VERIFIER_OVERRIDE,
+        tokens_js_1.SHIELD_ROOT_IDS,
+    ],
+};
+/**
+ * Bind the OPTIONAL login `totp` verifier override (the Phase-2 multi-device seam).
+ * Same value-provider pattern as the other seams: the supplied verifier when present,
+ * else `null` so the authenticator factory's inject resolves to "no override" → the
+ * default RFC-6238 verifier. Always provided so the DI token exists.
+ */
+function makeTotpVerifierOverrideProvider(override) {
+    return { provide: tokens_js_1.SHIELD_TOTP_VERIFIER_OVERRIDE, useValue: override ?? null };
+}
+/**
+ * Bind the OPTIONAL root allowlist (the {@link SHIELD_ROOT_IDS}
+ * seam). Same value-provider pattern as the other seams: the supplied ids when present,
+ * else `null` so the authenticator factory's inject resolves to "no allowlist" → the
+ * broker's default-deny empty set (nobody is a root — historical behavior). Always
+ * provided so the DI token exists. See {@link SHIELD_ROOT_IDS} for the security
+ * rationale (the flag is set SOLELY from this trusted list, never from a claim).
+ */
+function makeRootIdsProvider(rootIds) {
+    return { provide: tokens_js_1.SHIELD_ROOT_IDS, useValue: rootIds ?? null };
+}
+/**
+ * The core TOTP {@link FactorVerifier} — the SAME verifier the login MFA branch uses
+ * (`createTotpFactorVerifier({ hmacSha1 })`), provided app-wide so
+ * `POST /account/mfa/{enroll/confirm,disable}` can verify a presented code against the
+ * pending/stored secret. Built via {@link loadCore} (the CJS→ESM lazy load, see the
+ * file header) so guard's built CJS dist never eagerly `require`s the ESM-only core.
+ * Injected pre-built into {@link AccountController}, which cannot import the core
+ * factory at its own top level.
+ */
+const totpVerifierProvider = {
+    provide: tokens_js_1.SHIELD_TOTP_VERIFIER,
+    useFactory: async () => {
+        const { createTotpFactorVerifier } = await loadCore();
+        return createTotpFactorVerifier({ hmacSha1: exports.hmacSha1 });
+    },
+};
+/**
+ * Bind the OPTIONAL current-user profile resolver. When the consumer supplies one it
+ * is a value provider under {@link SHIELD_PROFILE_RESOLVER}; when absent we bind
+ * `null` so the `@Optional()` injection in the controller resolves cleanly to
+ * "no seam" (→ `/auth/me` returns 501). Always provided so the DI token exists.
+ */
+function makeProfileResolverProvider(override) {
+    return { provide: tokens_js_1.SHIELD_PROFILE_RESOLVER, useValue: override ?? null };
+}
+/**
+ * Bind each OPTIONAL account/credential-surface seam. Same pattern as
+ * {@link makeProfileResolverProvider}: a value provider under the seam's token —
+ * the supplied impl when present, else `null` so the route's `@Optional()` injection
+ * resolves cleanly to "no seam" (→ 501). Always provided so the DI token exists.
+ */
+function makeCredentialWriterProvider(override) {
+    return { provide: tokens_js_1.SHIELD_CREDENTIAL_WRITER, useValue: override ?? null };
+}
+function makeResetTokenStoreProvider(override) {
+    return { provide: tokens_js_1.SHIELD_RESET_TOKEN_STORE, useValue: override ?? null };
+}
+function makeEmailSenderProvider(override) {
+    return { provide: tokens_js_1.SHIELD_EMAIL_SENDER, useValue: override ?? null };
+}
+function makeRecoveryCodeStoreProvider(override) {
+    return { provide: tokens_js_1.SHIELD_RECOVERY_CODE_STORE, useValue: override ?? null };
+}
+function makeProfileWriterProvider(override) {
+    return { provide: tokens_js_1.SHIELD_PROFILE_WRITER, useValue: override ?? null };
+}
+function makeSessionSweeperProvider(override) {
+    return { provide: tokens_js_1.SHIELD_SESSION_SWEEPER, useValue: override ?? null };
+}
+function makeMfaDeviceStoreProvider(override) {
+    return { provide: tokens_js_1.SHIELD_MFA_DEVICE_STORE, useValue: override ?? null };
+}
+function makeAuditSinkProvider(override) {
+    return { provide: tokens_js_1.SHIELD_AUDIT_SINK, useValue: override ?? null };
+}
+/**
+ * Bind the OPTIONAL eager session-facts projector (ADR-0011). Same value-provider
+ * pattern as the other seams: the supplied impl when present, else `null` so the auth
+ * controller's `@Optional()` injection resolves cleanly to "no projector" (→ it omits
+ * `cachedFacts` → gate 5 DB-reloads). Always provided so the DI token exists.
+ */
+function makeSessionFactsProjectorProvider(override) {
+    return { provide: tokens_js_1.SHIELD_SESSION_FACTS_PROJECTOR, useValue: override ?? null };
+}
+/**
+ * The reset-link base URL the forgot-password handler builds the emailed link from
+ * (`${base}?token=<rawToken>`). A plain string VALUE (not a seam) resolved from the
+ * environment (`RESET_LINK_BASE_URL`) with a dev default, so the framework owns the
+ * URL composition and {@link SHIELD_EMAIL_SENDER} stays URL-agnostic. Always
+ * provided so the `@Optional()` injection resolves.
+ */
+const resetLinkBaseUrlProvider = {
+    provide: tokens_js_1.SHIELD_RESET_LINK_BASE_URL,
+    useValue: process.env.RESET_LINK_BASE_URL ?? 'http://localhost:5173/reset-password',
 };
 /**
  * The auth composition module. Imports {@link PersistenceModule} (the live
@@ -285,13 +514,40 @@ let AuthModule = AuthModule_1 = class AuthModule {
         return {
             module: AuthModule_1,
             imports: [persistence_module_js_1.PersistenceModule.forRoot()],
+            // (providers list below adds the profile-resolver seam)
             // Team C's four `@Public()` /auth/* endpoints. Registered here (integration
             // wiring) so the routes exist the moment auth is opted in — the controller
             // injects the two composed engines (below) + PendingMfaStore.
-            controllers: [auth_controller_js_1.AuthController],
+            controllers: [auth_controller_js_1.AuthController, account_controller_js_1.AccountController],
             providers: [
                 passwordHasherProvider,
                 makeCredentialResolverProvider(options.credentialResolver),
+                // The current-user profile seam backing `GET /auth/me` (null when absent).
+                makeProfileResolverProvider(options.profileResolver),
+                // The account/credential-surface seams (null when absent → route 501).
+                makeCredentialWriterProvider(options.credentialWriter),
+                makeResetTokenStoreProvider(options.resetTokenStore),
+                makeEmailSenderProvider(options.emailSender),
+                makeRecoveryCodeStoreProvider(options.recoveryCodeStore),
+                makeProfileWriterProvider(options.profileWriter),
+                makeSessionSweeperProvider(options.sessionSweeper),
+                // The auth-surface audit sink (null when absent → recovery-login audit no-ops).
+                makeAuditSinkProvider(options.auditSink),
+                // The multi-device MFA store (null when absent → device routes 501).
+                makeMfaDeviceStoreProvider(options.mfaDeviceStore),
+                // The login totp-verifier override (null when absent → default RFC-6238
+                // single-secret verify). Consumed by the authenticator factory.
+                makeTotpVerifierOverrideProvider(options.totpVerifier),
+                // The root allowlist (null when absent → broker default-deny).
+                // Consumed by the authenticator factory (createIdentityBroker). ROOT
+                // SAFETY: the ONLY source of the isRoot flag.
+                makeRootIdsProvider(options.rootIds),
+                // The eager session-facts projector (ADR-0011; null when absent → the auth
+                // controller omits cachedFacts → gate 5 DB-reloads). Consumed by AuthController.
+                makeSessionFactsProjectorProvider(options.sessionFactsProjector),
+                // The reset-link base URL value the forgot-password handler composes into the
+                // emailed link (framework-owned URL composition; EmailSender stays dumb).
+                resetLinkBaseUrlProvider,
                 sessionRecordStoreProvider,
                 hotSessionStoreProvider,
                 tokenGeneratorProvider,
@@ -299,15 +555,51 @@ let AuthModule = AuthModule_1 = class AuthModule {
                 clockProvider,
                 sessionAuthorityProvider,
                 authenticatorProvider,
+                // The core TOTP verifier (login MFA + account MFA enroll/disable share it).
+                totpVerifierProvider,
                 // Team C's server-side, single-use, TTL'd challenge store backing the
                 // login→mfa handoff (a plain class provider the controller injects).
                 pending_mfa_store_js_1.PendingMfaStore,
+                // The request-auth token binder (access-token → principal claims).
+                sessionTokenBinderProvider,
+                // The anti-brute-force rate limiters (spec §5): login (H1) + recovery, each
+                // a Redis-injected AttemptLimiter with its own threshold. Injected into
+                // AuthController (@Optional()).
+                loginLimiterProvider,
+                recoveryLimiterProvider,
+                // The forgot/reset-password limiters (feature #141): forgot keyed by client IP
+                // + per-hint (request-rate caps → silently skip the send when exceeded, stays
+                // 204); reset keyed by client IP (may 429 on lockout — token-gated, not enum-
+                // sensitive). Injected into AuthController (@Optional()).
+                forgotLimiterProvider,
+                forgotHintLimiterProvider,
+                resetLimiterProvider,
             ],
             exports: [
                 tokens_js_1.SHIELD_AUTHENTICATOR,
                 tokens_js_1.SHIELD_SESSION_AUTHORITY,
                 tokens_js_1.SHIELD_CREDENTIAL_RESOLVER,
                 argon2id_password_hasher_js_1.SHIELD_PASSWORD_HASHER,
+                // Exported so the (app-wide) enforcement guard can inject it.
+                tokens_js_2.SHIELD_SESSION_TOKEN_BINDER,
+                // The account/credential-surface seams — exported so the consumer's impls
+                // and the account/auth controllers see them app-wide through @Global Shield.
+                tokens_js_1.SHIELD_CREDENTIAL_WRITER,
+                tokens_js_1.SHIELD_RESET_TOKEN_STORE,
+                tokens_js_1.SHIELD_EMAIL_SENDER,
+                tokens_js_1.SHIELD_RECOVERY_CODE_STORE,
+                tokens_js_1.SHIELD_PROFILE_WRITER,
+                tokens_js_1.SHIELD_SESSION_SWEEPER,
+                // The auth-surface audit sink (consumed by the /auth/mfa recovery branch).
+                tokens_js_1.SHIELD_AUDIT_SINK,
+                // The multi-device MFA store (consumed by /account/mfa/devices/*).
+                tokens_js_1.SHIELD_MFA_DEVICE_STORE,
+                // The reset-link base URL value (consumed by /auth/forgot-password).
+                tokens_js_1.SHIELD_RESET_LINK_BASE_URL,
+                // The core TOTP verifier (consumed by /account/mfa/{enroll/confirm,disable}).
+                tokens_js_1.SHIELD_TOTP_VERIFIER,
+                // The eager session-facts projector (consumed by AuthController).
+                tokens_js_1.SHIELD_SESSION_FACTS_PROJECTOR,
             ],
         };
     }

package/dist/auth/dto.d.ts

@@ -56,6 +56,14 @@ export interface SessionTokensView {
 export interface SessionSuccess {
     readonly session: SessionView;
     readonly tokens: SessionTokensView;
+    /**
+     * Set to `true` ONLY when the session was completed via a RECOVERY CODE at the
+     * `/auth/mfa` step (the lost-device escape hatch). Absent on every normal
+     * password / TOTP / refresh success, so those paths are byte-for-byte
+     * unaffected. The frontend keys off this to route the recovered session into
+     * the enforced re-enroll flow. Carries NO secret — a pure signal flag.
+     */
+    readonly mfaRecoveryUsed?: boolean;
 }
 /** `POST /auth/login` request body. */
 export interface LoginRequest {
@@ -85,16 +93,18 @@ export interface MfaChallengeResponse {
 export type LoginResponse = SessionSuccess | MfaChallengeResponse;
 /**
  * `POST /auth/mfa` request body — completes a pending MFA challenge. `factor` is
- * `'totp'` in Phase 0b (the only real factor; WebAuthn/recovery are contract slots
- * only). `code` is the presented one-time code (digits). ⛔ `code` is single-use
- * material — never logged.
+ * `'totp'` (an authenticator code) or `'recovery_code'` (the lost-device escape
+ * hatch — a pre-issued single-use recovery code, verified in a separate branch,
+ * see `auth.controller.ts`). WebAuthn remains a contract slot only. `code` is the
+ * presented one-time code / recovery code. ⛔ `code` is single-use material —
+ * never logged.
  */
 export interface MfaRequest {
     /** The opaque handle from {@link MfaChallengeResponse}. Short-TTL, single-use. */
     readonly challengeToken: string;
-    /** The second-factor class being satisfied (Phase 0b: `'totp'`). */
-    readonly factor: 'totp';
-    /** The presented one-time code. NEVER logged. */
+    /** The second-factor class being satisfied (`'totp'` or `'recovery_code'`). */
+    readonly factor: 'totp' | 'recovery_code';
+    /** The presented one-time code / recovery code. NEVER logged. */
     readonly code: string;
 }
 /**

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,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,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;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,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":"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,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;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"}

package/dist/auth/ports/audit-sink.d.ts

@@ -0,0 +1,47 @@
+/**
+ * AuditSink — the auth-surface **audit seam** (spec §6.2). The auth surface is
+ * otherwise un-audited (only the @astram/engine pipe audits record CRUD); this port
+ * introduces the FIRST auth audit event. The framework builds the event; the consumer
+ * persists it (astram3 writes `shield_audit.audit_log`).
+ *
+ * OPTIONAL, consumer-plugged through `ShieldModule.forRoot({ auditSink })` and threaded
+ * to `AuthModule.forRoot` exactly like the other account/credential seams. Absent
+ * (`null`) → the route still works, just un-audited (the `@Optional()` injection in
+ * `AuthController` resolves to no seam → the best-effort call is a no-op).
+ *
+ * BEST-EFFORT by contract: `record` is invoked fire-and-forget on the recovery-login
+ * success path — a throwing or slow sink NEVER fails the (legitimate) login. The
+ * consumer's impl should not surface errors into the response path.
+ *
+ * NO SECRET LEAK: the event carries NO password, recovery code, TOTP secret, or token —
+ * only the actor id, tenant, action key, and non-secret attributes.
+ */
+/**
+ * A framework-built auth audit event. `type` is the audit category (`'authentication'`
+ * for the auth surface); `action` is the specific event key (e.g. `'mfa.recovery_used'`).
+ * `attributes` carries non-secret structured detail (never a code/token/secret).
+ */
+export interface AuthAuditEvent {
+    /** The audit category. Always `'authentication'` for auth-surface events. */
+    readonly type: 'authentication';
+    /** When the event occurred (epoch ms). */
+    readonly occurredAtMs: number;
+    /** The acting principal's id (the account the event is about). */
+    readonly actorId: string;
+    /** The active tenant/company the event is scoped to, if known. */
+    readonly tenantId?: string;
+    /** The specific event key, e.g. `'mfa.recovery_used'`. */
+    readonly action: string;
+    /** Non-secret structured detail. NEVER a code / token / secret. */
+    readonly attributes?: Record<string, unknown>;
+}
+/**
+ * The port a consumer implements to persist auth audit events. Supplied to the
+ * framework via `ShieldModule.forRoot({ auditSink })`. Best-effort: `record` is called
+ * fire-and-forget, so an impl error must not propagate into the login response.
+ */
+export interface AuditSink {
+    /** Persist one auth audit event. Best-effort — never fails the caller's flow. */
+    record(event: AuthAuditEvent): Promise<void>;
+}
+//# sourceMappingURL=audit-sink.d.ts.map

package/dist/auth/ports/audit-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-sink.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/audit-sink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/C;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,iFAAiF;IACjF,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C"}