@stigmer/server 3.21.0 → 3.22.1-dev.20260922095755

package/src/pipeline/steps/authorization-tuples.ts

@@ -94,9 +94,15 @@ import { metadataOf, parentIdOf } from "./shapes.js";
  * validation).
  *
  * The org floor: kinds flagged defaults_to_org_visibility (blueprints —
- * shared org assets) keep the org-viewer shape at public and platform
- * levels, so sharing a blueprint beyond the org never hides it from its
- * own org's catalog (ListObjects suppresses the public wildcard).
+ * shared org assets) keep the org-viewer shape at the platform level, so
+ * sharing a blueprint beyond the org never hides it from its own org's
+ * catalog.
+ *
+ * The retired public level has no shape here. No stored row holds it once
+ * the store migration has run, so no transition FROM it reaches this
+ * policy; a deployment that still holds public rows must move them through
+ * updateVisibility on the release that knew the level, whose reconciler
+ * deletes the wildcard grant, before it runs this one.
  */
 export function visibilityShapesFor(
   kind: ApiResourceKind,
@@ -112,14 +118,6 @@ export function visibilityShapesFor(
         shapes.add("org-viewer");
       }
       break;
-    case ApiResourceVisibility.visibility_public:
-      if (config?.supportsPublic === true) {
-        shapes.add("public-viewer");
-        if (orgFloor) {
-          shapes.add("org-viewer");
-        }
-      }
-      break;
     case ApiResourceVisibility.visibility_platform:
       if (config?.supportsPlatform === true) {
         shapes.add("platform-viewer");

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