@hyperbrowser/sdk 1.2.0 → 1.2.1

package/README.md

@@ -375,6 +375,76 @@ await sandbox.stop();
 await client.volumes.delete(sameVolume.id);
 ```
 
+Store secrets and deliver them to sandbox processes as environment variables:
+
+```typescript
+// The value is encrypted locally to the platform key; the API only receives
+// the envelope, and values are never returned.
+await client.secrets.create({
+  name: "provider-key",
+  description: "Provider API key",
+  value: process.env.PROVIDER_KEY!,
+});
+await client.secrets.addVersion("provider-key", newValue); // next version
+const secrets = await client.secrets.list({ search: "provider" });
+const detail = await client.secrets.get("provider-key"); // metadata and versions
+
+const sandbox = await client.sandboxes.create({ imageName: "node" });
+const result = await sandbox.exec("node app.js", {
+  secrets: { API_KEY: "provider-key", DB_URL: { name: "db-url", version: 2 } },
+});
+
+// Long-running processes report the versions they received.
+const worker = await sandbox.processes.start("node worker.js", {
+  secrets: { API_KEY: "provider-key" },
+});
+console.log(worker.secrets);
+
+// Secrets for the image's startup command (image launches only).
+await client.sandboxes.create({ imageName: "my-image", secrets: { API_KEY: "provider-key" } });
+
+await client.secrets.deleteVersion("provider-key", 1);
+await client.secrets.delete("provider-key");
+```
+
+- Secret methods take a secret's ID or exact name. Values are strings or bytes,
+  used byte-for-byte: 1 to 32,768 bytes of UTF-8 without NUL.
+- A secret is delivered only to the process it is passed to, but anything
+  running as the same user (or root) in the sandbox can read that process's
+  environment. The sandbox and its later snapshots are marked
+  `containsSecrets`.
+- Deleting a secret does not revoke a value already delivered to a sandbox.
+- Limits: 100 secrets per team, 10 stored versions per secret, 32 secrets per
+  process or sandbox. The API key needs the `secrets.read`, `secrets.manage`
+  or `secrets.use` scope for reading, managing or delivering secrets.
+  SDK updates, version additions, and deletions also require `secrets.read`
+  alongside `secrets.manage`: the SDK resolves the existing secret before
+  changing it, even when given an ID. Encryption also needs its encryption
+  context. Creating a new secret needs only `secrets.manage`.
+- A process start with secrets is never retried. If it times out, its
+  response is lost, or the API reports that the sandbox host did not confirm
+  the start (`SECRET_PROCESS_OUTCOME_UNKNOWN`), the error code is
+  `secret_process_outcome_unknown` and the API's response, if any, is in
+  `details`: check the sandbox's processes before starting it again.
+- The same applies to `sandboxes.create` with `secrets`: if the create result
+  can't be confirmed, the error code is `secret_process_outcome_unknown`, since
+  a sandbox may already be running its startup command with the secrets. List
+  sandboxes before creating it again.
+- Startup secrets need an image with a startup command and a Firecracker
+  sandbox. Otherwise the create fails with `SECRET_STARTUP_UNSUPPORTED`; create
+  the sandbox without `secrets` and pass them to `processes.exec` or
+  `processes.start` instead.
+- Secrets routes return 403 `SECRETS_FEATURE_DISABLED` when the team doesn't
+  have secrets enabled, and 503 `SECRETS_NOT_CONFIGURED` (not retryable) when
+  the server has no secrets encryption key.
+- A command timeout (`timeoutSec` or `timeoutMs`) for a process started with
+  secrets is sent in whole milliseconds and can be at most 24 hours.
+- Secret-started handles support `wait()` and `result()` without a local
+  deadline. An explicit wait timeout limits the whole local wait, leaving the
+  command running; the same handle can be awaited again. Runtime waits use
+  bounded requests below the client's request timeout. Output still comes from
+  the receiver's retained output, so `maxOutputBytes` does not apply.
+
 List sandboxes with time-range and search filters:
 
 ```typescript

package/dist/client.d.ts

@@ -18,6 +18,7 @@ import { JevComputerUseService } from "./services/agents/jev-computer-use";
 import { WebService } from "./services/web";
 import { SandboxesService } from "./services/sandboxes";
 import { VolumesService } from "./services/volumes";
+import { SecretsService } from "./services/secrets";
 export { HyperbrowserError } from "./error";
 export type { HyperbrowserErrorOptions, HyperbrowserService } from "./error";
 export declare class HyperbrowserClient {
@@ -42,5 +43,6 @@ export declare class HyperbrowserClient {
     readonly computerAction: ComputerActionService;
     readonly sandboxes: SandboxesService;
     readonly volumes: VolumesService;
+    readonly secrets: SecretsService;
     constructor(config?: HyperbrowserConfig);
 }

package/dist/client.js

@@ -20,6 +20,7 @@ const jev_computer_use_1 = require("./services/agents/jev-computer-use");
 const web_1 = require("./services/web");
 const sandboxes_1 = require("./services/sandboxes");
 const volumes_1 = require("./services/volumes");
+const secrets_1 = require("./services/secrets");
 const error_1 = require("./error");
 var error_2 = require("./error");
 Object.defineProperty(exports, "HyperbrowserError", { enumerable: true, get: function () { return error_2.HyperbrowserError; } });
@@ -43,6 +44,7 @@ class HyperbrowserClient {
         this.computerAction = new computer_action_1.ComputerActionService(apiKey, baseUrl, timeout);
         this.sandboxes = new sandboxes_1.SandboxesService(apiKey, baseUrl, timeout, runtimeProxyOverride);
         this.volumes = new volumes_1.VolumesService(apiKey, baseUrl, timeout);
+        this.secrets = new secrets_1.SecretsService(apiKey, baseUrl, timeout);
         this.agents = {
             browserUse: new browser_use_1.BrowserUseService(apiKey, baseUrl, timeout),
             claudeComputerUse: new claude_computer_use_1.ClaudeComputerUseService(apiKey, baseUrl, timeout),

package/dist/error.d.ts

@@ -25,3 +25,6 @@ export declare class HyperbrowserError extends Error {
     readonly path?: string;
     constructor(message: string, options?: number | HyperbrowserErrorOptions);
 }
+/** @internal The response body could not be read or decoded as JSON. */
+export declare class ResponseDecodingError extends HyperbrowserError {
+}

package/dist/error.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HyperbrowserError = exports.networkErrorMessage = exports.errorRequestPath = void 0;
+exports.ResponseDecodingError = exports.HyperbrowserError = exports.networkErrorMessage = exports.errorRequestPath = void 0;
 /** Keep diagnostics useful without retaining query credentials or URL hosts. */
 const errorRequestPath = (target) => {
     try {
@@ -30,3 +30,7 @@ class HyperbrowserError extends Error {
     }
 }
 exports.HyperbrowserError = HyperbrowserError;
+/** @internal The response body could not be read or decoded as JSON. */
+class ResponseDecodingError extends HyperbrowserError {
+}
+exports.ResponseDecodingError = ResponseDecodingError;

package/dist/sandbox/process.d.ts

@@ -1,13 +1,59 @@
 import { RuntimeSSEStream, RuntimeTransport } from "./base";
-import { SandboxExecParams, SandboxExecOptions, SandboxProcessListParams, SandboxProcessListResponse, SandboxProcessResult, SandboxProcessSignal, SandboxProcessStdinParams, SandboxProcessStreamEvent, SandboxProcessSummary, SandboxProcessWaitParams } from "../types/sandbox";
+import { WireSecretReference } from "./secret-references";
+import { SandboxExecParams, SandboxExecOptions, SandboxResolvedSecret, SandboxProcessListParams, SandboxProcessListResponse, SandboxProcessResult, SandboxProcessSignal, SandboxProcessStdinParams, SandboxProcessStreamEvent, SandboxProcessSummary, SandboxProcessWaitParams } from "../types/sandbox";
+export interface RawProcessSummary extends Partial<SandboxProcessSummary> {
+    id: string;
+    status: SandboxProcessSummary["status"];
+    command: string;
+    args?: string[] | null;
+    cwd: string;
+    pid?: number | null;
+    exit_code?: number | null;
+    started_at: number;
+    completed_at?: number | null;
+}
+/** The body of a control API process start with secrets. */
+export interface SecretProcessStartPayload {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    runAs?: string;
+    secrets: Record<string, WireSecretReference>;
+}
+export interface SecretProcessStartResponse {
+    /** The sandbox agent's summary, passed through unchanged. */
+    process?: RawProcessSummary;
+    secrets?: SandboxResolvedSecret[];
+}
+/** @internal Starts processes with secrets through the control API. */
+export interface SecretProcessStarter {
+    sandboxId: string;
+    /** Each runtime wait stays under the runtime request timeout. */
+    waitChunkMs: number;
+    start(payload: SecretProcessStartPayload, signal?: AbortSignal): Promise<SecretProcessStartResponse>;
+}
+interface SecretProcessWaitContext {
+    chunkMs: number;
+    signal?: AbortSignal;
+}
+/**
+ * @internal Whether a failed control API request may still have reached the
+ * API: it timed out or its response couldn't be read. API errors and failures
+ * to connect are excluded.
+ */
+export declare const requestMayHaveArrived: (error: unknown) => boolean;
 export declare class SandboxProcessHandle {
     private readonly transport;
     private summary;
+    private readonly secretWait?;
     private output;
     private collector;
     private closeStream;
     private readonly changed;
-    constructor(transport: RuntimeTransport, summary: SandboxProcessSummary);
+    /** The secret versions delivered to a process started with `secrets`. */
+    readonly secrets?: SandboxResolvedSecret[];
+    constructor(transport: RuntimeTransport, summary: SandboxProcessSummary, secrets?: SandboxResolvedSecret[], secretWait?: SecretProcessWaitContext | undefined);
     /** @internal Collect output from the start-stream that created this process. */
     attachCollector(stream: RuntimeSSEStream, maxOutputBytes: number): void;
     private collect;
@@ -23,6 +69,9 @@ export declare class SandboxProcessHandle {
      * collected stream; a local timeout rejects without stopping collection.
      */
     wait(params?: SandboxProcessWaitParams): Promise<SandboxProcessResult>;
+    /** Secret starts retain output on the receiver, so poll until the local deadline. */
+    private waitWithSecrets;
+    private waitRetained;
     signal(signal: SandboxProcessSignal): Promise<void>;
     kill(params?: SandboxProcessWaitParams): Promise<SandboxProcessResult>;
     writeStdin(input: string | Uint8Array | SandboxProcessStdinParams): Promise<void>;
@@ -35,7 +84,8 @@ export declare class SandboxProcessHandle {
 }
 export declare class SandboxProcessesApi {
     private readonly transport;
-    constructor(transport: RuntimeTransport);
+    private readonly secretStarter?;
+    constructor(transport: RuntimeTransport, secretStarter?: SecretProcessStarter | undefined);
     /** Run a command to completion, collecting its full output from process start. */
     exec(command: string, options?: SandboxExecOptions): Promise<SandboxProcessResult>;
     exec(input: SandboxExecParams): Promise<SandboxProcessResult>;
@@ -46,6 +96,18 @@ export declare class SandboxProcessesApi {
      */
     start(command: string, options?: SandboxExecOptions): Promise<SandboxProcessHandle>;
     start(input: SandboxExecParams): Promise<SandboxProcessHandle>;
+    /**
+     * Start through the control API so the sandbox service decrypts the
+     * secrets. Output is then read through the runtime's retained output.
+     */
+    private startWithSecrets;
+    /**
+     * Like one-shot exec: stdin is closed, then the command's final result is
+     * awaited. The command's own timeout is enforced in the sandbox, so an
+     * expired wait (408) only means it is still running.
+     */
+    private execWithSecrets;
     get(processId: string): Promise<SandboxProcessHandle>;
     list(params?: SandboxProcessListParams): Promise<SandboxProcessListResponse>;
 }
+export {};

package/dist/sandbox/process.js

@@ -1,8 +1,40 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxProcessesApi = exports.SandboxProcessHandle = void 0;
+exports.SandboxProcessesApi = exports.SandboxProcessHandle = exports.requestMayHaveArrived = void 0;
+const perf_hooks_1 = require("perf_hooks");
 const error_1 = require("../error");
 const process_output_1 = require("./process-output");
+const secret_references_1 = require("./secret-references");
+/** Errors from connecting at all; anything else may have reached the API. */
+const CONNECT_ERROR_CODES = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "EHOSTUNREACH"]);
+/** The control API's code for a secret process start it could not confirm. */
+const SERVER_OUTCOME_UNKNOWN_CODE = "SECRET_PROCESS_OUTCOME_UNKNOWN";
+/** The control API's limit on a secret process's `timeoutMs`. */
+const MAX_SECRET_PROCESS_TIMEOUT_MS = 86400000;
+/**
+ * @internal Whether a failed control API request may still have reached the
+ * API: it timed out or its response couldn't be read. API errors and failures
+ * to connect are excluded.
+ */
+const requestMayHaveArrived = (error) => {
+    if (error instanceof error_1.ResponseDecodingError) {
+        return true;
+    }
+    if (!(error instanceof error_1.HyperbrowserError)) {
+        return true;
+    }
+    // Pre-aborted calls are rejected before sending. Cancellation here may
+    // interrupt an error body after the API has already accepted the start.
+    if (error.code === "request_aborted") {
+        return true;
+    }
+    if (error.statusCode !== undefined && error.statusCode >= 400) {
+        return false;
+    }
+    const code = error.cause?.code;
+    return !(code && CONNECT_ERROR_CODES.has(code));
+};
+exports.requestMayHaveArrived = requestMayHaveArrived;
 const DEFAULT_PROCESS_KILL_WAIT_MS = 5000;
 const SHELL_SAFE_TOKEN_PATTERN = /^[A-Za-z0-9_@%+=:,./-]+$/;
 const normalizeProcessSummary = (process) => ({
@@ -99,6 +131,40 @@ const localWaitTimeoutMs = (params) => {
     }
     return undefined;
 };
+/**
+ * The command timeout for a secret process start, as the whole milliseconds
+ * the control API accepts. Rounded, but a positive timeout stays at least 1ms
+ * rather than becoming 0 (no timeout).
+ */
+const secretProcessTimeoutMs = (params) => {
+    for (const name of ["timeoutSec", "timeoutMs"]) {
+        const value = params[name];
+        if (value !== undefined &&
+            (typeof value !== "number" || !Number.isFinite(value) || value < 0)) {
+            throw new error_1.HyperbrowserError(`${name} must be a non-negative number`);
+        }
+    }
+    // Match the receiver: positive seconds take precedence over milliseconds.
+    const timeoutMs = localWaitTimeoutMs(params);
+    if (timeoutMs === undefined) {
+        return undefined;
+    }
+    const wholeMs = Math.max(1, Math.round(timeoutMs));
+    if (wholeMs > MAX_SECRET_PROCESS_TIMEOUT_MS) {
+        throw new error_1.HyperbrowserError(`A process started with secrets can run for at most ${MAX_SECRET_PROCESS_TIMEOUT_MS / 1000} seconds`);
+    }
+    return wholeMs;
+};
+const waitTimeoutError = () => new error_1.HyperbrowserError("Timed out waiting for command output", {
+    code: "wait_timeout",
+    service: "runtime",
+    retryable: false,
+});
+const requestAbortedError = () => new error_1.HyperbrowserError("Request canceled", {
+    code: "request_aborted",
+    retryable: false,
+    service: "runtime",
+});
 const buildProcessPayload = (input) => ({
     command: input.command,
     cwd: input.cwd,
@@ -133,13 +199,15 @@ const encodeStdinPayload = (input) => {
     };
 };
 class SandboxProcessHandle {
-    constructor(transport, summary) {
+    constructor(transport, summary, secrets, secretWait) {
         this.transport = transport;
         this.summary = summary;
+        this.secretWait = secretWait;
         this.output = null;
         this.collector = null;
         this.closeStream = null;
         this.changed = new ChangeSignal();
+        this.secrets = secrets;
     }
     /** @internal Collect output from the start-stream that created this process. */
     attachCollector(stream, maxOutputBytes) {
@@ -246,6 +314,70 @@ class SandboxProcessHandle {
             }
             return this.collectedResult();
         }
+        if (this.secretWait) {
+            return this.waitWithSecrets(params);
+        }
+        return this.waitRetained(params);
+    }
+    /** Secret starts retain output on the receiver, so poll until the local deadline. */
+    async waitWithSecrets(params) {
+        const context = this.secretWait;
+        const timeoutMs = localWaitTimeoutMs(params);
+        const deadline = timeoutMs === undefined ? undefined : perf_hooks_1.performance.now() + timeoutMs;
+        for (;;) {
+            if (context.signal?.aborted)
+                throw requestAbortedError();
+            const remaining = deadline === undefined ? undefined : deadline - perf_hooks_1.performance.now();
+            if (remaining !== undefined && remaining <= 0)
+                throw waitTimeoutError();
+            const controller = new AbortController();
+            let deadlineExpired = false;
+            let cancelWait;
+            const canceled = new Promise((_, reject) => {
+                cancelWait = reject;
+            });
+            const abort = () => {
+                controller.abort();
+                cancelWait(requestAbortedError());
+            };
+            context.signal?.addEventListener("abort", abort, { once: true });
+            // Node timers cannot represent intervals above 2^31-1 ms. Long local
+            // deadlines are checked again after every bounded request instead.
+            const timer = remaining !== undefined && remaining <= 2147483647
+                ? setTimeout(() => {
+                    deadlineExpired = true;
+                    controller.abort();
+                    cancelWait(waitTimeoutError());
+                }, remaining)
+                : undefined;
+            try {
+                const result = await Promise.race([
+                    this.waitRetained({ timeoutMs: Math.max(1, Math.floor(Math.min(context.chunkMs, remaining ?? Infinity))) }, controller.signal),
+                    canceled,
+                ]);
+                if (context.signal?.aborted)
+                    throw requestAbortedError();
+                if (deadlineExpired || (deadline !== undefined && perf_hooks_1.performance.now() >= deadline)) {
+                    throw waitTimeoutError();
+                }
+                return result;
+            }
+            catch (error) {
+                if (context.signal?.aborted)
+                    throw requestAbortedError();
+                if (deadlineExpired || (deadline !== undefined && perf_hooks_1.performance.now() >= deadline)) {
+                    throw waitTimeoutError();
+                }
+                if (!(error instanceof error_1.HyperbrowserError) || error.statusCode !== 408)
+                    throw error;
+            }
+            finally {
+                clearTimeout(timer);
+                context.signal?.removeEventListener("abort", abort);
+            }
+        }
+    }
+    async waitRetained(params, signal) {
         const response = await this.transport.requestJSON(`/sandbox/processes/${this.id}/wait`, {
             method: "POST",
             body: JSON.stringify({
@@ -255,6 +387,7 @@ class SandboxProcessHandle {
             headers: {
                 "content-type": "application/json",
             },
+            signal,
         });
         const result = (0, process_output_1.normalizeProcessResult)(response.result);
         if (result.outputTruncated) {
@@ -358,11 +491,16 @@ class SandboxProcessHandle {
 }
 exports.SandboxProcessHandle = SandboxProcessHandle;
 class SandboxProcessesApi {
-    constructor(transport) {
+    constructor(transport, secretStarter) {
         this.transport = transport;
+        this.secretStarter = secretStarter;
     }
     async exec(input, options) {
-        const handle = typeof input === "string" ? await this.start(input, options) : await this.start(input);
+        const params = normalizeExecParams(input, options);
+        if (params.secrets && Object.keys(params.secrets).length > 0) {
+            return this.execWithSecrets(params);
+        }
+        const handle = await this.start(params);
         try {
             return await handle.wait();
         }
@@ -372,6 +510,9 @@ class SandboxProcessesApi {
     }
     async start(input, options) {
         const params = normalizeExecParams(input, options);
+        if (params.secrets && Object.keys(params.secrets).length > 0) {
+            return this.startWithSecrets(params);
+        }
         const maxOutputBytes = params.maxOutputBytes ?? process_output_1.DEFAULT_MAX_PROCESS_OUTPUT_BYTES;
         (0, process_output_1.validateOutputLimit)(maxOutputBytes);
         const stream = await this.transport.openSSE("/sandbox/processes", undefined, {
@@ -398,6 +539,109 @@ class SandboxProcessesApi {
         handle.attachCollector(stream, maxOutputBytes);
         return handle;
     }
+    /**
+     * Start through the control API so the sandbox service decrypts the
+     * secrets. Output is then read through the runtime's retained output.
+     */
+    async startWithSecrets(params) {
+        if (params.signal?.aborted)
+            throw requestAbortedError();
+        const starter = this.secretStarter;
+        if (!starter) {
+            throw new error_1.HyperbrowserError("Starting a process with secrets requires a sandbox handle");
+        }
+        const secrets = (0, secret_references_1.serializeSecretReferences)(params.secrets);
+        (0, secret_references_1.assertNoEnvSecretOverlap)(params.env, secrets);
+        const timeoutMs = secretProcessTimeoutMs(params);
+        let response;
+        try {
+            response = await starter.start({
+                command: params.command,
+                cwd: params.cwd,
+                env: params.env,
+                timeoutMs,
+                runAs: params.runAs,
+                secrets,
+            }, params.signal);
+        }
+        catch (error) {
+            if (error instanceof error_1.HyperbrowserError && error.code === SERVER_OUTCOME_UNKNOWN_CODE) {
+                // The API reached the sandbox host but could not confirm the start.
+                throw new error_1.HyperbrowserError(error.message.replace(/^\[Hyperbrowser\]: /, ""), {
+                    statusCode: error.statusCode,
+                    code: "secret_process_outcome_unknown",
+                    requestId: error.requestId,
+                    retryable: false,
+                    service: "control",
+                    details: {
+                        ...(typeof error.details === "object" ? error.details : undefined),
+                        sandboxId: starter.sandboxId,
+                    },
+                    cause: error,
+                    method: error.method,
+                    path: error.path,
+                });
+            }
+            if (!(0, exports.requestMayHaveArrived)(error)) {
+                throw error;
+            }
+            throw new error_1.HyperbrowserError(`The process start may have reached the API, but no result came back; the command may be running, so check the sandbox's processes before retrying`, {
+                code: "secret_process_outcome_unknown",
+                retryable: false,
+                service: "control",
+                details: { sandboxId: starter.sandboxId },
+                cause: error,
+            });
+        }
+        const process = response?.process;
+        const processId = process?.id;
+        if (!process || typeof processId !== "string" || !processId.trim()) {
+            // The start succeeded, so the command may be running with the secrets.
+            throw new error_1.HyperbrowserError("The API accepted the process start but returned no process ID; the command may be running, so check the sandbox's processes before retrying", {
+                code: "secret_process_outcome_unknown",
+                retryable: false,
+                service: "control",
+                details: { sandboxId: starter.sandboxId },
+            });
+        }
+        return new SandboxProcessHandle(this.transport, normalizeProcessSummary({ ...process, id: processId.trim() }), response.secrets ?? [], { chunkMs: starter.waitChunkMs, signal: params.signal });
+    }
+    /**
+     * Like one-shot exec: stdin is closed, then the command's final result is
+     * awaited. The command's own timeout is enforced in the sandbox, so an
+     * expired wait (408) only means it is still running.
+     */
+    async execWithSecrets(params) {
+        const handle = await this.startWithSecrets(params);
+        const starter = this.secretStarter;
+        try {
+            try {
+                await this.transport.requestJSON(`/sandbox/processes/${handle.id}/stdin`, {
+                    method: "POST",
+                    body: JSON.stringify({ eof: true }),
+                    headers: { "content-type": "application/json" },
+                    signal: params.signal,
+                });
+            }
+            catch (error) {
+                // 409: the command already exited; its result is still reported.
+                if (!(error instanceof error_1.HyperbrowserError) || error.statusCode !== 409) {
+                    throw error;
+                }
+            }
+            return await handle.wait();
+        }
+        catch (error) {
+            // Running exec again would start a second process with the secrets.
+            throw new error_1.HyperbrowserError(`Process ${handle.id} started, but waiting for its result failed: ${error instanceof Error ? error.message.replace(/^\[Hyperbrowser\]: /, "") : String(error)}`, {
+                code: "secret_process_failed",
+                retryable: false,
+                service: "runtime",
+                details: { sandboxId: starter.sandboxId, processId: handle.id },
+                cause: error,
+            });
+        }
+    }
     async get(processId) {
         const response = await this.transport.requestJSON(`/sandbox/processes/${processId}`);
         return new SandboxProcessHandle(this.transport, normalizeProcessSummary(response.process));

package/dist/sandbox/secret-references.d.ts

@@ -0,0 +1,15 @@
+import { SandboxSecrets } from "../types/sandbox";
+export declare const SECRET_NAME_PATTERN: RegExp;
+/** The largest version number the API stores. */
+export declare const MAX_SECRET_VERSION = 2147483647;
+export interface WireSecretReference {
+    name: string;
+    version?: number | "latest";
+}
+/**
+ * Check secret references locally and convert them to the API's
+ * `{ name, version? }` shape. Returns undefined when there are none.
+ */
+export declare const serializeSecretReferences: (secrets: SandboxSecrets | undefined) => Record<string, WireSecretReference> | undefined;
+/** An environment variable must come from either `env` or `secrets`, not both. */
+export declare const assertNoEnvSecretOverlap: (env: Record<string, string> | undefined, secrets: Record<string, WireSecretReference>) => void;

package/dist/sandbox/secret-references.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertNoEnvSecretOverlap = exports.serializeSecretReferences = exports.MAX_SECRET_VERSION = exports.SECRET_NAME_PATTERN = void 0;
+const error_1 = require("../error");
+const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+exports.SECRET_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+/** The largest version number the API stores. */
+exports.MAX_SECRET_VERSION = 2147483647;
+const MAX_SECRETS = 32;
+/**
+ * Check secret references locally and convert them to the API's
+ * `{ name, version? }` shape. Returns undefined when there are none.
+ */
+const serializeSecretReferences = (secrets) => {
+    if (secrets === undefined || secrets === null) {
+        return undefined;
+    }
+    if (typeof secrets !== "object" || Array.isArray(secrets)) {
+        throw new error_1.HyperbrowserError("secrets must map environment variable names to secrets");
+    }
+    const entries = Object.entries(secrets);
+    if (entries.length === 0) {
+        return undefined;
+    }
+    if (entries.length > MAX_SECRETS) {
+        throw new error_1.HyperbrowserError(`At most ${MAX_SECRETS} secrets can be delivered at once`);
+    }
+    const wire = {};
+    for (const [env, reference] of entries) {
+        if (!ENV_NAME_PATTERN.test(env) || env === "__proto__") {
+            throw new error_1.HyperbrowserError(`Invalid environment variable name for a secret: ${env}`);
+        }
+        const { name, version } = typeof reference === "string" ? { name: reference, version: undefined } : (reference ?? {});
+        if (typeof name !== "string" || !exports.SECRET_NAME_PATTERN.test(name)) {
+            throw new error_1.HyperbrowserError(`Invalid secret name for ${env}: ${String(name)}`);
+        }
+        if (version !== undefined &&
+            version !== "latest" &&
+            (!Number.isSafeInteger(version) ||
+                version < 1 ||
+                version > exports.MAX_SECRET_VERSION)) {
+            throw new error_1.HyperbrowserError(`Secret version for ${env} must be an integer from 1 to ${exports.MAX_SECRET_VERSION} or "latest"`);
+        }
+        wire[env] = version === undefined ? { name } : { name, version };
+    }
+    return wire;
+};
+exports.serializeSecretReferences = serializeSecretReferences;
+/** An environment variable must come from either `env` or `secrets`, not both. */
+const assertNoEnvSecretOverlap = (env, secrets) => {
+    const overlap = Object.keys(env ?? {}).filter((name) => Object.prototype.hasOwnProperty.call(secrets, name));
+    if (overlap.length > 0) {
+        throw new error_1.HyperbrowserError(`Environment variables set by both env and secrets: ${overlap.sort().join(", ")}`);
+    }
+};
+exports.assertNoEnvSecretOverlap = assertNoEnvSecretOverlap;

package/dist/secrets-envelope.d.ts

@@ -0,0 +1,25 @@
+import { SecretsPublicKey, SecretValue } from "./types/secret";
+/** The largest secret value the platform accepts. */
+export declare const MAX_SECRET_VALUE_BYTES: number;
+/**
+ * Apply the platform's value rules locally, so a bad value is reported before
+ * anything is created rather than when a sandbox starts.
+ */
+export declare const secretValueBytes: (value: SecretValue) => Buffer;
+/** Encrypts values to a verified secrets public key. */
+export declare class SecretsSealer {
+    private readonly kid;
+    private readonly publicKey;
+    private constructor();
+    /**
+     * Check that `key` is a supported RSA key whose ID matches the key itself. A
+     * mismatch means a corrupted response or a misconfigured server; where the
+     * key comes from rests on TLS to the API.
+     */
+    static fromPublicKey(key: SecretsPublicKey): SecretsSealer;
+    /**
+     * Encrypt `value` as a compact JWE (RSA-OAEP-256 + A256GCM) bound to a
+     * secret's encryption context.
+     */
+    seal(encryptionContext: string, value: SecretValue): string;
+}