@vercel/sandbox 1.1.4 → 1.1.6

package/src/auth/linked-project.test.ts

@@ -0,0 +1,86 @@
+import { readLinkedProject } from "./linked-project";
+import { describe, test, expect } from "vitest";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+
+async function withTempDir(fn: (dir: string) => Promise<void>): Promise<void> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "linked-project-test-"));
+  try {
+    await fn(dir);
+  } finally {
+    await fs.rm(dir, { recursive: true });
+  }
+}
+
+describe("readLinkedProject", () => {
+  test("returns null when .vercel/project.json does not exist", async () => {
+    await withTempDir(async (dir) => {
+      const result = await readLinkedProject(dir);
+      expect(result).toBeNull();
+    });
+  });
+
+  test("returns null when .vercel directory exists but project.json does not", async () => {
+    await withTempDir(async (dir) => {
+      await fs.mkdir(path.join(dir, ".vercel"));
+      const result = await readLinkedProject(dir);
+      expect(result).toBeNull();
+    });
+  });
+
+  test("returns projectId and teamId when project.json exists", async () => {
+    await withTempDir(async (dir) => {
+      await fs.mkdir(path.join(dir, ".vercel"));
+      await fs.writeFile(
+        path.join(dir, ".vercel", "project.json"),
+        JSON.stringify({
+          projectId: "prj_123",
+          orgId: "team_456",
+          settings: { framework: null },
+        }),
+      );
+      const result = await readLinkedProject(dir);
+      expect(result).toEqual({
+        projectId: "prj_123",
+        teamId: "team_456",
+      });
+    });
+  });
+
+  test("returns null when project.json is invalid JSON", async () => {
+    await withTempDir(async (dir) => {
+      await fs.mkdir(path.join(dir, ".vercel"));
+      await fs.writeFile(
+        path.join(dir, ".vercel", "project.json"),
+        "not valid json",
+      );
+      const result = await readLinkedProject(dir);
+      expect(result).toBeNull();
+    });
+  });
+
+  test("returns null when project.json is missing projectId", async () => {
+    await withTempDir(async (dir) => {
+      await fs.mkdir(path.join(dir, ".vercel"));
+      await fs.writeFile(
+        path.join(dir, ".vercel", "project.json"),
+        JSON.stringify({ orgId: "team_456" }),
+      );
+      const result = await readLinkedProject(dir);
+      expect(result).toBeNull();
+    });
+  });
+
+  test("returns null when project.json is missing orgId", async () => {
+    await withTempDir(async (dir) => {
+      await fs.mkdir(path.join(dir, ".vercel"));
+      await fs.writeFile(
+        path.join(dir, ".vercel", "project.json"),
+        JSON.stringify({ projectId: "prj_123" }),
+      );
+      const result = await readLinkedProject(dir);
+      expect(result).toBeNull();
+    });
+  });
+});

package/src/auth/linked-project.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { json } from "./zod";
+
+const LinkedProjectSchema = json.pipe(
+  z.object({
+    projectId: z.string(),
+    orgId: z.string(),
+  }),
+);
+
+/**
+ * Reads the linked project configuration from `.vercel/project.json`.
+ *
+ * @param cwd - The directory to search for `.vercel/project.json`.
+ * @returns The linked project's `projectId` and `teamId`, or `null` if not found.
+ */
+export async function readLinkedProject(
+  cwd: string,
+): Promise<{ projectId: string; teamId: string } | null> {
+  const projectJsonPath = path.join(cwd, ".vercel", "project.json");
+
+  let content: string;
+  try {
+    content = await fs.readFile(projectJsonPath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const parsed = LinkedProjectSchema.safeParse(content);
+  if (!parsed.success) {
+    return null;
+  }
+
+  return {
+    projectId: parsed.data.projectId,
+    teamId: parsed.data.orgId,
+  };
+}

package/src/auth/oauth.ts

@@ -0,0 +1,333 @@
+import os from "os";
+import { z } from "zod";
+import { VERSION } from "../version";
+
+const USER_AGENT = `${os.hostname()} @ vercel/sandbox/${VERSION} node-${
+  process.version
+} ${os.platform()} (${os.arch()})`;
+
+const ISSUER = new URL("https://vercel.com");
+const CLIENT_ID = "cl_HYyOPBNtFMfHhaUn9L4QPfTZz6TP47bp";
+
+const AuthorizationServerMetadata = z.object({
+  issuer: z.string().url(),
+  device_authorization_endpoint: z.string().url(),
+  token_endpoint: z.string().url(),
+  revocation_endpoint: z.string().url(),
+  jwks_uri: z.string().url(),
+  introspection_endpoint: z.string().url(),
+});
+type AuthorizationServerMetadata = z.infer<typeof AuthorizationServerMetadata>;
+let _as: AuthorizationServerMetadata;
+
+const DeviceAuthorization = z.object({
+  device_code: z.string(),
+  user_code: z.string(),
+  verification_uri: z.string().url(),
+  verification_uri_complete: z.string().url(),
+  expires_in: z.number(),
+  interval: z.number(),
+});
+
+const IntrospectionResponse = z
+  .object({
+    active: z.literal(true),
+    client_id: z.string(),
+    session_id: z.string(),
+  })
+  .or(z.object({ active: z.literal(false) }));
+
+/**
+ * Returns the Authorization Server Metadata
+ *
+ * @see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest
+ * @see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse
+ */
+async function authorizationServerMetadata(): Promise<AuthorizationServerMetadata> {
+  if (_as) return _as;
+
+  const response = await fetch(
+    new URL(".well-known/openid-configuration", ISSUER),
+    {
+      headers: { "Content-Type": "application/json", "user-agent": USER_AGENT },
+    },
+  );
+
+  _as = AuthorizationServerMetadata.parse(await response.json());
+  return _as;
+}
+
+export async function OAuth() {
+  const as = await authorizationServerMetadata();
+  return {
+    /**
+     * Perform the Device Authorization Request
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.1
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.2
+     */
+    async deviceAuthorizationRequest(): Promise<DeviceAuthorizationRequest> {
+      const response = await fetch(as.device_authorization_endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          "user-agent": USER_AGENT,
+        },
+        body: new URLSearchParams({
+          client_id: CLIENT_ID,
+          scope: "openid offline_access",
+        }),
+      });
+
+      const json = await response.json();
+      const parsed = DeviceAuthorization.safeParse(json);
+
+      if (!parsed.success) {
+        throw new OAuthError(
+          `Failed to parse device authorization response: ${parsed.error.message}`,
+          json,
+        );
+      }
+
+      return {
+        device_code: parsed.data.device_code,
+        user_code: parsed.data.user_code,
+        verification_uri: parsed.data.verification_uri,
+        verification_uri_complete: parsed.data.verification_uri_complete,
+        expiresAt: Date.now() + parsed.data.expires_in * 1000,
+        interval: parsed.data.interval,
+      };
+    },
+    /**
+     * Perform the Device Access Token Request
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.4
+     */
+    async deviceAccessTokenRequest(
+      device_code: string,
+    ): Promise<[Error] | [null, Response]> {
+      try {
+        return [
+          null,
+          await fetch(as.token_endpoint, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/x-www-form-urlencoded",
+              "user-agent": USER_AGENT,
+            },
+            body: new URLSearchParams({
+              client_id: CLIENT_ID,
+              grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+              device_code,
+            }),
+            signal: AbortSignal.timeout(10 * 1000),
+          }),
+        ];
+      } catch (error) {
+        if (error instanceof Error) return [error];
+        return [
+          new Error("An unknown error occurred. See the logs for details.", {
+            cause: error,
+          }),
+        ];
+      }
+    },
+    /**
+     * Process the Token request Response
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
+     */
+    async processTokenResponse(
+      response: Response,
+    ): Promise<[OAuthError] | [null, TokenSet]> {
+      const json = await response.json();
+      const processed = TokenSet.safeParse(json);
+
+      if (!processed.success) {
+        return [
+          new OAuthError(
+            `Failed to parse token response: ${processed.error.message}`,
+            json,
+          ),
+        ];
+      }
+
+      return [null, processed.data];
+    },
+    /**
+     * Perform a Token Revocation Request.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc7009#section-2.1
+     * @see https://datatracker.ietf.org/doc/html/rfc7009#section-2.2
+     */
+    async revokeToken(token: string): Promise<OAuthError | void> {
+      const response = await fetch(as.revocation_endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          "user-agent": USER_AGENT,
+        },
+        body: new URLSearchParams({ token, client_id: CLIENT_ID }),
+      });
+
+      if (response.ok) return;
+      const json = await response.json();
+
+      return new OAuthError("Revocation request failed", json);
+    },
+    /**
+     * Perform Refresh Token Request.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc6749#section-6
+     */
+    async refreshToken(token: string): Promise<TokenSet> {
+      const response = await fetch(as.token_endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          "user-agent": USER_AGENT,
+        },
+        body: new URLSearchParams({
+          client_id: CLIENT_ID,
+          grant_type: "refresh_token",
+          refresh_token: token,
+        }),
+      });
+
+      const [tokensError, tokenSet] = await this.processTokenResponse(response);
+      if (tokensError) throw tokensError;
+      return tokenSet;
+    },
+    /**
+     * Perform Token Introspection Request.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc7662#section-2.1
+     */
+    async introspectToken(
+      token: string,
+    ): Promise<z.infer<typeof IntrospectionResponse>> {
+      const response = await fetch(as.introspection_endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          "user-agent": USER_AGENT,
+        },
+        body: new URLSearchParams({ token }),
+      });
+
+      const json = await response.json();
+      const processed = IntrospectionResponse.safeParse(json);
+      if (!processed.success) {
+        throw new OAuthError(
+          `Failed to parse introspection response: ${processed.error.message}`,
+          json,
+        );
+      }
+
+      return processed.data;
+    },
+  };
+}
+
+export type OAuth = Awaited<ReturnType<typeof OAuth>>;
+
+const TokenSet = z.object({
+  /** The access token issued by the authorization server. */
+  access_token: z.string(),
+  /** The type of the token issued */
+  token_type: z.literal("Bearer"),
+  /** The lifetime in seconds of the access token. */
+  expires_in: z.number(),
+  /** The refresh token, which can be used to obtain new access tokens. */
+  refresh_token: z.string().optional(),
+  /** The scope of the access token. */
+  scope: z.string().optional(),
+});
+
+type TokenSet = z.infer<typeof TokenSet>;
+
+const OAuthErrorResponse = z.object({
+  error: z.enum([
+    "invalid_request",
+    "invalid_client",
+    "invalid_grant",
+    "unauthorized_client",
+    "unsupported_grant_type",
+    "invalid_scope",
+    "server_error",
+    // Device Authorization Response Errors
+    "authorization_pending",
+    "slow_down",
+    "access_denied",
+    "expired_token",
+    // Revocation Response Errors
+    "unsupported_token_type",
+  ]),
+  error_description: z.string().optional(),
+  error_uri: z.string().optional(),
+});
+
+type OAuthErrorResponse = z.infer<typeof OAuthErrorResponse>;
+
+function processOAuthErrorResponse(
+  json: unknown,
+): OAuthErrorResponse | TypeError {
+  try {
+    return OAuthErrorResponse.parse(json);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return new TypeError(`Invalid OAuth error response: ${error.message}`);
+    }
+    return new TypeError("Failed to parse OAuth error response");
+  }
+}
+
+class OAuthError extends Error {
+  name = "OAuthError";
+  code: OAuthErrorResponse["error"];
+  cause: Error;
+  constructor(message: string, response: unknown) {
+    super(message);
+    const error = processOAuthErrorResponse(response);
+    if (error instanceof TypeError) {
+      const message = `Unexpected server response: ${JSON.stringify(response)}`;
+      this.cause = new Error(message, { cause: error });
+      this.code = "server_error";
+      return;
+    }
+    let cause = error.error;
+    if (error.error_description) cause += `: ${error.error_description}`;
+    if (error.error_uri) cause += ` (${error.error_uri})`;
+
+    this.cause = new Error(cause);
+    this.code = error.error;
+  }
+}
+
+export function isOAuthError(error: unknown): error is OAuthError {
+  return error instanceof OAuthError;
+}
+
+export interface DeviceAuthorizationRequest {
+  /** The device verification code. */
+  device_code: string;
+  /** The end-user verification code. */
+  user_code: string;
+  /**
+   * The minimum amount of time in seconds that the client
+   * SHOULD wait between polling requests to the token endpoint.
+   */
+  interval: number;
+  /** The end-user verification URI on the authorization server. */
+  verification_uri: string;
+  /**
+   * The end-user verification URI on the authorization server,
+   * including the `user_code`, without redirection.
+   */
+  verification_uri_complete: string;
+  /**
+   * The absolute lifetime of the `device_code` and `user_code`.
+   * Calculated from `expires_in`.
+   */
+  expiresAt: number;
+}

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