@stigmer/server 3.27.1 → 3.27.2

package/src/authorization/derived-tuples.ts

@@ -26,18 +26,39 @@
  *     rules' one predicate). The person comparison itself is the
  *     evaluator's, over the aliases `Person` carries.
  *
- * The SOURCE joins two records per (object, relation): the person's own
- * IamPolicy rows on the object (read ONCE per source through
- * `findByPrincipal` — every row open source writes names an account id,
- * so the person's account id is the whole key, and on the OSS adapter one
- * read is one scan whatever the number of organizations walked) and the
- * tuples derived from the object's row (loaded once per object through
- * the loader, which a declaration's `derived` rule also reads related
- * rows through). An absent row is no tuples — the target's own not-found
- * is the driver's arm, and a parent that no longer exists simply grants
- * nothing, as in the cloud; any other store fault propagates so the
- * driver folds it to `unavailable`. One source per check (or per list
- * call for the list scope): its memo is the check's.
+ * The SOURCE joins two records per (object, relation): the IamPolicy rows
+ * a check can meet on the object, and the tuples derived from the
+ * object's row (loaded once per object through the loader, which a
+ * declaration's `derived` rule also reads related rows through). The rows
+ * are read ONCE per source through `findByPrincipal`, keyed by the
+ * principals a check can reach the person through:
+ *
+ *   - the person's account — every role and every grant made to them;
+ *   - every team the person holds `member` on — a grant made to
+ *     `team:<id>#member` names the team, never the person, so it is read
+ *     by the team's id. The set is complete without recursion: a team's
+ *     membership is a direct grant only and a team never contains a team,
+ *     so every team that can admit the person appears among the person's
+ *     own rows. The rows grant nothing by being read: the evaluator still
+ *     asks whether the person is the team's member, which the model bounds
+ *     by the organization (`member: [identity_account] and viewer from
+ *     organization`), so a person who left the organization reads the
+ *     team's rows and is admitted by none of them.
+ *
+ * Open source serves no team (the kind's tier is enterprise), so the
+ * person's rows name none and the second read never happens: one read per
+ * source, an indexed read on the OSS adapter (its list index by
+ * principal) whatever the number of organizations walked or rows held.
+ * An edition that composes teams over the built-in
+ * evaluator pays one read more per team the person holds. The rows are
+ * indexed by (object, relation) once, so a list's thousands of candidates
+ * each find theirs without walking the rest.
+ *
+ * An absent row is no tuples — the target's own not-found is the driver's
+ * arm, and a parent that no longer exists simply grants nothing, as in the
+ * cloud; any other store fault propagates so the driver folds it to
+ * `unavailable`. One source per check (or per list call for the list
+ * scope): its memo is the check's.
  *
  * A source may be SEEDED with the facts of objects the caller already
  * holds (the list scope's candidates, decoded by the lane and carried on
@@ -102,6 +123,10 @@ export const ROW_RECORDED_OWNER_KINDS: ReadonlySet<ApiResourceKind> = new Set([
   ApiResourceKind.organization,
 ]);
 
+/** The FGA type a team grant names, and the relation that makes a person one of its members (the model's `team#member`). */
+const TEAM_TYPE = kindEnumName(ApiResourceKind.team);
+const TEAM_MEMBER_RELATION = "member";
+
 function account(id: string): Subject {
   return { form: "object", object: { type: ACCOUNT_TYPE, id } };
 }
@@ -209,7 +234,9 @@ export interface DerivedTupleSource extends TupleSource {
    * The person's own IamPolicy rows as tuples — the ONE read of them this
    * source makes, shared with `tuplesOf`. A list-shaped consumer (the
    * organization directory; the list scope) reads its candidate objects
-   * from here instead of scanning the port a second time.
+   * from here instead of scanning the port a second time. The rows granted
+   * to the person's teams are not among them: they name the team, and
+   * `tuplesOf` serves them where a check meets them.
    */
   personTuples(): Promise<ReadonlyArray<Tuple>>;
 }
@@ -235,6 +262,9 @@ export function newDerivedTupleSource(
     );
   }
   let personRows: Promise<ReadonlyArray<Tuple>> | undefined;
+  let reachableRows:
+    | Promise<ReadonlyMap<string, ReadonlyArray<Tuple>>>
+    | undefined;
 
   const loader: RowLoader = {
     load(object) {
@@ -284,6 +314,38 @@ export function newDerivedTupleSource(
     return personRows;
   }
 
+  /**
+   * Every row a check can meet, keyed by (object, relation): the person's
+   * own, then the rows granted to each team the person holds `member` on
+   * (the module header says why that set is complete). A person in no
+   * team costs nothing beyond their own rows.
+   */
+  function reachableTuples(): Promise<
+    ReadonlyMap<string, ReadonlyArray<Tuple>>
+  > {
+    if (reachableRows === undefined) {
+      reachableRows = rowTuples().then(async (own) => {
+        const teams = new Set<string>();
+        for (const tuple of own) {
+          if (
+            tuple.object.type === TEAM_TYPE &&
+            tuple.relation === TEAM_MEMBER_RELATION &&
+            tuple.object.id !== ""
+          ) {
+            teams.add(tuple.object.id);
+          }
+        }
+        const granted = await Promise.all(
+          [...teams].map((team) =>
+            deps.policies.findByPrincipal(TEAM_TYPE, team),
+          ),
+        );
+        return indexByPair([...own, ...granted.flat().map(tupleOfRow)]);
+      });
+    }
+    return reachableRows;
+  }
+
   return {
     loader,
     personTuples: rowTuples,
@@ -292,7 +354,8 @@ export function newDerivedTupleSource(
         tuple.relation === relation &&
         tuple.object.type === object.type &&
         tuple.object.id === object.id;
-      const fromRows = (await rowTuples()).filter(onPair);
+      const fromRows =
+        (await reachableTuples()).get(pairKey(object, relation)) ?? [];
       const declaration = model.byType(object.type);
       if (declaration === undefined) {
         return fromRows;
@@ -337,6 +400,27 @@ async function loadRow(
   }
 }
 
+/** The key a tuple is served under: its object and relation. */
+function pairKey(object: ObjectRef, relation: string): string {
+  return `${formatObjectRef(object)}#${relation}`;
+}
+
+function indexByPair(
+  tuples: ReadonlyArray<Tuple>,
+): ReadonlyMap<string, ReadonlyArray<Tuple>> {
+  const index = new Map<string, Tuple[]>();
+  for (const tuple of tuples) {
+    const key = pairKey(tuple.object, tuple.relation);
+    const held = index.get(key);
+    if (held === undefined) {
+      index.set(key, [tuple]);
+    } else {
+      held.push(tuple);
+    }
+  }
+  return index;
+}
+
 /** An IamPolicy row as the tuple it records: `resource#relation@principal`. */
 function tupleOfRow(row: IamPolicy): Tuple {
   const spec = row.spec;

package/src/boot/__tests__/list-indexes.test.ts

@@ -27,6 +27,10 @@ const PINNED: Readonly<
     fingerprint:
       "artifact{agent_execution=field:spec.source.agent_execution_id,workflow_execution=field:spec.source.workflow_execution_id}",
   },
+  iam_policy: {
+    revision: 1,
+    fingerprint: "iam_policy{principal=field:spec.principal.id}",
+  },
   session: {
     revision: 1,
     fingerprint:

package/src/boot/list-indexes.ts

@@ -10,9 +10,14 @@
  * parent's rows without decoding the whole kind; the kinds here were
  * chosen on the hosted edition's row counts and sizes (2026-09-23: every
  * other org-scoped kind held under a hundred rows and a hundred kilobytes).
+ * A kind also joins when a port read on every authorization check would
+ * otherwise decode the whole kind: `iam_policy`, whose adapter reads a
+ * person's rows by principal (measured 2026-09-24: about 4.6 microseconds
+ * per row per read, 47 ms a check at ten thousand rows on sqlite).
  */
 import { agentExecutionListIndex } from "../domain/agentexecution/list-index.js";
 import { artifactListIndex } from "../domain/artifact/list-index.js";
+import { iamPolicyListIndex } from "../domain/iampolicy/list-index.js";
 import { sessionListIndex } from "../domain/session/list-index.js";
 import { workflowExecutionListIndex } from "../domain/workflowexecution/list-index.js";
 import type { ListIndexDeclaration } from "../store/list-index.js";
@@ -20,6 +25,7 @@ import type { ListIndexDeclaration } from "../store/list-index.js";
 export const LIST_INDEXES: ReadonlyArray<ListIndexDeclaration> = [
   agentExecutionListIndex,
   artifactListIndex,
+  iamPolicyListIndex,
   sessionListIndex,
   workflowExecutionListIndex,
 ];

package/src/domain/iampolicy/__tests__/resource-store.test.ts

@@ -2,10 +2,12 @@
  * Runs the IamPolicyStore port-contract kit (../store-contract.ts) over the
  * OSS adapter (../resource-store.ts) on both drivers through the drivers'
  * own fixtures (sqlite always; Postgres under TEST_DATABASE_URL), and pins
- * the one behaviour that is the OSS adapter's rather than the port's
- * (T01_1_review.md Q-OR-9): save refuses a policy whose id is not the
- * triple's derived id, the invariant that makes "one row per triple" the
- * primary key's job in open source.
+ * the two behaviours that are the OSS adapter's rather than the port's:
+ * save refuses a policy whose id is not the triple's derived id, the
+ * invariant that makes "one row per triple" the primary key's job in open
+ * source; and a principal's rows are read through the kind's list index,
+ * never by decoding the whole kind, because the built-in authorizer reads
+ * them on every check.
  *
  * The kit's case list is pinned by name so a case cannot drop out unnoticed:
  * the cloud driver's test iterates the same export over `cloud.iam_policy`
@@ -21,6 +23,7 @@ import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/
 import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import { IamPolicySchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
 
+import { LIST_INDEXES } from "../../../boot/list-indexes.js";
 import type { Store } from "../../../store/interface.js";
 import { PostgresStore } from "../../../store/postgres/store.js";
 import {
@@ -82,7 +85,11 @@ const postgresFixture: DriverFixture = {
     if (postgresDatabase === undefined) {
       postgresDatabase = await createTestDatabase();
     }
-    const store = await PostgresStore.open(postgresDatabase.databaseUrl);
+    const store = await PostgresStore.open(
+      postgresDatabase.databaseUrl,
+      undefined,
+      { listIndexes: LIST_INDEXES },
+    );
     await store.deleteResourcesByKind(ApiResourceKind.iam_policy);
     return { store, close: () => store.close() };
   },
@@ -160,6 +167,59 @@ describe.each([sqliteFixture, postgresFixture])(
           spec,
         );
       });
+
+      it("reads a principal's rows through the list index, never by decoding the whole kind", async () => {
+        let scans = 0;
+        const target = opened.store;
+        // Every method runs on the real store; only the scan is counted.
+        const counted = new Proxy(target, {
+          get(store, property) {
+            if (property === "listResources") {
+              return (kind: ApiResourceKind) => {
+                if (kind === ApiResourceKind.iam_policy) {
+                  scans += 1;
+                }
+                return store.listResources(kind);
+              };
+            }
+            const value: unknown = Reflect.get(store, property, store);
+            return typeof value === "function" ? value.bind(store) : value;
+          },
+        });
+        const policies = newResourceIamPolicyStore(counted);
+        for (const [principal, relation] of [
+          ["ida_wtr3jcf281yfk9xx61kj59fsme", "admin"],
+          ["ida_wtr3jcf281yfk9xx61kj59fsme", "member"],
+          ["ida_0hlf2yb5mhkgb3bdzkkrptqf4d", "member"],
+        ] as const) {
+          const spec = orgRole(principal, relation, "acme");
+          await policies.save(
+            create(IamPolicySchema, {
+              apiVersion: IAM_POLICY_API_VERSION,
+              kind: IAM_POLICY_KIND,
+              metadata: create(ApiResourceMetadataSchema, {
+                id: policyIdFor(spec),
+              }),
+              spec,
+            }),
+          );
+        }
+        const found = await policies.findByPrincipal(
+          "identity_account",
+          "ida_wtr3jcf281yfk9xx61kj59fsme",
+        );
+        expect(found.map((policy) => policy.spec?.relation).sort()).toEqual([
+          "admin",
+          "member",
+        ]);
+        expect(
+          await policies.findByPrincipal(
+            "team",
+            "ida_wtr3jcf281yfk9xx61kj59fsme",
+          ),
+        ).toEqual([]);
+        expect(scans).toBe(0);
+      });
     });
   },
 );

package/src/domain/iampolicy/list-index.ts

@@ -0,0 +1,33 @@
+/**
+ * The IamPolicy list index (store/list-index.ts): `principal` is the key
+ * the open-source adapter's `findByPrincipal` reads (resource-store.ts).
+ * It is not a lane's index: the built-in authorizer reads a person's rows,
+ * and the rows granted to each team they belong to, on every check and
+ * every list batch (authorization/derived-tuples.ts), and without the key
+ * each of those reads decodes the whole kind — a table that grows with
+ * every member, organization and grant.
+ *
+ * The key is the principal's id alone: a key reads one string field, and
+ * an id carries its kind's prefix (`ida_` for an account, `tm_` for a
+ * team), so the index narrows to one principal and the adapter's
+ * predicate on (kind, id) keeps the answer exact whatever the index
+ * returns. A policy is not organization-scoped the way a lane's rows are,
+ * so the read names no organization; the key table's lookup index leads
+ * with the key, not the organization (the v6 migration of each driver).
+ *
+ * A change to `keys` bumps `revision` (boot/__tests__/list-indexes.test.ts
+ * pins the pair).
+ */
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { IamPolicySchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+
+import { declareListIndex, field } from "../../store/list-index.js";
+
+export const iamPolicyListIndex = declareListIndex({
+  kind: ApiResourceKind.iam_policy,
+  schema: IamPolicySchema,
+  revision: 1,
+  keys: {
+    principal: field("spec.principal.id"),
+  },
+});

package/src/domain/iampolicy/resource-store.ts

@@ -4,14 +4,21 @@
  * §3a, §4). The composition root installs it when no extension registers
  * `drivers.iamPolicyStore`.
  *
- * Reads. `findById` is a PRIMARY-KEY read. Every other find decodes
- * `listResources(iam_policy)` and filters in memory: the `resources` table
- * has no secondary index and `findByField` is single-hit, so a scan is the
- * honest shape, and the row count is members × organizations on a
- * self-host — measured in the entry's execution record (§4), not assumed.
- * The filters are the cloud store's WHERE clauses restated over the proto
- * (store.ts names each), so a driver's test over either edition reads the
- * same contract.
+ * Reads. `findById` is a PRIMARY-KEY read. `findByPrincipal` is an
+ * INDEXED read through the kind's list index (list-index.ts), because the
+ * built-in authorizer calls it on every check and every list batch — for
+ * the person, and once more per team they belong to — and a scan there
+ * costs a decode of every row the server holds, per call (measured
+ * 2026-09-24: about 4.6 microseconds per row, 47 ms a check at ten
+ * thousand rows on sqlite). The index narrows by the principal's id; the
+ * (kind, id) predicate decides, so the answer is exact whatever the index
+ * returns, and the store keeps it exact while an older binary still
+ * writes (store/interface.ts, `queryResources`). Every other find decodes
+ * `listResources(iam_policy)` and filters in memory: they serve the grant
+ * path and the access lists, not the check, and the row count behind them
+ * is members × organizations on a self-host. The filters are the cloud
+ * store's WHERE clauses restated over the proto (store.ts names each), so
+ * a driver's test over either edition reads the same contract.
  *
  * Writes. `save` refuses a policy whose id is not its triple's derived id
  * (constants.ts policyIdFor): open source has no legacy random ids, and a
@@ -43,6 +50,7 @@ import { kindEnumName } from "../../pipeline/apiresource-meta.js";
 import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { USER_GRANT_PRINCIPAL_KINDS, policyIdFor } from "./constants.js";
+import { iamPolicyListIndex } from "./list-index.js";
 import { DuplicatePolicyError } from "./store.js";
 import type { IamPolicyStore } from "./store.js";
 
@@ -72,7 +80,7 @@ export function newResourceIamPolicyStore(store: Store): IamPolicyStore {
     }
   }
 
-  /** Every row of the kind, decoded — the scan behind every non-id read. */
+  /** Every row of the kind, decoded — the scan behind every read but by id and by principal. */
   async function all(): Promise<ReadonlyArray<IamPolicy>> {
     const rows = await store.listResources(KIND);
     return rows.map((bytes) => fromBinary(IamPolicySchema, bytes));
@@ -102,8 +110,13 @@ export function newResourceIamPolicyStore(store: Store): IamPolicyStore {
 
     findById: readById,
 
-    findByPrincipal(principalKind, principalId) {
-      return where((policy) => onPrincipal(policy, principalKind, principalId));
+    async findByPrincipal(principalKind, principalId) {
+      const rows = await store.queryResources(iamPolicyListIndex, {
+        anyKey: [{ name: "principal", value: principalId }],
+      });
+      return rows
+        .map((row) => fromBinary(IamPolicySchema, row.data))
+        .filter((policy) => onPrincipal(policy, principalKind, principalId));
     },
 
     findByResource(resourceKind, resourceId) {

package/src/extensions/list-read-scope.ts

@@ -224,7 +224,8 @@ export interface ScopedListResource {
 /**
  * The ONE consumption idiom for post-scan lanes (the shared-step
  * discipline of pipeline/steps/authorization-tuples.ts, rendered as a
- * helper because half the lanes are direct handlers):
+ * helper because half the lanes are direct handlers; on the barrel, so a
+ * composition's lane over its own table narrows the same way):
  *
  *   - no scope composed → the input array unchanged (byte-identity;
  *     `requestOrg` deliberately not consulted — the OSS single-tenant

package/src/index.ts

@@ -274,6 +274,11 @@ export type {
   ListReadScope,
   ListEntryMeta,
 } from "./extensions/list-read-scope.js";
+// The one consumption idiom of the list read scope for post-scan list lanes:
+// exported so a list lane a composition serves from its own table narrows
+// its rows exactly as the library's lanes do, instead of building each
+// candidate's authorization facts by hand.
+export { restrictListByReadScope } from "./extensions/list-read-scope.js";
 // The stigmer-cloud#572 seam: the identity a schedule fire acts as
 // (drivers.scheduleFireCaller) — the composition mints it per fire; the
 // RunStarter propagates it through the R5 in-process header. A mint that