Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): verify remote Vercel credentials (#109)

Ruic084232e16ae
diff --git a/.changeset/verified-remote-credentials.md b/.changeset/verified-remote-credentials.md
new file mode 100644
index 000000000..12dce2f9c
--- /dev/null
+++ b/.changeset/verified-remote-credentials.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Verify remote Vercel deployment origins against the owner and project supplied by `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID`, or by a local project link, before sending ambient credentials. Remote dev and eval clients now refresh scoped OIDC tokens per request and refuse to forward credentials across redirects. Remote `eve dev` and `eve eval --url` targets now require `https://` (loopback hosts may still use `http://`).
diff --git a/docs/evals/targets.mdx b/docs/evals/targets.mdx
index a28a9577d..9a3d14315 100644
--- a/docs/evals/targets.mdx
+++ b/docs/evals/targets.mdx
@@ -30,12 +30,14 @@ Sessions attached this way are full `EveEvalSession`s: you can keep driving them
## Authentication
-Local targets send no auth: `eve eval` owns the dev server it boots. A remote `--url` target connects with the same credentials as every other development client, resolved in this order:
+Local targets send no auth: `eve eval` owns the dev server it boots. For a remote `--url`, eve gets the expected Vercel owner and project from `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` when both are set. Otherwise it reads `.vercel/project.json`. Eve then asks Vercel to resolve the exact HTTPS origin and sends ambient credentials only when the project IDs match. An arbitrary URL remains anonymous.
-- A Vercel OIDC trusted-IDP token, sent as a per-request header. It bypasses Deployment Protection without a per-project secret, so a CI job with a pulled OIDC token reaches a protected preview deployment without extra setup.
-- An `x-vercel-protection-bypass` header, added when `VERCEL_AUTOMATION_BYPASS_SECRET` is set.
-- A bearer token resolved from the same OIDC cascade.
-- `EVE_EVAL_AUTH_TOKEN`, which overrides the bearer with a static token for targets whose auth is not OIDC-based.
+After verification, eve sends the available Vercel credentials:
+
+- The resolved OIDC token as both the bearer and Vercel trusted-IDP header.
+- `VERCEL_AUTOMATION_BYPASS_SECRET`, when set, as the Protection Bypass for Automation header.
+
+`EVE_EVAL_AUTH_TOKEN` is an explicit bearer override for targets whose auth is not Vercel OIDC. Credential-bearing clients do not follow redirects, so those headers cannot be forwarded to another origin.
`t.target.fetch(path, init)` carries these same credentials, so channel and webhook ingress you exercise through it authenticates the same way the session protocol does.
diff --git a/docs/guides/client/overview.mdx b/docs/guides/client/overview.mdx
index 0d213ebf2..59d794af0 100644
--- a/docs/guides/client/overview.mdx
+++ b/docs/guides/client/overview.mdx
@@ -67,9 +67,12 @@ const client = new Client({
headers: async () => ({
"x-vercel-protection-bypass": await getBypassToken(),
}),
+ redirect: "manual",
});
```
+Set `redirect` to `"manual"` or `"error"` on credential-bearing clients so fetch cannot forward custom authorization headers to another origin. The policy applies to inspection requests, custom fetches, session creation, and event streams.
+
Per-request headers can be attached to an individual turn:
```ts
diff --git a/docs/guides/dev-tui.md b/docs/guides/dev-tui.md
index 40cc7f3c1..a712fef82 100644
--- a/docs/guides/dev-tui.md
+++ b/docs/guides/dev-tui.md
@@ -119,7 +119,7 @@ Pass a URL and the TUI talks to a running deployment instead of starting a local
eve dev https://<your-app>
```
-The bare URL is shorthand for `--url`. `--host`, `--port`, and `--no-ui` are ignored against a remote target. If the deployment sits behind Vercel preview protection, set `VERCEL_AUTOMATION_BYPASS_SECRET` locally first. See [Deployment](./deployment) for the smoke-test flow.
+The bare URL is shorthand for `--url`; `--host`, `--port`, and `--no-ui` cannot be combined with a remote target. Eve gets the expected Vercel owner and project from `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` when both are set, or from the current directory's Vercel link otherwise. It verifies the exact deployment origin before attaching a freshly resolved project-scoped OIDC token or `VERCEL_AUTOMATION_BYPASS_SECRET`. Unverified URLs remain anonymous, and credential-bearing requests do not follow redirects. See [Deployment](./deployment) for the smoke-test flow.
## What to read next
diff --git a/packages/eve/src/cli/dev/tui/target.test.ts b/packages/eve/src/cli/dev/tui/target.test.ts
new file mode 100644
index 000000000..9ea25a31e
--- /dev/null
+++ b/packages/eve/src/cli/dev/tui/target.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveTuiTitle } from "./target.js";
+
+describe("resolveTuiTitle", () => {
+ it("humanizes the app folder name for a local server", () => {
+ expect(
+ resolveTuiTitle({
+ name: undefined,
+ target: {
+ kind: "local",
+ serverUrl: "http://127.0.0.1:3000",
+ workspaceRoot: "/x/apps/fixtures/weather-agent",
+ },
+ }),
+ ).toBe("Weather Agent");
+ });
+
+ it("uses the remote host when connecting to a URL", () => {
+ expect(
+ resolveTuiTitle({
+ name: undefined,
+ target: {
+ kind: "remote",
+ serverUrl: "https://example.com:8080",
+ workspaceRoot: "/x",
+ },
+ }),
+ ).toBe("example.com:8080");
+ });
+
+ it("prefers an explicit --name over both", () => {
+ expect(
+ resolveTuiTitle({
+ name: "Custom",
+ target: {
+ kind: "remote",
+ serverUrl: "https://example.com",
+ workspaceRoot: "/x/weather-agent",
+ },
+ }),
+ ).toBe("Custom");
+ });
+});
diff --git a/packages/eve/src/cli/dev/tui/target.ts b/packages/eve/src/cli/dev/tui/target.ts
new file mode 100644
index 000000000..3cef97d01
--- /dev/null
+++ b/packages/eve/src/cli/dev/tui/target.ts
@@ -0,0 +1,45 @@
+import { basename } from "node:path";
+
+interface DevelopmentTargetBase {
+ readonly serverUrl: string;
+ /** Local workspace root for app files and the fallback Vercel project link. */
+ readonly workspaceRoot: string;
+}
+
+/** A development TUI session backed by the local `eve dev` server. */
+export interface LocalDevelopmentTarget extends DevelopmentTargetBase {
+ readonly kind: "local";
+}
+
+/** A development TUI session connected to an existing remote server. */
+export interface RemoteDevelopmentTarget extends DevelopmentTargetBase {
+ readonly kind: "remote";
+}
+
+/** Local or remote server backing one development TUI session. */
+export type DevelopmentTuiTarget = LocalDevelopmentTarget | RemoteDevelopmentTarget;
+
+/** Resolves the explicit name, remote host, or humanized local folder shown by the TUI. */
+export function resolveTuiTitle(input: {
+ readonly name: string | undefined;
+ readonly target: DevelopmentTuiTarget;
+}): string | undefined {
+ if (input.name !== undefined && input.name.length > 0) return input.name;
+
+ if (input.target.kind === "remote") {
+ try {
+ return new URL(input.target.serverUrl).host;
+ } catch {
+ return undefined;
+ }
+ }
+
+ const humanized = basename(input.target.workspaceRoot)
+ .replace(/[-_.]+/gu, " ")
+ .trim()
+ .split(/\s+/u)
+ .filter((word) => word.length > 0)
+ .map((word) => word[0]!.toUpperCase() + word.slice(1))
+ .join(" ");
+ return humanized.length > 0 ? humanized : undefined;
+}
diff --git a/packages/eve/src/cli/dev/tui/tui.ts b/packages/eve/src/cli/dev/tui/tui.ts
index c19134db8..991423fde 100644
--- a/packages/eve/src/cli/dev/tui/tui.ts
+++ b/packages/eve/src/cli/dev/tui/tui.ts
@@ -1,5 +1,9 @@
import { Client } from "#client/index.js";
import { resolveDevelopmentClientOptions } from "#services/dev-client/client-options.js";
+import {
+ resolveVerifiedRemoteDevelopmentClient,
+ type VerifiedRemoteDevelopmentClient,
+} from "#setup/verified-remote-client.js";
import {
formatVercelAuthChallengeMessage,
isVercelAuthChallenge,
@@ -9,23 +13,14 @@ import type { DevBootProgressReporter } from "#internal/dev-boot-progress.js";
import { createPromptCommandHandler } from "./prompt-command-handler.js";
import { EveTUIRunner, type EveTUIRunnerOptions } from "./runner.js";
+import type { DevelopmentTuiTarget } from "./target.js";
import type { TuiDisplayOptions } from "./types.js";
-/**
- * Options for running the `eve dev` terminal UI against a server URL.
- */
+export type { DevelopmentTuiTarget } from "./target.js";
+
export interface RunDevelopmentTuiInput extends TuiDisplayOptions {
- /**
- * The eve server URL the TUI connects to — either the in-process dev
- * server started by `eve dev`, or a remote `--url` target.
- */
- readonly serverUrl: string;
- /**
- * Absolute application root. When present and the server is a local dev
- * server, enables the TUI's `/model` command to edit local agent source.
- * Omitted for remote (`--url`) targets.
- */
- readonly appRoot?: string;
+ /** The local server or remote URL used by this TUI session. */
+ readonly target: DevelopmentTuiTarget;
/**
* Text to seed the prompt input with after the UI launches. The buffer is
* editable and is not auto-submitted — the user presses Enter to send it.
@@ -36,6 +31,22 @@ export interface RunDevelopmentTuiInput extends TuiDisplayOptions {
readonly onBootProgress?: DevBootProgressReporter;
}
+async function resolveClientOptions(
+ target: DevelopmentTuiTarget,
+): Promise<VerifiedRemoteDevelopmentClient> {
+ if (target.kind === "local") {
+ return {
+ options: resolveDevelopmentClientOptions(target.serverUrl),
+ lastOidcTokenFailure: () => undefined,
+ };
+ }
+
+ return await resolveVerifiedRemoteDevelopmentClient({
+ serverUrl: target.serverUrl,
+ workspaceRoot: target.workspaceRoot,
+ });
+}
+
/**
* Runs the `eve dev` terminal UI against the given server URL until the
* user exits.
@@ -46,22 +57,26 @@ export interface RunDevelopmentTuiInput extends TuiDisplayOptions {
* the inline error region rather than crashing the command.
*/
export async function runDevelopmentTui(input: RunDevelopmentTuiInput): Promise<void> {
- const { serverUrl, appRoot, initialInput, onBootProgress, ...display } = input;
+ const { target, initialInput, onBootProgress, ...display } = input;
+ const { serverUrl } = target;
- const client = new Client(resolveDevelopmentClientOptions(serverUrl));
+ const { options: clientOptions, lastOidcTokenFailure } = await resolveClientOptions(target);
+ const client = new Client(clientOptions);
const options: EveTUIRunnerOptions = {
...display,
session: client.session(),
client,
serverUrl,
- promptCommandHandler: createPromptCommandHandler({ appRoot }),
+ promptCommandHandler: createPromptCommandHandler(
+ target.kind === "local" ? { appRoot: target.workspaceRoot } : {},
+ ),
formatTransportError: (error) =>
isVercelAuthChallenge(error)
- ? formatVercelAuthChallengeMessage({ serverUrl })
+ ? formatVercelAuthChallengeMessage({ serverUrl, oidcTokenFailure: lastOidcTokenFailure() })
: toErrorMessage(error),
};
- if (appRoot !== undefined) options.appRoot = appRoot;
+ if (target.kind === "local") options.appRoot = target.workspaceRoot;
if (initialInput !== undefined) options.initialInput = initialInput;
if (onBootProgress !== undefined) options.onBootProgress = onBootProgress;
diff --git a/packages/eve/src/cli/dev/url.test.ts b/packages/eve/src/cli/dev/url.test.ts
new file mode 100644
index 000000000..094a9d04f
--- /dev/null
+++ b/packages/eve/src/cli/dev/url.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+
+import { InvalidArgumentError } from "#compiled/commander/index.js";
+
+import { parseDevelopmentServerUrl } from "./url.js";
+
+describe("parseDevelopmentServerUrl", () => {
+ it("accepts https remote URLs and strips hash and query", () => {
+ expect(parseDevelopmentServerUrl("https://my-app.vercel.app/path?token=1#frag")).toBe(
+ "https://my-app.vercel.app/path",
+ );
+ });
+
+ it("keeps http for loopback development hosts", () => {
+ for (const url of ["http://localhost:3000", "http://127.0.0.1:2000", "http://[::1]:2000"]) {
+ expect(parseDevelopmentServerUrl(url)).toBe(new URL(url).toString());
+ }
+ });
+
+ it("rejects http for remote hosts so credentials can never target an http origin", () => {
+ expect(() => parseDevelopmentServerUrl("http://my-app.vercel.app")).toThrow(
+ InvalidArgumentError,
+ );
+ expect(() => parseDevelopmentServerUrl("http://my-app.vercel.app")).toThrow(/https/);
+ });
+
+ it("rejects non-http(s) protocols", () => {
+ expect(() => parseDevelopmentServerUrl("ftp://example.com")).toThrow(InvalidArgumentError);
+ });
+
+ it("rejects malformed input", () => {
+ expect(() => parseDevelopmentServerUrl("not a url")).toThrow(InvalidArgumentError);
+ });
+});
diff --git a/packages/eve/src/cli/dev/url.ts b/packages/eve/src/cli/dev/url.ts
index 3a48b9a03..b10dda8e5 100644
--- a/packages/eve/src/cli/dev/url.ts
+++ b/packages/eve/src/cli/dev/url.ts
@@ -1,4 +1,5 @@
import { InvalidArgumentError } from "#compiled/commander/index.js";
+import { isLocalEveServerUrl } from "#services/dev-client/local-host.js";
const DEVELOPMENT_SERVER_PROTOCOLS = new Set(["http:", "https:"]);
@@ -8,6 +9,19 @@ function assertDevelopmentServerProtocol(url: URL, value: string): void {
}
}
+/**
+ * Reject http for remote hosts. The verified-remote client only sends
+ * credentials to an https origin, so an http remote would never authenticate.
+ * Loopback stays http for local dev.
+ */
+function assertSecureRemoteProtocol(url: URL, value: string): void {
+ if (url.protocol === "http:" && !isLocalEveServerUrl(url)) {
+ throw new InvalidArgumentError(
+ `Remote servers must use https://; received "${value}". Only local hosts may use http://.`,
+ );
+ }
+}
+
/**
* Parse and normalize an eve server URL for the development REPL.
*/
@@ -18,6 +32,7 @@ export function parseDevelopmentServerUrl(value: string): string {
const url = new URL(normalizedValue);
assertDevelopmentServerProtocol(url, value);
+ assertSecureRemoteProtocol(url, value);
url.hash = "";
url.search = "";
diff --git a/packages/eve/src/cli/run.test.ts b/packages/eve/src/cli/run.test.ts
index c0293fe7e..a360b559d 100644
--- a/packages/eve/src/cli/run.test.ts
+++ b/packages/eve/src/cli/run.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it, vi } from "vitest";
-import { resolveDevUiMode, resolveTuiDisplayOptions, resolveTuiTitle, runCli } from "#cli/run.js";
+import { resolveDevUiMode, resolveTuiDisplayOptions, runCli } from "#cli/run.js";
import type { RunDevelopmentTuiInput } from "#cli/dev/tui/tui.js";
import type { DevelopmentServerOptions } from "#internal/nitro/host/types.js";
@@ -57,7 +57,11 @@ describe("eve dev --input", () => {
expect(runDevelopmentTui).toHaveBeenCalledWith(
expect.objectContaining({
initialInput: "/model",
- serverUrl: "https://example.com/",
+ target: {
+ kind: "remote",
+ serverUrl: "https://example.com/",
+ workspaceRoot: process.cwd(),
+ },
}),
);
});
@@ -82,6 +86,22 @@ describe("eve dev --input", () => {
});
});
+describe("eve dev --url protocol", () => {
+ it("rejects an http:// remote URL up front instead of crashing during connect", async () => {
+ await expect(
+ runCli(["dev", "--url", "http://my-app.vercel.app"], { error: () => {}, log: () => {} }),
+ ).rejects.toThrow(/https/);
+ });
+});
+
+describe("eve eval --url protocol", () => {
+ it("rejects an http:// remote URL up front", async () => {
+ await expect(
+ runCli(["eval", "--url", "http://my-app.vercel.app"], { error: () => {}, log: () => {} }),
+ ).rejects.toThrow(/https/);
+ });
+});
+
describe("eve dev --logs", () => {
it("accepts sandbox as the initial TUI log mode", async () => {
const runDevelopmentTui = vi.fn(async () => {});
@@ -97,7 +117,11 @@ describe("eve dev --logs", () => {
expect(runDevelopmentTui).toHaveBeenCalledWith(
expect.objectContaining({
logs: "sandbox",
- serverUrl: "https://example.com/",
+ target: {
+ kind: "remote",
+ serverUrl: "https://example.com/",
+ workspaceRoot: process.cwd(),
+ },
}),
);
});
@@ -193,35 +217,3 @@ describe("resolveTuiDisplayOptions", () => {
expect(resolved.logs).toBe("stderr");
});
});
-
-describe("resolveTuiTitle", () => {
- it("humanizes the app folder name for a local server", () => {
- expect(
- resolveTuiTitle({
- name: undefined,
- remoteServerUrl: undefined,
- appRoot: "/x/apps/fixtures/weather-agent",
- }),
- ).toBe("Weather Agent");
- });
-
- it("uses the remote host when connecting to a URL", () => {
- expect(
- resolveTuiTitle({
- name: undefined,
- remoteServerUrl: "https://example.com:8080",
- appRoot: "/x",
- }),
- ).toBe("example.com:8080");
- });
-
- it("prefers an explicit --name over both", () => {
- expect(
- resolveTuiTitle({
- name: "Custom",
- remoteServerUrl: "https://example.com",
- appRoot: "/x/weather-agent",
- }),
- ).toBe("Custom");
- });
-});
diff --git a/packages/eve/src/cli/run.ts b/packages/eve/src/cli/run.ts
index 23ab692bb..c3fa73f7a 100644
--- a/packages/eve/src/cli/run.ts
+++ b/packages/eve/src/cli/run.ts
@@ -1,5 +1,3 @@
-import { basename } from "node:path";
-
import { Command, CommanderError, InvalidArgumentError } from "#compiled/commander/index.js";
import { devBootPhase, type DevBootProgressReporter } from "#internal/dev-boot-progress.js";
import { resolveApplicationRoot } from "#internal/application/paths.js";
@@ -8,6 +6,7 @@ import { eveCliBanner } from "#cli/banner.js";
import { registerProjectCommands } from "#cli/commands/register-project-commands.js";
import type { RunDevelopmentTuiInput } from "#cli/dev/tui/tui.js";
import { LOG_DISPLAY_MODES, parseLogDisplayMode } from "#cli/dev/tui/log-display-mode.js";
+import { resolveTuiTitle, type DevelopmentTuiTarget } from "#cli/dev/tui/target.js";
import { parseDevelopmentServerUrl } from "#cli/dev/url.js";
import { startCliLiveRow } from "#cli/ui/live-row.js";
import { createCliTheme, renderCliTaggedLine } from "#cli/ui/output.js";
@@ -263,44 +262,6 @@ export function resolveDevUiMode(input: {
return "tui";
}
-/**
- * Resolves the terminal UI's header title: an explicit `--name`, else the
- * remote server's host (for `--url`), else the humanized app-folder name
- * (e.g. `apps/fixtures/weather-agent` → "Weather Agent"). Returns `undefined` when
- * nothing meaningful can be derived, so the runner falls back to its own
- * default.
- */
-export function resolveTuiTitle(input: {
- name: string | undefined;
- remoteServerUrl: string | undefined;
- appRoot: string;
-}): string | undefined {
- if (input.name !== undefined && input.name.length > 0) {
- return input.name;
- }
-
- if (input.remoteServerUrl !== undefined) {
- try {
- return new URL(input.remoteServerUrl).host;
- } catch {
- return undefined;
- }
- }
-
- const humanized = humanizeProjectName(basename(input.appRoot));
- return humanized.length > 0 ? humanized : undefined;
-}
-
-function humanizeProjectName(name: string): string {
- return name
- .replace(/[-_.]+/gu, " ")
- .trim()
- .split(/\s+/u)
- .filter((word) => word.length > 0)
- .map((word) => word[0]!.toUpperCase() + word.slice(1))
- .join(" ");
-}
-
/**
* Builds the terminal-UI display options for `eve dev`. Tools default to
* `auto-collapsed`, reasoning to `full`, and stderr logs are visible so
@@ -535,13 +496,16 @@ function createCliProgram(logger: CliLogger, runtime: CliRuntimeOverrides): Comm
report,
);
const display = resolveTuiDisplayOptions(options);
- const title = resolveTuiTitle({ name: options.name, remoteServerUrl, appRoot });
+ const target: DevelopmentTuiTarget =
+ remoteServerUrl === undefined
+ ? { kind: "local", serverUrl, workspaceRoot: appRoot }
+ : { kind: "remote", serverUrl, workspaceRoot: appRoot };
+ const title = resolveTuiTitle({ name: options.name, target });
if (title !== undefined) display.name = title;
const tuiInput: RunDevelopmentTuiInput = {
- appRoot: remoteServerUrl === undefined ? appRoot : undefined,
+ target,
initialInput: options.input,
onBootProgress: report,
- serverUrl,
...display,
};
await runDevelopmentTui(tuiInput);
@@ -653,7 +617,7 @@ function createCliProgram(logger: CliLogger, runtime: CliRuntimeOverrides): Comm
"[evalIds...]",
"Eval ids (or directory prefixes) to run (all discovered evals when omitted)",
)
- .option("--url <url>", "Remote agent URL (skip local host startup)")
+ .option("--url <url>", "Remote agent URL (skip local host startup)", parseDevelopmentServerUrl)
.option("--tag <tag...>", "Run only evals carrying a tag")
.option("--strict", "Fail the exit code when any score falls below its threshold")
.option("--list", "Print discovered evals without running them")
diff --git a/packages/eve/src/client/client.integration.test.ts b/packages/eve/src/client/client.integration.test.ts
new file mode 100644
index 000000000..0fae9f54e
--- /dev/null
+++ b/packages/eve/src/client/client.integration.test.ts
@@ -0,0 +1,43 @@
+import { createServer, type Server } from "node:http";
+
+import { describe, expect, it } from "vitest";
+
+import { Client } from "./client.js";
+
+async function listen(server: Server): Promise<string> {
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ const address = server.address();
+ if (address === null || typeof address === "string") throw new Error("Expected a TCP address.");
+ return `http://127.0.0.1:${address.port}`;
+}
+
+describe("Client redirect policy", () => {
+ it("does not follow a credential-bearing redirect to another origin", async () => {
+ let redirectedRequests = 0;
+ const destination = createServer((_request, response) => {
+ redirectedRequests += 1;
+ response.end();
+ });
+ const destinationUrl = await listen(destination);
+ const source = createServer((_request, response) => {
+ response.writeHead(307, { location: `${destinationUrl}/capture` });
+ response.end();
+ });
+ const sourceUrl = await listen(source);
+
+ try {
+ const client = new Client({
+ host: sourceUrl,
+ auth: { bearer: "secret" },
+ redirect: "manual",
+ });
+ await expect(client.health()).rejects.toMatchObject({ status: 307 });
+ expect(redirectedRequests).toBe(0);
+ } finally {
+ await Promise.all([
+ new Promise<void>((resolve) => source.close(() => resolve())),
+ new Promise<void>((resolve) => destination.close(() => resolve())),
+ ]);
+ }
+ });
+});
diff --git a/packages/eve/src/client/client.test.ts b/packages/eve/src/client/client.test.ts
new file mode 100644
index 000000000..e7441ae33
--- /dev/null
+++ b/packages/eve/src/client/client.test.ts
@@ -0,0 +1,34 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { Client } from "#client/client.js";
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe("Client request policy", () => {
+ it("enforces its redirect policy for info, health, raw fetch, and sessions", async () => {
+ const fetchMock = vi
+ .spyOn(globalThis, "fetch")
+ .mockResolvedValueOnce(Response.json({ agent: {} }))
+ .mockResolvedValueOnce(Response.json({ ok: true, status: "ready", workflowId: "wf" }))
+ .mockResolvedValueOnce(new Response(null, { status: 204 }))
+ .mockResolvedValueOnce(
+ Response.json({ continuationToken: "eve:test", sessionId: "session_1" }, { status: 202 }),
+ )
+ .mockResolvedValueOnce(
+ new Response(`${JSON.stringify({ data: {}, type: "session.completed" })}\n`),
+ );
+ const client = new Client({ host: "https://eve.test", redirect: "manual" });
+
+ await client.info();
+ await client.health();
+ await client.fetch("/custom", { redirect: "follow" });
+ await (await client.session().send("hello")).result();
+
+ expect(fetchMock.mock.calls).toHaveLength(5);
+ for (const [, init] of fetchMock.mock.calls) {
+ expect(init?.redirect).toBe("manual");
+ }
+ });
+});
diff --git a/packages/eve/src/client/client.ts b/packages/eve/src/client/client.ts
index 18978199c..96668c782 100644
--- a/packages/eve/src/client/client.ts
+++ b/packages/eve/src/client/client.ts
@@ -7,6 +7,7 @@ import type {
AgentInfoResult,
ClientAuth,
ClientOptions,
+ ClientRedirectPolicy,
HeadersValue,
HealthResult,
SessionState,
@@ -26,6 +27,7 @@ export class Client {
readonly #host: string;
readonly #maxReconnectAttempts: number;
readonly #preserveCompletedSessions: boolean;
+ readonly #redirect: ClientRedirectPolicy | undefined;
constructor(options: ClientOptions) {
this.#host = options.host;
@@ -33,6 +35,7 @@ export class Client {
this.#headers = options.headers;
this.#maxReconnectAttempts = options.maxReconnectAttempts ?? 3;
this.#preserveCompletedSessions = options.preserveCompletedSessions ?? false;
+ this.#redirect = options.redirect;
}
/**
@@ -43,7 +46,7 @@ export class Client {
async health(): Promise<HealthResult> {
const url = createClientUrl(this.#host, EVE_HEALTH_ROUTE_PATH);
const headers = await this.#resolveHeaders();
- const response = await fetch(url, { headers });
+ const response = await fetch(url, withRedirectPolicy({ headers }, this.#redirect));
if (!response.ok) {
const body = await response.text();
@@ -65,7 +68,7 @@ export class Client {
async info(): Promise<AgentInfoResult> {
const url = createClientUrl(this.#host, EVE_INFO_ROUTE_PATH);
const headers = await this.#resolveHeaders();
- const response = await fetch(url, { headers });
+ const response = await fetch(url, withRedirectPolicy({ headers }, this.#redirect));
if (!response.ok) {
const body = await response.text();
@@ -85,7 +88,7 @@ export class Client {
async fetch(path: string, init: RequestInit = {}): Promise<Response> {
const url = createClientUrl(this.#host, path);
const headers = await this.#resolveHeaders(headersInitToRecord(init.headers));
- return await fetch(url, { ...init, headers });
+ return await fetch(url, withRedirectPolicy({ ...init, headers }, this.#redirect));
}
/**
@@ -112,6 +115,7 @@ export class Client {
host: this.#host,
maxReconnectAttempts: this.#maxReconnectAttempts,
preserveCompletedSessions: this.#preserveCompletedSessions,
+ redirect: this.#redirect,
resolveHeaders: (perRequest) => this.#resolveHeaders(perRequest),
},
resolved,
@@ -194,6 +198,13 @@ function headersInitToRecord(
return Object.fromEntries(new Headers(headers).entries());
}
+function withRedirectPolicy(
+ init: RequestInit,
+ redirect: ClientRedirectPolicy | undefined,
+): RequestInit {
+ return redirect === undefined ? init : { ...init, redirect };
+}
+
/**
* Encodes a username:password pair as a base64 Basic auth credential.
* Uses `TextEncoder` for correct UTF-8 handling across all runtimes.
diff --git a/packages/eve/src/client/index.ts b/packages/eve/src/client/index.ts
index 24744f10d..7e74162f8 100644
--- a/packages/eve/src/client/index.ts
+++ b/packages/eve/src/client/index.ts
@@ -43,6 +43,7 @@ export type {
AgentInfoTools,
ClientAuth,
ClientOptions,
+ ClientRedirectPolicy,
HeadersValue,
HealthResult,
MessageResult,
diff --git a/packages/eve/src/client/open-stream.ts b/packages/eve/src/client/open-stream.ts
index c3b4317d5..bc413254d 100644
--- a/packages/eve/src/client/open-stream.ts
+++ b/packages/eve/src/client/open-stream.ts
@@ -2,6 +2,7 @@ import type { HandleMessageStreamEvent } from "#protocol/message.js";
import { createEveMessageStreamRoutePath } from "#protocol/routes.js";
import { ClientError } from "#client/client-error.js";
import { isStreamDisconnectError, readNdjsonStream } from "#client/ndjson.js";
+import type { ClientRedirectPolicy } from "#client/types.js";
import { createClientUrl } from "#client/url.js";
const STREAM_OPEN_RETRY_ATTEMPTS = 12;
@@ -15,6 +16,7 @@ interface OpenStreamInput {
readonly host: string;
readonly maxReconnectAttempts: number;
readonly resolveHeaders: () => Promise<Headers>;
+ readonly redirect?: ClientRedirectPolicy;
readonly sessionId: string;
readonly signal?: AbortSignal;
readonly startIndex: number;
@@ -79,6 +81,7 @@ export async function openStreamBody(
const headers = await input.resolveHeaders();
const response = await fetch(url, {
headers,
+ redirect: input.redirect,
signal: input.signal ?? null,
});
diff --git a/packages/eve/src/client/session.ts b/packages/eve/src/client/session.ts
index 20d9e77a4..d839259ce 100644
--- a/packages/eve/src/client/session.ts
+++ b/packages/eve/src/client/session.ts
@@ -11,7 +11,13 @@ import { openStreamBody, openStreamIterable } from "#client/open-stream.js";
import { normalizeOutputSchemaForRequest } from "#client/output-schema.js";
import { advanceSession } from "#client/session-utils.js";
import { createClientUrl } from "#client/url.js";
-import type { SendTurnInput, SendTurnPayload, SessionState, StreamOptions } from "#client/types.js";
+import type {
+ ClientRedirectPolicy,
+ SendTurnInput,
+ SendTurnPayload,
+ SessionState,
+ StreamOptions,
+} from "#client/types.js";
const DELIVER_RETRY_ATTEMPTS = 10;
const DELIVER_RETRY_DELAY_MS = 200;
@@ -24,6 +30,7 @@ interface SessionContext {
readonly host: string;
readonly maxReconnectAttempts: number;
readonly preserveCompletedSessions: boolean;
+ readonly redirect?: ClientRedirectPolicy;
resolveHeaders(perRequest?: Readonly<Record<string, string>>): Promise<Headers>;
}
@@ -121,6 +128,7 @@ export class ClientSession {
body: JSON.stringify(body),
headers,
mustDeliver: (input.inputResponses?.length ?? 0) > 0,
+ redirect: this.#context.redirect,
signal: input.signal,
url,
});
@@ -221,6 +229,7 @@ export class ClientSession {
return await openStreamBody({
host: this.#context.host,
resolveHeaders: () => this.#context.resolveHeaders(headers),
+ redirect: this.#context.redirect,
sessionId,
signal,
startIndex,
@@ -240,6 +249,7 @@ export class ClientSession {
host: this.#context.host,
maxReconnectAttempts: this.#context.maxReconnectAttempts,
resolveHeaders: () => this.#context.resolveHeaders(),
+ redirect: this.#context.redirect,
sessionId,
signal: options?.signal,
startIndex: streamIndex,
@@ -263,6 +273,7 @@ async function postTurnWithRetry(input: {
readonly body: string;
readonly headers: Headers;
readonly mustDeliver: boolean;
+ readonly redirect?: ClientRedirectPolicy;
readonly signal?: AbortSignal;
readonly url: string;
}): Promise<Response> {
@@ -275,6 +286,7 @@ async function postTurnWithRetry(input: {
body: input.body,
headers: input.headers,
method: "POST",
+ redirect: input.redirect,
signal: input.signal ?? null,
});
diff --git a/packages/eve/src/client/types.ts b/packages/eve/src/client/types.ts
index 8acfb99f6..114a7fdbb 100644
--- a/packages/eve/src/client/types.ts
+++ b/packages/eve/src/client/types.ts
@@ -30,6 +30,9 @@ export type ClientAuth =
| { readonly basic: { readonly username: string; readonly password: TokenValue } }
| { readonly bearer: TokenValue };
+/** Redirect modes supported by the configured fetch implementation. */
+export type ClientRedirectPolicy = NonNullable<RequestInit["redirect"]>;
+
/**
* Configuration for creating a new {@link Client}.
*/
@@ -52,6 +55,14 @@ export interface ClientOptions {
*/
readonly headers?: HeadersValue;
+ /**
+ * Redirect policy for every request, including streams. Overrides a
+ * per-request `RequestInit.redirect`. Credential-bearing clients should use
+ * `"manual"` or `"error"` so custom auth headers can't follow a cross-origin
+ * redirect.
+ */
+ readonly redirect?: ClientRedirectPolicy;
+
/**
* Maximum number of stream reconnection attempts per message turn.
*
diff --git a/packages/eve/src/evals/cli/eval-client.test.ts b/packages/eve/src/evals/cli/eval-client.test.ts
index f19322847..b391add03 100644
--- a/packages/eve/src/evals/cli/eval-client.test.ts
+++ b/packages/eve/src/evals/cli/eval-client.test.ts
@@ -1,11 +1,19 @@
import { afterEach, describe, expect, it, vi } from "vitest";
-import { resolveDevelopmentOidcToken } from "#services/dev-client/request-headers.js";
+import { resolveTestVercelTarget } from "#internal/testing/verified-vercel-target.js";
+import type { DevelopmentOidcTokenResolution } from "#services/dev-client/request-headers.js";
-import { resolveEvalClientOptions } from "./eval-client.js";
+import { createEvalClient, resolveEvalClientOptions } from "./eval-client.js";
+
+const VERIFIED_TARGET = await resolveTestVercelTarget({
+ host: "example.vercel.app",
+ projectId: "prj_example",
+ projectName: "example",
+});
describe("resolveEvalClientOptions", () => {
afterEach(() => {
+ vi.restoreAllMocks();
vi.unstubAllEnvs();
});
@@ -14,17 +22,15 @@ describe("resolveEvalClientOptions", () => {
expect(options).toEqual({ host: "http://127.0.0.1:3000" });
});
- it("resolves dev-client headers and the OIDC bearer for remote targets", () => {
+ it("keeps the synchronous remote options anonymous", () => {
const options = resolveEvalClientOptions({
kind: "remote",
url: "https://example.vercel.app",
});
expect(options.host).toBe("https://example.vercel.app");
expect(options.preserveCompletedSessions).toBe(false);
- // The per-request resolver attaches the trusted OIDC IDP token (Deployment
- // Protection bypass) and any VERCEL_AUTOMATION_BYPASS_SECRET header.
- expect(typeof options.headers).toBe("function");
- expect(options.auth).toEqual({ bearer: resolveDevelopmentOidcToken });
+ expect(options.headers).toBeUndefined();
+ expect(options.auth).toBeUndefined();
});
it("prefers the EVE_EVAL_AUTH_TOKEN static bearer override", () => {
@@ -34,7 +40,8 @@ describe("resolveEvalClientOptions", () => {
url: "https://example.vercel.app",
});
expect(options.auth).toEqual({ bearer: "static-token" });
- expect(typeof options.headers).toBe("function");
+ expect(options.redirect).toBe("manual");
+ expect(options.headers).toBeUndefined();
});
it("ignores a blank EVE_EVAL_AUTH_TOKEN", () => {
@@ -43,6 +50,84 @@ describe("resolveEvalClientOptions", () => {
kind: "remote",
url: "https://example.vercel.app",
});
- expect(options.auth).toEqual({ bearer: resolveDevelopmentOidcToken });
+ expect(options.auth).toBeUndefined();
+ });
+
+ it("resolves ambient OIDC per request after Vercel verifies the exact remote origin", async () => {
+ const fetchMock = vi
+ .spyOn(globalThis, "fetch")
+ .mockResolvedValueOnce(Response.json({ ok: true, status: "ready", workflowId: "wf" }))
+ .mockResolvedValueOnce(Response.json({ ok: true, status: "ready", workflowId: "wf" }));
+ const resolveDevelopmentOidcToken = vi
+ .fn<
+ (input: {
+ readonly ownerId: string;
+ readonly projectId: string;
+ }) => Promise<DevelopmentOidcTokenResolution>
+ >()
+ .mockResolvedValueOnce({ kind: "resolved", token: " first-token " })
+ .mockResolvedValueOnce({ kind: "resolved", token: "second-token" });
+ const client = await createEvalClient(
+ { kind: "remote", url: "https://example.vercel.app" },
+ {
+ workspaceRoot: "/workspace",
+ deps: {
+ resolveVercelDeployment: async () => ({
+ kind: "resolved",
+ target: VERIFIED_TARGET,
+ }),
+ resolveDevelopmentOidcToken,
+ },
+ },
+ );
+
+ expect(resolveDevelopmentOidcToken).not.toHaveBeenCalled();
+ await client.health();
+ await client.health();
+
+ const firstHeaders = new Headers(fetchMock.mock.calls[0]?.[1]?.headers);
+ const secondHeaders = new Headers(fetchMock.mock.calls[1]?.[1]?.headers);
+ expect(firstHeaders.get("authorization")).toBe("Bearer first-token");
+ expect(firstHeaders.get("x-vercel-trusted-oidc-idp-token")).toBe("first-token");
+ expect(secondHeaders.get("authorization")).toBe("Bearer second-token");
+ expect(secondHeaders.get("x-vercel-trusted-oidc-idp-token")).toBe("second-token");
+ expect(resolveDevelopmentOidcToken).toHaveBeenCalledTimes(2);
+ expect(resolveDevelopmentOidcToken).toHaveBeenNthCalledWith(1, {
+ ownerId: "team_test",
+ projectId: "prj_example",
+ });
+ expect(resolveDevelopmentOidcToken).toHaveBeenNthCalledWith(2, {
+ ownerId: "team_test",
+ projectId: "prj_example",
+ });
+ expect(fetchMock.mock.calls[0]?.[1]?.redirect).toBe("manual");
+ expect(fetchMock.mock.calls[1]?.[1]?.redirect).toBe("manual");
+ });
+
+ it("does not resolve or emit ambient OIDC for an unverified remote origin", async () => {
+ const fetchMock = vi
+ .spyOn(globalThis, "fetch")
+ .mockResolvedValue(Response.json({ ok: true, status: "ready", workflowId: "wf" }));
+ const resolveDevelopmentOidcToken = vi.fn(async () => ({
+ kind: "resolved" as const,
+ token: "ambient-token",
+ }));
+ const client = await createEvalClient(
+ { kind: "remote", url: "https://arbitrary.example.com" },
+ {
+ workspaceRoot: "/workspace",
+ deps: {
+ resolveVercelDeployment: async () => ({ kind: "not-found" }),
+ resolveDevelopmentOidcToken,
+ },
+ },
+ );
+
+ await client.health();
+
+ const headers = new Headers(fetchMock.mock.calls[0]?.[1]?.headers);
+ expect(resolveDevelopmentOidcToken).not.toHaveBeenCalled();
+ expect(headers.get("authorization")).toBeNull();
+ expect(headers.get("x-vercel-trusted-oidc-idp-token")).toBeNull();
});
});
diff --git a/packages/eve/src/evals/cli/eval-client.ts b/packages/eve/src/evals/cli/eval-client.ts
index bce98aa00..73d608b0f 100644
--- a/packages/eve/src/evals/cli/eval-client.ts
+++ b/packages/eve/src/evals/cli/eval-client.ts
@@ -1,21 +1,17 @@
import { Client } from "#client/client.js";
import type { ClientOptions } from "#client/types.js";
import { resolveDevelopmentClientOptions } from "#services/dev-client/client-options.js";
+import {
+ resolveVerifiedRemoteDevelopmentClient,
+ type VerifiedRemoteDevelopmentClientDeps,
+} from "#setup/verified-remote-client.js";
import type { EveEvalTargetHandle } from "#evals/types.js";
/**
- * Resolves the {@link ClientOptions} for an eval target.
- *
- * Local targets need no auth. Remote targets connect with the same options
- * as every other development client (`resolveDevelopmentClientOptions`):
- * per-request headers carrying the Vercel OIDC trusted-IDP token (which
- * bypasses Deployment Protection without a per-project secret) plus
- * `x-vercel-protection-bypass` when `VERCEL_AUTOMATION_BYPASS_SECRET` is
- * set, and a bearer resolved from the same OIDC cascade.
- *
- * `EVE_EVAL_AUTH_TOKEN` overrides the bearer with a static token for
- * targets whose auth is not OIDC-based.
+ * Synchronous {@link ClientOptions} for an eval target: local needs no auth,
+ * remote stays anonymous unless `EVE_EVAL_AUTH_TOKEN` sets a static bearer.
+ * Ambient Vercel credentials need the async {@link createEvalClient}.
*/
export function resolveEvalClientOptions(
target: Pick<EveEvalTargetHandle, "kind" | "url">,
@@ -30,16 +26,36 @@ export function resolveEvalClientOptions(
};
const explicitToken = process.env.EVE_EVAL_AUTH_TOKEN?.trim();
if (explicitToken) {
- return { ...options, auth: { bearer: explicitToken } };
+ return { ...options, auth: { bearer: explicitToken }, redirect: "manual" };
}
return options;
}
-/**
- * Creates the eve {@link Client} for an eval target from
- * {@link resolveEvalClientOptions}.
- */
-export function createEvalClient(target: Pick<EveEvalTargetHandle, "kind" | "url">): Client {
- return new Client(resolveEvalClientOptions(target));
+export interface CreateEvalClientOptions {
+ /** Working directory for Vercel lookup and the fallback on-disk project link. */
+ readonly workspaceRoot?: string;
+ /** Test seams for the two authority-resolution boundaries. */
+ readonly deps?: Partial<VerifiedRemoteDevelopmentClientDeps>;
+}
+
+/** Creates one eval client, authorizing ambient Vercel credentials only after origin proof. */
+export async function createEvalClient(
+ target: Pick<EveEvalTargetHandle, "kind" | "url">,
+ options: CreateEvalClientOptions = {},
+): Promise<Client> {
+ const base = resolveEvalClientOptions(target);
+ if (target.kind === "local" || base.auth !== undefined || options.workspaceRoot === undefined) {
+ return new Client(base);
+ }
+
+ const { options: verified } = await resolveVerifiedRemoteDevelopmentClient({
+ serverUrl: target.url,
+ workspaceRoot: options.workspaceRoot,
+ deps: options.deps,
+ });
+ return new Client({
+ ...base,
+ ...verified,
+ });
}
diff --git a/packages/eve/src/evals/cli/eval.ts b/packages/eve/src/evals/cli/eval.ts
index d45eb9399..e84a13045 100644
--- a/packages/eve/src/evals/cli/eval.ts
+++ b/packages/eve/src/evals/cli/eval.ts
@@ -92,30 +92,31 @@ export async function runEvalCommand(
// Resolve target
let server: DevelopmentServerHandle | undefined;
let target: EveEvalTargetHandle;
+ let client: Awaited<ReturnType<typeof createEvalClient>>;
try {
if (options.url) {
- const remoteClient = createEvalClient({ kind: "remote", url: options.url });
+ client = await createEvalClient(
+ { kind: "remote", url: options.url },
+ { workspaceRoot: appRoot },
+ );
target = await resolveEvalTargetHandle({
- client: remoteClient,
+ client,
expectedAgentName: await readExpectedAgentName(appRoot),
kind: "remote",
url: options.url,
});
} else {
server = await startDevelopmentServer(appRoot, { host: "127.0.0.1", port: 0 });
- const localClient = createEvalClient({ kind: "local", url: server.url });
+ client = await createEvalClient({ kind: "local", url: server.url });
target = await resolveEvalTargetHandle({
- client: localClient,
+ client,
expectedAgentName: await readExpectedAgentName(appRoot),
kind: "local",
url: server.url,
});
}
- // Create client with auth using the same patterns as the dev-client
- const client = createEvalClient(target);
-
const reporters: EvalReporter[] = options.json === true ? [] : [new ConsoleReporter()];
if (options.junit !== undefined) {
reporters.push(JUnit({ filePath: options.junit }));
diff --git a/packages/eve/src/internal/testing/verified-vercel-target.ts b/packages/eve/src/internal/testing/verified-vercel-target.ts
new file mode 100644
index 000000000..22c4726a0
--- /dev/null
+++ b/packages/eve/src/internal/testing/verified-vercel-target.ts
@@ -0,0 +1,34 @@
+import { resolveVercelDeployment, type VerifiedVercelTarget } from "#setup/vercel-deployment.js";
+
+/** Builds a branded target through the production parser for unit tests. */
+export async function resolveTestVercelTarget(input: {
+ readonly host: string;
+ readonly projectId?: string;
+ readonly projectName?: string;
+ readonly environment?: "preview" | "production";
+}): Promise<VerifiedVercelTarget> {
+ const environment = input.environment ?? "preview";
+ const result = await resolveVercelDeployment({
+ workspaceRoot: "/test-workspace",
+ host: input.host,
+ source: {
+ orgId: "team_test",
+ projectId: input.projectId ?? "prj_test",
+ },
+ deps: {
+ captureVercel: async () => ({
+ ok: true,
+ stdout: JSON.stringify({
+ projectId: input.projectId ?? "prj_test",
+ name: input.projectName ?? "test-project",
+ target: environment,
+ customEnvironment: null,
+ }),
+ }),
+ },
+ });
+ if (result.kind !== "resolved") {
+ throw new Error(`Expected a verified Vercel target, received ${result.kind}.`);
+ }
+ return result.target;
+}
diff --git a/packages/eve/src/services/dev-client.ts b/packages/eve/src/services/dev-client.ts
index be7aa7edd..fc891d7b4 100644
--- a/packages/eve/src/services/dev-client.ts
+++ b/packages/eve/src/services/dev-client.ts
@@ -1,7 +1,7 @@
import type { UserContent } from "ai";
import type { ClientSession } from "#client/session.js";
import type { InputResponse } from "#runtime/input/types.js";
-import { isLocalDevelopmentServerUrl } from "#services/dev-client/request-headers.js";
+import { isLocalDevelopmentServerUrl } from "#services/dev-client/local-host.js";
import {
readDevelopmentRuntimeArtifactsRevision,
rebuildDevelopmentRuntimeArtifacts,
diff --git a/packages/eve/src/services/dev-client/client-options.test.ts b/packages/eve/src/services/dev-client/client-options.test.ts
index 7ed2c2f51..85d8b520d 100644
--- a/packages/eve/src/services/dev-client/client-options.test.ts
+++ b/packages/eve/src/services/dev-client/client-options.test.ts
@@ -1,14 +1,22 @@
import { describe, expect, it } from "vitest";
-import { resolveDevelopmentOidcToken } from "./request-headers.js";
-
-import { resolveDevelopmentClientOptions } from "./client-options.js";
+import {
+ resolveDevelopmentClientOptions,
+ resolveRemoteDevelopmentClientOptions,
+} from "./client-options.js";
+import { createDevelopmentCredentialGate } from "./credential-gate.js";
+import { isLocalDevelopmentServerUrl } from "./local-host.js";
describe("resolveDevelopmentClientOptions", () => {
- it("targets the given host and resolves headers lazily", () => {
+ it("targets the given host without inferring credentials from locality", () => {
const options = resolveDevelopmentClientOptions("http://localhost:3000");
expect(options.host).toBe("http://localhost:3000");
- expect(typeof options.headers).toBe("function");
+ expect(options.auth).toBeUndefined();
+ expect(options.headers).toBeUndefined();
+
+ const remote = resolveDevelopmentClientOptions("https://arbitrary.example.com");
+ expect(remote.auth).toBeUndefined();
+ expect(remote.headers).toBeUndefined();
});
it("does not preserve completed sessions across dev prompts", () => {
@@ -19,12 +27,23 @@ describe("resolveDevelopmentClientOptions", () => {
it("skips the OIDC bearer for local hosts", () => {
for (const url of ["http://localhost:3000", "http://127.0.0.1:3000", "http://[::1]:3000"]) {
+ expect(isLocalDevelopmentServerUrl(url)).toBe(true);
expect(resolveDevelopmentClientOptions(url).auth).toBeUndefined();
}
});
- it("attaches the dev OIDC bearer for remote hosts", () => {
- const options = resolveDevelopmentClientOptions("https://example.com");
- expect(options.auth).toEqual({ bearer: resolveDevelopmentOidcToken });
+ it("binds an authorized credential gate to a non-redirecting client", () => {
+ const credentials = createDevelopmentCredentialGate("https://verified.example.com");
+
+ expect(
+ resolveRemoteDevelopmentClientOptions({
+ credentials,
+ serverUrl: "https://verified.example.com",
+ }),
+ ).toEqual({
+ headers: credentials.resolveHeaders,
+ host: "https://verified.example.com",
+ redirect: "manual",
+ });
});
});
diff --git a/packages/eve/src/services/dev-client/client-options.ts b/packages/eve/src/services/dev-client/client-options.ts
index 59ae9aba5..f3008c585 100644
--- a/packages/eve/src/services/dev-client/client-options.ts
+++ b/packages/eve/src/services/dev-client/client-options.ts
@@ -1,26 +1,30 @@
import type { ClientOptions } from "#client/index.js";
-import {
- isLocalDevelopmentServerUrl,
- resolveDevelopmentClientHeaders,
- resolveDevelopmentOidcToken,
-} from "./request-headers.js";
+import type { DevelopmentCredentialGate } from "./credential-gate.js";
/**
- * Builds the {@link ClientOptions} every development client connects with:
- * local hosts skip the Vercel OIDC bearer (the framework's `localDev()`
- * channel auth accepts unauthenticated calls); remote hosts attach it
- * alongside any protection-bypass headers resolved per request.
+ * Builds anonymous {@link ClientOptions} for a development target. Locality is
+ * not an authorization decision, so remote URLs receive no ambient Vercel
+ * credentials through this default path.
*/
export function resolveDevelopmentClientOptions(serverUrl: string): ClientOptions {
- const base = {
- headers: () => resolveDevelopmentClientHeaders({ serverUrl }),
- host: serverUrl,
- };
+ return { host: serverUrl };
+}
- if (isLocalDevelopmentServerUrl(serverUrl)) {
- return base;
+/** Builds non-redirecting client options backed by one verified credential gate. */
+export function resolveRemoteDevelopmentClientOptions(input: {
+ readonly credentials: DevelopmentCredentialGate;
+ readonly serverUrl: string;
+}): ClientOptions {
+ const serverOrigin = new URL(input.serverUrl).origin;
+ if (input.credentials.serverOrigin !== serverOrigin) {
+ throw new Error(
+ `Credential gate origin ${input.credentials.serverOrigin} does not match client origin ${serverOrigin}.`,
+ );
}
-
- return { ...base, auth: { bearer: resolveDevelopmentOidcToken } };
+ return {
+ headers: input.credentials.resolveHeaders,
+ host: input.serverUrl,
+ redirect: "manual",
+ };
}
diff --git a/packages/eve/src/services/dev-client/credential-gate.test.ts b/packages/eve/src/services/dev-client/credential-gate.test.ts
new file mode 100644
index 000000000..c8f3d5f61
--- /dev/null
+++ b/packages/eve/src/services/dev-client/credential-gate.test.ts
@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { resolveTestVercelTarget } from "#internal/testing/verified-vercel-target.js";
+
+import { createDevelopmentCredentialGate } from "./credential-gate.js";
+import type { DevelopmentOidcTokenResolution } from "./request-headers.js";
+
+afterEach(() => {
+ vi.unstubAllEnvs();
+});
+
+async function verifiedTarget(host: string) {
+ return await resolveTestVercelTarget({
+ host,
+ projectId: "prj_verified",
+ projectName: "verified-project",
+ });
+}
+
+function resolvedToken(token: string): DevelopmentOidcTokenResolution {
+ return { kind: "resolved", token };
+}
+
+describe("createDevelopmentCredentialGate", () => {
+ it("stays anonymous until an authoritative target is installed", async () => {
+ vi.stubEnv("VERCEL_AUTOMATION_BYPASS_SECRET", "ambient-bypass");
+ const gate = createDevelopmentCredentialGate("https://verified.example.com/path");
+
+ await expect(gate.resolveHeaders()).resolves.toEqual({});
+
+ const target = await verifiedTarget("verified.example.com");
+ gate.authorize({ target, resolveToken: async () => resolvedToken(" oidc-token ") });
+
+ await expect(gate.resolveHeaders()).resolves.toEqual({
+ authorization: "Bearer oidc-token",
+ "x-vercel-protection-bypass": "ambient-bypass",
+ "x-vercel-trusted-oidc-idp-token": "oidc-token",
+ });
+ });
+
+ it("rejects authority for a different origin without replacing current authority", async () => {
+ const gate = createDevelopmentCredentialGate("https://verified.example.com");
+ const target = await verifiedTarget("verified.example.com");
+ const otherTarget = await verifiedTarget("other.example.com");
+ gate.authorize({ target, resolveToken: async () => resolvedToken("first-token") });
+
+ expect(() =>
+ gate.authorize({
+ target: otherTarget,
+ resolveToken: async () => resolvedToken("other-token"),
+ }),
+ ).toThrow("does not match");
+ await expect(gate.resolveHeaders()).resolves.toMatchObject({
+ authorization: "Bearer first-token",
+ });
+ });
+
+ it("permits an automation bypass only after origin verification", async () => {
+ vi.stubEnv("VERCEL_AUTOMATION_BYPASS_SECRET", "verified-bypass");
+ const gate = createDevelopmentCredentialGate("https://verified.example.com");
+ await expect(gate.resolveHeaders()).resolves.toEqual({});
+ const failure = { kind: "invalid-claims", invalidClaims: ["project_id"] } as const;
+
+ gate.authorize({
+ target: await verifiedTarget("verified.example.com"),
+ resolveToken: async () => failure,
+ });
+
+ await expect(gate.resolveHeaders()).resolves.toEqual({
+ "x-vercel-protection-bypass": "verified-bypass",
+ });
+ expect(gate.lastTokenFailure()).toEqual(failure);
+ });
+
+ it("resolves the current token for every request", async () => {
+ const gate = createDevelopmentCredentialGate("https://verified.example.com");
+ const resolveToken = vi
+ .fn<() => Promise<DevelopmentOidcTokenResolution>>()
+ .mockResolvedValueOnce(resolvedToken(" first-token "))
+ .mockResolvedValueOnce(resolvedToken("second-token"));
+ gate.authorize({
+ target: await verifiedTarget("verified.example.com"),
+ resolveToken,
+ });
+
+ await expect(gate.resolveHeaders()).resolves.toMatchObject({
+ authorization: "Bearer first-token",
+ });
+ await expect(gate.resolveHeaders()).resolves.toMatchObject({
+ authorization: "Bearer second-token",
+ });
+ expect(resolveToken).toHaveBeenCalledTimes(2);
+ });
+
+ it("clears a reported failure after a later token refresh succeeds", async () => {
+ const failure = { kind: "resolution-failed", message: "refresh failed" } as const;
+ const gate = createDevelopmentCredentialGate("https://verified.example.com");
+ const resolveToken = vi
+ .fn<() => Promise<DevelopmentOidcTokenResolution>>()
+ .mockResolvedValueOnce(failure)
+ .mockResolvedValueOnce(resolvedToken("fresh-token"));
+ gate.authorize({
+ target: await verifiedTarget("verified.example.com"),
+ resolveToken,
+ });
+
+ await expect(gate.resolveHeaders()).resolves.toEqual({});
+ expect(gate.lastTokenFailure()).toEqual(failure);
+ await expect(gate.resolveHeaders()).resolves.toMatchObject({
+ authorization: "Bearer fresh-token",
+ });
+ expect(gate.lastTokenFailure()).toBeUndefined();
+ });
+});
diff --git a/packages/eve/src/services/dev-client/credential-gate.ts b/packages/eve/src/services/dev-client/credential-gate.ts
new file mode 100644
index 000000000..6c2e40cb6
--- /dev/null
+++ b/packages/eve/src/services/dev-client/credential-gate.ts
@@ -0,0 +1,73 @@
+import type { VerifiedVercelTarget } from "#setup/vercel-deployment.js";
+
+import {
+ type DevelopmentOidcTokenFailure,
+ type DevelopmentOidcTokenResolution,
+ VERCEL_PROTECTION_BYPASS_HEADER,
+ VERCEL_TRUSTED_OIDC_IDP_TOKEN_HEADER,
+} from "./request-headers.js";
+
+export interface DevelopmentCredentialGrant {
+ readonly target: VerifiedVercelTarget;
+ readonly resolveToken: () => Promise<DevelopmentOidcTokenResolution>;
+}
+
+/** Per-client authority for resolving and emitting remote Vercel credentials. */
+export interface DevelopmentCredentialGate {
+ /** The origin this gate is permanently bound to. */
+ readonly serverOrigin: string;
+ /** Installs authority after Vercel verifies the exact origin. */
+ authorize(grant: DevelopmentCredentialGrant): void;
+ /** Resolves headers for one request. */
+ resolveHeaders(): Promise<Readonly<Record<string, string>>>;
+ /** Token failure from the most recent {@link resolveHeaders}, or `undefined` if it resolved one. */
+ lastTokenFailure(): DevelopmentOidcTokenFailure | undefined;
+}
+
+type DevelopmentCredentialGateState =
+ | { readonly kind: "anonymous" }
+ | {
+ readonly kind: "vercel";
+ readonly resolveToken: () => Promise<DevelopmentOidcTokenResolution>;
+ };
+
+/** Creates an anonymous credential gate bound to one client origin. */
+export function createDevelopmentCredentialGate(serverUrl: string): DevelopmentCredentialGate {
+ const serverOrigin = new URL(serverUrl).origin;
+ let state: DevelopmentCredentialGateState = { kind: "anonymous" };
+ let tokenFailure: DevelopmentOidcTokenFailure | undefined;
+
+ const authorize = (grant: DevelopmentCredentialGrant): void => {
+ if (grant.target.origin !== serverOrigin) {
+ throw new Error(
+ `Verified Vercel origin ${grant.target.origin} does not match client origin ${serverOrigin}.`,
+ );
+ }
+ state = {
+ kind: "vercel",
+ resolveToken: grant.resolveToken,
+ } as const;
+ };
+
+ const resolveHeaders = async (): Promise<Readonly<Record<string, string>>> => {
+ const authorized = state;
+ if (authorized.kind === "anonymous") return {};
+
+ const headers: Record<string, string> = {};
+ const bypassSecret = process.env.VERCEL_AUTOMATION_BYPASS_SECRET?.trim();
+ if (bypassSecret) headers[VERCEL_PROTECTION_BYPASS_HEADER] = bypassSecret;
+
+ const resolution = await authorized.resolveToken();
+ tokenFailure = resolution.kind === "resolved" ? undefined : resolution;
+ if (resolution.kind !== "resolved") return headers;
+
+ const token = resolution.token.trim();
+ if (token.length > 0) {
+ headers.authorization = `Bearer ${token}`;
+ headers[VERCEL_TRUSTED_OIDC_IDP_TOKEN_HEADER] = token;
+ }
+ return headers;
+ };
+
+ return { authorize, resolveHeaders, serverOrigin, lastTokenFailure: () => tokenFailure };
+}
diff --git a/packages/eve/src/services/dev-client/local-host.ts b/packages/eve/src/services/dev-client/local-host.ts
new file mode 100644
index 000000000..11807e4a2
--- /dev/null
+++ b/packages/eve/src/services/dev-client/local-host.ts
@@ -0,0 +1,21 @@
+const LOCAL_HOSTNAMES: ReadonlySet<string> = new Set([
+ "localhost",
+ "127.0.0.1",
+ "0.0.0.0",
+ "::1",
+ "[::1]",
+]);
+
+/** Returns whether `url` targets a recognized local development host. */
+export function isLocalEveServerUrl(url: URL): boolean {
+ return LOCAL_HOSTNAMES.has(url.hostname);
+}
+
+/** Whether `serverUrl` is a local dev host. Invalid URLs count as remote. */
+export function isLocalDevelopmentServerUrl(serverUrl: string): boolean {
+ try {
+ return isLocalEveServerUrl(new URL(serverUrl));
+ } catch {
+ return false;
+ }
+}
diff --git a/packages/eve/src/services/dev-client/request-headers.test.ts b/packages/eve/src/services/dev-client/request-headers.test.ts
new file mode 100644
index 000000000..b651e1526
--- /dev/null
+++ b/packages/eve/src/services/dev-client/request-headers.test.ts
@@ -0,0 +1,86 @@
+import { getVercelOidcToken } from "#compiled/@vercel/oidc/index.js";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { resolveDevelopmentOidcToken } from "./request-headers.js";
+
+vi.mock("#compiled/@vercel/oidc/index.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("#compiled/@vercel/oidc/index.js")>()),
+ getVercelOidcToken: vi.fn(),
+}));
+
+const target = { ownerId: "team_expected", projectId: "prj_expected" } as const;
+
+function token(claims: Record<string, string>): string {
+ return `header.${Buffer.from(JSON.stringify(claims)).toString("base64url")}.signature`;
+}
+
+afterEach(() => {
+ vi.mocked(getVercelOidcToken).mockReset();
+});
+
+describe("resolveDevelopmentOidcToken", () => {
+ it("returns a token whose owner and project match the verified target", async () => {
+ const expected = token({ owner_id: target.ownerId, project_id: target.projectId });
+ vi.mocked(getVercelOidcToken).mockResolvedValue(expected);
+
+ await expect(resolveDevelopmentOidcToken(target)).resolves.toEqual({
+ kind: "resolved",
+ token: expected,
+ });
+ expect(getVercelOidcToken).toHaveBeenCalledWith({
+ team: target.ownerId,
+ project: target.projectId,
+ });
+ });
+
+ it("reports a token minted for a different project", async () => {
+ vi.mocked(getVercelOidcToken).mockResolvedValue(
+ token({ owner_id: target.ownerId, project_id: "prj_other" }),
+ );
+
+ await expect(resolveDevelopmentOidcToken(target)).resolves.toEqual({
+ kind: "target-mismatch",
+ mismatchedClaims: ["project_id"],
+ });
+ });
+
+ it("reports claims that do not match the Vercel OIDC schema", async () => {
+ vi.mocked(getVercelOidcToken).mockResolvedValue(token({ subject: "user" }));
+
+ await expect(resolveDevelopmentOidcToken(target)).resolves.toMatchObject({
+ kind: "invalid-claims",
+ invalidClaims: expect.arrayContaining([
+ expect.stringContaining("owner_id"),
+ expect.stringContaining("project_id"),
+ ]),
+ });
+ });
+
+ it("reports a token without a JWT payload", async () => {
+ vi.mocked(getVercelOidcToken).mockResolvedValue("not-a-jwt");
+
+ await expect(resolveDevelopmentOidcToken(target)).resolves.toEqual({
+ kind: "malformed-token",
+ reason: "missing-payload",
+ });
+ });
+
+ it("reports a JWT payload that is not valid JSON", async () => {
+ const payload = Buffer.from("not json").toString("base64url");
+ vi.mocked(getVercelOidcToken).mockResolvedValue(`header.${payload}.signature`);
+
+ await expect(resolveDevelopmentOidcToken(target)).resolves.toEqual({
+ kind: "malformed-token",
+ reason: "invalid-json-payload",
+ });
+ });
+
+ it("reports why token resolution failed", async () => {
+ vi.mocked(getVercelOidcToken).mockRejectedValue(new Error("refresh failed"));
+
+ await expect(resolveDevelopmentOidcToken(target)).resolves.toEqual({
+ kind: "resolution-failed",
+ message: "refresh failed",
+ });
+ });
+});
diff --git a/packages/eve/src/services/dev-client/request-headers.ts b/packages/eve/src/services/dev-client/request-headers.ts
index 15e88433f..fa70245c0 100644
--- a/packages/eve/src/services/dev-client/request-headers.ts
+++ b/packages/eve/src/services/dev-client/request-headers.ts
@@ -1,61 +1,91 @@
import { getVercelOidcToken } from "#compiled/@vercel/oidc/index.js";
-import { EVE_ROUTE_PREFIX } from "#protocol/routes.js";
+import { toErrorMessage } from "#shared/errors.js";
+import { z } from "zod";
+
+const VercelOidcClaimsSchema = z.object({
+ owner_id: z.string().min(1),
+ project_id: z.string().min(1),
+});
+
+/** Vercel owner and project expected to have minted an OIDC token. */
+export interface DevelopmentOidcTarget {
+ readonly ownerId: string;
+ readonly projectId: string;
+}
-const EVE_ROUTE_PREFIX_WITH_SEPARATOR = `${EVE_ROUTE_PREFIX}/`;
+type VercelOidcClaimName = keyof z.infer<typeof VercelOidcClaimsSchema>;
+type InvalidVercelOidcClaim = VercelOidcClaimName | "claims";
-/**
- * Hostnames the dev client treats as "local" for auth purposes. When the
- * target server is one of these, the dev client skips the Vercel OIDC
- * bearer entirely — the framework's default channel auth chain is
- * `[localDev(), vercelOidc()]`, and `localDev()` accepts off Vercel
- * infrastructure, so attaching a bearer would be wasted work and noise
- * in the request inspector.
- */
-const LOCAL_HOSTNAMES: ReadonlySet<string> = new Set([
- "localhost",
- "127.0.0.1",
- "0.0.0.0",
- "::1",
- "[::1]",
-]);
+/** Why eve could not use a locally resolved Vercel OIDC token. */
+export type DevelopmentOidcTokenFailure =
+ | { readonly kind: "resolution-failed"; readonly message: string }
+ | {
+ readonly kind: "malformed-token";
+ readonly reason: "missing-payload" | "invalid-json-payload";
+ }
+ | {
+ readonly kind: "invalid-claims";
+ readonly invalidClaims: readonly InvalidVercelOidcClaim[];
+ }
+ | {
+ readonly kind: "target-mismatch";
+ readonly mismatchedClaims: readonly VercelOidcClaimName[];
+ };
-function isLocalEveServerUrl(url: URL): boolean {
- return LOCAL_HOSTNAMES.has(url.hostname);
-}
+/** Result of resolving and checking a Vercel OIDC token for one target. */
+export type DevelopmentOidcTokenResolution =
+ | { readonly kind: "resolved"; readonly token: string }
+ | DevelopmentOidcTokenFailure;
/**
- * Returns whether `serverUrl` targets one of the recognized local
- * development hostnames. Invalid URLs return `false` so callers can
- * always proceed as if the target is remote.
+ * Resolves and claim-checks the local Vercel OIDC token for a verified target.
+ * It does not authorize a destination; callers must verify the exact origin
+ * first and install the result in a `DevelopmentCredentialGate`.
*/
-export function isLocalDevelopmentServerUrl(serverUrl: string): boolean {
+export async function resolveDevelopmentOidcToken(
+ input: DevelopmentOidcTarget,
+): Promise<DevelopmentOidcTokenResolution> {
try {
- return isLocalEveServerUrl(new URL(serverUrl));
- } catch {
- return false;
+ const token = (
+ await getVercelOidcToken({ team: input.ownerId, project: input.projectId })
+ ).trim();
+ return validateDevelopmentOidcToken(token, input);
+ } catch (error) {
+ return { kind: "resolution-failed", message: toErrorMessage(error) };
}
}
-/**
- * Resolves a Vercel OIDC token for the development client.
- *
- * Tries the `@vercel/oidc` SDK first (refreshes a freshly-issued token
- * when the CLI is linked to a Vercel project), then falls back to the
- * `VERCEL_OIDC_TOKEN` environment variable. Returns an empty string
- * when no token is available so callers can proceed without auth.
- */
-export async function resolveDevelopmentOidcToken(): Promise<string> {
- try {
- const token = (await getVercelOidcToken()).trim();
+function validateDevelopmentOidcToken(
+ token: string,
+ input: DevelopmentOidcTarget,
+): Exclude<DevelopmentOidcTokenResolution, { readonly kind: "resolution-failed" }> {
+ const payload = token.split(".")[1];
+ if (!payload) return { kind: "malformed-token", reason: "missing-payload" };
- if (token.length > 0) {
- return token;
- }
+ let decoded: unknown;
+ try {
+ decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
} catch {
- // Fall through to env var.
+ return { kind: "malformed-token", reason: "invalid-json-payload" };
}
- return process.env.VERCEL_OIDC_TOKEN?.trim() ?? "";
+ const claims = VercelOidcClaimsSchema.safeParse(decoded);
+ if (!claims.success) {
+ return {
+ kind: "invalid-claims",
+ invalidClaims: claims.error.issues.map((issue) => {
+ const claim = issue.path[0];
+ return claim === "owner_id" || claim === "project_id" ? claim : "claims";
+ }),
+ };
+ }
+
+ const mismatchedClaims: VercelOidcClaimName[] = [];
+ if (claims.data.owner_id !== input.ownerId) mismatchedClaims.push("owner_id");
+ if (claims.data.project_id !== input.projectId) mismatchedClaims.push("project_id");
+ if (mismatchedClaims.length > 0) return { kind: "target-mismatch", mismatchedClaims };
+
+ return { kind: "resolved", token };
}
/**
@@ -77,182 +107,3 @@ export const VERCEL_PROTECTION_BYPASS_HEADER = "x-vercel-protection-bypass";
* `@vercel/oidc`.
*/
export const VERCEL_TRUSTED_OIDC_IDP_TOKEN_HEADER = "x-vercel-trusted-oidc-idp-token";
-
-/**
- * Vercel request header that carries the runtime OIDC token on function
- * invocations.
- */
-export const VERCEL_OIDC_TOKEN_HEADER = "x-vercel-oidc-token";
-
-/**
- * Header values accepted by eve's development client helpers.
- */
-export type DevelopmentRequestHeaders =
- | Headers
- | ReadonlyArray<readonly [string, string]>
- | Record<string, string>;
-
-type MutableDevelopmentRequestHeaders = Headers | Array<[string, string]> | Record<string, string>;
-
-function isEveRouteUrl(url: URL): boolean {
- return (
- url.pathname.endsWith(EVE_ROUTE_PREFIX) ||
- url.pathname.includes(EVE_ROUTE_PREFIX_WITH_SEPARATOR)
- );
-}
-
-/**
- * Creates request headers for one service-issued development request and
- * opportunistically refreshes a linked local Vercel OIDC token for eve-owned
- * routes when no explicit authorization header is present.
- */
-export async function createDevelopmentRequestHeadersAsync(input: {
- headers?: DevelopmentRequestHeaders;
- resourceUrl: URL;
-}): Promise<Headers> {
- const headers = createBaseDevelopmentRequestHeaders(input);
- const oidcToken = await resolveEveRouteOidcToken(headers, input.resourceUrl);
-
- if (oidcToken !== null) {
- attachEveRouteOidcHeaders(headers, oidcToken);
- }
-
- return headers;
-}
-
-function createBaseDevelopmentRequestHeaders(input: {
- headers?: DevelopmentRequestHeaders;
- resourceUrl: URL;
-}): Headers {
- const headers = new Headers(resolveDevelopmentHeadersInit(input.headers));
- const bypassSecret = process.env.VERCEL_AUTOMATION_BYPASS_SECRET?.trim();
-
- if (bypassSecret && isEveRouteUrl(input.resourceUrl)) {
- headers.set(VERCEL_PROTECTION_BYPASS_HEADER, bypassSecret);
- }
-
- return headers;
-}
-
-/**
- * Sets the authorization bearer and the trusted OIDC IDP bypass header
- * from a single resolved OIDC token. Authorization is left untouched if
- * the caller already set it explicitly; the bypass header is always
- * attached so deployment protection accepts the request even when the
- * caller picked their own bearer scheme (e.g. Basic auth on a preview).
- */
-function attachEveRouteOidcHeaders(headers: Headers, oidcToken: string): void {
- if (!headers.has("authorization")) {
- headers.set("authorization", `Bearer ${oidcToken}`);
- }
- headers.set(VERCEL_TRUSTED_OIDC_IDP_TOKEN_HEADER, oidcToken);
-}
-
-/**
- * Resolves an OIDC token for an eve-owned request, asking
- * `@vercel/oidc` for a freshly-issued token when the CLI is linked to a
- * Vercel project. Falls back to the forwarded runtime header or the
- * `VERCEL_OIDC_TOKEN` environment variable.
- */
-async function resolveEveRouteOidcToken(
- headers: Headers,
- resourceUrl: URL,
-): Promise<string | null> {
- if (!shouldResolveEveRouteOidcToken(resourceUrl)) {
- return null;
- }
-
- const requestToken = headers.get(VERCEL_OIDC_TOKEN_HEADER)?.trim();
-
- if (requestToken) {
- return requestToken;
- }
-
- return await resolveLocalDevelopmentOidcToken();
-}
-
-/**
- * Returns `true` when an eve-route request should attempt to attach a
- * Vercel OIDC token. Local dev servers do not need (and cannot validate)
- * the token, so this returns `false` for them.
- */
-function shouldResolveEveRouteOidcToken(resourceUrl: URL): boolean {
- if (!isEveRouteUrl(resourceUrl)) {
- return false;
- }
-
- // The framework's default HTTP channel auth chain is
- // `[localDev(), vercelOidc()]` (see runtime/framework-channels/index.ts),
- // and `localDev()` accepts off Vercel infrastructure — so attaching a
- // bearer or bypass token to a localhost request is wasted work and
- // noise in the request inspector.
- if (isLocalEveServerUrl(resourceUrl)) {
- return false;
- }
-
- return true;
-}
-
-async function resolveLocalDevelopmentOidcToken(): Promise<string | null> {
- const token = await resolveDevelopmentOidcToken();
- return token.length > 0 ? token : null;
-}
-
-function resolveDevelopmentHeadersInit(
- headers?: DevelopmentRequestHeaders,
-): MutableDevelopmentRequestHeaders | undefined {
- if (headers === undefined) {
- return undefined;
- }
-
- if (headers instanceof Headers) {
- return headers;
- }
-
- if (Array.isArray(headers)) {
- return headers.map(([key, value]): [string, string] => [key, value]);
- }
-
- return headers as Record<string, string>;
-}
-
-/**
- * Resolves the per-request custom headers used by the development client
- * when constructing requests against a configured server URL.
- *
- * - {@link VERCEL_PROTECTION_BYPASS_HEADER} is attached when
- * `VERCEL_AUTOMATION_BYPASS_SECRET` is set.
- * - {@link VERCEL_TRUSTED_OIDC_IDP_TOKEN_HEADER} is attached when a Vercel
- * OIDC token is available locally (either via `vercel link` +
- * `@vercel/oidc` or via the `VERCEL_OIDC_TOKEN` environment variable).
- * This lets the CLI bypass Vercel Deployment Protection without the user
- * creating a project-scoped Bypass for Automation token first.
- *
- * Both headers are sent when both sources are available; the platform
- * accepts whichever it can validate.
- *
- * Local dev servers skip the OIDC token entirely — the framework's
- * default channel auth chain is `[localDev(), vercelOidc()]`, and
- * `localDev()` accepts off Vercel infrastructure, so attaching the
- * bypass token would be wasted work.
- */
-export async function resolveDevelopmentClientHeaders(input: {
- readonly serverUrl: string;
-}): Promise<Record<string, string>> {
- const headers: Record<string, string> = {};
- const bypassSecret = process.env.VERCEL_AUTOMATION_BYPASS_SECRET?.trim();
-
- if (bypassSecret) {
- headers[VERCEL_PROTECTION_BYPASS_HEADER] = bypassSecret;
- }
-
- if (!isLocalDevelopmentServerUrl(input.serverUrl)) {
- const oidcToken = await resolveDevelopmentOidcToken();
-
- if (oidcToken.length > 0) {
- headers[VERCEL_TRUSTED_OIDC_IDP_TOKEN_HEADER] = oidcToken;
- }
- }
-
- return headers;
-}
diff --git a/packages/eve/src/services/dev-client/runtime-artifacts.ts b/packages/eve/src/services/dev-client/runtime-artifacts.ts
index 4d07d9042..c6a658de2 100644
--- a/packages/eve/src/services/dev-client/runtime-artifacts.ts
+++ b/packages/eve/src/services/dev-client/runtime-artifacts.ts
@@ -3,8 +3,6 @@ import {
EVE_DEV_RUNTIME_ARTIFACTS_ROUTE_PATH,
} from "#protocol/routes.js";
-import { resolveDevelopmentClientHeaders } from "./request-headers.js";
-
/**
* Reads the dev server's runtime-artifacts revision — an opaque token that
* changes whenever the authored-source watcher recompiles (HMR). Consumers
@@ -20,9 +18,7 @@ export async function readDevelopmentRuntimeArtifactsRevision(input: {
}): Promise<string | undefined> {
try {
const url = new URL(EVE_DEV_RUNTIME_ARTIFACTS_ROUTE_PATH, input.serverUrl);
- const response = await fetch(url, {
- headers: await resolveDevelopmentClientHeaders({ serverUrl: input.serverUrl }),
- });
+ const response = await fetch(url);
return await parseDevelopmentRuntimeArtifactsRevision(response);
} catch {
return undefined;
@@ -34,10 +30,7 @@ export async function rebuildDevelopmentRuntimeArtifacts(input: {
}): Promise<string | undefined> {
try {
const url = new URL(EVE_DEV_RUNTIME_ARTIFACTS_REBUILD_ROUTE_PATH, input.serverUrl);
- const response = await fetch(url, {
- headers: await resolveDevelopmentClientHeaders({ serverUrl: input.serverUrl }),
- method: "POST",
- });
+ const response = await fetch(url, { method: "POST" });
return await parseDevelopmentRuntimeArtifactsRevision(response);
} catch {
return undefined;
diff --git a/packages/eve/src/services/dev-client/vercel-auth-error.test.ts b/packages/eve/src/services/dev-client/vercel-auth-error.test.ts
index b8ccb174d..57c753b04 100644
--- a/packages/eve/src/services/dev-client/vercel-auth-error.test.ts
+++ b/packages/eve/src/services/dev-client/vercel-auth-error.test.ts
@@ -80,4 +80,31 @@ describe("formatVercelAuthChallengeMessage", () => {
expect(message).not.toContain("<");
expect(message).not.toContain("doctype");
});
+
+ it("includes invalid local OIDC claims in the repair context", () => {
+ const message = formatVercelAuthChallengeMessage({
+ serverUrl: "https://example.vercel.app",
+ oidcTokenFailure: {
+ kind: "invalid-claims",
+ invalidClaims: ["owner_id", "project_id"],
+ },
+ });
+
+ expect(message).toContain("invalid claims");
+ expect(message).toContain("owner_id");
+ expect(message).toContain("project_id");
+ });
+
+ it("identifies the claims that do not match the resolved target", () => {
+ const message = formatVercelAuthChallengeMessage({
+ serverUrl: "https://example.vercel.app",
+ oidcTokenFailure: {
+ kind: "target-mismatch",
+ mismatchedClaims: ["owner_id", "project_id"],
+ },
+ });
+
+ expect(message).toContain("owner_id");
+ expect(message).toContain("project_id");
+ });
});
diff --git a/packages/eve/src/services/dev-client/vercel-auth-error.ts b/packages/eve/src/services/dev-client/vercel-auth-error.ts
index 542996aa8..4bcebe4c8 100644
--- a/packages/eve/src/services/dev-client/vercel-auth-error.ts
+++ b/packages/eve/src/services/dev-client/vercel-auth-error.ts
@@ -15,6 +15,7 @@
*/
import { ClientError } from "#client/client-error.js";
+import type { DevelopmentOidcTokenFailure } from "#services/dev-client/request-headers.js";
/**
* Substrings that uniquely identify the Vercel Deployment Protection
@@ -93,9 +94,15 @@ export function isVercelAuthChallenge(error: unknown): boolean {
* short — multi-line CLI output is harder to scan than a focused
* directive.
*/
-export function formatVercelAuthChallengeMessage(input: { readonly serverUrl: string }): string {
- return [
- `Vercel Deployment Protection blocked the request to ${input.serverUrl}.`,
+export function formatVercelAuthChallengeMessage(input: {
+ readonly serverUrl: string;
+ readonly oidcTokenFailure?: DevelopmentOidcTokenFailure;
+}): string {
+ const lines = [`Vercel Deployment Protection blocked the request to ${input.serverUrl}.`];
+ if (input.oidcTokenFailure !== undefined) {
+ lines.push("", formatOidcTokenFailure(input.oidcTokenFailure));
+ }
+ lines.push(
"",
"To access the deployment from `eve dev`, do one of:",
" • Run `vercel link` in this project so the CLI can mint an OIDC",
@@ -105,5 +112,25 @@ export function formatVercelAuthChallengeMessage(input: { readonly serverUrl: st
" • Disable Deployment Protection on the target deployment.",
"",
"Docs: https://vercel.com/docs/deployment-protection",
- ].join("\n");
+ );
+ return lines.join("\n");
+}
+
+function formatOidcTokenFailure(failure: DevelopmentOidcTokenFailure): string {
+ switch (failure.kind) {
+ case "resolution-failed":
+ return `The local Vercel OIDC token could not be resolved: ${failure.message}`;
+ case "malformed-token":
+ return failure.reason === "missing-payload"
+ ? "Vercel returned a local OIDC token without a JWT payload."
+ : "Vercel returned a local OIDC token whose payload is not valid JSON.";
+ case "invalid-claims":
+ return `The local Vercel OIDC token has invalid claims: ${failure.invalidClaims.join(", ")}.`;
+ case "target-mismatch":
+ return `The local Vercel OIDC token does not match the resolved deployment: ${failure.mismatchedClaims.join(", ")}.`;
+ default: {
+ const exhaustive: never = failure;
+ return exhaustive;
+ }
+ }
}
diff --git a/packages/eve/src/setup/project-resolution.test.ts b/packages/eve/src/setup/project-resolution.test.ts
index 549138e43..2ca88f196 100644
--- a/packages/eve/src/setup/project-resolution.test.ts
+++ b/packages/eve/src/setup/project-resolution.test.ts
@@ -2,10 +2,30 @@ import { describe, expect, it } from "vitest";
import {
mergeProjectResolution,
+ projectReferenceFromEnvironment,
projectResolutionFromDeployResult,
type ProjectResolution,
} from "./project-resolution.js";
+describe("projectReferenceFromEnvironment", () => {
+ it("parses a complete owner and project pair", () => {
+ expect(
+ projectReferenceFromEnvironment({
+ VERCEL_ORG_ID: "team_example",
+ VERCEL_PROJECT_ID: "prj_example",
+ }),
+ ).toEqual({ orgId: "team_example", projectId: "prj_example" });
+ });
+
+ it("rejects incomplete and empty pairs", () => {
+ expect(projectReferenceFromEnvironment({ VERCEL_ORG_ID: "team_example" })).toBeUndefined();
+ expect(projectReferenceFromEnvironment({ VERCEL_PROJECT_ID: "prj_example" })).toBeUndefined();
+ expect(
+ projectReferenceFromEnvironment({ VERCEL_ORG_ID: "", VERCEL_PROJECT_ID: "prj_example" }),
+ ).toBeUndefined();
+ });
+});
+
describe("ProjectResolution", () => {
it("does not carry deployment metadata across project ids", () => {
const oldProject = {
diff --git a/packages/eve/src/setup/project-resolution.ts b/packages/eve/src/setup/project-resolution.ts
index 87678e1d6..1eb5c1253 100644
--- a/packages/eve/src/setup/project-resolution.ts
+++ b/packages/eve/src/setup/project-resolution.ts
@@ -1,5 +1,6 @@
import { readFile } from "node:fs/promises";
import { join } from "node:path";
+import { z } from "zod";
import { captureVercel } from "./primitives/run-vercel.js";
@@ -14,9 +15,42 @@ export interface DeploymentInfo {
productionUrl?: string;
}
-interface VercelProjectJson {
- projectId?: unknown;
- orgId?: unknown;
+const VercelProjectReferenceSchema = z.object({
+ projectId: z.string().min(1),
+ orgId: z.string().min(1),
+ projectName: z.string().min(1).optional(),
+});
+const VercelProjectEnvironmentSchema = z.object({
+ VERCEL_ORG_ID: VercelProjectReferenceSchema.shape.orgId,
+ VERCEL_PROJECT_ID: VercelProjectReferenceSchema.shape.projectId,
+});
+
+/** Validated Vercel owner and project identifiers. */
+export type VercelProjectReference = z.infer<typeof VercelProjectReferenceSchema>;
+
+/** Parses the complete Vercel owner and project environment pair. */
+export function projectReferenceFromEnvironment(
+ environment: Readonly<Record<string, string | undefined>>,
+): VercelProjectReference | undefined {
+ const parsed = VercelProjectEnvironmentSchema.safeParse(environment);
+ if (!parsed.success) return undefined;
+ return {
+ orgId: parsed.data.VERCEL_ORG_ID,
+ projectId: parsed.data.VERCEL_PROJECT_ID,
+ };
+}
+
+/** Reads a validated Vercel project reference from `.vercel/project.json`. */
+export async function readProjectLink(
+ projectPath: string,
+): Promise<VercelProjectReference | undefined> {
+ try {
+ const raw = await readFile(join(projectPath, ".vercel", "project.json"), "utf8");
+ const parsed = VercelProjectReferenceSchema.safeParse(JSON.parse(raw));
+ return parsed.success ? parsed.data : undefined;
+ } catch {
+ return undefined;
+ }
}
interface VercelApiProject {
@@ -68,32 +102,20 @@ export async function detectDeployment(
options: ProjectDetectionOptions = {},
): Promise<DeploymentInfo> {
options.signal?.throwIfAborted();
- let projectJsonRaw: string;
- try {
- projectJsonRaw = await readFile(join(projectPath, ".vercel", "project.json"), "utf8");
- } catch {
- return { state: "unlinked" };
- }
-
- let projectJson: VercelProjectJson;
- try {
- projectJson = JSON.parse(projectJsonRaw) as VercelProjectJson;
- } catch {
- return { state: "unlinked" };
- }
-
- const projectId = typeof projectJson.projectId === "string" ? projectJson.projectId : undefined;
- const orgId = typeof projectJson.orgId === "string" ? projectJson.orgId : undefined;
- if (!projectId || !orgId) {
- return { state: "unlinked" };
- }
-
- const productionUrl = await fetchProductionAlias(projectId, orgId, projectPath, options);
+ const link = await readProjectLink(projectPath);
+ if (link === undefined) return { state: "unlinked" };
+
+ const productionUrl = await fetchProductionAlias(
+ link.projectId,
+ link.orgId,
+ projectPath,
+ options,
+ );
options.signal?.throwIfAborted();
return {
state: productionUrl ? "deployed" : "linked",
- projectId,
- orgId,
+ projectId: link.projectId,
+ orgId: link.orgId,
productionUrl,
};
}
@@ -148,30 +170,20 @@ export async function detectProjectIdentity(
options: ProjectDetectionOptions = {},
): Promise<ProjectIdentity | undefined> {
options.signal?.throwIfAborted();
- let projectJsonRaw: string;
- try {
- projectJsonRaw = await readFile(join(projectPath, ".vercel", "project.json"), "utf8");
- } catch {
- return undefined;
- }
- let projectJson: VercelProjectJson;
- try {
- projectJson = JSON.parse(projectJsonRaw) as VercelProjectJson;
- } catch {
- return undefined;
- }
- const projectId = typeof projectJson.projectId === "string" ? projectJson.projectId : undefined;
- const orgId = typeof projectJson.orgId === "string" ? projectJson.orgId : undefined;
- if (!projectId || !orgId) return undefined;
+ const link = await readProjectLink(projectPath);
+ if (link === undefined) return undefined;
// Independent lookups; fetched concurrently because this read gates the
// first paint of every surface that names the link (/model, the dashboard).
const [projectName, teamName] = await Promise.all([
- fetchVercelName(`/v9/projects/${projectId}?teamId=${orgId}`, orgId, projectPath, options).then(
- (name) => name ?? projectId,
- ),
- orgId.startsWith("team_")
- ? fetchVercelName(`/v2/teams/${orgId}`, orgId, projectPath, options)
+ fetchVercelName(
+ `/v9/projects/${link.projectId}?teamId=${link.orgId}`,
+ link.orgId,
+ projectPath,
+ options,
+ ).then((name) => name ?? link.projectId),
+ link.orgId.startsWith("team_")
+ ? fetchVercelName(`/v2/teams/${link.orgId}`, link.orgId, projectPath, options)
: Promise.resolve(undefined),
]);
options.signal?.throwIfAborted();
diff --git a/packages/eve/src/setup/vercel-deployment.test.ts b/packages/eve/src/setup/vercel-deployment.test.ts
new file mode 100644
index 000000000..ffcae8cb0
--- /dev/null
+++ b/packages/eve/src/setup/vercel-deployment.test.ts
@@ -0,0 +1,214 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { VercelCaptureResult } from "#setup/primitives/index.js";
+
+import {
+ resolveVercelDeployment,
+ type VercelDeploymentResolutionDeps,
+} from "./vercel-deployment.js";
+
+beforeEach(() => {
+ vi.stubEnv("VERCEL_ORG_ID", "");
+ vi.stubEnv("VERCEL_PROJECT_ID", "");
+});
+
+afterEach(() => {
+ vi.unstubAllEnvs();
+});
+
+describe("resolveVercelDeployment", () => {
+ it("uses a complete Vercel project environment before the on-disk link", async () => {
+ vi.stubEnv("VERCEL_ORG_ID", "team_env");
+ vi.stubEnv("VERCEL_PROJECT_ID", "prj_env");
+ const readProjectLink = vi.fn<VercelDeploymentResolutionDeps["readProjectLink"]>(async () => ({
+ orgId: "team_link",
+ projectId: "prj_link",
+ }));
+ const captureVercel = vi.fn<VercelDeploymentResolutionDeps["captureVercel"]>(async () => ({
+ ok: true,
+ stdout: JSON.stringify({
+ projectId: "prj_env",
+ name: "inbound",
+ target: "preview",
+ }),
+ }));
+
+ await expect(
+ resolveVercelDeployment({
+ workspaceRoot: "/repo",
+ host: "inbound.example.com",
+ deps: { captureVercel, readProjectLink },
+ }),
+ ).resolves.toMatchObject({
+ kind: "resolved",
+ target: {
+ deployment: { ownerId: "team_env", projectId: "prj_env" },
+ },
+ });
+ expect(readProjectLink).not.toHaveBeenCalled();
+ });
+
+ it("resolves a standard deployment whose custom environment is null", async () => {
+ const response: VercelCaptureResult = {
+ ok: true,
+ stdout: JSON.stringify({
+ projectId: "prj_target",
+ name: "inbound",
+ target: null,
+ customEnvironment: null,
+ }),
+ };
+ const captureVercel = vi.fn<VercelDeploymentResolutionDeps["captureVercel"]>(
+ async () => response,
+ );
+
+ const resolution = await resolveVercelDeployment({
+ workspaceRoot: "/repo",
+ host: "inbound.example.com",
+ deps: {
+ captureVercel,
+ readProjectLink: async () => ({ orgId: "team_a", projectId: "prj_target" }),
+ },
+ });
+
+ expect(resolution).toMatchObject({
+ kind: "resolved",
+ target: {
+ origin: "https://inbound.example.com",
+ deployment: {
+ provider: "vercel",
+ ownerId: "team_a",
+ projectId: "prj_target",
+ projectName: "inbound",
+ environment: "preview",
+ },
+ },
+ });
+
+ expect(captureVercel).toHaveBeenCalledWith(
+ ["api", "/v13/deployments/inbound.example.com", "--scope", "team_a", "--raw"],
+ expect.objectContaining({ cwd: "/repo", nonInteractive: true, timeoutMs: 10_000 }),
+ );
+ });
+
+ it("distinguishes not-found, operational, and invalid-response failures", async () => {
+ const captures: VercelCaptureResult[] = [
+ {
+ ok: false,
+ failure: {
+ code: 1,
+ stdout: JSON.stringify({ error: { code: "not_found", message: "missing" } }),
+ stderr: "",
+ message: "vercel api exited with code 1.",
+ },
+ },
+ {
+ ok: false,
+ failure: {
+ code: null,
+ stdout: "",
+ stderr: "",
+ message: "vercel api timed out.",
+ },
+ },
+ { ok: true, stdout: "not json" },
+ { ok: true, stdout: JSON.stringify({ projectId: "prj_target" }) },
+ ];
+ const captureVercel = vi.fn<VercelDeploymentResolutionDeps["captureVercel"]>(async () => {
+ const result = captures.shift();
+ if (result === undefined) throw new Error("Unexpected Vercel lookup");
+ return result;
+ });
+ const input = {
+ workspaceRoot: "/repo",
+ host: "inbound.example.com",
+ source: { orgId: "team_a", projectId: "prj_target" },
+ deps: { captureVercel },
+ };
+
+ await expect(resolveVercelDeployment(input)).resolves.toEqual({ kind: "not-found" });
+ await expect(resolveVercelDeployment(input)).resolves.toMatchObject({
+ kind: "failed",
+ failure: { cause: "vercel", failure: { message: "vercel api timed out." } },
+ });
+ await expect(resolveVercelDeployment(input)).resolves.toEqual({
+ kind: "failed",
+ failure: {
+ cause: "invalid-json",
+ message: "Vercel returned invalid deployment JSON.",
+ },
+ });
+ await expect(resolveVercelDeployment(input)).resolves.toEqual({
+ kind: "failed",
+ failure: {
+ cause: "invalid-shape",
+ message: "Vercel returned an invalid deployment response.",
+ },
+ });
+ });
+
+ it("rejects a deployment from a different project under the same owner", async () => {
+ await expect(
+ resolveVercelDeployment({
+ workspaceRoot: "/repo",
+ host: "other.example.com",
+ source: { orgId: "team_a", projectId: "prj_source" },
+ deps: {
+ captureVercel: async () => ({
+ ok: true,
+ stdout: JSON.stringify({
+ projectId: "prj_other",
+ name: "other",
+ target: "preview",
+ customEnvironment: null,
+ }),
+ }),
+ },
+ }),
+ ).resolves.toEqual({
+ kind: "project-mismatch",
+ expectedProjectId: "prj_source",
+ actualProjectId: "prj_other",
+ });
+ });
+
+ it("reports an unscoped lookup without invoking the Vercel CLI", async () => {
+ const captureVercel = vi.fn<VercelDeploymentResolutionDeps["captureVercel"]>();
+
+ await expect(
+ resolveVercelDeployment({
+ workspaceRoot: "/repo",
+ host: "inbound.example.com",
+ deps: {
+ captureVercel,
+ readProjectLink: async () => undefined,
+ },
+ }),
+ ).resolves.toEqual({ kind: "unscoped" });
+ expect(captureVercel).not.toHaveBeenCalled();
+ });
+
+ it("does not infer not-found from an operational error's command text", async () => {
+ await expect(
+ resolveVercelDeployment({
+ workspaceRoot: "/repo",
+ host: "preview-404.example.com",
+ source: { orgId: "team_a", projectId: "prj_target" },
+ deps: {
+ captureVercel: async () => ({
+ ok: false,
+ failure: {
+ code: 1,
+ stdout: JSON.stringify({ error: { code: "forbidden", message: "Forbidden" } }),
+ stderr: "",
+ message: "vercel api /v13/deployments/preview-404.example.com exited with code 1.",
+ },
+ }),
+ },
+ }),
+ ).resolves.toMatchObject({
+ kind: "failed",
+ failure: { cause: "vercel" },
+ });
+ });
+});
diff --git a/packages/eve/src/setup/vercel-deployment.ts b/packages/eve/src/setup/vercel-deployment.ts
new file mode 100644
index 000000000..8326be4f6
--- /dev/null
+++ b/packages/eve/src/setup/vercel-deployment.ts
@@ -0,0 +1,167 @@
+import { captureVercel, type VercelCaptureFailure } from "#setup/primitives/index.js";
+import {
+ projectReferenceFromEnvironment,
+ readProjectLink,
+ type VercelProjectReference,
+} from "#setup/project-resolution.js";
+import { z } from "zod";
+
+const VercelDeploymentSchema = z.object({
+ projectId: z.string().min(1),
+ name: z.string().min(1),
+ target: z.string().nullable().optional(),
+ customEnvironment: z
+ .object({ slug: z.string().min(1) })
+ .nullable()
+ .optional(),
+});
+const VercelApiErrorSchema = z.object({
+ error: z.object({
+ code: z.union([z.string(), z.number()]).optional(),
+ message: z.string().optional(),
+ }),
+});
+
+const verifiedVercelTargetBrand: unique symbol = Symbol("VerifiedVercelTarget");
+
+export interface ResolvedVercelDeployment {
+ readonly provider: "vercel";
+ readonly ownerId: string;
+ readonly projectId: string;
+ readonly projectName: string;
+ readonly environment: string;
+}
+
+/** Proof that Vercel resolved one exact HTTPS origin under an authenticated scope. */
+export interface VerifiedVercelTarget {
+ readonly [verifiedVercelTargetBrand]: true;
+ readonly origin: `https://${string}`;
+ readonly deployment: ResolvedVercelDeployment;
+}
+
+export type VercelDeploymentResolutionFailure =
+ | { readonly cause: "vercel"; readonly failure: VercelCaptureFailure }
+ | { readonly cause: "invalid-json" | "invalid-shape"; readonly message: string };
+
+export type VercelDeploymentResolution =
+ | { readonly kind: "resolved"; readonly target: VerifiedVercelTarget }
+ | { readonly kind: "not-found" }
+ | { readonly kind: "unscoped" }
+ | {
+ readonly kind: "project-mismatch";
+ readonly expectedProjectId: string;
+ readonly actualProjectId: string;
+ }
+ | { readonly kind: "cancelled" }
+ | {
+ readonly kind: "failed";
+ readonly failure: VercelDeploymentResolutionFailure;
+ };
+
+export interface VercelDeploymentResolutionDeps {
+ readonly captureVercel: typeof captureVercel;
+ readonly readProjectLink: typeof readProjectLink;
+}
+
+const defaultDeps: VercelDeploymentResolutionDeps = { captureVercel, readProjectLink };
+const DEPLOYMENT_LOOKUP_TIMEOUT_MS = 10_000;
+
+function isNotFoundApiFailure(failure: VercelCaptureFailure): boolean {
+ if (failure.code === 404) return true;
+
+ try {
+ const parsed = VercelApiErrorSchema.safeParse(JSON.parse(failure.stdout));
+ if (!parsed.success) return false;
+ const code = String(parsed.data.error.code ?? "").toLowerCase();
+ const message = parsed.data.error.message?.toLowerCase() ?? "";
+ return code === "404" || code === "not_found" || message.includes("not found");
+ } catch {
+ return false;
+ }
+}
+
+function environmentForDeployment(deployment: z.infer<typeof VercelDeploymentSchema>): string {
+ if (deployment.customEnvironment !== null && deployment.customEnvironment !== undefined) {
+ return deployment.customEnvironment.slug;
+ }
+ return deployment.target === "production" ? "production" : "preview";
+}
+
+/** Resolves a Vercel deployment URL to its project and target environment. */
+export async function resolveVercelDeployment(input: {
+ readonly workspaceRoot: string;
+ readonly host: string;
+ readonly source?: Pick<VercelProjectReference, "orgId" | "projectId">;
+ readonly signal?: AbortSignal;
+ readonly deps?: Partial<VercelDeploymentResolutionDeps>;
+}): Promise<VercelDeploymentResolution> {
+ const deps = { ...defaultDeps, ...input.deps };
+ const source =
+ input.source ??
+ projectReferenceFromEnvironment(process.env) ??
+ (await deps.readProjectLink(input.workspaceRoot));
+ if (source === undefined) return { kind: "unscoped" };
+
+ const result = await deps.captureVercel(
+ ["api", `/v13/deployments/${encodeURIComponent(input.host)}`, "--scope", source.orgId, "--raw"],
+ {
+ cwd: input.workspaceRoot,
+ nonInteractive: true,
+ signal: input.signal,
+ timeoutMs: DEPLOYMENT_LOOKUP_TIMEOUT_MS,
+ },
+ );
+ if (!result.ok) {
+ if (input.signal?.aborted === true || result.failure.errno === "ABORT_ERR") {
+ return { kind: "cancelled" };
+ }
+ if (isNotFoundApiFailure(result.failure)) return { kind: "not-found" };
+ return { kind: "failed", failure: { cause: "vercel", failure: result.failure } };
+ }
+
+ let payload: unknown;
+ try {
+ payload = JSON.parse(result.stdout);
+ } catch {
+ return {
+ kind: "failed",
+ failure: { cause: "invalid-json", message: "Vercel returned invalid deployment JSON." },
+ };
+ }
+
+ const parsed = VercelDeploymentSchema.safeParse(payload);
+ if (!parsed.success) {
+ return {
+ kind: "failed",
+ failure: {
+ cause: "invalid-shape",
+ message: "Vercel returned an invalid deployment response.",
+ },
+ };
+ }
+
+ if (parsed.data.projectId !== source.projectId) {
+ return {
+ kind: "project-mismatch",
+ expectedProjectId: source.projectId,
+ actualProjectId: parsed.data.projectId,
+ };
+ }
+
+ const normalizedHost = new URL(`https://${input.host}`).host;
+ const origin: `https://${string}` = `https://${normalizedHost}`;
+ return {
+ kind: "resolved",
+ target: {
+ [verifiedVercelTargetBrand]: true,
+ origin,
+ deployment: {
+ provider: "vercel",
+ ownerId: source.orgId,
+ projectId: parsed.data.projectId,
+ projectName: parsed.data.name,
+ environment: environmentForDeployment(parsed.data),
+ },
+ },
+ };
+}
diff --git a/packages/eve/src/setup/verified-remote-client.test.ts b/packages/eve/src/setup/verified-remote-client.test.ts
new file mode 100644
index 000000000..463f567a9
--- /dev/null
+++ b/packages/eve/src/setup/verified-remote-client.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { resolveTestVercelTarget } from "#internal/testing/verified-vercel-target.js";
+
+import { resolveVerifiedRemoteDevelopmentClient } from "./verified-remote-client.js";
+
+const target = await resolveTestVercelTarget({
+ host: "example.vercel.app",
+ projectId: "prj_example",
+});
+
+describe("resolveVerifiedRemoteDevelopmentClient", () => {
+ it("resolves scoped credentials per request after exact deployment verification", async () => {
+ const resolveDevelopmentOidcToken = vi.fn(async () => ({
+ kind: "resolved" as const,
+ token: " fresh-token ",
+ }));
+ const { options } = await resolveVerifiedRemoteDevelopmentClient({
+ serverUrl: "https://example.vercel.app/path",
+ workspaceRoot: "/workspace",
+ deps: {
+ resolveVercelDeployment: async () => ({ kind: "resolved", target }),
+ resolveDevelopmentOidcToken,
+ },
+ });
+
+ expect(options.redirect).toBe("manual");
+ expect(typeof options.headers).toBe("function");
+ if (typeof options.headers !== "function") throw new Error("Expected dynamic headers.");
+ const headers = new Headers(await options.headers());
+
+ expect(headers.get("authorization")).toBe("Bearer fresh-token");
+ expect(headers.get("x-vercel-trusted-oidc-idp-token")).toBe("fresh-token");
+ expect(resolveDevelopmentOidcToken).toHaveBeenCalledWith({
+ ownerId: "team_test",
+ projectId: "prj_example",
+ });
+ });
+
+ it("exposes the token failure while preserving anonymous fallback", async () => {
+ const failure = {
+ kind: "target-mismatch",
+ mismatchedClaims: ["owner_id", "project_id"],
+ } as const;
+ const { options, lastOidcTokenFailure } = await resolveVerifiedRemoteDevelopmentClient({
+ serverUrl: "https://example.vercel.app/path",
+ workspaceRoot: "/workspace",
+ deps: {
+ resolveVercelDeployment: async () => ({ kind: "resolved", target }),
+ resolveDevelopmentOidcToken: async () => failure,
+ },
+ });
+
+ expect(typeof options.headers).toBe("function");
+ if (typeof options.headers !== "function") throw new Error("Expected dynamic headers.");
+ await expect(options.headers()).resolves.toEqual({});
+ expect(lastOidcTokenFailure()).toEqual(failure);
+ });
+
+ it("keeps an unverified remote anonymous", async () => {
+ const resolveDevelopmentOidcToken = vi.fn(async () => ({
+ kind: "resolved" as const,
+ token: "ambient-token",
+ }));
+ const { options } = await resolveVerifiedRemoteDevelopmentClient({
+ serverUrl: "https://arbitrary.example.com",
+ workspaceRoot: "/workspace",
+ deps: {
+ resolveVercelDeployment: async () => ({ kind: "not-found" }),
+ resolveDevelopmentOidcToken,
+ },
+ });
+
+ expect(typeof options.headers).toBe("function");
+ if (typeof options.headers !== "function") throw new Error("Expected dynamic headers.");
+ await expect(options.headers()).resolves.toEqual({});
+ expect(resolveDevelopmentOidcToken).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/eve/src/setup/verified-remote-client.ts b/packages/eve/src/setup/verified-remote-client.ts
new file mode 100644
index 000000000..4f0e8197d
--- /dev/null
+++ b/packages/eve/src/setup/verified-remote-client.ts
@@ -0,0 +1,57 @@
+import type { ClientOptions } from "#client/index.js";
+import { resolveRemoteDevelopmentClientOptions } from "#services/dev-client/client-options.js";
+import { createDevelopmentCredentialGate } from "#services/dev-client/credential-gate.js";
+import {
+ type DevelopmentOidcTokenFailure,
+ resolveDevelopmentOidcToken,
+} from "#services/dev-client/request-headers.js";
+
+import { resolveVercelDeployment } from "./vercel-deployment.js";
+
+/** Dependencies for verifying one remote client (injectable for tests). */
+export interface VerifiedRemoteDevelopmentClientDeps {
+ readonly resolveVercelDeployment: typeof resolveVercelDeployment;
+ readonly resolveDevelopmentOidcToken: typeof resolveDevelopmentOidcToken;
+}
+
+/** A verified remote client's options plus a reader for its latest OIDC failure. */
+export interface VerifiedRemoteDevelopmentClient {
+ readonly options: ClientOptions;
+ /** OIDC failure from the most recent request, or `undefined` while healthy. */
+ readonly lastOidcTokenFailure: () => DevelopmentOidcTokenFailure | undefined;
+}
+
+const defaultDeps: VerifiedRemoteDevelopmentClientDeps = {
+ resolveVercelDeployment,
+ resolveDevelopmentOidcToken,
+};
+
+/**
+ * Resolves a remote client that emits ambient Vercel credentials only after
+ * exact origin proof, plus a reader for the latest OIDC token failure.
+ */
+export async function resolveVerifiedRemoteDevelopmentClient(input: {
+ readonly serverUrl: string;
+ readonly workspaceRoot: string;
+ readonly deps?: Partial<VerifiedRemoteDevelopmentClientDeps>;
+}): Promise<VerifiedRemoteDevelopmentClient> {
+ const deps = { ...defaultDeps, ...input.deps };
+ const credentials = createDevelopmentCredentialGate(input.serverUrl);
+ const resolution = await deps.resolveVercelDeployment({
+ workspaceRoot: input.workspaceRoot,
+ host: new URL(input.serverUrl).host,
+ });
+
+ if (resolution.kind === "resolved") {
+ const { ownerId, projectId } = resolution.target.deployment;
+ credentials.authorize({
+ target: resolution.target,
+ resolveToken: () => deps.resolveDevelopmentOidcToken({ ownerId, projectId }),
+ });
+ }
+
+ return {
+ options: resolveRemoteDevelopmentClientOptions({ serverUrl: input.serverUrl, credentials }),
+ lastOidcTokenFailure: credentials.lastTokenFailure,
+ };
+}
diff --git a/packages/eve/test/dev-client-harness/request-headers.ts b/packages/eve/test/dev-client-harness/request-headers.ts
new file mode 100644
index 000000000..aba8c1116
--- /dev/null
+++ b/packages/eve/test/dev-client-harness/request-headers.ts
@@ -0,0 +1,80 @@
+import { getVercelOidcToken } from "#compiled/@vercel/oidc/index.js";
+import { EVE_ROUTE_PREFIX } from "#protocol/routes.js";
+import { isLocalDevelopmentServerUrl } from "#services/dev-client/local-host.js";
+import {
+ VERCEL_PROTECTION_BYPASS_HEADER,
+ VERCEL_TRUSTED_OIDC_IDP_TOKEN_HEADER,
+} from "#services/dev-client/request-headers.js";
+
+export {
+ VERCEL_PROTECTION_BYPASS_HEADER,
+ VERCEL_TRUSTED_OIDC_IDP_TOKEN_HEADER,
+} from "#services/dev-client/request-headers.js";
+
+const EVE_ROUTE_PREFIX_WITH_SEPARATOR = `${EVE_ROUTE_PREFIX}/`;
+export const VERCEL_OIDC_TOKEN_HEADER = "x-vercel-oidc-token";
+
+/** Header values accepted by the test-only development client harness. */
+export type DevelopmentRequestHeaders =
+ | Headers
+ | ReadonlyArray<readonly [string, string]>
+ | Record<string, string>;
+
+type MutableDevelopmentRequestHeaders = Headers | Array<[string, string]> | Record<string, string>;
+
+/**
+ * Test-harness credential behavior for live Vercel fixtures. Production
+ * development clients require an authorized `DevelopmentCredentialGate`.
+ */
+export async function createDevelopmentRequestHeadersAsync(input: {
+ readonly headers?: DevelopmentRequestHeaders;
+ readonly resourceUrl: URL;
+}): Promise<Headers> {
+ const headers = new Headers(resolveHeadersInit(input.headers));
+ if (!isEveRouteUrl(input.resourceUrl)) return headers;
+
+ const bypassSecret = process.env.VERCEL_AUTOMATION_BYPASS_SECRET?.trim();
+ if (bypassSecret) headers.set(VERCEL_PROTECTION_BYPASS_HEADER, bypassSecret);
+ if (isLocalDevelopmentServerUrl(input.resourceUrl.toString())) return headers;
+
+ const forwardedToken = headers.get(VERCEL_OIDC_TOKEN_HEADER)?.trim();
+ const oidcToken = forwardedToken || (await resolveTestOidcToken());
+ if (oidcToken.length === 0) return headers;
+
+ if (!headers.has("authorization")) headers.set("authorization", `Bearer ${oidcToken}`);
+ headers.set(VERCEL_TRUSTED_OIDC_IDP_TOKEN_HEADER, oidcToken);
+ return headers;
+}
+
+async function resolveTestOidcToken(): Promise<string> {
+ try {
+ const token = (await getVercelOidcToken()).trim();
+ if (token.length > 0) return token;
+ } catch {
+ // Fall through to the fixture environment.
+ }
+ return process.env.VERCEL_OIDC_TOKEN?.trim() ?? "";
+}
+
+function isEveRouteUrl(url: URL): boolean {
+ return (
+ url.pathname.endsWith(EVE_ROUTE_PREFIX) ||
+ url.pathname.includes(EVE_ROUTE_PREFIX_WITH_SEPARATOR)
+ );
+}
+
+function isHeaderEntries(
+ headers: DevelopmentRequestHeaders,
+): headers is ReadonlyArray<readonly [string, string]> {
+ return Array.isArray(headers);
+}
+
+function resolveHeadersInit(
+ headers: DevelopmentRequestHeaders | undefined,
+): MutableDevelopmentRequestHeaders | undefined {
+ if (headers === undefined || headers instanceof Headers) return headers;
+ if (isHeaderEntries(headers)) {
+ return headers.map(([key, value]): [string, string] => [key, value]);
+ }
+ return headers;
+}
diff --git a/packages/eve/test/dev-client-harness/send-message.ts b/packages/eve/test/dev-client-harness/send-message.ts
index 6a7712b36..0456356ef 100644
--- a/packages/eve/test/dev-client-harness/send-message.ts
+++ b/packages/eve/test/dev-client-harness/send-message.ts
@@ -8,7 +8,7 @@ import {
import {
createDevelopmentRequestHeadersAsync,
type DevelopmentRequestHeaders,
-} from "#services/dev-client/request-headers.js";
+} from "./request-headers.js";
import { openDevelopmentMessageStream } from "./live-stream.js";
import {
createDevelopmentMessageRequest,
diff --git a/packages/eve/test/dev-request-headers.test.ts b/packages/eve/test/dev-request-headers.test.ts
index 1ef2810e0..0e360b11c 100644
--- a/packages/eve/test/dev-request-headers.test.ts
+++ b/packages/eve/test/dev-request-headers.test.ts
@@ -6,7 +6,7 @@ import {
VERCEL_OIDC_TOKEN_HEADER,
VERCEL_PROTECTION_BYPASS_HEADER,
VERCEL_TRUSTED_OIDC_IDP_TOKEN_HEADER,
-} from "../src/services/dev-client/request-headers.js";
+} from "./dev-client-harness/request-headers.js";
vi.mock("#compiled/@vercel/oidc/index.js", async (importOriginal) => {
const original = await importOriginal<typeof import("#compiled/@vercel/oidc/index.js")>();
diff --git a/packages/eve/test/helpers/vercel-deployment-fixture.ts b/packages/eve/test/helpers/vercel-deployment-fixture.ts
index b29cbdf37..707c112e6 100644
--- a/packages/eve/test/helpers/vercel-deployment-fixture.ts
+++ b/packages/eve/test/helpers/vercel-deployment-fixture.ts
@@ -7,7 +7,7 @@ import { ensureScenarioEveTarballPath } from "#internal/testing/scenario-app.js"
import { runPnpmCommand } from "#internal/testing/run-pnpm-command.js";
import { EVE_PACKAGE_NAME } from "#internal/package-name.js";
import { EVE_HEALTH_ROUTE_PATH } from "#protocol/routes.js";
-import { createDevelopmentRequestHeadersAsync } from "#services/dev-client/request-headers.js";
+import { createDevelopmentRequestHeadersAsync } from "../dev-client-harness/request-headers.js";
import { resolveDevelopmentServerRouteUrl } from "../dev-client-harness/url.js";
const VERCEL_CLI_PACKAGE = "vercel@latest";
diff --git a/packages/eve/test/scenarios/dev-command-url.scenario.test.ts b/packages/eve/test/scenarios/dev-command-url.scenario.test.ts
index 510bf149f..6388a818d 100644
--- a/packages/eve/test/scenarios/dev-command-url.scenario.test.ts
+++ b/packages/eve/test/scenarios/dev-command-url.scenario.test.ts
@@ -1,4 +1,4 @@
-import { writeFile } from "node:fs/promises";
+import { realpath, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
@@ -68,7 +68,12 @@ describe("runCli dev URL support", () => {
expect(startHost).not.toHaveBeenCalled();
expect(runDevelopmentTui).toHaveBeenCalledWith(
- expect.objectContaining({ serverUrl: "https://example.com/" }),
+ expect.objectContaining({
+ target: expect.objectContaining({
+ kind: "remote",
+ serverUrl: "https://example.com/",
+ }),
+ }),
);
expect(logger.log.mock.calls.map(([message]) => String(message)).join("\n")).toContain(
"connecting to https://example.com/",
@@ -96,6 +101,7 @@ describe("runCli dev URL support", () => {
it("loads local development env files before connecting", async () => {
const appRoot = await createTemporaryRoot();
+ const canonicalAppRoot = await realpath(appRoot);
const previousCwd = process.cwd();
const logger = {
error: vi.fn(),
@@ -120,7 +126,13 @@ describe("runCli dev URL support", () => {
expect(process.env[DEV_URL_ENV_KEY]).toBe("from-env");
expect(runDevelopmentTui).toHaveBeenCalledWith(
- expect.objectContaining({ serverUrl: "https://example.com/" }),
+ expect.objectContaining({
+ target: {
+ kind: "remote",
+ serverUrl: "https://example.com/",
+ workspaceRoot: canonicalAppRoot,
+ },
+ }),
);
});
});