@hyperbrowser/sdk 1.4.0 → 1.5.0

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,35 @@ 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) {
+        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/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". */
@@ -42,7 +42,7 @@ export type ClaudeComputerUseLlm = "claude-opus-5-5" | "claude-fable-5-1" | "cla
 /** @deprecated Retired legacy ID; the API maps this to "claude-opus-4-8". */
  | "claude-4-opus-20250514";
 export type ClaudeComputerUseReasoningEffort = "low" | "medium" | "high" | "xhigh" | "max";
-export type CuaLlm = "computer-use-preview" | "gpt-6-astra" | "gpt-6.1-sol" | "gpt-6-sol" | "gpt-6-luna" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gpt-5.5" | "gpt-5.4" | "gpt-5.4-mini";
+export type CuaLlm = "computer-use-preview" | "gpt-6-astra" | "gpt-6.1-sol" | "gpt-6.1-terra" | "gpt-6-sol" | "gpt-6-luna" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gpt-5.5" | "gpt-5.4" | "gpt-5.4-mini";
 export type CuaReasoningEffort = "none" | "low" | "medium" | "high" | "xhigh" | "max";
 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"

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

@@ -12,11 +12,13 @@ export { StartGrokComputerUseTaskParams, StartGrokComputerUseTaskResponse, GrokC
 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 { 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";

package/dist/types/sandbox.d.ts

@@ -2,6 +2,7 @@ import type { Blob } from "buffer";
 import type { ReadableStream } from "node:stream/web";
 import { SessionRegion } from "./constants";
 import { SessionLaunchState, SessionStatus } from "./session";
+import type { VaultReference } from "./vault";
 export type SandboxStatus = SessionStatus;
 export interface SandboxNetworkPolicy {
     allowInternetAccess?: boolean | null;
@@ -73,23 +74,38 @@ export interface SandboxDetail extends Sandbox {
 }
 export type SandboxVolumeMountType = "rw" | "ro";
 /**
- * A stored secret to deliver as an environment variable: its name, or
- * `{ name, version }` to pin a version. The latest version is used otherwise.
+ * A stored secret by name, optionally pinned to a version. A
+ * customer-protected secret also carries `unwrapped`, the envelope the
+ * customer unwrapped, and must pin the version it came from;
+ * `secrets.unwrap()` returns one ready to pass.
  */
-export type SandboxSecretReference = string | {
+export interface SandboxStoredSecretReference {
     name: string;
     version?: number | "latest";
-};
+    /** Customer-protected secrets only: the version's unwrapped inner envelope. */
+    unwrapped?: string;
+}
+/**
+ * A stored secret to deliver as an environment variable: its name, or
+ * `{ name, version }` to pin a version. The latest version is used otherwise.
+ */
+export type SandboxSecretReference = string | SandboxStoredSecretReference;
 /** Environment variable name to secret, at most 32 per process or sandbox. */
 export type SandboxSecrets = Record<string, SandboxSecretReference>;
+/**
+ * A vault whose entries become environment variables: its name, or, when it
+ * has customer-protected entries, the `VaultReference` from
+ * `vaults.unwrap()` with their unwrapped envelopes.
+ */
+export type SandboxVaultSource = string | VaultReference;
 /**
  * Fields of one 1Password vault to deliver as environment variables, read
  * with a service account token kept as an `op_token` secret when the process
  * starts. Nothing about it is stored.
  */
 export interface SandboxOnePassword {
-    /** The name of the `op_token` secret; its latest version is used. */
-    token: string;
+    /** The `op_token` secret: its name (its latest version is used), or a reference. */
+    token: string | SandboxStoredSecretReference;
     /** The 1Password vault's name or ID. */
     vault: string;
     /**
@@ -193,11 +209,11 @@ export type CreateSandboxParams = (SandboxCreateCommonParams & {
      */
     secrets?: SandboxSecrets;
     /**
-     * A vault, by name, whose entries become the startup command's
-     * environment variables; `secrets` is merged over it and wins on a
-     * clash. Same requirements as `secrets`.
+     * A vault whose entries become the startup command's environment
+     * variables; `secrets` is merged over it and wins on a clash. Same
+     * requirements as `secrets`.
      */
-    vault?: string;
+    vault?: SandboxVaultSource;
     /** 1Password fields for the startup command. Same requirements as `secrets`. */
     onePassword?: SandboxOnePassword;
 });
@@ -526,12 +542,12 @@ export interface SandboxExecParams {
      */
     secrets?: SandboxSecrets;
     /**
-     * A vault, by name, whose entries become environment variables of this
-     * process, delivered like `secrets`. `secrets` is merged over it and wins
-     * on a clash; `env` can't set a variable either of them sets. Together
-     * they hold at most 32 variables.
+     * A vault whose entries become environment variables of this process,
+     * delivered like `secrets`. `secrets` is merged over it and wins on a
+     * clash; `env` can't set a variable either of them sets. Together they hold
+     * at most 32 variables.
      */
-    vault?: string;
+    vault?: SandboxVaultSource;
     /**
      * Fields of a 1Password vault, read with an `op_token` secret when the
      * process starts and delivered like `secrets`. A variable set here can't

package/dist/types/secret.d.ts

@@ -1,5 +1,12 @@
+import type { CustomerKey } from "../customer-key";
 /** A secret value: a UTF-8 string or its raw bytes, used byte-for-byte. */
 export type SecretValue = string | Uint8Array;
+/**
+ * Fixed at creation. `"customer"` secrets are also wrapped with your own
+ * `CustomerKey`, and each use passes what `secrets.unwrap()` or
+ * `vaults.unwrap()` returns; they can't be filled into browser pages.
+ */
+export type SecretProtection = "platform" | "customer";
 /**
  * What a secret's value is, fixed at creation:
  * - `"secret"`: an opaque value. It can be a sandbox environment variable,
@@ -45,6 +52,11 @@ export interface Secret {
      */
     type: string;
     metadata: SecretMetadata;
+    /**
+     * A `SecretProtection`, typed as a string for values added later. Absent
+     * from API versions before customer protection, which means `"platform"`.
+     */
+    protection?: string;
     /** Bound into every envelope for this secret; the SDK uses it when encrypting. */
     encryptionContext: string;
     /** Null until a value is stored. */
@@ -54,9 +66,67 @@ export interface Secret {
 }
 export interface SecretVersion {
     version: number;
+    /** The platform key the (inner) envelope was encrypted to. */
     kid: string;
+    /** The customer key that wrapped this version; customer-protected secrets only. */
+    outerKid?: string;
+    /**
+     * When this version stops working because its platform key is retired.
+     * After then, uses fail with `SECRET_KEY_RETIRED`; add a new version and use
+     * that instead.
+     */
+    retiresAt?: string | null;
     createdAt: string;
 }
+/** A customer-protected version as the API stores it, for the customer to unwrap. */
+export interface WrappedSecretVersion {
+    version: number;
+    /** The platform key the inner envelope is encrypted to. */
+    kid: string;
+    retiresAt: string | null;
+    /** The customer key that wrapped it. */
+    outerKid: string;
+    /** Unpadded base64url SHA-256 of the inner envelope. */
+    innerDigest: string;
+    /** The outer envelope, which only the customer key can open. */
+    envelope: string;
+}
+/**
+ * A customer-protected secret ready to use: pass it as a sandbox or process
+ * `secrets` entry, or as a 1Password `token`. It is the version's inner
+ * envelope, which only the platform can open, but anyone holding it can use
+ * that version, so treat it like the secret itself.
+ */
+export interface UnwrappedSecretReference {
+    name: string;
+    version: number;
+    unwrapped: string;
+}
+export interface UnwrapSecretOptions {
+    /** Defaults to the latest version. */
+    version?: number | "latest";
+}
+export interface AddSecretVersionOptions {
+    /** Required for customer-protected secrets, which it wraps the value with; not allowed otherwise. */
+    customerKey?: CustomerKey;
+}
+/** A new outer envelope for a version, wrapping the same inner envelope. */
+export interface ReplaceSecretVersionWrappingParams {
+    envelope: string;
+    /** Must match the version's `innerDigest`: rewrapping can't change the value. */
+    innerDigest: string;
+}
+export interface RewrapSecretParams {
+    /** The key (or keys, picked by `kid`) the versions are wrapped with now. */
+    from: CustomerKey | readonly CustomerKey[];
+    /** The key to wrap them with instead. */
+    to: CustomerKey;
+    /**
+     * Versions to rewrap. Defaults to every version not already wrapped with
+     * `to`, so an interrupted rotation can be run again.
+     */
+    versions?: number[];
+}
 export interface SecretDetail extends Secret {
     versions: SecretVersion[];
 }
@@ -87,6 +157,16 @@ export interface CreateSecretParams {
      * `["https://github.com"]`; 1-20 entries. Not for `"op_token"` secrets.
      */
     allowedOrigins?: string[];
+    /**
+     * Defaults to `"customer"` when `customerKey` is given and `"platform"`
+     * otherwise. Fixed at creation.
+     */
+    protection?: SecretProtection;
+    /**
+     * The customer's own key, which wraps every version of a
+     * customer-protected secret. Required to store `value` in one.
+     */
+    customerKey?: CustomerKey;
 }
 /**
  * Metadata members sent replace the stored ones, `null` removes a member, and

package/dist/types/session.d.ts

@@ -1,6 +1,6 @@
 import fs from "fs";
 import { Country, DownloadsStatus, ISO639_1, OperatingSystem, Platform, RecordingStatus, SessionEventLogType, SessionRegion, State } from "./constants";
-import { SessionCredential, SessionCredentialSource } from "./credential";
+import { SessionCredential, SessionCredentialSource, SessionVault } from "./credential";
 export type SessionStatus = "active" | "closed" | "close-error" | "error";
 export type BrowserMemorySize = "small" | "medium" | "large";
 export interface BasicResponse {
@@ -76,6 +76,8 @@ export interface SessionDetail extends Session {
     token: string;
     /** The secrets attached at creation, when any were requested. */
     credentials?: SessionCredential[];
+    /** The vaults attached at creation, by reference, when credentials were requested. */
+    vaults?: SessionVault[];
 }
 export interface SessionGetParams {
     liveViewTtlSeconds?: number;
@@ -230,13 +232,13 @@ export interface CreateSessionParams {
     startFromSnapshot?: StartSessionFromSnapshotParams;
     /**
      * Secrets that `sessions.credentials.fill` may type into pages, at most 20:
-     * a secret's name (or `{ secret: name }`), `{ vault: name }` for the
-     * secrets a vault's entries name when the session is created, or
+     * a secret's name (or `{ secret: name }`), `{ vault: name }` for a vault
+     * by reference, whose entries each fill reads as they are then, or
      * `{ onePassword: name }` for an `op_token` secret whose 1Password fields
      * fills may read.
-     * Secrets need allowed origins to be filled. They can only be attached at
-     * creation; the session runs on Firecracker with Chrome's password manager
-     * off.
+     * Secrets need allowed origins to be filled, and customer-protected ones
+     * can't be filled. They can only be attached at creation; the session runs
+     * on Firecracker with Chrome's password manager off.
      */
     credentials?: SessionCredentialSource[];
 }

package/dist/types/vault.d.ts

@@ -1,3 +1,4 @@
+import type { WrappedSecretVersion } from "./secret";
 /** An entry of a vault: a stored secret. */
 export interface VaultEntry {
     /** The secret's name. */
@@ -5,6 +6,39 @@ export interface VaultEntry {
     secretId: string;
     /** A pinned version, or null to follow the secret's latest version. */
     version: number | null;
+    /**
+     * The secret's `SecretProtection`. With `"customer"`, each use of the vault
+     * passes this entry's unwrapped envelope (see `vaults.unwrap()`). Absent
+     * from API versions before customer protection.
+     */
+    protection?: string;
+}
+/** A customer-protected entry's wrapped envelope, at the version the entry resolves to now. */
+export interface WrappedVaultEntry extends WrappedSecretVersion {
+    /** The secret's name. */
+    name: string;
+    secretId: string;
+}
+export interface WrappedVault {
+    id: string;
+    name: string;
+    /** Customer-protected entries only, by environment variable. */
+    entries: Record<string, WrappedVaultEntry>;
+}
+/** The envelope the customer unwrapped for one entry, and the version it is from. */
+export interface VaultUnwrappedEntry {
+    version: number;
+    unwrapped: string;
+}
+/**
+ * A vault with its customer-protected entries unwrapped, as `vaults.unwrap()`
+ * returns it, for a sandbox's or process's `vault`. Anyone holding it can use
+ * those versions.
+ */
+export interface VaultReference {
+    name: string;
+    /** Environment variable name to unwrapped envelope; at most 32. */
+    unwrapped: Record<string, VaultUnwrappedEntry>;
 }
 /** Named environment variables whose values come from stored secrets. A vault holds no values itself. */
 export interface Vault {
@@ -16,7 +50,10 @@ export interface Vault {
     createdAt: string;
     updatedAt: string;
 }
-/** A stored secret, following its latest version unless one is pinned. */
+/**
+ * A stored secret, following its latest version unless one is pinned. It may
+ * be customer-protected; entries never hold unwrapped envelopes.
+ */
 export interface VaultEntryParams {
     /** The secret's name. */
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperbrowser/sdk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Node SDK for Hyperbrowser API",
   "author": "",
   "repository": {