@vercel/sandbox 1.1.4 → 1.1.5

package/src/auth/poll-for-token.ts

@@ -0,0 +1,89 @@
+import { setTimeout } from "node:timers/promises";
+import { updateAuthConfig } from "./file";
+import { DeviceAuthorizationRequest, isOAuthError, OAuth } from "./oauth";
+
+export type PollTokenItem =
+  | { _tag: "Timeout"; newInterval: number }
+  | { _tag: "SlowDown"; newInterval: number }
+  | { _tag: "Error"; error: Error }
+  | {
+      _tag: "Response";
+      response: { text(): Promise<string> };
+    };
+
+export async function* pollForToken({
+  request,
+  oauth,
+}: {
+  request: DeviceAuthorizationRequest;
+  oauth: OAuth;
+}): AsyncGenerator<PollTokenItem, void, void> {
+  const controller = new AbortController();
+  try {
+    let intervalMs = request.interval * 1000;
+    while (Date.now() < request.expiresAt) {
+      const [tokenResponseError, tokenResponse] =
+        await oauth.deviceAccessTokenRequest(request.device_code);
+
+      if (tokenResponseError) {
+        // 2x backoff on connection timeouts per spec https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
+        if (tokenResponseError.message.includes("timeout")) {
+          intervalMs *= 2;
+          yield { _tag: "Timeout" as const, newInterval: intervalMs };
+          await setTimeout(intervalMs, { signal: controller.signal });
+          continue;
+        }
+        yield { _tag: "Error" as const, error: tokenResponseError };
+        return;
+      }
+
+      yield {
+        _tag: "Response" as const,
+        response: tokenResponse.clone() as { text(): Promise<string> },
+      };
+
+      const [tokensError, tokens] =
+        await oauth.processTokenResponse(tokenResponse);
+
+      if (isOAuthError(tokensError)) {
+        const { code } = tokensError;
+        switch (code) {
+          case "authorization_pending":
+            await setTimeout(intervalMs, { signal: controller.signal });
+            continue;
+          case "slow_down":
+            intervalMs += 5 * 1000;
+            yield { _tag: "SlowDown" as const, newInterval: intervalMs };
+            await setTimeout(intervalMs, { signal: controller.signal });
+            continue;
+          default:
+            yield { _tag: "Error", error: tokensError.cause };
+            return;
+        }
+      }
+
+      if (tokensError) {
+        yield { _tag: "Error", error: tokensError };
+        return;
+      }
+
+      updateAuthConfig({
+        token: tokens.access_token,
+        expiresAt: new Date(Date.now() + tokens.expires_in * 1000),
+        refreshToken: tokens.refresh_token,
+      });
+
+      return;
+    }
+
+    yield {
+      _tag: "Error" as const,
+      error: new Error(
+        "Timed out waiting for authentication. Please try again.",
+      ),
+    };
+    return;
+  } finally {
+    controller.abort();
+  }
+}

package/src/auth/project.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { fetchApi } from "./api";
+import { NotOk } from "./error";
+import { readLinkedProject } from "./linked-project";
+
+const TeamsSchema = z.object({
+  teams: z
+    .array(
+      z.object({
+        slug: z.string(),
+      }),
+    )
+    .min(1, `No teams found. Please create a team first.`),
+});
+
+const DEFAULT_PROJECT_NAME = "vercel-sandbox-default-project";
+
+/**
+ * Resolves the team and project scope for sandbox operations.
+ *
+ * First checks for a locally linked project in `.vercel/project.json`.
+ * If found, uses the `projectId` and `orgId` from there.
+ *
+ * Otherwise, if `teamId` is not provided, selects the first available team for the account.
+ * Ensures a default project exists within the team, creating it if necessary.
+ *
+ * @param opts.token - Vercel API authentication token.
+ * @param opts.teamId - Optional team slug. If omitted, the first team is selected.
+ * @param opts.cwd - Optional directory to search for `.vercel/project.json`. Defaults to `process.cwd()`.
+ * @returns The resolved scope with `projectId`, `teamId`, and whether the project was `created`.
+ *
+ * @throws {NotOk} If the API returns an error other than 404 when checking the project.
+ * @throws {ZodError} If no teams exist for the account.
+ *
+ * @example
+ * ```ts
+ * const scope = await inferScope({ token: "vercel_..." });
+ * // => { projectId: "vercel-sandbox-default-project", teamId: "my-team", created: false }
+ * ```
+ */
+export async function inferScope(opts: {
+  token: string;
+  teamId?: string;
+  cwd?: string;
+}): Promise<{ projectId: string; teamId: string; created: boolean }> {
+  const linkedProject = await readLinkedProject(opts.cwd ?? process.cwd());
+  if (linkedProject) {
+    return { ...linkedProject, created: false };
+  }
+
+  const teamId = opts.teamId ?? (await selectTeam(opts.token));
+
+  let created = false;
+  try {
+    await fetchApi({
+      token: opts.token,
+      endpoint: `/v2/projects/${encodeURIComponent(DEFAULT_PROJECT_NAME)}?slug=${encodeURIComponent(teamId)}`,
+    });
+  } catch (e) {
+    if (!(e instanceof NotOk) || e.response.statusCode !== 404) {
+      throw e;
+    }
+
+    await fetchApi({
+      token: opts.token,
+      endpoint: `/v11/projects?slug=${encodeURIComponent(teamId)}`,
+      method: "POST",
+      body: JSON.stringify({
+        name: DEFAULT_PROJECT_NAME,
+      }),
+    });
+    created = true;
+  }
+
+  return { projectId: DEFAULT_PROJECT_NAME, teamId, created };
+}
+
+/**
+ * Selects a team for the current token by querying the Teams API and
+ * returning the slug of the first team in the result set.
+ *
+ * @param token - Authentication token used to call the Vercel API.
+ * @returns A promise that resolves to the first team's slug.
+ */
+export async function selectTeam(token: string) {
+  const {
+    teams: [team],
+  } = await fetchApi({ token, endpoint: "/v2/teams?limit=1" }).then(
+    TeamsSchema.parse,
+  );
+  return team.slug;
+}

package/src/auth/zod.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+/**
+ * A Zod codec that serializes and deserializes JSON strings.
+ */
+export const json = z.string().transform((jsonString: string, ctx): unknown => {
+  try {
+    return JSON.parse(jsonString);
+  } catch (err: any) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `Invalid JSON: ${err.message}`,
+    });
+    return z.NEVER;
+  }
+});

package/src/sandbox.ts

@@ -198,8 +198,8 @@ export class Sandbox {
       fetch: params?.fetch,
     });
     return client.listSandboxes({
-      ...params,
       ...credentials,
+      ...params,
     });
   }
 

package/src/utils/dev-credentials.test.ts

@@ -0,0 +1,217 @@
+import { signInAndGetToken, generateCredentials } from "./dev-credentials";
+import { describe, expect, test, vi, beforeEach, type Mock } from "vitest";
+import { factory } from "factoree";
+import { setTimeout } from "node:timers/promises";
+import { DeviceAuthorizationRequest, OAuth } from "../auth";
+
+vi.mock("picocolors");
+
+vi.mock("../auth/index", () => ({
+  getAuth: vi.fn(),
+  inferScope: vi.fn(),
+  updateAuthConfig: vi.fn(),
+  OAuth: vi.fn(),
+  pollForToken: vi.fn(),
+}));
+
+import * as auth from "../auth/index";
+
+describe("signInAndGetToken", () => {
+  test("times out after provided timeout", async () => {
+    const consoleError = vi.spyOn(console, "error").mockReturnValue();
+    const promise = signInAndGetToken(
+      {
+        getAuth: () => null,
+        OAuth: async () => {
+          return createOAuthFactory({
+            async deviceAuthorizationRequest() {
+              return createDeviceAuthorizationRequest({
+                device_code: "device_code",
+                user_code: "user_code",
+                verification_uri_complete: `https://example.vercel.sh/device_code?code=user_code`,
+                verification_uri: "https://example.vercel.sh/device_code",
+              });
+            },
+          });
+        },
+        pollForToken: async function* () {
+          await setTimeout(500);
+        },
+      },
+      `100 milliseconds`,
+    );
+
+    await expect(promise).rejects.toThrowError(
+      /Authentication flow timed out after 100 milliseconds./,
+    );
+
+    const printed = consoleError.mock.calls.map((x) => x.join(" ")).join("\n");
+    expect(printed).toMatchInlineSnapshot(`
+      "<yellow><dim>[vercel/sandbox]</dim> No VERCEL_OIDC_TOKEN environment variable found, initiating device authorization flow...
+      <dim>[vercel/sandbox]</dim> │  <bold>help:</bold> this flow only happens on development environment.
+      <dim>[vercel/sandbox]</dim> │  In production, make sure to set up a proper token, or set up Vercel OIDC [https://vercel.com/docs/oidc].</yellow>
+      <blue><dim>[vercel/sandbox]</dim> ╰▶ To authenticate, visit: https://example.vercel.sh/device_code?code=user_code
+      <dim>[vercel/sandbox]</dim>    or visit <italic>https://example.vercel.sh/device_code</italic> and type <bold>user_code</bold>
+      <dim>[vercel/sandbox]</dim>    Press <bold><return></bold> to open in your browser</blue>
+      <red><dim>[vercel/sandbox]</dim> <bold>error:</bold> Authentication failed: Authentication flow timed out after 100 milliseconds.
+      <dim>[vercel/sandbox]</dim> │  Make sure to provide a token to avoid prompting an interactive flow.
+      <dim>[vercel/sandbox]</dim> ╰▶ <bold>help:</bold> Link your project with <italic><dim>\`</dim>npx vercel link<dim>\`</dim></italic> to refresh OIDC token automatically.</red>"
+    `);
+  });
+});
+
+const createOAuthFactory = factory<Awaited<OAuth>>();
+const createDeviceAuthorizationRequest = factory<DeviceAuthorizationRequest>();
+
+describe("generateCredentials", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test("triggers sign-in when auth exists but has no token", async () => {
+    // Auth object with refreshToken but no token - this was the bug
+    (auth.getAuth as Mock).mockReturnValue({
+      refreshToken: "refresh_xxx",
+      expiresAt: new Date(Date.now() + 100000),
+    });
+
+    (auth.OAuth as Mock).mockResolvedValue(
+      createOAuthFactory({
+        async deviceAuthorizationRequest() {
+          return createDeviceAuthorizationRequest({
+            device_code: "device_code",
+            user_code: "user_code",
+            verification_uri_complete: "https://vercel.com/device",
+            verification_uri: "https://vercel.com/device",
+          });
+        },
+      }),
+    );
+
+    (auth.pollForToken as Mock).mockImplementation(async function* () {
+      // Simulate successful auth by updating getAuth to return a token
+      (auth.getAuth as Mock).mockReturnValue({ token: "new_token" });
+      yield { _tag: "Response" as const };
+    });
+
+    (auth.inferScope as Mock).mockResolvedValue({
+      teamId: "team_xxx",
+      projectId: "prj_xxx",
+      created: false,
+    });
+
+    const result = await generateCredentials({});
+
+    expect(auth.pollForToken).toHaveBeenCalled();
+    expect(result).toEqual({
+      token: "new_token",
+      teamId: "team_xxx",
+      projectId: "prj_xxx",
+    });
+  });
+
+  test("triggers sign-in when auth is null", async () => {
+    (auth.getAuth as Mock).mockReturnValue(null);
+
+    (auth.OAuth as Mock).mockResolvedValue(
+      createOAuthFactory({
+        async deviceAuthorizationRequest() {
+          return createDeviceAuthorizationRequest({
+            device_code: "device_code",
+            user_code: "user_code",
+            verification_uri_complete: "https://vercel.com/device",
+            verification_uri: "https://vercel.com/device",
+          });
+        },
+      }),
+    );
+
+    (auth.pollForToken as Mock).mockImplementation(async function* () {
+      (auth.getAuth as Mock).mockReturnValue({ token: "new_token" });
+      yield { _tag: "Response" as const };
+    });
+
+    (auth.inferScope as Mock).mockResolvedValue({
+      teamId: "team_xxx",
+      projectId: "prj_xxx",
+      created: false,
+    });
+
+    await generateCredentials({});
+
+    expect(auth.pollForToken).toHaveBeenCalled();
+  });
+
+  test("skips sign-in when auth has valid token", async () => {
+    (auth.getAuth as Mock).mockReturnValue({ token: "valid_token" });
+
+    (auth.inferScope as Mock).mockResolvedValue({
+      teamId: "team_xxx",
+      projectId: "prj_xxx",
+      created: false,
+    });
+
+    const result = await generateCredentials({});
+
+    expect(auth.pollForToken).not.toHaveBeenCalled();
+    expect(auth.OAuth).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      token: "valid_token",
+      teamId: "team_xxx",
+      projectId: "prj_xxx",
+    });
+  });
+
+  test("calls inferScope only once when deriving both teamId and projectId", async () => {
+    (auth.getAuth as Mock).mockReturnValue({ token: "valid_token" });
+
+    (auth.inferScope as Mock).mockResolvedValue({
+      teamId: "team_xxx",
+      projectId: "prj_xxx",
+      created: false,
+    });
+
+    await generateCredentials({});
+
+    expect(auth.inferScope).toHaveBeenCalledTimes(1);
+  });
+
+  test("does not call inferScope when both teamId and projectId are provided", async () => {
+    (auth.getAuth as Mock).mockReturnValue({ token: "valid_token" });
+
+    const result = await generateCredentials({
+      teamId: "provided_team",
+      projectId: "provided_project",
+    });
+
+    expect(auth.inferScope).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      token: "valid_token",
+      teamId: "provided_team",
+      projectId: "provided_project",
+    });
+  });
+
+  test("calls inferScope with provided teamId when only teamId is given", async () => {
+    (auth.getAuth as Mock).mockReturnValue({ token: "valid_token" });
+
+    (auth.inferScope as Mock).mockResolvedValue({
+      teamId: "provided_team",
+      projectId: "inferred_project",
+      created: false,
+    });
+
+    const result = await generateCredentials({ teamId: "provided_team" });
+
+    expect(auth.inferScope).toHaveBeenCalledTimes(1);
+    expect(auth.inferScope).toHaveBeenCalledWith({
+      teamId: "provided_team",
+      token: "valid_token",
+    });
+    expect(result).toEqual({
+      token: "valid_token",
+      teamId: "provided_team",
+      projectId: "inferred_project",
+    });
+  });
+});

package/src/utils/dev-credentials.ts

@@ -0,0 +1,189 @@
+import pico from "picocolors";
+import type { Credentials } from "./get-credentials";
+import ms from "ms";
+import * as Log from "./log";
+
+async function importAuth() {
+  const auth = await import("../auth/index");
+  return auth;
+}
+
+export function shouldPromptForCredentials(): boolean {
+  return (
+    process.env.NODE_ENV !== "production" &&
+    !["1", "true"].includes(process.env.CI || "") &&
+    process.stdout.isTTY &&
+    process.stdin.isTTY
+  );
+}
+
+/**
+ * Returns cached credentials for the given team/project combination.
+ *
+ * @remarks
+ * The cache is keyed by `teamId` and `projectId`. A new credential generation
+ * is triggered only when these values change or when a previous attempt failed.
+ *
+ * **Important:** Successfully resolved credentials are cached indefinitely and
+ * will not be refreshed even if the token expires. Cache invalidation only occurs
+ * on rejection (error). This is intentional for development use cases where
+ * short-lived sessions don't require proactive token refresh.
+ */
+export const cachedGenerateCredentials = (() => {
+  let cache:
+    | [{ teamId?: string; projectId?: string }, Promise<Credentials>]
+    | null = null;
+  return async (opts: { projectId?: string; teamId?: string }) => {
+    if (
+      !cache ||
+      cache[0].teamId !== opts.teamId ||
+      cache[0].projectId !== opts.projectId
+    ) {
+      const promise = generateCredentials(opts).catch((err) => {
+        cache = null;
+        throw err;
+      });
+      cache = [opts, promise];
+    }
+    const v = await cache[1];
+    Log.write(
+      "warn",
+      `using inferred credentials team=${v.teamId} project=${v.projectId}`,
+    );
+    return v;
+  };
+})();
+
+/**
+ * Generates credentials by authenticating and inferring scope.
+ *
+ * @internal This is exported for testing purposes. Consider using
+ * {@link cachedGenerateCredentials} instead, which caches the result
+ * to avoid redundant authentication flows.
+ */
+export async function generateCredentials(opts: {
+  teamId?: string;
+  projectId?: string;
+}): Promise<Credentials> {
+  const { OAuth, pollForToken, getAuth, updateAuthConfig, inferScope } =
+    await importAuth();
+  let auth = getAuth();
+  if (!auth?.token) {
+    const timeout: ms.StringValue = process.env.VERCEL_URL
+      ? /* when deployed to vercel we don't want to have a long timeout */ "1 minute"
+      : "5 minutes";
+    auth = await signInAndGetToken({ OAuth, pollForToken, getAuth }, timeout);
+  }
+  if (
+    auth?.refreshToken &&
+    auth.expiresAt &&
+    auth.expiresAt.getTime() <= Date.now()
+  ) {
+    const oauth = await OAuth();
+    const newToken = await oauth.refreshToken(auth.refreshToken);
+    auth = {
+      expiresAt: new Date(Date.now() + newToken.expires_in * 1000),
+      token: newToken.access_token,
+      refreshToken: newToken.refresh_token || auth.refreshToken,
+    };
+    updateAuthConfig(auth);
+  }
+
+  if (!auth?.token) {
+    throw new Error("Failed to retrieve authentication token.");
+  }
+
+  if (opts.teamId && opts.projectId) {
+    return {
+      token: auth.token,
+      teamId: opts.teamId,
+      projectId: opts.projectId,
+    };
+  }
+
+  const scope = await inferScope({ teamId: opts.teamId, token: auth.token });
+
+  if (scope.created) {
+    Log.write(
+      "info",
+      `Created default project "${scope.projectId}" in team "${scope.teamId}".`,
+    );
+  }
+
+  return {
+    token: auth.token,
+    teamId: opts.teamId || scope.teamId,
+    projectId: opts.projectId || scope.projectId,
+  };
+}
+
+export async function signInAndGetToken(
+  auth: Pick<
+    Awaited<ReturnType<typeof importAuth>>,
+    "OAuth" | "getAuth" | "pollForToken"
+  >,
+  timeout: ms.StringValue,
+) {
+  Log.write("warn", [
+    `No VERCEL_OIDC_TOKEN environment variable found, initiating device authorization flow...`,
+    `│  ${pico.bold("help:")} this flow only happens on development environment.`,
+    `│  In production, make sure to set up a proper token, or set up Vercel OIDC [https://vercel.com/docs/oidc].`,
+  ]);
+  const oauth = await auth.OAuth();
+  const request = await oauth.deviceAuthorizationRequest();
+  Log.write("info", [
+    `╰▶ To authenticate, visit: ${request.verification_uri_complete}`,
+    `   or visit ${pico.italic(request.verification_uri)} and type ${pico.bold(request.user_code)}`,
+    `   Press ${pico.bold("<return>")} to open in your browser`,
+  ]);
+
+  let error: Error | undefined;
+  const generator = auth.pollForToken({ request, oauth });
+  let done = false;
+  let spawnedTimeout = setTimeout(() => {
+    if (done) return;
+    const message = [
+      `Authentication flow timed out after ${timeout}.`,
+      `│  Make sure to provide a token to avoid prompting an interactive flow.`,
+      `╰▶ ${pico.bold("help:")} Link your project with ${Log.code("npx vercel link")} to refresh OIDC token automatically.`,
+    ].join("\n");
+    error = new Error(message);
+    // Note: generator.return() initiates cooperative cancellation. The generator's
+    // finally block will abort pending setTimeout calls, but any in-flight HTTP
+    // request will complete before the generator terminates. This is acceptable
+    // for this dev-only timeout scenario.
+    generator.return();
+  }, ms(timeout));
+  try {
+    for await (const event of generator) {
+      switch (event._tag) {
+        case "SlowDown":
+        case "Timeout":
+        case "Response":
+          break;
+        case "Error":
+          error = event.error;
+          break;
+        default:
+          throw new Error(
+            `Unknown event type: ${JSON.stringify(event satisfies never)}`,
+          );
+      }
+    }
+  } finally {
+    done = true;
+    clearTimeout(spawnedTimeout);
+  }
+
+  if (error) {
+    Log.write(
+      "error",
+      `${pico.bold("error:")} Authentication failed: ${error.message}`,
+    );
+    throw error;
+  }
+
+  Log.write("success", `${pico.bold("done!")} Authenticated successfully!`);
+  const stored = auth.getAuth();
+  return stored;
+}

package/src/utils/get-credentials.test.ts

@@ -0,0 +1,20 @@
+import { test, expect, beforeEach } from "vitest";
+import {
+  getCredentials,
+  LocalOidcContextError,
+  VercelOidcContextError,
+} from "./get-credentials";
+
+beforeEach(() => {
+  delete process.env.VERCEL_OIDC_TOKEN;
+});
+
+test("explains how to set up oidc in local", async () => {
+  delete process.env.VERCEL_URL;
+  await expect(getCredentials()).rejects.toThrowError(LocalOidcContextError);
+});
+
+test("explains how to set up oidc in vercel", async () => {
+  process.env.VERCEL_URL = "example.vercel.sh";
+  await expect(getCredentials()).rejects.toThrowError(VercelOidcContextError);
+});