@stigmer/server 3.21.0 → 3.22.0

package/src/domain/agentinstance/__tests__/create-authorization.composed.test.ts

@@ -0,0 +1,243 @@
+/**
+ * Pins the instance create lane's authorization at the wire, on a real boot
+ * under the require-authentication posture with no unit Authorizer (the
+ * self-host's shape, the built-in Authorizer composed):
+ *
+ *   - a member creates a personal instance of an org-visible agent in their
+ *     organization (can_create_agent_instance is member-level; the parent's
+ *     can_create_instance is its viewer set);
+ *   - a member is refused an instance of a PRIVATE agent with the parent's
+ *     copy — the organization's bar passed, the agent's did not;
+ *   - an outsider naming an organization they hold no row in is refused
+ *     with the organization's copy, before anything about the agent;
+ *   - a member's wire request carrying the reserved default-instance label
+ *     is refused: the label buys nothing from the wire (the reserved-label
+ *     guard refuses it after the caller passes the personal bar);
+ *   - the SAME labelled request the server composes in-process for the
+ *     member (the default-instance self-heal's exact shape: the in-process
+ *     transport, the propagated caller, the parent's organization) is
+ *     admitted with no caller check and attributed to the member — the
+ *     arm that keeps every lane whose run was already admitted (a guest, a
+ *     channel turn, a schedule fire) working when the agent has no default
+ *     instance yet.
+ *
+ * Every negative arm sits beside a positive one so the file cannot pass
+ * vacuously. The resolver's own table is create-authorization.test.ts.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { Code, ConnectError, createClient } from "@connectrpc/connect";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentInstanceCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/command_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { IdentityAccountCommandController } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/command_pb";
+import { OrganizationCommandController } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/command_pb";
+
+import { loadConfig } from "../../../boot/config.js";
+import { composeServer } from "../../../boot/compose.js";
+import type { ComposedServer } from "../../../boot/compose.js";
+import type { ServerExtension } from "../../../extensions/registry.js";
+import {
+  baseConfig,
+  fakeJwt,
+  fakeVerifier,
+  silentLogger,
+  transportFor,
+} from "../../../extensions/__tests__/composed-support.js";
+import {
+  DEFAULT_INSTANCE_LABEL,
+  RESERVED_LABEL_TRUE,
+} from "../../../pipeline/apiresource-labels.js";
+import {
+  IN_PROCESS_CALLER_HEADER,
+  encodeInProcessCaller,
+} from "../../../pipeline/interceptors/auth.js";
+import { buildDefaultInstanceRequest } from "../defaultinstance.js";
+import {
+  INSTANCE_ORGANIZATION_DENIED_MESSAGE,
+  INSTANCE_PARENT_DENIED_MESSAGE,
+} from "../steps.js";
+
+const FOUNDER = "fake|founder";
+const MEMBER = "fake|member";
+const STRANGER = "fake|stranger";
+const ORG = "instance-authz-org";
+
+function organizationInput(slug: string) {
+  return {
+    apiVersion: "tenancy.stigmer.ai/v1",
+    kind: "Organization",
+    metadata: { name: slug, slug, org: "" },
+    spec: { description: slug },
+  };
+}
+
+function agentInput(name: string, visibility: ApiResourceVisibility) {
+  return {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "Agent",
+    metadata: { name, org: ORG, visibility },
+    spec: { instructions: "a conformant instruction body" },
+  };
+}
+
+function instanceInput(
+  name: string,
+  agentId: string,
+  org: string = ORG,
+  labels: Record<string, string> = {},
+) {
+  return {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "AgentInstance",
+    metadata: { name, org, labels },
+    spec: { agentId, description: name },
+  };
+}
+
+async function failureOf(promise: Promise<unknown>): Promise<ConnectError> {
+  try {
+    await promise;
+  } catch (error) {
+    return ConnectError.from(error);
+  }
+  throw new Error("expected the call to fail");
+}
+
+describe("agent instance create under the built-in authorizer", () => {
+  let dir: string;
+  let server: ComposedServer;
+  let port: number;
+  let orgAgent: Agent;
+  let privateAgent: Agent;
+
+  const asFounder = () =>
+    transportFor(port, fakeJwt(FOUNDER, "founder@example.com"));
+  const asMember = () =>
+    transportFor(port, fakeJwt(MEMBER, "member@example.com"));
+  const asStranger = () =>
+    transportFor(port, fakeJwt(STRANGER, "stranger@example.com"));
+
+  beforeAll(async () => {
+    dir = mkdtempSync(path.join(tmpdir(), "instance-create-authz-"));
+    const unit: ServerExtension = {
+      name: "fake-oidc-only",
+      requireAuthentication: true,
+      identityVerifiers: [fakeVerifier],
+    };
+    server = await composeServer({
+      config: loadConfig(baseConfig(dir)),
+      logger: silentLogger,
+      extensions: [unit],
+      portOverride: 0,
+      host: "127.0.0.1",
+    });
+    port = await server.start();
+
+    // The membership rules of a self-host: a person who provisions while
+    // the organization exists joins it as a member; a person provisioned
+    // BEFORE it was founded holds no row on it. So the stranger provisions
+    // first, the founder founds, and the member provisions after.
+    await createClient(
+      IdentityAccountCommandController,
+      asFounder(),
+    ).provisionMyAccount({});
+    await createClient(
+      IdentityAccountCommandController,
+      asStranger(),
+    ).provisionMyAccount({});
+    await createClient(OrganizationCommandController, asFounder()).create(
+      organizationInput(ORG),
+    );
+    await createClient(
+      IdentityAccountCommandController,
+      asMember(),
+    ).provisionMyAccount({});
+
+    const founderAgents = createClient(AgentCommandController, asFounder());
+    orgAgent = await founderAgents.create(
+      agentInput("Org Agent", ApiResourceVisibility.visibility_org),
+    );
+    privateAgent = await founderAgents.create(
+      agentInput("Private Agent", ApiResourceVisibility.visibility_private),
+    );
+  });
+
+  afterAll(async () => {
+    await server.shutdown();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("a member creates a personal instance of an org-visible agent in their organization", async () => {
+    const created = await createClient(
+      AgentInstanceCommandController,
+      asMember(),
+    ).create(instanceInput("member-personal", orgAgent.metadata!.id));
+    expect(created.metadata?.org).toBe(ORG);
+    expect(created.status?.audit?.specAudit?.createdBy?.id).toBe(MEMBER);
+  });
+
+  it("a member is refused an instance of a PRIVATE agent with the parent's copy", async () => {
+    const error = await failureOf(
+      createClient(AgentInstanceCommandController, asMember()).create(
+        instanceInput("member-on-private", privateAgent.metadata!.id),
+      ),
+    );
+    expect(error.code).toBe(Code.PermissionDenied);
+    expect(error.rawMessage).toBe(INSTANCE_PARENT_DENIED_MESSAGE);
+  });
+
+  it("an outsider naming the organization is refused with the organization's copy, before the agent is named", async () => {
+    const error = await failureOf(
+      createClient(AgentInstanceCommandController, asStranger()).create(
+        instanceInput("stranger-instance", orgAgent.metadata!.id),
+      ),
+    );
+    expect(error.code).toBe(Code.PermissionDenied);
+    expect(error.rawMessage).toBe(INSTANCE_ORGANIZATION_DENIED_MESSAGE);
+  });
+
+  it("the reserved default-instance label buys nothing from the wire", async () => {
+    const error = await failureOf(
+      createClient(AgentInstanceCommandController, asMember()).create(
+        instanceInput("wire-default", orgAgent.metadata!.id, ORG, {
+          [DEFAULT_INSTANCE_LABEL]: RESERVED_LABEL_TRUE,
+        }),
+      ),
+    );
+    // The personal bar admits a member on an org-visible agent; the label
+    // guard then refuses the reserved label a wire caller may not write.
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toContain(DEFAULT_INSTANCE_LABEL);
+  });
+
+  it("the same labelled request composed in-process for the member is admitted and attributed to them (the self-heal's shape)", async () => {
+    const member = await fakeVerifier.verify(
+      fakeJwt(MEMBER, "member@example.com"),
+    );
+    if (member === null) {
+      throw new Error("the fake verifier must admit the member");
+    }
+    // The agent's own default instance already exists (agent create made
+    // it); the self-heal's request is the same shape under a slug the store
+    // does not hold yet, which is what a legacy agent without one presents.
+    const request = buildDefaultInstanceRequest(orgAgent.metadata!);
+    request.metadata!.name = "org-agent-default-healed";
+    const created = await createClient(
+      AgentInstanceCommandController,
+      server.inProcessTransport,
+    ).create(request, {
+      headers: { [IN_PROCESS_CALLER_HEADER]: encodeInProcessCaller(member) },
+    });
+    expect(created.metadata?.labels?.[DEFAULT_INSTANCE_LABEL]).toBe(
+      RESERVED_LABEL_TRUE,
+    );
+    expect(created.metadata?.org).toBe(ORG);
+    expect(created.status?.audit?.specAudit?.createdBy?.id).toBe(MEMBER);
+  });
+});

package/src/domain/agentinstance/__tests__/create-authorization.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Pins the create lane's authorization questions (steps.ts,
+ * resolveInstanceCreateTargets): a personal instance asks the
+ * organization's bar (can_create_agent_instance on metadata.org) and then
+ * the parent's (can_create_instance on the agent), each with its own copy;
+ * a default instance the server composed in-process for the parent's
+ * organization asks nothing; a labelled request that arrived on the wire,
+ * or that names another organization, takes the personal bar in full; a
+ * missing parent is a thrown chain invariant, never an open lane.
+ */
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+
+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 { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import type { CallerIdentity } from "../../../extensions/identity.js";
+import {
+  DEFAULT_INSTANCE_LABEL,
+  RESERVED_LABEL_TRUE,
+} from "../../../pipeline/apiresource-labels.js";
+import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import { RequestContext } from "../../../pipeline/request-context.js";
+import {
+  INSTANCE_ORGANIZATION_DENIED_MESSAGE,
+  INSTANCE_PARENT_DENIED_MESSAGE,
+  PARENT_AGENT_KEY,
+  resolveInstanceCreateTargets,
+} from "../steps.js";
+
+const parent = create(AgentSchema, {
+  metadata: { id: "agt_01parent", name: "helper", org: "acme" },
+});
+
+function ctxFor(
+  org: string,
+  caller: CallerIdentity,
+  labels: Record<string, string> = {},
+  stashParent = true,
+) {
+  const ctx = new RequestContext(
+    AgentInstanceSchema,
+    create(AgentInstanceSchema, {
+      metadata: { name: "mine", org, labels },
+      spec: { agentId: parent.metadata!.id },
+    }),
+    caller,
+    ApiResourceKind.agent_instance,
+  );
+  if (stashParent) {
+    ctx.set(PARENT_AGENT_KEY, parent);
+  }
+  return ctx;
+}
+
+const DEFAULT_LABELS = { [DEFAULT_INSTANCE_LABEL]: RESERVED_LABEL_TRUE };
+
+describe("resolveInstanceCreateTargets", () => {
+  it("a personal instance asks the organization's bar first, then the parent's, each with its own copy", () => {
+    expect(
+      resolveInstanceCreateTargets(ctxFor("acme", testCallerIdentity())),
+    ).toEqual([
+      {
+        permission: IamPermission.can_create_agent_instance,
+        resourceKind: ApiResourceKind.organization,
+        resourceId: "acme",
+        deniedMessage: INSTANCE_ORGANIZATION_DENIED_MESSAGE,
+      },
+      {
+        permission: IamPermission.can_create_instance,
+        resourceKind: ApiResourceKind.agent,
+        resourceId: "agt_01parent",
+        deniedMessage: INSTANCE_PARENT_DENIED_MESSAGE,
+      },
+    ]);
+  });
+
+  it("a cross-org personal instance asks about ITS organization, not the parent's (the marketplace case)", () => {
+    const [orgBar] = resolveInstanceCreateTargets(
+      ctxFor("consumer-org", testCallerIdentity()),
+    );
+    expect(orgBar?.resourceId).toBe("consumer-org");
+  });
+
+  it("a default instance the server composed in-process for the parent's organization asks nothing", () => {
+    expect(
+      resolveInstanceCreateTargets(
+        ctxFor(
+          "acme",
+          testCallerIdentity({ callerClass: "user", origin: "in-process" }),
+          DEFAULT_LABELS,
+        ),
+      ),
+    ).toEqual([]);
+    expect(
+      resolveInstanceCreateTargets(
+        ctxFor(
+          "acme",
+          testCallerIdentity({ callerClass: "channel", origin: "in-process" }),
+          DEFAULT_LABELS,
+        ),
+      ),
+    ).toEqual([]);
+  });
+
+  it("the label alone buys nothing: a labelled request from the wire takes the personal bar in full, the machine class included", () => {
+    expect(
+      resolveInstanceCreateTargets(
+        ctxFor("acme", testCallerIdentity(), DEFAULT_LABELS),
+      ),
+    ).toHaveLength(2);
+    expect(
+      resolveInstanceCreateTargets(
+        ctxFor(
+          "acme",
+          testCallerIdentity({ callerClass: "machine" }),
+          DEFAULT_LABELS,
+        ),
+      ),
+    ).toHaveLength(2);
+  });
+
+  it("a labelled in-process request for another organization is not a default instance to this step", () => {
+    expect(
+      resolveInstanceCreateTargets(
+        ctxFor(
+          "other-org",
+          testCallerIdentity({ callerClass: "user", origin: "in-process" }),
+          DEFAULT_LABELS,
+        ),
+      ),
+    ).toHaveLength(2);
+  });
+
+  it("a missing parent is a broken chain invariant and throws", () => {
+    expect(() =>
+      resolveInstanceCreateTargets(
+        ctxFor("acme", testCallerIdentity(), {}, false),
+      ),
+    ).toThrow("parent agent not found in context");
+  });
+});

package/src/domain/agentinstance/controller.ts

@@ -10,13 +10,13 @@
  * Proven by agentinstance.conformance.test.ts (CONFORMANCE_TARGET=local)
  * and __tests__/agentinstance.test.ts.
  *
- * Versus Stigmer Cloud, OSS excludes the Authorize (FGA
- * can_create_instance on the parent agent), CreateIamPolicies, and Publish
+ * Versus Stigmer Cloud, OSS excludes the CreateIamPolicies and Publish
  * steps. Deliberately NO same-org rule on create, unlike WorkflowInstance:
  * an agent is a shareable blueprint, and one agent legitimately has
- * instances in several orgs (the marketplace case) — cloud governs
- * cross-org creation with FGA on the parent agent; OSS has no
- * authorization layer, so cross-org creation is allowed.
+ * instances in several orgs (the marketplace case). What governs a
+ * cross-org instance in both editions is the create lane's authorization
+ * (steps.ts, resolveInstanceCreateTargets): the caller's standing in the
+ * instance's organization and on the parent agent.
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
 
@@ -47,6 +47,10 @@ import type { PipelineStep } from "../../pipeline/pipeline.js";
 import { callerIdentityOf } from "../../pipeline/interceptors/auth.js";
 import { RequestContext } from "../../pipeline/request-context.js";
 import { newAuthorizeStep } from "../../pipeline/steps/authorize.js";
+import {
+  loadedTargetAsMethod,
+  newAuthorizeResolvedTargetStep,
+} from "../../pipeline/steps/authorize-resolved-target.js";
 import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-labels.js";
 import {
   newAuthorizeVisibilityTransitionStep,
@@ -106,6 +110,7 @@ import {
   newLoadParentAgentStep,
   newRejectDefaultInstanceVisibilityUpdateStep,
   newValidateInstanceUpdateStep,
+  resolveInstanceCreateTargets,
 } from "./steps.js";
 import type { ParentAgentLoaderProvider } from "./steps.js";
 
@@ -181,6 +186,14 @@ async function createInstance(
     .addStep(newValidateVisibilityStep())
     .addStep(newResolveSlugStep())
     .addStep(newLoadParentAgentStep(deps.parentAgentLoader, deps.logger))
+    // Before the duplicate check, so a refused caller learns nothing about
+    // which slugs exist (steps.ts, resolveInstanceCreateTargets).
+    .addStep(
+      newAuthorizeResolvedTargetStep(
+        deps.authorizer,
+        resolveInstanceCreateTargets,
+      ),
+    )
     .addStep(newCheckDuplicateStep(deps.store))
     .addStep(newBuildNewStateStep())
     .addStep(newGuardPublicVisibilityStep(deps.authorizer))
@@ -548,6 +561,12 @@ async function getByReference(
     )
     .addStep(newValidateProtoStep())
     .addStep(newLoadByReferenceStep(deps.store, AgentInstanceSchema))
+    .addStep(
+      newAuthorizeResolvedTargetStep(
+        deps.authorizer,
+        loadedTargetAsMethod(AgentInstanceQueryController.method.get),
+      ),
+    )
     .build()
     .execute(reqCtx);
   return reqCtx.get(TARGET_RESOURCE_KEY) as AgentInstance;

package/src/domain/agentinstance/steps.ts

@@ -16,8 +16,10 @@ import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinst
 import { AgentInstanceListSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/io_pb";
 import { AgentInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/query_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 
 import type { Logger } from "../../boot/logger.js";
+import { isServerComposedRequest } from "../../extensions/identity.js";
 import { isDefaultInstance } from "../../pipeline/apiresource-labels.js";
 import {
   failedPreconditionError,
@@ -29,6 +31,7 @@ import type { ListReadScope } from "../../extensions/list-read-scope.js";
 import { restrictListByReadScope } from "../../extensions/list-read-scope.js";
 import type { PipelineStep } from "../../pipeline/pipeline.js";
 import type { RequestContext } from "../../pipeline/request-context.js";
+import type { AuthorizationTarget } from "../../pipeline/steps/authorize.js";
 import {
   compareCreatedAtDesc,
   matchesAllLabels,
@@ -54,18 +57,19 @@ export interface ParentAgentLoader {
  */
 export type ParentAgentLoaderProvider = () => ParentAgentLoader;
 
+/** Context key for the loaded parent agent, read by the create check below. */
+export const PARENT_AGENT_KEY = "parent_agent";
+
 /**
  * LoadParentAgent — create.go: an unknown spec.agent_id is rejected with
  * NotFound instead of persisting a dangling instance (oss#645), converging
  * on cloud's LoadParentAgent step and this server's own WorkflowInstance
- * create pipeline.
- *
- * Unlike its WorkflowInstance twin, the loaded agent is NOT stored in the
- * request context: nothing downstream consumes it (cloud's consumer is the
- * FGA authorize step, which OSS excludes; the WorkflowInstance twin's
- * consumer is the same-org rule, which agent instances deliberately do not
- * have — an agent is a shareable blueprint, and one agent legitimately has
- * instances in several orgs: the marketplace case).
+ * create pipeline. The loaded agent is stashed under PARENT_AGENT_KEY for
+ * the authorization step that follows; no same-org rule reads it, because
+ * an agent is a shareable blueprint and one agent legitimately has
+ * instances in several orgs (the marketplace case) — the instance's
+ * organization is the caller's, and the check below asks the caller's
+ * standing there.
  */
 export function newLoadParentAgentStep(
   agentLoader: ParentAgentLoaderProvider,
@@ -95,10 +99,80 @@ export function newLoadParentAgentStep(
         agentId,
         org: parentAgent.metadata?.org ?? "",
       });
+      ctx.set(PARENT_AGENT_KEY, parentAgent);
     },
   };
 }
 
+/** The deny copy of the parent's bar, the Java AgentInstanceCreateHandler's. */
+export const INSTANCE_PARENT_DENIED_MESSAGE =
+  "You don't have permission to create instances of this agent";
+
+/** The deny copy of the organization's bar. */
+export const INSTANCE_ORGANIZATION_DENIED_MESSAGE =
+  "unauthorized to create agent instance in this organization";
+
+/**
+ * The create lane's authorization questions, for AuthorizeResolvedTarget
+ * after LoadParentAgent. The RPC is is_skip_authorization because its
+ * target is the PARENT, loaded from spec.agent_id, not a request field.
+ *
+ * A personal instance asks two questions, the organization's first so an
+ * outsider learns nothing about the agent from which copy came back:
+ * may the caller create instances in metadata.org (can_create_agent_instance,
+ * member-level: the instance is the caller's conversation shell in their
+ * own organization, which may differ from the agent's — the marketplace
+ * case), and may the caller instantiate this agent (can_create_instance on
+ * the parent, which the model resolves to whoever may run it).
+ *
+ * A DEFAULT instance asks nothing: it is the agent's row, not the caller's.
+ * The server composes one for the run's human when the agent has none
+ * (attribution stays the person's), and the run was already admitted one
+ * step earlier by the lane that vouched for it — a guest, a channel turn,
+ * a schedule fire hold no viewer tuple on the agent and would be refused
+ * here for a row that is not theirs. The arm is keyed on what only the
+ * server can produce: the request entered through the in-process transport
+ * (the wire cannot claim that; the propagation header is stripped at the
+ * chassis), it carries the reserved default-instance label (which the label
+ * guard lets only such a request write), and its organization is the
+ * parent's (the invariant buildDefaultInstanceRequest holds). A labelled
+ * request that fails any of the three takes the personal bar in full — a
+ * mis-orged default instance is judged as the human's own act, never waved
+ * through.
+ */
+export function resolveInstanceCreateTargets(
+  ctx: RequestContext<typeof AgentInstanceSchema>,
+): ReadonlyArray<AuthorizationTarget> {
+  const parent = ctx.get(PARENT_AGENT_KEY) as Agent | undefined;
+  if (parent === undefined) {
+    throw new Error("parent agent not found in context");
+  }
+  const metadata = ctx.newState.metadata;
+  const org = metadata?.org ?? "";
+  const parentId = parent.metadata?.id ?? "";
+  if (
+    isDefaultInstance(metadata) &&
+    isServerComposedRequest(ctx.callerIdentity) &&
+    org === (parent.metadata?.org ?? "")
+  ) {
+    return [];
+  }
+  return [
+    {
+      permission: IamPermission.can_create_agent_instance,
+      resourceKind: ApiResourceKind.organization,
+      resourceId: org,
+      deniedMessage: INSTANCE_ORGANIZATION_DENIED_MESSAGE,
+    },
+    {
+      permission: IamPermission.can_create_instance,
+      resourceKind: ApiResourceKind.agent,
+      resourceId: parentId,
+      deniedMessage: INSTANCE_PARENT_DENIED_MESSAGE,
+    },
+  ];
+}
+
 /**
  * ValidateInstanceUpdate — update.go: enforces the instance's immutable
  * identity on update — spec.agent_id must keep referencing the same agent.

package/src/domain/agentshare/__tests__/create-authorization.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Pins the create lane's two-arm consent bar (steps.ts,
+ * resolveShareCreateTargets), the Java handler's: a same-org share asks
+ * can_edit on the referenced agent; a cross-org share asks can_execute on
+ * the agent and then can_create_agent_share on the SHARING organization,
+ * agent first; each question carries its byte-pinned copy; a missing
+ * referenced agent throws.
+ */
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+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 { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import { RequestContext } from "../../../pipeline/request-context.js";
+import {
+  REFERENCED_AGENT_KEY,
+  SHARE_AGENT_DENIED_MESSAGE,
+  SHARE_ORGANIZATION_DENIED_MESSAGE,
+  resolveShareCreateTargets,
+} from "../steps.js";
+
+const agent = create(AgentSchema, {
+  metadata: { id: "agt_01public", name: "helper", org: "publisher-org" },
+});
+
+function ctxFor(shareOrg: string, agentOrg: string, stash = true) {
+  const ctx = new RequestContext(
+    AgentShareSchema,
+    create(AgentShareSchema, {
+      metadata: { name: "helper", org: shareOrg },
+      spec: { agentRef: { org: agentOrg, slug: "helper" } },
+    }),
+    testCallerIdentity(),
+    ApiResourceKind.agent_share,
+  );
+  if (stash) {
+    ctx.set(REFERENCED_AGENT_KEY, agent);
+  }
+  return ctx;
+}
+
+describe("resolveShareCreateTargets", () => {
+  it("a same-org share asks can_edit on the referenced agent", () => {
+    expect(
+      resolveShareCreateTargets(ctxFor("publisher-org", "publisher-org")),
+    ).toEqual([
+      {
+        permission: IamPermission.can_edit,
+        resourceKind: ApiResourceKind.agent,
+        resourceId: "agt_01public",
+        deniedMessage: SHARE_AGENT_DENIED_MESSAGE,
+      },
+    ]);
+  });
+
+  it("a cross-org share asks can_execute on the agent, then can_create_agent_share on the sharing organization", () => {
+    expect(
+      resolveShareCreateTargets(ctxFor("consumer-org", "publisher-org")),
+    ).toEqual([
+      {
+        permission: IamPermission.can_execute,
+        resourceKind: ApiResourceKind.agent,
+        resourceId: "agt_01public",
+        deniedMessage: SHARE_AGENT_DENIED_MESSAGE,
+      },
+      {
+        permission: IamPermission.can_create_agent_share,
+        resourceKind: ApiResourceKind.organization,
+        resourceId: "consumer-org",
+        deniedMessage: SHARE_ORGANIZATION_DENIED_MESSAGE,
+      },
+    ]);
+  });
+
+  it("a missing referenced agent is a broken chain invariant and throws", () => {
+    expect(() =>
+      resolveShareCreateTargets(
+        ctxFor("publisher-org", "publisher-org", false),
+      ),
+    ).toThrow("referenced agent not found in context");
+  });
+});