@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/security/authorizations/role-conferral.backend.utils.d.ts

@@ -0,0 +1,93 @@
+/**
+ * # Role conferral — ONE derivation of "which role keys confer authority X, in scope S"
+ *
+ * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — the shared derivation every authority floor
+ * measures its protected population with.
+ *
+ * ## The role-key vocabulary is genuinely OPEN, and closing it would be a defect
+ *
+ * Recorded here because the opposite is the obvious reading and was proposed as a finding: *"a
+ * membership's `roles` field is a free string, so an application-scope role value is storable in an
+ * organisation-scoped membership row."* Both halves of that are true. The conclusion — close the
+ * vocabulary — is not, and the evidence is in the framework's own contract:
+ *
+ *  - `RolesSchema` is `union([enum(CORE_APP_ROLES), enum(CORE_ORG_ROLES), z.string().min(1)])`, and
+ *    the third arm is the SUPPORTED feature, not an oversight: an application registers its own role
+ *    keys at startup through `initializeRolesWithCustom`, and `RolesConfigurationSchema` is a
+ *    `z.record(z.string(), RoleDefinitionSchema)`. A closed enum would delete custom roles.
+ *  - So "is this string a valid role key?" has no static answer. It has a RUNTIME answer, per
+ *    application, per scope — which is exactly what the role tables are.
+ *
+ * ## What IS closed, and where its one source lives
+ *
+ * The **scope partition**. Every role key belongs to exactly one `relatedPrimaryScope`, and
+ * `AuthorizationsBackendService.getRoleHierarchy(roleKey, scope)` is the single runtime source of
+ * that fact: it selects the APPLICATION table or the ORGANIZATIONS table and never consults both. A
+ * key unknown in the passed scope expands to the EMPTY chain, which is what makes an app-scope
+ * string written into an org-scoped membership row confer nothing — the safety comes from
+ * RESOLUTION, not from the field's type, and it must stay that way.
+ *
+ * ## What was duplicated, and is not any more
+ *
+ * The derivation BUILT ON that partition. `resolveSuperAdminConferringRoles` and
+ * `resolveOrganizationOwnerConferringRoles` were the same eleven lines twice, differing only in
+ * (table, scope, anchor) — each carrying its own paragraph re-establishing the partition argument
+ * above, in its own words, for its own reader. That is the shape `CLAUDE.md` asks to have one named
+ * runtime source for: not the role STRINGS, which cannot be closed, but the QUESTION asked of them.
+ *
+ * Two floors measure populations with it today ({@link resolveSuperAdminConferringRoles},
+ * {@link resolveOrganizationOwnerConferringRoles}); a third scope's floor is one call, not another
+ * copy.
+ *
+ * ## Why this module ships with NO test file of its own
+ *
+ * A direct suite was written and then DELETED, because measuring it showed every property it
+ * asserted was already covered — and its stated rationale was false. It claimed the floor suites
+ * "stub `getRoleHierarchy` as a function that IGNORES its scope"; both actually stub
+ * `(role, scope) => scope === <their own scope> ? table[role] : []`, and both tables already contain
+ * a CUSTOM, non-enum role key (`CUSTOM_PLATFORM_OWNER`, `CUSTOM_TENANT_PRINCIPAL`) reaching the
+ * anchor — so the open-vocabulary property is pinned too.
+ *
+ * Proven rather than assumed: binding the super-admin floor to `ORGANIZATIONS` scope instead of
+ * `APPLICATION` — the one regression the extraction newly makes possible — reddens THREE tests in
+ * `super-admin-floor.backend.utils.test.ts` on its own. The bindings are the coverage.
+ *
+ * So do not add a suite here to "cover the new module". If a THIRD binding appears, pin it in its
+ * own floor's suite the way these two are; that is where a wrong `scope` argument is observable.
+ */
+import type { ResourcePrimaryScope } from '@wildo-ai/saas-models';
+/**
+ * Every role key in `declaredRoleKeys` whose `inheritFrom` chain reaches `anchorRole`, within
+ * `scope` — i.e. every role whose holder passes a gate that requires `anchorRole`.
+ *
+ * ## Why the derivation is shaped this way
+ *
+ * **It mirrors the authorization layer's own test.** `authorize` admits a caller when
+ * `getRoleHierarchy(heldRole, scope).includes(requiredRole)`. Deriving the set the same way is what
+ * keeps a floor counting exactly the principals the gates would let through; an independently
+ * written membership test is how the two drift, and a floor that measures a different population
+ * than the gate protects is worse than no floor — it reports a healthy count for an unprotected
+ * scope.
+ *
+ * **The anchor is seeded unconditionally rather than discovered by the walk.** If an application's
+ * role table somehow omitted the anchor key, `roleHierarchyResolver` would return an empty chain for
+ * every key, the conferring set would be empty, and the floor would then measure a population that
+ * is empty BY CONSTRUCTION — refusing every removal forever while protecting nothing.
+ *
+ * **`scope` is passed to the resolver, never assumed.** That single argument is what carries the
+ * closed half of the vocabulary (see this module's header): the caller states which table the keys
+ * are to be read against, and a key belonging to the other table expands to nothing. A caller that
+ * passed the wrong scope would silently get `[anchorRole]` — the seed — which is the fail-CLOSED
+ * direction for a floor (it under-counts the protected population and so refuses more, never less).
+ *
+ * @param declaredRoleKeys the keys of the LIVE role table for `scope`. Live, because the effective
+ *   hierarchy is application-configurable and a statically-derived set would silently disagree with
+ *   the roles the authorization layer actually honours.
+ */
+export declare function resolveRolesConferringAnchor(params: {
+    readonly anchorRole: string;
+    readonly scope: ResourcePrimaryScope;
+    readonly declaredRoleKeys: readonly string[];
+    readonly roleHierarchyResolver: (roleKey: string, scope: ResourcePrimaryScope) => string[];
+}): string[];
+//# sourceMappingURL=role-conferral.backend.utils.d.ts.map

package/dist/esm/security/authorizations/role-conferral.backend.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-conferral.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/role-conferral.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,qBAAqB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,KAAK,MAAM,EAAE,CAAC;CAC5F,GAAG,MAAM,EAAE,CAUX"}

package/dist/esm/security/authorizations/role-conferral.backend.utils.js

@@ -0,0 +1,95 @@
+/**
+ * # Role conferral — ONE derivation of "which role keys confer authority X, in scope S"
+ *
+ * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — the shared derivation every authority floor
+ * measures its protected population with.
+ *
+ * ## The role-key vocabulary is genuinely OPEN, and closing it would be a defect
+ *
+ * Recorded here because the opposite is the obvious reading and was proposed as a finding: *"a
+ * membership's `roles` field is a free string, so an application-scope role value is storable in an
+ * organisation-scoped membership row."* Both halves of that are true. The conclusion — close the
+ * vocabulary — is not, and the evidence is in the framework's own contract:
+ *
+ *  - `RolesSchema` is `union([enum(CORE_APP_ROLES), enum(CORE_ORG_ROLES), z.string().min(1)])`, and
+ *    the third arm is the SUPPORTED feature, not an oversight: an application registers its own role
+ *    keys at startup through `initializeRolesWithCustom`, and `RolesConfigurationSchema` is a
+ *    `z.record(z.string(), RoleDefinitionSchema)`. A closed enum would delete custom roles.
+ *  - So "is this string a valid role key?" has no static answer. It has a RUNTIME answer, per
+ *    application, per scope — which is exactly what the role tables are.
+ *
+ * ## What IS closed, and where its one source lives
+ *
+ * The **scope partition**. Every role key belongs to exactly one `relatedPrimaryScope`, and
+ * `AuthorizationsBackendService.getRoleHierarchy(roleKey, scope)` is the single runtime source of
+ * that fact: it selects the APPLICATION table or the ORGANIZATIONS table and never consults both. A
+ * key unknown in the passed scope expands to the EMPTY chain, which is what makes an app-scope
+ * string written into an org-scoped membership row confer nothing — the safety comes from
+ * RESOLUTION, not from the field's type, and it must stay that way.
+ *
+ * ## What was duplicated, and is not any more
+ *
+ * The derivation BUILT ON that partition. `resolveSuperAdminConferringRoles` and
+ * `resolveOrganizationOwnerConferringRoles` were the same eleven lines twice, differing only in
+ * (table, scope, anchor) — each carrying its own paragraph re-establishing the partition argument
+ * above, in its own words, for its own reader. That is the shape `CLAUDE.md` asks to have one named
+ * runtime source for: not the role STRINGS, which cannot be closed, but the QUESTION asked of them.
+ *
+ * Two floors measure populations with it today ({@link resolveSuperAdminConferringRoles},
+ * {@link resolveOrganizationOwnerConferringRoles}); a third scope's floor is one call, not another
+ * copy.
+ *
+ * ## Why this module ships with NO test file of its own
+ *
+ * A direct suite was written and then DELETED, because measuring it showed every property it
+ * asserted was already covered — and its stated rationale was false. It claimed the floor suites
+ * "stub `getRoleHierarchy` as a function that IGNORES its scope"; both actually stub
+ * `(role, scope) => scope === <their own scope> ? table[role] : []`, and both tables already contain
+ * a CUSTOM, non-enum role key (`CUSTOM_PLATFORM_OWNER`, `CUSTOM_TENANT_PRINCIPAL`) reaching the
+ * anchor — so the open-vocabulary property is pinned too.
+ *
+ * Proven rather than assumed: binding the super-admin floor to `ORGANIZATIONS` scope instead of
+ * `APPLICATION` — the one regression the extraction newly makes possible — reddens THREE tests in
+ * `super-admin-floor.backend.utils.test.ts` on its own. The bindings are the coverage.
+ *
+ * So do not add a suite here to "cover the new module". If a THIRD binding appears, pin it in its
+ * own floor's suite the way these two are; that is where a wrong `scope` argument is observable.
+ */
+/**
+ * Every role key in `declaredRoleKeys` whose `inheritFrom` chain reaches `anchorRole`, within
+ * `scope` — i.e. every role whose holder passes a gate that requires `anchorRole`.
+ *
+ * ## Why the derivation is shaped this way
+ *
+ * **It mirrors the authorization layer's own test.** `authorize` admits a caller when
+ * `getRoleHierarchy(heldRole, scope).includes(requiredRole)`. Deriving the set the same way is what
+ * keeps a floor counting exactly the principals the gates would let through; an independently
+ * written membership test is how the two drift, and a floor that measures a different population
+ * than the gate protects is worse than no floor — it reports a healthy count for an unprotected
+ * scope.
+ *
+ * **The anchor is seeded unconditionally rather than discovered by the walk.** If an application's
+ * role table somehow omitted the anchor key, `roleHierarchyResolver` would return an empty chain for
+ * every key, the conferring set would be empty, and the floor would then measure a population that
+ * is empty BY CONSTRUCTION — refusing every removal forever while protecting nothing.
+ *
+ * **`scope` is passed to the resolver, never assumed.** That single argument is what carries the
+ * closed half of the vocabulary (see this module's header): the caller states which table the keys
+ * are to be read against, and a key belonging to the other table expands to nothing. A caller that
+ * passed the wrong scope would silently get `[anchorRole]` — the seed — which is the fail-CLOSED
+ * direction for a floor (it under-counts the protected population and so refuses more, never less).
+ *
+ * @param declaredRoleKeys the keys of the LIVE role table for `scope`. Live, because the effective
+ *   hierarchy is application-configurable and a statically-derived set would silently disagree with
+ *   the roles the authorization layer actually honours.
+ */
+export function resolveRolesConferringAnchor(params) {
+    const conferringRoles = new Set([params.anchorRole]);
+    for (const roleKey of params.declaredRoleKeys) {
+        if (params.roleHierarchyResolver(roleKey, params.scope).includes(params.anchorRole)) {
+            conferringRoles.add(roleKey);
+        }
+    }
+    return [...conferringRoles];
+}
+//# sourceMappingURL=role-conferral.backend.utils.js.map

package/dist/esm/security/authorizations/role-conferral.backend.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-conferral.backend.utils.js","sourceRoot":"","sources":["../../../../../src/security/authorizations/role-conferral.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAK5C;IACC,MAAM,eAAe,GAAG,IAAI,GAAG,CAAS,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAE7D,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC9C,IAAI,MAAM,CAAC,qBAAqB,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;YACpF,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC;AAC9B,CAAC","sourcesContent":["/**\n * # Role conferral — ONE derivation of \"which role keys confer authority X, in scope S\"\n *\n * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — the shared derivation every authority floor\n * measures its protected population with.\n *\n * ## The role-key vocabulary is genuinely OPEN, and closing it would be a defect\n *\n * Recorded here because the opposite is the obvious reading and was proposed as a finding: *\"a\n * membership's `roles` field is a free string, so an application-scope role value is storable in an\n * organisation-scoped membership row.\"* Both halves of that are true. The conclusion — close the\n * vocabulary — is not, and the evidence is in the framework's own contract:\n *\n *  - `RolesSchema` is `union([enum(CORE_APP_ROLES), enum(CORE_ORG_ROLES), z.string().min(1)])`, and\n *    the third arm is the SUPPORTED feature, not an oversight: an application registers its own role\n *    keys at startup through `initializeRolesWithCustom`, and `RolesConfigurationSchema` is a\n *    `z.record(z.string(), RoleDefinitionSchema)`. A closed enum would delete custom roles.\n *  - So \"is this string a valid role key?\" has no static answer. It has a RUNTIME answer, per\n *    application, per scope — which is exactly what the role tables are.\n *\n * ## What IS closed, and where its one source lives\n *\n * The **scope partition**. Every role key belongs to exactly one `relatedPrimaryScope`, and\n * `AuthorizationsBackendService.getRoleHierarchy(roleKey, scope)` is the single runtime source of\n * that fact: it selects the APPLICATION table or the ORGANIZATIONS table and never consults both. A\n * key unknown in the passed scope expands to the EMPTY chain, which is what makes an app-scope\n * string written into an org-scoped membership row confer nothing — the safety comes from\n * RESOLUTION, not from the field's type, and it must stay that way.\n *\n * ## What was duplicated, and is not any more\n *\n * The derivation BUILT ON that partition. `resolveSuperAdminConferringRoles` and\n * `resolveOrganizationOwnerConferringRoles` were the same eleven lines twice, differing only in\n * (table, scope, anchor) — each carrying its own paragraph re-establishing the partition argument\n * above, in its own words, for its own reader. That is the shape `CLAUDE.md` asks to have one named\n * runtime source for: not the role STRINGS, which cannot be closed, but the QUESTION asked of them.\n *\n * Two floors measure populations with it today ({@link resolveSuperAdminConferringRoles},\n * {@link resolveOrganizationOwnerConferringRoles}); a third scope's floor is one call, not another\n * copy.\n *\n * ## Why this module ships with NO test file of its own\n *\n * A direct suite was written and then DELETED, because measuring it showed every property it\n * asserted was already covered — and its stated rationale was false. It claimed the floor suites\n * \"stub `getRoleHierarchy` as a function that IGNORES its scope\"; both actually stub\n * `(role, scope) => scope === <their own scope> ? table[role] : []`, and both tables already contain\n * a CUSTOM, non-enum role key (`CUSTOM_PLATFORM_OWNER`, `CUSTOM_TENANT_PRINCIPAL`) reaching the\n * anchor — so the open-vocabulary property is pinned too.\n *\n * Proven rather than assumed: binding the super-admin floor to `ORGANIZATIONS` scope instead of\n * `APPLICATION` — the one regression the extraction newly makes possible — reddens THREE tests in\n * `super-admin-floor.backend.utils.test.ts` on its own. The bindings are the coverage.\n *\n * So do not add a suite here to \"cover the new module\". If a THIRD binding appears, pin it in its\n * own floor's suite the way these two are; that is where a wrong `scope` argument is observable.\n */\n\nimport type { ResourcePrimaryScope } from '@wildo-ai/saas-models';\n\n/**\n * Every role key in `declaredRoleKeys` whose `inheritFrom` chain reaches `anchorRole`, within\n * `scope` — i.e. every role whose holder passes a gate that requires `anchorRole`.\n *\n * ## Why the derivation is shaped this way\n *\n * **It mirrors the authorization layer's own test.** `authorize` admits a caller when\n * `getRoleHierarchy(heldRole, scope).includes(requiredRole)`. Deriving the set the same way is what\n * keeps a floor counting exactly the principals the gates would let through; an independently\n * written membership test is how the two drift, and a floor that measures a different population\n * than the gate protects is worse than no floor — it reports a healthy count for an unprotected\n * scope.\n *\n * **The anchor is seeded unconditionally rather than discovered by the walk.** If an application's\n * role table somehow omitted the anchor key, `roleHierarchyResolver` would return an empty chain for\n * every key, the conferring set would be empty, and the floor would then measure a population that\n * is empty BY CONSTRUCTION — refusing every removal forever while protecting nothing.\n *\n * **`scope` is passed to the resolver, never assumed.** That single argument is what carries the\n * closed half of the vocabulary (see this module's header): the caller states which table the keys\n * are to be read against, and a key belonging to the other table expands to nothing. A caller that\n * passed the wrong scope would silently get `[anchorRole]` — the seed — which is the fail-CLOSED\n * direction for a floor (it under-counts the protected population and so refuses more, never less).\n *\n * @param declaredRoleKeys the keys of the LIVE role table for `scope`. Live, because the effective\n *   hierarchy is application-configurable and a statically-derived set would silently disagree with\n *   the roles the authorization layer actually honours.\n */\nexport function resolveRolesConferringAnchor(params: {\n  readonly anchorRole: string;\n  readonly scope: ResourcePrimaryScope;\n  readonly declaredRoleKeys: readonly string[];\n  readonly roleHierarchyResolver: (roleKey: string, scope: ResourcePrimaryScope) => string[];\n}): string[] {\n  const conferringRoles = new Set<string>([params.anchorRole]);\n\n  for (const roleKey of params.declaredRoleKeys) {\n    if (params.roleHierarchyResolver(roleKey, params.scope).includes(params.anchorRole)) {\n      conferringRoles.add(roleKey);\n    }\n  }\n\n  return [...conferringRoles];\n}\n"]}

package/dist/esm/security/authorizations/scope-root-collection-confinement.backend.d.ts

@@ -50,9 +50,132 @@
  * tenant, not over the tenant row, and every org-wide gate in the authorization service filters
  * those out; counting one here would let a unit member enumerate the tenant they are narrowed inside.
  */
-import { CoreResourceOperation, ExecutionContext_ExecutionType } from '@wildo-ai/saas-models';
+import { CoreResourceOperation, ExecutionContext_ExecutionType, ResourcePrimaryScope } from '@wildo-ai/saas-models';
 /** The queryable key a scope-root row is addressed by. Named once so no call site can typo it. */
 export declare const SCOPE_ROOT_CONFINEMENT_FIELD = "_id";
+/**
+ * WHY a given scope root is, or is not, row-confined.
+ *
+ * A named vocabulary rather than four prose comments, because "which roots owe confinement" is a
+ * closed semantic question and had been answered four times, in four files, in four different words
+ * — the shape `CLAUDE.md` asks to have one runtime source for. It also makes the answer READABLE
+ * from the authority itself instead of from the resource configs it governs.
+ *
+ * THE RULE THAT DECIDES MEMBERSHIP, stated once so the next scope is not settled by taste:
+ *
+ * > **A scope root owes row confinement exactly when a caller's authority for that scope names ONE
+ * > INSTANCE of it, while the collection holds every instance.**
+ *
+ * That is a fact about ROLE ENTRIES, and it is measurable rather than a judgement: only an
+ * `ORGANIZATIONS` entry carries a `relatedResourceId` selecting a particular scope instance. An
+ * `APPLICATION` entry names the deployment (there is one), and `USER_SELF` / `ANONYMOUS` have no
+ * role entries at all — their instance comes from `initiatorIds`, which the request supplies about
+ * ITSELF and which therefore cannot be an authority set. So on today's vocabulary exactly one root
+ * owes it, and that is a derivation, not a denominator someone chose.
+ */
+export declare enum ScopeRootConfinementDisposition {
+    /**
+     * Confined to the tenants the caller holds an organization-WIDE role entry for. The only
+     * disposition that produces a predicate.
+     */
+    CONFINED_TO_CALLER_ORGANIZATIONS = "CONFINED_TO_CALLER_ORGANIZATIONS",
+    /**
+     * The root's HTTP collection surface is the APPLICATION-tier administrative directory, and the
+     * caller's authority for it is application-wide — so "all rows" is not wider than the authority
+     * that reached them. Narrower callers reach the same rows only through a route that confines them
+     * by a DIFFERENT mechanism (`users` is enumerated per tenant through
+     * `/organizations/{organizationId}/users/search`, whose junction filter intersects `_id` with the
+     * tenant's membership; the global routes stay admin-gated).
+     *
+     * ## ⚠️ The ELEVATION asymmetry this disposition carries, stated so nobody has to re-derive it
+     *
+     * Read against the per-row door, the sentence above is the whole of the control and it is a
+     * statement about a STANDING role. Measured 2026-09-09:
+     *
+     * | | per-row crossing | this directory read |
+     * |---|---|---|
+     * | declared per variant | `admitsCrossTenantPlatformAdministration` | nothing |
+     * | elevation required | a usable, time-bound, justified `platformAccessGrants` row | none |
+     * | role tier | `APP_ADMIN_SUPER_ADMIN` | `APP_ADMIN_VIEWER` (`users`), `ORG_MEMBER` (`applications` LIST) |
+     * | evidence | `CROSS_TENANT_ADMINISTRATIVE_ACCESS`, naming the authorizing grant | `PLATFORM_DIRECTORY_ACCESS`, naming no elevation |
+     *
+     * So the NARROW act is governed and the WIDE one is not, and the wide one sits at a strictly lower
+     * role tier. That is the correct reading of the finding, and it is worse than "not symmetric".
+     *
+     * ## Why the grant model cannot govern it, and what that does NOT mean
+     *
+     * `hasUsablePlatformAccessGrant` needs a TARGET tenant and answers `false` on an empty one; a
+     * collection call names none. So the EXISTING mechanism is structurally inapplicable here — but
+     * that is a fact about the mechanism, not a proof that prevention is impossible, and the
+     * distinction matters because the shipped `PLATFORM_DIRECTORY_ACCESS` JSDoc states the stronger
+     * form and a reader could take it as "do not try".
+     *
+     * An application-wide grant KIND is buildable. What blocks it is a decision, not structure, and the
+     * decision is WHO APPROVES: a tenant grant is approved by the tenant it names (Lockbox), and an
+     * application-wide one names none — so it is either self-service (auto-approved, which is the
+     * grant model's own default posture) or two-person, which
+     * `.claude/rules/administrative-continuity-floors.md` recommends for the widest acts. Nobody may
+     * pick that unilaterally.
+     *
+     * A related choice is already RECORDED and should not be quietly reversed: a browsable platform
+     * tenant directory was considered and rejected, on the reasoning that industry practice (Customer
+     * Lockbox, Access Approval) has the tenant id arrive out of band with the customer's support
+     * ticket. That reasoning also answers the grant flow's bootstrap gap — an operator needs an
+     * `organizationId` to request a grant and no surface yields one — so reopening the elevation
+     * question means reopening that decision too.
+     *
+     * ## What was rejected on MEASUREMENT rather than on cost
+     *
+     * Confining this read to tenants the caller holds a grant for is not merely undesirable here, it
+     * is structurally unavailable for the widest case: `users` rows carry NO tenant column at all
+     * (membership lives in `organizationMembers`), so there is nothing for a tenant predicate to bind
+     * to. Any such confinement would be a junction query that also removes the tenant-less user — the
+     * person who has just signed up and belongs to nobody — from the only surface that can find them.
+     */
+    UNCONFINED_APPLICATION_TIER_DIRECTORY = "UNCONFINED_APPLICATION_TIER_DIRECTORY",
+    /**
+     * ONE DATABASE PER APPLICATION. "An application's organizations live in that application's own
+     * database" — so this collection holds this deployment's own row and a caller can only ever see
+     * the application they are already using. Safe by ARCHITECTURE, not by a predicate, which is why
+     * it is spelled out: the default LIST/SEARCH variants are gated `ORG_MEMBER`, one role tier BELOW
+     * the `organizations` hole, and would be a full directory the day a second row existed.
+     *
+     * The premise is ASSERTED rather than assumed, and only a lane with a real store can assert it:
+     * `examples/wonder-todos/e2e/applications-scope-root-list-confinement.e2e.ts` fails if the
+     * deployment ever holds more than one application row. (The unit probe beside this authority
+     * asserts the complementary half — that this declaration and the compiled filter agree.)
+     */
+    UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE = "UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE",
+    /**
+     * There is NOTHING to confine to. An anonymous session is a pre-authentication visitor of the
+     * application; it has no organization, so a "confined" listing would name a relationship that does
+     * not exist. `APP_ADMIN_SUPER_ADMIN` is the whole of the control, and it is the right one.
+     *
+     * ⚠️ If anonymous sessions ever gain a tenant association this becomes an ORGANIZATIONS-axis
+     * question and the disposition moves to {@link ScopeRootConfinementDisposition.CONFINED_TO_CALLER_ORGANIZATIONS}.
+     */
+    UNCONFINED_NO_CONFINING_RELATIONSHIP = "UNCONFINED_NO_CONFINING_RELATIONSHIP"
+}
+/**
+ * The disposition of every scope root, TOTAL over `ResourcePrimaryScope`.
+ *
+ * Total on purpose (`.claude/rules/derive-before-you-ask.md` #3): a scope added to the vocabulary
+ * tomorrow is a COMPILE ERROR here, so someone has to answer the rule above for it rather than
+ * inheriting silence. The predicate this replaced was `resourcePrimaryScope !== ORGANIZATIONS` with
+ * a comment saying the other three "would change four surfaces this analysis did not measure" —
+ * true when written, and by then no longer true: all four had since been measured
+ * (`scope-root-collection-confinement.probe.test.ts`, the RESIDUAL sweep) and each answer recorded
+ * in a different resource config. This map is where that answer now lives, once.
+ */
+export declare const SCOPE_ROOT_CONFINEMENT_DISPOSITIONS: Readonly<Record<ResourcePrimaryScope, ScopeRootConfinementDisposition>>;
+/**
+ * The disposition governing this resource, or `undefined` when it is not a scope root at all.
+ *
+ * Exported so a test — or a future gate — can ask the SAME question this authority answers instead
+ * of re-deriving it from the resource configs, which is how the four recorded answers came to be
+ * four separate paragraphs in the first place.
+ */
+export declare function resolveScopeRootConfinementDisposition(resource: ScopeRootCollectionConfinementResource): ScopeRootConfinementDisposition | undefined;
 /** What this authority needs from the execution context. Deliberately narrow, like its siblings. */
 export interface ScopeRootCollectionConfinementSignal {
     readonly executionType: ExecutionContext_ExecutionType;

package/dist/esm/security/authorizations/scope-root-collection-confinement.backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-root-collection-confinement.backend.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/scope-root-collection-confinement.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAI/B,MAAM,uBAAuB,CAAC;AAE/B,kGAAkG;AAClG,eAAO,MAAM,4BAA4B,QAAQ,CAAC;AA8ClD,oGAAoG;AACpG,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,aAAa,EAAE,8BAA8B,CAAC;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS;QACjC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;QACtC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACnC;;;;;WAKG;QACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;KACtC,EAAE,GAAG,IAAI,CAAC;IACX;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,uCAAuC,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAC5F;AAED,iEAAiE;AACjE,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,sCAAsC,GAAG,OAAO,CAKhG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kCAAkC,CAAC,MAAM,EAAE;IACzD,QAAQ,CAAC,gBAAgB,EAAE,oCAAoC,CAAC;IAChE,QAAQ,CAAC,qBAAqB,EAAE,sCAAsC,CAAC;IACvE,QAAQ,CAAC,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAC;CACnE,GAAG,OAAO,CAcV;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,gBAAgB,EAAE,oCAAoC,GACrD,MAAM,EAAE,CASV;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,4CAA4C,CAAC,OAAO,SAAS,MAAM,EAAE,MAAM,EAAE;IAC3F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,oCAAoC,CAAC;IAChE,QAAQ,CAAC,qBAAqB,EAAE,sCAAsC,CAAC;IACvE,2FAA2F;IAC3F,QAAQ,CAAC,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAC;CACnE,GAAG,OAAO,CAsBV"}
+{"version":3,"file":"scope-root-collection-confinement.backend.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/scope-root-collection-confinement.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAE9B,oBAAoB,EAErB,MAAM,uBAAuB,CAAC;AAE/B,kGAAkG;AAClG,eAAO,MAAM,4BAA4B,QAAQ,CAAC;AAElD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,oBAAY,+BAA+B;IACzC;;;OAGG;IACH,gCAAgC,qCAAqC;IACrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoDG;IACH,qCAAqC,0CAA0C;IAC/E;;;;;;;;;;;OAWG;IACH,qCAAqC,0CAA0C;IAC/E;;;;;;;OAOG;IACH,oCAAoC,yCAAyC;CAC9E;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mCAAmC,EAAE,QAAQ,CAAC,MAAM,CAAC,oBAAoB,EAAE,+BAA+B,CAAC,CAKtH,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,sCAAsC,CACpD,QAAQ,EAAE,sCAAsC,GAC/C,+BAA+B,GAAG,SAAS,CAG7C;AA8CD,oGAAoG;AACpG,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,aAAa,EAAE,8BAA8B,CAAC;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS;QACjC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;QACtC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACnC;;;;;WAKG;QACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;KACtC,EAAE,GAAG,IAAI,CAAC;IACX;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,uCAAuC,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAC5F;AAED,iEAAiE;AACjE,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,sCAAsC,GAAG,OAAO,CAKhG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kCAAkC,CAAC,MAAM,EAAE;IACzD,QAAQ,CAAC,gBAAgB,EAAE,oCAAoC,CAAC;IAChE,QAAQ,CAAC,qBAAqB,EAAE,sCAAsC,CAAC;IACvE,QAAQ,CAAC,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAC;CACnE,GAAG,OAAO,CAcV;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,gBAAgB,EAAE,oCAAoC,GACrD,MAAM,EAAE,CASV;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,4CAA4C,CAAC,OAAO,SAAS,MAAM,EAAE,MAAM,EAAE;IAC3F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,oCAAoC,CAAC;IAChE,QAAQ,CAAC,qBAAqB,EAAE,sCAAsC,CAAC;IACvE,2FAA2F;IAC3F,QAAQ,CAAC,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAC;CACnE,GAAG,OAAO,CA0BV"}

package/dist/esm/security/authorizations/scope-root-collection-confinement.backend.js

@@ -53,6 +53,139 @@
 import { CoreResourceOperation, ExecutionContext_ExecutionType, PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE, ResourcePrimaryScope, isOrganizationWideRoleInfo, } from '@wildo-ai/saas-models';
 /** The queryable key a scope-root row is addressed by. Named once so no call site can typo it. */
 export const SCOPE_ROOT_CONFINEMENT_FIELD = '_id';
+/**
+ * WHY a given scope root is, or is not, row-confined.
+ *
+ * A named vocabulary rather than four prose comments, because "which roots owe confinement" is a
+ * closed semantic question and had been answered four times, in four files, in four different words
+ * — the shape `CLAUDE.md` asks to have one runtime source for. It also makes the answer READABLE
+ * from the authority itself instead of from the resource configs it governs.
+ *
+ * THE RULE THAT DECIDES MEMBERSHIP, stated once so the next scope is not settled by taste:
+ *
+ * > **A scope root owes row confinement exactly when a caller's authority for that scope names ONE
+ * > INSTANCE of it, while the collection holds every instance.**
+ *
+ * That is a fact about ROLE ENTRIES, and it is measurable rather than a judgement: only an
+ * `ORGANIZATIONS` entry carries a `relatedResourceId` selecting a particular scope instance. An
+ * `APPLICATION` entry names the deployment (there is one), and `USER_SELF` / `ANONYMOUS` have no
+ * role entries at all — their instance comes from `initiatorIds`, which the request supplies about
+ * ITSELF and which therefore cannot be an authority set. So on today's vocabulary exactly one root
+ * owes it, and that is a derivation, not a denominator someone chose.
+ */
+export var ScopeRootConfinementDisposition;
+(function (ScopeRootConfinementDisposition) {
+    /**
+     * Confined to the tenants the caller holds an organization-WIDE role entry for. The only
+     * disposition that produces a predicate.
+     */
+    ScopeRootConfinementDisposition["CONFINED_TO_CALLER_ORGANIZATIONS"] = "CONFINED_TO_CALLER_ORGANIZATIONS";
+    /**
+     * The root's HTTP collection surface is the APPLICATION-tier administrative directory, and the
+     * caller's authority for it is application-wide — so "all rows" is not wider than the authority
+     * that reached them. Narrower callers reach the same rows only through a route that confines them
+     * by a DIFFERENT mechanism (`users` is enumerated per tenant through
+     * `/organizations/{organizationId}/users/search`, whose junction filter intersects `_id` with the
+     * tenant's membership; the global routes stay admin-gated).
+     *
+     * ## ⚠️ The ELEVATION asymmetry this disposition carries, stated so nobody has to re-derive it
+     *
+     * Read against the per-row door, the sentence above is the whole of the control and it is a
+     * statement about a STANDING role. Measured 2026-09-09:
+     *
+     * | | per-row crossing | this directory read |
+     * |---|---|---|
+     * | declared per variant | `admitsCrossTenantPlatformAdministration` | nothing |
+     * | elevation required | a usable, time-bound, justified `platformAccessGrants` row | none |
+     * | role tier | `APP_ADMIN_SUPER_ADMIN` | `APP_ADMIN_VIEWER` (`users`), `ORG_MEMBER` (`applications` LIST) |
+     * | evidence | `CROSS_TENANT_ADMINISTRATIVE_ACCESS`, naming the authorizing grant | `PLATFORM_DIRECTORY_ACCESS`, naming no elevation |
+     *
+     * So the NARROW act is governed and the WIDE one is not, and the wide one sits at a strictly lower
+     * role tier. That is the correct reading of the finding, and it is worse than "not symmetric".
+     *
+     * ## Why the grant model cannot govern it, and what that does NOT mean
+     *
+     * `hasUsablePlatformAccessGrant` needs a TARGET tenant and answers `false` on an empty one; a
+     * collection call names none. So the EXISTING mechanism is structurally inapplicable here — but
+     * that is a fact about the mechanism, not a proof that prevention is impossible, and the
+     * distinction matters because the shipped `PLATFORM_DIRECTORY_ACCESS` JSDoc states the stronger
+     * form and a reader could take it as "do not try".
+     *
+     * An application-wide grant KIND is buildable. What blocks it is a decision, not structure, and the
+     * decision is WHO APPROVES: a tenant grant is approved by the tenant it names (Lockbox), and an
+     * application-wide one names none — so it is either self-service (auto-approved, which is the
+     * grant model's own default posture) or two-person, which
+     * `.claude/rules/administrative-continuity-floors.md` recommends for the widest acts. Nobody may
+     * pick that unilaterally.
+     *
+     * A related choice is already RECORDED and should not be quietly reversed: a browsable platform
+     * tenant directory was considered and rejected, on the reasoning that industry practice (Customer
+     * Lockbox, Access Approval) has the tenant id arrive out of band with the customer's support
+     * ticket. That reasoning also answers the grant flow's bootstrap gap — an operator needs an
+     * `organizationId` to request a grant and no surface yields one — so reopening the elevation
+     * question means reopening that decision too.
+     *
+     * ## What was rejected on MEASUREMENT rather than on cost
+     *
+     * Confining this read to tenants the caller holds a grant for is not merely undesirable here, it
+     * is structurally unavailable for the widest case: `users` rows carry NO tenant column at all
+     * (membership lives in `organizationMembers`), so there is nothing for a tenant predicate to bind
+     * to. Any such confinement would be a junction query that also removes the tenant-less user — the
+     * person who has just signed up and belongs to nobody — from the only surface that can find them.
+     */
+    ScopeRootConfinementDisposition["UNCONFINED_APPLICATION_TIER_DIRECTORY"] = "UNCONFINED_APPLICATION_TIER_DIRECTORY";
+    /**
+     * ONE DATABASE PER APPLICATION. "An application's organizations live in that application's own
+     * database" — so this collection holds this deployment's own row and a caller can only ever see
+     * the application they are already using. Safe by ARCHITECTURE, not by a predicate, which is why
+     * it is spelled out: the default LIST/SEARCH variants are gated `ORG_MEMBER`, one role tier BELOW
+     * the `organizations` hole, and would be a full directory the day a second row existed.
+     *
+     * The premise is ASSERTED rather than assumed, and only a lane with a real store can assert it:
+     * `examples/wonder-todos/e2e/applications-scope-root-list-confinement.e2e.ts` fails if the
+     * deployment ever holds more than one application row. (The unit probe beside this authority
+     * asserts the complementary half — that this declaration and the compiled filter agree.)
+     */
+    ScopeRootConfinementDisposition["UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE"] = "UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE";
+    /**
+     * There is NOTHING to confine to. An anonymous session is a pre-authentication visitor of the
+     * application; it has no organization, so a "confined" listing would name a relationship that does
+     * not exist. `APP_ADMIN_SUPER_ADMIN` is the whole of the control, and it is the right one.
+     *
+     * ⚠️ If anonymous sessions ever gain a tenant association this becomes an ORGANIZATIONS-axis
+     * question and the disposition moves to {@link ScopeRootConfinementDisposition.CONFINED_TO_CALLER_ORGANIZATIONS}.
+     */
+    ScopeRootConfinementDisposition["UNCONFINED_NO_CONFINING_RELATIONSHIP"] = "UNCONFINED_NO_CONFINING_RELATIONSHIP";
+})(ScopeRootConfinementDisposition || (ScopeRootConfinementDisposition = {}));
+/**
+ * The disposition of every scope root, TOTAL over `ResourcePrimaryScope`.
+ *
+ * Total on purpose (`.claude/rules/derive-before-you-ask.md` #3): a scope added to the vocabulary
+ * tomorrow is a COMPILE ERROR here, so someone has to answer the rule above for it rather than
+ * inheriting silence. The predicate this replaced was `resourcePrimaryScope !== ORGANIZATIONS` with
+ * a comment saying the other three "would change four surfaces this analysis did not measure" —
+ * true when written, and by then no longer true: all four had since been measured
+ * (`scope-root-collection-confinement.probe.test.ts`, the RESIDUAL sweep) and each answer recorded
+ * in a different resource config. This map is where that answer now lives, once.
+ */
+export const SCOPE_ROOT_CONFINEMENT_DISPOSITIONS = Object.freeze({
+    [ResourcePrimaryScope.ORGANIZATIONS]: ScopeRootConfinementDisposition.CONFINED_TO_CALLER_ORGANIZATIONS,
+    [ResourcePrimaryScope.USER_SELF]: ScopeRootConfinementDisposition.UNCONFINED_APPLICATION_TIER_DIRECTORY,
+    [ResourcePrimaryScope.APPLICATION]: ScopeRootConfinementDisposition.UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE,
+    [ResourcePrimaryScope.ANONYMOUS]: ScopeRootConfinementDisposition.UNCONFINED_NO_CONFINING_RELATIONSHIP,
+});
+/**
+ * The disposition governing this resource, or `undefined` when it is not a scope root at all.
+ *
+ * Exported so a test — or a future gate — can ask the SAME question this authority answers instead
+ * of re-deriving it from the resource configs, which is how the four recorded answers came to be
+ * four separate paragraphs in the first place.
+ */
+export function resolveScopeRootConfinementDisposition(resource) {
+    if (!isOwnScopeRootResource(resource))
+        return undefined;
+    return SCOPE_ROOT_CONFINEMENT_DISPOSITIONS[resource.resourcePrimaryScope];
+}
 /**
  * The operations this confinement governs: those that resolve a SET of rows with no per-row
  * authorization behind them.
@@ -192,12 +325,16 @@ export function resolveCallerOrganizationIds(executionContext) {
  * G-PG-NULL). One emitter covers the confined case and the deny-all case on both adapters.
  */
 export function assignScopeRootCollectionConfinementToFilter(params) {
-    if (!isOwnScopeRootResource(params.resourceConfiguration))
+    const disposition = resolveScopeRootConfinementDisposition(params.resourceConfiguration);
+    if (!disposition)
         return false;
-    // Only the tenant axis. `users`, `applications` and `anonymous_users` are also their own scope
-    // roots, but they are APPLICATION-level directories rather than tenant data, and confining them
-    // would change four surfaces this analysis did not measure. See the analysis plan's open question.
-    if (params.resourceConfiguration.resourcePrimaryScope !== ResourcePrimaryScope.ORGANIZATIONS)
+    // Which roots owe a predicate is DECLARED, total over the scope vocabulary, with the rule that
+    // decides membership stated on the enum. An unrecognised scope cannot reach here —
+    // `isOwnScopeRootResource` already refuses a scope absent from `PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE`
+    // — but were the two maps ever to disagree, `undefined` falls through this check and CONFINES,
+    // which yields the caller's organization ids as `_id`s of some other resource: no rows, loudly,
+    // rather than every row, silently.
+    if (disposition !== undefined && disposition !== ScopeRootConfinementDisposition.CONFINED_TO_CALLER_ORGANIZATIONS)
         return false;
     if (!params.executedCoreOperation)
         return false;