@hyperbrowser/sdk 1.4.1 → 1.5.1

package/dist/services/secrets.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SecretsService = void 0;
+const customer_key_1 = require("../customer-key");
 const error_1 = require("../error");
 const secret_references_1 = require("../sandbox/secret-references");
 const secret_values_1 = require("../secret-values");
@@ -12,6 +13,17 @@ const MAX_LIST_LIMIT = 100;
 /** Teams hold at most 100 secrets, so one page of search results covers every match. */
 const NAME_LOOKUP_LIMIT = MAX_LIST_LIMIT;
 const secretPath = (id) => `/secrets/${encodeURIComponent(id)}`;
+const isCustomerProtected = (secret) => secret.protection === "customer";
+/** Throws unless `version` is a version number, or `"latest"` where allowed. */
+const assertVersion = (version, allowLatest) => {
+    if (allowLatest && version === "latest")
+        return;
+    if (!Number.isSafeInteger(version) ||
+        version < 1 ||
+        version > secret_references_1.MAX_SECRET_VERSION) {
+        throw new error_1.HyperbrowserError(`version must be an integer from 1 to ${secret_references_1.MAX_SECRET_VERSION}${allowLatest ? ' or "latest"' : ""}`);
+    }
+};
 const rethrow = (error, message) => {
     if (error instanceof error_1.HyperbrowserError) {
         throw error;
@@ -22,6 +34,11 @@ const rethrow = (error, message) => {
  * Secrets are encrypted locally to the platform's public key; the API only
  * ever receives envelopes, and values are never returned.
  *
+ * A customer-protected secret's versions are also wrapped locally with your
+ * own key (`createCustomerKey()`, or your own `CustomerKey`), so the platform
+ * stores nothing it can open alone. Each use passes the reference `unwrap()`
+ * returns.
+ *
  * Methods that take `secret` accept its ID or its exact name. A UUID-shaped
  * argument is tried as an ID first and then as a name, since names may look
  * like UUIDs.
@@ -67,13 +84,26 @@ class SecretsService extends base_1.BaseService {
      * empty secret behind.
      */
     async create(params) {
-        const { name, description, type, allowedOrigins, value } = params ?? {};
+        const { name, description, type, allowedOrigins, value, customerKey } = params ?? {};
         if (typeof name !== "string" || !secret_references_1.SECRET_NAME_PATTERN.test(name)) {
             throw new error_1.HyperbrowserError("Secret name must be 1-128 letters, digits, '_' or '-', starting with a letter or digit");
         }
         if (type !== undefined && (typeof type !== "string" || !type)) {
             throw (0, error_1.invalidRequest)('type must be "secret", "totp" or "op_token"');
         }
+        const protection = params.protection ?? (customerKey !== undefined ? "customer" : undefined);
+        if (protection !== undefined && protection !== "platform" && protection !== "customer") {
+            throw (0, error_1.invalidRequest)('protection must be "platform" or "customer"');
+        }
+        if (customerKey !== undefined) {
+            if (protection !== "customer") {
+                throw (0, error_1.invalidRequest)('customerKey is only for secrets with protection "customer"');
+            }
+            (0, customer_key_1.assertCustomerKey)(customerKey);
+        }
+        if (protection === "customer" && value !== undefined && customerKey === undefined) {
+            throw (0, error_1.invalidRequest)("A customer-protected secret's value is wrapped with your own key: pass customerKey");
+        }
         const plaintext = value === undefined ? undefined : (0, secret_values_1.secretPlaintext)(type ?? "secret", value);
         const sealer = plaintext === undefined ? undefined : secrets_envelope_1.SecretsSealer.fromPublicKey(await this.getPublicKey());
         const metadata = allowedOrigins === undefined ? undefined : { browser: { allowedOrigins } };
@@ -81,7 +111,7 @@ class SecretsService extends base_1.BaseService {
         try {
             secret = await this.request("/secrets", {
                 method: "POST",
-                body: JSON.stringify({ name, description, type, metadata }),
+                body: JSON.stringify({ name, description, type, metadata, protection }),
             });
         }
         catch (error) {
@@ -91,7 +121,7 @@ class SecretsService extends base_1.BaseService {
             return secret;
         }
         try {
-            const version = await this.uploadVersion(secret, sealer, plaintext);
+            const version = await this.uploadVersion(secret, sealer, plaintext, customerKey);
             return { ...secret, latestVersion: version.version };
         }
         catch (error) {
@@ -143,18 +173,124 @@ class SecretsService extends base_1.BaseService {
      * value is checked against the rules of the secret's type, such as a TOTP
      * seed's format, before it is sealed.
      */
-    async addVersion(secret, value) {
+    async addVersion(secret, value, options = {}) {
         (0, secrets_envelope_1.secretValueBytes)(value);
+        const { customerKey } = options ?? {};
+        if (customerKey !== undefined)
+            (0, customer_key_1.assertCustomerKey)(customerKey);
         const sealer = secrets_envelope_1.SecretsSealer.fromPublicKey(await this.getPublicKey());
         try {
             const resolved = await this.resolve(secret);
+            const customer = isCustomerProtected(resolved);
+            if (customer && customerKey === undefined) {
+                throw (0, error_1.invalidRequest)(`Secret ${resolved.name} is customer-protected: pass customerKey to wrap the value with`);
+            }
+            if (!customer && customerKey !== undefined) {
+                throw (0, error_1.invalidRequest)(`Secret ${resolved.name} is not customer-protected, so its versions aren't wrapped: omit customerKey`);
+            }
             const plaintext = (0, secret_values_1.secretPlaintext)(resolved.type ?? "secret", value);
-            return await this.uploadVersion(resolved, sealer, plaintext);
+            return await this.uploadVersion(resolved, sealer, plaintext, customerKey);
         }
         catch (error) {
             return rethrow(error, `Failed to add a version to secret ${secret}`);
         }
     }
+    /**
+     * A customer-protected version's wrapped envelope, for unwrapping with
+     * your own key. Most callers want `unwrap()`, which also unwraps it.
+     */
+    async getWrappedVersion(secret, version = "latest") {
+        assertVersion(version, true);
+        try {
+            const { id } = await this.resolve(secret);
+            return await this.fetchWrapped(id, version);
+        }
+        catch (error) {
+            return rethrow(error, `Failed to get the wrapped version of secret ${secret}`);
+        }
+    }
+    /**
+     * Unwrap a customer-protected version locally with your own key, giving
+     * the reference each use passes: as a sandbox's or process's `secrets`
+     * entry, or as a 1Password `token`. It is pinned to the version unwrapped.
+     * The unwrapped envelope is checked against the digest stored with the
+     * version, and only the platform can open it.
+     *
+     * `customerKey` may be several keys, such as during a rotation; the one
+     * whose `kid` wrapped the version is used.
+     */
+    async unwrap(secret, customerKey, options = {}) {
+        const version = options?.version ?? "latest";
+        assertVersion(version, true);
+        (0, customer_key_1.assertCustomerKeys)(customerKey);
+        try {
+            const resolved = await this.resolve(secret);
+            const wrapped = await this.fetchWrapped(resolved.id, version);
+            const unwrapped = await (0, customer_key_1.unwrapVersion)(wrapped, customerKey, `Version ${wrapped.version} of secret ${resolved.name}`);
+            return { name: resolved.name, version: wrapped.version, unwrapped };
+        }
+        catch (error) {
+            return rethrow(error, `Failed to unwrap secret ${secret}`);
+        }
+    }
+    /**
+     * Rewrap a customer-protected secret's versions with a new key, for
+     * rotating your own key. Each version is unwrapped with `from` and wrapped
+     * with `to` locally; the value never changes and the platform never sees
+     * it. Returns the versions rewrapped.
+     */
+    async rewrap(secret, params) {
+        const { from, to, versions } = params ?? {};
+        (0, customer_key_1.assertCustomerKeys)(from, "from", { allowEmpty: true });
+        (0, customer_key_1.assertCustomerKey)(to, "to");
+        if (versions !== undefined) {
+            if (!Array.isArray(versions))
+                throw (0, error_1.invalidRequest)("versions must be an array of version numbers");
+            versions.forEach((version) => assertVersion(version, false));
+        }
+        try {
+            const detail = await this.resolveDetail(secret);
+            if (!isCustomerProtected(detail)) {
+                throw (0, error_1.invalidRequest)(`Secret ${detail.name} is not customer-protected; it has no wrapping`);
+            }
+            const wanted = versions ??
+                detail.versions.filter(({ outerKid }) => outerKid !== to.kid).map(({ version }) => version);
+            const rewrapped = [];
+            for (const version of wanted) {
+                const wrapped = await this.fetchWrapped(detail.id, version);
+                const label = `Version ${version} of secret ${detail.name}`;
+                const inner = await (0, customer_key_1.unwrapVersion)(wrapped, from, label);
+                const envelope = await (0, customer_key_1.wrapEnvelope)(to, inner, detail.encryptionContext);
+                rewrapped.push(await this.putWrapping(detail.id, version, { envelope, innerDigest: wrapped.innerDigest }));
+            }
+            return rewrapped;
+        }
+        catch (error) {
+            return rethrow(error, `Failed to rewrap secret ${secret}`);
+        }
+    }
+    /**
+     * Replace a customer-protected version's outer envelope with one you
+     * wrapped yourself. `innerDigest` must match the version's: only the
+     * wrapping changes, never the value. `rewrap()` does this for you.
+     */
+    async replaceVersionWrapping(secret, version, params) {
+        assertVersion(version, false);
+        const { envelope, innerDigest } = params ?? {};
+        if (typeof envelope !== "string" || !envelope) {
+            throw (0, error_1.invalidRequest)("envelope must be the wrapped envelope");
+        }
+        if (typeof innerDigest !== "string" || !innerDigest) {
+            throw (0, error_1.invalidRequest)("innerDigest must be the version's innerDigest");
+        }
+        try {
+            const { id } = await this.resolve(secret);
+            return await this.putWrapping(id, version, { envelope, innerDigest });
+        }
+        catch (error) {
+            return rethrow(error, `Failed to replace the wrapping of version ${version} of secret ${secret}`);
+        }
+    }
     /**
      * Replace the origins a secret may be filled into in browser sessions, or
      * clear them with `null` (it then can't be filled until origins are set
@@ -180,9 +316,7 @@ class SecretsService extends base_1.BaseService {
     }
     /** Delete one stored version. The latest version cannot be deleted. */
     async deleteVersion(secret, version) {
-        if (!Number.isSafeInteger(version) || version < 1 || version > secret_references_1.MAX_SECRET_VERSION) {
-            throw new error_1.HyperbrowserError(`version must be an integer from 1 to ${secret_references_1.MAX_SECRET_VERSION}`);
-        }
+        assertVersion(version, false);
         try {
             const { id } = await this.resolve(secret);
             return await this.request(`${secretPath(id)}/versions/${version}`, {
@@ -193,11 +327,32 @@ class SecretsService extends base_1.BaseService {
             return rethrow(error, `Failed to delete version ${version} of secret ${secret}`);
         }
     }
-    /** Sealed to the context the API returned for the secret; never one built here. */
-    uploadVersion(secret, sealer, plaintext) {
+    /**
+     * Sealed to the context the API returned for the secret; never one built
+     * here. With a customer key, the sealed envelope is wrapped to the same
+     * context and the API keeps only the wrapped one and the inner digest.
+     */
+    async uploadVersion(secret, sealer, plaintext, customerKey) {
+        const inner = sealer.seal(secret.encryptionContext, plaintext);
+        const body = customerKey === undefined
+            ? { envelope: inner }
+            : {
+                envelope: await (0, customer_key_1.wrapEnvelope)(customerKey, inner, secret.encryptionContext),
+                innerDigest: (0, customer_key_1.secretEnvelopeDigest)(inner),
+                innerKid: sealer.kid,
+            };
         return this.request(`${secretPath(secret.id)}/versions`, {
             method: "POST",
-            body: JSON.stringify({ envelope: sealer.seal(secret.encryptionContext, plaintext) }),
+            body: JSON.stringify(body),
+        });
+    }
+    fetchWrapped(id, version) {
+        return this.request(`${secretPath(id)}/versions/${version}/wrapped`);
+    }
+    putWrapping(id, version, body) {
+        return this.request(`${secretPath(id)}/versions/${version}/wrapping`, {
+            method: "PUT",
+            body: JSON.stringify(body),
         });
     }
     async resolve(secret) {

package/dist/services/sessions.js

@@ -244,12 +244,53 @@ class SessionsService extends base_1.BaseService {
      */
     async uploadFile(id, fileOptions) {
         const { fileInput, fileName } = fileOptions;
+        // Our own file stream, destroyed when the upload settles. A stream the
+        // caller passes in stays theirs and is never destroyed here.
+        let ownedStream;
+        let sourceStream;
+        let streamError;
+        let rejectStreamError;
+        const streamFailure = new Promise((_, reject) => {
+            rejectStreamError = reject;
+        });
+        streamFailure.catch(() => { });
+        // Aborts the in-flight request when the body fails, so the socket is not
+        // held open until the request timeout.
+        const controller = new AbortController();
+        let readLabel = "";
+        // form-data re-emits a source stream's "error" on the FormData, and
+        // node-fetch pipes the body without an error listener, so an unlistened
+        // FormData error is thrown as an uncaught exception. Every FormData body
+        // therefore gets a listener, whatever the input type.
+        const onStreamError = (error) => {
+            if (!streamError) {
+                streamError = new client_1.HyperbrowserError(`Failed to read file ${readLabel}: ${error.message}`, undefined);
+            }
+            controller.abort();
+            rejectStreamError?.(streamError);
+        };
+        const buildBody = (file, filename) => {
+            const formData = new form_data_1.default();
+            formData.on("error", onStreamError);
+            if (!Buffer.isBuffer(file)) {
+                sourceStream = file;
+                file.on("error", onStreamError);
+            }
+            formData.append("file", file, { filename });
+            return {
+                method: "POST",
+                body: formData,
+                headers: formData.getHeaders(),
+                signal: controller.signal,
+            };
+        };
         try {
             let fetchOptions;
             if (typeof fileInput === "string") {
                 let stats;
                 try {
                     stats = await fs_1.promises.stat(fileInput);
+                    await fs_1.promises.access(fileInput, fs_1.constants.R_OK);
                 }
                 catch (error) {
                     if (error.code === "ENOENT") {
@@ -263,61 +304,47 @@ class SessionsService extends base_1.BaseService {
                 if (!stats.isFile()) {
                     throw new client_1.HyperbrowserError(`Path is not a file: ${fileInput}`, undefined);
                 }
-                const formData = new form_data_1.default();
-                const fileStream = (0, fs_1.createReadStream)(fileInput);
-                const fileBaseName = fileName || path.basename(fileInput);
-                fileStream.on("error", (error) => {
-                    throw new client_1.HyperbrowserError(`Failed to read file ${fileInput}: ${error.message}`, undefined);
-                });
-                formData.append("file", fileStream, {
-                    filename: fileBaseName,
-                });
-                fetchOptions = {
-                    method: "POST",
-                    body: formData,
-                    headers: formData.getHeaders(),
-                };
+                readLabel = `at ${fileInput}`;
+                ownedStream = (0, fs_1.createReadStream)(fileInput);
+                fetchOptions = buildBody(ownedStream, fileName || path.basename(fileInput));
             }
             else if (this.isReadableStream(fileInput)) {
-                const formData = new form_data_1.default();
                 let tmpFileName = fileName || `file-${Date.now()}`;
                 if (fileInput.path && typeof fileInput.path === "string" && !fileName) {
                     tmpFileName = path.basename(fileInput.path);
                 }
-                formData.append("file", fileInput, {
-                    filename: tmpFileName,
-                });
-                fetchOptions = {
-                    method: "POST",
-                    body: formData,
-                    headers: formData.getHeaders(),
-                };
+                readLabel = `stream ${tmpFileName}`;
+                fetchOptions = buildBody(fileInput, tmpFileName);
             }
             else if (Buffer.isBuffer(fileInput)) {
                 if (!fileName) {
                     throw new client_1.HyperbrowserError("fileName is required when uploading Buffer data", undefined);
                 }
-                const formData = new form_data_1.default();
-                formData.append("file", fileInput, {
-                    filename: fileName,
-                });
-                fetchOptions = {
-                    method: "POST",
-                    body: formData,
-                    headers: formData.getHeaders(),
-                };
+                readLabel = `buffer ${fileName}`;
+                fetchOptions = buildBody(fileInput, fileName);
             }
             else {
                 throw new client_1.HyperbrowserError("Unsupported file input type. Please provide a file path string, ReadStream, or Buffer.", undefined);
             }
-            return await this.request(`/session/${id}/uploads`, fetchOptions);
+            const requestPromise = this.request(`/session/${id}/uploads`, fetchOptions);
+            requestPromise.catch(() => { });
+            return await Promise.race([requestPromise, streamFailure]);
         }
         catch (error) {
+            if (streamError) {
+                throw streamError;
+            }
             if (error instanceof client_1.HyperbrowserError) {
                 throw error;
             }
             throw new client_1.HyperbrowserError(`Failed to upload file for session ${id}: ${error}`, undefined);
         }
+        finally {
+            if (sourceStream && sourceStream !== ownedStream) {
+                sourceStream.removeListener("error", onStreamError);
+            }
+            ownedStream?.destroy();
+        }
     }
     /**
      * Helper method to check if input is a readable stream

package/dist/services/vaults.d.ts

@@ -1,10 +1,17 @@
-import { CreateVaultParams, UpdateVaultParams, Vault, VaultDeleteResult, VaultListParams, VaultListResponse } from "../types/vault";
+import { CustomerKey } from "../customer-key";
+import { CreateVaultParams, UpdateVaultParams, Vault, VaultDeleteResult, VaultListParams, VaultListResponse, VaultReference, WrappedVault } from "../types/vault";
 import { BaseService } from "./base";
 /**
  * Vaults name a set of environment variables whose values come from stored
  * secrets. Pass one as `vault` to a sandbox process
  * or sandbox create, or attach it to a browser session with
- * `credentials: [{ vault }]` and fill its entries by name.
+ * `credentials: [{ vault }]` and fill its entries by name. A session
+ * attaches the vault by reference, so each fill uses its entries as they are
+ * then.
+ *
+ * Entries may be customer-protected secrets. Each sandbox or process use then
+ * passes the vault as `unwrap()` returns it, with those entries' envelopes
+ * unwrapped with your own key.
  *
  * Methods that take `vault` accept its ID or its exact name. A UUID-shaped
  * argument is tried as an ID first and then as a name.
@@ -22,5 +29,21 @@ export declare class VaultsService extends BaseService {
     update(vault: string, params: UpdateVaultParams): Promise<Vault>;
     /** Delete a vault. The secrets its entries name are kept. */
     delete(vault: string): Promise<VaultDeleteResult>;
+    /**
+     * The wrapped envelopes of a vault's customer-protected entries, each at
+     * the version its entry resolves to now. Most callers want `unwrap()`.
+     */
+    getWrapped(vault: string): Promise<WrappedVault>;
+    /**
+     * Unwrap a vault's customer-protected entries locally with your own key,
+     * giving the reference to pass as a sandbox's or process's `vault`. Each
+     * envelope is checked against the digest stored with its version. A vault
+     * with no customer-protected entries needs none and can be passed by name.
+     *
+     * `customerKey` may be several keys; each entry uses the one whose `kid`
+     * wrapped it. If an entry changes after this, uses fail with
+     * `SECRET_VAULT_CHANGED`: unwrap the vault again.
+     */
+    unwrap(vault: string, customerKey: CustomerKey | readonly CustomerKey[]): Promise<VaultReference>;
     private resolve;
 }

package/dist/services/vaults.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VaultsService = void 0;
+const customer_key_1 = require("../customer-key");
 const error_1 = require("../error");
 const base_1 = require("./base");
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -11,7 +12,13 @@ const vaultPath = (id) => `/vaults/${encodeURIComponent(id)}`;
  * Vaults name a set of environment variables whose values come from stored
  * secrets. Pass one as `vault` to a sandbox process
  * or sandbox create, or attach it to a browser session with
- * `credentials: [{ vault }]` and fill its entries by name.
+ * `credentials: [{ vault }]` and fill its entries by name. A session
+ * attaches the vault by reference, so each fill uses its entries as they are
+ * then.
+ *
+ * Entries may be customer-protected secrets. Each sandbox or process use then
+ * passes the vault as `unwrap()` returns it, with those entries' envelopes
+ * unwrapped with your own key.
  *
  * Methods that take `vault` accept its ID or its exact name. A UUID-shaped
  * argument is tried as an ID first and then as a name.
@@ -50,6 +57,36 @@ class VaultsService extends base_1.BaseService {
         const { id } = await this.resolve(vault);
         return await this.request(vaultPath(id), { method: "DELETE" });
     }
+    /**
+     * The wrapped envelopes of a vault's customer-protected entries, each at
+     * the version its entry resolves to now. Most callers want `unwrap()`.
+     */
+    async getWrapped(vault) {
+        const { id } = await this.resolve(vault);
+        return await this.request(`${vaultPath(id)}/wrapped`);
+    }
+    /**
+     * Unwrap a vault's customer-protected entries locally with your own key,
+     * giving the reference to pass as a sandbox's or process's `vault`. Each
+     * envelope is checked against the digest stored with its version. A vault
+     * with no customer-protected entries needs none and can be passed by name.
+     *
+     * `customerKey` may be several keys; each entry uses the one whose `kid`
+     * wrapped it. If an entry changes after this, uses fail with
+     * `SECRET_VAULT_CHANGED`: unwrap the vault again.
+     */
+    async unwrap(vault, customerKey) {
+        (0, customer_key_1.assertCustomerKeys)(customerKey, "customerKey", { allowEmpty: true });
+        const wrapped = await this.getWrapped(vault);
+        const unwrapped = {};
+        for (const [env, entry] of Object.entries(wrapped.entries ?? {})) {
+            unwrapped[env] = {
+                version: entry.version,
+                unwrapped: await (0, customer_key_1.unwrapVersion)(entry, customerKey, `Entry ${env} of vault ${wrapped.name} (version ${entry.version} of secret ${entry.name})`),
+            };
+        }
+        return { name: wrapped.name, unwrapped };
+    }
     async resolve(key) {
         if (typeof key !== "string" || !key.trim()) {
             throw (0, error_1.invalidRequest)("A vault ID or name is required");

package/dist/tools/index.js

@@ -65,10 +65,10 @@ WebsiteCrawlTool.openaiToolDefinition = openai_1.CRAWL_TOOL_OPENAI;
 WebsiteCrawlTool.anthropicToolDefinition = anthropic_1.CRAWL_TOOL_ANTHROPIC;
 class WebsiteExtractTool {
     static async runnable(hb, params) {
-        if (params.schema && typeof params.schema === "string") {
-            params.schema = JSON.parse(params.schema);
-        }
-        const resp = await hb.extract.startAndWait(params);
+        const requestParams = params.schema && typeof params.schema === "string"
+            ? { ...params, schema: JSON.parse(params.schema) }
+            : { ...params };
+        const resp = await hb.extract.startAndWait(requestParams);
         return resp.data ? JSON.stringify(resp.data) : "";
     }
 }

package/dist/types/constants.d.ts

@@ -30,7 +30,7 @@ export type BrowserUseLlm = "gpt-4o" | "gpt-4o-mini" | "gpt-4.1" | "gpt-4.1-mini
  | "claude-3-5-sonnet-20241022"
 /** @deprecated Retired; the API maps this to "claude-sonnet-5". */
  | "claude-3-5-haiku-20241022" | "gemini-2.0-flash" | "gemini-2.5-flash" | "gemini-3.8-flash";
-export type ClaudeComputerUseLlm = "claude-opus-5-5" | "claude-fable-5-1" | "claude-opus-5" | "claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | "claude-opus-4-5" | "claude-sonnet-5-5" | "claude-sonnet-5" | "claude-sonnet-4-6" | "claude-haiku-5-5" | "claude-haiku-4-5-20251001"
+export type ClaudeComputerUseLlm = "claude-opus-5-5" | "claude-fable-5-2" | "claude-fable-5-1" | "claude-opus-5" | "claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | "claude-opus-4-5" | "claude-sonnet-5-5" | "claude-sonnet-5" | "claude-sonnet-4-6" | "claude-haiku-5-5" | "claude-haiku-4-5-20251001"
 /** @deprecated Retires November 30, 2026; use "claude-sonnet-5-5". */
  | "claude-sonnet-4-5"
 /** @deprecated Retired; the API maps this to "claude-sonnet-4-6". */
@@ -48,7 +48,7 @@ export type HyperAgentVersion = "0.8.0" | "1.1.0";
 export type HyperAgentLlm = "gpt-6-luna" | "gpt-5.6-luna" | "gpt-5.5" | "gpt-5.2" | "gpt-5.1" | "gpt-5" | "gpt-5-mini" | "gpt-4o" | "gpt-4o-mini" | "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "claude-sonnet-5" | "claude-sonnet-4-6" | "claude-haiku-5-5"
 /** @deprecated Retires November 30, 2026; use "claude-sonnet-5". */
  | "claude-sonnet-4-5" | "gemini-2.5-flash" | "gemini-3.8-flash" | "gemini-3.7-flash" | "gemini-3-flash-preview";
-export type GeminiComputerUseLlm = "gemini-4-argon" | "gemini-3.8-flash" | "gemini-3.7-flash" | "gemini-3.6-flash" | "gemini-3.5-flash" | "gemini-3.5-flash-lite" | "gemini-3-flash-preview" | "gemini-2.5-computer-use-preview-10-2025";
+export type GeminiComputerUseLlm = "gemini-4-carbon" | "gemini-4-argon" | "gemini-3.8-flash" | "gemini-3.7-flash" | "gemini-3.6-flash" | "gemini-3.5-flash" | "gemini-3.5-flash-lite" | "gemini-3-flash-preview" | "gemini-2.5-computer-use-preview-10-2025";
 export type GeminiComputerUseReasoningEffort = "minimal" | "low" | "medium" | "high";
 export type GrokComputerUseLlm = "grok-4.7" | "grok-4.6" | "grok-4.5";
 export type GrokReasoningEffort = "low" | "medium" | "high";

package/dist/types/credential.d.ts

@@ -1,13 +1,22 @@
+import type { SandboxStoredSecretReference } from "./sandbox";
 /** A secret attached to a browser session, which fill may type into its pages. */
 export interface SessionCredential {
     id: string;
     name: string;
 }
+/**
+ * A vault attached to a browser session by reference: each fill uses its
+ * entries as they are at that moment.
+ */
+export interface SessionVault {
+    id: string;
+    name: string;
+}
 /**
  * What to attach to a browser session at creation: a secret by name (or
- * `{ secret }`), `{ vault }` for the secrets a vault's entries name, or
- * `{ onePassword }` for an `op_token` secret that fills may read 1Password
- * fields with.
+ * `{ secret }`), `{ vault }` for a vault by reference (each fill reads its
+ * entries as they are then), or `{ onePassword }` for an `op_token` secret
+ * that fills may read 1Password fields with.
  */
 export type SessionCredentialSource = string | {
     secret: string;
@@ -47,8 +56,8 @@ export interface CredentialFillField {
  * the request names the origins it may be typed on.
  */
 export interface CredentialFillOnePassword {
-    /** The `op_token` secret attached to the session, by name; its latest version is used. */
-    token: string;
+    /** The `op_token` secret attached to the session: its name (its latest version is used), or a reference. */
+    token: string | SandboxStoredSecretReference;
     /** The 1Password vault's name or ID. */
     vault: string;
     /**

package/dist/types/index.d.ts

@@ -1,7 +1,7 @@
 export { HyperbrowserConfig } from "./config";
 export * from "./webmcp";
 export { StartCrawlJobParams, StartCrawlJobResponse, CrawledPage, CrawlJobResponse, GetCrawlJobParams, CrawlJobStatusResponse, } from "./crawl";
-export { StartScrapeJobParams, StartScrapeJobResponse, ScrapeJobData, ScrapeJobResponse, ScrapeOptions, ScrapeJobStatusResponse, BatchScrapeJobStatusResponse, StorageStateOptions, } from "./scrape";
+export { StartScrapeJobParams, StartScrapeJobResponse, ScrapeJobData, ScrapeJobResponse, ScrapeOptions, ScrapeJobStatusResponse, StartBatchScrapeJobParams, StartBatchScrapeJobResponse, BatchScrapeJobStatusResponse, BatchScrapeJobResponse, GetBatchScrapeJobParams, ScrapedPage, ScreenshotOptions, StorageStateOptions, } from "./scrape";
 export { StartExtractJobParams, StartExtractJobResponse, ExtractJobResponse, ExtractJobStatusResponse, ExtractJobMetadata, } from "./extract";
 export { StartBrowserUseTaskParams, StartBrowserUseTaskResponse, BrowserUseTaskStatusResponse, BrowserUseTaskResponse, BrowserUseTaskData, BrowserUseApiKeys, BrowserUseTaskMetadata, BrowserUseStep, BrowserUseAgentBrain, BrowserUseAgentOutput, BrowserUseActionResult, BrowserUseStepMetadata, BrowserUseTabInfo, BrowserUseBrowserStateHistory, BrowserUseAgentHistory, BrowserUseAgentOutputV0710, BrowserUseActionResultV0710, BrowserUseBrowserStateHistoryV0710, BrowserUseStepMetadataV0710, BrowserUseAgentHistoryV0710, BrowserUseAgentHistoryLatest, } from "./agents/browser-use";
 export { StartClaudeComputerUseTaskParams, StartClaudeComputerUseTaskResponse, ClaudeComputerUseTaskStatusResponse, ClaudeComputerUseTaskResponse, ClaudeComputerUseTaskData, ClaudeComputerUseStepResponse, ClaudeComputerUseApiKeys, ClaudeComputerUseTaskMetadata, } from "./agents/claude-computer-use";
@@ -11,12 +11,14 @@ export { StartGeminiComputerUseTaskParams, StartGeminiComputerUseTaskResponse, G
 export { StartGrokComputerUseTaskParams, StartGrokComputerUseTaskResponse, GrokComputerUseTaskStatusResponse, GrokComputerUseTaskResponse, GrokComputerUseTaskData, GrokComputerUseStepResponse, GrokComputerUseApiKeys, GrokComputerUseTaskMetadata, } from "./agents/grok-computer-use";
 export { StartMetaComputerUseTaskParams, StartMetaComputerUseTaskResponse, MetaComputerUseTaskStatusResponse, MetaComputerUseTaskResponse, MetaComputerUseTaskData, MetaComputerUseStepResponse, MetaComputerUseStepError, MetaComputerUseStepIncompleteDetails, MetaComputerUseStepReasoning, MetaComputerUseApiKeys, MetaComputerUseTaskMetadata, } from "./agents/meta-computer-use";
 export { StartJevComputerUseTaskParams, StartJevComputerUseTaskResponse, JevComputerUseTaskStatusResponse, JevComputerUseTaskResponse, JevComputerUseTaskData, JevComputerUseStepResponse, JevComputerUseApiKeys, JevComputerUseTaskMetadata, } from "./agents/jev-computer-use";
-export { BasicResponse, BrowserMemorySize, SessionStatus, Session, SessionDetail, SessionGetParams, SessionListParams, SessionListResponse, ScreenConfig, CaptchaEvaluationPageResult, CaptchaEvaluationParams, CaptchaEvaluationResponse, CaptchaEvaluationTarget, CaptchaEvaluationType, CaptchaSolverType, CreateSessionParams, CreateSessionSnapshotResponse, GetSessionDownloadsUrlResponse, GetSessionVideoRecordingUrlResponse, GetSessionRecordingUrlResponse, ImageCaptchaParam, UploadFileResponse, UploadFileOptions, GetActiveSessionsCountResponse, SessionEventLogListParams, SessionEventLogListResponse, SessionEventLog, SessionProfile, SessionLaunchState, SessionWebBotAuth, SessionCreditBreakdown, StartSessionFromSnapshotParams, WebBotAuthParams, ProxyRoute, UpdateSessionProfileParams, UpdateSessionProxyLocationParams, UpdateSessionProxyParams, UpdateSessionScreenParams, UpdateSessionSolveCaptchasParams, UpdateSessionSolveCaptchasResponse, } from "./session";
-export { SandboxStatus, SandboxRuntimeTarget, SandboxNetworkPolicy, SandboxNetworkPolicyPatch, SandboxNetworkUpdateResult, Sandbox, SandboxDetail, SandboxVolumeMountType, SandboxVolumeMount, SandboxSecretReference, SandboxSecrets, SandboxResolvedSecret, SandboxStoredSecretBinding, SandboxOnePasswordBinding, SandboxSecretSource, SandboxOnePassword, SandboxOnePasswordField, SandboxListParams, SandboxListResponse, SandboxImageSource, SandboxImageSummary, SandboxImageListParams, SandboxImageListResponse, SandboxSnapshotStatus, SandboxSnapshotSummary, SandboxSnapshotListParams, SandboxSnapshotListResponse, SandboxSnapshotDeleteResult, SandboxImageDeleteResult, SandboxImageInit, SandboxImageBuildStatus, SandboxImageBuildInputFormat, SandboxImageBuildSourcePlatform, SandboxImageBuildUpload, SandboxImageBuild, SandboxBuildContextBundle, SandboxBuildContextMode, SandboxBuildContextManifest, SandboxDockerImageConfig, SandboxDockerImageLayer, SandboxDockerImageManifest, CreateSandboxImageBuildParams, ReuseSandboxDockerImageParams, CompleteSandboxImageBuildParams, SandboxImageBuildCreateResult, SandboxDockerImageReuseResult, SandboxImageBuildResolutionOutcome, SandboxImageBuildResolution, SandboxImageBuildWaitOptions, BuildSandboxImageFromDockerImageOptions, BuildSandboxImageFromDockerfileOptions, GetOrBuildSandboxImageOptions, SandboxImageBuildListParams, SandboxImageBuildListResponse, CreateSandboxParams, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxExposeParams, SandboxExposeResult, SandboxUnexposeResult, SandboxProcessStatus, SandboxExecParams, SandboxExecOptions, SandboxProcessSummary, SandboxProcessResult, SandboxProcessListParams, SandboxProcessListResponse, SandboxProcessWaitParams, SandboxProcessSignal, SandboxProcessStdinParams, SandboxProcessOutputEvent, SandboxProcessExitEvent, SandboxProcessStreamEvent, SandboxFileType, SandboxFileInfo, SandboxFileWriteInfo, SandboxFileListOptions, SandboxFileReadFormat, SandboxFileReadOptions, SandboxFileWriteData, SandboxFileWriteEntry, SandboxFileTextWriteOptions, SandboxFileBytesWriteOptions, SandboxFileMakeDirOptions, SandboxFileCopyParams, SandboxFileChmodParams, SandboxFileChownParams, SandboxFileTransferResult, SandboxFileSystemEventType, SandboxFileSystemEvent, SandboxWatchDirOptions, SandboxPresignFileParams, SandboxPresignedUrl, SandboxTerminalCreateParams, SandboxTerminalOutputChunk, SandboxTerminalStatus, SandboxTerminalWaitParams, SandboxTerminalKillParams, SandboxTerminalEvent, } from "./sandbox";
+export { BasicResponse, BrowserMemorySize, SessionStatus, Session, SessionDetail, SessionGetParams, SessionListParams, SessionListResponse, ScreenConfig, CreateSessionProfile, CaptchaEvaluationPageResult, CaptchaEvaluationParams, CaptchaEvaluationResponse, CaptchaEvaluationTarget, CaptchaEvaluationType, CaptchaSolverType, CreateSessionParams, CreateSessionSnapshotResponse, SessionRecording, GetSessionDownloadsUrlResponse, GetSessionVideoRecordingUrlResponse, GetSessionRecordingUrlResponse, ImageCaptchaParam, UploadFileResponse, UploadFileOptions, GetActiveSessionsCountResponse, SessionEventLogListParams, SessionEventLogListResponse, SessionEventLog, SessionProfile, SessionLaunchState, SessionWebBotAuth, SessionCreditBreakdown, StartSessionFromSnapshotParams, WebBotAuthParams, ProxyRoute, UpdateSessionProfileParams, UpdateSessionProxyLocationParams, UpdateSessionProxyParams, UpdateSessionScreenParams, UpdateSessionSolveCaptchasParams, UpdateSessionSolveCaptchasResponse, } from "./session";
+export { SandboxStatus, SandboxRuntimeTarget, SandboxNetworkPolicy, SandboxNetworkPolicyPatch, SandboxNetworkUpdateResult, Sandbox, SandboxDetail, SandboxVolumeMountType, SandboxVolumeMount, SandboxSecretReference, SandboxStoredSecretReference, SandboxSecrets, SandboxVaultSource, SandboxResolvedSecret, SandboxStoredSecretBinding, SandboxOnePasswordBinding, SandboxSecretSource, SandboxOnePassword, SandboxOnePasswordField, SandboxListParams, SandboxListResponse, SandboxImageSource, SandboxImageSummary, SandboxImageListParams, SandboxImageListResponse, SandboxSnapshotStatus, SandboxSnapshotSummary, SandboxSnapshotListParams, SandboxSnapshotListResponse, SandboxSnapshotDeleteResult, SandboxImageDeleteResult, SandboxImageInit, SandboxImageBuildStatus, SandboxImageBuildInputFormat, SandboxImageBuildSourcePlatform, SandboxImageBuildUpload, SandboxImageBuild, SandboxBuildContextBundle, SandboxBuildContextMode, SandboxBuildContextManifest, SandboxDockerImageConfig, SandboxDockerImageLayer, SandboxDockerImageManifest, CreateSandboxImageBuildParams, ReuseSandboxDockerImageParams, CompleteSandboxImageBuildParams, SandboxImageBuildCreateResult, SandboxDockerImageReuseResult, SandboxImageBuildResolutionOutcome, SandboxImageBuildResolution, SandboxImageBuildWaitOptions, BuildSandboxImageFromDockerImageOptions, BuildSandboxImageFromDockerfileOptions, GetOrBuildSandboxImageOptions, SandboxImageBuildListParams, SandboxImageBuildListResponse, CreateSandboxParams, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxExposeParams, SandboxExposeResult, SandboxUnexposeResult, SandboxProcessStatus, SandboxExecParams, SandboxExecOptions, SandboxProcessSummary, SandboxProcessResult, SandboxProcessListParams, SandboxProcessListResponse, SandboxProcessWaitParams, SandboxProcessSignal, SandboxProcessStdinParams, SandboxProcessOutputEvent, SandboxProcessExitEvent, SandboxProcessStreamEvent, SandboxFileType, SandboxFileInfo, SandboxFileWriteInfo, SandboxFileListOptions, SandboxFileReadFormat, SandboxFileReadOptions, SandboxFileWriteData, SandboxFileWriteEntry, SandboxFileTextWriteOptions, SandboxFileBytesWriteOptions, SandboxFileMakeDirOptions, SandboxFileCopyParams, SandboxFileChmodParams, SandboxFileChownParams, SandboxFileTransferResult, SandboxFileSystemEventType, SandboxFileSystemEvent, SandboxWatchDirOptions, SandboxPresignFileParams, SandboxPresignedUrl, SandboxTerminalCreateParams, SandboxTerminalOutputChunk, SandboxTerminalStatus, SandboxTerminalWaitParams, SandboxTerminalKillParams, SandboxTerminalEvent, } from "./sandbox";
 export { CreateVolumeParams, Volume, VolumeListParams, VolumeListResponse, VolumeDeleteResult, } from "./volume";
-export { SecretValue, SecretType, SecretBrowserMetadata, SecretMetadata, UpdateSecretMetadata, SecretsPublicKey, SecretsPublicKeyJwk, Secret, SecretVersion, SecretDetail, CreateSecretParams, UpdateSecretParams, SecretListParams, SecretListResponse, SecretDeleteResult, SecretVersionDeleteResult, } from "./secret";
-export { SessionCredential, SessionCredentialSource, CredentialFillField, CredentialFillRef, CredentialFillOnePassword, FillCredentialParams, CredentialFillOutcome, CredentialFillFieldResult, CredentialFillResult, CredentialFillPage, } from "./credential";
-export { Vault, VaultEntry, VaultEntryParams, CreateVaultParams, UpdateVaultParams, VaultListParams, VaultListResponse, VaultDeleteResult, } from "./vault";
+export { SecretValue, SecretType, SecretProtection, SecretBrowserMetadata, SecretMetadata, UpdateSecretMetadata, SecretsPublicKey, SecretsPublicKeyJwk, Secret, SecretVersion, SecretDetail, CreateSecretParams, UpdateSecretParams, SecretListParams, SecretListResponse, SecretDeleteResult, SecretVersionDeleteResult, WrappedSecretVersion, UnwrappedSecretReference, UnwrapSecretOptions, AddSecretVersionOptions, ReplaceSecretVersionWrappingParams, RewrapSecretParams, } from "./secret";
+export { SessionCredential, SessionCredentialSource, SessionVault } from "./credential";
+export type { CustomerKey, CustomerKeyAlgorithm, CustomerKeyInput, CustomerKeyOptions, } from "../customer-key";
+export { CredentialFillField, CredentialFillRef, CredentialFillOnePassword, FillCredentialParams, CredentialFillOutcome, CredentialFillFieldResult, CredentialFillResult, CredentialFillPage, } from "./credential";
+export { Vault, VaultEntry, VaultEntryParams, CreateVaultParams, UpdateVaultParams, VaultListParams, VaultListResponse, VaultDeleteResult, WrappedVault, WrappedVaultEntry, VaultUnwrappedEntry, VaultReference, } from "./vault";
 export { CreateProfileParams, ForkProfileParams, ProfileResponse, CreateProfileResponse, ProfileListParams, ProfileListResponse, } from "./profile";
 export { CreateExtensionParams, CreateExtensionResponse, ListExtensionsResponse, } from "./extension";
 export { ExtractJobStatus, BrowserUseTaskStatus, BrowserUseLlm, ClaudeComputerUseLlm, ClaudeComputerUseReasoningEffort, CuaLlm, CuaReasoningEffort, GeminiComputerUseLlm, GeminiComputerUseReasoningEffort, GrokComputerUseLlm, GrokReasoningEffort, MetaComputerUseLlm, MetaReasoningEffort, JevComputerUseLlm, JevTextLlm, ScrapeScreenshotFormat, ScrapeJobStatus, CrawlJobStatus, Country, State, ISO639_1, OperatingSystem, Platform, ScrapeFormat, ScrapeWaitUntil, ScrapePageStatus, CrawlPageStatus, RecordingStatus, DownloadsStatus, HyperAgentLlm, HyperAgentTaskStatus, ClaudeComputerUseTaskStatus, CuaTaskStatus, GeminiComputerUseTaskStatus, GrokComputerUseTaskStatus, MetaComputerUseTaskStatus, JevComputerUseTaskStatus, SessionEventLogType, SessionRegion, BrowserUseVersion, HyperAgentVersion, } from "./constants";
@@ -24,6 +26,7 @@ export { TeamCreditInfo } from "./team";
 export { ComputerAction, Coordinate, ClickActionParams, DragActionParams, PressKeysActionParams, MoveMouseActionParams, ScreenshotActionParams, CursorPositionActionParams, ScrollAtCursorActionParams, ScrollActionParams, TypeTextActionParams, ComputerActionParams, ComputerActionResponse, ComputerActionMouseButton, ComputerActionResponseData, HoldKeyActionParams, MouseDownActionParams, MouseUpActionParams, GetClipboardTextActionParams, PutSelectionTextActionParams, ComputerActionResponseDataClipboardText, ListWindowsActionParams, ComputerActionWindow, ComputerActionResponseDataListWindows, ComputerActionResponseDataCursorPosition, } from "./computer-action";
 export { FetchParams, FetchResponse, FetchResponseData, FetchStatus } from "./web/fetch";
 export { StartBatchFetchJobParams, GetBatchFetchJobParams, StartBatchFetchJobResponse, BatchFetchJobStatusResponse, BatchFetchJobResponse, BatchFetchJobStatus, } from "./web/batch-fetch";
+export { WebCrawlJobStatus, WebCrawlOptions, StartWebCrawlJobParams, GetWebCrawlJobParams, StartWebCrawlJobResponse, WebCrawlJobStatusResponse, WebCrawlJobResponse, } from "./web/crawl";
 export { WebSearchParams, WebSearchResponse, WebSearchResponseData, WebSearchResultItem, WebSearchFilters, WebSearchLocation, WebSearchFiletype, WebSearchStatus, } from "./web/search";
 export { FetchStealthMode, FetchSanitizeMode, FetchWaitUntil, FetchScreenshotFormat, PageStatus, FetchOutputScreenshotOptions, FetchStorageStateOptions, FetchBrowserLocationOptions, PageData, FetchOutputMarkdown, FetchOutputHtml, FetchOutputLinks, FetchOutputScreenshot, FetchOutputJsonOptions, FetchOutputJson, FetchOutputBranding, FetchOutputFormat, FetchOutputOptions, FetchBrowserOptions, FetchNavigationOptions, FetchCacheOptions, } from "./web/common";
 export { BrandingProfile, BrandingColors, BrandingFont, BrandingFontRole, BrandingTypography, BrandingFontFamilies, BrandingFontStacks, BrandingFontSizes, BrandingSpacing, BrandingComponents, BrandingButtonStyle, BrandingInputStyle, BrandingBorderRadiusCorners, BrandingImages, BrandingPersonality, BrandingPersonalityTone, BrandingPersonalityEnergy, BrandingDesignSystem, BrandingDesignFramework, BrandingConfidence, BrandingColorScheme, } from "./web/branding";