@astram/guard 0.2.0 → 0.3.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/module/shield.module.js.map

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

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/request-principal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-principal.js","sourceRoot":"","sources":["../../src/request-auth/request-principal.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;AASH,gDAKC;AAOD,kDAoBC;AAMD,0DASC;AAUD,gDAWC;AAxED,sFAAsF;AACtF,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAE3E,6EAA6E;AAC7E,SAAgB,kBAAkB,CAAC,mBAA4B;IAC7D,IAAI,OAAO,mBAAmB,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzD,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IAC7B,OAAO,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,MAA4B;IAC9D,IACE,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ;QAC7B,MAAM,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC;QACtB,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;QACnC,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAC5B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,MAAM,CAAC,IAA0B,CAAC,CAAC,CAAC,MAAM,CAAC;IAC5F,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;QAC3C,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;QAClE,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI;QACJ,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC;QACpC,MAAM,EAAE,MAAM,CAAC,MAAM,KAAK,IAAI;KAC/B,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,uBAAuB,CAC3C,mBAA4B,EAC5B,MAA0B;IAE1B,MAAM,KAAK,GAAG,kBAAkB,CAAC,mBAAmB,CAAC,CAAC;IACtD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,kBAAkB,CACtC,mBAA4B,EAC5B,MAA0B;IAE1B,MAAM,KAAK,GAAG,kBAAkB,CAAC,mBAAmB,CAAC,CAAC;IACtD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjC,MAAM,SAAS,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;AAC/B,CAAC"}

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,
+});

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-facts-als.js","sourceRoot":"","sources":["../../src/request-auth/session-facts-als.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;;;AAEH,uDAAqD;AAmBrD;;;;;;GAMG;AACU,QAAA,wBAAwB,GAAG,IAAI,oCAAiB,EAAqB,CAAC;AAEnF;;;;GAIG;AACU,QAAA,gBAAgB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC/D,WAAW,EAAE,IAAI;IACjB,kBAAkB,EAAE,CAAC;CACtB,CAAC,CAAC"}