@stigmer/server 3.20.0 → 3.22.0

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");
+  });
+});

package/src/domain/agentshare/__tests__/member-audience.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Pins AuthorizeMemberAudience (steps.ts), the member-profile lane's gate:
+ * membership (can_view on the reference's organization) is asked before
+ * the share is loaded; deny and not-found both answer the lane's one
+ * NOT_FOUND, byte-identical to a missing share, so a share URL teaches a
+ * non-member nothing; unavailable is INTERNAL; an empty org asks nothing
+ * and is left to the loader's INVALID_ARGUMENT; the internal class skips.
+ */
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import type {
+  Authorizer,
+  AuthzCheck,
+  AuthzDecision,
+} from "../../../extensions/authorizer.js";
+import type { CallerIdentity } from "../../../extensions/identity.js";
+import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import { RequestContext } from "../../../pipeline/request-context.js";
+import { AUTHORIZATION_UNAVAILABLE_MESSAGE } from "../../../pipeline/steps/authorize.js";
+import { newAuthorizeMemberAudienceStep, sharedNotFound } from "../steps.js";
+
+function fakeAuthorizer(decision: AuthzDecision): {
+  authorizer: Authorizer;
+  checks: AuthzCheck[];
+} {
+  const checks: AuthzCheck[] = [];
+  return {
+    checks,
+    authorizer: {
+      authorize(_caller, check) {
+        checks.push(check);
+        return Promise.resolve(decision);
+      },
+    },
+  };
+}
+
+function ctxFor(org: string, caller: CallerIdentity = testCallerIdentity()) {
+  return new RequestContext(
+    ApiResourceReferenceSchema,
+    create(ApiResourceReferenceSchema, { org, slug: "helper" }),
+    caller,
+    ApiResourceKind.agent_share,
+  );
+}
+
+async function captureError(
+  run: () => void | Promise<void>,
+): Promise<ConnectError> {
+  try {
+    await run();
+  } catch (error) {
+    return ConnectError.from(error);
+  }
+  throw new Error("expected the step to reject");
+}
+
+describe("AuthorizeMemberAudience", () => {
+  it("asks can_view on the reference's organization and admits an allow", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+    await newAuthorizeMemberAudienceStep(authorizer).execute(ctxFor("acme"));
+    expect(checks).toEqual([
+      {
+        permission: IamPermission.can_view,
+        resourceKind: ApiResourceKind.organization,
+        resourceId: "acme",
+      },
+    ]);
+  });
+
+  it("deny and not-found both answer the lane's NOT_FOUND, byte-identical to a missing share", async () => {
+    for (const decision of [
+      { kind: "deny", reason: "not a member" },
+      { kind: "not-found" },
+    ] as const) {
+      const { authorizer } = fakeAuthorizer(decision);
+      const error = await captureError(() =>
+        newAuthorizeMemberAudienceStep(authorizer).execute(ctxFor("acme")),
+      );
+      expect(error.code).toBe(Code.NotFound);
+      expect(error.rawMessage).toBe(sharedNotFound("helper").rawMessage);
+    }
+  });
+
+  it("unavailable is INTERNAL, never a refusal", async () => {
+    const { authorizer } = fakeAuthorizer({
+      kind: "unavailable",
+      cause: new Error("backend down"),
+    });
+    const error = await captureError(() =>
+      newAuthorizeMemberAudienceStep(authorizer).execute(ctxFor("acme")),
+    );
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(AUTHORIZATION_UNAVAILABLE_MESSAGE);
+  });
+
+  it("an empty org asks nothing (the loader's INVALID_ARGUMENT answers), and the internal class skips", async () => {
+    const denying = fakeAuthorizer({ kind: "deny", reason: "" });
+    await newAuthorizeMemberAudienceStep(denying.authorizer).execute(
+      ctxFor(""),
+    );
+    await newAuthorizeMemberAudienceStep(denying.authorizer).execute(
+      ctxFor("acme", testCallerIdentity({ callerClass: "internal" })),
+    );
+    expect(denying.checks).toEqual([]);
+  });
+});

package/src/domain/agentshare/controller.ts

@@ -60,6 +60,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 {
   newBuildNewStateStep,
@@ -109,6 +113,8 @@ import {
   newValidateShareUpdateStep,
   sharedNotFound,
   sharingLinkTokenAllowed,
+  resolveShareCreateTargets,
+  newAuthorizeMemberAudienceStep,
 } from "./steps.js";
 
 export interface AgentShareControllerDeps {
@@ -176,6 +182,13 @@ async function createShare(
     .addStep(newValidateProtoStep())
     .addStep(newValidateVisibilityStep())
     .addStep(newResolveShareDefaultsStep(deps.store))
+    // Before the duplicate check (steps.ts, resolveShareCreateTargets).
+    .addStep(
+      newAuthorizeResolvedTargetStep(
+        deps.authorizer,
+        resolveShareCreateTargets,
+      ),
+    )
     .addStep(newResolveSlugStep())
     .addStep(newCheckDuplicateStep(deps.store))
     .addStep(newBuildNewStateStep())
@@ -491,6 +504,12 @@ async function getByReference(
     )
     .addStep(newValidateProtoStep())
     .addStep(newLoadByReferenceStep(deps.store, AgentShareSchema))
+    .addStep(
+      newAuthorizeResolvedTargetStep(
+        deps.authorizer,
+        loadedTargetAsMethod(AgentShareQueryController.method.get),
+      ),
+    )
     .build()
     .execute(reqCtx);
   return reqCtx.get(TARGET_RESOURCE_KEY) as AgentShare;
@@ -797,6 +816,8 @@ async function getSharedProfileForMember(
       ),
     )
     .addStep(newValidateProtoStep())
+    // Membership before existence (steps.ts, AuthorizeMemberAudience).
+    .addStep(newAuthorizeMemberAudienceStep(deps.authorizer))
     .addStep(newLoadShareForMemberProfileStep(deps.store))
     .addStep(newProjectMemberSharedProfileStep(deps.store))
     .build()