@astram/guard 0.6.0 → 0.8.0

package/dist/module/shield.module.d.ts

@@ -105,7 +105,13 @@ export interface ShieldModuleOptions {
      */
     readonly credentialWriter?: CredentialWriter;
     readonly resetTokenStore?: ResetTokenStore;
-    readonly emailSender?: EmailSender;
+    /**
+     * Password-reset email delivery — see {@link AuthModuleOptions.emailSender}. A real
+     * sender, or `'disabled'` (no-op, forgot-password still 204). REQUIRED under
+     * `auth: true` unless the raw `NODE_ENV` is `development`/`test` (where the dev
+     * `LogEmailSender` is the default); otherwise boot fails (security hardening #6).
+     */
+    readonly emailSender?: EmailSender | 'disabled';
     readonly recoveryCodeStore?: RecoveryCodeStore;
     readonly profileWriter?: ProfileWriter;
     readonly sessionSweeper?: SessionSweeper;
@@ -221,7 +227,8 @@ export interface ShieldModuleAsyncOptions {
      */
     readonly credentialWriter?: CredentialWriter;
     readonly resetTokenStore?: ResetTokenStore;
-    readonly emailSender?: EmailSender;
+    /** See {@link ShieldModuleOptions.emailSender} (a sender, or `'disabled'`). */
+    readonly emailSender?: EmailSender | 'disabled';
     readonly recoveryCodeStore?: RecoveryCodeStore;
     readonly profileWriter?: ProfileWriter;
     readonly sessionSweeper?: SessionSweeper;

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

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

package/dist/module/shield.module.js

@@ -55,6 +55,9 @@ const app_config_js_1 = require("../config/app-config.js");
 // the enforcement-only path never INSTANTIATES it (no live pool/Redis, no HMAC
 // gate, no core load).
 const auth_module_js_1 = require("../auth/auth.module.js");
+// Core-free (type-only core imports): the deferred default projector + the version-cache token.
+const default_session_facts_projector_js_1 = require("../auth/default-session-facts-projector.js");
+const tokens_js_1 = require("../auth/tokens.js");
 // The `SHIELD_DECISION_AUTHORITY` token now lives in `./shield-tokens.js` so the
 // enforcement guard can import it without a cycle (guard → token → ShieldModule →
 // EnforcementModule → guard). Re-exported here to keep the public import path stable.
@@ -87,7 +90,8 @@ let cachedRecordAuthApi;
 async function loadBuildRecordAuthorization() {
     if (cachedRecordAuthApi === undefined) {
         try {
-            cachedRecordAuthApi = (await Promise.resolve().then(() => __importStar(require('../authz/wire-record-authorization.js'))));
+            cachedRecordAuthApi =
+                (await Promise.resolve().then(() => __importStar(require('../authz/wire-record-authorization.js'))));
         }
         catch {
             // Built-dist fallback (the CJS dist path — see evalImport). `__dirname` is defined
@@ -97,7 +101,7 @@ async function loadBuildRecordAuthorization() {
             cachedRecordAuthApi = (await evalImport(base));
         }
     }
-    return cachedRecordAuthApi.buildRecordAuthorization;
+    return cachedRecordAuthApi;
 }
 /**
  * Resolve the `SHIELD_DECISION_AUTHORITY` VALUE from the caller's options (the ONE seam,
@@ -113,18 +117,33 @@ async function loadBuildRecordAuthorization() {
  *
  * Async because the `recordAuthorization` path lazy-loads the (core-touching) builder.
  */
-async function resolveDecisionAuthority(options) {
+async function resolveDecisionAuthority(options, extras = {}) {
     if (options.recordAuthorization && options.decisionAuthority) {
         throw new Error('ShieldModule: `recordAuthorization` and `decisionAuthority` are mutually exclusive — ' +
             'supply the record-authorization inputs (pool + app ports + registry) so the framework ' +
             'builds the decision authority, OR a pre-built `decisionAuthority`, but not both.');
     }
     if (options.recordAuthorization) {
-        const build = await loadBuildRecordAuthorization();
-        return build(options.recordAuthorization);
+        const api = await loadBuildRecordAuthorization();
+        const versionCache = extras.versionCache ?? undefined;
+        // ADR-0035 default projector: cache the SAME facts the authority decides on (version-cache
+        // wrapped, so a login projection also warms the Redis version).
+        extras.defaultProjector?.attach(versionCache !== undefined
+            ? api.withRedisPermissionVersion(options.recordAuthorization.permissionFacts, versionCache)
+            : options.recordAuthorization.permissionFacts);
+        return api.buildRecordAuthorization(options.recordAuthorization, versionCache !== undefined ? { versionCache } : {});
     }
     return options.decisionAuthority ?? core_seam_js_1.stubDecisionAuthority;
 }
+/**
+ * The deferred default projector for a registration (ADR-0035): only when auth is on and the
+ * consumer did not supply its own projector. `undefined` otherwise.
+ */
+function defaultProjectorFor(auth, explicit) {
+    return auth && explicit === undefined ? new default_session_facts_projector_js_1.DeferredSessionFactsProjector() : undefined;
+}
+/** Inject the Redis version cache when AuthModule provides it (`auth: true`); absent otherwise. */
+const OPTIONAL_VERSION_CACHE = { token: tokens_js_1.SHIELD_PERMISSION_VERSION_CACHE, optional: true };
 /**
  * `ShieldModule` — the SINGLE registration seam (ADR-0023 §4).
  *
@@ -153,6 +172,10 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
     /** Register Shield with static options (the common path). */
     static forRoot(options = {}) {
         const config = options.config ?? (0, app_config_js_1.loadAppConfig)();
+        // ADR-0035: with auth on and no explicit projector, sessions cache the facts the framework-built
+        // authority decides on (attached when the authority is built; inactive until then).
+        const defaultProjector = defaultProjectorFor(options.auth, options.sessionFactsProjector);
+        const sessionFactsProjector = options.sessionFactsProjector ?? defaultProjector;
         // Build the opt-in AuthModule ONCE so the SAME DynamicModule instance is both
         // imported (composes) and re-exported (propagates its exported engine tokens
         // app-wide through the @Global ShieldModule). Re-exporting the two Symbols
@@ -172,9 +195,7 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
                 ...(options.credentialResolver
                     ? { credentialResolver: options.credentialResolver }
                     : {}),
-                ...(options.profileResolver
-                    ? { profileResolver: options.profileResolver }
-                    : {}),
+                ...(options.profileResolver ? { profileResolver: options.profileResolver } : {}),
                 // The account/credential-surface seams — same spread-when-present rule
                 // (an explicit `undefined` is not assignable under
                 // exactOptionalPropertyTypes; absent → AuthModule binds `null` → 501).
@@ -194,15 +215,11 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
                 ...(options.identityControlPlaneKeys
                     ? { identityControlPlaneKeys: options.identityControlPlaneKeys }
                     : {}),
-                ...(options.sessionFactsProjector
-                    ? { sessionFactsProjector: options.sessionFactsProjector }
-                    : {}),
+                ...(sessionFactsProjector ? { sessionFactsProjector } : {}),
                 ...(options.scopeSubtreeResolver
                     ? { scopeSubtreeResolver: options.scopeSubtreeResolver }
                     : {}),
-                ...(options.membershipChecker
-                    ? { membershipChecker: options.membershipChecker }
-                    : {}),
+                ...(options.membershipChecker ? { membershipChecker: options.membershipChecker } : {}),
             })
             : undefined;
         return {
@@ -221,24 +238,22 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
                     // stub paths resolve synchronously but flow through the same one seam. Both
                     // supplied → throws (mutual exclusion).
                     provide: shield_tokens_js_1.SHIELD_DECISION_AUTHORITY,
-                    useFactory: () => resolveDecisionAuthority({
+                    useFactory: (versionCache) => resolveDecisionAuthority({
                         ...(options.recordAuthorization
                             ? { recordAuthorization: options.recordAuthorization }
                             : {}),
                         ...(options.decisionAuthority
                             ? { decisionAuthority: options.decisionAuthority }
                             : {}),
-                    }),
+                    }, { versionCache, defaultProjector }),
+                    // ADR-0035: the Redis version cache AuthModule provides under `auth: true`.
+                    inject: [OPTIONAL_VERSION_CACHE],
                 },
             ],
             // Re-export the composed AuthModule app-wide ONLY when auth is opted in — its
             // own `exports` (SHIELD_AUTHENTICATOR / SHIELD_SESSION_AUTHORITY) then become
             // visible to a consumer's controllers/services via the @Global seam.
-            exports: [
-                config_module_js_1.APP_CONFIG,
-                shield_tokens_js_1.SHIELD_DECISION_AUTHORITY,
-                ...(authModule ? [authModule] : []),
-            ],
+            exports: [config_module_js_1.APP_CONFIG, shield_tokens_js_1.SHIELD_DECISION_AUTHORITY, ...(authModule ? [authModule] : [])],
         };
     }
     /**
@@ -263,6 +278,10 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
             useFactory: (opts) => opts.config ?? (0, app_config_js_1.loadAppConfig)(),
             inject: [optionsToken],
         };
+        // ADR-0035: the deferred default projector (auth on, no explicit projector), attached when the
+        // async-resolved options yield `recordAuthorization`.
+        const defaultProjector = defaultProjectorFor(options.auth, options.sessionFactsProjector);
+        const sessionFactsProjector = options.sessionFactsProjector ?? defaultProjector;
         const authorityProvider = {
             provide: shield_tokens_js_1.SHIELD_DECISION_AUTHORITY,
             // Same one-seam resolution as forRoot, over the async-resolved options: the
@@ -270,11 +289,11 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
             // in its useFactory from the injected registrations) has the framework build the
             // real wired authority; `decisionAuthority` is the legacy passthrough; both →
             // throws; neither → stub. Async because the record path lazy-loads the builder.
-            useFactory: (opts) => resolveDecisionAuthority({
+            useFactory: (opts, versionCache) => resolveDecisionAuthority({
                 ...(opts.recordAuthorization ? { recordAuthorization: opts.recordAuthorization } : {}),
                 ...(opts.decisionAuthority ? { decisionAuthority: opts.decisionAuthority } : {}),
-            }),
-            inject: [optionsToken],
+            }, { versionCache, defaultProjector }),
+            inject: [optionsToken, OPTIONAL_VERSION_CACHE],
         };
         // Same one-instance opt-in AuthModule as forRoot (imported + re-exported).
         // `credentialResolver` is STATIC on the async options (like `auth`) — a
@@ -289,9 +308,7 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
                 ...(options.credentialResolver
                     ? { credentialResolver: options.credentialResolver }
                     : {}),
-                ...(options.profileResolver
-                    ? { profileResolver: options.profileResolver }
-                    : {}),
+                ...(options.profileResolver ? { profileResolver: options.profileResolver } : {}),
                 // The account/credential-surface seams — same spread-when-present rule
                 // (an explicit `undefined` is not assignable under
                 // exactOptionalPropertyTypes; absent → AuthModule binds `null` → 501).
@@ -311,15 +328,11 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
                 ...(options.identityControlPlaneKeys
                     ? { identityControlPlaneKeys: options.identityControlPlaneKeys }
                     : {}),
-                ...(options.sessionFactsProjector
-                    ? { sessionFactsProjector: options.sessionFactsProjector }
-                    : {}),
+                ...(sessionFactsProjector ? { sessionFactsProjector } : {}),
                 ...(options.scopeSubtreeResolver
                     ? { scopeSubtreeResolver: options.scopeSubtreeResolver }
                     : {}),
-                ...(options.membershipChecker
-                    ? { membershipChecker: options.membershipChecker }
-                    : {}),
+                ...(options.membershipChecker ? { membershipChecker: options.membershipChecker } : {}),
             })
             : undefined;
         return {
@@ -335,11 +348,7 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
                 ...(options.imports ?? []),
             ],
             providers: [asyncOptionsProvider, configProvider, authorityProvider],
-            exports: [
-                config_module_js_1.APP_CONFIG,
-                shield_tokens_js_1.SHIELD_DECISION_AUTHORITY,
-                ...(authModule ? [authModule] : []),
-            ],
+            exports: [config_module_js_1.APP_CONFIG, shield_tokens_js_1.SHIELD_DECISION_AUTHORITY, ...(authModule ? [authModule] : [])],
         };
     }
 };

package/dist/request-auth/request-principal.d.ts

@@ -12,7 +12,7 @@
  * captured from the login-time Principal, so a genuinely-root login stays
  * root; a normal login can never become one on a later request).
  */
-import type { Principal } from '@astram/core';
+import type { Principal, ServiceAuthenticator } from '@astram/core';
 import type { SessionTokenBinder, BoundPrincipalClaims } from './session-token-binder.js';
 /** Extract a bearer token from an `Authorization: Bearer <token>` header. */
 export declare function extractBearerToken(authorizationHeader: unknown): string | null;
@@ -22,11 +22,19 @@ export declare function extractBearerToken(authorizationHeader: unknown): string
  * a root on the request path.
  */
 export declare function principalFromClaims(claims: BoundPrincipalClaims): Principal | null;
+/**
+ * Is this bearer token a service-account API key (`ask_…`, ADR-0033) rather than a session
+ * access token? A cheap prefix check; the authenticator does the real (constant-time) verify.
+ */
+export declare function isApiKey(token: string): boolean;
 /**
  * Resolve an HTTP request's bearer token to a `Principal`, or `null` (fail-closed)
  * when there is no token, no binding, or the binding is malformed.
+ *
+ * When `serviceAuth` is provided and the bearer token is an API key (`ask_…`, ADR-0033), the token
+ * is authenticated as a service account instead of resolved against the session binder.
  */
-export declare function resolveRequestPrincipal(authorizationHeader: unknown, binder: SessionTokenBinder): Promise<Principal | null>;
+export declare function resolveRequestPrincipal(authorizationHeader: unknown, binder: SessionTokenBinder, serviceAuth?: ServiceAuthenticator): Promise<Principal | null>;
 /**
  * Resolve an HTTP request's bearer token to BOTH a `Principal` AND the raw
  * {@link BoundPrincipalClaims}, or `null` (fail-closed) — the same read path as
@@ -35,7 +43,7 @@ export declare function resolveRequestPrincipal(authorizationHeader: unknown, bi
  * uses this so it can read `claims.mustReenroll` to apply the enforced-re-enroll gate
  * while still attaching the resolved `Principal` for `decide()`.
  */
-export declare function resolveRequestAuth(authorizationHeader: unknown, binder: SessionTokenBinder): Promise<{
+export declare function resolveRequestAuth(authorizationHeader: unknown, binder: SessionTokenBinder, serviceAuth?: ServiceAuthenticator): Promise<{
     principal: Principal;
     claims: BoundPrincipalClaims;
 } | null>;

package/dist/request-auth/request-principal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-principal.d.ts","sourceRoot":"","sources":["../../src/request-auth/request-principal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAK1F,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,mBAAmB,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAK9E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CAiClF;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,mBAAmB,EAAE,OAAO,EAC5B,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAM3B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,mBAAmB,EAAE,OAAO,EAC5B,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GAAG,IAAI,CAAC,CAQxE"}
+{"version":3,"file":"request-principal.d.ts","sourceRoot":"","sources":["../../src/request-auth/request-principal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAa1F,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,mBAAmB,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAK9E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CAiClF;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/C;AA4BD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,mBAAmB,EAAE,OAAO,EAC5B,MAAM,EAAE,kBAAkB,EAC1B,WAAW,CAAC,EAAE,oBAAoB,GACjC,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAU3B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,mBAAmB,EAAE,OAAO,EAC5B,MAAM,EAAE,kBAAkB,EAC1B,WAAW,CAAC,EAAE,oBAAoB,GACjC,OAAO,CAAC;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GAAG,IAAI,CAAC,CAgBxE"}

package/dist/request-auth/request-principal.js

@@ -16,10 +16,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractBearerToken = extractBearerToken;
 exports.principalFromClaims = principalFromClaims;
+exports.isApiKey = isApiKey;
 exports.resolveRequestPrincipal = resolveRequestPrincipal;
 exports.resolveRequestAuth = resolveRequestAuth;
 /** Valid `Principal.kind` values (mirror of the Core union; validated at rebuild). */
 const PRINCIPAL_KINDS = new Set(['user', 'role_group', 'service_account']);
+/**
+ * The service-account API-key prefix (mirror of Core's `API_KEY_PREFIX = 'ask_'`, ADR-0033) —
+ * inlined as a literal so this file keeps its ZERO-runtime-`require('@astram/core')` discipline
+ * (importing the value would add a runtime dep; the type-only imports above are erased). Kept in
+ * sync with Core by the ADR + a guard test that asserts equality with the Core export.
+ */
+const API_KEY_PREFIX = 'ask_';
 /** Extract a bearer token from an `Authorization: Bearer <token>` header. */
 function extractBearerToken(authorizationHeader) {
     if (typeof authorizationHeader !== 'string')
@@ -64,14 +72,53 @@ function principalFromClaims(claims) {
         isRoot: claims.isRoot === true,
     });
 }
+/**
+ * Is this bearer token a service-account API key (`ask_…`, ADR-0033) rather than a session
+ * access token? A cheap prefix check; the authenticator does the real (constant-time) verify.
+ */
+function isApiKey(token) {
+    return token.startsWith(API_KEY_PREFIX);
+}
+/**
+ * Synthesize {@link BoundPrincipalClaims} for a machine (service-account) request from its resolved
+ * {@link Principal} (ADR-0033). A service account has NO interactive-session state — so the
+ * session-only gates are set to their benign defaults:
+ *  - `mustReenroll: false` — re-enroll is a human recovery-code concern; a machine never re-enrolls.
+ *  - `sessionId: ''` — there is no durable session row (the key IS the credential); the field is
+ *    present only to satisfy the claims shape (no logout/liveness correlation applies to a key —
+ *    revocation is via the key's `revokedAtMs`, enforced at authenticate time).
+ *  - no `cachedFacts` (absent) — gate 5 DB-reloads the account's grants (fail-closed default; a
+ *    machine has no login-time projection).
+ * The Principal's `scopeSubtreeNodeIds` is carried through so the tenant/scope gate reads the
+ * account's own subtree (least privilege).
+ */
+function claimsFromServicePrincipal(principal) {
+    return {
+        id: principal.id,
+        tenantId: principal.tenantId,
+        roleIds: [...principal.roleIds],
+        kind: principal.kind,
+        isRoot: false, // a service account is NEVER root (ADR-0033) — defense-in-depth on the claims too.
+        sessionId: '',
+        mustReenroll: false,
+        scopeSubtreeNodeIds: [...principal.scopeSubtreeNodeIds],
+    };
+}
 /**
  * Resolve an HTTP request's bearer token to a `Principal`, or `null` (fail-closed)
  * when there is no token, no binding, or the binding is malformed.
+ *
+ * When `serviceAuth` is provided and the bearer token is an API key (`ask_…`, ADR-0033), the token
+ * is authenticated as a service account instead of resolved against the session binder.
  */
-async function resolveRequestPrincipal(authorizationHeader, binder) {
+async function resolveRequestPrincipal(authorizationHeader, binder, serviceAuth) {
     const token = extractBearerToken(authorizationHeader);
     if (token === null)
         return null;
+    if (serviceAuth !== undefined && isApiKey(token)) {
+        const res = await serviceAuth.authenticateApiKey(token);
+        return res.ok ? res.principal : null; // fail-closed uniform on any bad key.
+    }
     const claims = await binder.resolve(token);
     if (claims === null)
         return null;
@@ -85,10 +132,19 @@ async function resolveRequestPrincipal(authorizationHeader, binder) {
  * uses this so it can read `claims.mustReenroll` to apply the enforced-re-enroll gate
  * while still attaching the resolved `Principal` for `decide()`.
  */
-async function resolveRequestAuth(authorizationHeader, binder) {
+async function resolveRequestAuth(authorizationHeader, binder, serviceAuth) {
     const token = extractBearerToken(authorizationHeader);
     if (token === null)
         return null;
+    // Machine path (ADR-0033): an `ask_…` bearer is a service-account API key. Authenticate it and
+    // synthesize the claims (benign session defaults) so ALL downstream enforcement — the re-enroll
+    // gate, the facts hot-path, decide() — is IDENTICAL to a human's (invariant #3, one authority).
+    if (serviceAuth !== undefined && isApiKey(token)) {
+        const res = await serviceAuth.authenticateApiKey(token);
+        if (!res.ok)
+            return null; // uniform fail-closed (malformed/unknown/expired/revoked/outage).
+        return { principal: res.principal, claims: claimsFromServicePrincipal(res.principal) };
+    }
     const claims = await binder.resolve(token);
     if (claims === null)
         return null;

package/dist/request-auth/session-facts-als.d.ts

@@ -35,7 +35,7 @@
  * (`PermissionFactsPort.loadCoarseGrants`). A cache miss NEVER fabricates a permit.
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
-import type { CoarseGrants } from '@astram/core';
+import type { CoarseGrants, PermissionFactsPort } from '@astram/core';
 /**
  * The per-request session-facts store carried through the ALS. `cachedFacts` is the
  * principal's coarse grants for THIS request (or `null` when none were projected →
@@ -47,7 +47,22 @@ export interface SessionFactsStore {
     readonly cachedFacts: CoarseGrants | null;
     /** The version `cachedFacts` was projected at (0 when absent). */
     readonly permissionsVersion: number;
+    /**
+     * OPTIONAL reload signal (security hardening Phase 1C). The framework-built decision authority
+     * calls it when gate 5 RELOADS the coarse grants for a principal inside this request's scope
+     * (cache miss or stale version), passing the authoritative reloaded grants. The enforcement guard
+     * uses it to notice a permission-version move and re-derive the session's scope subtree. A pure
+     * notification: it never changes the decision, and readers ignore it.
+     */
+    readonly onReload?: (principalId: string, tenantId: string, grants: CoarseGrants) => void;
 }
+/**
+ * Wrap an app-owned `PermissionFactsPort`-shaped object so a gate-5 reload inside an enforcement
+ * request notifies that request's {@link SessionFactsStore.onReload}. Behaviour-identical
+ * otherwise: same results, same errors (a throwing reload propagates and notifies nothing).
+ * Outside a guard request (no ALS store, e.g. the engine's in-handler decide calls) it is a no-op.
+ */
+export declare function signalGateFiveReloads(port: PermissionFactsPort): PermissionFactsPort;
 /**
  * The ONE shared session-facts `AsyncLocalStorage` (see the file header). The
  * enforcement guard imports this to `run()` the `decide()` call inside the request's

package/dist/request-auth/session-facts-als.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-facts-als.d.ts","sourceRoot":"","sources":["../../src/request-auth/session-facts-als.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,QAAQ,CAAC,WAAW,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,sCAA6C,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAG7B,CAAC"}
+{"version":3,"file":"session-facts-als.d.ts","sourceRoot":"","sources":["../../src/request-auth/session-facts-als.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIrD,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,QAAQ,CAAC,WAAW,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;CAC3F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,mBAAmB,CAepF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,sCAA6C,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAG7B,CAAC"}

package/dist/request-auth/session-facts-als.js

@@ -37,7 +37,30 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NO_SESSION_FACTS = exports.SHIELD_SESSION_FACTS_ALS = void 0;
+exports.signalGateFiveReloads = signalGateFiveReloads;
 const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * Wrap an app-owned `PermissionFactsPort`-shaped object so a gate-5 reload inside an enforcement
+ * request notifies that request's {@link SessionFactsStore.onReload}. Behaviour-identical
+ * otherwise: same results, same errors (a throwing reload propagates and notifies nothing).
+ * Outside a guard request (no ALS store, e.g. the engine's in-handler decide calls) it is a no-op.
+ */
+function signalGateFiveReloads(port) {
+    return {
+        currentPermissionsVersion: (principalId, tenantId) => port.currentPermissionsVersion(principalId, tenantId),
+        loadCoarseGrants: async (principalId, tenantId) => {
+            const grants = await port.loadCoarseGrants(principalId, tenantId);
+            const store = exports.SHIELD_SESSION_FACTS_ALS.getStore();
+            try {
+                store?.onReload?.(principalId, tenantId, grants);
+            }
+            catch {
+                // A notification must never turn a decision into an error.
+            }
+            return grants;
+        },
+    };
+}
 /**
  * The ONE shared session-facts `AsyncLocalStorage` (see the file header). The
  * enforcement guard imports this to `run()` the `decide()` call inside the request's