@stigmer/server 3.18.0 → 3.19.0

package/src/boot/oauth-redirect-uri.ts

@@ -0,0 +1,53 @@
+/**
+ * Where an MCP server's OAuth Sign in comes back to, on a server that was
+ * not told.
+ *
+ * `STIGMER_OAUTH_REDIRECT_URI` is the callback URL the McpServer OAuth
+ * Connect flows hand the vendor's login server; the cloud sets it to its
+ * console's callback page. A local install (`stigmer up`, the desktop app,
+ * the all-in-one image) never set it, and `initiateOAuthConnect` refuses
+ * without it, so every Sign in surface the console offers was dead on a
+ * local install. The posture that already decides how a served console
+ * signs its users in (`trusted-local` when no issuer is configured) answers
+ * this too: a server that serves the console on its unified port is
+ * reached by a browser on the machine it runs on, so its callback is the
+ * console's callback page at `http://localhost:<port>`, the same host the
+ * config already assumes for `SKILL_TRANSFER_BASE_URL`.
+ *
+ * The rules, in order: a configured value always wins; a server that
+ * serves no console derives nothing (the CLI and the SDKs need no
+ * callback, and today's warn and refusal stand); a server whose port is
+ * not yet known (an ephemeral `0`, the test harness's shape) derives
+ * nothing either. The console's callback route is the web app's
+ * `app/auth/oauth/callback/page.tsx`; its path is a constant here because
+ * this is the one place the server names it.
+ *
+ * Proven by __tests__/oauth-redirect-uri.test.ts.
+ */
+
+/** The console's OAuth callback page, relative to the served console's origin. */
+export const CONSOLE_OAUTH_CALLBACK_PATH = "/auth/oauth/callback";
+
+export type OAuthRedirectUriResolution =
+  /** The operator's value, as configured. */
+  | { readonly kind: "configured"; readonly uri: string }
+  /** Derived from the served console's own origin. */
+  | { readonly kind: "derived"; readonly uri: string }
+  /** Nothing to hand the login server; initiate refuses with the pinned copy. */
+  | { readonly kind: "absent" };
+
+export interface OAuthRedirectUriInputs {
+  /** `STIGMER_OAUTH_REDIRECT_URI` as loaded; empty when unset. */
+  readonly configured: string;
+  /** Whether this server serves the web console on its unified port. */
+  readonly servesConsole: boolean;
+  /** The port the unified listener binds; 0 means "not known until listen". */
+  readonly port: number;
+}
+
+/** The callback URL the McpServer OAuth flows use, and where it came from. */
+export function resolveOAuthRedirectUri(inputs: OAuthRedirectUriInputs): OAuthRedirectUriResolution {
+  if (inputs.configured !== "") return { kind: "configured", uri: inputs.configured };
+  if (!inputs.servesConsole || inputs.port === 0) return { kind: "absent" };
+  return { kind: "derived", uri: `http://localhost:${inputs.port}${CONSOLE_OAUTH_CALLBACK_PATH}` };
+}

package/src/domain/agentexecution/lifecycle.ts

@@ -720,7 +720,7 @@ export async function recoverExecution(
               temporalConfig: deps.temporalConfig,
             },
             loadedExecution(ctx),
-            ctx.callerIdentity.identityId,
+            ctx.callerIdentity,
           );
         },
       },

package/src/domain/mcpserver/__tests__/complete-endpoint-auth.test.ts

@@ -0,0 +1,270 @@
+/**
+ * Pins CompleteEndpointAuth over a fake fetch: the author's shape and
+ * nothing else is probed; an OAuth challenge completes exactly the trio
+ * plus the provenance label and the completed spec passes the proto
+ * validator; every other outcome and a throwing fetch leave the spec as
+ * sent; carry-over reuses an earlier completion with no network; the
+ * console's exact echo keeps the label; the author's own auth drops it; a
+ * changed URL probes again; the Bearer default serves a hand-written auth;
+ * the label is recorded as stamped so GuardReservedLabels admits it.
+ */
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+
+import type { OutboundFetch } from "@stigmer/outbound/egress";
+import { EnvVarDeclarationSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerAuthSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { MCP_AUTH_ENDPOINT, MCP_AUTH_LABEL } from "../../../pipeline/apiresource-labels.js";
+import { RequestContext } from "../../../pipeline/request-context.js";
+import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import { EXISTING_RESOURCE_KEY } from "../../../pipeline/steps/load-existing.js";
+import { serverStampedReservedLabels } from "../../../pipeline/steps/server-stamped-reserved-labels.js";
+import { validator } from "../../../pipeline/steps/validation.js";
+import { accessTokenVariable, newCompleteEndpointAuthStep } from "../complete-endpoint-auth.js";
+
+const silentLogger = createLogger({ level: "error", pretty: false, write: () => {} });
+
+const URL_ONLY = "https://mcp.vendor.test/mcp";
+const CHALLENGE = 'Bearer realm="OAuth", resource_metadata="https://mcp.vendor.test/.well-known/oauth-protected-resource/mcp"';
+const VARIABLE = "LINEAR_ACCESS_TOKEN";
+
+interface FakeFetch {
+  readonly fetchImpl: OutboundFetch;
+  readonly calls: { url: string; init: RequestInit | undefined }[];
+}
+
+function answering(status: number, headers: Record<string, string> = {}): FakeFetch {
+  const calls: FakeFetch["calls"] = [];
+  return {
+    calls,
+    fetchImpl: async (url, init) => {
+      calls.push({ url: String(url), init });
+      return new Response(null, { status, headers });
+    },
+  };
+}
+
+function throwing(): FakeFetch {
+  const calls: FakeFetch["calls"] = [];
+  return {
+    calls,
+    fetchImpl: async (url, init) => {
+      calls.push({ url: String(url), init });
+      throw new Error("connect ECONNREFUSED");
+    },
+  };
+}
+
+function server(overrides: { url?: string; headers?: Record<string, string>; env?: Record<string, { isSecret: boolean; optional?: boolean; description?: string }>; auth?: { targetEnvVar?: string; oauthOnly?: boolean; discoveryUrl?: string }; labels?: Record<string, string>; stdio?: boolean } = {}): McpServer {
+  return create(McpServerSchema, {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "McpServer",
+    metadata: { id: "mcps_1", name: "Linear", slug: "linear", org: "acme", labels: overrides.labels ?? {} },
+    spec: {
+      description: "Linear's hosted MCP server",
+      serverType: overrides.stdio === true ? { case: "stdio", value: { command: "npx" } } : { case: "http", value: { url: overrides.url ?? URL_ONLY, headers: overrides.headers ?? {} } },
+      env: Object.fromEntries(Object.entries(overrides.env ?? {}).map(([k, v]) => [k, create(EnvVarDeclarationSchema, { isSecret: v.isSecret, optional: v.optional ?? false, description: v.description ?? "" })])),
+      ...(overrides.auth !== undefined ? { auth: create(McpServerAuthSchema, overrides.auth) } : {}),
+    },
+  });
+}
+
+/** A row as an earlier save completed it: the trio and the label. */
+function completedRow(url = URL_ONLY): McpServer {
+  return server({
+    url,
+    headers: { Authorization: `Bearer \${${VARIABLE}}` },
+    env: { [VARIABLE]: { isSecret: true, description: "OAuth access token for the 'linear' MCP server; Sign in fills it" } },
+    auth: { targetEnvVar: VARIABLE, oauthOnly: true },
+    labels: { [MCP_AUTH_LABEL]: MCP_AUTH_ENDPOINT },
+  });
+}
+
+async function run(incoming: McpServer, fake: FakeFetch, existing?: McpServer): Promise<RequestContext<typeof McpServerSchema>> {
+  const ctx = new RequestContext(McpServerSchema, incoming, testCallerIdentity(), ApiResourceKind.mcp_server);
+  if (existing !== undefined) ctx.set(EXISTING_RESOURCE_KEY, existing);
+  await newCompleteEndpointAuthStep({ outboundFetch: fake.fetchImpl, logger: silentLogger }).execute(ctx);
+  return ctx;
+}
+
+function expectCompleted(state: McpServer): void {
+  expect(state.spec?.auth?.targetEnvVar).toBe(VARIABLE);
+  expect(state.spec?.auth?.oauthOnly).toBe(true);
+  expect(state.spec?.auth?.discoveryUrl).toBe("");
+  expect(state.spec?.auth?.scopeHints).toEqual([]);
+  expect(state.spec?.env[VARIABLE]).toMatchObject({ isSecret: true, optional: false });
+  expect(state.spec?.env[VARIABLE]?.description).toContain("Sign in fills it");
+  expect(state.spec?.serverType.case === "http" ? state.spec.serverType.value.headers : {}).toEqual({ Authorization: `Bearer \${${VARIABLE}}` });
+  expect(state.metadata?.labels[MCP_AUTH_LABEL]).toBe(MCP_AUTH_ENDPOINT);
+}
+
+function expectUntouched(state: McpServer, incoming: McpServer): void {
+  expect(state.spec).toEqual(incoming.spec);
+  expect(state.metadata?.labels[MCP_AUTH_LABEL]).toBeUndefined();
+}
+
+describe("CompleteEndpointAuth: the author's shape is probed with one complete initialize", () => {
+  it("completes exactly the trio plus the label on an OAuth challenge, and the completed spec validates", async () => {
+    const fake = answering(401, { "www-authenticate": CHALLENGE });
+    const ctx = await run(server(), fake);
+    expectCompleted(ctx.newState);
+    expect(fake.calls).toHaveLength(1);
+    expect(fake.calls[0]?.url).toBe(URL_ONLY);
+    const body = JSON.parse(String(fake.calls[0]?.init?.body)) as { method: string; params: { protocolVersion: string; clientInfo: { name: string } } };
+    expect(body.method).toBe("initialize");
+    expect(body.params.protocolVersion).toBe("2025-06-18");
+    expect(body.params.clientInfo.name).toBe("stigmer-server");
+    expect(serverStampedReservedLabels(ctx).has(MCP_AUTH_LABEL)).toBe(true);
+    expect(validator().validate(McpServerSchema, ctx.newState).kind).toBe("valid");
+  });
+
+  it("sends the author's literal headers with the probe", async () => {
+    const fake = answering(200);
+    await run(server({ headers: { "X-Vendor-Region": "eu" } }), fake);
+    expect((fake.calls[0]?.init?.headers as Record<string, string>)["X-Vendor-Region"]).toBe("eu");
+  });
+
+  it.each([
+    ["a 2xx (an open endpoint)", answering(200)],
+    ["a non-OAuth 401 (a static-token API)", answering(401, { "www-authenticate": 'Bearer error="invalid_token"' })],
+    ["a 401 without a challenge header", answering(401)],
+    ["any other status", answering(405)],
+    ["no answer at all", throwing()],
+  ])("leaves the spec as sent on %s", async (_label, fake) => {
+    const incoming = server();
+    const ctx = await run(incoming, fake);
+    expectUntouched(ctx.newState, incoming);
+    expect(serverStampedReservedLabels(ctx).has(MCP_AUTH_LABEL)).toBe(false);
+  });
+
+  it("never fails the save when the fetch it was handed throws synchronously", async () => {
+    const fetchImpl = (() => {
+      throw new Error("defective fetch");
+    }) as unknown as OutboundFetch;
+    const incoming = server();
+    const ctx = await run(incoming, { fetchImpl, calls: [] });
+    expectUntouched(ctx.newState, incoming);
+  });
+});
+
+describe("CompleteEndpointAuth: anything the author says about auth is left alone, unprobed", () => {
+  it.each([
+    ["a declared env variable", server({ headers: { Authorization: "Bearer ${TOKEN}" }, env: { TOKEN: { isSecret: true } } })],
+    ["a placeholder header without an env declaration", server({ headers: { "X-Api-Key": "${KEY}" } })],
+    ["a literal Authorization header, in any case", server({ headers: { authorization: "Bearer pasted-token" } })],
+    ["an auth block of the author's own", server({ auth: { targetEnvVar: "MY_TOKEN" }, env: { MY_TOKEN: { isSecret: true } } })],
+    ["a stdio server", server({ stdio: true })],
+  ])("does not probe %s", async (_label, incoming) => {
+    const fake = answering(401, { "www-authenticate": CHALLENGE });
+    const ctx = await run(incoming, fake);
+    expect(fake.calls).toHaveLength(0);
+    expect(ctx.newState.metadata?.labels[MCP_AUTH_LABEL]).toBeUndefined();
+  });
+
+  it("completes the token path for a hand-written auth: the header when no header sends the token, the declaration when none exists", async () => {
+    const fake = answering(401, { "www-authenticate": CHALLENGE });
+    const bare = await run(server({ auth: { targetEnvVar: "MY_TOKEN" }, env: { MY_TOKEN: { isSecret: true } } }), fake);
+    expect(bare.newState.spec?.serverType.case === "http" ? bare.newState.spec.serverType.value.headers : {}).toEqual({ Authorization: "Bearer ${MY_TOKEN}" });
+    const custom = await run(server({ auth: { targetEnvVar: "MY_TOKEN" }, env: { MY_TOKEN: { isSecret: true } }, headers: { "X-Token": "${MY_TOKEN}" } }), fake);
+    expect(custom.newState.spec?.serverType.case === "http" ? custom.newState.spec.serverType.value.headers : {}).toEqual({ "X-Token": "${MY_TOKEN}" });
+    // An auth whose variable was never declared could never receive its
+    // token (connect and execution inject only declared variables).
+    const undeclared = await run(server({ auth: { targetEnvVar: "MY_TOKEN" } }), fake);
+    expect(undeclared.newState.spec?.env["MY_TOKEN"]).toMatchObject({ isSecret: true, optional: false });
+    expect(undeclared.newState.spec?.env["MY_TOKEN"]?.description).toContain("Sign in fills it");
+    // A declaration the author wrote is left as written.
+    const declared = await run(server({ auth: { targetEnvVar: "MY_TOKEN" }, env: { MY_TOKEN: { isSecret: false, optional: true, description: "mine" } } }), fake);
+    expect(declared.newState.spec?.env["MY_TOKEN"]).toMatchObject({ isSecret: false, optional: true, description: "mine" });
+    expect(fake.calls).toHaveLength(0);
+  });
+
+  it("declares the variable for a stdio server's hand-written auth and adds no header", async () => {
+    const fake = answering(401, { "www-authenticate": CHALLENGE });
+    const ctx = await run(server({ stdio: true, auth: { targetEnvVar: "MY_TOKEN" } }), fake);
+    expect(ctx.newState.spec?.env["MY_TOKEN"]).toMatchObject({ isSecret: true });
+    expect(ctx.newState.spec?.serverType.case).toBe("stdio");
+    expect(fake.calls).toHaveLength(0);
+  });
+});
+
+describe("CompleteEndpointAuth: carry-over on update, three questions in order", () => {
+  it("reuses an earlier completion for the author's shape at the same URL, with no network", async () => {
+    const fake = answering(401, { "www-authenticate": CHALLENGE });
+    const ctx = await run(server(), fake, completedRow());
+    expectCompleted(ctx.newState);
+    expect(fake.calls).toHaveLength(0);
+    expect(serverStampedReservedLabels(ctx).has(MCP_AUTH_LABEL)).toBe(true);
+  });
+
+  it("keeps the label on an exact echo of the derived trio (the console's per-field save), with no network", async () => {
+    const fake = answering(401, { "www-authenticate": CHALLENGE });
+    const echo = completedRow();
+    echo.spec!.description = "edited in the console";
+    const ctx = await run(echo, fake, completedRow());
+    expect(ctx.newState.metadata?.labels[MCP_AUTH_LABEL]).toBe(MCP_AUTH_ENDPOINT);
+    expect(ctx.newState.spec?.description).toBe("edited in the console");
+    expect(fake.calls).toHaveLength(0);
+    expect(serverStampedReservedLabels(ctx).has(MCP_AUTH_LABEL)).toBe(true);
+  });
+
+  it("drops the label when the author alters the derived trio: their auth is theirs now", async () => {
+    const fake = answering(401, { "www-authenticate": CHALLENGE });
+    const altered = completedRow();
+    altered.spec!.auth!.discoveryUrl = "https://login.vendor.test";
+    const ctx = await run(altered, fake, completedRow());
+    expect(ctx.newState.spec?.auth?.discoveryUrl).toBe("https://login.vendor.test");
+    expect(ctx.newState.metadata?.labels[MCP_AUTH_LABEL]).toBeUndefined();
+    expect(fake.calls).toHaveLength(0);
+  });
+
+  it("drops the label when the author declares their own env on a completed row", async () => {
+    const fake = answering(401, { "www-authenticate": CHALLENGE });
+    const own = server({ headers: { Authorization: "Bearer ${TOKEN}" }, env: { TOKEN: { isSecret: true } }, labels: { [MCP_AUTH_LABEL]: MCP_AUTH_ENDPOINT } });
+    const ctx = await run(own, fake, completedRow());
+    expect(ctx.newState.spec?.auth).toBeUndefined();
+    expect(ctx.newState.metadata?.labels[MCP_AUTH_LABEL]).toBeUndefined();
+    expect(fake.calls).toHaveLength(0);
+  });
+
+  it("probes again when the URL changed, and completes from the new answer", async () => {
+    const fake = answering(401, { "www-authenticate": CHALLENGE });
+    const moved = server({ url: "https://mcp2.vendor.test/mcp" });
+    const ctx = await run(moved, fake, completedRow());
+    expect(fake.calls).toHaveLength(1);
+    expect(fake.calls[0]?.url).toBe("https://mcp2.vendor.test/mcp");
+    expectCompleted(ctx.newState);
+  });
+
+  it("probes again when the URL changed, and drops the label when the new endpoint is open", async () => {
+    const fake = answering(200);
+    const moved = server({ url: "https://open.vendor.test/mcp", labels: { [MCP_AUTH_LABEL]: MCP_AUTH_ENDPOINT } });
+    const ctx = await run(moved, fake, completedRow());
+    expect(fake.calls).toHaveLength(1);
+    expect(ctx.newState.spec?.auth).toBeUndefined();
+    expect(ctx.newState.metadata?.labels[MCP_AUTH_LABEL]).toBeUndefined();
+  });
+
+  it("does not reuse a completion from a row that lacks the label (an author's own auth is not a completion)", async () => {
+    const fake = answering(200);
+    const authored = completedRow();
+    delete authored.metadata!.labels[MCP_AUTH_LABEL];
+    const incoming = server();
+    const ctx = await run(incoming, fake, authored);
+    expect(fake.calls).toHaveLength(1);
+    expectUntouched(ctx.newState, incoming);
+  });
+});
+
+describe("accessTokenVariable", () => {
+  it("upper-cases the slug and folds every non-alphanumeric run into one underscore", () => {
+    expect(accessTokenVariable("linear")).toBe("LINEAR_ACCESS_TOKEN");
+    expect(accessTokenVariable("my-plugin.github-mcp")).toBe("MY_PLUGIN_GITHUB_MCP_ACCESS_TOKEN");
+    expect(accessTokenVariable("--odd--")).toBe("ODD_ACCESS_TOKEN");
+    expect(accessTokenVariable("")).toBe("MCP_ACCESS_TOKEN");
+  });
+});

package/src/domain/mcpserver/__tests__/connect-authorization.test.ts

@@ -118,6 +118,9 @@ function deps(authorizer: Authorizer): McpServerConnectDeps {
     pendingOAuthStates: store.pendingOAuthStates,
     secretService: unreachable("secretService"),
     oauthRedirectUri: "http://localhost:7233/oauth/callback",
+    outboundFetch: async () => {
+      throw new Error("no outbound fetch in this harness");
+    },
   };
 }
 

package/src/domain/mcpserver/__tests__/connect.test.ts

@@ -210,6 +210,10 @@ function makeHarness(options: FakeEngineOptions = {}): Harness {
       pendingOAuthStates: store.pendingOAuthStates,
       secretService: SecretService.create(undefined),
       oauthRedirectUri: "http://127.0.0.1:8234/auth/oauth/callback",
+      // No arm in this harness dials out; a call is a test bug, not a network.
+      outboundFetch: async () => {
+        throw new Error("no outbound fetch in this harness");
+      },
     },
   };
   return harness;
@@ -641,4 +645,31 @@ describe("startBestEffortConnect (apply tail)", () => {
       startBestEffortConnect(harness.deps, server),
     ).resolves.toBeUndefined();
   });
+
+  it("records a failed run through the same mapping as the blocking lane, so the page says what the runner found", async () => {
+    const harness = makeHarness({
+      outcome: {
+        ok: false,
+        failure: {
+          kind: "application",
+          message: "MCP server 'test' requires OAuth: its endpoint returned an authentication challenge (HTTP 401).",
+        },
+      },
+    });
+    const server = await seedServer({ stdio: false });
+    await startBestEffortConnect(harness.deps, server);
+    const after = await store.getResource(
+      ApiResourceKind.mcp_server,
+      server.metadata!.id,
+      McpServerSchema,
+    );
+    expect(after.status?.connectStatus?.phase).toBe(ConnectPhase.failed);
+    expect(after.status?.connectStatus?.failureCode).toBe("FailedPrecondition");
+    // The runner's "requires OAuth" sentence rides through verbatim
+    // (buildConnectFailureMessage's pass-through), never a generic
+    // "best-effort connect did not complete".
+    expect(after.status?.connectStatus?.failureMessage).toBe(
+      "MCP server 'test' requires OAuth: its endpoint returned an authentication challenge (HTTP 401).",
+    );
+  });
 });

package/src/domain/mcpserver/__tests__/oauth-handshake.test.ts

@@ -343,7 +343,7 @@ describe("initiateOAuthConnect", () => {
     await expectCode(
       command.initiateOAuthConnect({ mcpServerId: id, org: ORG }),
       Code.FailedPrecondition,
-      "does not advertise a registration_endpoint for DCR",
+      "does not advertise a registration_endpoint for DCR: 127.0.0.1:",
     );
     mockAs.reset();
   });