@stigmer/server 3.15.3-dev.20260916211208 → 3.16.0

package/src/domain/mcpserver/start-connect.ts

@@ -118,7 +118,7 @@ export async function startConnect(
     }
   }
 
-  const prepared = await prepareConnect(deps, mcpServer, input);
+  const prepared = await prepareConnect(deps, mcpServer, input, identity);
 
   // Taken before the start so the advisory describes the queue the run is
   // about to join. Warn-only by design: a worker may be booting (the

package/src/domain/platform/controller.ts

@@ -10,21 +10,34 @@
  * composed-server pattern).
  *
  * getRunnerScopedToken is the mint side of the runner-token lane
- * (oss#535) — the seam src/runnerauth/ reserved for this sub-project. OSS
- * has no caller identity, so unlike the cloud exchange there is no
- * credential to verify: any caller naming an execution receives a token
- * for it. On a single-user server the token is the LANE DISCRIMINATOR that
- * lets the EC read RPCs redact by default without breaking the runner, not
- * a trust boundary (DD-004).
+ * (oss#535) — the seam src/runnerauth/. What the token IS depends on the
+ * server's posture, and so does who may obtain one:
+ *
+ *   - Under trusted-local (the laptop: one caller, nothing to separate)
+ *     the arms below mint a clocked token for any caller naming an
+ *     execution. The token is the LANE DISCRIMINATOR that lets the
+ *     ExecutionContext read RPCs redact by default without breaking the
+ *     runner, not a trust boundary — there is no identity for it to
+ *     change.
+ *   - Under the built-in authorization posture the same token is an
+ *     IDENTITY: the runner-subject verifier admits its bearer as the
+ *     human whose run it is (runnerauth/runner-subject-verifier.ts). A
+ *     mint for anyone would be impersonation, so the built-in provider
+ *     defines exchangeScopedToken and this controller delegates to it:
+ *     the run credential is minted for the run's own person and nobody
+ *     else (runnerauth/built-in-runner-credential-provider.ts). Runs get
+ *     their credential from the dispatch itself (the engine clients put
+ *     it on the workflow input); this exchange is the runner's fallback.
  *
  * The C4 capability delegation (20260827.09, gate ruling Q1): when the
  * composed provider defines exchangeScopedToken / bootstrapCredentials,
  * this controller delegates the exchange arms and the bootstrap
- * credential fields to it wholesale — the cloud's per-arm caller-class
- * gating, row authorization, and multi-lane minting are POLICY, not
- * contract, and live behind the seam. With neither defined (the OSS
- * default), every arm below behaves exactly as before; the conformance
- * suites pin that byte-identity.
+ * credential fields to it wholesale — per-arm caller gating, row
+ * authorization, and multi-lane minting are POLICY, not contract, and
+ * live behind the seam (the cloud's four-arm exchange; open source's
+ * built-in gate). With neither defined (the trusted-local default), every
+ * arm below behaves exactly as before; the conformance suites pin that
+ * byte-identity.
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";

package/src/domain/plugin/__tests__/plugin.test.ts

@@ -10,7 +10,9 @@
  * upgrade drops what the archive dropped; uninstall removes every member
  * and is refused while a user's own agent still references one; a slug an
  * unmanaged resource holds refuses the install; a bad overlay refuses
- * before any write.
+ * before any write. A second composition, under an authorizer that denies
+ * `can_write_reserved_labels`, pins the reserved-label refusal the
+ * open-source posture allows by design.
  */
 import { mkdtempSync, rmSync } from "node:fs";
 import net from "node:net";
@@ -46,11 +48,13 @@ import { SkillQueryController } from "@stigmer/protos/ai/stigmer/agentic/skill/v
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 
 import { writeArchive } from "../../../archive/write.js";
 import { loadConfig } from "../../../boot/config.js";
 import { composeServer } from "../../../boot/compose.js";
 import type { ComposedServer } from "../../../boot/compose.js";
+import type { Authorizer, AuthzCheck } from "../../../extensions/authorizer.js";
 import { createLogger } from "../../../boot/logger.js";
 import {
   PLUGIN_LABEL,
@@ -679,3 +683,114 @@ describe("Plugin push — refusals before any write", () => {
     expect(agent.metadata?.labels[PLUGIN_LABEL]).toBe(installed.metadata?.id);
   });
 });
+
+/**
+ * The reserved-label refusal where an authorizer enforces. The open-source
+ * built-in authorizer allows `can_write_reserved_labels` by design, so the
+ * default composition above cannot show the refusal; this composition
+ * registers an authorizer that denies exactly that permission and allows
+ * everything else, the posture a hosted edition takes. An archive whose
+ * overlay carries a `stigmer.ai/*` label is refused before a byte is
+ * written, and a plain overlay under the same authorizer still installs —
+ * so the sanitiser asks the platform capability and nothing broader.
+ */
+describe("Plugin push under an authorizer that enforces reserved labels", () => {
+  let enforcingDir: string;
+  let enforcing: ComposedServer;
+  let enforcingPlugins: Client<typeof PluginCommandController>;
+  let enforcingQuery: Client<typeof PluginQueryController>;
+  const observed: AuthzCheck[] = [];
+
+  beforeAll(async () => {
+    enforcingDir = mkdtempSync(path.join(tmpdir(), "plugin-domain-enforcing-"));
+    const grpcPort = await reserveFreePort();
+    const authorizer: Authorizer = {
+      authorize(_caller, check) {
+        if (check.permission === IamPermission.can_write_reserved_labels) {
+          observed.push(check);
+          return Promise.resolve({
+            kind: "deny",
+            reason: "reserved labels are the platform's",
+          });
+        }
+        return Promise.resolve({ kind: "allow" });
+      },
+    };
+    enforcing = await composeServer({
+      config: loadConfig({
+        STIGMER_MODEL_REGISTRY_REFRESH: "off",
+        TEMPORAL_HOST_PORT: "127.0.0.1:1",
+        GRPC_PORT: String(grpcPort),
+        DB_PATH: path.join(enforcingDir, "stigmer.db"),
+        ARTIFACT_LOCAL_BASE_PATH: path.join(enforcingDir, "artifacts"),
+        STORAGE_PATH: path.join(enforcingDir, "storage"),
+      }),
+      logger: silentLogger,
+      host: "127.0.0.1",
+      extensions: [{ name: "reserved-labels-enforced", authorizer }],
+    });
+    const port = await enforcing.start();
+    const transport: Transport = createGrpcTransport({
+      baseUrl: `http://127.0.0.1:${port}`,
+    });
+    enforcingPlugins = createClient(PluginCommandController, transport);
+    enforcingQuery = createClient(PluginQueryController, transport);
+  });
+
+  afterAll(async () => {
+    await enforcing.shutdown();
+    rmSync(enforcingDir, { recursive: true, force: true });
+  });
+
+  it("refuses an archive whose overlay carries a reserved label, naming the document and the key, and writes nothing", async () => {
+    const name = uniqueName("plg-forged");
+    const forged = withFile(
+      thermosLike(name),
+      "ai.stigmer/agent.yaml",
+      [
+        "apiVersion: agentic.stigmer.ai/v1",
+        "kind: Agent",
+        "metadata:",
+        `  name: ${name}`,
+        "  labels:",
+        "    stigmer.ai/plugin: plg_somebody_else",
+        "spec:",
+        "  instructions: Long enough instructions for the forged agent.",
+        "",
+      ].join("\n"),
+    );
+    const error = await expectCode(
+      enforcingPlugins.push({ org: ORG, artifact: archiveOf(forged) }),
+      Code.InvalidArgument,
+    );
+    expect(error.rawMessage).toContain(
+      "cannot be set by a plugin (ai.stigmer/agent.yaml: stigmer.ai/plugin)",
+    );
+    expect(observed.map((c) => c.permission)).toEqual([
+      IamPermission.can_write_reserved_labels,
+    ]);
+    await expectCode(
+      enforcingQuery.getByReference(
+        createMessage(ApiResourceReferenceSchema, {
+          org: ORG,
+          kind: ApiResourceKind.plugin,
+          slug: name,
+        }),
+      ),
+      Code.NotFound,
+    );
+  });
+
+  it("installs a plain overlay under the same authorizer: the platform stamps its own labels through the in-process origin", async () => {
+    const name = uniqueName("plg-honest");
+    const installed = await enforcingPlugins.push({
+      org: ORG,
+      artifact: archiveOf(thermosLike(name)),
+    });
+    expect(installed.status?.state).toBe(PluginState.READY);
+    const { members } = await enforcingQuery.listMembers({
+      value: installed.metadata!.id,
+    });
+    expect(members).toHaveLength(3);
+  });
+});

package/src/domain/plugin/__tests__/sanitize.test.ts

@@ -1,7 +1,7 @@
 /**
  * Pins the sanitiser, the one place plugin-provided metadata is judged
  * before it rides the in-process lane: a `stigmer.ai/*` label in an
- * overlay is refused PERMISSION_DENIED naming the document and the keys
+ * overlay is refused INVALID_ARGUMENT naming the document and the keys
  * under a denying authorizer and passes under an allowing one (the
  * open-source posture), the operator check is consulted lazily and only
  * for the platform capability, a preset id and a name that describes
@@ -86,7 +86,7 @@ describe("sanitizeOverlays", () => {
         USER,
       ),
     );
-    expect(error.code).toBe(Code.PermissionDenied);
+    expect(error.code).toBe(Code.InvalidArgument);
     expect(error.rawMessage).toContain(
       "ai.stigmer/agent.yaml: stigmer.ai/default-agent",
     );

package/src/domain/plugin/overlay/sanitize.ts

@@ -13,7 +13,9 @@
  *     `platform:stigmer`, the same check GuardReservedLabels runs and the
  *     same lazy consultation of the one composed Authorizer (the
  *     open-source permissive default allows; an enforcing authorizer
- *     denies with PERMISSION_DENIED naming the keys);
+ *     denies with INVALID_ARGUMENT naming the keys, the code the
+ *     reserved-label guard answers a client mutation with, so one refusal
+ *     class carries one code wherever it is met);
  *   - `metadata.id` is the server's to mint, never an author's;
  *   - the agent overlay's name is the plugin's, a server overlay's name is
  *     its `mcpServers` key, a workflow overlay's name is its file stem: an
@@ -130,7 +132,7 @@ export async function sanitizeOverlays(
       throw new ConnectError(
         `Labels in the reserved '${RESERVED_LABEL_PREFIX}' namespace are platform-managed and ` +
           `cannot be set by a plugin (${listed}). Remove them from the plugin's ai.stigmer/ documents.`,
-        Code.PermissionDenied,
+        Code.InvalidArgument,
       );
     }
     case "unavailable":

package/src/domain/workflowexecution/__tests__/phases.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Pins `isTerminalWorkflowExecutionPhase` (phases.ts) over every member
+ * of the workflow ExecutionPhase enum, so the set is stated by
+ * enumeration and a new phase added to the contract lands in exactly one
+ * arm here. The contrast with subscribe.ts's `isWorkflowTerminalPhase`
+ * (TERMINATED omitted on purpose) is pinned so the two are never merged.
+ */
+import { describe, expect, it } from "vitest";
+
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+
+import { isTerminalWorkflowExecutionPhase } from "../phases.js";
+import { isWorkflowTerminalPhase } from "../subscribe.js";
+
+const TERMINAL = [
+  ExecutionPhase.EXECUTION_COMPLETED,
+  ExecutionPhase.EXECUTION_FAILED,
+  ExecutionPhase.EXECUTION_CANCELLED,
+  ExecutionPhase.EXECUTION_TERMINATED,
+];
+
+describe("isTerminalWorkflowExecutionPhase", () => {
+  it.each(TERMINAL.map((phase) => [ExecutionPhase[phase], phase] as const))(
+    "%s will never run again",
+    (_name, phase) => {
+      expect(isTerminalWorkflowExecutionPhase(phase)).toBe(true);
+    },
+  );
+
+  it.each([
+    ["UNSPECIFIED", ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED],
+    ["PENDING", ExecutionPhase.EXECUTION_PENDING],
+    ["IN_PROGRESS", ExecutionPhase.EXECUTION_IN_PROGRESS],
+    ["PAUSED", ExecutionPhase.EXECUTION_PAUSED],
+  ])("%s may still run", (_name, phase) => {
+    expect(isTerminalWorkflowExecutionPhase(phase)).toBe(false);
+  });
+
+  it("covers every member of the enum — a new phase must be classified here", () => {
+    const members = Object.values(ExecutionPhase).filter(
+      (value): value is ExecutionPhase => typeof value === "number",
+    );
+    const classified = members.filter((phase) =>
+      isTerminalWorkflowExecutionPhase(phase),
+    );
+    expect(classified.sort()).toEqual([...TERMINAL].sort());
+    expect(members).toHaveLength(8);
+  });
+
+  it("differs from the subscribe stream's close set on TERMINATED alone — deliberate, not to be merged", () => {
+    expect(isWorkflowTerminalPhase(ExecutionPhase.EXECUTION_TERMINATED)).toBe(
+      false,
+    );
+    expect(
+      isTerminalWorkflowExecutionPhase(ExecutionPhase.EXECUTION_TERMINATED),
+    ).toBe(true);
+  });
+});

package/src/domain/workflowexecution/phases.ts

@@ -0,0 +1,33 @@
+/**
+ * The workflow execution's "will this run ever run again?" predicate —
+ * the twin of domain/agentexecution/phases.ts `isTerminalExecutionPhase`,
+ * stated once so every consumer names the same set: COMPLETED, FAILED,
+ * CANCELLED and TERMINATED. PAUSED is NOT terminal (lifecycle.ts:
+ * `applyLifecyclePhaseTransition` keeps `completed_at` as-is on a pause
+ * and clears it on the way back to IN_PROGRESS), and neither is PENDING.
+ *
+ * Deliberately distinct from `isWorkflowTerminalPhase` in subscribe.ts,
+ * which OMITS TERMINATED — the disclosed Go quirk the subscribe stream
+ * ports faithfully as its close set. Do not merge the two; that file's
+ * header carries the reason.
+ *
+ * The first consumer is the runner-credential lane (runnerauth/
+ * bound-execution.ts): a run credential is valid while its run may still
+ * run, so a terminated workflow's credential must die exactly as a
+ * completed one's does.
+ */
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+
+export function isTerminalWorkflowExecutionPhase(
+  phase: ExecutionPhase,
+): boolean {
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_COMPLETED:
+    case ExecutionPhase.EXECUTION_FAILED:
+    case ExecutionPhase.EXECUTION_CANCELLED:
+    case ExecutionPhase.EXECUTION_TERMINATED:
+      return true;
+    default:
+      return false;
+  }
+}

package/src/extensions/__tests__/extension-composition.test.ts

@@ -544,7 +544,13 @@ describe("extension composition (require-authentication posture)", () => {
     };
     expect(parsed.posture).toBe("required");
     expect(parsed.source).toBe("extension 'fake-identity'");
-    expect(parsed.verifiers).toBe("apikey, fake-verifier");
+    // A unit that declares the posture and brings verifiers but NO
+    // Authorizer is the BUILT-IN authorization posture: open source
+    // composes its Authorizer, and with it the runner-subject verifier
+    // between the API-key lane and the unit's own (runnerauth/
+    // runner-subject-verifier.ts). A unit with its own Authorizer gets
+    // neither (runner-subject-composed.test.ts pins that chain).
+    expect(parsed.verifiers).toBe("apikey, runner, fake-verifier");
   });
 
   it("a declared posture whose unit registers no verifier of its own is a boot throw naming the unit — the API-key lane alone cannot bootstrap", async () => {

package/src/identity/__tests__/oidc-verifier.test.ts

@@ -218,6 +218,28 @@ describe("the byte-pinned classifyAuthError arms", () => {
     expect(ConnectError.from(error).code).toBe(Code.Unauthenticated);
     expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
   });
+
+  it("a JWT whose algorithm the JWKS cannot serve (HS256 against RS256 keys) → 'invalid token', a CREDENTIAL rejection, never a plain error the chassis maps INTERNAL", async () => {
+    // The shape the server's own execution-scoped runner token has
+    // (runnerauth.ts). Whether this verifier should ever SEE it is the
+    // chain order's business (the runner verifier claims it first); that
+    // it must not answer INTERNAL when it does is this arm's. Until
+    // 2026-09-16 it threw jose's JOSENotSupported unclassified, and a
+    // self-host with sign-in on failed every agent execution with
+    // "internal server error" (stigmer#1137).
+    const segment = (value: unknown): string =>
+      Buffer.from(JSON.stringify(value)).toString("base64url");
+    const hs256 = `${segment({ alg: "HS256", typ: "JWT" })}.${segment({
+      token_type: "execution_scoped",
+      execution_id: "aex_1",
+      iat: 1,
+      exp: 4102444800,
+    })}.${segment("a-mac-this-verifier-cannot-check")}`;
+    const error = await rejectionOf(verifier().verify(hs256));
+    expect(error).toBeInstanceOf(ConnectError);
+    expect(ConnectError.from(error).code).toBe(Code.Unauthenticated);
+    expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
+  });
 });
 
 describe("subject → account resolution (20260911.11 Q-IA-2, A1)", () => {

package/src/identity/oidc-verifier.ts

@@ -159,7 +159,14 @@ function classifyJoseError(error: unknown): unknown {
   }
   if (
     error instanceof joseErrors.JWTInvalid ||
-    error instanceof joseErrors.JWSInvalid
+    error instanceof joseErrors.JWSInvalid ||
+    // A JWT whose algorithm the issuer's key set cannot serve (an HS256
+    // token against an RS256 JWKS): a credential this verifier recognizes
+    // but cannot verify, so a credential rejection — never the
+    // infrastructure arm. Until 2026-09-16 it fell through to INTERNAL,
+    // and a self-host with sign-in on failed every agent execution on its
+    // own runner token (stigmer#1137).
+    error instanceof joseErrors.JOSENotSupported
   ) {
     return new ConnectError(INVALID_TOKEN_MESSAGE, Code.Unauthenticated);
   }

package/src/pipeline/__tests__/kind-by-id-prefix.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Pins `kindByIdPrefix` (pipeline/apiresource-meta.ts), the inverse of
+ * `getIdPrefix` over the ids the server mints (`<prefix>_<ulid>`,
+ * pipeline/steps/defaults.ts). The runner-credential lane reads it to
+ * learn which execution kind a token's binding names — an agent
+ * execution (`aex_`) or a workflow execution (`wex_`) — without a second
+ * claim on the token or a guess.
+ *
+ * Two properties are load-bearing:
+ *
+ *   - NEVER a throw. The id arrives inside a credential; the caller
+ *     refuses with its own sentence, so anything that is not a known
+ *     prefix followed by an underscore is the unknown kind.
+ *   - Every `id_prefix` in the contract is UNIQUE. The lookup is a Map
+ *     over the `kind_meta` table; a duplicate prefix would silently win
+ *     for one kind and lose for the other. The pin below turns a future
+ *     duplicate into a reviewed change.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  ApiResourceKind,
+  ApiResourceKindSchema,
+  kind_meta,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { getOption, hasOption } from "@bufbuild/protobuf";
+
+import { getIdPrefix, kindByIdPrefix } from "../apiresource-meta.js";
+
+describe("kindByIdPrefix — a minted id names its kind by prefix", () => {
+  it.each([
+    ["aex_01m2mp45efcjvq2z1e1yn4cyz7", ApiResourceKind.agent_execution],
+    ["wex_01m2mp45efcjvq2z1e1yn4cyz7", ApiResourceKind.workflow_execution],
+    ["ses_x", ApiResourceKind.session],
+    ["ida_carol", ApiResourceKind.identity_account],
+  ])("%s is %s", (id, kind) => {
+    expect(kindByIdPrefix(id)).toBe(kind);
+  });
+
+  it.each([
+    ["zzz_unknown_kind", "an unknown prefix"],
+    ["aex", "a prefix with no underscore"],
+    ["_aex", "a leading underscore names no prefix"],
+    ["", "empty"],
+    ["AEX_upper", "prefixes are lowercase in the contract"],
+    ["stk_notajwt", "an API key's prefix is not a kind"],
+  ])("%s is the unknown kind (%s) — never a throw", (id) => {
+    expect(kindByIdPrefix(id)).toBe(ApiResourceKind.api_resource_kind_unknown);
+  });
+
+  it("round-trips with getIdPrefix over every kind the contract declares", () => {
+    for (const value of ApiResourceKindSchema.values) {
+      if (!hasOption(value, kind_meta)) continue;
+      const kind = value.number as ApiResourceKind;
+      expect(kindByIdPrefix(`${getIdPrefix(kind)}_01anyulid`), value.name).toBe(
+        kind,
+      );
+    }
+  });
+
+  it("every id_prefix in the contract is unique — the table pin a duplicate must change", () => {
+    const seen = new Map<string, string>();
+    for (const value of ApiResourceKindSchema.values) {
+      if (!hasOption(value, kind_meta)) continue;
+      const prefix = getOption(value, kind_meta).idPrefix;
+      expect(prefix, `${value.name} declares no id_prefix`).not.toBe("");
+      const holder = seen.get(prefix);
+      expect(
+        holder,
+        `id_prefix '${prefix}' is declared by both ${holder} and ${value.name}`,
+      ).toBeUndefined();
+      seen.set(prefix, value.name);
+    }
+  });
+});

package/src/pipeline/apiresource-meta.ts

@@ -351,3 +351,44 @@ function kindsByEnumName(): Map<string, ApiResourceKind> {
   }
   return enumNameCache;
 }
+
+/**
+ * The kind a minted resource id belongs to, read off its prefix — the
+ * inverse of `getIdPrefix` over the ids `generateId` mints
+ * (`<prefix>_<ulid>`, pipeline/steps/defaults.ts). The one consumer today
+ * is the runner-credential lane, whose token binds an execution by id and
+ * must know whether that id names an agent execution or a workflow
+ * execution without a second claim or a guess. Anything that is not
+ * `<known prefix>_<rest>` — no underscore, an unknown prefix, the empty
+ * string — is `api_resource_kind_unknown`; never a throw, because the id
+ * arrived inside a credential and the caller refuses with its own
+ * sentence. Every `id_prefix` in the contract is unique; the table pin in
+ * __tests__ makes a future duplicate a reviewed change, since this lookup
+ * would otherwise resolve it silently to one of the two.
+ */
+export function kindByIdPrefix(id: string): ApiResourceKind {
+  const separator = id.indexOf("_");
+  if (separator <= 0) {
+    return ApiResourceKind.api_resource_kind_unknown;
+  }
+  return (
+    kindsByIdPrefix().get(id.slice(0, separator)) ??
+    ApiResourceKind.api_resource_kind_unknown
+  );
+}
+
+let idPrefixCache: Map<string, ApiResourceKind> | undefined;
+
+function kindsByIdPrefix(): Map<string, ApiResourceKind> {
+  if (idPrefixCache === undefined) {
+    idPrefixCache = new Map(
+      ApiResourceKindSchema.values
+        .filter((value) => hasOption(value, kind_meta))
+        .map((value) => [
+          getOption(value, kind_meta).idPrefix,
+          value.number as ApiResourceKind,
+        ]),
+    );
+  }
+  return idPrefixCache;
+}