@vercel/sandbox 0.0.16 → 0.0.18

package/dist/utils/normalizePath.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Normalize a path and make it relative to `params.extractDir` for inclusion
+ * in our tar archives.
+ *
+ * Relative paths are first resolved to `params.cwd`.
+ * Absolute paths are normalized and resolved relative to `params.extractDir`.
+ *
+ * In addition, paths are normalized so consecutive slashes are removed and
+ * stuff like `../..` is resolved appropriately.
+ *
+ * This function always returns a path relative to `params.extractDir`.
+ */
+export declare function normalizePath(params: {
+    filePath: string;
+    cwd: string;
+    extractDir: string;
+}): string;

package/dist/utils/normalizePath.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePath = normalizePath;
+const path_1 = __importDefault(require("path"));
+/**
+ * Normalize a path and make it relative to `params.extractDir` for inclusion
+ * in our tar archives.
+ *
+ * Relative paths are first resolved to `params.cwd`.
+ * Absolute paths are normalized and resolved relative to `params.extractDir`.
+ *
+ * In addition, paths are normalized so consecutive slashes are removed and
+ * stuff like `../..` is resolved appropriately.
+ *
+ * This function always returns a path relative to `params.extractDir`.
+ */
+function normalizePath(params) {
+    if (!path_1.default.posix.isAbsolute(params.cwd)) {
+        throw new Error("cwd dir must be absolute");
+    }
+    if (!path_1.default.posix.isAbsolute(params.extractDir)) {
+        throw new Error("extractDir must be absolute");
+    }
+    const basePath = path_1.default.posix.isAbsolute(params.filePath)
+        ? path_1.default.posix.normalize(params.filePath)
+        : path_1.default.posix.join(params.cwd, params.filePath);
+    return path_1.default.posix.relative(params.extractDir, basePath);
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.16";
+export declare const VERSION = "0.0.18";

package/dist/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // Autogenerated by inject-version.ts
-exports.VERSION = "0.0.16";
+exports.VERSION = "0.0.18";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@vercel/oidc": "^2.0.0",
+    "@vercel/oidc": "^2.0.2",
     "async-retry": "1.3.3",
     "jsonlines": "0.1.1",
     "ms": "2.1.3",

package/src/api-client/api-client.ts

@@ -20,9 +20,12 @@ import { z } from "zod";
 import jsonlines from "jsonlines";
 import os from "os";
 import { Readable } from "stream";
+import { normalizePath } from "../utils/normalizePath";
+import { JwtExpiry } from "../utils/jwt-expiry";
 
 export class APIClient extends BaseClient {
   private teamId: string;
+  private tokenExpiry: JwtExpiry | null;
 
   constructor(params: { host?: string; teamId: string; token: string }) {
     super({
@@ -32,9 +35,29 @@ export class APIClient extends BaseClient {
     });
 
     this.teamId = params.teamId;
+    this.tokenExpiry = JwtExpiry.fromToken(params.token);
+  }
+
+  private async ensureValidToken(): Promise<void> {
+    if (!this.tokenExpiry) {
+      return;
+    }
+
+    const newExpiry = await this.tokenExpiry.tryRefresh();
+    if (!newExpiry) {
+      return;
+    }
+
+    this.tokenExpiry = newExpiry;
+    this.token = this.tokenExpiry.token;
+    if (this.tokenExpiry.payload) {
+      this.teamId = this.tokenExpiry.payload?.owner_id;
+    }
   }
 
   protected async request(path: string, params?: RequestParams) {
+    await this.ensureValidToken();
+
     return super.request(path, {
       ...params,
       query: { teamId: this.teamId, ...params?.query },
@@ -150,13 +173,16 @@ export class APIClient extends BaseClient {
     );
   }
 
-  getFileWriter(params: { sandboxId: string }) {
+  getFileWriter(params: { sandboxId: string; extractDir: string }) {
     const writer = new FileWriter();
     return {
       response: (async () => {
         return this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
           method: "POST",
-          headers: { "content-type": "application/gzip" },
+          headers: {
+            "content-type": "application/gzip",
+            "x-cwd": params.extractDir,
+          },
           body: await consumeReadable(writer.readable),
         });
       })(),
@@ -166,14 +192,24 @@ export class APIClient extends BaseClient {
 
   async writeFiles(params: {
     sandboxId: string;
+    cwd: string;
     files: { path: string; content: Buffer }[];
+    extractDir: string;
   }) {
     const { writer, response } = this.getFileWriter({
       sandboxId: params.sandboxId,
+      extractDir: params.extractDir,
     });
 
     for (const file of params.files) {
-      await writer.addFile({ name: file.path, content: file.content });
+      await writer.addFile({
+        name: normalizePath({
+          filePath: file.path,
+          extractDir: params.extractDir,
+          cwd: params.cwd,
+        }),
+        content: file.content,
+      });
     }
 
     writer.end();

package/src/api-client/validators.ts

@@ -16,6 +16,7 @@ export const Sandbox = z.object({
   stoppedAt: z.number().optional(),
   duration: z.number().optional(),
   createdAt: z.number(),
+  cwd: z.string(),
   updatedAt: z.number(),
 });
 

package/src/command.ts

@@ -4,8 +4,11 @@ import { Signal, resolveSignal } from "./utils/resolveSignal";
 /**
  * A command executed in a Sandbox.
  *
- * You can {@link wait} on commands to access their {@link CommandFinished.exitCode}, and
- * iterate over their output with {@link logs}.
+ * For detached commands, you can {@link wait} to get a {@link CommandFinished} instance
+ * with the populated exit code. For non-detached commands, {@link Sandbox.runCommand}
+ * automatically waits and returns a {@link CommandFinished} instance.
+ *
+ * You can iterate over command output with {@link logs}.
  *
  * @see {@link Sandbox.runCommand} to start a command.
  *
@@ -94,9 +97,14 @@ export class Command {
   /**
    * Wait for a command to exit and populate its exit code.
    *
+   * This method is useful for detached commands where you need to wait
+   * for completion. For non-detached commands, {@link Sandbox.runCommand}
+   * automatically waits and returns a {@link CommandFinished} instance.
+   *
    * ```
-   * await cmd.wait()
-   * if (cmd.exitCode != 0) {
+   * const detachedCmd = await sandbox.runCommand({ cmd: 'sleep', args: ['5'], detached: true });
+   * const result = await detachedCmd.wait();
+   * if (result.exitCode !== 0) {
    *   console.error("Something went wrong...")
    * }
    * ```
@@ -180,14 +188,16 @@ export class Command {
 /**
  * A command that has finished executing.
  *
- * Contains the exit code of the command.
+ * The exit code is immediately available and populated upon creation.
+ * Unlike {@link Command}, you don't need to call wait() - the command
+ * has already completed execution.
  *
  * @hideconstructor
  */
 export class CommandFinished extends Command {
   /**
-   * The exit code of the command, if available. This is set after
-   * {@link wait} has returned.
+   * The exit code of the command. This is always populated for
+   * CommandFinished instances.
    */
   public exitCode: number;
 
@@ -207,4 +217,16 @@ export class CommandFinished extends Command {
     super({ ...params });
     this.exitCode = params.exitCode;
   }
+
+  /**
+   * The wait method is not needed for CommandFinished instances since
+   * the command has already completed and exitCode is populated.
+   *
+   * @deprecated This method is redundant for CommandFinished instances.
+   * The exitCode is already available.
+   * @returns This CommandFinished instance.
+   */
+  async wait(): Promise<CommandFinished> {
+    return this;
+  }
 }

package/src/sandbox.test.ts

@@ -2,10 +2,11 @@ import { it, beforeEach, afterEach, expect } from "vitest";
 import { consumeReadable } from "./utils/consume-readable";
 import { Sandbox } from "./sandbox";
 
+const PORTS = [3000, 4000];
 let sandbox: Sandbox;
 
 beforeEach(async () => {
-  sandbox = await Sandbox.create();
+  sandbox = await Sandbox.create({ ports: PORTS });
 });
 
 afterEach(async () => {
@@ -23,3 +24,43 @@ it("allows to write files and then read them", async () => {
   expect((await consumeReadable(content1!)).toString()).toBe("Hello 1");
   expect((await consumeReadable(content2!)).toString()).toBe("Hello 2");
 });
+
+it("verifies port forwarding works correctly", async () => {
+  const serverScript = `
+const http = require('http');
+const ports = process.argv.slice(2);
+
+for (const port of ports) {
+  const server = http.createServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end(\`hello port \${port}\`);
+  });
+
+  server.listen(port, () => {
+    console.log(\`Server running on port \${port}\`);
+  });
+}
+`;
+
+  await sandbox.writeFiles([
+    { path: "server.js", content: Buffer.from(serverScript) },
+  ]);
+
+  const server = await sandbox.runCommand({
+    cmd: "node",
+    args: ["server.js", ...PORTS.map(String)],
+    detached: true,
+    stdout: process.stdout,
+    stderr: process.stderr,
+  });
+
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+
+  for (const port of PORTS) {
+    const response = await fetch(sandbox.domain(port));
+    const text = await response.text();
+    expect(text).toBe(`hello port ${port}`);
+  }
+
+  await server.kill();
+});

package/src/sandbox.ts

@@ -32,7 +32,8 @@ export interface CreateSandboxParams {
       }
     | { type: "tarball"; url: string };
   /**
-   * Array of port numbers to expose from the sandbox.
+   * Array of port numbers to expose from the sandbox. Sandboxes can
+   * expose up to 4 ports.
    */
   ports?: number[];
   /**
@@ -141,7 +142,7 @@ export class Sandbox {
   static async create(
     params?: CreateSandboxParams | (CreateSandboxParams & Credentials),
   ): Promise<Sandbox> {
-    const credentials = getCredentials(params);
+    const credentials = await getCredentials(params);
     const client = new APIClient({
       teamId: credentials.teamId,
       token: credentials.token,
@@ -172,7 +173,7 @@ export class Sandbox {
   static async get(
     params: GetSandboxParams | (GetSandboxParams & Credentials),
   ): Promise<Sandbox> {
-    const credentials = getCredentials(params);
+    const credentials = await getCredentials(params);
     const client = new APIClient({
       teamId: credentials.teamId,
       token: credentials.token,
@@ -331,6 +332,8 @@ export class Sandbox {
 
   /**
    * Write files to the filesystem of this sandbox.
+   * Defaults to writing to /vercel/sandbox unless an absolute path is specified.
+   * Writes files using the `vercel-sandbox` user.
    *
    * @param files - Array of files with path and stream/buffer contents
    * @returns A promise that resolves when the files are written
@@ -338,6 +341,8 @@ export class Sandbox {
   async writeFiles(files: { path: string; content: Buffer }[]) {
     return this.client.writeFiles({
       sandboxId: this.sandbox.id,
+      cwd: this.sandbox.cwd,
+      extractDir: "/",
       files: files,
     });
   }

package/src/utils/get-credentials.ts

@@ -1,4 +1,4 @@
-import { getVercelOidcTokenSync } from "@vercel/oidc";
+import { getVercelOidcToken } from "@vercel/oidc";
 import { decodeBase64Url } from "./decode-base64-url";
 import { z } from "zod";
 
@@ -28,13 +28,13 @@ export interface Credentials {
  * If both methods are used, the object properties take precedence over the
  * environment variable. If neither method is used, an error is thrown.
  */
-export function getCredentials<T>(params?: T | Credentials): Credentials {
+export async function getCredentials(params?: unknown): Promise<Credentials> {
   const credentials = getCredentialsFromParams(params ?? {});
   if (credentials) {
     return credentials;
   }
 
-  const oidcToken = getVercelOidcTokenSync();
+  const oidcToken = await getVercelOidcToken();
   if (oidcToken) {
     return getCredentialsFromOIDCToken(oidcToken);
   }
@@ -50,9 +50,12 @@ export function getCredentials<T>(params?: T | Credentials): Credentials {
  * required fields (`token`, `teamId`, and `projectId`) must be present
  * or none of them, otherwise an error is thrown.
  */
-function getCredentialsFromParams<Params extends Record<string, unknown>>(
-  params: Params | Credentials,
-): Credentials | null {
+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",
@@ -63,9 +66,9 @@ function getCredentialsFromParams<Params extends Record<string, unknown>>(
 
   if (missing.length === 0) {
     return {
-      token: params.token as string,
-      projectId: params.projectId as string,
-      teamId: params.teamId as string,
+      token: (params as any).token,
+      projectId: (params as any).projectId,
+      teamId: (params as any).teamId,
     };
   }
 
@@ -84,7 +87,9 @@ function getCredentialsFromParams<Params extends Record<string, unknown>>(
  * Schema to validate the payload of the Vercel OIDC token where we expect
  * to find the `teamId` and `projectId`.
  */
-const schema = z.object({
+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(),
 });

package/src/utils/jwt-expiry.test.ts

@@ -0,0 +1,125 @@
+import { assert, beforeEach, describe, expect, test, vi } from "vitest";
+import { JwtExpiry } from "./jwt-expiry";
+import type { getVercelOidcToken } from "@vercel/oidc";
+
+const { getVercelOidcTokenMock } = vi.hoisted(() => {
+  return {
+    getVercelOidcTokenMock: vi.fn<typeof getVercelOidcToken>(),
+  };
+});
+vi.mock("@vercel/oidc", () => ({
+  getVercelOidcToken: getVercelOidcTokenMock,
+}));
+beforeEach(() => {
+  getVercelOidcTokenMock.mockReset();
+});
+
+describe("JwtExpiry", () => {
+  test("refreshes a token", async () => {
+    const token = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+    });
+    getVercelOidcTokenMock.mockImplementationOnce(async () => "hello world");
+    const expiry = await JwtExpiry.fromToken(token)?.refresh();
+    expect(expiry).toBeInstanceOf(JwtExpiry);
+    expect(expiry?.token).toEqual("hello world");
+  });
+
+  test("isValid returns true for tokens without expiry", () => {
+    // Mock token without exp field (like OIDC tokens without exp)
+    const tokenWithoutExp = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+    });
+    const expiry = JwtExpiry.fromToken(tokenWithoutExp);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid()).toBe(false); // No exp field means malformed JWT
+  });
+
+  test("isValid returns true for unexpired tokens", () => {
+    const futureTime = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
+    const tokenValid = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+      exp: futureTime,
+    });
+    const expiry = JwtExpiry.fromToken(tokenValid);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid()).toBe(true);
+  });
+
+  test("isValid returns false for expired tokens", () => {
+    const pastTime = Math.floor(Date.now() / 1000) - 3600; // 1 hour ago
+    const tokenExpired = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+      exp: pastTime,
+    });
+    const expiry = JwtExpiry.fromToken(tokenExpired);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid()).toBe(false);
+  });
+
+  test("isValid returns false for tokens expiring within buffer time", () => {
+    const soonTime = Math.floor(Date.now() / 1000) + 120; // 2 minutes from now
+    const tokenExpiringSoon = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+      exp: soonTime,
+    });
+    const expiry = JwtExpiry.fromToken(tokenExpiringSoon);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid(5)).toBe(false); // 5 minute buffer
+  });
+
+  test("isValid returns false for malformed JWT tokens", () => {
+    const expiry = JwtExpiry.fromToken("header.invalid-payload.signature");
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid()).toBe(false);
+  });
+
+  test("getExpiryDate returns correct expiry date", () => {
+    const expTime = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
+    const token = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+      exp: expTime,
+    });
+    const expiry = JwtExpiry.fromToken(token);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.getExpiryDate()).toEqual(new Date(expTime * 1000));
+  });
+
+  test("getExpiryDate returns null for tokens without expiry", () => {
+    const token = createMockJWT({ owner_id: "team1", project_id: "proj1" });
+    const expiry = JwtExpiry.fromToken(token);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.getExpiryDate()).toBeNull();
+  });
+
+  test("getExpiryDate returns null for malformed tokens", () => {
+    const token = "hello.world.hey";
+    const expiry = JwtExpiry.fromToken(token);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.getExpiryDate()).toBeNull();
+  });
+
+  test("returns null for non-JWT style tokens", () => {
+    expect(JwtExpiry.fromToken("personal-access-token")).toBeNull();
+  });
+});
+
+// Helper function to create mock JWT tokens for testing
+function createMockJWT(payload: any): string {
+  const header = { typ: "JWT", alg: "HS256" };
+  const encodedHeader = Buffer.from(JSON.stringify(header)).toString(
+    "base64url",
+  );
+  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString(
+    "base64url",
+  );
+  const signature = "mock-signature";
+
+  return `${encodedHeader}.${encodedPayload}.${signature}`;
+}

package/src/utils/jwt-expiry.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { decodeBase64Url } from "./decode-base64-url";
+import { schema } from "./get-credentials";
+import { getVercelOidcToken } from "@vercel/oidc";
+import ms from "ms";
+
+/** Time buffer before token expiry to consider it invalid (in milliseconds) */
+const BUFFER_MS = ms("5m");
+
+export class OidcRefreshError extends Error {
+  name = "OidcRefreshError";
+}
+
+/**
+ * Expiry implementation for JWT tokens (OIDC tokens).
+ * Parses the JWT once and provides fast expiry validation.
+ */
+export class JwtExpiry {
+  private expiryTime: number | null; // Unix timestamp in seconds
+  readonly payload?: Readonly<z.infer<typeof schema>>;
+
+  static fromToken(token: string): JwtExpiry | null {
+    if (!isJwtFormat(token)) {
+      return null;
+    } else {
+      return new JwtExpiry(token);
+    }
+  }
+
+  /**
+   * Creates a new JWT expiry checker.
+   *
+   * @param token - The JWT token to parse
+   */
+  constructor(readonly token: string) {
+    try {
+      const tokenContents = token.split(".")[1];
+      this.payload = schema.parse(decodeBase64Url(tokenContents));
+      this.expiryTime = this.payload.exp || null;
+    } catch {
+      // Malformed token - treat as expired to trigger refresh
+      this.expiryTime = 0;
+    }
+  }
+
+  /**
+   * Checks if the JWT token is valid (not expired).
+   * @returns true if token is valid, false if expired or expiring soon
+   */
+  isValid(): boolean {
+    if (this.expiryTime === null) {
+      return false; // No expiry means malformed JWT
+    }
+
+    const now = Math.floor(Date.now() / 1000);
+    const buffer = BUFFER_MS / 1000;
+    return now + buffer < this.expiryTime;
+  }
+
+  /**
+   * Gets the expiry date of the JWT token.
+   *
+   * @returns Date object representing when the token expires, or null if no expiry
+   */
+  getExpiryDate(): Date | null {
+    return this.expiryTime ? new Date(this.expiryTime * 1000) : null;
+  }
+
+  /**
+   * Refreshes the JWT token by fetching a new OIDC token.
+   *
+   * @returns Promise resolving to a new JwtExpiry instance with fresh token
+   */
+  async refresh(): Promise<JwtExpiry> {
+    try {
+      const freshToken = await getVercelOidcToken();
+      return new JwtExpiry(freshToken);
+    } catch (cause) {
+      throw new OidcRefreshError("Failed to refresh OIDC token", {
+        cause,
+      });
+    }
+  }
+
+  /**
+   * Refreshes the JWT token if it's expired or expiring soon.
+   */
+  async tryRefresh(): Promise<JwtExpiry | null> {
+    if (this.isValid()) {
+      return null; // Still valid, no need to refresh
+    }
+
+    return this.refresh();
+  }
+}
+
+/**
+ * Checks if a token follows JWT format (has 3 parts separated by dots).
+ *
+ * @param token - The token to check
+ * @returns true if token appears to be a JWT, false otherwise
+ */
+function isJwtFormat(token: string): boolean {
+  return token.split(".").length === 3;
+}