@vercel/sandbox 1.1.4 → 1.1.6

package/src/command.ts

@@ -33,6 +33,14 @@ export class Command {
 
   public exitCode: number | null;
 
+  private outputCache: { stdout: string; stderr: string; both: string } | null =
+    null;
+  private outputCachePromise: Promise<{
+    stdout: string;
+    stderr: string;
+    both: string;
+  }> | null = null;
+
   /**
    * ID of the command execution.
    */
@@ -134,6 +142,46 @@ export class Command {
     });
   }
 
+  /**
+   * Get cached output, fetching logs only once and reusing for concurrent calls.
+   * This prevents race conditions when stdout() and stderr() are called in parallel.
+   */
+  private async getCachedOutput(opts?: { signal?: AbortSignal }): Promise<{
+    stdout: string;
+    stderr: string;
+    both: string;
+  }> {
+    if (this.outputCache) {
+      return this.outputCache;
+    }
+
+    if (!this.outputCachePromise) {
+      this.outputCachePromise = (async () => {
+        try {
+          let stdout = "";
+          let stderr = "";
+          let both = "";
+          for await (const log of this.logs({ signal: opts?.signal })) {
+            both += log.data;
+            if (log.stream === "stdout") {
+              stdout += log.data;
+            } else {
+              stderr += log.data;
+            }
+          }
+          this.outputCache = { stdout, stderr, both };
+          return this.outputCache;
+        } catch (err) {
+          // Clear the promise so future calls can retry
+          this.outputCachePromise = null;
+          throw err;
+        }
+      })();
+    }
+
+    return this.outputCachePromise;
+  }
+
   /**
    * Get the output of `stdout`, `stderr`, or both as a string.
    *
@@ -149,13 +197,8 @@ export class Command {
     stream: "stdout" | "stderr" | "both" = "both",
     opts?: { signal?: AbortSignal },
   ) {
-    let data = "";
-    for await (const log of this.logs({ signal: opts?.signal })) {
-      if (stream === "both" || log.stream === stream) {
-        data += log.data;
-      }
-    }
-    return data;
+    const cached = await this.getCachedOutput(opts);
+    return cached[stream];
   }
 
   /**

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

package/src/utils/get-credentials.ts

@@ -1,6 +1,10 @@
 import { getVercelOidcToken } from "@vercel/oidc";
 import { decodeBase64Url } from "./decode-base64-url";
 import { z } from "zod";
+import {
+  cachedGenerateCredentials,
+  shouldPromptForCredentials,
+} from "./dev-credentials";
 
 export interface Credentials {
   /**
@@ -18,6 +22,57 @@ export interface Credentials {
   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.",
+    ].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",
+      "Read more at 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:
@@ -34,15 +89,24 @@ export async function getCredentials(params?: unknown): Promise<Credentials> {
     return credentials;
   }
 
-  const oidcToken = await getVercelOidcToken();
-  if (oidcToken) {
-    return getCredentialsFromOIDCToken(oidcToken);
-  }
+  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,
+  });
 
-  throw new Error(
-    "You must provide credentials to access the Vercel API \n" +
-      "either through parameters or using OpenID Connect [https://vercel.com/docs/oidc]",
-  );
+  return oidcToken;
 }
 
 /**

package/src/utils/log.ts

@@ -0,0 +1,20 @@
+import pico from "picocolors";
+const colors = {
+  warn: pico.yellow,
+  error: pico.red,
+  success: pico.green,
+  info: pico.blue,
+};
+const logPrefix = pico.dim("[vercel/sandbox]");
+export function write(
+  level: "warn" | "error" | "info" | "success",
+  text: string | string[],
+) {
+  text = Array.isArray(text) ? text.join("\n") : text;
+  const prefixed = text.replace(/^/gm, `${logPrefix} `);
+  console.error(colors[level](prefixed));
+}
+
+export function code(text: string) {
+  return pico.italic(pico.dim("`") + text + pico.dim("`"));
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 // Autogenerated by inject-version.ts
-export const VERSION = "1.1.4";
+export const VERSION = "1.1.6";

package/test-utils/mock-response.ts

@@ -0,0 +1,12 @@
+export function createNdjsonStream(
+  lines: object[],
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  const ndjson = lines.map((line) => JSON.stringify(line)).join("\n") + "\n";
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(encoder.encode(ndjson));
+      controller.close();
+    },
+  });
+}

package/vitest.config.ts

@@ -2,6 +2,7 @@ import { defineConfig } from "vitest/config";
 
 export default defineConfig({
   test: {
+    env: { FORCE_COLOR: "1" },
     setupFiles: ["./vitest.setup.ts"],
     testTimeout: 60_000,
   },