@astram/guard 0.5.1 → 0.6.0

package/dist/auth/dto.d.ts

@@ -52,6 +52,27 @@ export interface SessionTokensView {
     readonly accessToken: string;
     readonly refreshToken: string;
 }
+/**
+ * The caller's own coarse authorization-fact projection — the EXACT shape
+ * `GET /identity/auth-facts` returns. Inlined into the login / mfa success body
+ * (ADDITIVE, optional) so the frontend can seed its permission-gated nav from
+ * the login result in ONE round-trip, instead of a second `/identity/auth-facts`
+ * fetch after login resolves. Carries `permissionsVersion` so the SDK's
+ * version-staleness contract still holds: a later poke detects a bump and
+ * refetches. A single ALLOWED fact per granted key (an absent fact is the
+ * fail-closed deny). Carries NO secret.
+ */
+export interface AuthFactsView {
+    readonly principalId: string;
+    readonly facts: ReadonlyArray<{
+        readonly action: string;
+        readonly allowed: boolean;
+        readonly resource?: string;
+        readonly reasonCode?: string;
+    }>;
+    readonly projectedAt: number;
+    readonly permissionsVersion?: number;
+}
 /** A successful session establishment payload (login / mfa / refresh success). */
 export interface SessionSuccess {
     readonly session: SessionView;
@@ -64,6 +85,17 @@ export interface SessionSuccess {
      * the enforced re-enroll flow. Carries NO secret — a pure signal flag.
      */
     readonly mfaRecoveryUsed?: boolean;
+    /**
+     * The caller's own auth-facts projection (same shape as `/identity/auth-facts`),
+     * inlined so the permission-gated nav is ready the instant login returns — no
+     * second round-trip on the login path. ADDITIVE + OPTIONAL: absent when the
+     * projector isn't wired or a projection couldn't be computed (best-effort — a
+     * projection failure NEVER fails the login); the frontend then falls back to
+     * its separate `/identity/auth-facts` fetch (graceful degradation for an older
+     * server too). Attached on login + mfa success; NEVER on the mfa-CHALLENGE
+     * branch (no session yet ⇒ no facts).
+     */
+    readonly authFacts?: AuthFactsView;
 }
 /** `POST /auth/login` request body. */
 export interface LoginRequest {

package/dist/auth/dto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../../src/auth/dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC9D,oBAAoB;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oBAAoB;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAMD,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,oBAAoB,CAAC;AAMlE;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC;IAC1C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC;AAMzC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC;AAM7C;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACxB"}
+{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../../src/auth/dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC9D,oBAAoB;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oBAAoB;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC,CAAC;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;CACpC;AAMD,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,oBAAoB,CAAC;AAMlE;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC;IAC1C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC;AAMzC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC;AAM7C;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACxB"}

package/dist/auth/ports/membership-checker.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The `MembershipChecker` PORT (Task 5.2 of the scoped-hierarchy tenancy program,
+ * ADR-0027 / ADR-0024) — the OPT-IN seam the auth surface uses to GATE a SCOPE-SWITCH:
+ * before a principal may re-bind its session to act under a different active node, the
+ * framework MUST confirm the principal actually HOLDS a binding at that node (an active
+ * `company_membership`). This is the fail-closed gate that stops a principal switching
+ * to a FOREIGN node it is not bound at (which would be a fail-open tenancy hole).
+ *
+ * ── ONE QUESTION ────────────────────────────────────────────────────────────────────
+ * `hasActiveMembership(principalId, nodeId)` → does `principalId` hold an ACTIVE
+ * membership at `nodeId`? The identity impl answers with a single existence read over
+ * `shield_app.company_membership` (`cm_is_active = 1 AND cm_status = 'active'`).
+ *
+ * ── LAYERING ────────────────────────────────────────────────────────────────────────
+ * The PORT is DEFINED here in `@astram/guard`; the IMPLEMENTATION lives in
+ * `@astram/identity` (`DbMembershipChecker`, which owns the app schema + the
+ * `company_membership` table). The consumer injects an instance through
+ * `ShieldModule.forRoot({ membershipChecker })` — the sanctioned direction (port in
+ * guard, impl in identity). Guard never imports identity. Mirrors `ScopeSubtreeResolver`.
+ *
+ * ── FAIL-CLOSED (the security point) ────────────────────────────────────────────────
+ * A scope-switch is DENIED unless the checker AFFIRMATIVELY returns `true`:
+ *   - ABSENT (no checker wired) → the switch fails closed (cannot verify the binding →
+ *     do not grant it). An unwired checker NEVER allows a switch.
+ *   - `false` (no active membership at the target) → DENIED (403). The old binding stands.
+ *   - a THROW (store outage) → treated as DENY (cannot verify → fail closed).
+ * The framework NEVER trusts `targetNodeId` from the client without this affirmative
+ * binding check — that would be the fail-open hole (a principal switching to a node it
+ * isn't bound at, inheriting that node's subtree + authority).
+ */
+export interface MembershipChecker {
+    /**
+     * Does `principalId` hold an ACTIVE membership at `nodeId` (an active
+     * `company_membership` — `cm_is_active = 1 AND cm_status = 'active'`)? Returns `true`
+     * ONLY when such a binding exists. The scope-switch gate treats anything but a
+     * `true` (a `false`, or a thrown store outage the caller swallows) as a DENY —
+     * fail-closed, never fail-open.
+     */
+    hasActiveMembership(principalId: string, nodeId: string): Promise<boolean>;
+}
+//# sourceMappingURL=membership-checker.d.ts.map

package/dist/auth/ports/membership-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"membership-checker.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/membership-checker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5E"}

package/dist/auth/ports/membership-checker.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * The `MembershipChecker` PORT (Task 5.2 of the scoped-hierarchy tenancy program,
+ * ADR-0027 / ADR-0024) — the OPT-IN seam the auth surface uses to GATE a SCOPE-SWITCH:
+ * before a principal may re-bind its session to act under a different active node, the
+ * framework MUST confirm the principal actually HOLDS a binding at that node (an active
+ * `company_membership`). This is the fail-closed gate that stops a principal switching
+ * to a FOREIGN node it is not bound at (which would be a fail-open tenancy hole).
+ *
+ * ── ONE QUESTION ────────────────────────────────────────────────────────────────────
+ * `hasActiveMembership(principalId, nodeId)` → does `principalId` hold an ACTIVE
+ * membership at `nodeId`? The identity impl answers with a single existence read over
+ * `shield_app.company_membership` (`cm_is_active = 1 AND cm_status = 'active'`).
+ *
+ * ── LAYERING ────────────────────────────────────────────────────────────────────────
+ * The PORT is DEFINED here in `@astram/guard`; the IMPLEMENTATION lives in
+ * `@astram/identity` (`DbMembershipChecker`, which owns the app schema + the
+ * `company_membership` table). The consumer injects an instance through
+ * `ShieldModule.forRoot({ membershipChecker })` — the sanctioned direction (port in
+ * guard, impl in identity). Guard never imports identity. Mirrors `ScopeSubtreeResolver`.
+ *
+ * ── FAIL-CLOSED (the security point) ────────────────────────────────────────────────
+ * A scope-switch is DENIED unless the checker AFFIRMATIVELY returns `true`:
+ *   - ABSENT (no checker wired) → the switch fails closed (cannot verify the binding →
+ *     do not grant it). An unwired checker NEVER allows a switch.
+ *   - `false` (no active membership at the target) → DENIED (403). The old binding stands.
+ *   - a THROW (store outage) → treated as DENY (cannot verify → fail closed).
+ * The framework NEVER trusts `targetNodeId` from the client without this affirmative
+ * binding check — that would be the fail-open hole (a principal switching to a node it
+ * isn't bound at, inheriting that node's subtree + authority).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/ports/scope-subtree-resolver.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The `ScopeSubtreeResolver` PORT (Task 2.2 of the scoped-hierarchy tenancy program,
+ * ADR-0027 / ADR-0024) — the OPT-IN seam the auth surface uses to resolve a principal's
+ * ACTIVE-SCOPE SUBTREE (its active scope node + all descendants) ONCE at LOGIN time, so
+ * the resolved set can be cached on the session binding and the per-request tenant gate
+ * reads it from the binding with ZERO extra DB (the parity guarantee).
+ *
+ * ── WHY A DEDICATED PORT (a sibling to `SessionFactsProjector`, not an extension) ─────
+ * The subtree is a TENANCY-ISOLATION concern (the reach of a principal's active scope),
+ * distinct from `SessionFactsProjector`'s PERFORMANCE opt-in (caching coarse grants to
+ * skip a gate-5 DB reload). They are wired INDEPENDENTLY: a deployment may want the real
+ * hierarchical subtree without turning on facts-caching (the reference consumer wires no
+ * facts projector today). One tiny single-responsibility interface, its own fail-safe
+ * semantics — no coupling of tenancy correctness to a caching opt-in.
+ *
+ * ── LAYERING ──────────────────────────────────────────────────────────────────────
+ * The PORT is DEFINED here in `@astram/guard`; the IMPLEMENTATION lives in
+ * `@astram/identity` (`DbScopeSubtreeResolver`, which owns the app/authz schemas + the
+ * `scope_closure` the subtree is read from). The consumer injects an instance through
+ * `ShieldModule.forRoot({ scopeSubtreeResolver })` — the sanctioned direction (port in
+ * guard, impl in identity). Guard never imports identity.
+ *
+ * ── OPT-IN / ADDITIVE / FAIL-SAFE ──────────────────────────────────────────────────
+ * ABSENT (the default): the auth controller omits `scopeSubtreeNodeIds` when binding the
+ * session → the per-request `principalFromClaims` falls back to `[tenantId]` (the self
+ * node) = today's exact flat self-tenant isolation (non-widening).
+ * PRESENT: the controller calls `resolveSubtree(activeScopeNodeId)` at login and stores
+ * the returned set on the binding, so the per-request tenant gate reads the real subtree.
+ * A resolver that THROWS is swallowed best-effort at login (→ subtree omitted → self-node
+ * fallback): a resolution failure NEVER fails the login and NEVER widens reach. An EMPTY
+ * result is likewise treated as "omit" → self-node fallback (non-widening).
+ *
+ * ── ROOT ──────────────────────────────────────────────────────────────────────────
+ * The subtree is resolved the SAME way for every principal; a root's extra cross-tree span
+ * comes from `isRoot` in the tenant gate (authoritative), NOT from a widened subtree here.
+ */
+export interface ScopeSubtreeResolver {
+    /**
+     * Resolve the active-scope subtree for `activeScopeNodeId` — that node plus all its
+     * descendants — from the scope closure, at login time (ADR-0027). Returns the set of node
+     * ids to cache on the session binding. Implementations return `[activeScopeNodeId]` (the
+     * self-node, non-widening) when the closure has no rows for the node yet (pre-first-reconcile),
+     * and THROW on a store outage (the auth controller swallows it best-effort → the binding
+     * omits the subtree → the per-request path falls back to the self-node).
+     */
+    resolveSubtree(activeScopeNodeId: string): Promise<readonly string[]>;
+}
+//# sourceMappingURL=scope-subtree-resolver.d.ts.map

package/dist/auth/ports/scope-subtree-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-subtree-resolver.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/scope-subtree-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,cAAc,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CACvE"}

package/dist/auth/ports/scope-subtree-resolver.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * The `ScopeSubtreeResolver` PORT (Task 2.2 of the scoped-hierarchy tenancy program,
+ * ADR-0027 / ADR-0024) — the OPT-IN seam the auth surface uses to resolve a principal's
+ * ACTIVE-SCOPE SUBTREE (its active scope node + all descendants) ONCE at LOGIN time, so
+ * the resolved set can be cached on the session binding and the per-request tenant gate
+ * reads it from the binding with ZERO extra DB (the parity guarantee).
+ *
+ * ── WHY A DEDICATED PORT (a sibling to `SessionFactsProjector`, not an extension) ─────
+ * The subtree is a TENANCY-ISOLATION concern (the reach of a principal's active scope),
+ * distinct from `SessionFactsProjector`'s PERFORMANCE opt-in (caching coarse grants to
+ * skip a gate-5 DB reload). They are wired INDEPENDENTLY: a deployment may want the real
+ * hierarchical subtree without turning on facts-caching (the reference consumer wires no
+ * facts projector today). One tiny single-responsibility interface, its own fail-safe
+ * semantics — no coupling of tenancy correctness to a caching opt-in.
+ *
+ * ── LAYERING ──────────────────────────────────────────────────────────────────────
+ * The PORT is DEFINED here in `@astram/guard`; the IMPLEMENTATION lives in
+ * `@astram/identity` (`DbScopeSubtreeResolver`, which owns the app/authz schemas + the
+ * `scope_closure` the subtree is read from). The consumer injects an instance through
+ * `ShieldModule.forRoot({ scopeSubtreeResolver })` — the sanctioned direction (port in
+ * guard, impl in identity). Guard never imports identity.
+ *
+ * ── OPT-IN / ADDITIVE / FAIL-SAFE ──────────────────────────────────────────────────
+ * ABSENT (the default): the auth controller omits `scopeSubtreeNodeIds` when binding the
+ * session → the per-request `principalFromClaims` falls back to `[tenantId]` (the self
+ * node) = today's exact flat self-tenant isolation (non-widening).
+ * PRESENT: the controller calls `resolveSubtree(activeScopeNodeId)` at login and stores
+ * the returned set on the binding, so the per-request tenant gate reads the real subtree.
+ * A resolver that THROWS is swallowed best-effort at login (→ subtree omitted → self-node
+ * fallback): a resolution failure NEVER fails the login and NEVER widens reach. An EMPTY
+ * result is likewise treated as "omit" → self-node fallback (non-widening).
+ *
+ * ── ROOT ──────────────────────────────────────────────────────────────────────────
+ * The subtree is resolved the SAME way for every principal; a root's extra cross-tree span
+ * comes from `isRoot` in the tenant gate (authoritative), NOT from a widened subtree here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/tokens.d.ts

@@ -185,6 +185,31 @@ export declare const SHIELD_ROOT_IDS: unique symbol;
  * `auth: true`.
  */
 export declare const SHIELD_SESSION_FACTS_PROJECTOR: unique symbol;
+/**
+ * OPTIONAL {@link import('./ports/scope-subtree-resolver.js').ScopeSubtreeResolver} — the
+ * Task 2.2 (ADR-0027 / ADR-0024) active-scope-subtree seam. Threaded through
+ * `ShieldModule.forRoot({ scopeSubtreeResolver })` → `AuthModule.forRoot`, `@Optional()`
+ * (bound `null` when absent). When PRESENT, the auth controller calls
+ * `resolveSubtree(activeScopeNodeId)` ONCE at login and caches the returned node-id set on
+ * the session binding (`scopeSubtreeNodeIds`), so the per-request tenant gate reads the real
+ * closure-resolved subtree from the binding with ZERO extra DB (the parity guarantee). ABSENT
+ * → the controller omits `scopeSubtreeNodeIds` → the per-request path falls back to the
+ * self-node `[tenantId]` (today's flat isolation, non-widening). Fail-safe: a resolver that
+ * throws NEVER fails login. Purely additive + opt-in. Only consulted under `auth: true`.
+ */
+export declare const SHIELD_SCOPE_SUBTREE_RESOLVER: unique symbol;
+/**
+ * OPTIONAL {@link import('./ports/membership-checker.js').MembershipChecker} — the Task 5.2
+ * (ADR-0027 / ADR-0024) SCOPE-SWITCH gate seam. Threaded through
+ * `ShieldModule.forRoot({ membershipChecker })` → `AuthModule.forRoot`, `@Optional()` (bound
+ * `null` when absent). When PRESENT, `POST /auth/scope-switch` calls
+ * `hasActiveMembership(principalId, targetNodeId)` BEFORE re-binding the session to the new
+ * active node — a principal may only switch to a node it HOLDS an active membership at. ABSENT
+ * (or a `false`/thrown result) → the switch is DENIED (fail-closed: cannot verify the binding →
+ * do not grant it; `targetNodeId` is NEVER trusted without this affirmative check). Only
+ * consulted under `auth: true`. Mirrors {@link SHIELD_SCOPE_SUBTREE_RESOLVER}'s wiring.
+ */
+export declare const SHIELD_MEMBERSHIP_CHECKER: unique symbol;
 /**
  * The password-login {@link AttemptLimiter} (spec §5 / IdP-hardening H1) — keyed
  * `login:<identityHint>`, default 10 failures / 15-min window. Consumed at the TOP

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

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/auth/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,eAA2B,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,YAAY,eAAyB,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAW3E;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,eAAmC,CAAC;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,eAA0C,CAAC;AAErF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,eAA2C,CAAC;AAUvF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/auth/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,eAA2B,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,YAAY,eAAyB,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAW3E;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,eAAmC,CAAC;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,eAA0C,CAAC;AAErF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,eAA2C,CAAC;AAEvF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,eAA0C,CAAC;AAErF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,eAAsC,CAAC;AAU7E;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC"}

package/dist/auth/tokens.js

@@ -23,7 +23,7 @@
  * ADR-0003: no framework/DB/crypto imports here — just Symbols (+ one re-export).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SHIELD_PERMISSION_FACTS = exports.SHIELD_RESET_LIMITER = exports.SHIELD_FORGOT_HINT_LIMITER = exports.SHIELD_FORGOT_LIMITER = exports.SHIELD_RECOVERY_LIMITER = exports.SHIELD_LOGIN_LIMITER = exports.SHIELD_SESSION_FACTS_PROJECTOR = exports.SHIELD_ROOT_IDS = exports.SHIELD_TOTP_VERIFIER_OVERRIDE = exports.SHIELD_TOTP_VERIFIER = exports.SHIELD_RESET_LINK_BASE_URL = exports.SHIELD_SESSION_SWEEPER = exports.SHIELD_MFA_DEVICE_STORE = exports.SHIELD_AUDIT_SINK = 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.SHIELD_PASSWORD_HASHER = void 0;
+exports.SHIELD_PERMISSION_FACTS = exports.SHIELD_RESET_LIMITER = exports.SHIELD_FORGOT_HINT_LIMITER = exports.SHIELD_FORGOT_LIMITER = exports.SHIELD_RECOVERY_LIMITER = exports.SHIELD_LOGIN_LIMITER = exports.SHIELD_MEMBERSHIP_CHECKER = exports.SHIELD_SCOPE_SUBTREE_RESOLVER = exports.SHIELD_SESSION_FACTS_PROJECTOR = exports.SHIELD_ROOT_IDS = exports.SHIELD_TOTP_VERIFIER_OVERRIDE = exports.SHIELD_TOTP_VERIFIER = exports.SHIELD_RESET_LINK_BASE_URL = exports.SHIELD_SESSION_SWEEPER = exports.SHIELD_MFA_DEVICE_STORE = exports.SHIELD_AUDIT_SINK = 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.SHIELD_PASSWORD_HASHER = void 0;
 var argon2id_password_hasher_js_1 = require("../authentication/argon2id-password-hasher.js");
 Object.defineProperty(exports, "SHIELD_PASSWORD_HASHER", { enumerable: true, get: function () { return argon2id_password_hasher_js_1.SHIELD_PASSWORD_HASHER; } });
 /**
@@ -197,6 +197,31 @@ exports.SHIELD_ROOT_IDS = Symbol('SHIELD_ROOT_IDS');
  * `auth: true`.
  */
 exports.SHIELD_SESSION_FACTS_PROJECTOR = Symbol('SHIELD_SESSION_FACTS_PROJECTOR');
+/**
+ * OPTIONAL {@link import('./ports/scope-subtree-resolver.js').ScopeSubtreeResolver} — the
+ * Task 2.2 (ADR-0027 / ADR-0024) active-scope-subtree seam. Threaded through
+ * `ShieldModule.forRoot({ scopeSubtreeResolver })` → `AuthModule.forRoot`, `@Optional()`
+ * (bound `null` when absent). When PRESENT, the auth controller calls
+ * `resolveSubtree(activeScopeNodeId)` ONCE at login and caches the returned node-id set on
+ * the session binding (`scopeSubtreeNodeIds`), so the per-request tenant gate reads the real
+ * closure-resolved subtree from the binding with ZERO extra DB (the parity guarantee). ABSENT
+ * → the controller omits `scopeSubtreeNodeIds` → the per-request path falls back to the
+ * self-node `[tenantId]` (today's flat isolation, non-widening). Fail-safe: a resolver that
+ * throws NEVER fails login. Purely additive + opt-in. Only consulted under `auth: true`.
+ */
+exports.SHIELD_SCOPE_SUBTREE_RESOLVER = Symbol('SHIELD_SCOPE_SUBTREE_RESOLVER');
+/**
+ * OPTIONAL {@link import('./ports/membership-checker.js').MembershipChecker} — the Task 5.2
+ * (ADR-0027 / ADR-0024) SCOPE-SWITCH gate seam. Threaded through
+ * `ShieldModule.forRoot({ membershipChecker })` → `AuthModule.forRoot`, `@Optional()` (bound
+ * `null` when absent). When PRESENT, `POST /auth/scope-switch` calls
+ * `hasActiveMembership(principalId, targetNodeId)` BEFORE re-binding the session to the new
+ * active node — a principal may only switch to a node it HOLDS an active membership at. ABSENT
+ * (or a `false`/thrown result) → the switch is DENIED (fail-closed: cannot verify the binding →
+ * do not grant it; `targetNodeId` is NEVER trusted without this affirmative check). Only
+ * consulted under `auth: true`. Mirrors {@link SHIELD_SCOPE_SUBTREE_RESOLVER}'s wiring.
+ */
+exports.SHIELD_MEMBERSHIP_CHECKER = Symbol('SHIELD_MEMBERSHIP_CHECKER');
 // ---------------------------------------------------------------------------
 // Rate-limit seams (anti-brute-force, spec §5) — ONE `AttemptLimiter` class
 // (Redis-backed), provided as TWO instances with independent thresholds under

package/dist/authentication/mariadb-profile-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mariadb-profile-writer.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-profile-writer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAOtE,qBAAa,oBAAqB,YAAW,aAAa;IAE5C,OAAO,CAAC,QAAQ,CAAC,IAAI;IADjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBACrB,IAAI,EAAE,IAAI;IAIjC,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC;CA0B3G"}
+{"version":3,"file":"mariadb-profile-writer.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-profile-writer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAOtE,qBAAa,oBAAqB,YAAW,aAAa;IAE5C,OAAO,CAAC,QAAQ,CAAC,IAAI;IADjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBACrB,IAAI,EAAE,IAAI;IAIjC,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAmC3G"}

package/dist/authentication/mariadb-profile-writer.js

@@ -27,7 +27,16 @@ class MariaDbProfileWriter {
         // Resolve the caller's active company so the re-read profile is tenant-correct.
         const active = (await this.pool.query("SELECT cm_company_uuid FROM `shield_app`.`company_membership` WHERE cm_user_uuid = ? AND cm_is_active = 1 AND cm_status = 'active' LIMIT 1", [principalId]));
         const tenantId = active[0]?.cm_company_uuid ?? '';
-        const profile = await this.resolver.resolve({ kind: 'user', id: principalId, tenantId, roleIds: [], isRoot: false });
+        const profile = await this.resolver.resolve({
+            kind: 'user',
+            id: principalId,
+            // Scope (ADR-0027) — INTERIM self-node default (Task 2.1): non-widening, = today's isolation.
+            activeScopeNodeId: tenantId,
+            scopeSubtreeNodeIds: [tenantId],
+            tenantId,
+            roleIds: [],
+            isRoot: false,
+        });
         if (profile === null)
             throw new Error('profile_unavailable'); // fail-closed: never a partial write result
         return profile;

package/dist/authz/list-scope-sql.d.ts

@@ -0,0 +1,125 @@
+/**
+ * `translateListScope` — the PURE, SECURITY-CRITICAL translator that turns core's
+ * abstract {@link ListScopeSpec} (Phase 1, `list-scope.ts`) into a SAFE, parameterized
+ * SQL WHERE fragment. Phase 3 injects the returned fragment into the engine's `list()`
+ * so a collection endpoint returns ONLY the rows `decide()` would allow — filtered IN
+ * the query (Invariant #8), never fetch-then-discard.
+ *
+ * ── THE SHAPE IT EMITS (mirrors the record-permit tier composition, `permit-tier.ts`):
+ *
+ *      <tenant-bound>  AND  ( <positive union> )  [ AND NOT ( <deny union> ) ]
+ *
+ *    • positive union = ownerBaseline OR policyAllow OR share OR crossTenant — a row is
+ *      INCLUDED if ANY term is true. NO positive term present ⇒ the union is `(FALSE)`
+ *      (fail-closed — never an empty `()` and never a `TRUE`).
+ *    • deny union     = policyDeny AND-groups OR'd, wrapped in `AND NOT (...)` so a row
+ *      matching ANY deny group is EXCLUDED even if a share/owner/allow would include it
+ *      (deny-wins is load-bearing).
+ *    • policyAllow / policyDeny are AND-GROUPS OR'd: each group is `( c1 AND c2 ... )`,
+ *      groups joined by ` OR `. Preserving the AND-within / OR-across grouping EXACTLY is
+ *      security-critical — flattening `(a AND b) OR (c)` into `a OR b OR c` over-widens.
+ *
+ * ── NO SQL INJECTION (the whole point): the ONLY tokens interpolated into the `sql`
+ *    string are PHYSICAL COLUMN identifiers resolved from the {@link ObjectType} registry
+ *    (via `columnOf`/`ownerColumn`/`uuidPkColumn`/`tenantColumnOf` from `@astram/engine` —
+ *    the guard→engine→core DAG makes that import legal), backtick-quoted. Every SPEC VALUE
+ *    is a `?` placeholder with the value pushed to `params` in emission order — NEVER
+ *    interpolated. An UNKNOWN field key (not registered on the type) is REJECTED (throws) —
+ *    a rule referencing an unregistered field is a misconfiguration, and emitting the raw
+ *    key as a column IS the injection hole (fail the read closed instead).
+ *
+ * ── FAIL-CLOSED OPERATORS (mirrors `mariadb-record-rule-adapter.ts`'s `conditionHolds`
+ *    so the SQL row set equals the per-record verdict, row-for-row):
+ *    • the NEGATIVE operators (`ne`/`not_in`/`not_contains`/`is_not_owner`) emit an
+ *      `IS NOT NULL` guard so a NULL column never wrongly matches (the Phase-0/0.4
+ *      widening bug in SQL form — `NULL <> ?` must not include the row).
+ *    • `is_owner`/`is_not_owner` additionally guard `<> ''` (an empty owner column must
+ *      never "match" an empty principal id) and compare to `principal.id`, NOT the
+ *      condition operand (the operand is ignored, exactly as `conditionHolds` does).
+ *    • `contains`/`not_contains` escape the LIKE metacharacters (`\ % _`) and use
+ *      `ESCAPE '\\'` (mirrors record-engine's search LIKE).
+ *    • an UNKNOWN operator falls to a defensive `FALSE` (fail-closed — never omit-and-widen,
+ *      never throw-open). The switch is over the closed {@link PolicyOperator} type, so this
+ *      is belt-and-braces.
+ *
+ * ── `$actor` TOKENS (mirrors `resolveValue`): a scalar-op value of `'$actor.id'` /
+ *    `'$actor.tenant'` resolves to the principal's id / tenant AS A BOUND PARAM (still `?`).
+ *    Inside an `in`/`not_in` SET the adapter does NOT resolve `$actor` — neither do we.
+ *
+ * ── `in`/`not_in` SERIALIZATION (the Phase-1 review's Low-1/Low-2 obligation): the value
+ *    may arrive as an ARRAY (`['us','eu']`) or a COMMA-STRING (`'us,eu'`); BOTH expand to
+ *    the SAME token list (split on `,`, trim) so the emitted `IN (?, ?)` matches the
+ *    adapter's `String(rpr_value).split(',')` membership test exactly.
+ *
+ * ── ROOT-UNBOUNDED: `tenantBound === 'root-unbounded'` emits NO tenant clause (root spans
+ *    tenants) AND OMITS the share + crossTenant terms — root's ownerBaseline is `{kind:'all'}`
+ *    ⇒ the union is `(TRUE)` (all rows), so share/crossTenant would be redundant (and share
+ *    needs a tenant value root does not carry). crossTenant is ALWAYS omitted in Task 2.1
+ *    (Phase 4 completes the real cross-tenant record set).
+ *
+ * ── `tenantSubtree` — the scoped-hierarchy tenant bound (ADR-0027). Core
+ *    (`ScopeTenantBound`) emits `{role:'tenantSubtree', nodeIds}` for every non-root list
+ *    (the generalization of the flat `tenantId` bound), where `nodeIds` is the PRE-EXPANDED
+ *    reachable subtree (`principal.scopeSubtreeNodeIds` — the active node + descendants,
+ *    resolved once at login and cached, Task 2.2). This translator emits a DIRECT membership:
+ *    `tenant_col IN (?, ...)` over those node ids — a row is visible when its tenant node is
+ *    IN the subtree. Every id is `?`-bound. It uses the SAME cached set the tenant GATE tests
+ *    membership against, so list ≡ decide holds BY CONSTRUCTION (no closure query at list time
+ *    → no divergence from a stale/absent `scope_closure` row, and no closure read on the list
+ *    hot path — the ADR-0024 parity guarantee). The subtree clause is ANDed with the positive
+ *    union + deny sections exactly like the flat `tenantId` case — NOT an early return. Fails
+ *    CLOSED (`{sql:'FALSE', params:[]}`) when the type has no tenant column (misconfiguration)
+ *    or when `nodeIds` is empty (no reachable scope) — never silently widen. Note:
+ *    `tenantSubtree` carries no single flat tenant value, so the share term (which needs one)
+ *    is naturally omitted here.
+ *
+ * PURE — no DB, no I/O. `translateListScope(spec, reg, principal) → { sql, params }`.
+ */
+import type { ListScopeSpec, ScopeCondition } from '@astram/core';
+import { type ObjectType } from '@astram/engine';
+/** The translated fragment: a boolean WHERE expression + its ordered bind params. */
+export interface TranslatedListScope {
+    /** A SQL boolean expression carrying ONLY `?` placeholders + backtick columns. */
+    readonly sql: string;
+    /** The bind values, in the exact order the `?` placeholders appear in `sql`. */
+    readonly params: unknown[];
+}
+/**
+ * The principal facts the translator needs to resolve `is_owner`/`is_not_owner` and
+ * `$actor.*` tokens — threaded EXPLICITLY (not read off the spec) so the translator's
+ * ownership/token resolution matches the adapter's `input.principal.id` /
+ * `input.principal.tenantId` exactly (Decision A in the task report).
+ */
+export interface ListScopePrincipal {
+    readonly principalId: string;
+    readonly principalTenantId: string;
+}
+/** Error thrown when a scope condition references a field the type does not register. */
+export declare class UnknownScopeFieldError extends Error {
+    constructor(typeKey: string, field: string);
+}
+/**
+ * Translate the full {@link ListScopeSpec} into a SAFE parameterized WHERE fragment.
+ *
+ * @param spec      the abstract visible-set description (from `computeListScope`).
+ * @param reg       the target object type registration (the ONLY source of columns).
+ * @param principal the actor's id + tenant, for `is_owner`/`$actor.*` resolution.
+ * @returns `{ sql, params }` — `sql` carries ONLY `?` + backtick columns; `params` the
+ *          bound values in `?`-order.
+ * @throws {@link UnknownScopeFieldError} if any condition names an unregistered field.
+ */
+export declare function translateListScope(spec: ListScopeSpec, reg: ObjectType, principal: ListScopePrincipal, opts?: {
+    schema?: string;
+    nowMs?: () => number;
+    /**
+     * The OWNING tenant's deny AND-groups (Task 4.2 — the fail-open leak fix). Applied ONLY to
+     * the cross-tenant branch (`crossTenantReach AND NOT (owningTenantDeny)`), mirroring
+     * `decide()`'s per-record evaluation at the resource's tenant. Empty/omitted ⇒ no
+     * owning-tenant deny (the common no-cross-grant path — the structure is then unchanged).
+     * The same-tenant deny stays `spec.policyDeny` (scoped to the actor's subtree). Global
+     * (NULL-tenant) deny rules appear in BOTH sets (the wiring fetches them for both tenant
+     * sets), so they exclude rows in either branch, exactly as `decide()` applies them.
+     */
+    owningTenantDeny?: readonly (readonly ScopeCondition[])[];
+}): TranslatedListScope;
+//# sourceMappingURL=list-scope-sql.d.ts.map

package/dist/authz/list-scope-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-scope-sql.d.ts","sourceRoot":"","sources":["../../src/authz/list-scope-sql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EAIf,MAAM,cAAc,CAAC;AACtB,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,gBAAgB,CAAC;AAKxB,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,yFAAyF;AACzF,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAO3C;AAmID;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,aAAa,EACnB,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,kBAAkB,EAC7B,IAAI,GAAE;IACJ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,SAAS,CAAC,SAAS,cAAc,EAAE,CAAC,EAAE,CAAC;CACtD,GACL,mBAAmB,CAoJrB"}