@stigmer/server 3.14.0 → 3.15.0

package/src/pipeline/steps/__tests__/authorize-run-target.test.ts

@@ -0,0 +1,261 @@
+/**
+ * Pins the AuthorizeRunTarget step's contract (P1 sp.run-gate, 2026-09-11):
+ * the step is a thin shell around authorizeResolvedResource — a resolver
+ * that answers no target makes NO check (the chain's own invariant guards
+ * own the shape-less arm); a resolved target reaches the Authorizer
+ * verbatim; deny carries the RESOLVER's copy; not-found answers the
+ * load-first NOT_FOUND; unavailable is INTERNAL; the internal caller class
+ * skips. Also pins isRunGateCheck: exactly the five (kind, permission)
+ * pairs the resolvers can produce, and nothing adjacent — the cloud's
+ * lane-admission decorator keys on this predicate, so a drift here would
+ * either deny a schedule fire or admit a lane to a check it never owned.
+ */
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/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 {
+  Authorizer,
+  AuthzCheck,
+  AuthzDecision,
+} from "../../../extensions/authorizer.js";
+import { testCallerIdentity } from "../../__tests__/support.js";
+import { RequestContext } from "../../request-context.js";
+import { AUTHORIZATION_UNAVAILABLE_MESSAGE } from "../authorize.js";
+import {
+  RUN_GATE_CHECKS,
+  isRunGateCheck,
+  newAuthorizeRunTargetStep,
+} from "../authorize-run-target.js";
+import type { RunTarget } from "../authorize-run-target.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);
+      },
+    },
+  };
+}
+
+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");
+}
+
+const TARGET: RunTarget = {
+  ...RUN_GATE_CHECKS.agentInstance,
+  resourceId: "agi_01target",
+  deniedMessage: "unauthorized to run agent instance 'agi_01target'",
+};
+
+function sessionCtx(callerClass?: string) {
+  return new RequestContext(
+    SessionSchema,
+    create(SessionSchema, { metadata: { name: "s", org: "acme" } }),
+    callerClass === undefined
+      ? testCallerIdentity()
+      : testCallerIdentity({ callerClass }),
+    ApiResourceKind.session,
+  );
+}
+
+describe("AuthorizeRunTarget — the step shell", () => {
+  it("is named AuthorizeRunTarget in every chain (shared vocabulary)", () => {
+    const { authorizer } = fakeAuthorizer({ kind: "allow" });
+    const step = newAuthorizeRunTargetStep<typeof SessionSchema>(
+      authorizer,
+      () => TARGET,
+    );
+    expect(step.name).toBe("AuthorizeRunTarget");
+  });
+
+  it("makes NO check when the resolver answers no target", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "deny", reason: "" });
+    const step = newAuthorizeRunTargetStep<typeof SessionSchema>(
+      authorizer,
+      () => undefined,
+    );
+    await step.execute(sessionCtx());
+    expect(checks).toEqual([]);
+  });
+
+  it("hands the resolved target to the Authorizer verbatim and proceeds on allow", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+    const seen: unknown[] = [];
+    const step = newAuthorizeRunTargetStep<typeof SessionSchema>(
+      authorizer,
+      (record) => {
+        seen.push(record);
+        return TARGET;
+      },
+    );
+    const ctx = sessionCtx();
+    await step.execute(ctx);
+    expect(checks).toEqual([
+      {
+        permission: IamPermission.can_execute,
+        resourceKind: ApiResourceKind.agent_instance,
+        resourceId: "agi_01target",
+      },
+    ]);
+    // The resolver reads the record being BUILT (newState), where the
+    // chain's own resolution steps write, never the immutable input.
+    expect(seen).toEqual([ctx.newState]);
+  });
+
+  it("deny → PERMISSION_DENIED carrying the resolver's copy", async () => {
+    const { authorizer } = fakeAuthorizer({
+      kind: "deny",
+      reason: "fga said no",
+    });
+    const step = newAuthorizeRunTargetStep<typeof SessionSchema>(
+      authorizer,
+      () => TARGET,
+    );
+    const err = await captureError(() => step.execute(sessionCtx()));
+    expect(err.code).toBe(Code.PermissionDenied);
+    expect(err.rawMessage).toBe(TARGET.deniedMessage);
+  });
+
+  it("not-found → the load-first chain's NOT_FOUND naming the target", async () => {
+    const { authorizer } = fakeAuthorizer({ kind: "not-found" });
+    const step = newAuthorizeRunTargetStep<typeof SessionSchema>(
+      authorizer,
+      () => TARGET,
+    );
+    const err = await captureError(() => step.execute(sessionCtx()));
+    expect(err.code).toBe(Code.NotFound);
+    expect(err.rawMessage).toContain("agi_01target");
+  });
+
+  it("unavailable → INTERNAL, never a softened denial", async () => {
+    const { authorizer } = fakeAuthorizer({
+      kind: "unavailable",
+      cause: new Error("fga down"),
+    });
+    const step = newAuthorizeRunTargetStep<typeof SessionSchema>(
+      authorizer,
+      () => TARGET,
+    );
+    const err = await captureError(() => step.execute(sessionCtx()));
+    expect(err.code).toBe(Code.Internal);
+    expect(err.rawMessage).toBe(AUTHORIZATION_UNAVAILABLE_MESSAGE);
+  });
+
+  it("the internal caller class skips (the server acting as itself)", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "deny", reason: "" });
+    const step = newAuthorizeRunTargetStep<typeof SessionSchema>(
+      authorizer,
+      () => TARGET,
+    );
+    await step.execute(sessionCtx("internal"));
+    expect(checks).toEqual([]);
+  });
+
+  it("every other caller class is checked — a lane is admitted by its Authorizer, never by this step", async () => {
+    for (const callerClass of [
+      "user",
+      "machine",
+      "runner",
+      "guest",
+      "schedule",
+      "workflow_sandbox",
+    ]) {
+      const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+      const step = newAuthorizeRunTargetStep<typeof SessionSchema>(
+        authorizer,
+        () => TARGET,
+      );
+      await step.execute(sessionCtx(callerClass));
+      expect(checks, callerClass).toHaveLength(1);
+    }
+  });
+});
+
+describe("isRunGateCheck — the one definition of the run-gate check set", () => {
+  const pairs: ReadonlyArray<[string, ApiResourceKind, IamPermission]> = [
+    ["agent", ApiResourceKind.agent, IamPermission.can_execute],
+    [
+      "agent_instance",
+      ApiResourceKind.agent_instance,
+      IamPermission.can_execute,
+    ],
+    ["session", ApiResourceKind.session, IamPermission.can_create_execution_in],
+    ["workflow", ApiResourceKind.workflow, IamPermission.can_execute],
+    [
+      "workflow_instance",
+      ApiResourceKind.workflow_instance,
+      IamPermission.can_execute,
+    ],
+  ];
+
+  it.each(pairs)(
+    "%s is a run-gate check",
+    (_name, resourceKind, permission) => {
+      expect(
+        isRunGateCheck({ permission, resourceKind, resourceId: "x" }),
+      ).toBe(true);
+    },
+  );
+
+  it("names exactly five checks, one per entry the resolvers draw from", () => {
+    expect(Object.keys(RUN_GATE_CHECKS).sort()).toEqual(
+      [
+        "agent",
+        "agentInstance",
+        "session",
+        "workflow",
+        "workflowInstance",
+      ].sort(),
+    );
+    for (const [, resourceKind, permission] of pairs) {
+      expect(
+        Object.values(RUN_GATE_CHECKS).filter(
+          (c) => c.resourceKind === resourceKind && c.permission === permission,
+        ),
+      ).toHaveLength(1);
+    }
+  });
+
+  it.each([
+    ["session#can_view", ApiResourceKind.session, IamPermission.can_view],
+    ["agent#can_edit", ApiResourceKind.agent, IamPermission.can_edit],
+    ["agent#can_view", ApiResourceKind.agent, IamPermission.can_view],
+    [
+      "agent_execution#can_execute",
+      ApiResourceKind.agent_execution,
+      IamPermission.can_execute,
+    ],
+    [
+      "organization#can_create_session",
+      ApiResourceKind.organization,
+      IamPermission.can_create_session,
+    ],
+    ["session#can_execute", ApiResourceKind.session, IamPermission.can_execute],
+  ] as const)(
+    "%s is NOT a run-gate check",
+    (_name, resourceKind, permission) => {
+      expect(
+        isRunGateCheck({ permission, resourceKind, resourceId: "x" }),
+      ).toBe(false);
+    },
+  );
+});

package/src/pipeline/steps/authorize-run-target.ts

@@ -0,0 +1,148 @@
+/**
+ * AuthorizeRunTarget — the run gate (P1 sp.run-gate, 2026-09-11;
+ * stigmer-cloud#709): may this caller RUN what this record targets?
+ *
+ * Every create that starts or continues a run names a target — a blueprint
+ * (`agent`, `workflow`), an instance (`agent_instance`, `workflow_instance`)
+ * or a conversation (`session`) — and until this step nothing asked whether
+ * the caller may use it: session-create authorized only the organization's
+ * `can_create_session`, agent- and workflow-execution create are
+ * `is_skip_authorization`, and `can_execute` was defined on every blueprint
+ * and instance type of the FGA model and checked nowhere. The invariant the
+ * model states ("you can run what you can read") is enforced here.
+ *
+ * One shared step, one domain resolver: the shape of IndexSearch (a shared
+ * step over a domain extractor). The resolver is a PURE function of the
+ * record being built (`ctx.newState`, where the chain's own resolution
+ * steps write) that names the target and the domain's byte-pinned deny
+ * copy; this step hands it to authorizeResolvedResource — the ratified
+ * mid-chain resolved-id form (DD-007; the ListVersions and listByChannel
+ * precedent) for lanes the position-1 annotation cannot express. A
+ * resolver that answers no target makes NO check: the chain's own
+ * invariant guards (EnsureSessionOrAgentResolved,
+ * ValidateWorkflowOrInstance) own the shape-less arm, and this step never
+ * second-guesses them.
+ *
+ * Position, in every chain: immediately after the step that guarantees the
+ * target reference exists — before EnsureEngineAvailable (a denied caller
+ * learns nothing about engine state), before every gate slot, before every
+ * side effect the chain owns. The chains' own convention, Authorize before
+ * Validate, is what places it there.
+ *
+ * Admission has one owner per lane. This step asks for EVERY caller but the
+ * `internal` class (authorizeResolvedResource's contract): a direct
+ * principal is admitted by the Authorizer; a runtime lane (a guest share, a
+ * channel, a schedule fire, a workflow sandbox's child run) is admitted by
+ * the gate step that vouches for it, and the edition's Authorizer says so
+ * for the lanes it mints — the OSS chain stays policy-free. RUN_GATE_CHECKS
+ * is the one definition of "the run-gate checks" that such an Authorizer
+ * keys on (isRunGateCheck, exported on the barrel); the resolvers draw their
+ * (kind, permission) pairs from the same table, so the predicate cannot
+ * drift from what the step actually asks.
+ */
+import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
+
+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 { Authorizer, AuthzCheck } from "../../extensions/authorizer.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { authorizeResolvedResource } from "./authorize.js";
+
+/** One (kind, permission) pair the run gate asks about. */
+export interface RunGateCheck {
+  readonly permission: IamPermission;
+  readonly resourceKind: ApiResourceKind;
+}
+
+/**
+ * The run-gate check set — exactly the pairs a resolver can produce. Each
+ * is the FGA model's own relation for "may run this": `can_execute` on the
+ * blueprints and instances (`agent.fga` `can_execute: viewer`;
+ * `agent_instance.fga` `can_execute: can_view`; the workflow twins), and
+ * `can_create_execution_in` on a session (`session.fga`: adding a turn to a
+ * conversation is the session's own permission, not the agent's).
+ */
+export const RUN_GATE_CHECKS = {
+  agent: {
+    permission: IamPermission.can_execute,
+    resourceKind: ApiResourceKind.agent,
+  },
+  agentInstance: {
+    permission: IamPermission.can_execute,
+    resourceKind: ApiResourceKind.agent_instance,
+  },
+  session: {
+    permission: IamPermission.can_create_execution_in,
+    resourceKind: ApiResourceKind.session,
+  },
+  workflow: {
+    permission: IamPermission.can_execute,
+    resourceKind: ApiResourceKind.workflow,
+  },
+  workflowInstance: {
+    permission: IamPermission.can_execute,
+    resourceKind: ApiResourceKind.workflow_instance,
+  },
+} as const satisfies Record<string, RunGateCheck>;
+
+const RUN_GATE_CHECK_LIST: ReadonlyArray<RunGateCheck> =
+  Object.values(RUN_GATE_CHECKS);
+
+/**
+ * Whether `check` is one of the run gate's — the predicate an edition's
+ * Authorizer keys its lane admission on. Reads only the pair (an AuthzCheck
+ * is one); the resource id is the target's identity, not part of the
+ * question.
+ */
+export function isRunGateCheck(check: RunGateCheck | AuthzCheck): boolean {
+  return RUN_GATE_CHECK_LIST.some(
+    (candidate) =>
+      candidate.permission === check.permission &&
+      candidate.resourceKind === check.resourceKind,
+  );
+}
+
+/**
+ * A resolved run target: the check plus the domain's byte-pinned deny copy
+ * for it (the lane's error_msg, in the position-1 annotation's terms).
+ */
+export interface RunTarget extends RunGateCheck {
+  readonly resourceId: string;
+  readonly deniedMessage: string;
+}
+
+/**
+ * Names a record's run target, or `undefined` when the record names none
+ * (a state the chain's own guards refuse; never this step's arm). Pure over
+ * the record being built — no store, no clock, no caller.
+ */
+export type RunTargetResolver<Desc extends DescMessage> = (
+  record: MessageShape<Desc>,
+) => RunTarget | undefined;
+
+export function newAuthorizeRunTargetStep<Desc extends DescMessage>(
+  authorizer: Authorizer,
+  resolveRunTarget: RunTargetResolver<Desc>,
+): PipelineStep<Desc> {
+  return {
+    name: "AuthorizeRunTarget",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      const target = resolveRunTarget(ctx.newState);
+      if (target === undefined) {
+        return;
+      }
+      await authorizeResolvedResource(
+        authorizer,
+        ctx.callerIdentity,
+        {
+          permission: target.permission,
+          resourceKind: target.resourceKind,
+          resourceId: target.resourceId,
+        },
+        target.deniedMessage,
+      );
+    },
+  };
+}

package/src/query/search/__tests__/criteria.test.ts

@@ -7,8 +7,12 @@
  */
 import { describe, expect, it } from "vitest";
 
-import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import {
+  ApiResourceKind,
+  ResourceTier,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
+import { getKindMeta } from "../../../pipeline/apiresource-meta.js";
 import {
   DEFAULT_PAGE_SIZE,
   MAX_PAGE_SIZE,
@@ -68,6 +72,19 @@ describe("searchIndexedKinds derivation (kind_meta)", () => {
     expect(kinds).not.toContain(ApiResourceKind.channel_app);
     expect(kinds).not.toContain(ApiResourceKind.memory);
   });
+
+  it("contains no kind above the open_source tier — the index is the core's (editions program)", () => {
+    // Read from the descriptors, not a hand list: a kind re-tiered to
+    // enterprise or cloud_only must drop out of the derivation whatever
+    // its not_search_indexed flag says. Today every such kind is also
+    // not_search_indexed, so this pins a guard, not a behaviour change.
+    for (const kind of searchIndexedKinds()) {
+      expect(
+        getKindMeta(kind).tier,
+        `${ApiResourceKind[kind]} is searchable but not open_source-tier`,
+      ).toBe(ResourceTier.open_source);
+    }
+  });
 });
 
 describe("SearchCriteria normalization (Go NewSearchCriteria)", () => {

package/src/query/search/criteria.ts

@@ -5,7 +5,7 @@
  * discover).
  *
  * The searchable-kind set is DERIVED from the proto kind_meta extension
- * (not_search_indexed: false, tier != cloud_only) — Go's
+ * (not_search_indexed: false, tier == open_source) — Go's
  * SearchIndexedKinds() posture since stigmer/stigmer#439, where hand-copied
  * kind lists drifted from the proto and from each other. Go still carries a
  * hand map (SearchableKinds) pinned to the derivation by an invariant test;
@@ -13,6 +13,13 @@
  * registry unit test pins the registered extractors against this same
  * derivation (the #439 invariant's TS home).
  *
+ * The tier clause admits open_source alone, not "anything but cloud_only":
+ * the index is the core's, and a kind tiered enterprise (editions program,
+ * DD-001) must not enter it by accident. This derivation is edition-blind
+ * by design (the same code runs in every composition); an edition-aware
+ * derivation is a design act with a named trigger — the first searchable
+ * kind above open_source.
+ *
  * kinds are kept VERBATIM from the request; filtering to the searchable set
  * happens in effectiveKinds(). Keeping the raw request is what
  * distinguishes "no kinds requested" (discover mode) from "kinds requested
@@ -45,8 +52,8 @@ let searchableKindSetCache: ReadonlySet<ApiResourceKind> | undefined;
 
 /**
  * Go SearchIndexedKinds(): every kind this edition's search read side
- * serves — kind_meta declares it search-indexed and servable outside the
- * cloud. Sorted ascending by enum value, exactly Go's sort. Kinds whose
+ * serves — kind_meta declares it search-indexed and open_source-tier.
+ * Sorted ascending by enum value, exactly Go's sort. Kinds whose
  * kind_meta cannot be read are skipped (Go's contract; the registry unit
  * test separately fails on such a defect).
  */
@@ -64,7 +71,7 @@ export function searchIndexedKinds(): readonly ApiResourceKind[] {
       } catch {
         continue;
       }
-      if (meta.notSearchIndexed || meta.tier === ResourceTier.cloud_only) {
+      if (meta.notSearchIndexed || meta.tier !== ResourceTier.open_source) {
         continue;
       }
       kinds.push(kind);