@stigmer/server 3.27.1 → 3.28.0

package/src/authorization/derived-tuples.ts

@@ -12,7 +12,7 @@
  *   - owner SELF:     <row>#owner@identity_account:<row id>
  *   - creator:        <row>#creator@identity_account:<creator stamp>   (kinds flagged requires_creator_tuple)
  *   - org-viewer:     <row>#viewer@organization:<org>#viewer          (visibility_org; cloud#257's shape)
- *   - platform-viewer: none — it fans out over identity providers, a kind this edition does not serve
+ *   - platform-viewer: none — it fans out over identity providers, which this edition does not serve: the model defines the type, and no tuple of it is derived here
  *
  * Two facts are this edition's own and are stated here, nowhere else:
  *   - The ORGANIZATION's owner is a ROW, not a derivation. 2b's role
@@ -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;
@@ -309,7 +372,11 @@ export function newDerivedTupleSource(
   };
 }
 
-/** The decoded row for an object, or undefined when the kind is not declared or the row does not exist. */
+/**
+ * The decoded row for an object, or undefined when the kind is not
+ * declared, is rowless (`platform`, which resolves over tuples alone), or
+ * the row does not exist.
+ */
 async function loadRow(
   deps: Pick<DerivedTupleSourceDeps, "store" | "accounts">,
   model: Model,
@@ -319,6 +386,7 @@ async function loadRow(
   const kind = kindByEnumName(object.type);
   if (
     declaration === undefined ||
+    declaration.schema === undefined ||
     kind === ApiResourceKind.api_resource_kind_unknown ||
     object.id === ""
   ) {
@@ -337,6 +405,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/authorization/evaluator.ts

@@ -30,11 +30,11 @@
  * it is being resolved is a cycle in the declarations, which is a bug,
  * and a resolution deeper than MAX_RESOLUTION_DEPTH is the same class of
  * bug; both throw, because the alternative — a quiet `false` — would turn
- * a broken transcript into a lockout nobody can see. A kind the model does
- * not declare is a fault as the check's TARGET (the driver refuses
- * unserved kinds before evaluation, so reaching here is a registry gap)
- * and simply an object with no relations when reached through a tuple
- * (`identity_provider#platform_user`, which no open-source tuple names).
+ * a broken model into a lockout nobody can see. A kind the model does
+ * not declare is a fault as the check's TARGET (the built-in model
+ * declares every kind, so reaching here is a registry gap) and simply an
+ * object with no relations when reached through a tuple (only a test's
+ * throwaway model omits a type).
  * A relation the kind does not declare is `false` — the ruled answer for
  * a wire question the model has no line for, where OpenFGA
  * itself answers a validation error.
@@ -59,14 +59,12 @@ import { ACCOUNT_TYPE, formatObjectRef, pairKey } from "./tuples.js";
 export const MAX_RESOLUTION_DEPTH = 25;
 
 /**
- * The faults an evaluation can raise. Two are consumer bugs by the seam
- * contracts (a kind the model does not declare; the `internal` class
- * offered to the list scope's restrict verb, which the shared helper
- * answers before any driver); the rest are the model's own.
+ * The faults an evaluation can raise. One is a consumer bug by the seam
+ * contracts (a kind the model does not declare, or a rowless one asked
+ * for its rows); the rest are the model's own.
  */
 export type EvaluationFault =
   | "undeclared-target-kind"
-  | "internal-caller-offered"
   | "resolution-depth-exceeded"
   | "resolution-cycle";
 

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

@@ -40,27 +40,30 @@
  * returns the org-narrowed rows for the class before any driver is asked
  * (extensions/list-read-scope.ts, the header's contract line), the
  * Authorize step's trust-domain rule applied to a list answer. So this
- * driver's `restrictListEntries` REFUSES the class (`internal-caller-offered`):
- * being offered it means a caller reached the driver around the one
- * consumption idiom, and evaluating the server as a person would return
- * a quiet short list — the failure shape stigmer#1207 fixed. The
- * enumeration verb has no helper in front of it and keeps its own arm:
- * every id of the kind, as the built-in directory answers the class with
- * every organization. No in-process edge reaches an enumeration lane
- * today; the arm is pinned so a future one meets the rule.
+ * driver's `restrictListEntries` REFUSES the class with the seam's
+ * `InternalCallerOfferedError`: being offered it means a caller reached
+ * the driver around the one consumption idiom, and evaluating the server
+ * as a person would return a quiet short list — the failure shape
+ * stigmer#1207 fixed. The enumeration verb has no helper in front of it
+ * and keeps its own arm: every id of the kind, as the built-in directory
+ * answers the class with every organization. No in-process edge reaches
+ * an enumeration lane today; the arm is pinned so a future one meets the
+ * rule.
  *
  * Faults THROW and are never an empty answer (the seam: an empty set means
  * "authorized to see nothing"; an outage is the pipeline's sanitized
- * INTERNAL). A kind the model does not declare, like the internal class
- * above, is a consumer bug by the seam's contract and faults through the
- * evaluator, loud; the model declares exactly the open-source tier, so no
- * served lane can reach it.
+ * INTERNAL). A kind the model does not declare, or a rowless one
+ * (`platform`, which has no stored rows to list), is, like the internal
+ * class above, a consumer bug by the seam's contract, and faults through
+ * the evaluator's own error, loud; every served list lane lists a kind
+ * with rows.
  *
  * Logging. One debug line per call — kind, offered, kept, elapsed — what
  * an operator needs to answer "why is Alice's list short" beside the
  * Authorizer's per-denial lines; never the token.
  */
 import { fromBinary } from "@bufbuild/protobuf";
+import type { DescMessage } from "@bufbuild/protobuf";
 
 import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
@@ -71,6 +74,7 @@ import type {
   ListEntryMeta,
   ListReadScope,
 } from "../extensions/list-read-scope.js";
+import { InternalCallerOfferedError } from "../extensions/list-read-scope.js";
 import { kindEnumName } from "../pipeline/apiresource-meta.js";
 import type { Store } from "../store/interface.js";
 import { newDerivedTupleSource } from "./derived-tuples.js";
@@ -87,6 +91,9 @@ import type { ObjectRef, Person } from "./tuples.js";
 /** The relation every list lane reads through (the cloud's LIST_RELATION). */
 const LIST_RELATION = "can_view";
 
+/** A declaration of a kind with stored rows: the only kind a list lane can list. */
+type ListableDeclaration = KindDeclaration & { readonly schema: DescMessage };
+
 export interface BuiltInListReadScopeDeps {
   readonly store: Store;
   /** The port the grant path writes through — the person's rows are read from the same instance. */
@@ -153,8 +160,12 @@ export function newBuiltInListReadScope(
     return kept;
   }
 
-  /** The declaration a verb evaluates against; an undeclared kind is the evaluator's own fault, raised before any read. */
-  function requireDeclared(kind: ApiResourceKind): KindDeclaration {
+  /**
+   * The declaration a verb evaluates against, which must be a kind with
+   * stored rows. An undeclared kind, or a rowless one, is the evaluator's
+   * own fault, raised before any read.
+   */
+  function requireListable(kind: ApiResourceKind): ListableDeclaration {
     const declaration = model.byKind(kind);
     if (declaration === undefined) {
       throw new AuthorizationEvaluationError(
@@ -162,11 +173,18 @@ export function newBuiltInListReadScope(
         `no declaration for kind '${kindEnumName(kind)}' — a list lane asked the scope about a kind the model does not declare`,
       );
     }
-    return declaration;
+    const schema = declaration.schema;
+    if (schema === undefined) {
+      throw new AuthorizationEvaluationError(
+        "undeclared-target-kind",
+        `kind '${kindEnumName(kind)}' has no stored rows — a list lane asked the scope about a rowless kind`,
+      );
+    }
+    return { ...declaration, schema };
   }
 
   /** Every row of `kind` the store holds, as facts; a row that does not decode is skipped. */
-  async function everyRowOf(declaration: KindDeclaration): Promise<RowFacts[]> {
+  async function everyRowOf(declaration: ListableDeclaration): Promise<RowFacts[]> {
     const kind = declaration.kind;
     const rows = await deps.store.listResources(kind);
     const facts: RowFacts[] = [];
@@ -189,12 +207,9 @@ export function newBuiltInListReadScope(
       kind: ApiResourceKind,
       entries: ReadonlyArray<ListEntryMeta>,
     ): Promise<ReadonlySet<string>> {
-      requireDeclared(kind);
+      requireListable(kind);
       if (caller.callerClass === "internal") {
-        throw new AuthorizationEvaluationError(
-          "internal-caller-offered",
-          `the internal caller class was offered to the list scope for kind '${kindEnumName(kind)}' — the shared helper answers that class before any driver; a list lane reached the driver around it`,
-        );
+        throw new InternalCallerOfferedError(kind);
       }
       // One candidate per unique id: a lane offers each row once, and a
       // duplicate would only spend a walk to learn the same answer.
@@ -211,7 +226,7 @@ export function newBuiltInListReadScope(
       caller: CallerIdentity,
       kind: ApiResourceKind,
     ): Promise<ReadonlySet<string>> {
-      const candidates = await everyRowOf(requireDeclared(kind));
+      const candidates = await everyRowOf(requireListable(kind));
       if (caller.callerClass === "internal") {
         return new Set(candidates.map((facts) => facts.id));
       }