@astram/guard 0.5.1 → 0.7.0

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

@@ -11,6 +11,8 @@ import type { SessionSweeper } from '../auth/ports/session-sweeper.js';
 import type { MfaDeviceStore } from '../auth/ports/mfa-device-store.js';
 import type { AuditSink } from '../auth/ports/audit-sink.js';
 import type { SessionFactsProjector } from '../auth/ports/session-facts-projector.js';
+import type { ScopeSubtreeResolver } from '../auth/ports/scope-subtree-resolver.js';
+import type { MembershipChecker } from '../auth/ports/membership-checker.js';
 import type { CoreDecisionAuthority } from '../enforcement/core-seam.js';
 import { type AppConfig } from '../config/app-config.js';
 import { SHIELD_DECISION_AUTHORITY } from './shield-tokens.js';
@@ -156,6 +158,25 @@ export interface ShieldModuleOptions {
      * `cachedFacts`. Only consulted when `auth: true`.
      */
     readonly sessionFactsProjector?: SessionFactsProjector;
+    /**
+     * OPTIONAL active-scope-subtree resolver (Task 2.2, ADR-0027 / ADR-0024) — see
+     * {@link AuthModuleOptions.scopeSubtreeResolver}. Threaded straight through to
+     * {@link AuthModule.forRoot} (bound under {@link SHIELD_SCOPE_SUBTREE_RESOLVER}, or `null` when
+     * absent → the auth controller omits `scopeSubtreeNodeIds` and the per-request path falls back to
+     * the self-node `[tenantId]`, today's flat isolation). When supplied, login resolves the
+     * principal's closure subtree ONCE and caches it on the session binding so the per-request tenant
+     * gate reads the real subtree with zero DB. Only consulted when `auth: true`.
+     */
+    readonly scopeSubtreeResolver?: ScopeSubtreeResolver;
+    /**
+     * OPTIONAL scope-switch membership checker (Task 5.2, ADR-0027 / ADR-0024) — see
+     * {@link AuthModuleOptions.membershipChecker}. Threaded straight through to
+     * {@link AuthModule.forRoot} (bound under {@link SHIELD_MEMBERSHIP_CHECKER}, or `null` when
+     * absent → `POST /auth/scope-switch` fails closed, denying every switch — cannot verify the
+     * target binding). When supplied, the scope-switch gate confirms the principal holds an active
+     * membership at the target node before re-binding the session. Only consulted when `auth: true`.
+     */
+    readonly membershipChecker?: MembershipChecker;
 }
 /** Async variant of {@link ShieldModuleOptions} (DI-computed config). */
 export interface ShieldModuleAsyncOptions {
@@ -248,6 +269,18 @@ export interface ShieldModuleAsyncOptions {
      * options. Only consulted when `auth: true`.
      */
     readonly sessionFactsProjector?: SessionFactsProjector;
+    /**
+     * OPTIONAL active-scope-subtree resolver — see {@link ShieldModuleOptions.scopeSubtreeResolver}.
+     * STATIC here (like the other seams): a registration-time collaborator threaded into the
+     * statically-composed {@link AuthModule} import. Only consulted when `auth: true`.
+     */
+    readonly scopeSubtreeResolver?: ScopeSubtreeResolver;
+    /**
+     * OPTIONAL scope-switch membership checker — see {@link ShieldModuleOptions.membershipChecker}.
+     * STATIC here (like the other seams): a registration-time collaborator threaded into the
+     * statically-composed {@link AuthModule} import. Only consulted when `auth: true`.
+     */
+    readonly membershipChecker?: MembershipChecker;
 }
 /**
  * `ShieldModule` — the SINGLE registration seam (ADR-0023 §4).

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

@@ -197,6 +197,12 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
                 ...(options.sessionFactsProjector
                     ? { sessionFactsProjector: options.sessionFactsProjector }
                     : {}),
+                ...(options.scopeSubtreeResolver
+                    ? { scopeSubtreeResolver: options.scopeSubtreeResolver }
+                    : {}),
+                ...(options.membershipChecker
+                    ? { membershipChecker: options.membershipChecker }
+                    : {}),
             })
             : undefined;
         return {
@@ -308,6 +314,12 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
                 ...(options.sessionFactsProjector
                     ? { sessionFactsProjector: options.sessionFactsProjector }
                     : {}),
+                ...(options.scopeSubtreeResolver
+                    ? { scopeSubtreeResolver: options.scopeSubtreeResolver }
+                    : {}),
+                ...(options.membershipChecker
+                    ? { membershipChecker: options.membershipChecker }
+                    : {}),
             })
             : undefined;
         return {

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

@@ -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,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"}
+{"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')
@@ -44,22 +52,73 @@ function principalFromClaims(claims) {
     const roleIds = Array.isArray(claims.roleIds)
         ? claims.roleIds.filter((r) => typeof r === 'string')
         : [];
+    // Scope (ADR-0027 / ADR-0024, Task 2.2) — the active scope node IS the bound tenant. The
+    // reachable subtree is the CLOSURE-RESOLVED set (self node + descendants) cached on the binding
+    // at LOGIN (`claims.scopeSubtreeNodeIds`), read here with ZERO DB — the parity guarantee: the
+    // closure query happened once at login, never per request. FAIL-SAFE + NON-WIDENING: when the
+    // cached subtree is ABSENT or EMPTY (a legacy binding, an unwired resolver, or a resolver that
+    // threw at login), fall back to just the self-node `[tenantId]` — today's flat self-tenant
+    // isolation, EXACTLY. A missing subtree can never widen a principal's reach.
+    const subtree = Array.isArray(claims.scopeSubtreeNodeIds) && claims.scopeSubtreeNodeIds.length > 0
+        ? [...claims.scopeSubtreeNodeIds]
+        : [claims.tenantId];
     return Object.freeze({
         kind,
         id: claims.id,
+        activeScopeNodeId: claims.tenantId,
+        scopeSubtreeNodeIds: Object.freeze(subtree),
         tenantId: claims.tenantId,
         roleIds: Object.freeze([...roleIds]),
         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;
@@ -73,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/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,kDAiCC;AAMD,0DASC;AAUD,gDAWC;AArFD,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,yFAAyF;IACzF,gGAAgG;IAChG,8FAA8F;IAC9F,8FAA8F;IAC9F,+FAA+F;IAC/F,2FAA2F;IAC3F,6EAA6E;IAC7E,MAAM,OAAO,GACX,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,IAAI,MAAM,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC;QAChF,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,mBAAmB,CAAC;QACjC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI;QACJ,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,iBAAiB,EAAE,MAAM,CAAC,QAAQ;QAClC,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;QAC3C,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.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"}

package/dist/request-auth/session-token-binder.d.ts

@@ -65,6 +65,20 @@ export interface BoundPrincipalClaims {
      * `cachedFacts` slot is treated as absent (see `resolve()`), never fabricated.
      */
     readonly cachedFacts?: CoarseGrants;
+    /**
+     * OPTIONAL cached active-scope subtree (ADR-0027 / ADR-0024) — the active scope node + all its
+     * descendants, resolved ONCE at session establish from `shield_authz.scope_closure` and stored
+     * HERE so the per-request tenant gate reads it from the binding (zero per-request DB — the parity
+     * guarantee). The subtree query happens ONLY at login; `resolve()` returns this cached set and
+     * `principalFromClaims` reads it with NO DB call.
+     *
+     * ABSENT (undefined) → `principalFromClaims` falls back to `[tenantId]` (self-node, today's flat
+     * isolation) — the fail-safe, NON-WIDENING default for a legacy/old binding, an unwired resolver,
+     * or a resolver that threw at login. It is NEVER inferred; only a genuine login-time resolution
+     * sets it, and an EMPTY resolution is treated as absent (→ self-node) so a missing closure can
+     * never silently widen or empty a principal's reach.
+     */
+    readonly scopeSubtreeNodeIds?: readonly string[];
 }
 export declare class SessionTokenBinder {
     private readonly redis;
@@ -96,7 +110,27 @@ export declare class SessionTokenBinder {
      *   - `null` → STRIP `cachedFacts` (a projection that yielded nothing → the next
      *     request DB-reloads; fail-closed).
      */
-    rebindOnRotate(newAccessToken: string, sessionId: string, ttlMs: number, freshFacts?: CoarseGrants | null): Promise<boolean>;
+    rebindOnRotate(newAccessToken: string, sessionId: string, ttlMs: number, freshFacts?: CoarseGrants | null, freshSubtree?: readonly string[]): Promise<boolean>;
+    /**
+     * SCOPE-SWITCH re-bind (Task 5.2, ADR-0027 / ADR-0024). A principal is switching which
+     * active node it acts under; re-bind its CURRENT session (the same access token — no
+     * rotate, no new tokens) so the bound `tenantId` becomes `targetNodeId` (the new active
+     * scope node → `principalFromClaims` reads `activeScopeNodeId = tenantId`) and
+     * `scopeSubtreeNodeIds` becomes the NEW node's closure-resolved subtree. The old node's
+     * subtree/tenant is REPLACED — stale authority from the previous scope does NOT carry
+     * over (the security point of the switch).
+     *
+     * Rewrites BOTH the per-access-token binding AND the session-claims cushion (so a later
+     * refresh/rotate carries the NEW active scope forward), each preserving its remaining TTL
+     * (a scope-switch NEVER extends the session life). The `cachedFacts` slot is STRIPPED —
+     * the old node's coarse grants are stale under the new scope; the next request re-projects
+     * / DB-reloads (fail-closed, never a stale-grant carry-over). The caller resolves the
+     * subtree for the NEW node and passes it in.
+     *
+     * Returns `true` on a successful re-bind, `false` when the binding is gone (logged out /
+     * expired) or Redis is unavailable (the caller then denies the switch — fail-closed).
+     */
+    rebindActiveScope(accessToken: string, sessionId: string, targetNodeId: string, subtree: readonly string[]): Promise<boolean>;
     /**
      * Resolve an access token to its bound claims, or `null` if the binding is
      * absent/expired. Fail-closed: any Redis error → `null` (the caller denies), never

package/dist/request-auth/session-token-binder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-token-binder.d.ts","sourceRoot":"","sources":["../../src/request-auth/session-token-binder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAKjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,oFAAoF;AACpF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,YAAY,CAAC;CACrC;AA0CD,qBAAa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,KAAK;IAEzC;;;;;;;OAOG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3F;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAClB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,YAAY,GAAG,IAAI,GAC/B,OAAO,CAAC,OAAO,CAAC;IAgCnB;;;;;OAKG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA8DxE;;;;;;;;;;;;OAYG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BrD,gDAAgD;IAC1C,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhD;;;;OAIG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOtD"}
+{"version":3,"file":"session-token-binder.d.ts","sourceRoot":"","sources":["../../src/request-auth/session-token-binder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAKjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,oFAAoF;AACpF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,YAAY,CAAC;IACpC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClD;AAmED,qBAAa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,KAAK;IAEzC;;;;;;;OAOG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3F;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAClB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,YAAY,GAAG,IAAI,EAChC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAC/B,OAAO,CAAC,OAAO,CAAC;IA2CnB;;;;;;;;;;;;;;;;;;OAkBG;IACG,iBAAiB,CACrB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,OAAO,CAAC,OAAO,CAAC;IAmDnB;;;;;OAKG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAwExE;;;;;;;;;;;;OAYG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BrD,gDAAgD;IAC1C,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhD;;;;OAIG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOtD"}

package/dist/request-auth/session-token-binder.js

@@ -45,6 +45,30 @@ function parseCachedFacts(slot) {
         grantedPermissionKeys: [...c.grantedPermissionKeys],
     };
 }
+/**
+ * Structurally validate the OPTIONAL `scopeSubtreeNodeIds` slot from the (untrusted) Redis
+ * payload. Returns a fresh string[] of the non-empty node ids, or `undefined` when the slot is
+ * absent, not an array, empty, or carries any non-string element (fail-safe → the per-request
+ * path falls back to the self-node; a junk slot can never widen or empty a principal's reach).
+ */
+function parseScopeSubtree(slot) {
+    if (!Array.isArray(slot) || slot.length === 0)
+        return undefined;
+    const out = [];
+    for (const n of slot) {
+        if (typeof n !== 'string' || n.length === 0)
+            return undefined;
+        out.push(n);
+    }
+    return out;
+}
+/** Return the claims with any `scopeSubtreeNodeIds` slot removed (absent → self-node fallback). */
+function stripScopeSubtree(claims) {
+    if (!('scopeSubtreeNodeIds' in claims))
+        return claims;
+    const { scopeSubtreeNodeIds: _drop, ...rest } = claims;
+    return rest;
+}
 /** Return the claims with any `cachedFacts` slot removed (absent → gate 5 DB-reloads). */
 function stripCachedFacts(claims) {
     if (!('cachedFacts' in claims))
@@ -100,7 +124,7 @@ class SessionTokenBinder {
      *   - `null` → STRIP `cachedFacts` (a projection that yielded nothing → the next
      *     request DB-reloads; fail-closed).
      */
-    async rebindOnRotate(newAccessToken, sessionId, ttlMs, freshFacts) {
+    async rebindOnRotate(newAccessToken, sessionId, ttlMs, freshFacts, freshSubtree) {
         let raw;
         try {
             raw = await this.redis.get(sessClaimsKey(sessionId));
@@ -110,16 +134,28 @@ class SessionTokenBinder {
         }
         if (raw === null)
             return false;
-        // Default: carry the existing payload forward byte-for-byte (facts unchanged).
+        // Default: carry the existing payload forward byte-for-byte (facts + subtree unchanged).
         let payload = raw;
-        if (freshFacts !== undefined) {
-            // A refresh-time projection was supplied → rewrite the `cachedFacts` slot on the
-            // carried-forward claims. A parse failure here is treated as "nothing to update"
-            // and we carry the original payload forward (fail-safe: never drop the whole
-            // binding on a transient JSON hiccup — a later request re-projects/DB-reloads).
+        if (freshFacts !== undefined || freshSubtree !== undefined) {
+            // A refresh-time projection and/or subtree was supplied → rewrite those slots on the
+            // carried-forward claims. A parse failure here is treated as "nothing to update" and we
+            // carry the original payload forward (fail-safe: never drop the whole binding on a
+            // transient JSON hiccup — a later request re-projects/DB-reloads).
             try {
                 const parsed = JSON.parse(raw);
-                const next = freshFacts === null ? stripCachedFacts(parsed) : { ...parsed, cachedFacts: freshFacts };
+                let next = parsed;
+                if (freshFacts !== undefined) {
+                    next =
+                        freshFacts === null ? stripCachedFacts(next) : { ...next, cachedFacts: freshFacts };
+                }
+                // The subtree (the stale-subtree-after-move fix): a non-empty fresh set REPLACES the
+                // carried-forward one (a re-parented session gets its correct, possibly-smaller subtree).
+                // `undefined` (no resolver / empty / threw at refresh) → carry the existing subtree
+                // forward (fail-safe, non-widening — never narrow to self-node on a transient resolver
+                // hiccup, never fail the refresh).
+                if (freshSubtree !== undefined && freshSubtree.length > 0) {
+                    next = { ...next, scopeSubtreeNodeIds: [...freshSubtree] };
+                }
                 payload = JSON.stringify(next);
             }
             catch {
@@ -131,6 +167,77 @@ class SessionTokenBinder {
         await this.redis.set(sessClaimsKey(sessionId), payload, 'PX', Math.max(ttlMs * 4, ttlMs));
         return true;
     }
+    /**
+     * SCOPE-SWITCH re-bind (Task 5.2, ADR-0027 / ADR-0024). A principal is switching which
+     * active node it acts under; re-bind its CURRENT session (the same access token — no
+     * rotate, no new tokens) so the bound `tenantId` becomes `targetNodeId` (the new active
+     * scope node → `principalFromClaims` reads `activeScopeNodeId = tenantId`) and
+     * `scopeSubtreeNodeIds` becomes the NEW node's closure-resolved subtree. The old node's
+     * subtree/tenant is REPLACED — stale authority from the previous scope does NOT carry
+     * over (the security point of the switch).
+     *
+     * Rewrites BOTH the per-access-token binding AND the session-claims cushion (so a later
+     * refresh/rotate carries the NEW active scope forward), each preserving its remaining TTL
+     * (a scope-switch NEVER extends the session life). The `cachedFacts` slot is STRIPPED —
+     * the old node's coarse grants are stale under the new scope; the next request re-projects
+     * / DB-reloads (fail-closed, never a stale-grant carry-over). The caller resolves the
+     * subtree for the NEW node and passes it in.
+     *
+     * Returns `true` on a successful re-bind, `false` when the binding is gone (logged out /
+     * expired) or Redis is unavailable (the caller then denies the switch — fail-closed).
+     */
+    async rebindActiveScope(accessToken, sessionId, targetNodeId, subtree) {
+        // Read the current claims (from the per-access-token entry) + confirm the session is
+        // still live (the session-claims entry exists). Any miss / Redis error → fail closed.
+        let rawAt;
+        let rawSess;
+        try {
+            rawAt = await this.redis.get(atKey(accessToken));
+            rawSess = await this.redis.get(sessClaimsKey(sessionId));
+        }
+        catch {
+            return false; // Redis unavailable → fail closed (no switch).
+        }
+        if (rawAt === null || rawSess === null)
+            return false; // token/session gone → fail closed.
+        let current;
+        try {
+            current = JSON.parse(rawAt);
+        }
+        catch {
+            return false; // malformed → fail closed (a later request re-denies anyway).
+        }
+        // Build the re-scoped claims: new active node (tenantId) + new subtree, facts stripped.
+        // An empty subtree is stored as absent (→ per-request self-node fallback, non-widening) —
+        // but the switch caller always passes at least `[targetNodeId]`, so this is defensive.
+        const next = stripCachedFacts({
+            ...stripScopeSubtree(current),
+            tenantId: targetNodeId,
+            sessionId,
+            ...(subtree.length > 0 ? { scopeSubtreeNodeIds: [...subtree] } : {}),
+        });
+        const payload = JSON.stringify(next);
+        // Preserve each key's remaining TTL — a scope-switch must never extend the session.
+        let atTtl;
+        let sessTtl;
+        try {
+            atTtl = await this.redis.pttl(atKey(accessToken));
+            sessTtl = await this.redis.pttl(sessClaimsKey(sessionId));
+        }
+        catch {
+            return false;
+        }
+        if (atTtl <= 0 || sessTtl <= 0)
+            return false; // expired between reads → fail closed.
+        try {
+            await this.redis.set(atKey(accessToken), payload, 'PX', atTtl);
+            await this.redis.set(sessClaimsKey(sessionId), payload, 'PX', sessTtl);
+        }
+        catch {
+            return false;
+        }
+        return true;
+    }
     /**
      * Resolve an access token to its bound claims, or `null` if the binding is
      * absent/expired. Fail-closed: any Redis error → `null` (the caller denies), never
@@ -171,6 +278,14 @@ class SessionTokenBinder {
         parsed = cachedFacts === undefined
             ? stripCachedFacts(parsed)
             : { ...parsed, cachedFacts };
+        // Normalize the OPTIONAL scope-subtree slot (ADR-0027 / Task 2.2): an absent, empty, or
+        // malformed slot is scrubbed to ABSENT (→ `principalFromClaims` falls back to the self-node,
+        // non-widening); a well-formed non-empty array is the validated cached subtree. Never
+        // fabricated — rebuild the object so a junk slot cannot ride through into a Principal.
+        const scopeSubtreeNodeIds = parseScopeSubtree(parsed.scopeSubtreeNodeIds);
+        parsed = scopeSubtreeNodeIds === undefined
+            ? stripScopeSubtree(parsed)
+            : { ...parsed, scopeSubtreeNodeIds };
         // SESSION-LIVENESS GATE: the per-token binding alone is not enough — a logout
         // revokes the session but cannot reach every outstanding access-token key. So we
         // ALSO require the session-claims entry (which `unbindSession` deletes on logout)

package/dist/request-auth/session-token-binder.js.map

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

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

@@ -11,4 +11,14 @@
  * missing (fail-closed).
  */
 export declare const SHIELD_SESSION_TOKEN_BINDER: unique symbol;
+/**
+ * The {@link import('@astram/core').ServiceAuthenticator} — authenticates a service-account API
+ * key (`Authorization: Bearer ask_…`, ADR-0033) into a tenant-bound `service_account` Principal.
+ * Provided only when the app wires an {@link import('@astram/core').ApiKeyStore} (i.e. it enables
+ * machine/agent access). ABSENT by default — the guard injects it `@Optional()`; when missing, an
+ * `ask_…` bearer simply has no authenticator and is treated as an unresolvable token (401,
+ * fail-closed), exactly as if the key were unknown. Enabling it opens the machine auth path WITHOUT
+ * touching the human session path.
+ */
+export declare const SHIELD_SERVICE_AUTHENTICATOR: unique symbol;
 //# sourceMappingURL=tokens.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/request-auth/tokens.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,eAAwC,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/request-auth/tokens.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,eAAwC,CAAC;AAEjF;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,eAAyC,CAAC"}

package/dist/request-auth/tokens.js

@@ -4,7 +4,7 @@
  * the enforcement guard and the auth wiring can both depend on them without cycles.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SHIELD_SESSION_TOKEN_BINDER = void 0;
+exports.SHIELD_SERVICE_AUTHENTICATOR = exports.SHIELD_SESSION_TOKEN_BINDER = void 0;
 /**
  * The {@link import('./session-token-binder.js').SessionTokenBinder} — binds an
  * opaque access token to its principal claims (server-side), so the enforcement
@@ -14,3 +14,13 @@ exports.SHIELD_SESSION_TOKEN_BINDER = void 0;
  * missing (fail-closed).
  */
 exports.SHIELD_SESSION_TOKEN_BINDER = Symbol('SHIELD_SESSION_TOKEN_BINDER');
+/**
+ * The {@link import('@astram/core').ServiceAuthenticator} — authenticates a service-account API
+ * key (`Authorization: Bearer ask_…`, ADR-0033) into a tenant-bound `service_account` Principal.
+ * Provided only when the app wires an {@link import('@astram/core').ApiKeyStore} (i.e. it enables
+ * machine/agent access). ABSENT by default — the guard injects it `@Optional()`; when missing, an
+ * `ask_…` bearer simply has no authenticator and is treated as an unresolvable token (401,
+ * fail-closed), exactly as if the key were unknown. Enabling it opens the machine auth path WITHOUT
+ * touching the human session path.
+ */
+exports.SHIELD_SERVICE_AUTHENTICATOR = Symbol('SHIELD_SERVICE_AUTHENTICATOR');

package/dist/request-auth/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/request-auth/tokens.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;;;GAOG;AACU,QAAA,2BAA2B,GAAG,MAAM,CAAC,6BAA6B,CAAC,CAAC"}