@stigmer/server 3.27.1 → 3.28.0

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

@@ -1,33 +1,40 @@
 /**
- * Pins the built-in model's registry: which kinds are declared — every
- * kind of the open-source tier, in `fga.mod` order, and nothing else —
- * that each declaration names its `.fga` source by its own type, that a
- * kind is reached by enum and by FGA type name alike, and that every
- * permission the wire can ask about (the IamPermission vocabulary) is
- * either a declared relation of the kind or absent from its `.fga` file —
- * never a relation the transcript forgot — and that 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 step and the model cannot
- * disagree about where a team may be granted.
+ * Pins the built-in model against its sources and the contract:
+ *   - its types are the files `fga.mod` lists, in that order, one type per
+ *     file named by the file, and every one is bound (bindings.ts);
+ *   - every binding's schema is the message `kind_meta` spells for the
+ *     kind (`ai.stigmer.<group>.<name>.<version>.<Name>`), `platform`
+ *     excepted by name as the one rowless type, so the explicit table
+ *     cannot bind a kind to the wrong message;
+ *   - every declaration names a `.fga` file that exists under fga/model;
+ *   - the model declares every open-source-tier kind, and outside the tier
+ *     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;
+ *   - 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
+ *     step and the model cannot disagree about where a team may be
+ *     granted;
+ *   - the derived rules are exactly the three relations `kind_meta` cannot
+ *     derive.
  *
- * The kind list is pinned twice on purpose: as the literal in registry
- * order (a reordering or a dropped file is a visible diff) and as
- * set-equal to the `kind_meta.tier` open-source members (a kind the
- * contract moves into or out of the tier is a visible diff here before
- * it is a silent gap in enforcement).
+ * Whether the model defines what the wire asks is the whole contract's
+ * question, pinned in __tests__/wire-permissions.test.ts.
  */
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
 import { describe, expect, it } from "vitest";
 
+import { ApiResourceGroup } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_group_pb";
 import {
   ApiResourceKind,
   ApiResourceKindSchema,
+  ApiResourceVersion,
   ResourceTier,
 } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
-import {
-  IamPermissionSchema,
-  IamRole,
-} from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 
 import {
   getKindMeta,
@@ -35,221 +42,40 @@ import {
   kindEnumName,
   teamGrantableRolesFor,
 } from "../../../pipeline/apiresource-meta.js";
+import { KIND_BINDINGS, ROWLESS } from "../bindings.js";
 import { builtInModel, declarationFor } from "../index.js";
 import type { Rewrite, SubjectType } from "../rewrite.js";
 
-/** The open-source tier, in registry order (the `fga.mod` order of their files). */
-const DECLARED_KINDS = [
-  ApiResourceKind.identity_account,
-  ApiResourceKind.iam_policy,
-  ApiResourceKind.api_key,
-  ApiResourceKind.oauth_app,
-  ApiResourceKind.platform_client,
-  ApiResourceKind.organization,
-  ApiResourceKind.agent,
-  ApiResourceKind.agent_channel,
-  ApiResourceKind.agent_share,
-  ApiResourceKind.channel_app,
-  ApiResourceKind.agent_instance,
-  ApiResourceKind.agent_execution,
-  ApiResourceKind.artifact,
-  ApiResourceKind.environment,
-  ApiResourceKind.execution_context,
-  ApiResourceKind.mcp_server,
-  ApiResourceKind.memory,
-  ApiResourceKind.schedule,
-  ApiResourceKind.session,
-  ApiResourceKind.skill,
-  ApiResourceKind.workflow,
-  ApiResourceKind.workflow_instance,
-  ApiResourceKind.workflow_execution,
-  ApiResourceKind.plugin,
-] as const;
+/** The server package root, where fga/model lives. */
+const PACKAGE_ROOT = new URL("../../../../", import.meta.url);
 
-/**
- * The permissions each `.fga` file defines that the wire vocabulary also
- * names, in the file's order — derived by hand from the files at the
- * pinned commit. A relation in the file and not here, or here and not in
- * the transcript, fails. Verbs the files define outside the vocabulary
- * (`can_use`, `can_clone`, `can_rotate`, `can_revoke`) are the model's
- * own and are not listed.
- */
-const WIRE_PERMISSIONS_BY_TYPE: Readonly<
-  Record<string, ReadonlyArray<string>>
-> = {
-  identity_account: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  iam_policy: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  api_key: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  oauth_app: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  platform_client: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  organization: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_create_agent",
-    "can_create_workflow",
-    "can_create_session",
-    "can_create_environment",
-    "can_create_skill",
-    "can_create_plugin",
-    "can_create_mcp_server",
-    "can_create_idp",
-    "can_create_identity_account",
-    "can_create_oauth_app",
-    "can_create_platform_client",
-    "can_create_channel_app",
-    "can_create_execution_in",
-    "can_create_agent_share",
-    "can_create_agent_instance",
-    "can_create_team",
-    "can_grant_access",
-    "can_view_access",
-    "can_view_billing",
-    "can_manage_billing",
-  ],
-  agent: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_execute",
-    "can_create_instance",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  agent_channel: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_participate",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  agent_share: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  channel_app: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  agent_instance: [
-    "can_view",
-    "can_execute",
-    "can_edit",
-    "can_delete",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  agent_execution: ["can_view", "can_edit"],
-  artifact: ["can_view", "can_edit"],
-  environment: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_read_secrets",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  execution_context: ["can_view", "can_edit"],
-  mcp_server: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_connect",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  memory: ["can_view", "can_edit", "can_delete"],
-  schedule: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  session: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_create_execution_in",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  skill: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  workflow: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_execute",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  plugin: [
-    "can_view",
-    "can_edit",
-    "can_delete",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  workflow_instance: [
-    "can_view",
-    "can_execute",
-    "can_edit",
-    "can_delete",
-    "can_grant_access",
-    "can_view_access",
-  ],
-  workflow_execution: [
-    "can_view",
-    "can_edit",
-    "can_grant_access",
-    "can_view_access",
-  ],
-};
+/** The kinds the model defines outside the open-source tier: the ones the wider editions serve. */
+const WIDER_EDITION_KINDS: ReadonlyArray<ApiResourceKind> = [
+  ApiResourceKind.platform,
+  ApiResourceKind.identity_provider,
+  ApiResourceKind.invitation,
+  ApiResourceKind.team,
+];
+
+/** The files `fga.mod` lists, in its order. */
+function modFiles(): ReadonlyArray<string> {
+  const text = readFileSync(fileURLToPath(new URL("fga/model/fga.mod", PACKAGE_ROOT)), "utf8");
+  return [...text.matchAll(/^\s*-\s*(\S+\.fga)\s*$/gm)].map((match) => match[1] ?? "");
+}
+
+/** The message `kind_meta` spells for a kind. */
+function kindMetaMessageName(kind: ApiResourceKind): string {
+  const meta = getKindMeta(kind);
+  return [
+    "ai",
+    "stigmer",
+    ApiResourceGroup[meta.group],
+    meta.name.toLowerCase(),
+    ApiResourceVersion[meta.version],
+    meta.name,
+  ].join(".");
+}
 
-/** The subject types a relation's direct lists name, wherever they sit in its rewrite. */
 function directSubjects(rewrite: Rewrite): ReadonlyArray<SubjectType> {
   switch (rewrite.node) {
     case "this":
@@ -268,14 +94,10 @@ function directSubjects(rewrite: Rewrite): ReadonlyArray<SubjectType> {
 }
 
 function isTeamMembers(subject: SubjectType): boolean {
-  return (
-    subject.form === "userset" &&
-    subject.type === "team" &&
-    subject.relation === "member"
-  );
+  return subject.form === "userset" && subject.type === "team" && subject.relation === "member";
 }
 
-/** Every kind whose `kind_meta.tier` is the open-source tier, by enum number. */
+/** Every kind whose `kind_meta.tier` is the open-source tier. */
 function openSourceTierKinds(): ReadonlySet<ApiResourceKind> {
   const kinds = new Set<ApiResourceKind>();
   for (const value of ApiResourceKindSchema.values) {
@@ -290,59 +112,63 @@ function openSourceTierKinds(): ReadonlySet<ApiResourceKind> {
   return kinds;
 }
 
-describe("the built-in model's registry", () => {
-  it("declares exactly the open-source tier's kinds, in fga.mod order", () => {
-    expect(builtInModel.declarations.map((d) => d.kind)).toEqual([
-      ...DECLARED_KINDS,
-    ]);
-    expect(new Set(DECLARED_KINDS)).toEqual(openSourceTierKinds());
+describe("the built-in model", () => {
+  it("defines one type per file fga.mod lists, named by the file, in fga.mod order, every one bound", () => {
+    const files = modFiles();
+    expect(files.length).toBeGreaterThan(0);
+    expect(builtInModel.declarations.map((d) => d.type)).toEqual(
+      files.map((file) => file.replace(/^.*\//, "").replace(/\.fga$/, "")),
+    );
+    expect(builtInModel.declarations.map((d) => d.source)).toEqual(
+      files.map((file) => `fga/model/${file}`),
+    );
+    expect([...KIND_BINDINGS.keys()].map(kindEnumName)).toEqual(
+      builtInModel.declarations.map((d) => d.type),
+    );
   });
 
-  it("reaches a declaration by kind and by FGA type name, and answers undefined for the kinds this edition does not serve", () => {
-    for (const kind of DECLARED_KINDS) {
-      const byKind = declarationFor(kind);
-      expect(byKind?.kind).toBe(kind);
-      expect(builtInModel.byType(kindEnumName(kind))).toBe(byKind);
-    }
-    for (const unserved of [
-      ApiResourceKind.platform,
-      ApiResourceKind.identity_provider,
-      ApiResourceKind.invitation,
-      ApiResourceKind.team,
-    ]) {
-      expect(declarationFor(unserved), kindEnumName(unserved)).toBeUndefined();
+  it("binds every kind to the message kind_meta spells, and platform alone to ROWLESS", () => {
+    for (const declaration of builtInModel.declarations) {
+      if (declaration.kind === ApiResourceKind.platform) {
+        expect(declaration.schema).toBe(ROWLESS);
+        continue;
+      }
+      expect(declaration.schema?.typeName, declaration.type).toBe(
+        kindMetaMessageName(declaration.kind),
+      );
     }
-    expect(builtInModel.byType("")).toBeUndefined();
   });
 
-  it("names its `.fga` source by the kind's own type, under the module the fga.mod files it in", () => {
+  it("names a .fga source that exists", () => {
     for (const declaration of builtInModel.declarations) {
-      expect(declaration.source).toMatch(
-        new RegExp(
-          `^fga/model/(tenancy|agentic|iam)/${declaration.type}\\.fga$`,
-        ),
-      );
+      expect(
+        existsSync(fileURLToPath(new URL(declaration.source, PACKAGE_ROOT))),
+        declaration.source,
+      ).toBe(true);
     }
   });
 
-  it("declares, for every kind, exactly the wire permissions its `.fga` file defines", () => {
-    const wireVocabulary = new Set(
-      IamPermissionSchema.values.map((value) => value.name),
-    );
-    expect(Object.keys(WIRE_PERMISSIONS_BY_TYPE).sort()).toEqual(
-      builtInModel.declarations.map((d) => d.type).sort(),
-    );
+  it("defines every open-source-tier kind, and outside the tier exactly the kinds the wider editions serve", () => {
+    const declared = new Set(builtInModel.declarations.map((d) => d.kind));
+    const tier = openSourceTierKinds();
+    for (const kind of tier) {
+      expect(declared.has(kind), kindEnumName(kind)).toBe(true);
+    }
+    expect(
+      [...declared].filter((kind) => !tier.has(kind)).map(kindEnumName).sort(),
+    ).toEqual(WIDER_EDITION_KINDS.map(kindEnumName).sort());
+  });
+
+  it("reaches a declaration by kind and by FGA type name", () => {
     for (const declaration of builtInModel.declarations) {
-      const declaredWirePermissions = [...declaration.relations.keys()].filter(
-        (relation) => wireVocabulary.has(relation),
-      );
-      expect(declaredWirePermissions, declaration.type).toEqual(
-        WIRE_PERMISSIONS_BY_TYPE[declaration.type],
-      );
+      expect(declarationFor(declaration.kind)).toBe(declaration);
+      expect(builtInModel.byType(kindEnumName(declaration.kind))).toBe(declaration);
     }
+    expect(declarationFor(ApiResourceKind.api_resource_kind_unknown)).toBeUndefined();
+    expect(builtInModel.byType("")).toBeUndefined();
   });
 
-  it("admits a team exactly on the roles each kind's team_grantable_roles lists — the transcript and the contract say one thing", () => {
+  it("admits a team exactly on the roles each kind's team_grantable_roles lists — the model and the contract say one thing", () => {
     for (const declaration of builtInModel.declarations) {
       const admitsTeam = [...declaration.relations]
         .filter(([, rewrite]) => directSubjects(rewrite).some(isTeamMembers))

package/src/authorization/model/bindings.ts

@@ -0,0 +1,131 @@
+/**
+ * What the compiled model cannot say about a type, and the evaluator needs:
+ * the message schema a stored row of the kind decodes with, and the
+ * relations `kind_meta.authorization` cannot derive from the row alone.
+ * One row per type of the model, in `fga.mod` order; model/index.ts joins
+ * this table with the compiled JSON and refuses, at load, a type with no
+ * binding, a binding with no type, and a derived rule for a relation the
+ * type does not define.
+ *
+ * The table is explicit rather than computed from `kind_meta`'s naming
+ * convention (`ai.stigmer.<group>.<name>.<version>.<Name>`): a lookup by
+ * name would need a registry holding every message and would hide a
+ * mistake behind a rule, and an explicit import is what the tree-shaken
+ * slim bundle wants. The convention holds for every row but `platform`,
+ * and model/__tests__/registry.test.ts pins the table against it.
+ *
+ * `platform` has no stored resource: it is the singleton the platform's
+ * own permissions hang off (`platform:stigmer`), and a check on it
+ * resolves over tuples alone. Its row is ROWLESS, so the table says so
+ * rather than leaving a hole; the tuple source never loads a row for it
+ * and the list scope never lists it.
+ *
+ * The three derived rules: `default_of` on both instance kinds, which the
+ * blueprint's default-instance pointer decides (default-of.ts), and a
+ * workflow instance's `execution_viewer`, which its execution visibility
+ * decides (execution-viewer.ts).
+ */
+import type { DescMessage } from "@bufbuild/protobuf";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentChannelSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { AgentShareSchema } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/api_pb";
+import { ArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
+import { ChannelAppSchema } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
+import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { ExecutionContextSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { MemorySchema } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/api_pb";
+import { PluginSchema } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/api_pb";
+import { ScheduleSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiKeySchema } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
+import { IamPolicySchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import { IdentityAccountSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import { IdentityProviderSchema } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/api_pb";
+import { InvitationSchema } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/api_pb";
+import { OAuthAppSchema } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/api_pb";
+import { PlatformClientSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+import { TeamSchema } from "@stigmer/protos/ai/stigmer/iam/team/v1/api_pb";
+import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+
+import { defaultOfBlueprint } from "./default-of.js";
+import { executionViewer } from "./execution-viewer.js";
+import type { DerivedRelation } from "./rewrite.js";
+
+/** A type with no stored resource: it resolves over tuples alone (the module header). */
+export const ROWLESS = undefined;
+
+export interface KindBinding {
+  /** What a stored row decodes with, or ROWLESS. */
+  readonly schema: DescMessage | typeof ROWLESS;
+  /** The relations `kind_meta` cannot derive, by relation name. */
+  readonly derived?: Readonly<Record<string, DerivedRelation>>;
+}
+
+/** Every type of the model, bound, in `fga.mod` order. */
+export const KIND_BINDINGS: ReadonlyMap<ApiResourceKind, KindBinding> = new Map<
+  ApiResourceKind,
+  KindBinding
+>([
+  [ApiResourceKind.platform, { schema: ROWLESS }],
+  [ApiResourceKind.identity_account, { schema: IdentityAccountSchema }],
+  [ApiResourceKind.identity_provider, { schema: IdentityProviderSchema }],
+  [ApiResourceKind.iam_policy, { schema: IamPolicySchema }],
+  [ApiResourceKind.api_key, { schema: ApiKeySchema }],
+  [ApiResourceKind.oauth_app, { schema: OAuthAppSchema }],
+  [ApiResourceKind.platform_client, { schema: PlatformClientSchema }],
+  [ApiResourceKind.invitation, { schema: InvitationSchema }],
+  [ApiResourceKind.team, { schema: TeamSchema }],
+  [ApiResourceKind.organization, { schema: OrganizationSchema }],
+  [ApiResourceKind.agent, { schema: AgentSchema }],
+  [ApiResourceKind.agent_channel, { schema: AgentChannelSchema }],
+  [ApiResourceKind.agent_share, { schema: AgentShareSchema }],
+  [ApiResourceKind.channel_app, { schema: ChannelAppSchema }],
+  [
+    ApiResourceKind.agent_instance,
+    {
+      schema: AgentInstanceSchema,
+      derived: {
+        default_of: defaultOfBlueprint({
+          kind: ApiResourceKind.agent,
+          schema: AgentSchema,
+          defaultInstanceIdOf: (agent) => agent.status?.defaultInstanceId ?? "",
+        }),
+      },
+    },
+  ],
+  [ApiResourceKind.agent_execution, { schema: AgentExecutionSchema }],
+  [ApiResourceKind.artifact, { schema: ArtifactSchema }],
+  [ApiResourceKind.environment, { schema: EnvironmentSchema }],
+  [ApiResourceKind.execution_context, { schema: ExecutionContextSchema }],
+  [ApiResourceKind.mcp_server, { schema: McpServerSchema }],
+  [ApiResourceKind.memory, { schema: MemorySchema }],
+  [ApiResourceKind.plugin, { schema: PluginSchema }],
+  [ApiResourceKind.schedule, { schema: ScheduleSchema }],
+  [ApiResourceKind.session, { schema: SessionSchema }],
+  [ApiResourceKind.skill, { schema: SkillSchema }],
+  [ApiResourceKind.workflow, { schema: WorkflowSchema }],
+  [
+    ApiResourceKind.workflow_instance,
+    {
+      schema: WorkflowInstanceSchema,
+      derived: {
+        default_of: defaultOfBlueprint({
+          kind: ApiResourceKind.workflow,
+          schema: WorkflowSchema,
+          defaultInstanceIdOf: (workflow) => workflow.status?.defaultInstanceId ?? "",
+        }),
+        execution_viewer: executionViewer,
+      },
+    },
+  ],
+  [ApiResourceKind.workflow_execution, { schema: WorkflowExecutionSchema }],
+]);