eve 0.36.0 → 0.37.0

package/dist/src/compiled/@vercel/sandbox-stable/filesystem.d.ts

@@ -0,0 +1,258 @@
+import { Dirent, Stats } from "fs";
+
+//#region src/filesystem.d.ts
+type WriteFileData = string | Buffer | Uint8Array;
+interface MkdirOptions {
+  recursive?: boolean;
+  signal?: AbortSignal;
+}
+interface RmOptions {
+  recursive?: boolean;
+  force?: boolean;
+  signal?: AbortSignal;
+}
+interface SandboxHandle {
+  readFileToBuffer(file: {
+    path: string;
+  }, opts?: {
+    signal?: AbortSignal;
+  }): Promise<Buffer | null>;
+  writeFiles(files: {
+    path: string;
+    content: Buffer;
+  }[], opts?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  mkDir(path: string, opts?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  runCommand(cmd: string, args?: string[], opts?: {
+    signal?: AbortSignal;
+  }): Promise<{
+    exitCode: number;
+    stdout(opts?: {
+      signal?: AbortSignal;
+    }): Promise<string>;
+    stderr(opts?: {
+      signal?: AbortSignal;
+    }): Promise<string>;
+  }>;
+}
+declare class FileSystem {
+  /** @internal */
+  private sandbox;
+  /** @internal */
+  constructor(sandbox: SandboxHandle);
+  /**
+   * Read the entire contents of a file.
+   *
+   * @param path - Path to the file
+   * @param options - Encoding or options object. If encoding is specified, returns a string; otherwise returns a Buffer.
+   */
+  readFile(path: string, options?: {
+    encoding?: null;
+    signal?: AbortSignal;
+  } | null): Promise<Buffer>;
+  readFile(path: string, options: {
+    encoding: BufferEncoding;
+    signal?: AbortSignal;
+  } | BufferEncoding): Promise<string>;
+  /**
+   * Write data to a file, replacing the file if it already exists.
+   *
+   * @param path - Path to the file
+   * @param data - The data to write
+   * @param options - Write options
+   */
+  writeFile(path: string, data: WriteFileData, options?: {
+    encoding?: BufferEncoding;
+    signal?: AbortSignal;
+  } | BufferEncoding): Promise<void>;
+  /**
+   * Append data to a file, creating the file if it does not yet exist.
+   *
+   * @param path - Path to the file
+   * @param data - The data to append
+   * @param options - Write options
+   */
+  appendFile(path: string, data: WriteFileData, options?: {
+    encoding?: BufferEncoding;
+    signal?: AbortSignal;
+  } | BufferEncoding): Promise<void>;
+  /**
+   * Create a directory.
+   *
+   * @param path - Path of the directory to create
+   * @param options - Options for directory creation
+   */
+  mkdir(path: string, options?: MkdirOptions | number): Promise<string | undefined>;
+  /**
+   * Read the contents of a directory.
+   *
+   * @param path - Path to the directory
+   * @param options - Options. When `withFileTypes` is true, returns `Dirent` objects.
+   */
+  readdir(path: string, options?: {
+    signal?: AbortSignal;
+    withFileTypes?: false;
+  }): Promise<string[]>;
+  readdir(path: string, options: {
+    signal?: AbortSignal;
+    withFileTypes: true;
+  }): Promise<Dirent[]>;
+  /**
+   * Get file status. Follows symbolic links.
+   *
+   * @param path - Path to the file
+   * @param options - Options
+   */
+  stat(path: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<Stats>;
+  /**
+   * Get file status. Does not follow symbolic links.
+   *
+   * @param path - Path to the file
+   * @param options - Options
+   */
+  lstat(path: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<Stats>;
+  /**
+   * Remove a file or symbolic link.
+   *
+   * @param path - Path to the file
+   * @param options - Options
+   */
+  unlink(path: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Remove files and directories.
+   *
+   * @param path - Path to remove
+   * @param options - Options
+   */
+  rm(path: string, options?: RmOptions): Promise<void>;
+  /**
+   * Remove a directory.
+   *
+   * @param path - Path to the directory
+   * @param options - Options
+   */
+  rmdir(path: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Rename a file or directory.
+   *
+   * @param oldPath - Current path
+   * @param newPath - New path
+   * @param options - Options
+   */
+  rename(oldPath: string, newPath: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Copy a file.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   * @param options - Options
+   */
+  copyFile(src: string, dest: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Test whether a file exists and the user has the specified permissions.
+   *
+   * @param path - Path to the file
+   * @param options - Options
+   */
+  access(path: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Check if a path exists.
+   *
+   * This is a convenience method not in `node:fs/promises` but commonly needed.
+   *
+   * @param path - Path to check
+   * @param options - Options
+   */
+  exists(path: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<boolean>;
+  /**
+   * Change file mode (permissions).
+   *
+   * @param path - Path to the file
+   * @param mode - File mode (e.g., 0o755 or "755")
+   * @param options - Options
+   */
+  chmod(path: string, mode: number | string, options?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Change file owner and group.
+   *
+   * @param path - Path to the file
+   * @param uid - User ID
+   * @param gid - Group ID
+   * @param options - Options
+   */
+  chown(path: string, uid: number, gid: number, options?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Create a symbolic link.
+   *
+   * @param target - The target of the symbolic link
+   * @param path - The path of the symbolic link to create
+   * @param options - Options
+   */
+  symlink(target: string, path: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Read the value of a symbolic link.
+   *
+   * @param path - Path to the symbolic link
+   * @param options - Options
+   */
+  readlink(path: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<string>;
+  /**
+   * Resolve the real path of a file (resolving symlinks).
+   *
+   * @param path - Path to resolve
+   * @param options - Options
+   */
+  realpath(path: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<string>;
+  /**
+   * Truncate a file to a specified length.
+   *
+   * @param path - Path to the file
+   * @param len - Length to truncate to (default: 0)
+   * @param options - Options
+   */
+  truncate(path: string, len?: number, options?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Create a unique temporary directory.
+   *
+   * @param prefix - The prefix for the temporary directory name
+   * @param options - Options
+   * @returns The path of the created temporary directory
+   */
+  mkdtemp(prefix: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<string>;
+}
+//#endregion
+export { FileSystem };
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/src/compiled/@vercel/sandbox-stable/index.d.ts

@@ -0,0 +1,12 @@
+import { APIError, StreamError } from "./api-client/api-error.js";
+import { SnapshotTreeNodeData } from "./api-client/validators.js";
+import { NetworkPolicy, NetworkPolicyKeyValueMatcher, NetworkPolicyMatch, NetworkPolicyMatcher, NetworkPolicyRule, NetworkTransformer } from "./network-policy.js";
+import { Command, CommandFinished, CommandOutput, SerializedCommand, SerializedCommandFinished } from "./command.js";
+import { SerializedSnapshot, Snapshot } from "./snapshot.js";
+import { ExecutionContext } from "./execution-context.js";
+import { Session } from "./session.js";
+import { FileSystem } from "./filesystem.js";
+import { SandboxUser, SandboxUserAlreadyExistsError } from "./sandbox-user.js";
+import { Sandbox, SerializedSandbox } from "./sandbox.js";
+import { InvalidRequestProxyHandler, ProxyHandler, ProxyMeta, defineSandboxProxy } from "./proxy.js";
+export { APIError, Command, CommandFinished, type CommandOutput, type ExecutionContext, FileSystem, type InvalidRequestProxyHandler, type NetworkPolicy, type NetworkPolicyKeyValueMatcher, type NetworkPolicyMatch, type NetworkPolicyMatcher, type NetworkPolicyRule, type NetworkTransformer, type ProxyHandler, type ProxyMeta, Sandbox, SandboxUser, SandboxUserAlreadyExistsError, type SerializedCommand, type SerializedCommandFinished, type SerializedSandbox, type SerializedSnapshot, Session, Snapshot, type SnapshotTreeNodeData, StreamError, defineSandboxProxy };

package/dist/src/compiled/@vercel/sandbox-stable/index.js

@@ -0,0 +1 @@
+export {};

package/dist/src/compiled/@vercel/sandbox-stable/network-policy.d.ts

@@ -0,0 +1,169 @@
+//#region src/network-policy.d.ts
+/**
+ * A transform applied to network requests matching a domain rule.
+ *
+ * @example
+ * {
+ *   headers: { authorization: "Bearer sk-..." }
+ * }
+ */
+type NetworkTransformer = {
+  /** Headers to set on the outgoing request. */
+  headers?: Record<string, string>;
+};
+/**
+ * Defines how a request value is matched.
+ */
+type NetworkPolicyMatcher = {
+  /** Match the value exactly. */
+  exact?: string;
+} | {
+  /** Match values that start with the provided prefix. */
+  startsWith?: string;
+} | {
+  /** Match values against an RE2 regular expression. */
+  regex?: string;
+};
+/**
+ * Matcher for key/value request entries such as headers and query parameters.
+ */
+type NetworkPolicyKeyValueMatcher = {
+  /** Matcher for the entry key. */
+  key?: NetworkPolicyMatcher;
+  /** Matcher for the entry value. */
+  value?: NetworkPolicyMatcher;
+};
+/**
+ * Request matcher for a network policy rule.
+ *
+ * All specified dimensions must match. Multiple methods are ORed; multiple
+ * header and query-string matchers are ANDed.
+ */
+type NetworkPolicyMatch = {
+  /** Match on the request path. */
+  path?: NetworkPolicyMatcher;
+  /** Match on the HTTP method. */
+  method?: string[];
+  /** Match on query-string entries. */
+  queryString?: NetworkPolicyKeyValueMatcher[];
+  /** Match on request headers. */
+  headers?: NetworkPolicyKeyValueMatcher[];
+};
+/**
+ * A rule applied to requests matching a domain in the network policy.
+ */
+type NetworkPolicyRule = {
+  /**
+   * Optional request matcher. When provided, transforms and forwarding rules
+   * only apply to requests that match every specified dimension.
+   */
+  match?: NetworkPolicyMatch;
+} & ({
+  /**
+   * Transforms to apply to matching requests.
+   *
+   * `transform` cannot be used together with `forwardURL`.
+   */
+  transform: NetworkTransformer[];
+  forwardURL?: never;
+} | {
+  transform?: never;
+  /**
+   * HTTPS proxy URL to forward matching requests to. Must not include query string or fragment.
+   *
+   * You can use the `defineSandboxProxy` helper from `@vercel/sandbox/proxy` to implement the proxy handler
+   * automatically, which handles authorization and extracts metadata about the request and sandbox.
+   *
+   * `forwardURL` cannot be used together with `transform`.
+   *
+   * @see https://vercel.com/docs/vercel-sandbox/concepts/firewall#requests-proxying
+   */
+  forwardURL: string;
+});
+/**
+ * Network policy to define network restrictions for the sandbox.
+ *
+ * - `"allow-all"`: Full internet access (default). All traffic is allowed.
+ * - `"deny-all"`: No internet access. All traffic is denied.
+ * - Object: Custom access with explicit allow/deny lists.
+ *
+ * @example
+ * // Full internet access (default)
+ * "allow-all"
+ *
+ * @example
+ * // No external access
+ * "deny-all"
+ *
+ * @example
+ * // Custom access with specific domains (simple list)
+ * // All traffic not explicitly allowed is denied.
+ * {
+ *   allow: ["*.npmjs.org", "github.com"],
+ *   subnets: {
+ *     allow: ["10.0.0.0/8"],
+ *     deny: ["10.1.0.0/16"]
+ *   }
+ * }
+ *
+ * @example
+ * // Custom access with specific domains (record form)
+ * {
+ *   allow: {
+ *     "*.npmjs.org": [],
+ *     "github.com": [],
+ *   }
+ * }
+ *
+ * @example
+ * // Custom access with request transformers
+ * {
+ *   allow: {
+ *     "ai-gateway.vercel.sh": [
+ *       {
+ *         match: {
+ *           method: ["POST"],
+ *           path: { startsWith: "/v1/" },
+ *           headers: [
+ *             { key: { exact: "x-api-key" }, value: { exact: "placeholder" } }
+ *           ]
+ *         },
+ *         transform: [{
+ *           headers: { authorization: "Bearer ..." }
+ *         }]
+ *       }
+ *     ],
+ *     "*": []
+ *   }
+ * }
+ */
+type NetworkPolicy = "allow-all" | "deny-all" | {
+  /**
+   * Domains to allow traffic to.
+   * Use "*" prefix for wildcard matching (e.g., "*.npmjs.org").
+   *
+   * Accepts either:
+   * - `string[]`: A simple list of domains to allow.
+   * - `Record<string, NetworkPolicyRule[]>`: A map of domains to rules.
+   *   An empty array allows traffic with no additional rules.
+   */
+  allow?: string[] | Record<string, NetworkPolicyRule[]>;
+  /**
+   * Subnet-level access control using CIDR notation.
+   */
+  subnets?: {
+    /**
+     * List of CIDRs to allow traffic to.
+     * Traffic to these addresses will bypass the domain allowlist.
+     */
+    allow?: string[];
+    /**
+     * List of CIDRs to deny traffic to.
+     * These take precedence over allowed domains and CIDRs.
+     */
+    deny?: string[];
+  };
+};
+//#endregion
+export { NetworkPolicy, NetworkPolicyKeyValueMatcher, NetworkPolicyMatch, NetworkPolicyMatcher, NetworkPolicyRule, NetworkTransformer };
+//# sourceMappingURL=network-policy.d.ts.map

package/dist/src/compiled/@vercel/sandbox-stable/proxy.d.ts

@@ -0,0 +1,55 @@
+//#region src/proxy.d.ts
+interface ProxyMeta {
+  /**
+   * The host of the request as received by this proxy.
+   */
+  host: string;
+  /**
+   * The ID of the team that owns the sandbox that proxied the request.
+   */
+  teamId: string;
+  /**
+   * The ID of the project that owns the sandbox that proxied the request.
+   */
+  projectId: string;
+  /**
+   * The ID of the sandbox that proxied the request.
+   */
+  sandboxId: string;
+  /**
+   * The name of the sandbox that proxied the request, when using persistent sandboxes.
+   */
+  sandboxName: string;
+}
+type ProxyHandler = (request: Request, meta: ProxyMeta) => Response | Promise<Response>;
+type InvalidRequestProxyHandler = (request: Request, error: Error) => Response | Promise<Response>;
+/**
+ * Creates a Web Handler for proxied requests from Vercel Sandboxes using the network policy `forwardURL`
+ * option. The provided `handler` is called for each valid proxied request, with the original request
+ * alongside extracted metadata used to identify the source sandbox and request details.
+ *
+ * This function automatically verifies the OIDC token included in proxied requests to ensure the request
+ * is legitimate: if invalid, the `invalidRequestHandler` is called (by default, a 403 response is returned).
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   fetch: defineSandboxProxy(async (request, meta) => {
+ *     // meta contains the original host & source team/project/sandbox ids
+ *     console.log(meta)
+ *
+ *     // return a custom response, or proxy upstream:
+ *     return await fetch(request)
+ *   }, (request, error) => {
+ *     // optional, handle any authorization error
+ *     return new Response("Forbidden", { status: 403 })
+ *   })
+ * }
+ * ```
+ *
+ * @see https://vercel.com/docs/vercel-sandbox/concepts/firewall#requests-proxying
+ */
+declare function defineSandboxProxy(handler: ProxyHandler, invalidRequestHandler?: InvalidRequestProxyHandler): (request: Request) => Promise<Response>;
+//#endregion
+export { InvalidRequestProxyHandler, ProxyHandler, ProxyMeta, defineSandboxProxy };
+//# sourceMappingURL=proxy.d.ts.map

package/dist/src/compiled/@vercel/sandbox-stable/sandbox-user.d.ts

@@ -0,0 +1,212 @@
+import { Command, CommandFinished } from "./command.js";
+import { ExecutionContext } from "./execution-context.js";
+import { RunCommandParams } from "./session.js";
+import { Sandbox } from "./sandbox.js";
+
+//#region src/sandbox-user.d.ts
+
+/**
+ * Thrown when {@link Sandbox.createUser} is called for an existing username.
+ */
+declare class SandboxUserAlreadyExistsError extends Error {
+  readonly username: string;
+  constructor(username: string);
+}
+/**
+ * A user context within a sandbox.
+ *
+ * All file and command operations default to running as this user.
+ * Created via {@link Sandbox.createUser} or {@link Sandbox.asUser}.
+ *
+ * @hideconstructor
+ */
+declare class SandboxUser implements ExecutionContext {
+  /**
+   * The Linux username.
+   */
+  readonly username: string;
+  /**
+   * The user's home directory (e.g., `/home/alice`).
+   */
+  readonly homeDir: string;
+  private readonly sandbox;
+  /**
+   * Memoized lookup of this user's primary group.
+   * See {@link SandboxUser.primaryGroup}.
+   */
+  private primaryGroupPromise?;
+  constructor({
+    sandbox,
+    username
+  }: {
+    sandbox: Sandbox;
+    username: string;
+  });
+  /**
+   * Build the wrapped command args to run as this user via `sudo -u`.
+   *
+   * When `env` is provided, injects `env KEY=VAL ...` so that environment
+   * variables survive the `sudo -u` transition.
+   */
+  private buildUserCommand;
+  /**
+   * Resolve a path relative to this user's home directory.
+   * Absolute paths are returned as-is.
+   */
+  private resolvePath;
+  /**
+   * Start executing a command as this user.
+   *
+   * @param command - The command to execute.
+   * @param args - Arguments to pass to the command.
+   * @param opts - Optional parameters.
+   * @returns A {@link CommandFinished} result once execution is done.
+   */
+  runCommand(command: string, args?: string[], opts?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+  }): Promise<CommandFinished>;
+  /**
+   * Start executing a command as this user in detached mode.
+   *
+   * @param params - The command parameters.
+   * @returns A {@link Command} instance for the running command.
+   */
+  runCommand(params: RunCommandParams & {
+    detached: true;
+  }): Promise<Command>;
+  /**
+   * Start executing a command as this user.
+   *
+   * @param params - The command parameters.
+   * @returns A {@link CommandFinished} result once execution is done.
+   */
+  runCommand(params: RunCommandParams): Promise<CommandFinished>;
+  /**
+   * Write files to this user's home directory (or absolute paths).
+   * Files are written via the sandbox HTTP API then chowned to this user.
+   *
+   * The HTTP API can write to user home dirs because they are group-owned
+   * by the sandbox's default user group with `770` permissions.
+   *
+   * @param files - Array of files with path, content, and optional mode
+   * @param opts - Optional parameters.
+   */
+  writeFiles(files: {
+    path: string;
+    content: string | Uint8Array;
+    mode?: number;
+  }[], opts?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Read a file from this user's context as a stream.
+   *
+   * @param file - File to read, with path and optional cwd
+   * @param opts - Optional parameters.
+   * @returns A ReadableStream of the file contents, or null if not found
+   */
+  readFile(file: {
+    path: string;
+    cwd?: string;
+  }, opts?: {
+    signal?: AbortSignal;
+  }): Promise<NodeJS.ReadableStream | null>;
+  /**
+   * Read a file from this user's context as a Buffer.
+   *
+   * @param file - File to read, with path and optional cwd
+   * @param opts - Optional parameters.
+   * @returns The file contents as a Buffer, or null if not found
+   */
+  readFileToBuffer(file: {
+    path: string;
+    cwd?: string;
+  }, opts?: {
+    signal?: AbortSignal;
+  }): Promise<Buffer | null>;
+  /**
+   * Download a file from this user's context to the local filesystem.
+   *
+   * @param src - Source file in the sandbox
+   * @param dst - Destination on the local machine
+   * @param opts - Optional parameters.
+   * @returns The absolute path to the written file, or null if not found
+   */
+  downloadFile(src: {
+    path: string;
+    cwd?: string;
+  }, dst: {
+    path: string;
+    cwd?: string;
+  }, opts?: {
+    mkdirRecursive?: boolean;
+    signal?: AbortSignal;
+  }): Promise<string | null>;
+  /**
+   * Read a file as this user and return its bytes, or null if it does not
+   * exist.
+   *
+   * Reads via `sudo -u <user> base64` rather than the HTTP file API: on stock
+   * runtimes the API runs as `vercel-sandbox` and cannot read files this user
+   * has kept private (e.g. mode `600`), whereas reading as the user always
+   * honours the user's own permissions. The payload is base64-encoded because
+   * the command output channel is UTF-8 only and would otherwise corrupt
+   * binary files.
+   */
+  private catAsUser;
+  /**
+   * Create a directory owned by this user.
+   *
+   * @param path - Path of the directory to create
+   * @param opts - Optional parameters.
+   */
+  mkDir(path: string, opts?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * This user's primary group. Users created via {@link Sandbox.createUser}
+   * get a group named after them, but {@link Sandbox.asUser} accepts
+   * pre-existing users whose primary group can differ (e.g. system users), so
+   * we resolve it from the sandbox rather than assuming `<username>`.
+   *
+   * The result is memoized for the lifetime of this instance.
+   */
+  private primaryGroup;
+  private resolvePrimaryGroup;
+  /**
+   * Run `chown <ownership> <paths...>` as root, throwing on failure.
+   */
+  private chownOrThrow;
+  /**
+   * Run `chmod <mode> <paths...>` as root, throwing on failure.
+   */
+  private chmodOrThrow;
+  /**
+   * Given absolute leaf paths, return the directories strictly between this
+   * user's home directory and each leaf. The home dir itself is excluded, as
+   * are any paths that fall outside the home dir.
+   */
+  private ancestorDirsUnderHome;
+  /**
+   * Add this user to a group.
+   *
+   * @param groupname - Name of the group to join
+   * @param opts - Optional parameters.
+   */
+  addToGroup(groupname: string, opts?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Remove this user from a group.
+   *
+   * @param groupname - Name of the group to leave
+   * @param opts - Optional parameters.
+   */
+  removeFromGroup(groupname: string, opts?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+}
+//#endregion
+export { SandboxUser, SandboxUserAlreadyExistsError };
+//# sourceMappingURL=sandbox-user.d.ts.map