@vercel/sandbox 1.1.9 → 1.2.1

package/src/utils/decode-base64-url.ts

@@ -1,14 +0,0 @@
-/**
- * Decode a Base64 URL-encoded string into a JSON object.
- *
- * @param base64Url - The Base64 URL-encoded string to decode.
- * @returns The decoded JSON object or null if decoding fails.
- */
-export function decodeBase64Url(base64Url: string) {
-  return JSON.parse(
-    Buffer.from(
-      base64Url.replace(/-/g, "+").replace(/_/g, "/"),
-      "base64",
-    ).toString("utf8"),
-  );
-}

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

@@ -1,217 +0,0 @@
-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

@@ -1,196 +0,0 @@
-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.`,
-        `${pico.bold("hint:")} Set VERCEL_OIDC_TOKEN or provide a Vercel API token.`,
-        "├▶ Sandbox docs: https://vercel.com/docs/sandbox",
-        "╰▶ Access tokens: https://vercel.com/kb/guide/how-do-i-use-a-vercel-api-access-token",
-      ].join("\n"),
-    );
-  }
-
-  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

@@ -1,20 +0,0 @@
-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);
-});

package/src/utils/get-credentials.ts

@@ -1,183 +0,0 @@
-import { getVercelOidcToken } from "@vercel/oidc";
-import { decodeBase64Url } from "./decode-base64-url";
-import { z } from "zod";
-import {
-  cachedGenerateCredentials,
-  shouldPromptForCredentials,
-} from "./dev-credentials";
-
-export interface Credentials {
-  /**
-   * Authentication token for the Vercel API. It could be an OIDC token
-   * or a personal access token.
-   */
-  token: string;
-  /**
-   * The ID of the project to associate Sandbox operations.
-   */
-  projectId: string;
-  /**
-   * The ID of the team to associate Sandbox operations.
-   */
-  teamId: string;
-}
-
-/**
- * Error thrown when OIDC context is not available in local development,
- * therefore we should guide how to ensure it is set up by linking a project
- */
-export class LocalOidcContextError extends Error {
-  name = "LocalOidcContextError";
-  constructor(cause: unknown) {
-    const message = [
-      "Could not get credentials from OIDC context.",
-      "Please link your Vercel project using `npx vercel link`.",
-      "Then, pull an initial OIDC token with `npx vercel env pull`",
-      "and retry.",
-      "╰▶ Make sure you are loading `.env.local` correctly, or passing $VERCEL_OIDC_TOKEN directly."
-    ].join("\n");
-    super(message, { cause });
-  }
-}
-
-/**
- * Error thrown when OIDC context is not available in Vercel environment,
- * therefore we should guide how to set it up.
- */
-export class VercelOidcContextError extends Error {
-  name = "VercelOidcContextError";
-  constructor(cause: unknown) {
-    const message = [
-      "Could not get credentials from OIDC context.",
-      "Please make sure OIDC is set up for your project",
-      "╰▶ Docs: https://vercel.com/docs/oidc",
-    ].join("\n");
-    super(message, { cause });
-  }
-}
-
-async function getVercelToken(opts: {
-  teamId?: string;
-  projectId?: string;
-}): Promise<Credentials> {
-  try {
-    return getCredentialsFromOIDCToken(await getVercelOidcToken());
-  } catch (error) {
-    if (!shouldPromptForCredentials()) {
-      if (process.env.VERCEL_URL) {
-        throw new VercelOidcContextError(error);
-      } else {
-        throw new LocalOidcContextError(error);
-      }
-    }
-    return await cachedGenerateCredentials(opts);
-  }
-}
-
-/**
- * Allow to get credentials to access the Vercel API. Credentials can be
- * provided in two different ways:
- *
- * 1. By passing an object with the `teamId`, `token`, and `projectId` properties.
- * 2. By using an environment variable VERCEL_OIDC_TOKEN.
- *
- * If both methods are used, the object properties take precedence over the
- * environment variable. If neither method is used, an error is thrown.
- */
-export async function getCredentials(params?: unknown): Promise<Credentials> {
-  const credentials = getCredentialsFromParams(params ?? {});
-  if (credentials) {
-    return credentials;
-  }
-
-  const oidcToken = await getVercelToken({
-    teamId:
-      params &&
-      typeof params === "object" &&
-      "teamId" in params &&
-      typeof params.teamId === "string"
-        ? params.teamId
-        : undefined,
-    projectId:
-      params &&
-      typeof params === "object" &&
-      "projectId" in params &&
-      typeof params.projectId === "string"
-        ? params.projectId
-        : undefined,
-  });
-
-  return oidcToken;
-}
-
-/**
- * Attempt to extract credentials from the provided parameters. Either all
- * required fields (`token`, `teamId`, and `projectId`) must be present
- * or none of them, otherwise an error is thrown.
- */
-function getCredentialsFromParams(params: unknown): Credentials | null {
-  // Type guard: params must be an object
-  if (!params || typeof params !== "object") {
-    return null;
-  }
-
-  const missing = [
-    "token" in params && typeof params.token === "string" ? null : "token",
-    "teamId" in params && typeof params.teamId === "string" ? null : "teamId",
-    "projectId" in params && typeof params.projectId === "string"
-      ? null
-      : "projectId",
-  ].filter((value) => value !== null);
-
-  if (missing.length === 0) {
-    return {
-      token: (params as any).token,
-      projectId: (params as any).projectId,
-      teamId: (params as any).teamId,
-    };
-  }
-
-  if (missing.length < 3) {
-    throw new Error(
-      `Missing credentials parameters to access the Vercel API: ${missing
-        .filter((value) => value !== null)
-        .join(", ")}`,
-    );
-  }
-
-  return null;
-}
-
-/**
- * Schema to validate the payload of the Vercel OIDC token where we expect
- * to find the `teamId` and `projectId`.
- */
-export const schema = z.object({
-  exp: z.number().optional().describe("Expiry timestamp (seconds since epoch)"),
-  iat: z.number().optional().describe("Issued at timestamp"),
-  owner_id: z.string(),
-  project_id: z.string(),
-});
-
-/**
- * Extracts credentials from a Vercel OIDC token. The token is expected to be
- * a JWT with a payload that contains `project_id` and `owner_id`.
- *
- * @param token - The Vercel OIDC token.
- * @returns An object containing the token, projectId, and teamId.
- * @throws If the token is invalid or does not contain the required fields.
- */
-function getCredentialsFromOIDCToken(token: string): Credentials {
-  try {
-    const payload = schema.parse(decodeBase64Url(token.split(".")[1]));
-    return {
-      token,
-      projectId: payload.project_id,
-      teamId: payload.owner_id,
-    };
-  } catch (error) {
-    throw new Error(
-      `Invalid Vercel OIDC token: ${error instanceof Error ? error.message : String(error)}`,
-    );
-  }
-}