@stigmer/server 3.27.1 → 3.28.0

package/src/authorization/__tests__/derived-tuples.test.ts

@@ -14,6 +14,10 @@
  * source, an absent object answering nothing, a store fault propagating
  * as the fault it is — the ratified store-fault mapping, which is what
  * lets the driver above fold it to `unavailable` and never to a denial.
+ * Its grants-to-teams arm evaluates the built-in model's Enterprise team
+ * type: a grant to a team reaches its members and nobody
+ * who left the organization, and a person in no team — every open-source
+ * caller — still costs the source exactly one read.
  */
 import { create } from "@bufbuild/protobuf";
 import { afterAll, afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -40,20 +44,12 @@ import { deriveTuples, newDerivedTupleSource } from "../derived-tuples.js";
 import { checkRelation } from "../evaluator.js";
 import { rowFactsOf } from "../facts.js";
 import { builtInModel } from "../model/index.js";
-import type { KindDeclaration } from "../model/rewrite.js";
 import type { Person } from "../tuples.js";
 import { formatTuple, parseObjectRef } from "../tuples.js";
 import { driverFixtures, dropPostgresFixture } from "./drivers.js";
 import type { OpenedStore } from "./drivers.js";
-import { fixtureRow } from "./support.js";
-
-function declared(type: string): KindDeclaration {
-  const declaration = builtInModel.byType(type);
-  if (declaration === undefined) {
-    throw new Error(`${type} is declared in this slice`);
-  }
-  return declaration;
-}
+import { fixtureRow, storedDeclaration } from "./support.js";
+import type { StoredKindDeclaration } from "./support.js";
 
 function derivedFor(
   type: string,
@@ -64,7 +60,7 @@ function derivedFor(
     spec?: Readonly<Record<string, unknown>>;
   },
 ): string[] {
-  const declaration = declared(type);
+  const declaration = storedDeclaration(type);
   const row = fixtureRow(declaration, {
     id: `${type}-1`,
     org: facts.org ?? "acme",
@@ -244,6 +240,7 @@ const SEEDED_KINDS: ReadonlyArray<ApiResourceKind> = [
   ApiResourceKind.workflow_instance,
   ApiResourceKind.workflow_execution,
   ApiResourceKind.identity_account,
+  ApiResourceKind.team,
 ];
 
 afterAll(dropPostgresFixture);
@@ -295,7 +292,7 @@ describe.each(driverFixtures(SEEDED_KINDS))(
         opened = await fixture.open();
         counted = countingPolicies(newResourceIamPolicyStore(opened.store));
         accounts = newResourceIdentityAccountStore(opened.store);
-        const organization = declared("organization");
+        const organization = storedDeclaration("organization");
         await opened.store.saveResource(
           ApiResourceKind.organization,
           "acme",
@@ -307,7 +304,7 @@ describe.each(driverFixtures(SEEDED_KINDS))(
             createdBy: ROOT.accountId,
           }),
         );
-        const agent = declared("agent");
+        const agent = storedDeclaration("agent");
         await opened.store.saveResource(
           ApiResourceKind.agent,
           "agt_team",
@@ -433,17 +430,28 @@ describe.each(driverFixtures(SEEDED_KINDS))(
         ).toEqual([]);
       });
 
-      it("an absent object, or an object of a kind this edition does not declare, answers no tuples", async () => {
+      it("an absent object, a declared kind this edition stores no row of, a rowless kind, or a kind the model does not declare answers no tuples", async () => {
         const source = sourceFor(ROOT);
         expect(
           await source.tuplesOf(parseObjectRef("agent:agt_missing"), "owner"),
         ).toEqual([]);
+        // Declared, served by the wider editions: the store has no such row.
         expect(
           await source.tuplesOf(
             parseObjectRef("identity_provider:idp"),
             "owner",
           ),
         ).toEqual([]);
+        // Rowless: no row is loaded for it at all.
+        expect(
+          await source.tuplesOf(parseObjectRef("platform:stigmer"), "operator"),
+        ).toEqual([]);
+        expect(
+          await source.tuplesOf(
+            parseObjectRef("api_resource_version:v1"),
+            "owner",
+          ),
+        ).toEqual([]);
         expect(
           await source.tuplesOf(parseObjectRef("nonsense:x"), "owner"),
         ).toEqual([]);
@@ -462,7 +470,7 @@ describe.each(driverFixtures(SEEDED_KINDS))(
 
       it("a source seeded with a candidate's facts derives that object's tuples WITHOUT loading its row; the parent hop still loads", async () => {
         let rowReads = 0;
-        const agent = declared("agent");
+        const agent = storedDeclaration("agent");
         const seeded = newDerivedTupleSource(
           {
             store: {
@@ -517,7 +525,7 @@ describe.each(driverFixtures(SEEDED_KINDS))(
         // carry, so the rule loads the row — one read, stated in the list
         // scope's cost pin as well.
         let rowReads = 0;
-        const instance = declared("agent_instance");
+        const instance = storedDeclaration("agent_instance");
         const row = fixtureRow(instance, {
           id: "ai_seeded",
           org: "acme",
@@ -567,6 +575,173 @@ describe.each(driverFixtures(SEEDED_KINDS))(
       });
     });
 
+    /**
+     * The grants made to a person's teams, through the real source and the
+     * evaluator over the built-in model's Enterprise team type. Seeded:
+     * `acme` with Dave a member and Root its owner; `tm_core` and
+     * `tm_other` in `acme`; Dave and Erin granted `member` on `tm_core`,
+     * Erin holding no organization role (she left); `agt_core` shared with
+     * `tm_core#member` and `agt_other` with `tm_other#member`, both private
+     * and Carol's.
+     */
+    describe.skipIf(fixture.skip)("the grants made to a person's teams", () => {
+      let opened: OpenedStore;
+      let counted: ReturnType<typeof countingPolicies>;
+      const ERIN: Person = {
+        accountId: "ida_erin",
+        aliases: new Set(["ida_erin"]),
+      };
+
+      async function seed(
+        declaration: StoredKindDeclaration,
+        facts: Parameters<typeof fixtureRow>[1],
+      ): Promise<void> {
+        await opened.store.saveResource(
+          declaration.kind,
+          facts.id,
+          declaration.schema,
+          fixtureRow(declaration, facts),
+        );
+      }
+
+      beforeEach(async () => {
+        opened = await fixture.open();
+        counted = countingPolicies(newResourceIamPolicyStore(opened.store));
+        await seed(storedDeclaration("organization"), {
+          id: "acme",
+          org: "",
+          visibility: ApiResourceVisibility.visibility_private,
+          createdBy: ROOT.accountId,
+        });
+        for (const id of ["tm_core", "tm_other"]) {
+          await seed(storedDeclaration("team"), {
+            id,
+            org: "acme",
+            visibility: ApiResourceVisibility.visibility_private,
+            createdBy: ROOT.accountId,
+          });
+        }
+        for (const [id, team] of [
+          ["agt_core", "tm_core"],
+          ["agt_other", "tm_other"],
+        ] as const) {
+          await seed(storedDeclaration("agent"), {
+            id,
+            org: "acme",
+            visibility: ApiResourceVisibility.visibility_private,
+            createdBy: "ida_carol",
+          });
+          await grant(
+            counted.policies,
+            triple({ kind: "team", id: team, relation: "member" }, "viewer", {
+              kind: "agent",
+              id,
+            }),
+          );
+        }
+        await grant(counted.policies, orgRole(ROOT.accountId, "owner", "acme"));
+        await grant(
+          counted.policies,
+          orgRole(DAVE.accountId, "member", "acme"),
+        );
+        for (const member of [DAVE, ERIN]) {
+          await grant(
+            counted.policies,
+            triple(
+              { kind: "identity_account", id: member.accountId },
+              "member",
+              { kind: "team", id: "tm_core" },
+            ),
+          );
+        }
+      });
+
+      afterEach(async () => {
+        await opened.close();
+      });
+
+      function sourceFor(person: Person) {
+        return newDerivedTupleSource(
+          {
+            store: opened.store,
+            policies: counted.policies,
+            accounts: newResourceIdentityAccountStore(opened.store),
+            model: builtInModel,
+          },
+          person,
+        );
+      }
+
+      async function allowed(
+        person: Person,
+        object: string,
+        relation: string,
+      ): Promise<boolean> {
+        return checkRelation(
+          { model: builtInModel, source: sourceFor(person) },
+          parseObjectRef(object),
+          relation,
+          person,
+        );
+      }
+
+      it("a grant to a team reaches its member: the source serves the team's row on the object, and the member views it", async () => {
+        expect(
+          (
+            await sourceFor(DAVE).tuplesOf(
+              parseObjectRef("agent:agt_core"),
+              "viewer",
+            )
+          ).map(formatTuple),
+        ).toEqual(["agent:agt_core#viewer@team:tm_core#member"]);
+        expect(await allowed(DAVE, "agent:agt_core", "can_view")).toBe(true);
+      });
+
+      it("a member who left the organization reads the team's rows and is admitted by none of them — the model's bound, not a cleanup", async () => {
+        expect(
+          (
+            await sourceFor(ERIN).tuplesOf(
+              parseObjectRef("agent:agt_core"),
+              "viewer",
+            )
+          ).map(formatTuple),
+        ).toEqual(["agent:agt_core#viewer@team:tm_core#member"]);
+        expect(await allowed(ERIN, "agent:agt_core", "can_view")).toBe(false);
+      });
+
+      it("a grant to a team the person is not in never enters their source", async () => {
+        expect(
+          await sourceFor(DAVE).tuplesOf(
+            parseObjectRef("agent:agt_other"),
+            "viewer",
+          ),
+        ).toEqual([]);
+        expect(await allowed(DAVE, "agent:agt_other", "can_view")).toBe(false);
+        expect(await allowed(ROOT, "agent:agt_core", "can_view")).toBe(true);
+      });
+
+      it("reads once for a person in no team and once more per team held, however many objects are asked", async () => {
+        const root = sourceFor(ROOT);
+        await root.tuplesOf(parseObjectRef("agent:agt_core"), "viewer");
+        await root.tuplesOf(parseObjectRef("agent:agt_other"), "viewer");
+        expect(counted.reads()).toBe(1);
+        const dave = sourceFor(DAVE);
+        await dave.tuplesOf(parseObjectRef("agent:agt_core"), "viewer");
+        await dave.tuplesOf(parseObjectRef("agent:agt_other"), "viewer");
+        await dave.tuplesOf(parseObjectRef("organization:acme"), "member");
+        expect(counted.reads()).toBe(1 + 2);
+      });
+
+      it("personTuples stays the person's own rows — the organization directory's candidates do not grow with team grants", async () => {
+        expect(
+          (await sourceFor(DAVE).personTuples()).map(formatTuple).sort(),
+        ).toEqual([
+          "organization:acme#member@identity_account:ida_dave",
+          "team:tm_core#member@identity_account:ida_dave",
+        ]);
+      });
+    });
+
     /**
      * The two derived rules through the real source and the evaluator:
      * `default_of` from the blueprint's pointer, `execution_viewer` from
@@ -589,7 +764,7 @@ describe.each(driverFixtures(SEEDED_KINDS))(
         id: string,
         facts: Omit<Parameters<typeof fixtureRow>[1], "id">,
       ): Promise<void> {
-        const declaration = declared(type);
+        const declaration = storedDeclaration(type);
         await opened.store.saveResource(
           declaration.kind,
           id,

package/src/authorization/__tests__/evaluator.test.ts

@@ -1,19 +1,20 @@
 /**
  * Pins the evaluator's semantics the store tests cannot express (the
- * cloud's `.fga.yaml` documents prove the model's answers; this file
- * proves the machinery under them): how a person matches a tuple, that a
- * direct tuple outside the line's type restriction is ignored (model drift
- * fails closed), how far a resolution may walk, that an intersection
- * holds only while every member does (the team bound) and stops at its
- * first false member, that `declareKind` refuses a line a `.fga` file
- * could not hold, and that a declaration cycle or an undeclared target is
- * a thrown fault and never a silent deny.
+ * model's `.fga.yaml` suites prove its answers; this file proves the
+ * machinery under them): how a person matches a tuple, that a direct
+ * tuple outside the line's type restriction is ignored (model drift fails
+ * closed), how far a resolution may walk, that an intersection holds only
+ * while every member does (the team bound) and stops at its first false
+ * member, and that a declaration cycle or an undeclared target is a
+ * thrown fault and never a silent deny. What the model file may hold is
+ * the reader's to refuse (model/__tests__/openfga-json.test.ts).
  *
  * The fixture source is the in-memory one the store-test kit uses, so the
  * two proofs share one tuple vocabulary. Where a case needs a shape the
- * real model does not have (a cycle, a chain past the depth bound), it
- * declares a throwaway model with `declareKind`; everything else runs
- * over the built-in model so the fixtures are real relations.
+ * real model does not have (a cycle, a chain past the depth bound, a type
+ * the model omits), it declares a throwaway model (throwaway-model.ts);
+ * everything else runs over the built-in model so the fixtures are real
+ * relations.
  */
 import { describe, expect, it } from "vitest";
 
@@ -26,23 +27,21 @@ import {
   checkRelation,
 } from "../evaluator.js";
 import { builtInModel, newModel } from "../model/index.js";
+import type { Person, Tuple, TupleSource } from "../tuples.js";
+import {
+  newInMemoryTupleSource,
+  parseObjectRef,
+  parseSubject,
+} from "../tuples.js";
 import {
   computed,
-  declareKind,
   direct,
   from,
-  intersection,
   objectOf,
+  throwawayDeclaration,
   union,
   usersetOf,
-} from "../model/rewrite.js";
-import type { Rewrite } from "../model/rewrite.js";
-import type { Person, Tuple, TupleSource } from "../tuples.js";
-import {
-  newInMemoryTupleSource,
-  parseObjectRef,
-  parseSubject,
-} from "../tuples.js";
+} from "./throwaway-model.js";
 
 /** `object#relation@subject` in the FGA tuple notation, the fixtures' own spelling. */
 function tuple(text: string): Tuple {
@@ -157,13 +156,13 @@ describe("relations and kinds the model does not declare", () => {
     ).toBe(false);
   });
 
-  it("an undeclared kind as the TARGET is a thrown fault — the driver refused unserved kinds before, so reaching here is a registry gap", async () => {
+  it("an undeclared kind as the TARGET is a thrown fault — the model declares every kind, so reaching here is a registry gap", async () => {
     await expect(
-      allowed(source, "identity_provider:idp", "can_view", person("ida_carol")),
+      allowed(source, "api_resource_version:v1", "can_view", person("ida_carol")),
     ).rejects.toMatchObject({ reason: "undeclared-target-kind" });
   });
 
-  it("an undeclared kind reached through a hop yields nothing — `agent.platform_viewer` walks `identity_provider#platform_user`", async () => {
+  it("a declared kind reached through a hop with no tuple on it yields nothing — `agent.platform_viewer` walks `identity_provider#platform_user`", async () => {
     const platform = newInMemoryTupleSource([
       tuple("agent:p#organization@organization:acme"),
       tuple("agent:p#platform_viewer@identity_provider:idp#platform_user"),
@@ -172,6 +171,30 @@ describe("relations and kinds the model does not declare", () => {
       await allowed(platform, "agent:p", "can_view", person("ida_zed")),
     ).toBe(false);
   });
+
+  it("a type the model omits, reached through a hop, is an object with no relations — nothing, never a fault", async () => {
+    const model = newModel([
+      throwawayDeclaration({
+        kind: ApiResourceKind.agent,
+        schema: AgentSchema,
+        relations: [
+          ["viewer", direct(usersetOf("api_resource_version", "member"))],
+          ["can_view", computed("viewer")],
+        ],
+      }),
+    ]);
+    const hop = newInMemoryTupleSource([
+      tuple("agent:p#viewer@api_resource_version:v1#member"),
+    ]);
+    expect(
+      await checkRelation(
+        { model, source: hop },
+        parseObjectRef("agent:p"),
+        "can_view",
+        person("ida_zed"),
+      ),
+    ).toBe(false);
+  });
 });
 
 describe("the walk itself", () => {
@@ -203,10 +226,9 @@ describe("the walk itself", () => {
 
   it("bounds the resolution at OpenFGA's own limit and reports the overrun as a fault", async () => {
     // A chain of `next from link` deeper than the bound, on a throwaway model.
-    const deep = declareKind({
+    const deep = throwawayDeclaration({
       kind: ApiResourceKind.agent,
       schema: AgentSchema,
-      source: "test/deep.fga",
       relations: [
         ["link", direct(objectOf("agent"))],
         [
@@ -230,23 +252,8 @@ describe("the walk itself", () => {
   });
 
   it("an intersection holds only while every member does — a team member reaches a team grant only while still an organization viewer", async () => {
-    // The Enterprise team type, declared here because open source serves
-    // no team: membership bounded by the organization's viewers.
-    const team = declareKind({
-      kind: ApiResourceKind.team,
-      schema: AgentSchema,
-      source: "test/team.fga",
-      relations: [
-        ["organization", direct(objectOf("organization"))],
-        [
-          "member",
-          intersection(
-            direct(objectOf("identity_account")),
-            from("viewer", "organization"),
-          ),
-        ],
-      ],
-    });
+    // The model's Enterprise team type: `member` is a person granted the
+    // role AND still one of the organization's viewers.
     const source = newInMemoryTupleSource([
       tuple("organization:acme#viewer@identity_account:ida_vic"),
       tuple("team:sre#organization@organization:acme"),
@@ -255,10 +262,9 @@ describe("the walk itself", () => {
       tuple("agent:a#organization@organization:acme"),
       tuple("agent:a#viewer@team:sre#member"),
     ]);
-    const model = newModel([...builtInModel.declarations, team]);
     const check = (who: Person): Promise<boolean> =>
       checkRelation(
-        { model, source },
+        { model: builtInModel, source },
         parseObjectRef("agent:a"),
         "can_view",
         who,
@@ -270,21 +276,6 @@ describe("the walk itself", () => {
   });
 
   it("an intersection stops at its first false member — the direct arm is read before the hop that bounds it", async () => {
-    const team = declareKind({
-      kind: ApiResourceKind.team,
-      schema: AgentSchema,
-      source: "test/team.fga",
-      relations: [
-        ["organization", direct(objectOf("organization"))],
-        [
-          "member",
-          intersection(
-            direct(objectOf("identity_account")),
-            from("viewer", "organization"),
-          ),
-        ],
-      ],
-    });
     const asked: string[] = [];
     const inner = newInMemoryTupleSource([
       tuple("team:sre#organization@organization:acme"),
@@ -297,7 +288,7 @@ describe("the walk itself", () => {
     };
     expect(
       await checkRelation(
-        { model: newModel([team]), source: counting },
+        { model: builtInModel, source: counting },
         parseObjectRef("team:sre"),
         "member",
         person("ida_nobody"),
@@ -307,10 +298,9 @@ describe("the walk itself", () => {
   });
 
   it("a declaration that re-enters itself on one object is a cycle fault, never a silent false", async () => {
-    const cyclic = declareKind({
+    const cyclic = throwawayDeclaration({
       kind: ApiResourceKind.agent,
       schema: AgentSchema,
-      source: "test/cyclic.fga",
       relations: [
         ["a", computed("b")],
         ["b", computed("a")],
@@ -326,100 +316,3 @@ describe("the walk itself", () => {
     ).rejects.toBeInstanceOf(AuthorizationEvaluationError);
   });
 });
-
-describe("declareKind validates a transcript at load", () => {
-  it("refuses a computed or tupleset reference to a relation the kind does not declare", () => {
-    expect(() =>
-      declareKind({
-        kind: ApiResourceKind.agent,
-        schema: AgentSchema,
-        source: "test/bad.fga",
-        relations: [["can_view", computed("viewer")]],
-      }),
-    ).toThrow("relation 'viewer'");
-    expect(() =>
-      declareKind({
-        kind: ApiResourceKind.agent,
-        schema: AgentSchema,
-        source: "test/bad.fga",
-        relations: [["owner", from("admin", "organization")]],
-      }),
-    ).toThrow("tupleset 'organization'");
-  });
-
-  it("refuses a relation declared twice", () => {
-    expect(() =>
-      declareKind({
-        kind: ApiResourceKind.agent,
-        schema: AgentSchema,
-        source: "test/bad.fga",
-        relations: [
-          ["viewer", direct(objectOf("identity_account"))],
-          ["viewer", direct(usersetOf("organization", "viewer"))],
-        ],
-      }),
-    ).toThrow("declared twice");
-  });
-
-  it("refuses a line no .fga file could hold without parentheses, and an operator over one member", () => {
-    const declare = (rewrite: Rewrite) =>
-      declareKind({
-        kind: ApiResourceKind.agent,
-        schema: AgentSchema,
-        source: "test/bad.fga",
-        relations: [
-          ["organization", direct(objectOf("organization"))],
-          ["viewer", rewrite],
-        ],
-      });
-    expect(() =>
-      declare(
-        intersection(
-          union(direct(objectOf("identity_account")), computed("organization")),
-          from("viewer", "organization"),
-        ),
-      ),
-    ).toThrow("nests or inside and");
-    expect(() =>
-      declare(
-        union(
-          intersection(
-            direct(objectOf("identity_account")),
-            from("viewer", "organization"),
-          ),
-          computed("organization"),
-        ),
-      ),
-    ).toThrow("nests and inside or");
-    expect(() =>
-      declare(intersection(direct(objectOf("identity_account")))),
-    ).toThrow("fewer than two members");
-    expect(() =>
-      declare(
-        intersection(
-          direct(objectOf("identity_account")),
-          from("viewer", "organization"),
-        ),
-      ),
-    ).not.toThrow();
-  });
-
-  it("carries the FGA type name of its kind and its relations in file order", () => {
-    const declaration = declareKind({
-      kind: ApiResourceKind.mcp_server,
-      schema: AgentSchema,
-      source: "test/order.fga",
-      relations: [
-        ["organization", direct(objectOf("organization"))],
-        ["owner", direct(usersetOf("organization", "admin"))],
-        ["can_edit", computed("owner")],
-      ],
-    });
-    expect(declaration.type).toBe("mcp_server");
-    expect([...declaration.relations.keys()]).toEqual([
-      "organization",
-      "owner",
-      "can_edit",
-    ]);
-  });
-});

package/src/authorization/__tests__/facts.test.ts

@@ -36,7 +36,7 @@ import {
 } from "../../pipeline/steps/authorization-tuples.js";
 import { rowFactsOf, rowFactsOfEntry } from "../facts.js";
 import { builtInModel } from "../model/index.js";
-import { fixtureRow } from "./support.js";
+import { fixtureRow, hasStoredRows, storedDeclaration } from "./support.js";
 
 const CREATOR: CallerIdentity = {
   identityId: "ida_carol",
@@ -46,7 +46,7 @@ const CREATOR: CallerIdentity = {
 };
 
 describe("rowFactsOf against the tuple lifecycle's own resolution", () => {
-  for (const declaration of builtInModel.declarations) {
+  for (const declaration of builtInModel.declarations.filter(hasStoredRows)) {
     for (const visibility of [
       ApiResourceVisibility.visibility_private,
       ApiResourceVisibility.visibility_org,
@@ -77,10 +77,7 @@ describe("rowFactsOf against the tuple lifecycle's own resolution", () => {
   }
 
   it("carries a legacy row's missing organization as no scope link, where the create-time resolver throws", () => {
-    const agent = builtInModel.byType("agent");
-    if (agent === undefined) {
-      throw new Error("agent is declared in this slice");
-    }
+    const agent = storedDeclaration("agent");
     const row = fixtureRow(agent, {
       id: "agent-legacy",
       org: "",
@@ -94,10 +91,7 @@ describe("rowFactsOf against the tuple lifecycle's own resolution", () => {
   });
 
   it("reads an absent creator stamp as the empty string", () => {
-    const agent = builtInModel.byType("agent");
-    if (agent === undefined) {
-      throw new Error("agent is declared in this slice");
-    }
+    const agent = storedDeclaration("agent");
     const bare = create(agent.schema, {
       metadata: { id: "agent-bare", org: "acme" },
     });
@@ -129,7 +123,7 @@ describe("a list candidate against the loaded row — the facts' two producers",
     return offered;
   }
 
-  for (const declaration of builtInModel.declarations) {
+  for (const declaration of builtInModel.declarations.filter(hasStoredRows)) {
     for (const visibility of [
       ApiResourceVisibility.visibility_private,
       ApiResourceVisibility.visibility_org,