@stigmer/server 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

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

@@ -0,0 +1,317 @@
+/**
+ * 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.
+ *
+ * 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).
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  ApiResourceKind,
+  ApiResourceKindSchema,
+  ResourceTier,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { IamPermissionSchema } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import {
+  getKindMeta,
+  kindEnumName,
+} from "../../../pipeline/apiresource-meta.js";
+import { builtInModel, declarationFor } from "../index.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.organization,
+  ApiResourceKind.project,
+  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 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",
+  ],
+  organization: [
+    "can_view",
+    "can_edit",
+    "can_delete",
+    "can_create_project",
+    "can_create_agent",
+    "can_create_workflow",
+    "can_create_session",
+    "can_create_environment",
+    "can_create_skill",
+    "can_create_plugin",
+    "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_grant_access",
+    "can_view_access",
+    "can_view_billing",
+    "can_manage_billing",
+  ],
+  project: [
+    "can_view",
+    "can_edit",
+    "can_delete",
+    "can_grant_access",
+    "can_view_access",
+  ],
+  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",
+  ],
+};
+
+/** Every kind whose `kind_meta.tier` is the open-source tier, by enum number. */
+function openSourceTierKinds(): ReadonlySet<ApiResourceKind> {
+  const kinds = new Set<ApiResourceKind>();
+  for (const value of ApiResourceKindSchema.values) {
+    const kind = value.number as ApiResourceKind;
+    if (
+      kind !== ApiResourceKind.api_resource_kind_unknown &&
+      getKindMeta(kind).tier === ResourceTier.open_source
+    ) {
+      kinds.add(kind);
+    }
+  }
+  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());
+  });
+
+  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.platform_client,
+      ApiResourceKind.invitation,
+    ]) {
+      expect(declarationFor(unserved), kindEnumName(unserved)).toBeUndefined();
+    }
+    expect(builtInModel.byType("")).toBeUndefined();
+  });
+
+  it("names its `.fga` source by the kind's own type, under the module the fga.mod files it in", () => {
+    for (const declaration of builtInModel.declarations) {
+      expect(declaration.source).toMatch(
+        new RegExp(
+          `^fga/model/(tenancy|agentic|iam)/${declaration.type}\\.fga$`,
+        ),
+      );
+    }
+  });
+
+  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(),
+    );
+    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],
+      );
+    }
+  });
+
+  it("carries a derived rule only where kind_meta cannot derive the relation: default_of on the two instance kinds, execution_viewer on the workflow instance", () => {
+    const derived = builtInModel.declarations
+      .flatMap((d) => [...d.derived.keys()].map((r) => `${d.type}#${r}`))
+      .sort();
+    expect(derived).toEqual([
+      "agent_instance#default_of",
+      "workflow_instance#default_of",
+      "workflow_instance#execution_viewer",
+    ]);
+  });
+});

package/src/authorization/model/agent.ts

@@ -0,0 +1,64 @@
+/**
+ * Transcript of fga/model/agentic/agent.fga — a blueprint: owned by its
+ * creator and by the organization's admins (`admin from organization`),
+ * read by whoever the visibility axis lets in. The `organization#member`
+ * and `organization#viewer` usersets on `viewer` are the org-visibility
+ * tuple's two shapes (the cloud writes `#viewer` since cloud#257; `#member`
+ * is the legacy shape it still honours), the conditional wildcard is the
+ * public level, and `platform_viewer` is an identity-provider userset no
+ * open-source tuple ever names.
+ */
+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 {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  publicWith,
+  union,
+  usersetOf,
+} from "./rewrite.js";
+
+export const agentDeclaration = declareKind({
+  kind: ApiResourceKind.agent,
+  schema: AgentSchema,
+  source: "fga/model/agentic/agent.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    [
+      "owner",
+      union(
+        direct(objectOf("identity_account")),
+        from("admin", "organization"),
+      ),
+    ],
+    [
+      "platform_viewer",
+      direct(usersetOf("identity_provider", "platform_user")),
+    ],
+    [
+      "viewer",
+      union(
+        direct(
+          objectOf("identity_account"),
+          publicWith("identity_account", "allow_public"),
+          usersetOf("organization", "member"),
+          usersetOf("organization", "viewer"),
+        ),
+        computed("owner"),
+        computed("platform_viewer"),
+      ),
+    ],
+    ["can_view", computed("viewer")],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_execute", computed("viewer")],
+    ["can_create_instance", computed("can_execute")],
+    ["can_clone", computed("viewer")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+});

package/src/authorization/model/agent_channel.ts

@@ -0,0 +1,49 @@
+/**
+ * Transcript of fga/model/agentic/agent_channel.fga — a channel binding,
+ * admin-owned like a blueprint, with `participant` as the one relation
+ * between owner and viewer: the conversation-participation role
+ * (reply and takeover without configuration authority), grantable as a
+ * role on this kind alone. Every owner participates; every participant
+ * views.
+ */
+import { AgentChannelSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  union,
+} from "./rewrite.js";
+
+export const agentChannelDeclaration = declareKind({
+  kind: ApiResourceKind.agent_channel,
+  schema: AgentChannelSchema,
+  source: "fga/model/agentic/agent_channel.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    [
+      "owner",
+      union(
+        direct(objectOf("identity_account")),
+        from("admin", "organization"),
+      ),
+    ],
+    [
+      "participant",
+      union(direct(objectOf("identity_account")), computed("owner")),
+    ],
+    [
+      "viewer",
+      union(direct(objectOf("identity_account")), computed("participant")),
+    ],
+    ["can_view", computed("viewer")],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_participate", computed("participant")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+});

package/src/authorization/model/agent_execution.ts

@@ -0,0 +1,33 @@
+/**
+ * Transcript of fga/model/agentic/agent_execution.fga — a run is its
+ * session's: no owner tuple of its own (`kind_meta` attribution
+ * INHERITED), every relation a hop through `session`, which the
+ * derivation writes from `spec.session_id`. `can_view: viewer or
+ * can_view from session` walks a parent PERMISSION whose own arms include
+ * the session's channel and schedule hops; the evaluator resolves those
+ * on the session's declaration, so this file needs no knowledge of them.
+ */
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  union,
+} from "./rewrite.js";
+
+export const agentExecutionDeclaration = declareKind({
+  kind: ApiResourceKind.agent_execution,
+  schema: AgentExecutionSchema,
+  source: "fga/model/agentic/agent_execution.fga",
+  relations: [
+    ["session", direct(objectOf("session"))],
+    ["owner", from("owner", "session")],
+    ["viewer", union(from("viewer", "session"), computed("owner"))],
+    ["can_view", union(computed("viewer"), from("can_view", "session"))],
+    ["can_edit", computed("owner")],
+  ],
+});

package/src/authorization/model/agent_instance.ts

@@ -0,0 +1,66 @@
+/**
+ * Transcript of fga/model/agentic/agent_instance.fga — a person's
+ * configuration of an agent: owner-only in every write (no admin arm,
+ * unlike the blueprint), readable through its own visibility axis or, for
+ * the system-managed default instance, through the blueprint's whole
+ * viewer set (`viewer from default_of`; default-of.ts). `agent` is the
+ * parent link written on every instance for tracking and walked by
+ * nothing; `default_of` is the derived link written on the default
+ * instance alone.
+ */
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { defaultOfBlueprint } from "./default-of.js";
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  publicWith,
+  union,
+  usersetOf,
+} from "./rewrite.js";
+
+export const agentInstanceDeclaration = declareKind({
+  kind: ApiResourceKind.agent_instance,
+  schema: AgentInstanceSchema,
+  source: "fga/model/agentic/agent_instance.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    ["agent", direct(objectOf("agent"))],
+    ["default_of", direct(objectOf("agent"))],
+    ["owner", direct(objectOf("identity_account"))],
+    [
+      "viewer",
+      union(
+        direct(
+          objectOf("identity_account"),
+          publicWith("identity_account", "allow_public"),
+          usersetOf("organization", "member"),
+          usersetOf("organization", "viewer"),
+        ),
+        computed("owner"),
+        from("viewer", "default_of"),
+      ),
+    ],
+    ["can_view", computed("viewer")],
+    ["can_execute", computed("can_view")],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+  derived: [
+    [
+      "default_of",
+      defaultOfBlueprint({
+        kind: ApiResourceKind.agent,
+        schema: AgentSchema,
+        defaultInstanceIdOf: (agent) => agent.status?.defaultInstanceId ?? "",
+      }),
+    ],
+  ],
+});

package/src/authorization/model/agent_share.ts

@@ -0,0 +1,40 @@
+/**
+ * Transcript of fga/model/agentic/agent_share.fga — a share link's
+ * configuration row, admin-owned; its anonymous visitors are the cloud's
+ * `guest` credential on the organization, a class no open-source lane
+ * mints, so on this edition a share is visible to its owners and explicit
+ * grantees only.
+ */
+import { AgentShareSchema } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  union,
+} from "./rewrite.js";
+
+export const agentShareDeclaration = declareKind({
+  kind: ApiResourceKind.agent_share,
+  schema: AgentShareSchema,
+  source: "fga/model/agentic/agent_share.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    [
+      "owner",
+      union(
+        direct(objectOf("identity_account")),
+        from("admin", "organization"),
+      ),
+    ],
+    ["viewer", union(direct(objectOf("identity_account")), computed("owner"))],
+    ["can_view", computed("viewer")],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+});

package/src/authorization/model/api_key.ts

@@ -0,0 +1,28 @@
+/**
+ * Transcript of fga/model/iam/api_key.fga — a credential, owner-only in
+ * every verb: no organization link (`kind_meta` scope OWNER_ONLY) and no
+ * admin arm, so the key a person minted is theirs to view, rotate, revoke
+ * and use, and nobody else's. `can_rotate`, `can_revoke` and `can_use` are
+ * the file's own verbs; the wire vocabulary names only the first three.
+ */
+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 { computed, declareKind, direct, objectOf } from "./rewrite.js";
+
+export const apiKeyDeclaration = declareKind({
+  kind: ApiResourceKind.api_key,
+  schema: ApiKeySchema,
+  source: "fga/model/iam/api_key.fga",
+  relations: [
+    ["owner", direct(objectOf("identity_account"))],
+    ["can_view", computed("owner")],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_rotate", computed("owner")],
+    ["can_revoke", computed("owner")],
+    ["can_use", computed("owner")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("owner")],
+  ],
+});

package/src/authorization/model/artifact.ts

@@ -0,0 +1,38 @@
+/**
+ * Transcript of fga/model/agentic/artifact.fga — an organization's shared
+ * output: read by its creator and by every organization viewer (`viewer
+ * from organization`, no visibility tuple involved — the kind has no
+ * visibility axis), edited by the organization's admins alone (the
+ * creator does NOT edit through `owner`), and with no `can_delete` line
+ * at all. The wire annotates only `can_view` and `can_edit` on it.
+ */
+import { ArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  union,
+} from "./rewrite.js";
+
+export const artifactDeclaration = declareKind({
+  kind: ApiResourceKind.artifact,
+  schema: ArtifactSchema,
+  source: "fga/model/agentic/artifact.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    ["owner", direct(objectOf("identity_account"))],
+    [
+      "viewer",
+      union(
+        direct(objectOf("identity_account")),
+        from("viewer", "organization"),
+      ),
+    ],
+    ["can_view", union(computed("owner"), computed("viewer"))],
+    ["can_edit", from("admin", "organization")],
+  ],
+});

package/src/authorization/model/channel_app.ts

@@ -0,0 +1,39 @@
+/**
+ * Transcript of fga/model/agentic/channel_app.fga — a messaging-platform
+ * app registration, admin-owned, viewable by its owners and explicit
+ * grantees: the same shape as agent_share, kept as its own file so the
+ * drift compare reads this file's lines.
+ */
+import { ChannelAppSchema } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  union,
+} from "./rewrite.js";
+
+export const channelAppDeclaration = declareKind({
+  kind: ApiResourceKind.channel_app,
+  schema: ChannelAppSchema,
+  source: "fga/model/agentic/channel_app.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    [
+      "owner",
+      union(
+        direct(objectOf("identity_account")),
+        from("admin", "organization"),
+      ),
+    ],
+    ["viewer", union(direct(objectOf("identity_account")), computed("owner"))],
+    ["can_view", computed("viewer")],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+});