@stigmer/server 3.27.2 → 3.28.0

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,

package/src/authorization/__tests__/list-read-scope.measure.test.ts

@@ -48,8 +48,8 @@
  *
  * Every shape states what its caller keeps, so a measurement over an
  * evaluator that answered wrongly measures nothing. The model is the
- * built-in one with the Enterprise team type beside it
- * (enterprise-model.ts); the open-source shapes answer the same under it.
+ * built-in one, which declares the Enterprise team type beside the
+ * open-source ones.
  */
 import { create } from "@bufbuild/protobuf";
 import { afterAll, afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -84,8 +84,8 @@ import { newBuiltInListReadScope } from "../list-read-scope.js";
 import type { KindDeclaration } from "../model/rewrite.js";
 import { driverFixtures, dropPostgresFixture } from "./drivers.js";
 import type { OpenedStore } from "./drivers.js";
-import { enterpriseModel, teamDeclaration } from "./enterprise-model.js";
-import { fixtureRow } from "./support.js";
+import { builtInModel } from "../model/index.js";
+import { fixtureRow, storedDeclaration } from "./support.js";
 import type { FixtureRowFacts } from "./support.js";
 
 const MEASURE = process.env["AUTHORIZATION_MEASURE"] === "1";
@@ -143,14 +143,6 @@ function directGrantOn(i: number): boolean {
   return i % 50 === 1;
 }
 
-function declared(type: string): KindDeclaration {
-  const declaration = enterpriseModel.byType(type);
-  if (declaration === undefined) {
-    throw new Error(`${type} is declared`);
-  }
-  return declaration;
-}
-
 function resolved(accountId: string): CallerIdentity {
   return {
     identityId: accountId,
@@ -461,7 +453,7 @@ describe
     let accounts: IdentityAccountStore;
 
     async function save(type: string, facts: FixtureRowFacts): Promise<object> {
-      const declaration = declared(type);
+      const declaration = storedDeclaration(type);
       const row = fixtureRow(declaration, facts);
       await opened.store.saveResource(
         declaration.kind,
@@ -530,8 +522,8 @@ describe
         await opened.store.saveResource(
           ApiResourceKind.team,
           teamId(team),
-          teamDeclaration.schema,
-          fixtureRow(teamDeclaration, {
+          storedDeclaration("team").schema,
+          fixtureRow(storedDeclaration("team"), {
             id: teamId(team),
             org: ORG,
             visibility: ApiResourceVisibility.visibility_private,
@@ -550,7 +542,7 @@ describe
         it(
           `${shape.name} at ${n} rows`,
           async () => {
-            const declaration = declared(shape.kind);
+            const declaration = storedDeclaration(shape.kind);
             const policyRows = await seedPopulation(n);
             for (const parent of shape.parents ?? []) {
               await save(parent.type, parent.facts);
@@ -568,7 +560,7 @@ describe
               policies,
               accounts,
               logger: silentLogger,
-              model: enterpriseModel,
+              model: builtInModel,
             });
             const started = performance.now();
             const kept =
@@ -599,7 +591,7 @@ describe
       it(
         `pages: ${shape.name}, at a ${PAGE_POPULATION}-row population`,
         async () => {
-          const declaration = declared("agent");
+          const declaration = storedDeclaration("agent");
           const policyRows = await seedPopulation(PAGE_POPULATION);
           const entries: ListEntryMeta[] = [];
           for (let i = 0; i < PAGE_EXAMINE_BUDGET; i += 1) {
@@ -614,7 +606,7 @@ describe
             policies,
             accounts,
             logger: silentLogger,
-            model: enterpriseModel,
+            model: builtInModel,
           });
           const caller = resolved(shape.caller);
           // A page's batches run one after another, each through the scope
@@ -659,7 +651,7 @@ describe
               accounts,
               edition: ServerEdition.oss,
               logger: silentLogger,
-              model: enterpriseModel,
+              model: builtInModel,
             });
             const check = {
               permission: IamPermission.can_view,

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

@@ -53,7 +53,10 @@ import type {
   ListEntryMeta,
   ListReadScope,
 } from "../../extensions/list-read-scope.js";
-import { restrictListByReadScope } from "../../extensions/list-read-scope.js";
+import {
+  InternalCallerOfferedError,
+  restrictListByReadScope,
+} from "../../extensions/list-read-scope.js";
 import { kindEnumName } from "../../pipeline/apiresource-meta.js";
 import { rowAuthorizationFactsOf } from "../../pipeline/steps/authorization-facts.js";
 import type { Store } from "../../store/interface.js";
@@ -63,7 +66,7 @@ import { builtInModel } from "../model/index.js";
 import type { KindDeclaration } from "../model/rewrite.js";
 import { driverFixtures, dropPostgresFixture } from "./drivers.js";
 import type { OpenedStore } from "./drivers.js";
-import { fixtureRow } from "./support.js";
+import { fixtureRow, storedDeclaration } from "./support.js";
 import type { FixtureRowFacts } from "./support.js";
 
 const FOUNDER = accountIdFor("auth0|founder");
@@ -94,14 +97,6 @@ const SEEDED_KINDS = [
   ApiResourceKind.agent_instance,
 ];
 
-function declared(type: string): KindDeclaration {
-  const declaration = builtInModel.byType(type);
-  if (declaration === undefined) {
-    throw new Error(`${type} is declared`);
-  }
-  return declaration;
-}
-
 function resolved(accountId: string): CallerIdentity {
   return {
     identityId: accountId,
@@ -161,7 +156,7 @@ describe.each(driverFixtures(SEEDED_KINDS))(
           type: string,
           facts: FixtureRowFacts,
         ): Promise<void> {
-          const declaration = declared(type);
+          const declaration = storedDeclaration(type);
           const row = fixtureRow(declaration, facts);
           await opened.store.saveResource(
             declaration.kind,
@@ -608,9 +603,15 @@ describe.each(driverFixtures(SEEDED_KINDS))(
                 () => undefined,
                 (error: unknown) => error,
               );
-            expect(refusal).toBeInstanceOf(AuthorizationEvaluationError);
-            expect((refusal as AuthorizationEvaluationError).reason).toBe(
-              "internal-caller-offered",
+            // The seam's own refusal, the one a composition's driver throws
+            // too; never the evaluator's fault, since nothing was evaluated.
+            expect(refusal).toBeInstanceOf(InternalCallerOfferedError);
+            expect(refusal).not.toBeInstanceOf(AuthorizationEvaluationError);
+            expect((refusal as InternalCallerOfferedError).kind).toBe(
+              ApiResourceKind.agent,
+            );
+            expect((refusal as InternalCallerOfferedError).message).toContain(
+              "kind 'agent'",
             );
             // Refused before any read: the server was never evaluated as a person.
             expect(accountReads).toBe(0);

package/src/authorization/__tests__/organization-directory.test.ts

@@ -38,7 +38,7 @@ import { builtInModel } from "../model/index.js";
 import { newBuiltInOrganizationDirectory } from "../organization-directory.js";
 import { driverFixtures, dropPostgresFixture } from "./drivers.js";
 import type { OpenedStore } from "./drivers.js";
-import { fixtureRow } from "./support.js";
+import { fixtureRow, storedDeclaration } from "./support.js";
 
 const FOUNDER = accountIdFor("auth0|founder");
 const MEMBER = accountIdFor("auth0|member");
@@ -81,7 +81,7 @@ describe.each(
     let principalReads: number;
 
     async function organization(id: string) {
-      const declaration = builtInModel.byType("organization")!;
+      const declaration = storedDeclaration("organization");
       await opened.store.saveResource(
         ApiResourceKind.organization,
         id,