@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/src/authorization/__tests__/store-tests.test.ts

@@ -0,0 +1,306 @@
+/**
+ * Runs the cloud's own OpenFGA store tests against the built-in
+ * evaluator: the documents under fixtures/fga/ are pinned copies of
+ * stigmer-cloud's `fga/tests/*.fga.yaml` (each header names its source
+ * and commit), written by the model's authors and run against real
+ * OpenFGA in the cloud's CI. Every `check` assertion on a kind this
+ * edition declares must answer the same here — the proof that "the model
+ * evaluated over derived tuples" means the SAME model.
+ *
+ * What is not run is reported, never dropped: a check that targets a kind
+ * this edition does not serve, every `list_objects` assertion (the list
+ * scope's proof), and an assertion whose walk read a grant through a
+ * type this edition does not declare come back from the kit as a skipped
+ * set this file pins entry by entry, so a fixture that gains a scenario
+ * is a visible diff here and not a silently smaller proof. The second
+ * describe below pins the walk-dependent reason's own behaviour over a
+ * throwaway model, so the kit is proven and not only used.
+ *
+ * The cloud re-runs the LIVE documents through the same kit at the
+ * re-pin (the drift test's second table), which is what makes the pinned
+ * copies safe to hold.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import yaml from "js-yaml";
+import { describe, expect, it } from "vitest";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { builtInModel, newModel } from "../model/index.js";
+import {
+  computed,
+  declareKind,
+  direct,
+  objectOf,
+  union,
+  usersetOf,
+} from "../model/rewrite.js";
+import type { StoreTestDocument, StoreTestSkip } from "../store-test-kit.js";
+import { parseStoreTestDocument, storeTestCases } from "../store-test-kit.js";
+
+const FIXTURES = new URL("./fixtures/fga/", import.meta.url);
+
+/**
+ * Every document the cloud's `fga/tests/` folder holds, by file name — the
+ * fixtures folder is a byte-exact mirror of it; a file added to either
+ * without a line here fails.
+ */
+const DOCUMENTS = [
+  "agent-channel-owner.fga.yaml",
+  "agent-share-owner.fga.yaml",
+  "artifact-org-and-owner.fga.yaml",
+  "blueprint-private-visibility.fga.yaml",
+  "channel-app-owner.fga.yaml",
+  "channel-participation.fga.yaml",
+  "channel-session-visibility.fga.yaml",
+  "cross-org-share-creation.fga.yaml",
+  "default-instance-inheritance.fga.yaml",
+  "memory-subject-only.fga.yaml",
+  "org-admin-owner-inheritance.fga.yaml",
+  "org-shared-environment.fga.yaml",
+  "platform-visibility.fga.yaml",
+  "provider-standing-viewer.fga.yaml",
+  "public-visibility-setter.fga.yaml",
+  "reserved-label-writer.fga.yaml",
+  "schedule-owner.fga.yaml",
+  "schedule-session-visibility.fga.yaml",
+  "session-personal-resource.fga.yaml",
+  "workflow-execution-sharing.fga.yaml",
+] as const;
+
+function skipLine(skip: StoreTestSkip): string {
+  const relation = skip.relation === undefined ? "" : ` ${skip.relation}`;
+  const types = skip.types === undefined ? "" : ` (${skip.types.join(", ")})`;
+  return `${skip.document} :: ${skip.test} :: ${skip.subject}${relation} ${skip.object} :: ${skip.reason}${types}`;
+}
+
+/**
+ * Every assertion the kit did not run, pinned, in the kit's three
+ * reasons. `list-objects` lines are the list scope's proof and run when
+ * it lands. `undeclared-kind` lines target `platform`, a kind this
+ * edition never serves (the driver refuses it before any evaluation).
+ * `undeclared-subject-type` lines are the checks whose walk read the
+ * cloud's platform-tenancy grant, `identity_provider:<idp>#platform_user`
+ * — a userset on a kind this edition does not declare, so the answer here
+ * (nobody) is not the oracle's and is not asserted; the cloud runs the
+ * same lines over its full model at the re-pin.
+ */
+const SKIPPED_PINNED: ReadonlyArray<string> = [
+  // list-objects
+  "agent-channel-owner :: listing channels reflects ownership and grants, not membership :: identity_account:alice <agent_channel> :: list-objects",
+  "agent-channel-owner :: listing channels reflects ownership and grants, not membership :: identity_account:carol <agent_channel> :: list-objects",
+  "agent-channel-owner :: listing channels reflects ownership and grants, not membership :: identity_account:mallory <agent_channel> :: list-objects",
+  "agent-share-owner :: listing shares reflects ownership and grants, not membership :: identity_account:alice <agent_share> :: list-objects",
+  "agent-share-owner :: listing shares reflects ownership and grants, not membership :: identity_account:carol <agent_share> :: list-objects",
+  "agent-share-owner :: listing shares reflects ownership and grants, not membership :: identity_account:mallory <agent_share> :: list-objects",
+  "artifact-org-and-owner :: listing reflects org inheritance plus creator ownership :: identity_account:acme-guest <artifact> :: list-objects",
+  "artifact-org-and-owner :: listing reflects org inheritance plus creator ownership :: identity_account:eve <artifact> :: list-objects",
+  "artifact-org-and-owner :: listing reflects org inheritance plus creator ownership :: identity_account:victor <artifact> :: list-objects",
+  "blueprint-private-visibility :: org admin's listable agents include private ones (T08) :: identity_account:oscar <agent> :: list-objects",
+  "blueprint-private-visibility :: org member's listable agents exclude private ones (wildcard suppressed) :: identity_account:dave <agent> :: list-objects",
+  "blueprint-private-visibility :: org viewer's listable agents are exactly the viewer-shaped org-visible ones :: identity_account:vera <agent> :: list-objects",
+  "blueprint-private-visibility :: owner's listable agents include everything they authored :: identity_account:carol <agent> :: list-objects",
+  "channel-app-owner :: listing channel apps reflects ownership and grants, not membership :: identity_account:alice <channel_app> :: list-objects",
+  "channel-app-owner :: listing channel apps reflects ownership and grants, not membership :: identity_account:carol <channel_app> :: list-objects",
+  "channel-app-owner :: listing channel apps reflects ownership and grants, not membership :: identity_account:mallory <channel_app> :: list-objects",
+  "channel-participation :: list viewable and participable channels resolve per grant (drives listConversations) :: identity_account:carol <agent_channel> :: list-objects",
+  "channel-participation :: list viewable and participable channels resolve per grant (drives listConversations) :: identity_account:dave <agent_channel> :: list-objects",
+  "channel-participation :: list viewable and participable channels resolve per grant (drives listConversations) :: identity_account:trina <agent_channel> :: list-objects",
+  "channel-session-visibility :: list viewable sessions resolves the channel chain (drives listByChannel) :: identity_account:alice <session> :: list-objects",
+  "channel-session-visibility :: list viewable sessions resolves the channel chain (drives listByChannel) :: identity_account:bob <session> :: list-objects",
+  "channel-session-visibility :: list viewable sessions resolves the channel chain (drives listByChannel) :: identity_account:carol <session> :: list-objects",
+  "default-instance-inheritance :: list managed-org member's viewable agent instances resolves the default_of chain :: identity_account:alice <agent_instance> :: list-objects",
+  "memory-subject-only :: list-objects returns only the subject's own records :: identity_account:alice <memory> :: list-objects",
+  "memory-subject-only :: list-objects returns only the subject's own records :: identity_account:mallory <memory> :: list-objects",
+  "org-admin-owner-inheritance :: admin's listable resources include private blueprints, never personal kinds :: identity_account:ana <agent> :: list-objects",
+  "org-admin-owner-inheritance :: admin's listable resources include private blueprints, never personal kinds :: identity_account:ana <agent_instance> :: list-objects",
+  "org-admin-owner-inheritance :: admin's listable resources include private blueprints, never personal kinds :: identity_account:ana <session> :: list-objects",
+  "org-shared-environment :: org-members-can-list-shared-environments-only :: identity_account:dave <environment> :: list-objects",
+  "platform-visibility :: list managed-org member's viewable agents includes only the shared one :: identity_account:alice <agent> :: list-objects",
+  "schedule-owner :: listing schedules reflects ownership and grants, not membership :: identity_account:alice <schedule> :: list-objects",
+  "schedule-owner :: listing schedules reflects ownership and grants, not membership :: identity_account:carol <schedule> :: list-objects",
+  "schedule-owner :: listing schedules reflects ownership and grants, not membership :: identity_account:mallory <schedule> :: list-objects",
+  "schedule-session-visibility :: list viewable sessions resolves the schedule chain :: identity_account:alice <session> :: list-objects",
+  "schedule-session-visibility :: list viewable sessions resolves the schedule chain :: identity_account:bob <session> :: list-objects",
+  "schedule-session-visibility :: list viewable sessions resolves the schedule chain :: identity_account:carol <session> :: list-objects",
+  "workflow-execution-sharing :: list a teammate's viewable runs reflects both sharing axes :: identity_account:bob <workflow_execution> :: list-objects",
+  // undeclared-kind: platform
+  "provider-standing-viewer :: operator may view provider standing, tenants may not :: identity_account:mallory platform:stigmer :: undeclared-kind",
+  "provider-standing-viewer :: operator may view provider standing, tenants may not :: identity_account:opal platform:stigmer :: undeclared-kind",
+  "public-visibility-setter :: operators may set public visibility, tenants may not :: identity_account:machine platform:stigmer :: undeclared-kind",
+  "public-visibility-setter :: operators may set public visibility, tenants may not :: identity_account:mallory platform:stigmer :: undeclared-kind",
+  "public-visibility-setter :: operators may set public visibility, tenants may not :: identity_account:opal platform:stigmer :: undeclared-kind",
+  "reserved-label-writer :: operator may write reserved labels, tenants may not :: identity_account:machine platform:stigmer :: undeclared-kind",
+  "reserved-label-writer :: operator may write reserved labels, tenants may not :: identity_account:mallory platform:stigmer :: undeclared-kind",
+  // undeclared-subject-type: identity_provider#platform_user
+  "default-instance-inheritance :: managed-org member reaches the default instance of a platform-shared agent :: identity_account:alice can_execute agent_instance:sara-default :: undeclared-subject-type (identity_provider)",
+  "default-instance-inheritance :: managed-org member reaches the default instance of a platform-shared agent :: identity_account:alice can_view agent_instance:sara-default :: undeclared-subject-type (identity_provider)",
+  "default-instance-inheritance :: managed-org member reaches the default instance of a platform-shared workflow :: identity_account:alice can_execute workflow_instance:onboarding-default :: undeclared-subject-type (identity_provider)",
+  "default-instance-inheritance :: managed-org member reaches the default instance of a platform-shared workflow :: identity_account:alice can_view workflow_instance:onboarding-default :: undeclared-subject-type (identity_provider)",
+  "default-instance-inheritance :: outsiders get nothing from the default_of link :: identity_account:mallory can_execute agent_instance:sara-default :: undeclared-subject-type (identity_provider)",
+  "default-instance-inheritance :: outsiders get nothing from the default_of link :: identity_account:mallory can_view agent_instance:sara-default :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: managed-org members can view and execute a platform-shared agent :: identity_account:alice can_create_instance agent:sara :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: managed-org members can view and execute a platform-shared agent :: identity_account:alice can_execute agent:sara :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: managed-org members can view and execute a platform-shared agent :: identity_account:alice can_view agent:sara :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: managed-org members can view and execute a platform-shared agent :: identity_account:bob can_execute agent:sara :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: managed-org members can view and execute a platform-shared agent :: identity_account:bob can_view agent:sara :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: outsiders and unrelated orgs get nothing from platform visibility :: identity_account:mallory can_create_instance agent:sara :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: outsiders and unrelated orgs get nothing from platform visibility :: identity_account:mallory can_execute agent:sara :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: outsiders and unrelated orgs get nothing from platform visibility :: identity_account:mallory can_view agent:sara :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: platform-shared mcp_server is usable by managed-org members :: identity_account:alice can_connect mcp_server:github :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: platform-shared mcp_server is usable by managed-org members :: identity_account:alice can_use mcp_server:github :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: platform-shared mcp_server is usable by managed-org members :: identity_account:alice can_view mcp_server:github :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: platform-shared skill is usable by managed-org members :: identity_account:alice can_use skill:research :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: platform-shared skill is usable by managed-org members :: identity_account:alice can_view skill:research :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: platform-shared workflow is viewable and executable by managed-org members :: identity_account:alice can_execute workflow:onboarding :: undeclared-subject-type (identity_provider)",
+  "platform-visibility :: platform-shared workflow is viewable and executable by managed-org members :: identity_account:alice can_view workflow:onboarding :: undeclared-subject-type (identity_provider)",
+];
+
+describe("the cloud's OpenFGA store tests over the built-in evaluator", () => {
+  it("the fixtures folder holds exactly the documents this file pins", () => {
+    expect(
+      readdirSync(FIXTURES)
+        .filter((name) => name.endsWith(".fga.yaml"))
+        .sort(),
+    ).toEqual([...DOCUMENTS]);
+  });
+
+  const kits = DOCUMENTS.map((name) => {
+    const document = parseStoreTestDocument(
+      yaml.load(readFileSync(fileURLToPath(new URL(name, FIXTURES)), "utf8")),
+      name,
+    );
+    return { document, kit: storeTestCases(document, builtInModel) };
+  });
+
+  for (const { document, kit } of kits) {
+    if (kit.cases.length === 0) {
+      // Every check targets a kind this edition does not declare (the
+      // platform documents); reported as skipped, pinned below.
+      it.skip(`${document.name}: no check targets a declared kind`, () => {});
+      continue;
+    }
+    describe(document.name, () => {
+      for (const storeTestCase of kit.cases) {
+        it(storeTestCase.name, storeTestCase.run);
+      }
+    });
+  }
+
+  // Declared after every case: a kit's `skipped` is complete once its
+  // cases have run (the walk-dependent reason is decided per assertion).
+  it("reports every assertion it did not run, and the list is the pinned one", () => {
+    const skipped = kits.flatMap(({ kit }) => kit.skipped.map(skipLine));
+    expect(skipped.sort()).toEqual([...SKIPPED_PINNED].sort());
+  });
+});
+
+/**
+ * The kit's walk-dependent skip, proven over a throwaway model shaped
+ * like a blueprint whose `viewer` line reads, in order, a direct person,
+ * `owner`, then a userset on a type the model does not declare — the
+ * platform-tenancy shape — so each arm below settles at a different point
+ * of the union.
+ */
+describe("the kit skips an assertion whose walk read a type the model does not declare", () => {
+  const model = newModel([
+    declareKind({
+      kind: ApiResourceKind.agent,
+      schema: AgentSchema,
+      source: "fga/model/agentic/agent.fga",
+      relations: [
+        ["owner", direct(objectOf("identity_account"))],
+        [
+          "platform_viewer",
+          direct(usersetOf("identity_provider", "platform_user")),
+        ],
+        [
+          "viewer",
+          union(
+            direct(objectOf("identity_account")),
+            computed("owner"),
+            computed("platform_viewer"),
+          ),
+        ],
+        ["can_view", computed("viewer")],
+        ["can_edit", computed("owner")],
+      ],
+    }),
+  ]);
+
+  const document: StoreTestDocument = {
+    name: "throwaway",
+    tuples: [
+      { user: "identity_account:carol", relation: "owner", object: "agent:a" },
+      {
+        user: "identity_provider:idp#platform_user",
+        relation: "platform_viewer",
+        object: "agent:a",
+      },
+      { user: "identity_account:carol", relation: "owner", object: "agent:b" },
+    ],
+    tests: [
+      {
+        name: "arms",
+        check: [
+          // The owner: `viewer` settles on the direct line; `can_edit` never reads platform_viewer.
+          {
+            user: "identity_account:carol",
+            object: "agent:a",
+            assertions: { can_view: true, can_edit: true },
+          },
+          // A stranger: the union walks to platform_viewer and reads the undeclared userset.
+          {
+            user: "identity_account:mallory",
+            object: "agent:a",
+            assertions: { can_view: false, can_edit: false },
+          },
+          // No such tuple on this object: the same stranger's walk reads nothing undeclared.
+          {
+            user: "identity_account:mallory",
+            object: "agent:b",
+            assertions: { can_view: false },
+          },
+        ],
+        list_objects: [],
+      },
+    ],
+  };
+
+  it("runs the arms the walk settles before the undeclared type, skips exactly the one that read it — whatever it would have answered", async () => {
+    const kit = storeTestCases(document, model);
+    expect(kit.skipped).toEqual([]);
+    for (const storeTestCase of kit.cases) {
+      await storeTestCase.run();
+    }
+    expect(kit.skipped.map(skipLine)).toEqual([
+      "throwaway :: arms :: identity_account:mallory can_view agent:a :: undeclared-subject-type (identity_provider)",
+    ]);
+  });
+
+  it("asserts the arms it runs: a wrong expectation on a settled arm still fails", async () => {
+    const wrong: StoreTestDocument = {
+      ...document,
+      tests: [
+        {
+          name: "wrong",
+          check: [
+            {
+              user: "identity_account:carol",
+              object: "agent:a",
+              assertions: { can_edit: false },
+            },
+          ],
+          list_objects: [],
+        },
+      ],
+    };
+    const kit = storeTestCases(wrong, model);
+    await expect(kit.cases[0]?.run()).rejects.toThrow(
+      /expected false, got true/,
+    );
+  });
+});

package/src/authorization/__tests__/support.ts

@@ -0,0 +1,101 @@
+/**
+ * Fixtures the authorization module's tests share: a stored row of any
+ * declared kind with the facts the derivation reads set through the
+ * kind's own schema — every resource carries `metadata` of the one shared
+ * type and its audit under `status.audit`, so one builder serves every
+ * declaration.
+ *
+ * A row's parent fields are filled from `kind_meta` itself: for the
+ * kind's scope parent and every additional parent, the spec field the
+ * config names gets `<parentKind>-1`, resolved to the field's generated
+ * name through the schema descriptor (the reflection idiom
+ * pipeline/steps/shapes.ts documents) so this file keeps no copy of the
+ * config and no name transform of its own. A well-formed row for every
+ * kind is what the create-time resolver demands (it throws on a missing
+ * parent), which is what lets the parity pin run over all of them.
+ * `spec` and `status` overrides sit on top for the arms that need a
+ * pointer or a level set.
+ */
+import { create } from "@bufbuild/protobuf";
+import type { DescMessage, Message } from "@bufbuild/protobuf";
+
+import type { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
+import {
+  getKindEnum,
+  getKindMeta,
+  kindEnumName,
+} from "../../pipeline/apiresource-meta.js";
+import type { KindDeclaration } from "../model/rewrite.js";
+
+export interface FixtureRowFacts {
+  readonly id: string;
+  readonly org: string;
+  readonly visibility: ApiResourceVisibility;
+  readonly createdBy: string;
+  /** Spec fields set over the parent defaults, by generated field name. */
+  readonly spec?: Readonly<Record<string, unknown>>;
+  /** Status fields set beside the audit, by generated field name. */
+  readonly status?: Readonly<Record<string, unknown>>;
+}
+
+/** The id the fixture gives the parent of `parentKind`: `<type>-1`. */
+export function fixtureParentId(parentKind: string): string {
+  return `${kindEnumName(getKindEnum(parentKind))}-1`;
+}
+
+/** A row of `declaration.kind` carrying exactly the given facts, its parents filled. */
+export function fixtureRow(
+  declaration: KindDeclaration,
+  facts: FixtureRowFacts,
+): Message {
+  // Typed loosely on purpose: the schema is any declared kind's, and
+  // protobuf-es only knows the field set of a concrete schema. Every kind
+  // shares these two paths (`metadata`, `status.audit`), which is the
+  // premise the derivation itself rests on.
+  const init: Record<string, unknown> = {
+    metadata: {
+      id: facts.id,
+      name: facts.id,
+      org: facts.org,
+      visibility: facts.visibility,
+    },
+    spec: { ...parentFieldsOf(declaration), ...facts.spec },
+    status: {
+      audit: { specAudit: { createdBy: { id: facts.createdBy } } },
+      ...facts.status,
+    },
+  };
+  return create(declaration.schema, init);
+}
+
+/** `kind_meta`'s parent spec fields for the kind, by generated name, each naming `<parentKind>-1`. */
+function parentFieldsOf(declaration: KindDeclaration): Record<string, string> {
+  const config = getKindMeta(declaration.kind).authorization;
+  const spec = specSchemaOf(declaration.schema);
+  const fields: Record<string, string> = {};
+  if (config === undefined || spec === undefined) {
+    return fields;
+  }
+  const parents = [
+    ...(config.parent === undefined ? [] : [config.parent]),
+    ...config.additionalParents,
+  ];
+  for (const parent of parents) {
+    const field = spec.fields.find((f) => f.name === parent.specField);
+    if (field === undefined) {
+      throw new Error(
+        `${declaration.type}: kind_meta names spec field '${parent.specField}', which ${spec.typeName} does not have`,
+      );
+    }
+    fields[field.localName] = fixtureParentId(parent.kind);
+  }
+  return fields;
+}
+
+function specSchemaOf(schema: DescMessage): DescMessage | undefined {
+  const spec = schema.fields.find((f) => f.name === "spec");
+  return spec !== undefined && spec.fieldKind === "message"
+    ? spec.message
+    : undefined;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Pins the tuple vocabulary's contract: the string notation the cloud's
+ * store tests and the IamPolicy proto share round-trips through parse and
+ * format. The person's construction is person.test.ts's.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  formatSubject,
+  formatTuple,
+  parseObjectRef,
+  parseSubject,
+} from "../tuples.js";
+
+describe("the string notation", () => {
+  it("parses an object, a userset and the wildcard, and an id may carry a colon (issuer subjects do)", () => {
+    expect(parseObjectRef("agent:agt_1")).toEqual({
+      type: "agent",
+      id: "agt_1",
+    });
+    expect(parseObjectRef("identity_account:auth0|c:d")).toEqual({
+      type: "identity_account",
+      id: "auth0|c:d",
+    });
+    expect(parseSubject("organization:acme#viewer")).toEqual({
+      form: "userset",
+      object: { type: "organization", id: "acme" },
+      relation: "viewer",
+    });
+    expect(parseSubject("identity_account:*")).toEqual({
+      form: "wildcard",
+      type: "identity_account",
+      condition: undefined,
+    });
+    expect(parseSubject("identity_account:ida_x")).toEqual({
+      form: "object",
+      object: { type: "identity_account", id: "ida_x" },
+    });
+  });
+
+  it("refuses text with no type", () => {
+    expect(() => parseObjectRef("nonsense")).toThrow("not an object reference");
+    expect(() => parseObjectRef(":id")).toThrow("not an object reference");
+  });
+
+  it("formats a tuple in the proto's notation, the condition spelled after `with`", () => {
+    expect(
+      formatTuple({
+        object: parseObjectRef("agent:a"),
+        relation: "viewer",
+        subject: {
+          form: "wildcard",
+          type: "identity_account",
+          condition: "allow_public",
+        },
+      }),
+    ).toBe("agent:a#viewer@identity_account:* with allow_public");
+    expect(formatSubject(parseSubject("organization:acme#member"))).toBe(
+      "organization:acme#member",
+    );
+  });
+});

package/src/authorization/__tests__/wire-permissions.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Pins that every question the wire can ask this edition's authorizer
+ * has a line in the model: for every `rpc.config`-annotated method the
+ * open-source server SERVES whose annotation names a static kind this
+ * edition serves, the permission is a relation that kind's transcript
+ * declares. A relation the kind does not define answers `deny` here
+ * (evaluator.ts) — an RPC annotated with such a pair would refuse every
+ * caller, green on the permissive `local*` targets and dark only under
+ * enforcement, so the gap is caught at the registry instead of on a
+ * self-host.
+ *
+ * Scope follows authorize-annotation-completeness.test.ts: the empty
+ * composition's routes, replayed into a recorder, are exactly the methods
+ * the OSS Authorize step governs. Outside the pin, each for a stated
+ * reason: `is_public` and `is_skip_authorization` methods (the annotation
+ * is never resolved); a kind the edition does not serve (`platform`; the
+ * driver refuses it before any evaluation, so under the built-in posture
+ * nobody holds a platform permission); a kind named by
+ * `resource_kind_path` (the IamPolicy lane's — the kind is the request's,
+ * and the target's own declaration answers at run time).
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { getOption, hasOption } from "@bufbuild/protobuf";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import {
+  config as rpcAuthorizationConfig,
+  is_public,
+  is_skip_authorization,
+} from "@stigmer/protos/ai/stigmer/commons/rpc/method_options_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+
+import { loadConfig } from "../../boot/config.js";
+import { composeServer } from "../../boot/compose.js";
+import type { ComposedServer } from "../../boot/compose.js";
+import {
+  baseConfig,
+  servedServices,
+  silentLogger,
+} from "../../extensions/__tests__/composed-support.js";
+import {
+  kindEnumName,
+  kindServedByEdition,
+} from "../../pipeline/apiresource-meta.js";
+import { declarationFor } from "../model/index.js";
+
+/** One annotated, served, statically-targeted method: the question the wire asks. */
+interface WireQuestion {
+  readonly method: string;
+  readonly kind: ApiResourceKind;
+  readonly permission: string;
+}
+
+describe("every static (kind, permission) the served RPCs ask about is a declared relation", () => {
+  let dir: string;
+  let server: ComposedServer;
+
+  beforeAll(async () => {
+    dir = mkdtempSync(path.join(tmpdir(), "wire-permissions-test-"));
+    server = await composeServer({
+      config: loadConfig(baseConfig(dir)),
+      logger: silentLogger,
+      portOverride: 0,
+      host: "127.0.0.1",
+    });
+  });
+
+  afterAll(async () => {
+    await server.shutdown();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  function wireQuestions(): WireQuestion[] {
+    const questions: WireQuestion[] = [];
+    for (const service of servedServices(server.routes)) {
+      for (const method of service.methods) {
+        if (
+          !hasOption(method, rpcAuthorizationConfig) ||
+          getOption(method, is_public) ||
+          getOption(method, is_skip_authorization)
+        ) {
+          continue;
+        }
+        const config = getOption(method, rpcAuthorizationConfig);
+        if (
+          config.resourceKind === ApiResourceKind.api_resource_kind_unknown ||
+          !kindServedByEdition(config.resourceKind, ServerEdition.oss)
+        ) {
+          continue;
+        }
+        questions.push({
+          method: `${service.typeName}/${method.name}`,
+          kind: config.resourceKind,
+          permission: IamPermission[config.permission] ?? "",
+        });
+      }
+    }
+    return questions;
+  }
+
+  it("names a declared relation for every question, with none undeclared", () => {
+    const questions = wireQuestions();
+    expect(questions.length).toBeGreaterThan(60);
+    const undeclared = questions
+      .filter(
+        (q) => declarationFor(q.kind)?.relations.has(q.permission) !== true,
+      )
+      .map(
+        (q) =>
+          `${q.method} asks ${q.permission} on ${kindEnumName(q.kind)}, which its transcript does not declare`,
+      );
+    expect(undeclared).toEqual([]);
+  });
+
+  it("asks about every served kind the model declares except the two no RPC targets statically", () => {
+    // iam_policy's RPCs target the policy's RESOURCE (`resource_kind_path`
+    // or the load-then-authorize `get`); execution_context's RPCs are
+    // `is_skip_authorization` lanes (or unannotated) whose handlers gate on
+    // the runner's execution-scoped token. Every other declared kind is
+    // asked about by at least one static annotation.
+    const asked = new Set(wireQuestions().map((q) => kindEnumName(q.kind)));
+    expect([...asked].sort()).toEqual(
+      [
+        "agent",
+        "agent_channel",
+        "agent_execution",
+        "agent_instance",
+        "agent_share",
+        "api_key",
+        "artifact",
+        "channel_app",
+        "environment",
+        "identity_account",
+        "mcp_server",
+        "memory",
+        "oauth_app",
+        "organization",
+        "plugin",
+        "project",
+        "schedule",
+        "session",
+        "skill",
+        "workflow",
+        "workflow_execution",
+        "workflow_instance",
+      ].sort(),
+    );
+  });
+});