@stigmer/server 3.40.0 → 3.41.0

package/src/authorization/authorizer.ts

@@ -64,6 +64,7 @@ import type {
   AuthzDecision,
 } from "../extensions/authorizer.js";
 import type { CallerIdentity } from "../extensions/identity.js";
+import type { ResourceRowReader } from "../extensions/resource-row-reader.js";
 import {
   kindEnumName,
   kindServedByEdition,
@@ -81,15 +82,18 @@ import { formatObjectRef } from "./tuples.js";
 /**
  * Kinds whose missing row is a denial, never `not-found` (arm 4): the
  * cloud's `PROBE_EXEMPT_KINDS` (stigmer-cloud
- * src/authorizer/fga-authorizer.ts) restricted to the kinds this edition
- * serves — `platform`, `identity_provider` and `invitation` are refused by
- * arm 2 before any row is asked about. The cloud exempts them because
- * their rows live in its own tables, out of its probe's reach; matching
- * the set here keeps the wire identical across editions (an unknown
- * platform client's id is PERMISSION_DENIED with the annotation's copy in
- * both). The cloud pins every kind here inside its own
- * `PROBE_EXEMPT_KINDS`, which is why this set is exported; a kind that
- * moves into open source joins this set in the same change.
+ * src/authorizer/fga-authorizer.ts), the same set. The cloud exempts them
+ * because their rows live in its own tables, out of its probe's reach;
+ * matching the set here keeps the wire identical across editions (an
+ * unknown platform client's id is PERMISSION_DENIED with the annotation's
+ * copy in both), so a member cannot learn which provider, invitation or
+ * team ids exist in an organization they may not read. In open source,
+ * `platform`, `identity_provider`, `invitation` and `team` are refused by
+ * arm 2 before any row is asked about, so their entries matter only to an
+ * edition that serves them. `platform` also has no row at all
+ * (model/bindings.ts, ROWLESS): outside this set every check on it would
+ * answer not-found without evaluating. The cloud pins every kind here
+ * inside its own `PROBE_EXEMPT_KINDS`, which is why this set is exported.
  *
  * `iam_policy` is reachable as a target through the IamPolicy RPCs' own
  * `resource.kind` (a caller may name it); the grant scope refuses such a
@@ -97,9 +101,13 @@ import { formatObjectRef } from "./tuples.js";
  * keeps the wire the same on the way there.
  */
 export const NOT_FOUND_EXEMPT_KINDS: ReadonlySet<ApiResourceKind> = new Set([
+  ApiResourceKind.platform,
   ApiResourceKind.identity_account,
+  ApiResourceKind.identity_provider,
   ApiResourceKind.iam_policy,
   ApiResourceKind.platform_client,
+  ApiResourceKind.invitation,
+  ApiResourceKind.team,
 ]);
 
 /** The Java RequestAuthorizationService's pre-check copy, byte for byte (the cloud renders the same). */
@@ -121,9 +129,11 @@ export interface BuiltInAuthorizerDeps {
   readonly policies: IamPolicyStore;
   /** The account port: the caller's account, and identity_account targets. */
   readonly accounts: AccountsByCaller;
-  /** The served edition (`extensions.edition`); the built-in posture pins it to `oss` at boot. */
+  /** The served edition (`extensions.edition`); above `oss`, boot has checked every served kind's rows are readable. */
   readonly edition: ServerEdition;
   readonly logger: Logger;
+  /** The readers of the kinds units keep themselves (`drivers.resourceRowReaders`), handed to every tuple source. */
+  readonly rowReaders?: ReadonlyMap<ApiResourceKind, ResourceRowReader>;
   /** The declarations to evaluate; the built-in model unless a test says otherwise. */
   readonly model?: Model;
 }
@@ -163,6 +173,7 @@ export function newBuiltInAuthorizer(deps: BuiltInAuthorizerDeps): Authorizer {
             store: deps.store,
             policies: deps.policies,
             accounts: deps.accounts,
+            rowReaders: deps.rowReaders,
             model,
           },
           person,

package/src/authorization/derived-tuples.ts

@@ -45,6 +45,10 @@
  *     organization`), so a person who left the organization reads the
  *     team's rows and is admitted by none of them.
  *
+ * A check about an object rather than a person (an organization asked
+ * whether a resource is its own, authorization/policy-check.ts) reads the
+ * rows that name that object directly, and holds no team.
+ *
  * 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
@@ -71,15 +75,19 @@
  * spec fields the facts do not carry), so listing the two instance kinds
  * costs one row read per candidate, stated in the scope's cost pins.
  *
- * Rows are read through the generic Store, with one exception: an
- * `identity_account` object is read through the account PORT
- * (`accounts.findById`), the binding every other reader of accounts —
- * the verifiers, whoAmI, the create path — follows. A composition that
- * registers its own account store and keeps the built-in authorizer
- * therefore still lets a person read their own account (the derivation
- * is `owner@self`); a generic read would miss and deny them their own
- * row. IamPolicy rows are already the port's (`findByPrincipal`), so no
- * second exception is needed for them.
+ * A row is read where the composition keeps it. Open source's kinds are
+ * read through the generic Store. An `identity_account` object is read
+ * through the account PORT (`accounts.findById`), the binding every other
+ * reader of accounts — the verifiers, whoAmI, the create path — follows:
+ * a composition that registers its own account store and keeps the
+ * built-in authorizer therefore still lets a person read their own
+ * account (the derivation is `owner@self`), where a generic read would
+ * miss and deny them their own row. A kind a unit keeps in a store of its
+ * own (an identity provider, an invitation, a team, in the editions that
+ * serve them) is read through the reader the unit registered for it
+ * (`rowReaders`, extensions/resource-row-reader.ts), so a team a grant
+ * names resolves its organization from the row its unit wrote. IamPolicy
+ * rows are already the port's (`findByPrincipal`), so they need no reader.
  */
 import type { Message } from "@bufbuild/protobuf";
 
@@ -91,6 +99,7 @@ import { isPersonStamp } from "../domain/iampolicy/membership.js";
 import type { IamPolicyStore } from "../domain/iampolicy/store.js";
 import type { IdentityAccountStore } from "../domain/identityaccount/store.js";
 import type { VisibilityTupleShape } from "../extensions/resource-authorization.js";
+import type { ResourceRowReader } from "../extensions/resource-row-reader.js";
 import {
   getKindMeta,
   kindByEnumName,
@@ -105,13 +114,13 @@ import type { Model } from "./model/index.js";
 import { builtInModel } from "./model/index.js";
 import type {
   ObjectRef,
-  Person,
+  Principal,
   RowLoader,
   Subject,
   Tuple,
   TupleSource,
 } from "./tuples.js";
-import { ACCOUNT_TYPE, formatObjectRef } from "./tuples.js";
+import { ACCOUNT_TYPE, formatObjectRef, isPerson } from "./tuples.js";
 
 /**
  * Kinds whose `[identity_account]` owner is recorded as an IamPolicy row
@@ -123,6 +132,10 @@ export const ROW_RECORDED_OWNER_KINDS: ReadonlySet<ApiResourceKind> = new Set([
   ApiResourceKind.organization,
 ]);
 
+/** The organization type, and the relation that stands while a person holds a role on it (tenancy/organization.fga). */
+const ORGANIZATION_TYPE = kindEnumName(ApiResourceKind.organization);
+const AFFILIATED_RELATION = "affiliated";
+
 /** 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";
@@ -223,6 +236,8 @@ export interface DerivedTupleSourceDeps {
   readonly policies: IamPolicyStore;
   /** The account port — an `identity_account` object is read through it, never the generic Store (the module header). */
   readonly accounts: Pick<IdentityAccountStore, "findById">;
+  /** The readers of the kinds units keep themselves (`drivers.resourceRowReaders`); absent, every other row is the generic Store's. */
+  readonly rowReaders?: ReadonlyMap<ApiResourceKind, ResourceRowReader>;
   /** The declarations to derive with; the built-in model unless a test says otherwise. */
   readonly model?: Model;
 }
@@ -231,7 +246,8 @@ export interface DerivedTupleSource extends TupleSource {
   /** The memoised row reads, exposed for a declaration's `derived` rules and for tests. */
   readonly loader: RowLoader;
   /**
-   * The person's own IamPolicy rows as tuples — the ONE read of them this
+   * The person's own IamPolicy rows as tuples, each organization role with
+   * the organization's `affiliated` tuple it stands for — 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. The rows granted
@@ -248,7 +264,7 @@ export interface DerivedTupleSourceSeed {
 
 export function newDerivedTupleSource(
   deps: DerivedTupleSourceDeps,
-  person: Person,
+  principal: Principal,
   seed?: DerivedTupleSourceSeed,
 ): DerivedTupleSource {
   const model = deps.model ?? builtInModel;
@@ -307,9 +323,13 @@ export function newDerivedTupleSource(
 
   function rowTuples(): Promise<ReadonlyArray<Tuple>> {
     if (personRows === undefined) {
-      personRows = deps.policies
-        .findByPrincipal(ACCOUNT_TYPE, person.accountId)
-        .then((found) => found.map(tupleOfRow));
+      personRows = isPerson(principal)
+        ? deps.policies
+            .findByPrincipal(ACCOUNT_TYPE, principal.accountId)
+            .then((found) => found.flatMap(tuplesOfPersonRow))
+        : deps.policies
+            .findByPrincipal(principal.object.type, principal.object.id)
+            .then((found) => found.filter(isDirectGrant).map(tupleOfRow));
     }
     return personRows;
   }
@@ -357,7 +377,10 @@ export function newDerivedTupleSource(
       const fromRows =
         (await reachableTuples()).get(pairKey(object, relation)) ?? [];
       const declaration = model.byType(object.type);
-      if (declaration === undefined) {
+      if (declaration === undefined || isAffiliation(object, relation)) {
+        // An organization's `affiliated` tuples are the person's rows'
+        // (tuplesOfPersonRow); the organization's own row derives none, so
+        // it is not read for them.
         return fromRows;
       }
       const fromRow = (await derivedTuplesOf(object)).filter(onPair);
@@ -378,7 +401,7 @@ export function newDerivedTupleSource(
  * the row does not exist.
  */
 async function loadRow(
-  deps: Pick<DerivedTupleSourceDeps, "store" | "accounts">,
+  deps: Pick<DerivedTupleSourceDeps, "store" | "accounts" | "rowReaders">,
   model: Model,
   object: ObjectRef,
 ): Promise<Message | undefined> {
@@ -395,6 +418,10 @@ async function loadRow(
   if (kind === ApiResourceKind.identity_account) {
     return deps.accounts.findById(object.id);
   }
+  const reader = deps.rowReaders?.get(kind);
+  if (reader !== undefined) {
+    return reader.findById(object.id);
+  }
   try {
     return await deps.store.getResource(kind, object.id, declaration.schema);
   } catch (error) {
@@ -405,6 +432,15 @@ async function loadRow(
   }
 }
 
+/**
+ * Whether a row names its principal directly (`organization:o`), not as a
+ * userset (`organization:o#member`): the rows an object principal itself
+ * holds. A userset row grants the object's members, never the object.
+ */
+function isDirectGrant(row: IamPolicy): boolean {
+  return (row.spec?.principal?.relation ?? "") === "";
+}
+
 /** The key a tuple is served under: its object and relation. */
 function pairKey(object: ObjectRef, relation: string): string {
   return `${formatObjectRef(object)}#${relation}`;
@@ -426,6 +462,44 @@ function indexByPair(
   return index;
 }
 
+/** Whether the pair is an organization's `affiliated`, which only the person's rows carry. */
+function isAffiliation(object: ObjectRef, relation: string): boolean {
+  return object.type === ORGANIZATION_TYPE && relation === AFFILIATED_RELATION;
+}
+
+/**
+ * A row of the person's as the tuples it stands for: the tuple it records,
+ * and, for a role on an organization, the organization's `affiliated`
+ * tuple. `affiliated` is stored in the model so its bound costs one read
+ * (fga/model/tenancy/organization.fga); it stands exactly while the person
+ * holds a row on the organization, and this edition derives it from those
+ * rows here, in the same one read, where an edition that stores tuples
+ * writes it from the grant path's affiliation announcements. A row that
+ * names a userset (a team's members) is not the person's role and stands
+ * for no affiliation.
+ */
+function tuplesOfPersonRow(row: IamPolicy): ReadonlyArray<Tuple> {
+  const recorded = tupleOfRow(row);
+  const principal = row.spec?.principal;
+  if (
+    recorded.object.type !== ORGANIZATION_TYPE ||
+    recorded.object.id === "" ||
+    principal === undefined ||
+    principal.kind !== ACCOUNT_TYPE ||
+    principal.relation !== ""
+  ) {
+    return [recorded];
+  }
+  return [
+    recorded,
+    {
+      object: recorded.object,
+      relation: AFFILIATED_RELATION,
+      subject: account(principal.id),
+    },
+  ];
+}
+
 /** 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

@@ -1,10 +1,13 @@
 /**
  * The evaluator — OpenFGA's check, over the built-in model and a tuple
  * source, small because the model uses five rewrite forms and nothing
- * else (model/rewrite.ts). `checkRelation(object, relation, person)`
- * answers "does this person hold this relation on this object" the way
- * the cloud's engine answers it over stored tuples, so the two editions
- * share one meaning of authorization. There is no context parameter: the
+ * else (model/rewrite.ts). `checkRelation(object, relation, principal)`
+ * answers "does this person (or this object) hold this relation on this
+ * object" the way the cloud's engine answers it over stored tuples, so the
+ * two editions share one meaning of authorization. The principal is
+ * almost always a person; an object principal (an organization) is how a
+ * unit asks the structural questions the cloud asks its engine, such as
+ * whether a resource belongs to an organization. There is no context parameter: the
  * model declares no condition, so a check has no posture to state.
  *
  * The walk, in the order a `.fga` line reads:
@@ -12,7 +15,8 @@
  *     its subject's TYPE is in the line's restriction list — the check
  *     OpenFGA makes at write time, made here at read time, so a derived
  *     tuple the model no longer admits denies instead of allowing. An
- *     object subject matches when it names one of the person's aliases;
+ *     object subject matches a person when it is an account naming one of
+ *     their aliases, and an object principal when it is that very object;
  *     a userset subject is resolved on its own object.
  *   - `computed`: the same object, another relation.
  *   - `from`: every object the tupleset relation links to (again within
@@ -46,8 +50,8 @@
  */
 import type { Model } from "./model/index.js";
 import type { Rewrite, SubjectType } from "./model/rewrite.js";
-import type { ObjectRef, Person, Subject, TupleSource } from "./tuples.js";
-import { ACCOUNT_TYPE, formatObjectRef, pairKey } from "./tuples.js";
+import type { ObjectRef, Principal, Subject, TupleSource } from "./tuples.js";
+import { ACCOUNT_TYPE, formatObjectRef, isPerson, pairKey } from "./tuples.js";
 
 /**
  * OpenFGA's default resolution-depth limit (its `resolveNodeLimit`), so
@@ -88,7 +92,7 @@ export async function checkRelation(
   deps: EvaluationDeps,
   object: ObjectRef,
   relation: string,
-  person: Person,
+  principal: Principal,
 ): Promise<boolean> {
   if (deps.model.byType(object.type) === undefined) {
     throw new AuthorizationEvaluationError(
@@ -96,7 +100,7 @@ export async function checkRelation(
       `no declaration for kind '${object.type}' (target ${formatObjectRef(object)})`,
     );
   }
-  return new Walk(deps, person).resolve(object, relation, 0);
+  return new Walk(deps, principal).resolve(object, relation, 0);
 }
 
 /** One check's state: the memo and the in-progress set, over one source. */
@@ -106,7 +110,7 @@ class Walk {
 
   constructor(
     private readonly deps: EvaluationDeps,
-    private readonly person: Person,
+    private readonly principal: Principal,
   ) {}
 
   resolve(
@@ -203,7 +207,7 @@ class Walk {
     }
   }
 
-  /** Whether one direct tuple's subject reaches the person, within the line's type restriction. */
+  /** Whether one direct tuple's subject reaches the principal, within the line's type restriction. */
   private async subjectHolds(
     subject: Subject,
     restriction: ReadonlyArray<SubjectType>,
@@ -212,12 +216,10 @@ class Walk {
     switch (subject.form) {
       case "object":
         return (
-          subject.object.type === ACCOUNT_TYPE &&
           restriction.some(
             (allowed) =>
-              allowed.form === "object" && allowed.type === ACCOUNT_TYPE,
-          ) &&
-          this.person.aliases.has(subject.object.id)
+              allowed.form === "object" && allowed.type === subject.object.type,
+          ) && this.isPrincipal(subject.object)
         );
       case "userset":
         return (
@@ -235,6 +237,19 @@ class Walk {
     }
   }
 
+  /** Whether an object subject names the principal: one of a person's aliases on an account, or the object principal itself. */
+  private isPrincipal(object: ObjectRef): boolean {
+    if (isPerson(this.principal)) {
+      return (
+        object.type === ACCOUNT_TYPE && this.principal.aliases.has(object.id)
+      );
+    }
+    return (
+      object.type === this.principal.object.type &&
+      object.id === this.principal.object.id
+    );
+  }
+
   /** The object types the tupleset line admits — `[organization]`, `[session]` — from its `this` nodes. */
   private objectTypesOf(
     object: ObjectRef,

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

@@ -70,6 +70,7 @@ import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apireso
 import type { Logger } from "../boot/logger.js";
 import type { IamPolicyStore } from "../domain/iampolicy/store.js";
 import type { CallerIdentity } from "../extensions/identity.js";
+import type { ResourceRowReader } from "../extensions/resource-row-reader.js";
 import type {
   ListEntryMeta,
   ListReadScope,
@@ -101,6 +102,8 @@ export interface BuiltInListReadScopeDeps {
   /** The account port: the caller's account, and the parent hops that land on one. */
   readonly accounts: AccountsByCaller;
   readonly logger: Logger;
+  /** The readers of the kinds units keep themselves (`drivers.resourceRowReaders`), handed to every tuple source. */
+  readonly rowReaders?: ReadonlyMap<ApiResourceKind, ResourceRowReader>;
   /** The declarations to evaluate; the built-in model unless a test says otherwise. */
   readonly model?: Model;
 }
@@ -126,6 +129,7 @@ export function newBuiltInListReadScope(
         store: deps.store,
         policies: deps.policies,
         accounts: deps.accounts,
+        rowReaders: deps.rowReaders,
         model,
       },
       person,

package/src/authorization/model/__tests__/registry.test.ts

@@ -11,6 +11,11 @@
  *     exactly the four kinds the wider editions serve, so a kind the
  *     contract moves between tiers is a visible diff here;
  *   - a kind is reached by enum and by FGA type name alike;
+ *   - every role a kind's `grantable_roles` lets a person hold is a
+ *     relation of the kind's type whose direct list admits
+ *     `identity_account`, so a grant the step accepts is a tuple the engine
+ *     can store (`authorization_config.proto` states the rule; this holds
+ *     the model to it);
  *   - the relations whose direct list admits a team (`team#member`) are
  *     exactly the roles the kind's `team_grantable_roles` names, a subset
  *     of what a person can be granted and never ownership, so the grant
@@ -283,6 +288,10 @@ function inheritedWholeKinds(): ReadonlyArray<{
   });
 }
 
+function isPerson(subject: SubjectType): boolean {
+  return subject.form === "object" && subject.type === "identity_account";
+}
+
 function isTeamMembers(subject: SubjectType): boolean {
   return subject.form === "userset" && subject.type === "team" && subject.relation === "member";
 }
@@ -371,6 +380,20 @@ describe("the built-in model", () => {
     }
   });
 
+  it("stores every role a kind lets a person hold as a relation that admits the person directly — the model and the contract say one thing", () => {
+    const gaps: string[] = [];
+    for (const declaration of builtInModel.declarations) {
+      for (const role of grantableRolesFor(declaration.kind)) {
+        const relation = IamRole[role];
+        const rewrite = declaration.relations.get(relation);
+        if (rewrite === undefined || !directSubjects(rewrite).some(isPerson)) {
+          gaps.push(`${declaration.type}#${relation}`);
+        }
+      }
+    }
+    expect(gaps.sort()).toEqual([]);
+  });
+
   it("lets a team hold only roles a person can hold on the kind, and never ownership", () => {
     for (const value of ApiResourceKindSchema.values) {
       const kind = value.number as ApiResourceKind;