@astram/guard 0.5.0 → 0.6.0

package/dist/index.js

@@ -16,9 +16,9 @@
  * `@nestjs/core`, `reflect-metadata`, `rxjs` so the host owns one copy of each.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MariaDbCrossTenantGrantAdapter = exports.makeShareDeleteCascade = exports.ShareStoreUnavailableError = exports.ShareNotPermittedError = exports.SHIELD_RECORD_SHARE_WRITER = exports.RecordShareWriter = exports.SHIELD_RECORD_SHARE_PORT = exports.MariaDbRecordShareAdapter = exports.SHIELD_RECORD_RULE_PORT = exports.MariaDbRecordPermissionRuleAdapter = exports.SHIELD_CLOCK = exports.SHIELD_REFRESH_HASHER = exports.SHIELD_TOKEN_GENERATOR = exports.systemClockProvider = exports.refreshHasherProvider = exports.cryptoTokenGeneratorProvider = exports.SystemClock = exports.Sha256RefreshTokenHasher = exports.CryptoTokenGenerator = exports.SHIELD_HOT_SESSION_STORE = exports.RedisHotSessionStore = exports.SHIELD_SESSION_RECORD_STORE = exports.MariaDbSessionRecordStore = exports.SHIELD_PASSWORD_HASHER = exports.argon2idHasherProvider = exports.Argon2idPasswordHasher = exports.stubDecisionAuthority = exports.GlobalEnforcementGuard = exports.NO_SESSION_FACTS = exports.SHIELD_SESSION_FACTS_ALS = exports.extractBearerToken = exports.principalFromClaims = exports.resolveRequestPrincipal = exports.SessionTokenBinder = exports.SHIELD_SESSION_TOKEN_BINDER = exports.CatalogGatabilityError = exports.CatalogReconciler = exports.OperationInventoryScanner = exports.normalizeClassification = exports.DEFAULT_CLASSIFIED_ACTION = exports.CLASSIFICATION_METADATA = exports.Classified = exports.Public = exports.SHIELD_DECISION_AUTHORITY = exports.ShieldModule = exports.actionsFor = exports.IDENTITY_ACTIONS = exports.MODULE_KEY = exports.buildIdentityModuleRegistry = exports.guardMigrationsDir = void 0;
-exports.buildOtpauthUri = exports.generateTotpSecret = exports.PendingMfaStore = exports.AuthController = exports.SHIELD_SESSION_FACTS_PROJECTOR = exports.hmacSha1 = exports.resolveTotpVerifier = exports.makeDefaultTotpVerifier = exports.AuthModule = exports.PersistenceModule = exports.MariaDbCredentialResolver = exports.SHIELD_TOTP_VERIFIER_OVERRIDE = exports.SHIELD_MFA_DEVICE_STORE = exports.SHIELD_AUDIT_SINK = exports.SHIELD_SESSION_SWEEPER = exports.SHIELD_PROFILE_WRITER = exports.SHIELD_RECOVERY_CODE_STORE = exports.SHIELD_EMAIL_SENDER = exports.SHIELD_RESET_TOKEN_STORE = exports.SHIELD_CREDENTIAL_WRITER = exports.SHIELD_SESSION_AUTHORITY = exports.SHIELD_AUTHENTICATOR = exports.SHIELD_PROFILE_RESOLVER = exports.SHIELD_CREDENTIAL_RESOLVER = exports.SHIELD_REDIS = exports.SHIELD_DB_POOL = exports.DEFAULT_REDIS_URL = exports.DEFAULT_DB_CONFIG = exports.assertRefreshHmacKey = exports.loadRefreshHmacKey = exports.loadSessionLifetimes = exports.loadRedisConfig = exports.loadDbConfig = exports.SCHEMA_SVC_POOL_HARD_CAP = exports.DEFAULT_POOL_BUDGET = exports.evaluatePoolBudget = exports.loadPoolBudget = exports.loadAppConfig = exports.APP_CONFIG = exports.assertPoolBudget = exports.BootSequence = exports.buildRecordAuthorization = exports.SHIELD_OPERATION_AUTHORITY_PORT = exports.ManifestOperationAuthorityAdapter = exports.GrantStoreUnavailableError = exports.InvalidGrantError = exports.GrantNotPermittedError = exports.SHIELD_CROSS_TENANT_GRANT_WRITER = exports.CrossTenantGrantWriter = exports.SHIELD_CROSS_TENANT_GRANT_PORT = void 0;
-exports.AccountController = exports.generateRecoveryCodes = void 0;
+exports.SHIELD_RECORD_SHARE_PORT = exports.MariaDbRecordShareAdapter = exports.UnknownScopeFieldError = exports.translateListScope = exports.SHIELD_LIST_SCOPE_PORT = exports.MariaDbListScopeAdapter = exports.SHIELD_POLICY_STORE = exports.MariaDbPolicyStore = exports.SHIELD_RECORD_RULE_PORT = exports.MariaDbRecordPermissionRuleAdapter = exports.SHIELD_CLOCK = exports.SHIELD_REFRESH_HASHER = exports.SHIELD_TOKEN_GENERATOR = exports.systemClockProvider = exports.refreshHasherProvider = exports.cryptoTokenGeneratorProvider = exports.SystemClock = exports.Sha256RefreshTokenHasher = exports.CryptoTokenGenerator = exports.SHIELD_HOT_SESSION_STORE = exports.RedisHotSessionStore = exports.SHIELD_SESSION_RECORD_STORE = exports.MariaDbSessionRecordStore = exports.SHIELD_PASSWORD_HASHER = exports.argon2idHasherProvider = exports.Argon2idPasswordHasher = exports.stubDecisionAuthority = exports.GlobalEnforcementGuard = exports.NO_SESSION_FACTS = exports.SHIELD_SESSION_FACTS_ALS = exports.extractBearerToken = exports.principalFromClaims = exports.resolveRequestPrincipal = exports.SessionTokenBinder = exports.SHIELD_SESSION_TOKEN_BINDER = exports.CatalogGatabilityError = exports.CatalogReconciler = exports.OperationInventoryScanner = exports.normalizeClassification = exports.DEFAULT_CLASSIFIED_ACTION = exports.CLASSIFICATION_METADATA = exports.Classified = exports.Public = exports.SHIELD_DECISION_AUTHORITY = exports.ShieldModule = exports.actionsFor = exports.IDENTITY_ACTIONS = exports.MODULE_KEY = exports.buildIdentityModuleRegistry = exports.guardMigrationsDir = void 0;
+exports.makeDefaultTotpVerifier = exports.AuthModule = exports.PersistenceModule = exports.MariaDbCredentialResolver = exports.SHIELD_TOTP_VERIFIER_OVERRIDE = exports.SHIELD_MFA_DEVICE_STORE = exports.SHIELD_AUDIT_SINK = exports.SHIELD_SESSION_SWEEPER = exports.SHIELD_PROFILE_WRITER = exports.SHIELD_RECOVERY_CODE_STORE = exports.SHIELD_EMAIL_SENDER = exports.SHIELD_RESET_TOKEN_STORE = exports.SHIELD_CREDENTIAL_WRITER = exports.SHIELD_SESSION_AUTHORITY = exports.SHIELD_AUTHENTICATOR = exports.SHIELD_PROFILE_RESOLVER = exports.SHIELD_CREDENTIAL_RESOLVER = exports.SHIELD_REDIS = exports.SHIELD_DB_POOL = exports.DEFAULT_REDIS_URL = exports.DEFAULT_DB_CONFIG = exports.assertRefreshHmacKey = exports.loadRefreshHmacKey = exports.loadSessionLifetimes = exports.loadRedisConfig = exports.loadDbConfig = exports.SCHEMA_SVC_POOL_HARD_CAP = exports.DEFAULT_POOL_BUDGET = exports.evaluatePoolBudget = exports.loadPoolBudget = exports.loadAppConfig = exports.APP_CONFIG = exports.assertPoolBudget = exports.BootSequence = exports.buildListScopeFn = exports.buildRecordAuthorization = exports.SHIELD_OPERATION_AUTHORITY_PORT = exports.ManifestOperationAuthorityAdapter = exports.GrantStoreUnavailableError = exports.InvalidGrantError = exports.GrantNotPermittedError = exports.SHIELD_CROSS_TENANT_GRANT_WRITER = exports.CrossTenantGrantWriter = exports.SHIELD_CROSS_TENANT_GRANT_PORT = exports.MariaDbCrossTenantGrantAdapter = exports.makeShareDeleteCascade = exports.ShareStoreUnavailableError = exports.ShareNotPermittedError = exports.SHIELD_RECORD_SHARE_WRITER = exports.RecordShareWriter = void 0;
+exports.ScopeUnknownParentError = exports.ScopeDepthError = exports.ScopeCycleError = exports.buildClosureRows = exports.AccountController = exports.generateRecoveryCodes = exports.buildOtpauthUri = exports.generateTotpSecret = exports.PendingMfaStore = exports.AuthController = exports.SHIELD_SCOPE_SUBTREE_RESOLVER = exports.SHIELD_SESSION_FACTS_PROJECTOR = exports.hmacSha1 = exports.resolveTotpVerifier = void 0;
 // Framework authz migrations (shield_authz DDL — permission / role_permission /
 // authz_permission_version). Absolute path a consumer's `@astram/migrate` setup merges in.
 var migrations_dir_js_1 = require("./migrations-dir.js");
@@ -127,6 +127,30 @@ Object.defineProperty(exports, "SHIELD_CLOCK", { enumerable: true, get: function
 var mariadb_record_rule_adapter_js_1 = require("./authz/mariadb-record-rule-adapter.js");
 Object.defineProperty(exports, "MariaDbRecordPermissionRuleAdapter", { enumerable: true, get: function () { return mariadb_record_rule_adapter_js_1.MariaDbRecordPermissionRuleAdapter; } });
 Object.defineProperty(exports, "SHIELD_RECORD_RULE_PORT", { enumerable: true, get: function () { return mariadb_record_rule_adapter_js_1.SHIELD_RECORD_RULE_PORT; } });
+// The guided-policy AUTHOR store (ADR-0003 / design Task 0.3): the concrete
+// `PolicyStore` (core admin port) over the SAME `record_permission_rule` table the
+// rule adapter enforces — author-what-enforces. Persists a `GuidedPolicy`'s N
+// AND-composed conditions as N rows sharing one `rpr_policy_uuid` group id (the read
+// adapter AND-groups by it). `everyone` subject (v1 mapping); canonical operator
+// names; parameterized SQL; no hard-coded UUIDs. NOT wired into buildRecordAuthorization
+// here — the admin authoring surface (Phase 5) consumes it.
+var mariadb_policy_store_js_1 = require("./authz/mariadb-policy-store.js");
+Object.defineProperty(exports, "MariaDbPolicyStore", { enumerable: true, get: function () { return mariadb_policy_store_js_1.MariaDbPolicyStore; } });
+Object.defineProperty(exports, "SHIELD_POLICY_STORE", { enumerable: true, get: function () { return mariadb_policy_store_js_1.SHIELD_POLICY_STORE; } });
+// The LIST-SCOPE port adapter + the ScopeSpec→SQL translator (ADR-0003 / ADR-0005 list
+// form / Task 2.1). The adapter ({@link MariaDbListScopeAdapter}, `ListScopePort`) projects
+// the SAME `record_permission_rule` rows the rule adapter enforces into abstract allow/deny
+// {@link ScopeCondition} AND-groups; the PURE translator ({@link translateListScope}) turns
+// core's {@link ListScopeSpec} into a SAFE, parameterized WHERE fragment (every VALUE a `?`
+// bound param; ONLY registry-derived columns interpolated; unknown field ⇒ throw; negative
+// operators fail closed on NULL; deny-wins as `AND NOT (...)`). Phase 3 injects the fragment
+// into the engine's `list()`. Store outage ⇒ AuthorizationUnavailableError (never unbounded).
+var mariadb_list_scope_adapter_js_1 = require("./authz/mariadb-list-scope-adapter.js");
+Object.defineProperty(exports, "MariaDbListScopeAdapter", { enumerable: true, get: function () { return mariadb_list_scope_adapter_js_1.MariaDbListScopeAdapter; } });
+Object.defineProperty(exports, "SHIELD_LIST_SCOPE_PORT", { enumerable: true, get: function () { return mariadb_list_scope_adapter_js_1.SHIELD_LIST_SCOPE_PORT; } });
+var list_scope_sql_js_1 = require("./authz/list-scope-sql.js");
+Object.defineProperty(exports, "translateListScope", { enumerable: true, get: function () { return list_scope_sql_js_1.translateListScope; } });
+Object.defineProperty(exports, "UnknownScopeFieldError", { enumerable: true, get: function () { return list_scope_sql_js_1.UnknownScopeFieldError; } });
 // The per-record SHARE adapter (ADR-0003 / design §6): the concrete `RecordSharePort` over
 // the `record_share` table. Answers `hasShare` (user- OR role-granted shares, exact-or-`*`
 // action). No share ⇒ false; store outage ⇒ AuthorizationUnavailableError. Injected into
@@ -196,6 +220,13 @@ Object.defineProperty(exports, "SHIELD_OPERATION_AUTHORITY_PORT", { enumerable:
 // enforcement-only path core-free.
 var wire_record_authorization_js_1 = require("./authz/wire-record-authorization.js");
 Object.defineProperty(exports, "buildRecordAuthorization", { enumerable: true, get: function () { return wire_record_authorization_js_1.buildRecordAuthorization; } });
+// The LIST-FORM sibling (Task 2.2): the engine-facing `ListScopeFn` the module wiring hands
+// to the engine's `list()` (Task 3.1). `buildListScopeFn` is a SEPARATE factory (Option A)
+// that takes the SAME `RecordAuthorizationInputs` and constructs its `MariaDbListScopeAdapter`
+// over the SAME un-overridable `inputs.pool` — the adapter is NOT a field of the inputs, so a
+// consumer cannot inject a fail-open scope port. Fail-closed: a transient throw PROPAGATES.
+var wire_record_authorization_js_2 = require("./authz/wire-record-authorization.js");
+Object.defineProperty(exports, "buildListScopeFn", { enumerable: true, get: function () { return wire_record_authorization_js_2.buildListScopeFn; } });
 // Boot infrastructure (ADR-0018 connection-pool budget assertion). `BootModule`
 // itself is NOT exported — it is composed internally by `ShieldModule.forRoot()`.
 var boot_sequence_js_1 = require("./boot/boot-sequence.js");
@@ -279,6 +310,8 @@ Object.defineProperty(exports, "resolveTotpVerifier", { enumerable: true, get: f
 Object.defineProperty(exports, "hmacSha1", { enumerable: true, get: function () { return auth_module_js_2.hmacSha1; } });
 var tokens_js_3 = require("./auth/tokens.js");
 Object.defineProperty(exports, "SHIELD_SESSION_FACTS_PROJECTOR", { enumerable: true, get: function () { return tokens_js_3.SHIELD_SESSION_FACTS_PROJECTOR; } });
+var tokens_js_4 = require("./auth/tokens.js");
+Object.defineProperty(exports, "SHIELD_SCOPE_SUBTREE_RESOLVER", { enumerable: true, get: function () { return tokens_js_4.SHIELD_SCOPE_SUBTREE_RESOLVER; } });
 // The framework-owned `/auth/*` HTTP controller (Team C) + its pending-MFA store.
 // The controller CONSUMES SHIELD_AUTHENTICATOR / SHIELD_SESSION_AUTHORITY and the
 // PendingMfaStore. It is EXPORTED so AuthModule (Team B) / the integration owner
@@ -301,3 +334,14 @@ Object.defineProperty(exports, "generateRecoveryCodes", { enumerable: true, get:
 // later). Registered by AuthModule alongside AuthController under `auth: true`.
 var account_controller_js_1 = require("./auth/account.controller.js");
 Object.defineProperty(exports, "AccountController", { enumerable: true, get: function () { return account_controller_js_1.AccountController; } });
+// The PURE scope-closure builder (ADR-0027 / Phase 1 Task 1.1 of the scoped-hierarchy
+// tenancy program): turns a node forest's parent edges into the flat ancestor/descendant/
+// depth rows the `shield_authz.scope_closure` table stores. No I/O — the Task 1.2
+// reconciler is the one that calls this against real edges and writes the rows back.
+// `ScopeCycleError` / `ScopeDepthError` / `ScopeUnknownParentError` are the fail-loud
+// exceptions a caller (the reconciler) must handle as data-corruption signals, never swallow.
+var closure_builder_js_1 = require("./scope/closure-builder.js");
+Object.defineProperty(exports, "buildClosureRows", { enumerable: true, get: function () { return closure_builder_js_1.buildClosureRows; } });
+Object.defineProperty(exports, "ScopeCycleError", { enumerable: true, get: function () { return closure_builder_js_1.ScopeCycleError; } });
+Object.defineProperty(exports, "ScopeDepthError", { enumerable: true, get: function () { return closure_builder_js_1.ScopeDepthError; } });
+Object.defineProperty(exports, "ScopeUnknownParentError", { enumerable: true, get: function () { return closure_builder_js_1.ScopeUnknownParentError; } });

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":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAOnF,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQvE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAC;AACvF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACtF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AACpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAKzE,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAYxE,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,yBAAyB,EAAE,CAAC;AAIrC,YAAY,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAC;AAyFvF;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IACnD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,yBAAyB,CAAC;IACzD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IACvC;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,0FAA0F;IAC1F,QAAQ,CAAC,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtD;;;;;;;;OAQG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IACvD;;;;;;;;OAQG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IACrD;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD;AAED,yEAAyE;AACzE,MAAM,WAAW,wBAAwB;IACvC,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACrC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,CACnB,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,KACxB,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;IACxD,gDAAgD;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IACvC;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,2FAA2F;IAC3F,QAAQ,CAAC,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtD;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IACvD;;;;OAIG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IACrD;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAEa,YAAY;IACvB,6DAA6D;IAC7D,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,mBAAwB,GAAG,aAAa;IA6FhE;;;;;;;;;OASG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,wBAAwB,GAAG,aAAa;CAiGtE"}

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/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;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAK1F,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,mBAAmB,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAK9E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CAiClF;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,mBAAmB,EAAE,OAAO,EAC5B,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAM3B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,mBAAmB,EAAE,OAAO,EAC5B,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GAAG,IAAI,CAAC,CAQxE"}

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

@@ -44,9 +44,21 @@ 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,

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/scope/closure-builder.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `buildClosureRows` — the PURE, data-foundation half of Task 1.1 (Phase 1 of the
+ * scoped-hierarchy tenancy program). Turns a node forest's parent edges into the flat
+ * ancestor/descendant/depth rows the `shield_authz.scope_closure` table stores, so any
+ * subtree query (`WHERE ancestor_uuid = N`) or ancestry query (`WHERE descendant_uuid = N`)
+ * is a flat, indexed lookup — NEVER a recursive walk on any request-serving query path.
+ *
+ * This module does NO I/O. The Task 1.2 reconciler is the one that calls this against real
+ * node edges (read from the DB) and writes the resulting rows back to `scope_closure`; this
+ * file only computes the correct row set from an in-memory edge list.
+ *
+ * ── SEMANTICS ───────────────────────────────────────────────────────────────────────────
+ *   • EVERY node gets a self-row `{ancestor: n, descendant: n, depth: 0}` — including a
+ *     root (parent === null) and including a node with NO children.
+ *   • For each node, walking UP its parent chain, every ancestor `a` at chain-distance `d`
+ *     (1-based: the immediate parent is depth 1, the grandparent depth 2, ...) emits
+ *     `{ancestor: a, descendant: n, depth: d}`.
+ *   • A FLAT set (every node's parent is `null`) therefore degenerates to SELF-ROWS ONLY —
+ *     this is the non-breaking case: a flat deployment (no hierarchy configured yet) is
+ *     just a depth-1 forest of roots, and every existing single-tenant scope check
+ *     (`ancestor_uuid = descendant_uuid = tenant`) continues to hold.
+ *   • A FOREST (multiple independent root trees) computes each branch independently — no
+ *     cross-tree rows are ever emitted.
+ *
+ * ── FAILURE MODES (all fail LOUD — a closure computed over bad data must never silently
+ *    produce a wrong, over- or under-scoped row set; that would be a tenant-isolation bug) ─
+ *   • CYCLE (a node reachable from itself via parent edges, direct `A→A` or indirect
+ *     `A→B→A`): throws {@link ScopeCycleError}. Detected by tracking the in-progress walk
+ *     set per node — if the walk revisits a node already on the CURRENT path, it's a cycle.
+ *   • DEPTH EXCEEDED (a parent chain longer than `opts.maxDepth`, default 32 — a sane bound
+ *     for any real org hierarchy): throws {@link ScopeDepthError}. Guards against a
+ *     pathological or malformed edge set turning this into an unbounded walk.
+ *   • UNKNOWN PARENT (a node's `parent` id doesn't reference any node in the SAME edge set):
+ *     throws a plain `Error` — an orphaned edge is a data error (e.g. the parent was deleted
+ *     without re-parenting children), never a silent skip that would misplace a subtree.
+ *   • Empty input → empty output (no throw) — the vacuous case.
+ *
+ * ── DETERMINISM: output order is not semantically meaningful (the caller writes rows to a
+ *    PK-indexed table), but rows are sorted (ancestor, then descendant, then depth) so tests
+ *    and diffs are stable.
+ *
+ * ── COMPLEXITY: O(nodes × depth) — for each node, one iterative (non-recursive) walk up its
+ *    parent chain, bounded by `maxDepth`. No recursion, so no call-stack depth risk either.
+ */
+/** One parent edge in the node forest: `parent === null` marks a root. */
+export interface ScopeEdge {
+    readonly node: string;
+    readonly parent: string | null;
+}
+/** One row of the computed transitive closure. */
+export interface ClosureRow {
+    readonly ancestor: string;
+    readonly descendant: string;
+    readonly depth: number;
+}
+/** A node's parent chain revisits a node already on the walk — the edge set has a cycle. */
+export declare class ScopeCycleError extends Error {
+    constructor(node: string);
+}
+/** A node's parent chain exceeds the configured (or default) maximum depth. */
+export declare class ScopeDepthError extends Error {
+    constructor(node: string, maxDepth: number);
+}
+/** A node's `parent` id does not reference any node present in the same edge set. */
+export declare class ScopeUnknownParentError extends Error {
+    constructor(node: string, parent: string);
+}
+/**
+ * Compute the transitive closure of a node forest from its parent edges.
+ * Pure — no I/O. See the file header for full semantics and failure modes.
+ */
+export declare function buildClosureRows(edges: readonly ScopeEdge[], opts?: {
+    maxDepth?: number;
+}): ClosureRow[];
+//# sourceMappingURL=closure-builder.d.ts.map

package/dist/scope/closure-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closure-builder.d.ts","sourceRoot":"","sources":["../../src/scope/closure-builder.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,4FAA4F;AAC5F,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,IAAI,EAAE,MAAM;CAQzB;AAED,+EAA+E;AAC/E,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAS3C;AAED,qFAAqF;AACrF,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CASzC;AAKD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3B,UAAU,EAAE,CA2Dd"}