@astram/guard 0.2.0 → 0.4.0

package/dist/module/shield.module.js

@@ -1,14 +1,48 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var ShieldModule_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ShieldModule = exports.SHIELD_DECISION_AUTHORITY = void 0;
 const common_1 = require("@nestjs/common");
+const node_url_1 = require("node:url");
 const core_seam_js_1 = require("../enforcement/core-seam.js");
 const enforcement_module_js_1 = require("../enforcement/enforcement.module.js");
 const boot_module_js_1 = require("../boot/boot.module.js");
@@ -21,14 +55,76 @@ 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");
+// 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.
+const shield_tokens_js_1 = require("./shield-tokens.js");
+Object.defineProperty(exports, "SHIELD_DECISION_AUTHORITY", { enumerable: true, get: function () { return shield_tokens_js_1.SHIELD_DECISION_AUTHORITY; } });
+/**
+ * A `Function`-wrapped dynamic `import()` that survives the CommonJS **build** — the same
+ * shim as auth.module.ts's `evalImport`. Under `module: commonjs`, `tsc` would rewrite a
+ * literal `import()` into `require(...)`; routing through the `Function` constructor keeps
+ * a genuine native `import()` in the emitted dist so this file's OWN compiled output stays
+ * free of a top-level `require('../authz/wire-record-authorization.js')` (→ core). We pass
+ * the file's absolute URL (resolved off `__dirname` in the CJS dist / `import.meta.url`
+ * would not exist here) so the eval'd import has a base to resolve against.
+ */
+const evalImport = new Function('specifier', 'return import(specifier);');
+let cachedRecordAuthApi;
+/**
+ * Lazily load the framework's record-authorization builder. Invoked ONLY inside the
+ * `SHIELD_DECISION_AUTHORITY` async factory when a consumer supplies
+ * `recordAuthorization` — NEVER at module top-level. The target file value-imports
+ * `@astram/core` + the four adapter classes, so deferring its load keeps a runtime
+ * `require('@astram/core')` OUT of THIS module's (the enforcement-only) load path.
+ *
+ * TWO strategies, mirroring auth.module.ts's `loadCore`, so it works in BOTH runtimes:
+ *  1. A plain dynamic `import()` — native under vitest/SWC (source path).
+ *  2. On failure (the tsc-built CJS dist downlevels #1 to a throwing `require` when the
+ *     transitive `@astram/core` ESM cannot be `require`d in that context), the
+ *     {@link evalImport} `Function`-wrapped native `import()` resolved off `__dirname`.
+ */
+async function loadBuildRecordAuthorization() {
+    if (cachedRecordAuthApi === undefined) {
+        try {
+            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
+            // in the emitted CJS module; resolve the compiled sibling relative to it and import
+            // it as a file:// URL so Node's CJS→ESM interop loads it (and its ESM-only core dep).
+            const base = (0, node_url_1.pathToFileURL)(`${__dirname}/../authz/wire-record-authorization.js`).href;
+            cachedRecordAuthApi = (await evalImport(base));
+        }
+    }
+    return cachedRecordAuthApi.buildRecordAuthorization;
+}
 /**
- * DI token for the Core decision authority (the ADR-0001 single decision
- * authority) that the enforcement guard consults. The consumer supplies the real
- * `@astram/core` authority through {@link ShieldModule.forRoot}; when omitted the
- * framework binds the fail-closed {@link stubDecisionAuthority} (deny-by-default),
- * so a mis-wiring cannot silently open a door.
+ * Resolve the `SHIELD_DECISION_AUTHORITY` VALUE from the caller's options (the ONE seam,
+ * ADR-0023 — only how its value is PRODUCED changes here). Precedence + mutual exclusion:
+ *
+ *  - `recordAuthorization` PRESENT → the framework builds the REAL wired authority itself
+ *    (the four record-tier adapters constructed inside guard, un-overridable). This is the
+ *    Phase-5 path: the app can no longer supply or weaken those adapters.
+ *  - `decisionAuthority` PRESENT (legacy passthrough) → bind the caller's pre-built
+ *    authority verbatim (kept for other consumers / back-compat).
+ *  - BOTH present → MISCONFIG: throw a clear error (they are mutually exclusive).
+ *  - NEITHER → the fail-closed {@link stubDecisionAuthority} (unchanged fallback).
+ *
+ * Async because the `recordAuthorization` path lazy-loads the (core-touching) builder.
  */
-exports.SHIELD_DECISION_AUTHORITY = Symbol('SHIELD_DECISION_AUTHORITY');
+async function resolveDecisionAuthority(options) {
+    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);
+    }
+    return options.decisionAuthority ?? core_seam_js_1.stubDecisionAuthority;
+}
 /**
  * `ShieldModule` — the SINGLE registration seam (ADR-0023 §4).
  *
@@ -68,13 +164,34 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
         // irrelevant (no AuthModule composes) — a documented no-op.
         const authModule = options.auth
             ? auth_module_js_1.AuthModule.forRoot(
-            // Only pass the property when the consumer supplied one — under
+            // Only pass a property when the consumer supplied one — under
             // `exactOptionalPropertyTypes`, an explicit `undefined` is not assignable
-            // to the optional `credentialResolver`; a spread keeps it truly absent so
-            // AuthModule falls back to the default MariaDb binding.
-            options.credentialResolver
-                ? { credentialResolver: options.credentialResolver }
-                : {})
+            // to an optional field; a spread keeps it truly absent so AuthModule falls
+            // back to its defaults (MariaDb credential store; 501 /auth/me).
+            {
+                ...(options.credentialResolver
+                    ? { credentialResolver: options.credentialResolver }
+                    : {}),
+                ...(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).
+                ...(options.credentialWriter ? { credentialWriter: options.credentialWriter } : {}),
+                ...(options.resetTokenStore ? { resetTokenStore: options.resetTokenStore } : {}),
+                ...(options.emailSender ? { emailSender: options.emailSender } : {}),
+                ...(options.recoveryCodeStore ? { recoveryCodeStore: options.recoveryCodeStore } : {}),
+                ...(options.profileWriter ? { profileWriter: options.profileWriter } : {}),
+                ...(options.sessionSweeper ? { sessionSweeper: options.sessionSweeper } : {}),
+                ...(options.auditSink ? { auditSink: options.auditSink } : {}),
+                ...(options.mfaDeviceStore ? { mfaDeviceStore: options.mfaDeviceStore } : {}),
+                ...(options.totpVerifier ? { totpVerifier: options.totpVerifier } : {}),
+                ...(options.rootIds ? { rootIds: options.rootIds } : {}),
+                ...(options.sessionFactsProjector
+                    ? { sessionFactsProjector: options.sessionFactsProjector }
+                    : {}),
+            })
             : undefined;
         return {
             module: ShieldModule_1,
@@ -87,8 +204,19 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
             providers: [
                 { provide: config_module_js_1.APP_CONFIG, useValue: config },
                 {
-                    provide: exports.SHIELD_DECISION_AUTHORITY,
-                    useValue: options.decisionAuthority ?? core_seam_js_1.stubDecisionAuthority,
+                    // Async factory: the `recordAuthorization` path lazy-loads the (core-touching)
+                    // builder — see resolveDecisionAuthority. The legacy `decisionAuthority` +
+                    // 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({
+                        ...(options.recordAuthorization
+                            ? { recordAuthorization: options.recordAuthorization }
+                            : {}),
+                        ...(options.decisionAuthority
+                            ? { decisionAuthority: options.decisionAuthority }
+                            : {}),
+                    }),
                 },
             ],
             // Re-export the composed AuthModule app-wide ONLY when auth is opted in — its
@@ -96,7 +224,7 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
             // visible to a consumer's controllers/services via the @Global seam.
             exports: [
                 config_module_js_1.APP_CONFIG,
-                exports.SHIELD_DECISION_AUTHORITY,
+                shield_tokens_js_1.SHIELD_DECISION_AUTHORITY,
                 ...(authModule ? [authModule] : []),
             ],
         };
@@ -124,8 +252,16 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
             inject: [optionsToken],
         };
         const authorityProvider = {
-            provide: exports.SHIELD_DECISION_AUTHORITY,
-            useFactory: (opts) => opts.decisionAuthority ?? core_seam_js_1.stubDecisionAuthority,
+            provide: shield_tokens_js_1.SHIELD_DECISION_AUTHORITY,
+            // Same one-seam resolution as forRoot, over the async-resolved options: the
+            // `recordAuthorization` path (the app hands pool + app ports + registry — computed
+            // 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({
+                ...(opts.recordAuthorization ? { recordAuthorization: opts.recordAuthorization } : {}),
+                ...(opts.decisionAuthority ? { decisionAuthority: opts.decisionAuthority } : {}),
+            }),
             inject: [optionsToken],
         };
         // Same one-instance opt-in AuthModule as forRoot (imported + re-exported).
@@ -133,13 +269,34 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
         // registration-time collaborator, threaded straight through here.
         const authModule = options.auth
             ? auth_module_js_1.AuthModule.forRoot(
-            // Only pass the property when the consumer supplied one — under
+            // Only pass a property when the consumer supplied one — under
             // `exactOptionalPropertyTypes`, an explicit `undefined` is not assignable
-            // to the optional `credentialResolver`; a spread keeps it truly absent so
-            // AuthModule falls back to the default MariaDb binding.
-            options.credentialResolver
-                ? { credentialResolver: options.credentialResolver }
-                : {})
+            // to an optional field; a spread keeps it truly absent so AuthModule falls
+            // back to its defaults (MariaDb credential store; 501 /auth/me).
+            {
+                ...(options.credentialResolver
+                    ? { credentialResolver: options.credentialResolver }
+                    : {}),
+                ...(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).
+                ...(options.credentialWriter ? { credentialWriter: options.credentialWriter } : {}),
+                ...(options.resetTokenStore ? { resetTokenStore: options.resetTokenStore } : {}),
+                ...(options.emailSender ? { emailSender: options.emailSender } : {}),
+                ...(options.recoveryCodeStore ? { recoveryCodeStore: options.recoveryCodeStore } : {}),
+                ...(options.profileWriter ? { profileWriter: options.profileWriter } : {}),
+                ...(options.sessionSweeper ? { sessionSweeper: options.sessionSweeper } : {}),
+                ...(options.auditSink ? { auditSink: options.auditSink } : {}),
+                ...(options.mfaDeviceStore ? { mfaDeviceStore: options.mfaDeviceStore } : {}),
+                ...(options.totpVerifier ? { totpVerifier: options.totpVerifier } : {}),
+                ...(options.rootIds ? { rootIds: options.rootIds } : {}),
+                ...(options.sessionFactsProjector
+                    ? { sessionFactsProjector: options.sessionFactsProjector }
+                    : {}),
+            })
             : undefined;
         return {
             module: ShieldModule_1,
@@ -156,7 +313,7 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
             providers: [asyncOptionsProvider, configProvider, authorityProvider],
             exports: [
                 config_module_js_1.APP_CONFIG,
-                exports.SHIELD_DECISION_AUTHORITY,
+                shield_tokens_js_1.SHIELD_DECISION_AUTHORITY,
                 ...(authModule ? [authModule] : []),
             ],
         };

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

@@ -0,0 +1,42 @@
+/**
+ * Request-principal resolution — extract the bearer access token from an HTTP
+ * request and resolve it (via the {@link SessionTokenBinder}) to a `Principal`,
+ * fail-closed. This is the request-auth read path the enforcement guard uses for
+ * `@Classified` routes before calling `decide()`.
+ *
+ * The `Principal` is rebuilt from the bound claims. We deliberately do NOT re-run
+ * the Core identity broker here (which would apply the root allowlist and could
+ * mint a root from an id) — instead we reconstruct a plain, non-root
+ * Principal from the exact claims captured at login. `isRoot` is set to
+ * `false` on the request path unless the binding explicitly recorded it (it is
+ * 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 { 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;
+/**
+ * Rebuild a `Principal` from bound claims (validated). `isRoot` is read
+ * from the binding (captured at login), NEVER inferred — a normal user cannot become
+ * a root on the request path.
+ */
+export declare function principalFromClaims(claims: BoundPrincipalClaims): Principal | null;
+/**
+ * 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.
+ */
+export declare function resolveRequestPrincipal(authorizationHeader: unknown, binder: SessionTokenBinder): 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
+ * {@link resolveRequestPrincipal}, but it also surfaces the claims the `Principal`
+ * projection drops (notably `mustReenroll` and `sessionId`). The enforcement guard
+ * 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<{
+    principal: Principal;
+    claims: BoundPrincipalClaims;
+} | null>;
+//# sourceMappingURL=request-principal.d.ts.map

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

@@ -0,0 +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,CAoBlF;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"}

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

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Request-principal resolution — extract the bearer access token from an HTTP
+ * request and resolve it (via the {@link SessionTokenBinder}) to a `Principal`,
+ * fail-closed. This is the request-auth read path the enforcement guard uses for
+ * `@Classified` routes before calling `decide()`.
+ *
+ * The `Principal` is rebuilt from the bound claims. We deliberately do NOT re-run
+ * the Core identity broker here (which would apply the root allowlist and could
+ * mint a root from an id) — instead we reconstruct a plain, non-root
+ * Principal from the exact claims captured at login. `isRoot` is set to
+ * `false` on the request path unless the binding explicitly recorded it (it is
+ * captured from the login-time Principal, so a genuinely-root login stays
+ * root; a normal login can never become one on a later request).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractBearerToken = extractBearerToken;
+exports.principalFromClaims = principalFromClaims;
+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']);
+/** Extract a bearer token from an `Authorization: Bearer <token>` header. */
+function extractBearerToken(authorizationHeader) {
+    if (typeof authorizationHeader !== 'string')
+        return null;
+    const m = /^Bearer\s+(.+)$/i.exec(authorizationHeader.trim());
+    const token = m?.[1]?.trim();
+    return token && token.length > 0 ? token : null;
+}
+/**
+ * Rebuild a `Principal` from bound claims (validated). `isRoot` is read
+ * from the binding (captured at login), NEVER inferred — a normal user cannot become
+ * a root on the request path.
+ */
+function principalFromClaims(claims) {
+    if (typeof claims.id !== 'string' ||
+        claims.id.length === 0 ||
+        typeof claims.tenantId !== 'string' ||
+        claims.tenantId.length === 0) {
+        return null;
+    }
+    const kind = PRINCIPAL_KINDS.has(claims.kind) ? claims.kind : 'user';
+    const roleIds = Array.isArray(claims.roleIds)
+        ? claims.roleIds.filter((r) => typeof r === 'string')
+        : [];
+    return Object.freeze({
+        kind,
+        id: claims.id,
+        tenantId: claims.tenantId,
+        roleIds: Object.freeze([...roleIds]),
+        isRoot: claims.isRoot === true,
+    });
+}
+/**
+ * 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.
+ */
+async function resolveRequestPrincipal(authorizationHeader, binder) {
+    const token = extractBearerToken(authorizationHeader);
+    if (token === null)
+        return null;
+    const claims = await binder.resolve(token);
+    if (claims === null)
+        return null;
+    return principalFromClaims(claims);
+}
+/**
+ * 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
+ * {@link resolveRequestPrincipal}, but it also surfaces the claims the `Principal`
+ * projection drops (notably `mustReenroll` and `sessionId`). The enforcement guard
+ * 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) {
+    const token = extractBearerToken(authorizationHeader);
+    if (token === null)
+        return null;
+    const claims = await binder.resolve(token);
+    if (claims === null)
+        return null;
+    const principal = principalFromClaims(claims);
+    if (principal === null)
+        return null;
+    return { principal, claims };
+}

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

@@ -0,0 +1,65 @@
+/**
+ * The per-request **session-facts AsyncLocalStorage** (ADR-0011 hot path) — the
+ * SINGLE shared instance the enforcement guard ENTERS and the consumer's
+ * `SessionFactsReader` READS. This is the seam that lets gate 5 serve a principal's
+ * coarse grants from the request's cached facts instead of a DB reload on every
+ * request, WITHOUT touching the frozen 4-arg `decide()` signature or the core
+ * `SessionFactsReader` dep contract.
+ *
+ * ── WHY A FRAMEWORK-EXPORTED SINGLETON (not DI-injected) ─────────────────────────
+ * The guard (framework) must ENTER the scope; the reader (app-owned — astram3 swaps
+ * `nullSessionFacts` for an ALS-backed one) must READ the SAME scope. An
+ * `AsyncLocalStorage` only shares state across `run()`/`getStore()` calls on the
+ * SAME instance, so both sides MUST hold one identical object. Exporting ONE module
+ * singleton and importing it on both sides is the simplest way to guarantee that —
+ * no DI token round-trip, no risk of two divergent instances. It is a pure in-memory
+ * request-scoping primitive (no I/O, no secret), so a shared module-level singleton
+ * is safe and idiomatic (this is exactly how Nest's own `ClsService`-style helpers
+ * and request-context libraries share an ALS).
+ *
+ * ── CROSS-PRINCIPAL ISOLATION (the #1 danger) ────────────────────────────────────
+ * `AsyncLocalStorage.run(store, cb)` binds `store` to the async execution context of
+ * `cb` and everything it awaits — and ONLY that context. Two concurrent requests each
+ * call `run()` with THEIR OWN store, so `getStore()` inside each returns that request's
+ * facts and never the other's. The guard enters the scope with THIS request's
+ * `claims.cachedFacts` (same bearer token → same principal → same facts) wrapping the
+ * `decide()` call, so the facts a gate reads are always the current request's. The
+ * reader holds NO per-request state on `this` — only the ALS handle — so nothing leaks
+ * across requests through the reader object itself.
+ *
+ * ── FAIL-CLOSED ──────────────────────────────────────────────────────────────────
+ * Outside any `run()` scope (or when the guard entered with `cachedFacts: null` because
+ * the binding carried none / was malformed), `getStore()` is `undefined` / the store's
+ * `cachedFacts` is `null`. The reader maps BOTH to `{ cachedFacts: null,
+ * permissionsVersion: 0 }`, so gate 5 falls back to the authoritative DB reload
+ * (`PermissionFactsPort.loadCoarseGrants`). A cache miss NEVER fabricates a permit.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { CoarseGrants } 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 →
+ * gate 5 DB-reloads); `permissionsVersion` is the version those facts were projected
+ * at (0 when absent). Mirrors the core `SessionFactsReader` shape 1:1.
+ */
+export interface SessionFactsStore {
+    /** THIS request's coarse grants (ADR-0011), or `null` → gate 5 reloads via the port. */
+    readonly cachedFacts: CoarseGrants | null;
+    /** The version `cachedFacts` was projected at (0 when absent). */
+    readonly permissionsVersion: number;
+}
+/**
+ * The ONE shared session-facts `AsyncLocalStorage` (see the file header). The
+ * enforcement guard imports this to `run()` the `decide()` call inside the request's
+ * scope; the consumer's ALS-backed `SessionFactsReader` imports the SAME instance to
+ * `getStore()`. Exported through the guard barrel so the app reads the identical
+ * singleton — never a second, divergent ALS.
+ */
+export declare const SHIELD_SESSION_FACTS_ALS: AsyncLocalStorage<SessionFactsStore>;
+/**
+ * The fail-closed "no facts" store — what a reader returns when there is no active
+ * scope or the scope carried no facts. Kept here as the single source of the
+ * fail-closed shape so the guard and the reader agree byte-for-byte.
+ */
+export declare const NO_SESSION_FACTS: SessionFactsStore;
+//# sourceMappingURL=session-facts-als.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * The per-request **session-facts AsyncLocalStorage** (ADR-0011 hot path) — the
+ * SINGLE shared instance the enforcement guard ENTERS and the consumer's
+ * `SessionFactsReader` READS. This is the seam that lets gate 5 serve a principal's
+ * coarse grants from the request's cached facts instead of a DB reload on every
+ * request, WITHOUT touching the frozen 4-arg `decide()` signature or the core
+ * `SessionFactsReader` dep contract.
+ *
+ * ── WHY A FRAMEWORK-EXPORTED SINGLETON (not DI-injected) ─────────────────────────
+ * The guard (framework) must ENTER the scope; the reader (app-owned — astram3 swaps
+ * `nullSessionFacts` for an ALS-backed one) must READ the SAME scope. An
+ * `AsyncLocalStorage` only shares state across `run()`/`getStore()` calls on the
+ * SAME instance, so both sides MUST hold one identical object. Exporting ONE module
+ * singleton and importing it on both sides is the simplest way to guarantee that —
+ * no DI token round-trip, no risk of two divergent instances. It is a pure in-memory
+ * request-scoping primitive (no I/O, no secret), so a shared module-level singleton
+ * is safe and idiomatic (this is exactly how Nest's own `ClsService`-style helpers
+ * and request-context libraries share an ALS).
+ *
+ * ── CROSS-PRINCIPAL ISOLATION (the #1 danger) ────────────────────────────────────
+ * `AsyncLocalStorage.run(store, cb)` binds `store` to the async execution context of
+ * `cb` and everything it awaits — and ONLY that context. Two concurrent requests each
+ * call `run()` with THEIR OWN store, so `getStore()` inside each returns that request's
+ * facts and never the other's. The guard enters the scope with THIS request's
+ * `claims.cachedFacts` (same bearer token → same principal → same facts) wrapping the
+ * `decide()` call, so the facts a gate reads are always the current request's. The
+ * reader holds NO per-request state on `this` — only the ALS handle — so nothing leaks
+ * across requests through the reader object itself.
+ *
+ * ── FAIL-CLOSED ──────────────────────────────────────────────────────────────────
+ * Outside any `run()` scope (or when the guard entered with `cachedFacts: null` because
+ * the binding carried none / was malformed), `getStore()` is `undefined` / the store's
+ * `cachedFacts` is `null`. The reader maps BOTH to `{ cachedFacts: null,
+ * permissionsVersion: 0 }`, so gate 5 falls back to the authoritative DB reload
+ * (`PermissionFactsPort.loadCoarseGrants`). A cache miss NEVER fabricates a permit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_SESSION_FACTS = exports.SHIELD_SESSION_FACTS_ALS = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * The ONE shared session-facts `AsyncLocalStorage` (see the file header). The
+ * enforcement guard imports this to `run()` the `decide()` call inside the request's
+ * scope; the consumer's ALS-backed `SessionFactsReader` imports the SAME instance to
+ * `getStore()`. Exported through the guard barrel so the app reads the identical
+ * singleton — never a second, divergent ALS.
+ */
+exports.SHIELD_SESSION_FACTS_ALS = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * The fail-closed "no facts" store — what a reader returns when there is no active
+ * scope or the scope carried no facts. Kept here as the single source of the
+ * fail-closed shape so the guard and the reader agree byte-for-byte.
+ */
+exports.NO_SESSION_FACTS = Object.freeze({
+    cachedFacts: null,
+    permissionsVersion: 0,
+});