@stigmer/server 3.21.0 → 3.22.0

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

@@ -0,0 +1,285 @@
+/**
+ * Pins the AuthorizeResolvedTarget step's contract: a thin shell around the
+ * shared evaluation over the questions a PURE resolver names. Every target
+ * reaches the Authorizer as exactly the three fields of a check (never the
+ * copy); the questions are asked in the resolver's order and the first
+ * refusal answers; an empty list asks nothing; a throwing resolver surfaces
+ * as the chain's Internal, never as an admitted request; deny carries the
+ * target's copy, not-found the load-first NOT_FOUND, unavailable INTERNAL;
+ * the `internal` class alone skips, and a propagated in-process caller does
+ * not (that arm is a resolver's to model, never the step's). The step runs
+ * under the shared name by default and under a caller-supplied frozen name
+ * for the lanes that predate it.
+ *
+ * Also pins `loadedTargetAsMethod`: the reads' resolver asks the sibling
+ * `get` annotation about the LOADED row's id — the `get`'s kind,
+ * permission and byte-pinned copy, the loader's id — and is a no-op when
+ * that `get` is itself a skip, so a read by reference is never stricter
+ * than the read by id and never laxer. A missing loaded row is a thrown
+ * invariant, not an empty answer.
+ */
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+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 { testCallerIdentity } from "../../__tests__/support.js";
+import { RequestContext } from "../../request-context.js";
+import {
+  AUTHORIZATION_UNAVAILABLE_MESSAGE,
+  type AuthorizationTarget,
+} from "../authorize.js";
+import {
+  AUTHORIZE_RESOLVED_TARGET_STEP,
+  loadedTargetAsMethod,
+  newAuthorizeResolvedTargetStep,
+} from "../authorize-resolved-target.js";
+import { TARGET_RESOURCE_KEY } from "../load-target.js";
+
+function fakeAuthorizer(decide: (check: AuthzCheck) => AuthzDecision): {
+  authorizer: Authorizer;
+  checks: AuthzCheck[];
+} {
+  const checks: AuthzCheck[] = [];
+  return {
+    checks,
+    authorizer: {
+      authorize(_caller, check) {
+        checks.push(check);
+        return Promise.resolve(decide(check));
+      },
+    },
+  };
+}
+
+const allow = (): AuthzDecision => ({ kind: "allow" });
+
+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 ORG_QUESTION: AuthorizationTarget = {
+  permission: IamPermission.can_create_agent_instance,
+  resourceKind: ApiResourceKind.organization,
+  resourceId: "acme",
+  deniedMessage: "unauthorized to create agent instance in this organization",
+};
+
+const PARENT_QUESTION: AuthorizationTarget = {
+  permission: IamPermission.can_create_instance,
+  resourceKind: ApiResourceKind.agent,
+  resourceId: "agt_01parent",
+  deniedMessage: "You don't have permission to create instances of this agent",
+};
+
+function agentCtx(caller = testCallerIdentity()) {
+  return new RequestContext(
+    AgentSchema,
+    create(AgentSchema, { metadata: { name: "a", org: "acme" } }),
+    caller,
+    ApiResourceKind.agent,
+  );
+}
+
+describe("AuthorizeResolvedTarget — the step shell", () => {
+  it("runs under the shared name by default and under a frozen name when a folded lane supplies one", () => {
+    const { authorizer } = fakeAuthorizer(allow);
+    expect(newAuthorizeResolvedTargetStep(authorizer, () => []).name).toBe(
+      AUTHORIZE_RESOLVED_TARGET_STEP,
+    );
+    expect(
+      newAuthorizeResolvedTargetStep(
+        authorizer,
+        () => [],
+        "AuthorizeResolvedPlugin",
+      ).name,
+    ).toBe("AuthorizeResolvedPlugin");
+  });
+
+  it("asks nothing when the resolver answers an empty list", async () => {
+    const { authorizer, checks } = fakeAuthorizer(() => ({
+      kind: "deny",
+      reason: "would have refused",
+    }));
+    await newAuthorizeResolvedTargetStep(authorizer, () => []).execute(
+      agentCtx(),
+    );
+    expect(checks).toEqual([]);
+  });
+
+  it("asks each question in the resolver's order, as a bare check without the copy", async () => {
+    const { authorizer, checks } = fakeAuthorizer(allow);
+    await newAuthorizeResolvedTargetStep(authorizer, () => [
+      ORG_QUESTION,
+      PARENT_QUESTION,
+    ]).execute(agentCtx());
+    expect(checks).toEqual([
+      {
+        permission: IamPermission.can_create_agent_instance,
+        resourceKind: ApiResourceKind.organization,
+        resourceId: "acme",
+      },
+      {
+        permission: IamPermission.can_create_instance,
+        resourceKind: ApiResourceKind.agent,
+        resourceId: "agt_01parent",
+      },
+    ]);
+  });
+
+  it("the first refusal answers, with THAT question's copy, and later questions are never asked", async () => {
+    const { authorizer, checks } = fakeAuthorizer((check) =>
+      check.resourceKind === ApiResourceKind.organization
+        ? { kind: "deny", reason: "" }
+        : allow(),
+    );
+    const error = await captureError(() =>
+      newAuthorizeResolvedTargetStep(authorizer, () => [
+        ORG_QUESTION,
+        PARENT_QUESTION,
+      ]).execute(agentCtx()),
+    );
+    expect(error.code).toBe(Code.PermissionDenied);
+    expect(error.rawMessage).toBe(ORG_QUESTION.deniedMessage);
+    expect(checks).toHaveLength(1);
+  });
+
+  it("not-found answers the load-first NOT_FOUND for the target", async () => {
+    const { authorizer } = fakeAuthorizer(() => ({ kind: "not-found" }));
+    const error = await captureError(() =>
+      newAuthorizeResolvedTargetStep(authorizer, () => [
+        PARENT_QUESTION,
+      ]).execute(agentCtx()),
+    );
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toContain("agt_01parent");
+  });
+
+  it("unavailable is INTERNAL with the sanitized copy", async () => {
+    const { authorizer } = fakeAuthorizer(() => ({
+      kind: "unavailable",
+      cause: new Error("backend down"),
+    }));
+    const error = await captureError(() =>
+      newAuthorizeResolvedTargetStep(authorizer, () => [
+        PARENT_QUESTION,
+      ]).execute(agentCtx()),
+    );
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(AUTHORIZATION_UNAVAILABLE_MESSAGE);
+  });
+
+  it("a resolver that throws surfaces its error; a broken chain invariant never admits the request", async () => {
+    const { authorizer, checks } = fakeAuthorizer(allow);
+    await expect(
+      newAuthorizeResolvedTargetStep(authorizer, () => {
+        throw new Error("parent not found in context");
+      }).execute(agentCtx()),
+    ).rejects.toThrow("parent not found in context");
+    expect(checks).toEqual([]);
+  });
+
+  it("the internal class alone skips; a propagated in-process caller is still asked", async () => {
+    const denying = fakeAuthorizer(() => ({ kind: "deny", reason: "" }));
+    await newAuthorizeResolvedTargetStep(denying.authorizer, () => [
+      PARENT_QUESTION,
+    ]).execute(agentCtx(testCallerIdentity({ callerClass: "internal" })));
+    expect(denying.checks).toEqual([]);
+
+    const error = await captureError(() =>
+      newAuthorizeResolvedTargetStep(denying.authorizer, () => [
+        PARENT_QUESTION,
+      ]).execute(
+        agentCtx(
+          testCallerIdentity({ callerClass: "user", origin: "in-process" }),
+        ),
+      ),
+    );
+    expect(error.code).toBe(Code.PermissionDenied);
+  });
+});
+
+function referenceCtx(loaded?: unknown) {
+  const ctx = new RequestContext(
+    ApiResourceReferenceSchema,
+    create(ApiResourceReferenceSchema, { org: "acme", slug: "helper" }),
+    testCallerIdentity(),
+    ApiResourceKind.agent,
+  );
+  if (loaded !== undefined) {
+    ctx.set(TARGET_RESOURCE_KEY, loaded);
+  }
+  return ctx;
+}
+
+describe("loadedTargetAsMethod — a read by reference asks what its get asks", () => {
+  it("names the get annotation's kind, permission and copy on the LOADED row's id", async () => {
+    const { authorizer, checks } = fakeAuthorizer(() => ({
+      kind: "deny",
+      reason: "",
+    }));
+    const loaded = create(AgentSchema, {
+      metadata: { id: "agt_01loaded", name: "helper", org: "acme" },
+    });
+    const error = await captureError(() =>
+      newAuthorizeResolvedTargetStep(
+        authorizer,
+        loadedTargetAsMethod(AgentQueryController.method.get),
+      ).execute(referenceCtx(loaded)),
+    );
+    expect(checks).toEqual([
+      {
+        permission: IamPermission.can_view,
+        resourceKind: ApiResourceKind.agent,
+        resourceId: "agt_01loaded",
+      },
+    ]);
+    expect(error.code).toBe(Code.PermissionDenied);
+    expect(error.rawMessage).toBe("unauthorized to get agent");
+  });
+
+  it("is a no-op when the method it is keyed on is itself a skip — never stricter than the annotation it mirrors", async () => {
+    // Keyed on a skip descriptor (the reference RPC's own), the resolver
+    // answers nothing: the annotation, not the step, owns the skip arms.
+    const { authorizer, checks } = fakeAuthorizer(() => ({
+      kind: "deny",
+      reason: "",
+    }));
+    const loaded = create(AgentSchema, {
+      metadata: { id: "agt_01loaded", name: "helper", org: "acme" },
+    });
+    await newAuthorizeResolvedTargetStep(
+      authorizer,
+      loadedTargetAsMethod(AgentQueryController.method.getByReference),
+    ).execute(referenceCtx(loaded));
+    expect(checks).toEqual([]);
+  });
+
+  it("a missing loaded row is a thrown invariant, never an empty answer", async () => {
+    const { authorizer, checks } = fakeAuthorizer(allow);
+    await expect(
+      newAuthorizeResolvedTargetStep(
+        authorizer,
+        loadedTargetAsMethod(AgentQueryController.method.get),
+      ).execute(referenceCtx()),
+    ).rejects.toThrow(TARGET_RESOURCE_KEY);
+    expect(checks).toEqual([]);
+  });
+});

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

@@ -0,0 +1,129 @@
+/**
+ * AuthorizeResolvedTarget — the ONE mid-chain authorization step: the
+ * question a lane can only ask once its chain has loaded something the
+ * position-1 annotation could not key on.
+ *
+ * The `Authorize` step resolves its target from the REQUEST (a field path
+ * over the input), so it cannot serve two shapes of lane, and both are
+ * `is_skip_authorization` on the wire for that reason alone:
+ *
+ *   - a read by reference: the request carries an org and a slug, the
+ *     target is the row the loader finds, and the question is exactly the
+ *     one the kind's `get` asks by id — `can_view` on that row, with the
+ *     `get` annotation's byte-pinned copy. `loadedTargetAsMethod(get)` is
+ *     that resolver: it reads the row under TARGET_RESOURCE_KEY and asks the
+ *     sibling `get` descriptor's annotation about its id, so the two lanes
+ *     cannot drift (one annotation owns the permission and the copy; a
+ *     `get` that is itself a skip makes the reference read a skip too).
+ *   - a parent-gated create: the request names a parent (an agent to
+ *     schedule, share, channel-bind or instantiate; a workflow to
+ *     instantiate), the domain's resolve step loads and stashes it, and the
+ *     question is the caller's standing on that parent (or on the row's
+ *     organization), with the copy the lane has always answered.
+ *
+ * The step owns nothing but the position and the evaluation: a PURE
+ * resolver over the request context names the questions (kind, id,
+ * permission, copy), in the order the lane asks them; the first refusal
+ * answers. The evaluation is `authorizeTarget` (authorize.ts): allow
+ * proceeds, deny is PERMISSION_DENIED with the copy, not-found is NOT_FOUND
+ * as the load-first chain would answer, unavailable is INTERNAL, and the
+ * `internal` class alone is exempt — the annotation's skip arms do not
+ * apply, because the caller IS the enforcement the annotation opted out of.
+ *
+ * Two contracts a resolver keeps. It returns an EMPTY list only for an arm
+ * the lane has modelled as "nothing to ask" (a default instance the server
+ * composed for the run's human, whose access already follows the parent);
+ * an absent stash, a parent the chain guaranteed and did not deliver, is a
+ * chain invariant broken and the resolver THROWS, so a mis-ordered chain
+ * fails loudly instead of silently reopening the lane. And it names the
+ * questions in the anti-probing order: the organization's bar before the
+ * parent's where both are asked, so an outsider learns nothing about the
+ * parent's grants from which copy came back.
+ *
+ * Position: immediately after the step that loads what the resolver reads,
+ * before the duplicate check, before any engine or store side effect, and
+ * before any step whose refusal would reveal the loaded row (a same-org
+ * rule that names the parent's organization, an enrichment that reads the
+ * row's connections).
+ *
+ * The step's name is the shared vocabulary for every NEW lane. The lanes
+ * that carried a hand-written copy of this body before it existed keep
+ * their frozen names through `stepName` — the version ladder's own
+ * precedent (LoadSkillByReference and LoadPluginByReference are one
+ * factory) — because a step name is never renamed.
+ *
+ * Sibling: `AuthorizeRunTarget` runs the same evaluation over the record
+ * being built (`ctx.newState`) and carries the run-gate doctrine an
+ * edition's lane admission keys on; this step reads what the chain LOADED
+ * and carries no doctrine of its own.
+ */
+import type { DescMessage, DescMethod, Message } from "@bufbuild/protobuf";
+
+import type { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+
+import type { Authorizer } from "../../extensions/authorizer.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { metadataOf } from "./shapes.js";
+import { TARGET_RESOURCE_KEY } from "./load-target.js";
+import {
+  authorizeTarget,
+  resolveAnnotatedCheck,
+  type AuthorizationTarget,
+} from "./authorize.js";
+
+/** The step's shared name; a folded lane passes its own frozen name instead. */
+export const AUTHORIZE_RESOLVED_TARGET_STEP = "AuthorizeResolvedTarget";
+
+/**
+ * Names the questions a lane asks, in order, over the request context after
+ * its chain has loaded the target. Pure: no store, no clock, no side effect.
+ * Empty means the lane has nothing to ask on this request; an invariant the
+ * chain broke (an absent stash) is a throw, never an empty list.
+ */
+export type ResolvedTargetResolver<Desc extends DescMessage> = (
+  ctx: RequestContext<Desc>,
+) => ReadonlyArray<AuthorizationTarget>;
+
+export function newAuthorizeResolvedTargetStep<Desc extends DescMessage>(
+  authorizer: Authorizer,
+  resolve: ResolvedTargetResolver<Desc>,
+  stepName: string = AUTHORIZE_RESOLVED_TARGET_STEP,
+): PipelineStep<Desc> {
+  return {
+    name: stepName,
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      for (const target of resolve(ctx)) {
+        await authorizeTarget(authorizer, ctx.callerIdentity, target);
+      }
+    },
+  };
+}
+
+/** The request shape every `getByReference` lane runs on. */
+export type GetByReferenceDesc = typeof ApiResourceReferenceSchema;
+
+/**
+ * The reads' resolver: the row the loader stashed under TARGET_RESOURCE_KEY,
+ * authorized exactly as `get` would authorize it by id. The `get`
+ * descriptor's annotation supplies the kind, the permission and the copy;
+ * the loaded row's id is the target override (a reference has no `value`
+ * field for the annotation's path to read). A `get` that is public, skip
+ * or unannotated makes this a no-op — the reference read is never stricter
+ * than the read by id, and never laxer.
+ */
+export function loadedTargetAsMethod(
+  get: DescMethod,
+): ResolvedTargetResolver<GetByReferenceDesc> {
+  return (ctx) => {
+    const loaded = ctx.get(TARGET_RESOURCE_KEY) as Message | undefined;
+    const id = loaded === undefined ? undefined : metadataOf(loaded)?.id;
+    if (id === undefined) {
+      throw new Error(
+        `${AUTHORIZE_RESOLVED_TARGET_STEP}: no loaded target with metadata under ${TARGET_RESOURCE_KEY}; the loader must run first`,
+      );
+    }
+    const target = resolveAnnotatedCheck(get, ctx.input, { resourceId: id });
+    return target === undefined ? [] : [target];
+  };
+}

package/src/pipeline/steps/authorize.ts

@@ -56,6 +56,14 @@
  * names no kind because the target is the loaded row's resource). The
  * annotation keeps owning the permission, the copy and the skip arms in
  * both shapes; only the target is the handler's.
+ *
+ * The annotation read itself is one pure function, `resolveAnnotatedCheck`,
+ * so a third entry shape needs no third copy of it: the resolved-target
+ * step (authorize-resolved-target.ts) authorizes a row a chain LOADED as
+ * a sibling method's annotation would — a read by reference asks exactly
+ * what its `get` asks, target override and all — and every lane whose
+ * position-1 annotation is a skip because the target is not in the request
+ * answers its question there, with the same four arms.
  */
 import { Code, ConnectError } from "@connectrpc/connect";
 import type { DescMethod, DescMessage, Message } from "@bufbuild/protobuf";
@@ -137,6 +145,49 @@ export interface AuthorizeTargetOverride {
   readonly resourceId: string;
 }
 
+/**
+ * One question for the Authorizer together with the lane's deny copy: the
+ * unit `authorizeResolvedResource` consumes, whether the annotation named
+ * it (`resolveAnnotatedCheck`) or a chain's own resolver did (the run gate,
+ * the resolved-target step).
+ */
+export interface AuthorizationTarget extends AuthzCheck {
+  readonly deniedMessage: string;
+}
+
+/**
+ * The annotation's answer for one method: the target it names for this
+ * request, or `undefined` when it names none — `is_public`,
+ * `is_skip_authorization`, or no config at all. Pure over the descriptor
+ * and the request; the `internal` exemption is the evaluation's, not the
+ * annotation's, so it is not applied here. Exported so a chain step can
+ * authorize a loaded row exactly as a SIBLING method's annotation would
+ * (a read by reference asks what its `get` asks) without a second copy of
+ * the skip arms or the field-path resolution.
+ */
+export function resolveAnnotatedCheck(
+  method: DescMethod,
+  input: Message,
+  override?: AuthorizeTargetOverride,
+): AuthorizationTarget | undefined {
+  if (
+    getOption(method, is_public) ||
+    getOption(method, is_skip_authorization)
+  ) {
+    return undefined;
+  }
+  if (!hasOption(method, rpcAuthorizationConfig)) {
+    return undefined;
+  }
+  const config = getOption(method, rpcAuthorizationConfig);
+  return {
+    permission: config.permission,
+    resourceKind: override?.resourceKind ?? resolveResourceKind(input, config),
+    resourceId: override?.resourceId ?? resolveResourceId(input, config),
+    deniedMessage: config.errorMsg,
+  };
+}
+
 /**
  * The Authorize evaluation for direct handlers: identical skip arms,
  * target resolution, and decision-to-wire mapping as the pipeline step
@@ -153,27 +204,33 @@ export async function authorizeDirect(
   if (identity.callerClass === "internal") {
     return;
   }
-  if (
-    getOption(method, is_public) ||
-    getOption(method, is_skip_authorization)
-  ) {
-    return;
-  }
-  if (!hasOption(method, rpcAuthorizationConfig)) {
+  const target = resolveAnnotatedCheck(method, input, override);
+  if (target === undefined) {
     return;
   }
-  const config = getOption(method, rpcAuthorizationConfig);
+  return authorizeTarget(authorizer, identity, target);
+}
 
+/**
+ * `authorizeResolvedResource` over an AuthorizationTarget: the check the
+ * Authorizer sees carries exactly the three fields of an AuthzCheck, never
+ * the copy, so a recording Authorizer (a test's, a driver's audit line)
+ * observes the question and nothing else.
+ */
+export function authorizeTarget(
+  authorizer: Authorizer,
+  identity: CallerIdentity,
+  target: AuthorizationTarget,
+): Promise<void> {
   return authorizeResolvedResource(
     authorizer,
     identity,
     {
-      permission: config.permission,
-      resourceKind:
-        override?.resourceKind ?? resolveResourceKind(input, config),
-      resourceId: override?.resourceId ?? resolveResourceId(input, config),
+      permission: target.permission,
+      resourceKind: target.resourceKind,
+      resourceId: target.resourceId,
     },
-    config.errorMsg,
+    target.deniedMessage,
   );
 }
 

package/src/pipeline/steps/guard-memory-capture.ts

@@ -37,6 +37,7 @@
 import type { DescMessage } from "@bufbuild/protobuf";
 import { Code, ConnectError } from "@connectrpc/connect";
 
+import { isServerComposedRequest } from "../../extensions/identity.js";
 import type { PipelineStep } from "../pipeline.js";
 import type { RequestContext } from "../request-context.js";
 import type { RunnerCredentialProvider } from "../../runnerauth/runner-credential-provider.js";
@@ -61,7 +62,7 @@ export function newGuardMemoryCaptureStep<Desc extends DescMessage>(
     name: "GuardMemoryCapture",
     async execute(ctx: RequestContext<Desc>): Promise<void> {
       const caller = ctx.callerIdentity;
-      if (caller.callerClass === "internal" || caller.origin === "in-process") {
+      if (isServerComposedRequest(caller)) {
         // Server-composed traversals are not capture requests from a
         // credential; the entry-point request already passed the gate.
         return;

package/src/pipeline/steps/guard-reserved-labels.ts

@@ -55,6 +55,7 @@ import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/
 import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 
 import type { Authorizer } from "../../extensions/authorizer.js";
+import { isServerComposedRequest } from "../../extensions/identity.js";
 import { internalError } from "../errors.js";
 import type { PipelineStep } from "../pipeline.js";
 import type { RequestContext } from "../request-context.js";
@@ -117,15 +118,11 @@ export function newGuardReservedLabelsStep<Desc extends DescMessage>(
   return {
     name: "GuardReservedLabels",
     async execute(ctx: RequestContext<Desc>): Promise<void> {
-      if (
-        ctx.callerIdentity.callerClass === "internal" ||
-        ctx.callerIdentity.origin === "in-process"
-      ) {
-        // Server-composed request (the Java isInProcessCall arm,
-        // cloud#386): the trust decision was made by the service code
-        // that built it — default-instance factories stamp reserved
-        // labels by design, even when the call propagates the user's
-        // identity for attribution (ruling R5).
+      if (isServerComposedRequest(ctx.callerIdentity)) {
+        // The Java isInProcessCall arm (cloud#386): the trust decision was
+        // made by the service code that built the request — default-instance
+        // factories stamp reserved labels by design, even when the call
+        // propagates the user's identity for attribution (ruling R5).
         return;
       }
       const state = stateOf(ctx);

package/src/pipeline/steps/helpers.ts

@@ -8,7 +8,6 @@ import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
 import type { Timestamp } from "@bufbuild/protobuf/wkt";
 
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
-import { AuthorizationScopeType } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/authorization_config_pb";
 
 import type { Store } from "../../store/interface.js";
 import { getKindMeta } from "../apiresource-meta.js";
@@ -85,11 +84,15 @@ export async function findResourceByLabelAndOrg<Desc extends DescMessage>(
 }
 
 /**
- * Rejects a getByReference lookup that omits org for an org-scoped kind —
- * Go RequireOrgForReference. For AUTHORIZATION_SCOPE_TYPE_ORGANIZATION
- * kinds a slug is unique only WITHIN an org; resolving an org-less
- * reference globally would cross tenant boundaries. The message matches
- * the cloud edition verbatim (cross-edition error contract).
+ * Rejects a getByReference lookup that omits org — Go RequireOrgForReference,
+ * widened to every kind that has a reference lane. A slug is unique only
+ * WITHIN an org, so an org-less reference resolves globally and the first
+ * match wins: for an org-scoped kind that crosses tenant boundaries, and
+ * for an owner-only kind (the execution context) it let a caller name a
+ * slug and receive whichever organization's row matched first. Every kind
+ * with a reference lane is served per organization, so the rule is the
+ * same for all of them. The message matches the cloud edition verbatim
+ * (cross-edition error contract); the kind name comes from kind_meta.
  *
  * Belongs at the getByReference boundary only — the low-level slug finders
  * are legitimately called with a relative (possibly empty) org by internal
@@ -102,23 +105,16 @@ export function requireOrgForReference(
   if (org !== "") {
     return;
   }
-  let scopeType: AuthorizationScopeType | undefined;
   let kindName: string;
   try {
-    const meta = getKindMeta(kind);
-    scopeType = meta.authorization?.scopeType;
-    kindName = meta.name;
+    kindName = getKindMeta(kind).name;
   } catch (error) {
     throw internalError(
       error,
       "failed to resolve kind metadata for reference org check",
     );
   }
-  // protobuf-es strips the shared enum prefix: proto
-  // AUTHORIZATION_SCOPE_TYPE_ORGANIZATION generates as ORGANIZATION.
-  if (scopeType === AuthorizationScopeType.ORGANIZATION) {
-    throw invalidArgumentError(`org is required for ${kindName} lookup`);
-  }
+  throw invalidArgumentError(`org is required for ${kindName} lookup`);
 }
 
 // The two list-step helpers below are duplicated per package in Go (each

package/src/pipeline/steps/version-history.ts

@@ -31,6 +31,7 @@ import type { DescMessage, Message, MessageShape } from "@bufbuild/protobuf";
 
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import type { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 
 import {
   internalError,
@@ -42,6 +43,7 @@ import type { RequestContext } from "../request-context.js";
 import { AuditNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { findResourceBySlug, requireOrgForReference } from "./helpers.js";
+import type { ResolvedTargetResolver } from "./authorize-resolved-target.js";
 import { TARGET_RESOURCE_KEY } from "./load-target.js";
 import { metadataOf } from "./shapes.js";
 
@@ -192,6 +194,38 @@ export const LIST_VERSIONS_RESOURCE_ID_KEY = "listVersionsResourceId";
 export const LIST_VERSIONS_HEAD_HASH_KEY = "listVersionsHeadHash";
 export const LIST_VERSIONS_RESPONSE_KEY = "listVersionsResponse";
 
+/**
+ * The ListVersions lanes' authorization question, for the
+ * AuthorizeResolvedTarget step placed after the slug resolver: `can_view`
+ * on the resolved head's id (the version history of a row is readable by
+ * whoever may read the row), with the lane's byte-pinned copy. The id key
+ * is the resolver's own — the shared resolver stashes under
+ * LIST_VERSIONS_RESOURCE_ID_KEY; a domain resolver with its own key names
+ * it. An id the chain did not stash is a broken invariant and throws.
+ */
+export function versionHistoryTarget<Desc extends DescMessage>(
+  kind: ApiResourceKind,
+  deniedMessage: string,
+  idKey: string = LIST_VERSIONS_RESOURCE_ID_KEY,
+): ResolvedTargetResolver<Desc> {
+  return (ctx) => {
+    const resourceId = ctx.get(idKey);
+    if (typeof resourceId !== "string" || resourceId === "") {
+      throw new Error(
+        `ListVersions: no resolved resource id under ${idKey}; the slug resolver must run first`,
+      );
+    }
+    return [
+      {
+        permission: IamPermission.can_view,
+        resourceKind: kind,
+        resourceId,
+        deniedMessage,
+      },
+    ];
+  };
+}
+
 /** The fields every ListVersions input carries; the binding reads them off its own message. */
 export interface ListVersionsInputShape {
   readonly org: string;