@hyperbrowser/sdk 1.4.1 → 1.5.1

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 {
@@ -9,6 +9,7 @@ export interface BasicResponse {
 export interface SessionProfile {
     id: string;
     persistChanges?: boolean;
+    persistNetworkCache?: boolean;
 }
 /** How a session signs its requests with Web Bot Auth. */
 export interface SessionWebBotAuth {
@@ -48,6 +49,8 @@ export interface SessionLaunchState {
     enableAlwaysOpenPdfExternally?: boolean;
     appendTimestampToDownloads?: boolean;
     disablePostQuantumKeyAgreement?: boolean;
+    /** @deprecated Discontinued: WebGL fingerprinting was removed from the browser, and the server ignores this option. Kept so existing code still type-checks. */
+    enableWebglFingerprinting?: boolean;
 }
 export interface SessionCreditBreakdown {
     creditsUsed: number | null;
@@ -66,6 +69,8 @@ export interface Session {
     launchState?: SessionLaunchState | null;
     creditsUsed: number | null;
     creditBreakdown: SessionCreditBreakdown;
+    duration?: number;
+    proxyDataConsumed?: string;
 }
 export interface SessionDetail extends Session {
     wsEndpoint: string;
@@ -76,6 +81,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;
@@ -213,6 +220,7 @@ export interface CreateSessionParams {
     saveDownloads?: boolean;
     imageCaptchaParams?: Array<ImageCaptchaParam>;
     timeoutMinutes?: number;
+    /** @deprecated Discontinued: WebGL fingerprinting was removed from the browser, and the server ignores this option. Kept so existing code still type-checks. */
     enableWebglFingerprinting?: boolean;
     enableWindowManager?: boolean;
     enableWindowManagerTaskbar?: boolean;
@@ -230,13 +238,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.1",
+  "version": "1.5.1",
   "description": "Node SDK for Hyperbrowser API",
   "author": "",
   "repository": {