@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/agent-proxy/__tests__/cursor-sdk-key-required.test.ts

@@ -0,0 +1,119 @@
+/**
+ * An organization with no Cursor key, end to end with the real SDK:
+ * `@cursor/sdk` in a process of its own (`__test-utils__/cursor-sdk-wire-child.ts`),
+ * through the real local proxy's Cursor lane in forward mode, against a
+ * stand-in for the Stigmer Cloud proxy that refuses every REST call the way
+ * the cloud's Cursor REST lane refuses an organization with no Cursor key:
+ * HTTP 403 with `{"code":"permission_denied","message":"… [code:
+ * STIGMER_PROVIDER_KEY_REQUIRED]"}`.
+ *
+ * The refusal reaches the SDK at its key exchange, the first call a turn
+ * makes. The classifier recognises it only by the code in the message, so
+ * what this test pins is that the SDK keeps the body's message on the error
+ * it throws, and that the runner's classification of that error (the
+ * `CursorSdkError` arm of `execute-cursor/turn.ts`) reads as the missing
+ * key and is not retried. Every other test of the wording doubles the SDK.
+ */
+
+import { spawn } from "node:child_process";
+import { createServer, type IncomingHttpHeaders } from "node:http";
+import type { AddressInfo } from "node:net";
+import { fileURLToPath } from "node:url";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { testConfig } from "../../__test-utils__/config-fixture.js";
+import { formatClassifiedError, synthesizeError } from "../../activities/execute-cursor/error-classifier.js";
+import { writeTrustedCertificates } from "../../agent-host/hosting.js";
+import { PROVIDER_KEY_REQUIRED_SENTINEL } from "../../shared/model-error.js";
+import { AgentProxy } from "../server.js";
+
+const HOST_TOKEN = "host-token-key-required";
+const RUNNER_TOKEN = "runner-token-key-required";
+const EXECUTION = "aex-key-required";
+const TURN_KEY = "turn-key-key-required";
+const CHILD = fileURLToPath(new URL("../../__test-utils__/cursor-sdk-wire-child.ts", import.meta.url));
+const NO_KEY = "This organization has no Cursor key. An admin can add one in Settings → Provider keys.";
+
+interface Seen {
+  readonly method: string;
+  readonly path: string;
+  readonly headers: IncomingHttpHeaders;
+}
+
+interface Reported {
+  readonly status: string;
+  readonly error: string | null;
+  readonly sdkError?: { readonly code: string | null; readonly status: number | null };
+}
+
+/** The Stigmer Cloud proxy for an organization with no Cursor key: every REST call refused. */
+const seen: Seen[] = [];
+const cloud = createServer((req, res) => {
+  req.resume();
+  req.on("end", () => {
+    seen.push({ method: req.method ?? "", path: req.url ?? "", headers: req.headers });
+    res.writeHead(403, { "content-type": "application/json" });
+    res.end(JSON.stringify({ code: "permission_denied", message: `${NO_KEY} [code: ${PROVIDER_KEY_REQUIRED_SENTINEL}]` }));
+  });
+});
+let proxy: AgentProxy;
+let trust: { readonly file: string; remove(): void };
+
+beforeAll(async () => {
+  await new Promise<void>((resolve) => cloud.listen(0, "127.0.0.1", resolve));
+  const proxyEndpoint = `http://127.0.0.1:${(cloud.address() as AddressInfo).port}`;
+  proxy = await AgentProxy.start(testConfig({ proxyEndpoint, proxyTokenRef: { current: RUNNER_TOKEN } }));
+  proxy.authorizeHost(HOST_TOKEN);
+  proxy.openTurn({ executionId: EXECUTION, threadId: "thread-ses-key-required", turnKey: TURN_KEY });
+  trust = writeTrustedCertificates(proxy.cursorCertificate, undefined);
+});
+
+afterAll(async () => {
+  await proxy.close();
+  trust.remove();
+  await new Promise<void>((resolve) => cloud.close(() => resolve()));
+});
+
+/** Run the SDK's side in its own process and read the line it reports. */
+function runSdk(): Promise<Reported> {
+  return new Promise((resolve, reject) => {
+    const env: NodeJS.ProcessEnv = { ...process.env, NODE_EXTRA_CA_CERTS: trust.file, CURSOR_BACKEND_URL: proxy.cursorEndpoint };
+    delete env.NODE_TLS_REJECT_UNAUTHORIZED;
+    const child = spawn(process.execPath, ["--import", "tsx", CHILD, proxy.cursorEndpoint, HOST_TOKEN, EXECUTION, TURN_KEY], { env, stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (chunk: Buffer) => (out += chunk.toString("utf8")));
+    child.stderr.on("data", (chunk: Buffer) => (err += chunk.toString("utf8")));
+    child.on("exit", () => {
+      const line = out.split("\n").find((l) => l.startsWith("WIRE "));
+      if (line === undefined) reject(new Error(`the SDK's process reported nothing:\n${out}\n${err}`));
+      else resolve(JSON.parse(line.slice("WIRE ".length)) as Reported);
+    });
+  });
+}
+
+describe("the real Cursor SDK refused for an organization with no Cursor key", () => {
+  it("keeps the refusal's code on the error it throws, and the runner words it as the missing key, not retried", async () => {
+    const result = await runSdk();
+
+    const exchange = seen.find((s) => s.path === "/v1/proxy/cursor/api2.cursor.sh/auth/exchange_user_api_key");
+    expect(exchange?.method, "the key exchange reached the cloud through the lane").toBe("POST");
+    expect(exchange?.headers.authorization).toBe(`Bearer ${RUNNER_TOKEN}`);
+    expect(exchange?.headers["x-stigmer-execution-id"]).toBe(EXECUTION);
+
+    expect(result.status).toBe("thrown");
+    expect(result.error).toContain(PROVIDER_KEY_REQUIRED_SENTINEL);
+    expect(result.sdkError, "the SDK threw a CursorSdkError").toBeDefined();
+
+    // As `classifyThrown` in execute-cursor/turn.ts classifies a CursorSdkError.
+    const classified = synthesizeError({
+      sdkError: { code: result.sdkError?.code ?? undefined, status: result.sdkError?.status ?? undefined, message: result.error ?? undefined },
+      sdkResultFields: undefined,
+      streamErrorMessage: undefined,
+      capturedRejection: undefined,
+      isResumedHandle: false,
+      fallbackContext: { model: "composer-2.5", mode: "local", agentId: "" },
+    });
+    expect(formatClassifiedError(classified)).toBe(`${NO_KEY} [category=auth, source=sdk, retryable=false]`);
+  }, 60_000);
+});

package/src/agent-proxy/__tests__/cursor-sdk-wire.test.ts

@@ -0,0 +1,175 @@
+/**
+ * The Cursor wire end to end with the real SDK: `@cursor/sdk` in a process
+ * of its own, as the agent host runs it (`__test-utils__/cursor-sdk-wire-child.ts`),
+ * against the real local proxy (`agent-proxy/server.ts`, `cursor-lane.ts`),
+ * against a fake of Cursor that speaks both HTTP/1.1 and HTTP/2 on one port
+ * as Cursor's own hosts do. Every other Cursor test doubles the SDK; this one
+ * proves what only the SDK itself can.
+ *
+ * Pinned:
+ *  - the SDK trusts the lane through `NODE_EXTRA_CA_CERTS` alone, and opens
+ *    its agent run on it as an HTTP/2 stream;
+ *  - every key exchange reaches Cursor with the operator's key, every call
+ *    after it with the real access token, and nothing Cursor receives
+ *    carries the host's token;
+ *  - Cursor's answer on the stream comes back to the SDK;
+ *  - the lane refuses none of the SDK's side calls (its allow-list,
+ *    `CURSOR_SIDE_CALLS`, covers every `/aiserver.v1.*` call the SDK made);
+ *  - the SDK leaves certificate checks on in the host (it turns them off
+ *    for a backend URL that reads as localhost or 127.0.0.1).
+ */
+
+import { spawn } from "node:child_process";
+import { createServer as createHttp1Server, type IncomingHttpHeaders } from "node:http";
+import { createServer as createH2cServer, type ServerHttp2Stream } from "node:http2";
+import { createServer as createNetServer, type AddressInfo, type Server as NetServer } from "node:net";
+import { Duplex } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+
+import { testConfig } from "../../__test-utils__/config-fixture.js";
+import { writeTrustedCertificates } from "../../agent-host/hosting.js";
+import { CURSOR_SIDE_CALLS } from "../cursor-lane.js";
+import { AgentProxy } from "../server.js";
+
+const HOST_TOKEN = "host-token-sdk-wire";
+const OPERATOR_KEY = "crsr_operator_sdk_wire";
+const EXECUTION = "aex-sdk-wire";
+const TURN_KEY = "turn-key-sdk-wire";
+const REAL_TOKEN = `real.${Buffer.from(JSON.stringify({ exp: 2_000_000_000 })).toString("base64url")}.signature`;
+const CHILD = fileURLToPath(new URL("../../__test-utils__/cursor-sdk-wire-child.ts", import.meta.url));
+
+interface Seen {
+  readonly protocol: "http/1.1" | "h2";
+  readonly path: string;
+  readonly headers: IncomingHttpHeaders;
+}
+
+/** Cursor, faked: the exchange, the model list, the side calls, and an agent run it ends with an error of its own. */
+function fakeCursor(seen: Seen[]): NetServer {
+  const http1 = createHttp1Server((req, res) => {
+    req.resume();
+    req.on("end", () => {
+      seen.push({ protocol: "http/1.1", path: req.url ?? "", headers: req.headers });
+      const json = (status: number, body: unknown): void => {
+        res.writeHead(status, { "content-type": "application/json" });
+        res.end(JSON.stringify(body));
+      };
+      if (req.url === "/auth/exchange_user_api_key") json(200, { accessToken: REAL_TOKEN });
+      else if (req.url === "/v1/models") json(200, { items: [{ id: "composer-2.5", displayName: "Composer" }] });
+      else json(200, {});
+    });
+  });
+  const h2 = createH2cServer();
+  h2.on("stream", (stream: ServerHttp2Stream, headers) => {
+    seen.push({ protocol: "h2", path: String(headers[":path"]), headers });
+    stream.on("data", () => {});
+    const body = Buffer.from(JSON.stringify({ error: { code: "unavailable", message: "the fake Cursor ends the run" } }));
+    const frame = Buffer.alloc(5 + body.length);
+    frame[0] = 2; // the Connect end-of-stream flag
+    frame.writeUInt32BE(body.length, 1);
+    body.copy(frame, 5);
+    stream.respond({ ":status": 200, "content-type": String(headers["content-type"] ?? "application/connect+proto") });
+    stream.end(frame);
+  });
+  // One port for both, told apart by the HTTP/2 preface. The HTTP/2 server
+  // reads the socket's own handle, so it is handed a stream that replays the
+  // first chunk instead of the socket the chunk was taken from.
+  return createNetServer((socket) => {
+    // The SDK's process exits as soon as it reports, resetting its connections.
+    socket.on("error", () => {});
+    socket.once("data", (first: Buffer) => {
+      if (first.toString("latin1").startsWith("PRI * HTTP/2.0")) {
+        const bridge = new Duplex({
+          read() {},
+          write(chunk: Buffer, _encoding, done) {
+            socket.write(chunk, done);
+          },
+          final(done) {
+            socket.end();
+            done();
+          },
+        });
+        bridge.push(first);
+        socket.on("data", (chunk: Buffer) => bridge.push(chunk));
+        socket.on("end", () => bridge.push(null));
+        socket.on("close", () => bridge.destroy());
+        bridge.on("error", () => {});
+        h2.emit("connection", bridge);
+      } else {
+        socket.pause();
+        socket.unshift(first);
+        http1.emit("connection", socket);
+        socket.resume();
+      }
+    });
+  });
+}
+
+const seen: Seen[] = [];
+const cursor = fakeCursor(seen);
+let proxy: AgentProxy;
+let trust: { readonly file: string; remove(): void };
+const savedBackend = process.env.CURSOR_BACKEND_URL;
+
+beforeAll(async () => {
+  await new Promise<void>((resolve) => cursor.listen(0, "127.0.0.1", resolve));
+  process.env.CURSOR_BACKEND_URL = `http://127.0.0.1:${(cursor.address() as AddressInfo).port}`;
+  proxy = await AgentProxy.start(testConfig({ proxyEndpoint: null, cursorApiKey: OPERATOR_KEY }));
+  proxy.authorizeHost(HOST_TOKEN);
+  proxy.openTurn({ executionId: EXECUTION, threadId: "thread-ses-sdk-wire", turnKey: TURN_KEY });
+  trust = writeTrustedCertificates(proxy.cursorCertificate, undefined);
+});
+
+afterAll(async () => {
+  await proxy.close();
+  trust.remove();
+  await new Promise<void>((resolve) => cursor.close(() => resolve()));
+  if (savedBackend === undefined) delete process.env.CURSOR_BACKEND_URL;
+  else process.env.CURSOR_BACKEND_URL = savedBackend;
+});
+
+/** Run the SDK's side in its own process and read the line it reports. */
+function runSdk(): Promise<{ readonly status: string; readonly error: string | null; readonly tlsRejectUnauthorized: string | null }> {
+  return new Promise((resolve, reject) => {
+    const env: NodeJS.ProcessEnv = { ...process.env, NODE_EXTRA_CA_CERTS: trust.file, CURSOR_BACKEND_URL: proxy.cursorEndpoint };
+    delete env.NODE_TLS_REJECT_UNAUTHORIZED;
+    const child = spawn(process.execPath, ["--import", "tsx", CHILD, proxy.cursorEndpoint, HOST_TOKEN, EXECUTION, TURN_KEY], { env, stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (chunk: Buffer) => (out += chunk.toString("utf8")));
+    child.stderr.on("data", (chunk: Buffer) => (err += chunk.toString("utf8")));
+    child.on("exit", () => {
+      const line = out.split("\n").find((l) => l.startsWith("WIRE "));
+      if (line === undefined) reject(new Error(`the SDK's process reported nothing:\n${out}\n${err}`));
+      else resolve(JSON.parse(line.slice("WIRE ".length)) as never);
+    });
+  });
+}
+
+describe("the real Cursor SDK through the Cursor lane", () => {
+  it("opens its agent run over HTTP/2 on the lane, Cursor sees the runner's credentials only, and Cursor's answer comes back", async () => {
+    const warn = vi.spyOn(console, "warn");
+    const result = await runSdk();
+    const refused = warn.mock.calls.map((call) => String(call[0])).filter((line) => line.startsWith("[agent-proxy] refused"));
+    warn.mockRestore();
+    expect(refused, "the lane refused none of the SDK's calls").toEqual([]);
+
+    expect(result).toEqual({ status: "error", error: "[unavailable] the fake Cursor ends the run", tlsRejectUnauthorized: null });
+
+    const run = seen.find((s) => s.path === "/agent.v1.AgentService/Run");
+    expect(run?.protocol, "the agent run is an HTTP/2 stream").toBe("h2");
+    expect(run?.headers.authorization).toBe(`Bearer ${REAL_TOKEN}`);
+
+    const exchanges = seen.filter((s) => s.path === "/auth/exchange_user_api_key");
+    expect(exchanges.length).toBeGreaterThan(0);
+    for (const exchange of exchanges) expect(exchange.headers.authorization).toBe(`Bearer ${OPERATOR_KEY}`);
+    for (const call of seen.filter((s) => s.path.startsWith("/aiserver.v1.") || s.path.startsWith("/agent.v1."))) {
+      expect(call.headers.authorization, call.path).toBe(`Bearer ${REAL_TOKEN}`);
+    }
+    const sideCalls = seen.filter((s) => s.path.startsWith("/aiserver.v1.")).map((s) => s.path);
+    expect(sideCalls.length, "the SDK made side calls through the lane").toBeGreaterThan(0);
+    for (const path of sideCalls) expect(CURSOR_SIDE_CALLS.has(path), `${path} is on the lane's list`).toBe(true);
+    expect(JSON.stringify(seen.map((s) => s.headers))).not.toContain(HOST_TOKEN);
+  }, 60_000);
+});

package/src/agent-proxy/__tests__/lanes.test.ts

@@ -0,0 +1,258 @@
+/**
+ * The local proxy's lanes when the runner's own settings or identity cannot
+ * serve the call (`agent-proxy/lanes.ts`): each is answered with a status
+ * and a sentence the host's SDK surfaces, never a hang or an unanswered
+ * request, and never a call made with a credential the runner does not
+ * have.
+ *
+ * Pinned, through the server (`agent-proxy/server.ts`) against a fake
+ * provider:
+ *  - a setting a lane needs is missing or malformed (the Anthropic gateway,
+ *    the Bedrock and Vertex regions, the Foundry resource): 500 naming it;
+ *  - each lane serves its provider's model calls and nothing else under
+ *    its root (files, batches, fine-tuning, another API of the cloud
+ *    project): 404, with nothing sent;
+ *  - the runner's cloud identity cannot be had (no AWS credentials, no
+ *    Google credentials, no Azure token): 502 with the identity's own words;
+ *  - a forwarding runner that holds no Stigmer credential: 503;
+ *  - with an Azure identity and no Foundry key, the call carries the
+ *    identity's token;
+ *  - the Vertex endpoint for each kind of region, as the Vertex SDK names it;
+ *  - a path that names another origin (a scheme, or `//`) stays on the
+ *    lane's own host: the runner's key never leaves for a host the agent
+ *    host names.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const identities = vi.hoisted(() => ({ google: "ok" as "ok" | "fail", azure: "ok" as "ok" | "fail" }));
+
+vi.mock("google-auth-library", () => ({
+  GoogleAuth: class {
+    async getRequestHeaders(): Promise<Headers> {
+      if (identities.google === "fail") throw new Error("Could not load the default credentials");
+      return new Headers({ authorization: "Bearer google-token" });
+    }
+    async getProjectId(): Promise<string> {
+      return "real-project";
+    }
+  },
+}));
+
+vi.mock("@azure/identity", () => ({
+  DefaultAzureCredential: class {},
+  getBearerTokenProvider: () => async () => {
+    if (identities.azure === "fail") throw new Error("ChainedTokenCredential authentication failed");
+    return "azure-token";
+  },
+}));
+
+import { testConfig } from "../../__test-utils__/config-fixture.js";
+import { FakeUpstream } from "../../__test-utils__/fake-upstream.js";
+import type { Config } from "../../config.js";
+import { laneUrl, vertexBase } from "../lanes.js";
+import { AgentProxy } from "../server.js";
+
+const HOST_TOKEN = "host-token-lanes";
+const EXECUTION = "aex-lanes-edges";
+const TURN_KEY = "turn-key-lanes";
+const asHost = { authorization: `Bearer ${HOST_TOKEN}`, "x-stigmer-execution-id": EXECUTION, "x-stigmer-turn-key": TURN_KEY, "content-type": "application/json" };
+
+const upstream = new FakeUpstream();
+const saved = new Map<string, string | undefined>();
+
+function setEnv(values: Record<string, string | undefined>): void {
+  for (const [name, value] of Object.entries(values)) {
+    if (!saved.has(name)) saved.set(name, process.env[name]);
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+}
+
+beforeAll(() => upstream.start());
+afterAll(() => upstream.stop());
+beforeEach(() => {
+  upstream.received.length = 0;
+  identities.google = "ok";
+  identities.azure = "ok";
+});
+afterEach(() => {
+  for (const [name, value] of saved) {
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+  saved.clear();
+});
+
+async function ask(path: string, overrides: Partial<Config> = {}): Promise<{ readonly status: number; readonly message: string }> {
+  const proxy = await AgentProxy.start(testConfig({ proxyEndpoint: null, ...overrides }));
+  proxy.authorizeHost(HOST_TOKEN);
+  const close = proxy.openTurn({ executionId: EXECUTION, threadId: "thread-ses-lanes-edges", turnKey: TURN_KEY });
+  try {
+    const res = await fetch(`${proxy.endpoint}${path}`, { method: "POST", headers: asHost, body: "{}" });
+    const text = await res.text();
+    let message = text;
+    try {
+      message = (JSON.parse(text) as { error?: { message?: string } }).error?.message ?? text;
+    } catch {
+      // the provider's own body, relayed as it came
+    }
+    return { status: res.status, message };
+  } finally {
+    close();
+    await proxy.close();
+  }
+}
+
+describe("a lane the runner's settings cannot serve", () => {
+  it("names a malformed Anthropic gateway", async () => {
+    setEnv({ ANTHROPIC_BASE_URL: "not a url" });
+    const { status, message } = await ask("/v1/proxy/llm/anthropic/v1/messages");
+    expect(status).toBe(500);
+    expect(message).toMatch(/ANTHROPIC_BASE_URL="not a url" is not an http\(s\) URL/);
+  });
+
+  it("serves each provider's model calls and nothing else under its root", async () => {
+    setEnv({
+      ANTHROPIC_BASE_URL: upstream.url,
+      OPENAI_BASE_URL: `${upstream.url}/v1`,
+      AWS_REGION: "us-east-1",
+      AWS_BEARER_TOKEN_BEDROCK: "bedrock-bearer",
+      ANTHROPIC_BEDROCK_BASE_URL: upstream.url,
+      CLOUD_ML_REGION: "us-east5",
+      ANTHROPIC_VERTEX_BASE_URL: upstream.url,
+      ANTHROPIC_FOUNDRY_BASE_URL: `${upstream.url}/anthropic/`,
+      ANTHROPIC_FOUNDRY_API_KEY: "foundry-key",
+    });
+    for (const [path, refused] of [
+      ["/v1/proxy/llm/anthropic/v1/files", "/v1/files"],
+      ["/v1/proxy/llm/anthropic/v1/messages/batches", "/v1/messages/batches"],
+      ["/v1/proxy/llm/openai/models", "/models"],
+      ["/v1/proxy/llm/openai/v1/files/file-1/content", "/v1/files/file-1/content"],
+      ["/v1/proxy/llm/openai/v1/fine_tuning/jobs", "/v1/fine_tuning/jobs"],
+      ["/v1/proxy/llm/bedrock/model/x/list", "/model/x/list"],
+      ["/v1/proxy/llm/vertex/projects/p/locations/us-east5/datasets", "/projects/p/locations/us-east5/datasets"],
+      ["/v1/proxy/llm/foundry/v1/files", "/v1/files"],
+    ] as const) {
+      const lane = path.split("/")[4];
+      expect(await ask(path), path).toEqual({ status: 404, message: `the ${lane} lane serves model calls only, not ${refused}` });
+    }
+    expect(upstream.received).toEqual([]);
+  });
+
+  it("names the region Bedrock and Vertex need, and the resource Foundry needs", async () => {
+    setEnv({ AWS_REGION: undefined, CLOUD_ML_REGION: undefined, ANTHROPIC_FOUNDRY_RESOURCE: undefined, ANTHROPIC_FOUNDRY_BASE_URL: undefined });
+    expect(await ask("/v1/proxy/llm/bedrock/model/x/invoke")).toEqual({ status: 500, message: "the bedrock lane needs AWS_REGION on the runner" });
+    expect(await ask("/v1/proxy/llm/vertex/projects/p/locations/l/publishers/anthropic/models/m:rawPredict")).toEqual({
+      status: 500,
+      message: "the vertex lane needs CLOUD_ML_REGION on the runner",
+    });
+    expect(await ask("/v1/proxy/llm/foundry/v1/messages")).toEqual({
+      status: 500,
+      message: "the foundry lane needs ANTHROPIC_FOUNDRY_RESOURCE or ANTHROPIC_FOUNDRY_BASE_URL on the runner",
+    });
+  });
+
+  it("refuses to forward for a runner that holds no Stigmer credential", async () => {
+    const result = await ask("/v1/proxy/llm/anthropic/v1/messages", { proxyEndpoint: upstream.url, stigmerTokenRef: { current: null } });
+    expect(result).toEqual({ status: 503, message: "the runner holds no Stigmer credential to forward this call with" });
+    expect(upstream.received).toEqual([]);
+  });
+});
+
+describe("a lane the runner's cloud identity cannot serve", () => {
+  it("answers 502 with the AWS chain's own words when there are no AWS credentials", async () => {
+    const empty = mkdtempSync(join(tmpdir(), "stigmer-no-aws-"));
+    writeFileSync(join(empty, "config"), "");
+    writeFileSync(join(empty, "credentials"), "");
+    setEnv({
+      AWS_REGION: "ap-south-1",
+      ANTHROPIC_BEDROCK_BASE_URL: upstream.url,
+      AWS_BEARER_TOKEN_BEDROCK: undefined,
+      AWS_ACCESS_KEY_ID: undefined,
+      AWS_SECRET_ACCESS_KEY: undefined,
+      AWS_SESSION_TOKEN: undefined,
+      AWS_PROFILE: undefined,
+      AWS_WEB_IDENTITY_TOKEN_FILE: undefined,
+      AWS_CONTAINER_CREDENTIALS_RELATIVE_URI: undefined,
+      AWS_CONTAINER_CREDENTIALS_FULL_URI: undefined,
+      AWS_CONFIG_FILE: join(empty, "config"),
+      AWS_SHARED_CREDENTIALS_FILE: join(empty, "credentials"),
+      AWS_EC2_METADATA_DISABLED: "true",
+    });
+    try {
+      const { status, message } = await ask("/v1/proxy/llm/bedrock/model/x/invoke");
+      expect(status).toBe(502);
+      expect(message).toMatch(/^Failed to resolve AWS credentials from the credential provider chain\. \(.+\)$/);
+      expect(upstream.received).toEqual([]);
+    } finally {
+      rmSync(empty, { recursive: true, force: true });
+    }
+  });
+
+  it("answers 502 when Google credentials cannot be had", async () => {
+    identities.google = "fail";
+    setEnv({ CLOUD_ML_REGION: "us-east5", ANTHROPIC_VERTEX_BASE_URL: upstream.url });
+    const { status, message } = await ask("/v1/proxy/llm/vertex/projects/p/locations/us-east5/publishers/anthropic/models/m:rawPredict");
+    expect(status).toBe(502);
+    expect(message).toBe("Failed to acquire Google OAuth credentials: Could not load the default credentials");
+  });
+
+  it("carries the Azure identity's token when there is no Foundry key, and answers 502 when there is none", async () => {
+    setEnv({ ANTHROPIC_FOUNDRY_BASE_URL: `${upstream.url}/anthropic/`, ANTHROPIC_FOUNDRY_RESOURCE: undefined, ANTHROPIC_FOUNDRY_API_KEY: undefined });
+    await ask("/v1/proxy/llm/foundry/v1/messages");
+    expect(upstream.last.headers.authorization).toBe("Bearer azure-token");
+
+    identities.azure = "fail";
+    const { status, message } = await ask("/v1/proxy/llm/foundry/v1/messages");
+    expect(status).toBe(502);
+    expect(message).toBe("Failed to acquire an Azure token for Microsoft Foundry: ChainedTokenCredential authentication failed");
+  });
+});
+
+describe("a path that names another origin", () => {
+  const elsewhere = new FakeUpstream();
+  beforeAll(() => elsewhere.start());
+  afterAll(() => elsewhere.stop());
+
+  it("stays on each lane's own host, the runner's key with it", async () => {
+    const away = new URL(elsewhere.url);
+    setEnv({
+      ANTHROPIC_FOUNDRY_BASE_URL: `${upstream.url}/anthropic/`,
+      ANTHROPIC_FOUNDRY_API_KEY: "foundry-key-stays-home",
+      ANTHROPIC_BASE_URL: upstream.url,
+      ANTHROPIC_API_KEY: "anthropic-key-stays-home",
+      OPENAI_BASE_URL: `${upstream.url}/v1`,
+      OPENAI_API_KEY: "openai-key-stays-home",
+    });
+    for (const path of [
+      `/v1/proxy/llm/foundry/${elsewhere.url}/v1/messages`,
+      `/v1/proxy/llm/foundry//${away.host}/v1/messages`,
+      `/v1/proxy/llm/anthropic/${elsewhere.url}/v1/messages`,
+      `/v1/proxy/llm/anthropic//${away.host}/v1/messages`,
+      `/v1/proxy/llm/openai/v1/${elsewhere.url}/x`,
+    ]) {
+      expect((await ask(path)).status, path).toBe(404);
+    }
+    expect(elsewhere.received, "a request reached the other origin").toEqual([]);
+    expect(upstream.received).toEqual([]);
+  });
+
+  it("is refused when the joined URL would leave the lane's origin or its path", () => {
+    expect(laneUrl("https://res.services.ai.azure.com/anthropic/", "/v1/messages").toString()).toBe("https://res.services.ai.azure.com/anthropic/v1/messages");
+    expect(() => laneUrl("https://api.anthropic.com", "@elsewhere.example/v1/messages")).toThrow("the lane's path must stay under the lane's own endpoint");
+    expect(() => laneUrl("https://res.services.ai.azure.com/anthropic", "/../other/v1/messages")).toThrow("the lane's path must stay under the lane's own endpoint");
+  });
+});
+
+describe("the Vertex endpoint", () => {
+  it("is the one the Vertex SDK names for each kind of region", () => {
+    expect(vertexBase("global")).toBe("https://aiplatform.googleapis.com/v1");
+    expect(vertexBase("us")).toBe("https://aiplatform.us.rep.googleapis.com/v1");
+    expect(vertexBase("eu")).toBe("https://aiplatform.eu.rep.googleapis.com/v1");
+    expect(vertexBase("us-east5")).toBe("https://us-east5-aiplatform.googleapis.com/v1");
+  });
+});

package/src/agent-proxy/__tests__/loopback-certificate.test.ts

@@ -0,0 +1,100 @@
+/**
+ * The loopback certificate (`agent-proxy/loopback-certificate.ts`), proved
+ * the way the agent host uses it.
+ *
+ * Pinned:
+ *  - Node's X.509 parser reads it: self-signed, for IP 127.0.0.1, valid now
+ *    and for years, signed by its own key;
+ *  - a TLS client that trusts it completes a handshake with a server that
+ *    serves it, on 127.0.0.1, over HTTP/2;
+ *  - a client that trusts something else refuses it, and each mint is a
+ *    different key;
+ *  - a serial whose random bytes start with zeros, or with a high bit, is
+ *    still encoded in DER's minimal form (about one random serial in 256
+ *    starts with a zero byte);
+ *  - a certificate minted near or past 2050 still names its real dates
+ *    (RFC 5280: UTCTime through 2049, GeneralizedTime from 2050).
+ */
+
+import { X509Certificate, createPublicKey } from "node:crypto";
+import { connect, createSecureServer, type Http2SecureServer } from "node:http2";
+import type { AddressInfo } from "node:net";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { mintLoopbackCertificate } from "../loopback-certificate.js";
+
+let server: Http2SecureServer | undefined;
+
+afterEach(async () => {
+  await new Promise<void>((resolve) => (server ? server.close(() => resolve()) : resolve()));
+  server = undefined;
+});
+
+async function serve(certPem: string, keyPem: string): Promise<number> {
+  server = createSecureServer({ cert: certPem, key: keyPem }, (_req, res) => {
+    res.writeHead(200, { "content-type": "text/plain" });
+    res.end("over loopback TLS");
+  });
+  await new Promise<void>((resolve) => server!.listen(0, "127.0.0.1", resolve));
+  return (server.address() as AddressInfo).port;
+}
+
+function get(port: number, ca: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const session = connect(`https://127.0.0.1:${port}`, { ca });
+    session.on("error", reject);
+    const req = session.request({ ":path": "/" });
+    let body = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk: string) => (body += chunk));
+    req.on("end", () => {
+      session.close();
+      resolve(body);
+    });
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+describe("the loopback certificate", () => {
+  it("is a self-signed certificate for 127.0.0.1, valid for years, signed by its own key", () => {
+    const now = new Date("2026-10-10T00:00:00Z");
+    const { certPem, keyPem } = mintLoopbackCertificate(now);
+    const cert = new X509Certificate(certPem);
+
+    expect(cert.subject).toBe("CN=stigmer agent proxy");
+    expect(cert.issuer).toBe(cert.subject);
+    expect(cert.checkIP("127.0.0.1")).toBe("127.0.0.1");
+    expect(cert.checkHost("example.com")).toBeUndefined();
+    expect(new Date(cert.validFrom).getTime()).toBeLessThan(now.getTime());
+    expect(new Date(cert.validTo).getUTCFullYear()).toBe(2036);
+    expect(cert.verify(createPublicKey(keyPem))).toBe(true);
+  });
+
+  it("completes an HTTP/2 handshake for a client that trusts it, and only for one", async () => {
+    const minted = mintLoopbackCertificate();
+    const port = await serve(minted.certPem, minted.keyPem);
+
+    expect(await get(port, minted.certPem)).toBe("over loopback TLS");
+    await expect(get(port, mintLoopbackCertificate().certPem)).rejects.toThrow(/self[- ]signed|unable to verify|certificate/i);
+  });
+
+  it("encodes a serial that starts with zero bytes, or with a high bit, as DER requires", () => {
+    for (const serial of [Buffer.from("00001122334455667788", "hex"), Buffer.from("007f", "hex"), Buffer.from("80ff", "hex"), Buffer.from("00", "hex")]) {
+      const cert = new X509Certificate(mintLoopbackCertificate(new Date(), serial).certPem);
+      expect(cert.serialNumber.replace(/^0+(?=.)/, "").toLowerCase(), serial.toString("hex")).toBe(BigInt(`0x${serial.toString("hex")}`).toString(16));
+    }
+  });
+
+  it("names its real dates when its validity reaches 2050 or later", () => {
+    for (const [minted, expires] of [["2045-06-01T00:00:00Z", 2055], ["2051-06-01T00:00:00Z", 2061]] as const) {
+      const cert = new X509Certificate(mintLoopbackCertificate(new Date(minted)).certPem);
+      expect(new Date(cert.validTo).getUTCFullYear(), minted).toBe(expires);
+      expect(new Date(cert.validFrom).getUTCFullYear(), minted).toBe(new Date(minted).getUTCFullYear());
+    }
+  });
+
+  it("is a new key at every mint", () => {
+    expect(mintLoopbackCertificate().keyPem).not.toBe(mintLoopbackCertificate().keyPem);
+  });
+});