@vercel/sandbox 1.2.0 → 1.2.1

package/src/snapshot.ts

@@ -1,110 +0,0 @@
-import type { SnapshotMetadata } from "./api-client";
-import { APIClient } from "./api-client";
-import { Credentials, getCredentials } from "./utils/get-credentials";
-
-/** @inline */
-interface GetSnapshotParams {
-  /**
-   * Unique identifier of the snapshot.
-   */
-  snapshotId: string;
-  /**
-   * An AbortSignal to cancel the operation.
-   */
-  signal?: AbortSignal;
-}
-
-/**
- * A Snapshot is a saved state of a Sandbox that can be used to create new Sandboxes
- *
- * Use {@link Sandbox.snapshot} or {@link Snapshot.get} to construct.
- * @hideconstructor
- */
-export class Snapshot {
-  private readonly client: APIClient;
-
-  /**
-   * Unique ID of this snapshot.
-   */
-  public get snapshotId(): string {
-    return this.snapshot.id;
-  }
-
-  /**
-   * The ID the sandbox from which this snapshot was created.
-   */
-  public get sourceSandboxId(): string {
-    return this.snapshot.sourceSandboxId;
-  }
-
-  /**
-   * The status of the snapshot.
-   */
-  public get status(): SnapshotMetadata["status"] {
-    return this.snapshot.status;
-  }
-
-  /**
-   * Internal metadata about this snapshot.
-   */
-  private snapshot: SnapshotMetadata;
-
-  /**
-   * Create a new Snapshot instance.
-   *
-   * @param client - API client used to communicate with the backend
-   * @param snapshot - Snapshot metadata
-   */
-  constructor({
-    client,
-    snapshot,
-  }: {
-    client: APIClient;
-    snapshot: SnapshotMetadata;
-  }) {
-    this.client = client;
-    this.snapshot = snapshot;
-  }
-
-  /**
-   * Retrieve an existing snapshot.
-   *
-   * @param params - Get parameters and optional credentials.
-   * @returns A promise resolving to the {@link Sandbox}.
-   */
-  static async get(
-    params: GetSnapshotParams | (GetSnapshotParams & Credentials),
-  ): Promise<Snapshot> {
-    const credentials = await getCredentials(params);
-    const client = new APIClient({
-      teamId: credentials.teamId,
-      token: credentials.token,
-    });
-
-    const sandbox = await client.getSnapshot({
-      snapshotId: params.snapshotId,
-      signal: params.signal,
-    });
-
-    return new Snapshot({
-      client,
-      snapshot: sandbox.json.snapshot,
-    });
-  }
-
-  /**
-   * Delete this snapshot.
-   *
-   * @param opts - Optional parameters.
-   * @param opts.signal - An AbortSignal to cancel the operation.
-   * @returns A promise that resolves once the snapshot has been deleted.
-   */
-  async delete(opts?: { signal?: AbortSignal }): Promise<void> {
-    const response = await this.client.deleteSnapshot({
-      snapshotId: this.snapshot.id,
-      signal: opts?.signal,
-    });
-
-    this.snapshot = response.json.snapshot;
-  }
-}

package/src/utils/array.ts

@@ -1,15 +0,0 @@
-/**
- * Returns an array from the given item. If the  item is an array it will be
- * returned as a it is, otherwise it will be returned as a single item array.
- * If the item is undefined or null an empty array will be returned.
- *
- * @param item The item to convert to an array.
- * @returns An array.
- */
-export function array<T>(item?: null | T | T[]): T[] {
-  return item !== undefined && item !== null
-    ? Array.isArray(item)
-      ? item
-      : [item]
-    : [];
-}

package/src/utils/consume-readable.ts

@@ -1,12 +0,0 @@
-/**
- * Consumes a readable entirely concatenating all content in a single Buffer
- * @param readable A Readable stream
- */
-export function consumeReadable(readable: NodeJS.ReadableStream) {
-  return new Promise<Buffer>((resolve, reject) => {
-    const chunks: Buffer[] = [];
-    readable.on("error", (err) => reject(err));
-    readable.on("data", (chunk) => chunks.push(chunk));
-    readable.on("end", () => resolve(Buffer.concat(chunks)));
-  });
-}

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);
-});