@astram/guard 0.6.0 → 0.8.0

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

@@ -136,7 +136,16 @@ export interface AuthModuleOptions {
      */
     readonly credentialWriter?: CredentialWriter;
     readonly resetTokenStore?: ResetTokenStore;
-    readonly emailSender?: EmailSender;
+    /**
+     * The password-reset email delivery seam (security hardening #6):
+     *  - an {@link EmailSender} → used in every environment (production needs one);
+     *  - `'disabled'` → a no-op sender: forgot-password still answers 204, nothing is
+     *    delivered or printed, one startup warning;
+     *  - omitted → the dev `LogEmailSender` (prints reset links to stdout) ONLY when the raw
+     *    `NODE_ENV` is `development` or `test`; otherwise (incl. unset `NODE_ENV`) auth
+     *    composition throws "auth:true requires `emailSender` (or `emailSender: 'disabled'`)".
+     */
+    readonly emailSender?: EmailSender | 'disabled';
     readonly recoveryCodeStore?: RecoveryCodeStore;
     readonly profileWriter?: ProfileWriter;
     readonly sessionSweeper?: SessionSweeper;
@@ -210,6 +219,11 @@ export interface AuthModuleOptions {
      */
     readonly membershipChecker?: MembershipChecker;
 }
+/**
+ * The no-override default sender decision (pure apart from the warning). Exported for
+ * the unit test only — not part of the package's public surface.
+ */
+export declare function resolveDefaultEmailSender(rawNodeEnv: string | undefined): EmailSender;
 /**
  * The auth composition module. Imports {@link PersistenceModule} (the live
  * connections) and provides the adapters + composed engines. Exports the two

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":"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"}
+{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../../src/auth/auth.module.ts"],"names":[],"mappings":"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"}

package/dist/auth/auth.module.js

@@ -107,6 +107,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthModule = exports.hmacSha1 = void 0;
 exports.resolveTotpVerifier = resolveTotpVerifier;
 exports.makeDefaultTotpVerifier = makeDefaultTotpVerifier;
+exports.resolveDefaultEmailSender = resolveDefaultEmailSender;
 const common_1 = require("@nestjs/common");
 const node_crypto_1 = require("node:crypto");
 const app_config_js_1 = require("../config/app-config.js");
@@ -121,6 +122,7 @@ const mariadb_recovery_code_store_js_1 = require("../authentication/mariadb-reco
 const mariadb_mfa_device_store_js_1 = require("../authentication/mariadb-mfa-device-store.js");
 const mariadb_session_sweeper_js_1 = require("../authentication/mariadb-session-sweeper.js");
 const log_email_sender_js_1 = require("../authentication/log-email-sender.js");
+const noop_email_sender_js_1 = require("../authentication/noop-email-sender.js");
 const mariadb_or_totp_verifier_js_1 = require("../authentication/mariadb-or-totp-verifier.js");
 const permission_facts_adapter_js_1 = require("../identity/permission-facts.adapter.js");
 const auth_facts_controller_js_1 = require("../identity/auth-facts.controller.js");
@@ -129,9 +131,15 @@ 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 mfa_step_up_js_1 = require("./mfa-step-up.js");
 const tokens_js_1 = require("./tokens.js");
+const permission_version_cache_js_1 = require("../authz/permission-version-cache.js");
+const session_restriction_store_js_1 = require("../session/session-restriction-store.js");
 const attempt_limiter_js_1 = require("./rate-limit/attempt-limiter.js");
+const trust_proxy_check_js_1 = require("./rate-limit/trust-proxy-check.js");
 const tokens_js_2 = require("../request-auth/tokens.js");
+const mariadb_api_key_store_js_1 = require("../authentication/mariadb-api-key-store.js");
+const core_1 = require("@astram/core");
 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
@@ -236,14 +244,53 @@ function makeCredentialResolverProvider(override) {
         ? { provide: tokens_js_1.SHIELD_CREDENTIAL_RESOLVER, useValue: override }
         : {
             provide: tokens_js_1.SHIELD_CREDENTIAL_RESOLVER,
-            useFactory: (pool) => new mariadb_credential_resolver_js_1.MariaDbCredentialResolver(pool),
-            inject: [tokens_js_1.SHIELD_DB_POOL],
+            // #7: the default resolver folds the principal's CONFIRMED MFA devices into a
+            // `totp` required factor, so enrolled MFA is enforced at every password login.
+            useFactory: (pool, devices) => new mariadb_credential_resolver_js_1.MariaDbCredentialResolver(pool, devices),
+            inject: [tokens_js_1.SHIELD_DB_POOL, tokens_js_1.SHIELD_MFA_DEVICE_STORE],
         };
 }
-/** Durable session record store (MariaDB adapter, injected with the live pool). */
+/**
+ * The resolved, validated session lifetimes (ADR-0015) — the ONE source the session
+ * authority, the token binder and the auth controller read (security hardening #8).
+ */
+const sessionLifetimesProvider = {
+    provide: index_js_1.SHIELD_SESSION_LIFETIMES,
+    useFactory: (config) => (0, core_1.resolveLifetimes)(config.lifetimes),
+    inject: [config_module_js_1.APP_CONFIG],
+};
+/**
+ * Durable session record store (MariaDB adapter, injected with the live pool), decorated
+ * by {@link HotRevokingSessionRecordStore} (M-A): a durable lineage / session revoke is
+ * followed by a Redis unbind, so a reuse-killed session's live access token dies on its
+ * next request (the request path stays Redis-only).
+ */
 const sessionRecordStoreProvider = {
     provide: index_js_1.SHIELD_SESSION_RECORD_STORE,
-    useFactory: (pool) => new index_js_1.MariaDbSessionRecordStore(pool),
+    useFactory: (pool, binder) => {
+        const durable = new index_js_1.MariaDbSessionRecordStore(pool);
+        return new index_js_1.HotRevokingSessionRecordStore(durable, binder, durable);
+    },
+    inject: [tokens_js_1.SHIELD_DB_POOL, tokens_js_2.SHIELD_SESSION_TOKEN_BINDER],
+};
+/**
+ * The Redis permission-version cache (ADR-0035, GAPS #6): gate 5 reads the tenant's version from
+ * Redis (one GET) instead of MariaDB, and identity's bumper publishes to it after commit. Exported
+ * so the framework-built decision authority (ShieldModule) and the identity bumper inject it.
+ */
+const permissionVersionCacheProvider = {
+    provide: tokens_js_1.SHIELD_PERMISSION_VERSION_CACHE,
+    useFactory: (redis) => new permission_version_cache_js_1.RedisPermissionVersionCache(redis),
+    inject: [tokens_js_1.SHIELD_REDIS],
+};
+/**
+ * The durable session-restriction store (Phase 3B review P1): the recovery-login re-enroll marker
+ * on `shield_identity.session` + the account status the refresh rebuild checks. Exported so the
+ * account controller (device confirm) clears the marker.
+ */
+const sessionRestrictionStoreProvider = {
+    provide: tokens_js_1.SHIELD_SESSION_RESTRICTIONS,
+    useFactory: (pool) => new session_restriction_store_js_1.MariaDbSessionRestrictionStore(pool),
     inject: [tokens_js_1.SHIELD_DB_POOL],
 };
 /** Hot session store (Redis adapter, injected with the live client). */
@@ -260,12 +307,64 @@ const hotSessionStoreProvider = {
  */
 const sessionTokenBinderProvider = {
     provide: tokens_js_2.SHIELD_SESSION_TOKEN_BINDER,
-    useFactory: (redis) => new session_token_binder_js_1.SessionTokenBinder(redis),
+    // #8: the session-claims (liveness) entry lives for the refresh idle window, and the
+    // previous access token keeps a 30 s grace after a rotation (plan D7).
+    useFactory: (redis, lifetimes) => new session_token_binder_js_1.SessionTokenBinder(redis, {
+        sessionClaimsTtlMs: lifetimes.refreshIdleMs,
+        rotateGraceMs: index_js_1.ROTATE_GRACE_MS,
+    }),
+    inject: [tokens_js_1.SHIELD_REDIS, index_js_1.SHIELD_SESSION_LIFETIMES],
+};
+/**
+ * The pending-MFA challenge store (M6): Redis-backed, so `/auth/mfa` completes on any
+ * instance, and it holds the password step's RESULT (principal + hint + credential
+ * fingerprint) — never the password. Bound under the {@link PendingMfaStore} class token
+ * the controller injects.
+ */
+const pendingMfaStoreProvider = {
+    provide: pending_mfa_store_js_1.PendingMfaStore,
+    useFactory: (redis) => new pending_mfa_store_js_1.RedisPendingMfaStore(redis),
     inject: [tokens_js_1.SHIELD_REDIS],
 };
+/**
+ * The TOTP-step limiter (#9) — 5 failures / 15-min window, keyed `mfa:pid:<principalId>`.
+ * Checked before the factor is verified; fails open on a Redis outage like every limiter
+ * (the code itself still gates — and its replay guard fails closed).
+ */
+const mfaLimiterProvider = {
+    provide: tokens_js_1.SHIELD_MFA_LIMITER,
+    useFactory: (redis) => new attempt_limiter_js_1.AttemptLimiter(redis, { maxAttempts: 5, windowMs: 15 * 60 * 1000 }),
+    inject: [tokens_js_1.SHIELD_REDIS],
+};
+/**
+ * The service-account API-key authenticator (ADR-0033) — resolves an `Authorization: Bearer ask_…`
+ * into a `service_account` Principal. Built HERE (in the guard's own AuthModule) over the live
+ * {@link SHIELD_DB_POOL} + the framework Argon2id hasher, and EXPORTED so the `APP_GUARD` (in this
+ * same module tree) injects it — the SAME reason the {@link sessionTokenBinderProvider} lives here.
+ *
+ * WHY HERE, not in the consumer's identity module: the enforcement guard is provided by ShieldModule;
+ * a token provided in a later, sibling feature module is NOT visible to it (that DI boundary made an
+ * identity-module-provided authenticator resolve to `undefined` → an `ask_…` bearer 401'd). Providing
+ * it alongside the guard (like the binder) is what makes the machine auth path work out-of-the-box
+ * under `auth: true`. The store reads `shield_authz.service_account_key` (created by the framework
+ * migration); the account admin surface lives in @astram/identity, but AUTHENTICATION is the guard's.
+ */
+const serviceAuthenticatorProvider = {
+    provide: tokens_js_2.SHIELD_SERVICE_AUTHENTICATOR,
+    useFactory: (pool) => (0, core_1.createServiceAuthenticator)({
+        store: new mariadb_api_key_store_js_1.MariaDbApiKeyStore(pool),
+        hasher: new argon2id_password_hasher_js_1.Argon2idPasswordHasher(),
+    }),
+    inject: [tokens_js_1.SHIELD_DB_POOL],
+};
+/** Boot-time warnings from the auth composition (dev email logger, disabled email, …). */
+const authBootLogger = new common_1.Logger('ShieldAuth');
 /**
  * The password-login rate limiter (spec §5 / H1) — a Redis-injected
- * {@link AttemptLimiter}, 10 failures / 15-min window, keyed `login:<hint>`. Same
+ * {@link AttemptLimiter}, 10 failures / 15-min window, keyed
+ * per ACCOUNT, `login:pid:<principalId>` (security hardening #5 / review F1: every spelling
+ * the DB collation maps to one account shares one budget; an unknown hint falls back to
+ * `login:<sha256(canonical hint)>`; no PII in the Redis key). 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).
@@ -275,6 +374,22 @@ const loginLimiterProvider = {
     useFactory: (redis) => new attempt_limiter_js_1.AttemptLimiter(redis, { maxAttempts: 10, windowMs: 15 * 60 * 1000 }),
     inject: [tokens_js_1.SHIELD_REDIS],
 };
+/**
+ * The per-client-IP password-login FAILURE limiter (security hardening #5, plan D3) — a
+ * Redis-injected {@link AttemptLimiter} keyed `login:ip:<req.ip>`, default 50 failures /
+ * 15-min window, configurable through `AppConfig.loginIpLimit` (env
+ * `LOGIN_IP_MAX_FAILURES` / `LOGIN_IP_WINDOW_MS`). Stops password spraying across many
+ * distinct hints from one client. Failures only; never reset on success. Fails open on
+ * a Redis outage like every limiter. ENFORCED ONLY when the app set Express `trust proxy`
+ * explicitly (0 = no proxy, else the hop count); otherwise {@link TrustProxyBootCheck}
+ * switches it OFF at boot with a warning, because every client behind a proxy would share
+ * one IP and 50 failures would lock everyone out.
+ */
+const loginIpLimiterProvider = {
+    provide: tokens_js_1.SHIELD_LOGIN_IP_LIMITER,
+    useFactory: (redis, config) => new attempt_limiter_js_1.AttemptLimiter(redis, config.loginIpLimit ?? app_config_js_1.DEFAULT_LOGIN_IP_LIMIT),
+    inject: [tokens_js_1.SHIELD_REDIS, config_module_js_1.APP_CONFIG],
+};
 /**
  * The recovery-code rate limiter (spec §5) — a Redis-injected {@link AttemptLimiter},
  * 5 failures / 15-min window, keyed `recovery:<principalId>` (a lower ceiling than
@@ -289,7 +404,8 @@ const recoveryLimiterProvider = {
 };
 /**
  * The forgot-password rate limiter (feature #141) — a Redis-injected
- * {@link AttemptLimiter}, keyed BY CLIENT IP (`forgot:ip:<ip>`, 5 per 15-min window)
+ * {@link AttemptLimiter}, keyed BY CLIENT IP (`forgot:ip:<ip>`, 5 per 15-min window;
+ * enforced only with an explicit Express `trust proxy`, see {@link TrustProxyBootCheck})
  * 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
@@ -307,7 +423,7 @@ const forgotLimiterProvider = {
 };
 /**
  * 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
+ * {@link AttemptLimiter}, keyed per account (`forgot:pid:<principalId>`, unknown → `forgot:<sha256(canonical)>`), 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)
@@ -321,7 +437,8 @@ const forgotHintLimiterProvider = {
 };
 /**
  * The reset-password rate limiter (feature #141) — a Redis-injected
- * {@link AttemptLimiter}, keyed by CLIENT IP (`reset:ip:<ip>`, 10 per 15-min window).
+ * {@link AttemptLimiter}, keyed by CLIENT IP (`reset:ip:<ip>`, 10 per 15-min window;
+ * enforced only with an explicit Express `trust proxy`, see {@link TrustProxyBootCheck}).
  * 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
@@ -359,7 +476,7 @@ const clockProvider = {
 const sessionAuthorityProvider = {
     provide: tokens_js_1.SHIELD_SESSION_AUTHORITY,
     // async: loads the core factory lazily (CJS→ESM, see loadCore()); Nest awaits it.
-    useFactory: async (recordStore, hotStore, tokenGenerator, refreshHasher, clock, config) => {
+    useFactory: async (recordStore, hotStore, tokenGenerator, refreshHasher, clock, lifetimes) => {
         const { createSessionAuthority } = await loadCore();
         return createSessionAuthority({
             recordStore,
@@ -367,7 +484,7 @@ const sessionAuthorityProvider = {
             tokenGenerator,
             refreshHasher,
             clock,
-            lifetimes: config.lifetimes,
+            lifetimes,
         });
     },
     inject: [
@@ -376,7 +493,7 @@ const sessionAuthorityProvider = {
         index_js_1.SHIELD_TOKEN_GENERATOR,
         index_js_1.SHIELD_REFRESH_HASHER,
         index_js_1.SHIELD_CLOCK,
-        config_module_js_1.APP_CONFIG,
+        index_js_1.SHIELD_SESSION_LIFETIMES,
     ],
 };
 /**
@@ -388,18 +505,28 @@ const sessionAuthorityProvider = {
  * 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.
  */
+/**
+ * The LOGIN `totp` verifier ({@link SHIELD_LOGIN_TOTP_VERIFIER}) — ALWAYS the
+ * OR-across-devices wrapper: it delegates to the resolved base (the consumer
+ * `totpOverride` when supplied, else the framework's single-secret RFC-6238 verifier) per
+ * device secret, so a principal's multiple confirmed devices OR-match, and it claims each
+ * accepted code in Redis (M-B replay guard, fail closed). ONE instance, shared by the
+ * authenticator and the MFA step-up.
+ */
+const loginTotpVerifierProvider = {
+    provide: tokens_js_1.SHIELD_LOGIN_TOTP_VERIFIER,
+    useFactory: async (totpOverride, mfaDeviceStore, redis) => {
+        const { createTotpFactorVerifier } = await loadCore();
+        const base = resolveTotpVerifier(totpOverride, createTotpFactorVerifier({ hmacSha1: exports.hmacSha1 }));
+        return new mariadb_or_totp_verifier_js_1.OrTotpVerifier(base, mfaDeviceStore, redis);
+    },
+    inject: [tokens_js_1.SHIELD_TOTP_VERIFIER_OVERRIDE, tokens_js_1.SHIELD_MFA_DEVICE_STORE, tokens_js_1.SHIELD_REDIS],
+};
 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, totpOverride, rootIds, mfaDeviceStore) => {
-        const { createAuthenticator, createIdentityBroker, createTotpFactorVerifier } = await loadCore();
-        // The login totp verifier is ALWAYS the OR-across-devices wrapper: it delegates
-        // to the resolved base (the consumer `totpOverride` when supplied, else the
-        // framework's single-secret RFC-6238 verifier) per device secret, so a
-        // principal's multiple confirmed devices OR-match. A consumer override still wins
-        // (it's the base inside the OR-wrap); multi-device works by default.
-        const base = resolveTotpVerifier(totpOverride, createTotpFactorVerifier({ hmacSha1: exports.hmacSha1 }));
-        const totp = new mariadb_or_totp_verifier_js_1.OrTotpVerifier(base, mfaDeviceStore);
+    useFactory: async (hasher, resolver, totp, rootIds) => {
+        const { createAuthenticator, createIdentityBroker } = await loadCore();
         return createAuthenticator({
             hasher,
             resolver,
@@ -414,11 +541,25 @@ const authenticatorProvider = {
     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_LOGIN_TOTP_VERIFIER,
         tokens_js_1.SHIELD_ROOT_IDS,
-        tokens_js_1.SHIELD_MFA_DEVICE_STORE,
     ],
 };
+/**
+ * The MFA step-up (M6) behind `/auth/mfa`'s TOTP branch: verifies ONLY the second factor
+ * for the principal the password step recorded, through the SAME resolver, the SAME login
+ * TOTP verifier (replay guard included) and an identity broker with the SAME root
+ * allowlist as {@link authenticatorProvider} — so the minted principal is identical to the
+ * one a single-step login would produce. No password is held between the two requests.
+ */
+const mfaStepUpProvider = {
+    provide: tokens_js_1.SHIELD_MFA_STEP_UP,
+    useFactory: async (resolver, totp, rootIds) => {
+        const { createIdentityBroker } = await loadCore();
+        return new mfa_step_up_js_1.CredentialMfaStepUp(resolver, [totp], createIdentityBroker({ internalRootIds: rootIds ?? [] }));
+    },
+    inject: [tokens_js_1.SHIELD_CREDENTIAL_RESOLVER, tokens_js_1.SHIELD_LOGIN_TOTP_VERIFIER, 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,
@@ -503,10 +644,48 @@ function makeResetTokenStoreProvider(override) {
             inject: [tokens_js_1.SHIELD_DB_POOL],
         };
 }
+/**
+ * Bind the {@link EmailSender} (security hardening #6):
+ *  - a supplied sender → used verbatim (any environment);
+ *  - `'disabled'` → {@link NoopEmailSender} + one startup warning (forgot-password stays 204;
+ *    nothing is delivered or printed);
+ *  - omitted → the dev {@link LogEmailSender} ONLY when the RAW `NODE_ENV` is explicitly
+ *    `development` or `test` (+ one startup warning, since it prints live reset links);
+ *    anything else, INCLUDING an unset `NODE_ENV`, THROWS at composition (boot fails closed).
+ * `NODE_ENV` is read when the factory runs (module compile), not at `forRoot()` time.
+ */
 function makeEmailSenderProvider(override) {
-    return override
-        ? { provide: tokens_js_1.SHIELD_EMAIL_SENDER, useValue: override }
-        : { provide: tokens_js_1.SHIELD_EMAIL_SENDER, useFactory: () => new log_email_sender_js_1.LogEmailSender() };
+    if (override === 'disabled') {
+        return {
+            provide: tokens_js_1.SHIELD_EMAIL_SENDER,
+            useFactory: () => {
+                authBootLogger.warn("emailSender: 'disabled' — password-reset emails are NOT delivered " +
+                    '(forgot-password still answers 204). Supply a real EmailSender to enable resets.');
+                return new noop_email_sender_js_1.NoopEmailSender();
+            },
+        };
+    }
+    if (override)
+        return { provide: tokens_js_1.SHIELD_EMAIL_SENDER, useValue: override };
+    return {
+        provide: tokens_js_1.SHIELD_EMAIL_SENDER,
+        useFactory: () => resolveDefaultEmailSender(process.env.NODE_ENV),
+    };
+}
+/**
+ * The no-override default sender decision (pure apart from the warning). Exported for
+ * the unit test only — not part of the package's public surface.
+ */
+function resolveDefaultEmailSender(rawNodeEnv) {
+    if (!(0, app_config_js_1.isDevOrTestNodeEnv)(rawNodeEnv)) {
+        throw new Error("Astram auth composition: auth:true requires `emailSender` (or `emailSender: 'disabled'`) " +
+            `when NODE_ENV is not 'development' or 'test' (got: ${rawNodeEnv === undefined ? 'unset' : `'${rawNodeEnv}'`}). ` +
+            'The dev LogEmailSender prints live password-reset links to stdout, so it is only ' +
+            'used when NODE_ENV is explicitly development/test.');
+    }
+    authBootLogger.warn(`Using the dev LogEmailSender (NODE_ENV=${rawNodeEnv}): password-reset emails are printed ` +
+        'to stdout, reset links included. Never run like this in production — supply an emailSender.');
+    return new log_email_sender_js_1.LogEmailSender();
 }
 function makeRecoveryCodeStoreProvider(override) {
     return override
@@ -667,25 +846,47 @@ let AuthModule = AuthModule_1 = class AuthModule {
                 // The reset-link base URL value the forgot-password handler composes into the
                 // emailed link (framework-owned URL composition; EmailSender stays dumb).
                 resetLinkBaseUrlProvider,
+                // The resolved session lifetimes (#8) — one source for authority, binder, controller.
+                sessionLifetimesProvider,
                 sessionRecordStoreProvider,
+                // ADR-0035: the Redis permission-version cache (gate 5 + the identity bumper).
+                permissionVersionCacheProvider,
+                // Phase 3B review P1: the durable re-enroll marker + account status for the rebuild.
+                sessionRestrictionStoreProvider,
                 hotSessionStoreProvider,
                 tokenGeneratorProvider,
                 refreshHasherProvider,
                 clockProvider,
                 sessionAuthorityProvider,
+                // The login TOTP verifier (OR across devices + Redis replay guard, M-B), shared by
+                // the authenticator and the MFA step-up.
+                loginTotpVerifierProvider,
                 authenticatorProvider,
-                // The core TOTP verifier (login MFA + account MFA enroll/disable share it).
+                // The MFA step-up (M6): `/auth/mfa` verifies only the second factor.
+                mfaStepUpProvider,
+                // The single-secret TOTP verifier for account MFA enroll/disable.
                 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 server-side, single-use, TTL'd challenge store backing the login→mfa
+                // handoff — Redis-backed, never holds the password (M6).
+                pendingMfaStoreProvider,
                 // The request-auth token binder (access-token → principal claims).
                 sessionTokenBinderProvider,
+                // The service-account API-key authenticator (ADR-0033) — `ask_…` bearer → service_account
+                // Principal. Provided here (with the guard) so the APP_GUARD sees it; exported below.
+                serviceAuthenticatorProvider,
                 // 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,
+                // #5: the per-client-IP login failure limiter (D3: 50 / 15 min, configurable) +
+                // the boot-time `trust proxy` check that enables ALL per-IP limiters (login,
+                // forgot, reset) on an explicit trust proxy, or switches them OFF with a warning
+                // (unset → req.ip would be the shared proxy IP).
+                loginIpLimiterProvider,
+                trust_proxy_check_js_1.TrustProxyBootCheck,
                 recoveryLimiterProvider,
+                // #9: the TOTP-step limiter (5 / 15 min per account, `mfa:pid:<principalId>`).
+                mfaLimiterProvider,
                 // 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-
@@ -701,6 +902,9 @@ let AuthModule = AuthModule_1 = class AuthModule {
                 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,
+                // Exported so the (app-wide) enforcement guard injects it → the `ask_…` machine auth path
+                // (ADR-0033) works out-of-the-box under `auth: true`.
+                tokens_js_2.SHIELD_SERVICE_AUTHENTICATOR,
                 // 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,
@@ -719,6 +923,13 @@ let AuthModule = AuthModule_1 = class AuthModule {
                 tokens_js_1.SHIELD_TOTP_VERIFIER,
                 // The eager session-facts projector (consumed by AuthController).
                 tokens_js_1.SHIELD_SESSION_FACTS_PROJECTOR,
+                // The scope-subtree resolver — exported so the (app-wide) enforcement guard can re-derive
+                // a session's subtree when gate 5 reloads at a newer permission version (Phase 1C).
+                tokens_js_1.SHIELD_SCOPE_SUBTREE_RESOLVER,
+                // ADR-0035: the Redis permission-version cache — the framework-built decision authority
+                // reads it (gate 5) and `@astram/identity`'s bumper publishes to it after commit.
+                tokens_js_1.SHIELD_PERMISSION_VERSION_CACHE,
+                tokens_js_1.SHIELD_SESSION_RESTRICTIONS,
             ],
         };
     }

package/dist/auth/connections.d.ts

@@ -24,7 +24,7 @@
 import { type OnModuleDestroy } from '@nestjs/common';
 import { type Pool } from 'mariadb';
 import Redis from 'ioredis';
-import type { AppConfig } from '../config/app-config.js';
+import { type AppConfig } from '../config/app-config.js';
 /**
  * Create the ONE live `mariadb` {@link Pool} for the `shield_core` account from
  * {@link AppConfig}. The `connectionLimit` comes from the ADR-0018 budget

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

@@ -1 +1 @@
-{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../../src/auth/connections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAgB,EAAE,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,MAAM,SAAS,CAAC;AAC5B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAcpD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,KAAK,CAI1D;AAED;;;;;;GAMG;AACH,qBACa,mBAAoB,YAAW,eAAe;IAEvD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,KAAK;IAGzB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;CAavC"}
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../../src/auth/connections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAgB,EAAE,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,MAAM,SAAS,CAAC;AAC5B,OAAO,EAAoC,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE3F;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAcpD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,KAAK,CAc1D;AAED;;;;;;GAMG;AACH,qBACa,mBAAoB,YAAW,eAAe;IAEvD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,KAAK;IAGzB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;CAavC"}

package/dist/auth/connections.js

@@ -41,6 +41,7 @@ exports.createRedisClient = createRedisClient;
 const common_1 = require("@nestjs/common");
 const mariadb_1 = __importDefault(require("mariadb"));
 const ioredis_1 = __importDefault(require("ioredis"));
+const app_config_js_1 = require("../config/app-config.js");
 /**
  * Create the ONE live `mariadb` {@link Pool} for the `shield_core` account from
  * {@link AppConfig}. The `connectionLimit` comes from the ADR-0018 budget
@@ -75,9 +76,19 @@ function createDbPool(config) {
  * `unavailable` hot-store outcome (fail-closed), never a silent `absent`.
  */
 function createRedisClient(config) {
-    // `maxRetriesPerRequest: null` keeps a transient blip from turning into a thrown
-    // command (the hot-store adapter classifies unreachable as `unavailable`).
-    return new ioredis_1.default(config.redis.url, { maxRetriesPerRequest: null, lazyConnect: false });
+    // BOUNDED (GAPS #7, security hardening Phase 3). Previously `maxRetriesPerRequest: null`
+    // queued every command while Redis was down, so a classified request HUNG until Redis came
+    // back instead of failing closed (ADR-0013: "if Redis cannot answer, the request is denied").
+    // Now each command fails after `commandTimeout` (default 2 s, `REDIS_COMMAND_TIMEOUT_MS`) or
+    // after one reconnect attempt; every caller treats a Redis error as its fail-closed outcome
+    // (401 / 503), except the rate limiters, which fail OPEN by design (never a lockout blip).
+    // Reconnects keep ioredis's default strategy. Nothing in the framework relies on queued
+    // commands (no pub/sub, no blocking reads, no MULTI/pipeline).
+    return new ioredis_1.default(config.redis.url, {
+        maxRetriesPerRequest: 1,
+        commandTimeout: config.redis.commandTimeoutMs ?? app_config_js_1.DEFAULT_REDIS_COMMAND_TIMEOUT_MS,
+        lazyConnect: false,
+    });
 }
 /**
  * Lifecycle-aware holder that owns the pool + redis handles and closes them on

package/dist/auth/default-session-facts-projector.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The framework-DEFAULT session-facts projector (ADR-0035, GAPS #6). Without a projector, a session
+ * carries no `cachedFacts` and gate 5 re-reads the grants from the DB on every request. When the app
+ * hands ShieldModule its `recordAuthorization` (and no explicit `sessionFactsProjector`), the facts
+ * the decision authority uses are the right ones to cache: this projector delegates to that SAME
+ * `PermissionFactsPort.loadCoarseGrants` (one definition of a principal's grants and live roles).
+ *
+ * DEFERRED: `AuthModule` is composed statically, but `recordAuthorization` may be resolved later
+ * (`forRootAsync`), and the port is only known when the decision authority is built. ShieldModule
+ * creates one instance per registration, hands it to `AuthModule`, and attaches the port when it
+ * builds the authority. Until attached it is INACTIVE: the auth controller then behaves exactly as
+ * with no projector (nothing cached at login, the existing cache carried forward at refresh).
+ *
+ * Free of runtime `@astram/core` imports (type-only).
+ */
+import type { CoarseGrants, PermissionFactsPort } from '@astram/core';
+import type { SessionFactsProjector } from './ports/session-facts-projector.js';
+export declare class DeferredSessionFactsProjector implements SessionFactsProjector {
+    private source;
+    /** Attach the decision authority's facts port (once; a second attach is ignored). */
+    attach(source: Pick<PermissionFactsPort, 'loadCoarseGrants'>): void;
+    /** Whether a port was attached (inactive ⇒ the controller treats it as "no projector"). */
+    isActive(): boolean;
+    project(principalId: string, tenantId: string): Promise<CoarseGrants | null>;
+}
+//# sourceMappingURL=default-session-facts-projector.d.ts.map

package/dist/auth/default-session-facts-projector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-session-facts-projector.d.ts","sourceRoot":"","sources":["../../src/auth/default-session-facts-projector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAEhF,qBAAa,6BAA8B,YAAW,qBAAqB;IACzE,OAAO,CAAC,MAAM,CAA4D;IAE1E,qFAAqF;IACrF,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,kBAAkB,CAAC,GAAG,IAAI;IAInE,2FAA2F;IAC3F,QAAQ,IAAI,OAAO;IAIb,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;CAInF"}

package/dist/auth/default-session-facts-projector.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeferredSessionFactsProjector = void 0;
+class DeferredSessionFactsProjector {
+    source;
+    /** Attach the decision authority's facts port (once; a second attach is ignored). */
+    attach(source) {
+        if (this.source === undefined)
+            this.source = source;
+    }
+    /** Whether a port was attached (inactive ⇒ the controller treats it as "no projector"). */
+    isActive() {
+        return this.source !== undefined;
+    }
+    async project(principalId, tenantId) {
+        if (this.source === undefined)
+            return null;
+        return this.source.loadCoarseGrants(principalId, tenantId);
+    }
+}
+exports.DeferredSessionFactsProjector = DeferredSessionFactsProjector;

package/dist/auth/mfa-step-up.d.ts

@@ -0,0 +1,32 @@
+import type { Credential, CredentialResolver, FactorVerifier, IdentityBroker, Principal, ResolvedCredential } from '@astram/core';
+import type { PendingMfaChallenge } from './pending-mfa-store.js';
+/** The step-up outcome the controller maps to 200 / 401 / 503. */
+export type MfaStepUpResult = {
+    readonly outcome: 'authenticated';
+    readonly principal: Principal;
+} | {
+    readonly outcome: 'rejected';
+} | {
+    readonly outcome: 'unavailable';
+};
+/** The seam the controller injects under `SHIELD_MFA_STEP_UP`. */
+export interface MfaStepUp {
+    verify(challenge: PendingMfaChallenge, credential: Credential): Promise<MfaStepUpResult>;
+}
+/** SHA-256 of the stored credential hash — binds a challenge to the credential state. */
+export declare function credentialFingerprint(resolved: Pick<ResolvedCredential, 'passwordHash'>): string;
+/**
+ * `true` iff `resolved` is still the credential the challenge was issued for: same
+ * principal, same stored credential hash. Shared by the TOTP step-up and the
+ * recovery-code branch.
+ */
+export declare function challengeMatches(resolved: ResolvedCredential, challenge: PendingMfaChallenge): boolean;
+/** The framework-default {@link MfaStepUp} over the injected core ports. */
+export declare class CredentialMfaStepUp implements MfaStepUp {
+    private readonly resolver;
+    private readonly broker;
+    private readonly verifiers;
+    constructor(resolver: Pick<CredentialResolver, 'resolve'>, factorVerifiers: readonly FactorVerifier[], broker: IdentityBroker);
+    verify(challenge: PendingMfaChallenge, credential: Credential): Promise<MfaStepUpResult>;
+}
+//# sourceMappingURL=mfa-step-up.d.ts.map

package/dist/auth/mfa-step-up.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mfa-step-up.d.ts","sourceRoot":"","sources":["../../src/auth/mfa-step-up.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,SAAS,EACT,kBAAkB,EACnB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,kEAAkE;AAClE,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC;AAExC,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,SAAS,EAAE,mBAAmB,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC1F;AAED,yFAAyF;AACzF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,cAAc,CAAC,GAAG,MAAM,CAIhG;AAQD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,kBAAkB,EAC5B,SAAS,EAAE,mBAAmB,GAC7B,OAAO,CAKT;AAKD,4EAA4E;AAC5E,qBAAa,mBAAoB,YAAW,SAAS;IAIjD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAEzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;gBAG5C,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,CAAC,EAC9D,eAAe,EAAE,SAAS,cAAc,EAAE,EACzB,MAAM,EAAE,cAAc;IAUnC,MAAM,CAAC,SAAS,EAAE,mBAAmB,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC;CAqC/F"}