@hyperbrowser/sdk 1.4.1 → 1.5.1

package/dist/sandbox/process.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeSSEStream, RuntimeTransport } from "./base";
-import { WireOnePassword, WireSecretReference } from "./secret-references";
+import { WireOnePassword, WireSecretReference, WireVaultSource } 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;
@@ -20,8 +20,8 @@ export interface SecretProcessStartPayload {
     timeoutMs?: number;
     runAs?: string;
     secrets?: Record<string, WireSecretReference>;
-    /** A vault name; `secrets` is merged over its entries. */
-    vault?: string;
+    /** A vault, by name or with unwrapped entries; `secrets` is merged over its entries. */
+    vault?: WireVaultSource;
     /** 1Password fields; their variables can't come from any other source. */
     onePassword?: WireOnePassword;
 }

package/dist/sandbox/process.js

@@ -557,8 +557,8 @@ class SandboxProcessesApi {
             throw new error_1.HyperbrowserError("Starting a process with secrets requires a sandbox handle");
         }
         const secrets = (0, secret_references_1.serializeSecretReferences)(params.secrets);
-        const vault = params.vault;
-        const onePassword = params.onePassword;
+        const vault = (0, secret_references_1.serializeVaultSource)(params.vault);
+        const onePassword = (0, secret_references_1.serializeOnePassword)(params.onePassword);
         // A clash between env and the vault's variables is reported by the API.
         if (secrets !== undefined)
             (0, secret_references_1.assertNoEnvSecretOverlap)(params.env, secrets);

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

@@ -1,4 +1,4 @@
-import { SandboxSecrets } from "../types/sandbox";
+import { SandboxOnePassword, SandboxSecrets, SandboxVaultSource } from "../types/sandbox";
 /** Names of secrets and vaults. */
 export declare const SECRET_NAME_PATTERN: RegExp;
 /** The largest version number the API stores. */
@@ -8,12 +8,34 @@ export declare const isSecretEnvName: (name: unknown) => name is string;
 export interface WireSecretReference {
     name: string;
     version?: number | "latest";
+    unwrapped?: string;
+}
+export interface WireVaultReference {
+    name: string;
+    unwrapped: Record<string, {
+        version: number;
+        unwrapped: string;
+    }>;
+}
+/** A vault as the API takes it: its name, or its name with unwrapped entries. */
+export type WireVaultSource = string | WireVaultReference;
+export interface WireOnePassword extends Omit<SandboxOnePassword, "token"> {
+    token: string | WireSecretReference;
 }
 /**
  * Check secret references locally and convert them to the API's
- * `{ name, version? }` shape. Returns undefined when there are none.
+ * `{ name, version?, unwrapped? }` shape. Returns undefined when there are none.
  */
 export declare const serializeSecretReferences: (secrets: SandboxSecrets | undefined) => Record<string, WireSecretReference> | undefined;
+/**
+ * Check a vault source and convert it to the API's shape: a name is passed
+ * as is, and a `VaultReference` keeps only its name and unwrapped entries.
+ */
+export declare const serializeVaultSource: (vault: SandboxVaultSource | undefined) => WireVaultSource | undefined;
+/**
+ * Check a 1Password source's token, the one member that can be a secret
+ * reference; the API checks the rest.
+ */
+export declare const serializeOnePassword: <T extends Pick<SandboxOnePassword, "token">>(onePassword: T | undefined) => (Omit<T, "token"> & Pick<WireOnePassword, "token">) | 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;
-export type { SandboxOnePassword as WireOnePassword } from "../types/sandbox";

package/dist/sandbox/secret-references.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertNoEnvSecretOverlap = exports.serializeSecretReferences = exports.isSecretEnvName = exports.MAX_SECRET_VERSION = exports.SECRET_NAME_PATTERN = void 0;
+exports.assertNoEnvSecretOverlap = exports.serializeOnePassword = exports.serializeVaultSource = exports.serializeSecretReferences = exports.isSecretEnvName = exports.MAX_SECRET_VERSION = exports.SECRET_NAME_PATTERN = void 0;
 const error_1 = require("../error");
+const secrets_envelope_1 = require("../secrets-envelope");
 const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** The longest environment variable name the API stores. */
 const MAX_ENV_NAME_LENGTH = 256;
@@ -10,15 +11,44 @@ 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;
+/** The longest unwrapped envelope the API takes. */
+const MAX_UNWRAPPED_LENGTH = 64 * 1024;
 /** An environment variable name the API accepts for a secret or a vault entry. */
 const isSecretEnvName = (name) => typeof name === "string" &&
     name.length <= MAX_ENV_NAME_LENGTH &&
     ENV_NAME_PATTERN.test(name) &&
     name !== "__proto__";
 exports.isSecretEnvName = isSecretEnvName;
+const isVersionNumber = (version) => Number.isSafeInteger(version) &&
+    version >= 1 &&
+    version <= exports.MAX_SECRET_VERSION;
+const isUnwrappedEnvelope = (unwrapped) => typeof unwrapped === "string" &&
+    unwrapped.length >= 1 &&
+    unwrapped.length <= MAX_UNWRAPPED_LENGTH;
+/** Check one secret reference and convert it to the API's `{ name, version?, unwrapped? }`. */
+const serializeSecretReference = (reference, label) => {
+    const { name, version, unwrapped } = (typeof reference === "string" ? { name: reference } : (reference ?? {}));
+    if (typeof name !== "string" || !exports.SECRET_NAME_PATTERN.test(name)) {
+        throw new error_1.HyperbrowserError(`Invalid secret name for ${label}: ${String(name)}`);
+    }
+    if (version !== undefined && version !== "latest" && !isVersionNumber(version)) {
+        throw new error_1.HyperbrowserError(`Secret version for ${label} must be an integer from 1 to ${exports.MAX_SECRET_VERSION} or "latest"`);
+    }
+    if (unwrapped === undefined) {
+        return version === undefined ? { name } : { name, version: version };
+    }
+    if (!isUnwrappedEnvelope(unwrapped)) {
+        throw new error_1.HyperbrowserError(`The unwrapped envelope for ${label} must be a string of 1 to ${MAX_UNWRAPPED_LENGTH} characters`);
+    }
+    // An unwrapped envelope is one version's value; "latest" could move on.
+    if (typeof version !== "number") {
+        throw new error_1.HyperbrowserError(`Pin the version of ${label} to the version you unwrapped when passing "unwrapped"`, { code: "invalid_request" });
+    }
+    return { name, version, unwrapped };
+};
 /**
  * Check secret references locally and convert them to the API's
- * `{ name, version? }` shape. Returns undefined when there are none.
+ * `{ name, version?, unwrapped? }` shape. Returns undefined when there are none.
  */
 const serializeSecretReferences = (secrets) => {
     if (secrets === undefined || secrets === null) {
@@ -39,22 +69,64 @@ const serializeSecretReferences = (secrets) => {
         if (!(0, exports.isSecretEnvName)(env)) {
             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 };
+        wire[env] = serializeSecretReference(reference, env);
     }
     return wire;
 };
 exports.serializeSecretReferences = serializeSecretReferences;
+/**
+ * Check a vault source and convert it to the API's shape: a name is passed
+ * as is, and a `VaultReference` keeps only its name and unwrapped entries.
+ */
+const serializeVaultSource = (vault) => {
+    if (vault === undefined || typeof vault === "string") {
+        return vault;
+    }
+    if (!vault || typeof vault !== "object" || Array.isArray(vault)) {
+        throw new error_1.HyperbrowserError("vault must be a vault's name or the reference vaults.unwrap() returns");
+    }
+    const { name, unwrapped } = vault;
+    if (typeof name !== "string" || !exports.SECRET_NAME_PATTERN.test(name)) {
+        throw new error_1.HyperbrowserError(`Invalid vault name: ${String(name)}`);
+    }
+    if (!unwrapped || typeof unwrapped !== "object" || Array.isArray(unwrapped)) {
+        throw new error_1.HyperbrowserError(`vault.unwrapped must map vault ${name}'s variables to { version, unwrapped }`);
+    }
+    const entries = Object.entries(unwrapped);
+    if (entries.length > MAX_SECRETS) {
+        throw new error_1.HyperbrowserError(`At most ${MAX_SECRETS} unwrapped vault entries are allowed`);
+    }
+    const wire = {};
+    for (const [env, entry] of entries) {
+        if (!(0, exports.isSecretEnvName)(env)) {
+            throw new error_1.HyperbrowserError(`Invalid environment variable name in vault ${name}: ${env}`);
+        }
+        const { version, unwrapped: envelope } = (entry ?? {});
+        if (!isVersionNumber(version)) {
+            throw new error_1.HyperbrowserError(`The version of vault ${name}'s ${env} must be the integer it was unwrapped from`);
+        }
+        if (!isUnwrappedEnvelope(envelope)) {
+            throw new error_1.HyperbrowserError(`The unwrapped envelope of vault ${name}'s ${env} must be a string of 1 to ${MAX_UNWRAPPED_LENGTH} characters`);
+        }
+        wire[env] = { version, unwrapped: envelope };
+    }
+    return { name, unwrapped: wire };
+};
+exports.serializeVaultSource = serializeVaultSource;
+/**
+ * Check a 1Password source's token, the one member that can be a secret
+ * reference; the API checks the rest.
+ */
+const serializeOnePassword = (onePassword) => {
+    if (!(0, secrets_envelope_1.isPlainObject)(onePassword))
+        return onePassword;
+    const { token } = onePassword;
+    return {
+        ...onePassword,
+        token: typeof token === "string" ? token : serializeSecretReference(token, "the 1Password token"),
+    };
+};
+exports.serializeOnePassword = serializeOnePassword;
 /** 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));

package/dist/secrets-envelope.d.ts

@@ -13,7 +13,8 @@ export declare const secretValueBytes: (value: SecretValue) => Buffer;
 export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
 /** Encrypts values to a verified secrets public key. */
 export declare class SecretsSealer {
-    private readonly kid;
+    /** The platform key's ID, which every envelope it seals names. */
+    readonly kid: string;
     private readonly publicKey;
     private constructor();
     /**

package/dist/secrets-envelope.js

@@ -62,7 +62,9 @@ const rsaThumbprint = (n, e) => base64Url(crypto_1.default
     .digest());
 /** Encrypts values to a verified secrets public key. */
 class SecretsSealer {
-    constructor(kid, publicKey) {
+    constructor(
+    /** The platform key's ID, which every envelope it seals names. */
+    kid, publicKey) {
         this.kid = kid;
         this.publicKey = publicKey;
     }

package/dist/services/base.js

@@ -13,7 +13,14 @@ const getRequestId = (response) => {
 /** The API's machine codes, such as SECRET_NOT_FOUND. */
 const SERVER_ERROR_CODE_PATTERN = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/;
 /** Codes whose retryable status default (such as 503) would be wrong. */
-const NON_RETRYABLE_ERROR_CODES = new Set(["SECRETS_NOT_CONFIGURED"]);
+const NON_RETRYABLE_ERROR_CODES = new Set([
+    "SECRETS_ADMIN_REQUIRED",
+    "SECRETS_NOT_CONFIGURED",
+    "SECRET_KEY_UNAVAILABLE",
+    "SECRET_DECRYPT_FAILED",
+    "SECRET_ENVELOPE_INVALID",
+    "SECRET_VALUE_INVALID",
+]);
 /** The sandbox and secret an error is about, when the API names them. */
 const errorMessageContext = (errorData) => {
     let context = "";

package/dist/services/credentials.d.ts

@@ -13,7 +13,11 @@ export declare class CredentialsService extends BaseService {
      * `op_token` secret must have been attached at session creation as
      * `{ onePassword: name }`, and the request's `allowedOrigins` are the
      * origins the values may be typed on. Each field's result carries the
-     * `reference` read, and there is no top-level `version`.
+     * `reference` read, and there is no top-level `version`. A
+     * customer-protected token is passed as `secrets.unwrap()` returns it.
+     *
+     * A `vault` fill needs the vault attached to the session; it fills the
+     * entries as they are now. Customer-protected secrets can't be filled.
      *
      * API errors are `HyperbrowserError`s whose `details` is the error body; the
      * server's own details are in `details.details`, such as `details.details.pages`

package/dist/services/credentials.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CredentialsService = void 0;
 const error_1 = require("../error");
+const secret_references_1 = require("../sandbox/secret-references");
 const secrets_envelope_1 = require("../secrets-envelope");
 const base_1 = require("./base");
 /** The API gives up on a fill after about 18 seconds. */
@@ -19,7 +20,11 @@ class CredentialsService extends base_1.BaseService {
      * `op_token` secret must have been attached at session creation as
      * `{ onePassword: name }`, and the request's `allowedOrigins` are the
      * origins the values may be typed on. Each field's result carries the
-     * `reference` read, and there is no top-level `version`.
+     * `reference` read, and there is no top-level `version`. A
+     * customer-protected token is passed as `secrets.unwrap()` returns it.
+     *
+     * A `vault` fill needs the vault attached to the session; it fills the
+     * entries as they are now. Customer-protected secrets can't be filled.
      *
      * API errors are `HyperbrowserError`s whose `details` is the error body; the
      * server's own details are in `details.details`, such as `details.details.pages`
@@ -38,9 +43,14 @@ class CredentialsService extends base_1.BaseService {
         }
         // Preserve request members so the API can reject unknown or conflicting options.
         const { frameUrl, ...body } = params;
+        const onePassword = (0, secret_references_1.serializeOnePassword)(body.onePassword);
         return this.request(`/session/${encodeURIComponent(sessionId)}/credentials/fill`, {
             method: "POST",
-            body: JSON.stringify({ ...body, frame: frameUrl == null ? undefined : { url: frameUrl } }),
+            body: JSON.stringify({
+                ...body,
+                onePassword,
+                frame: frameUrl == null ? undefined : { url: frameUrl },
+            }),
             timeout: Math.max(this.timeout, MIN_FILL_TIMEOUT_MS),
         });
     }

package/dist/services/sandboxes.d.ts

@@ -25,6 +25,7 @@ export declare class SandboxHandle {
     get diskMiB(): number | null | undefined;
     get timeoutMinutes(): number | null | undefined;
     get exposedPorts(): SandboxExposeResult[];
+    get startupSecrets(): SandboxDetail["startupSecrets"];
     toJSON(): SandboxDetail;
     info(): Promise<SandboxDetail>;
     refresh(): Promise<SandboxHandle>;
@@ -48,7 +49,6 @@ export declare class SandboxHandle {
         forceRefresh?: boolean;
     }): Promise<SandboxRuntimeSession>;
     private ensureRuntimeSession;
-    private applyRuntimeSession;
     private clearRuntimeSession;
     private assertRuntimeAvailable;
     private static toRuntimeSession;

package/dist/services/sandboxes.js

@@ -71,8 +71,8 @@ const serializeCreateSandboxParams = (params) => {
         throw new error_1.HyperbrowserError("Unsupported sandbox runtimeClass");
     if (typeof params.imageName === "string") {
         const secrets = (0, secret_references_1.serializeSecretReferences)(params.secrets);
-        const vault = params.vault;
-        const onePassword = params.onePassword;
+        const vault = (0, secret_references_1.serializeVaultSource)(params.vault);
+        const onePassword = (0, secret_references_1.serializeOnePassword)(params.onePassword);
         // The startup command with secrets runs only in Firecracker sandboxes.
         if ((secrets !== undefined || vault !== undefined || onePassword !== undefined) &&
             params.runtimeClass === "gvisor-cpu")
@@ -256,6 +256,9 @@ class SandboxHandle {
     get exposedPorts() {
         return (this.detail.exposedPorts ?? []).map((entry) => ({ ...entry }));
     }
+    get startupSecrets() {
+        return this.detail.startupSecrets?.map((entry) => ({ ...entry }));
+    }
     toJSON() {
         return { ...this.detail };
     }
@@ -379,17 +382,6 @@ class SandboxHandle {
         }
         return { ...this.runtimeSession };
     }
-    applyRuntimeSession(session) {
-        this.runtimeSession = { ...session };
-        this.detail = {
-            ...this.detail,
-            status: session.status,
-            region: session.region,
-            runtime: session.runtime,
-            token: session.token,
-            tokenExpiresAt: session.tokenExpiresAt,
-        };
-    }
     clearRuntimeSession(status = this.detail.status) {
         this.runtimeSession = null;
         this.detail = {

package/dist/services/secrets.d.ts

@@ -1,9 +1,15 @@
-import { CreateSecretParams, Secret, SecretDeleteResult, SecretDetail, SecretListParams, SecretListResponse, SecretsPublicKey, SecretValue, SecretVersion, SecretVersionDeleteResult, UpdateSecretParams } from "../types/secret";
+import { CustomerKey } from "../customer-key";
+import { AddSecretVersionOptions, CreateSecretParams, ReplaceSecretVersionWrappingParams, RewrapSecretParams, Secret, SecretDeleteResult, SecretDetail, SecretListParams, SecretListResponse, SecretsPublicKey, SecretValue, SecretVersion, SecretVersionDeleteResult, UnwrappedSecretReference, UnwrapSecretOptions, UpdateSecretParams, WrappedSecretVersion } from "../types/secret";
 import { BaseService } from "./base";
 /**
  * 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.
@@ -31,7 +37,36 @@ export declare class SecretsService extends BaseService {
      * value is checked against the rules of the secret's type, such as a TOTP
      * seed's format, before it is sealed.
      */
-    addVersion(secret: string, value: SecretValue): Promise<SecretVersion>;
+    addVersion(secret: string, value: SecretValue, options?: AddSecretVersionOptions): Promise<SecretVersion>;
+    /**
+     * A customer-protected version's wrapped envelope, for unwrapping with
+     * your own key. Most callers want `unwrap()`, which also unwraps it.
+     */
+    getWrappedVersion(secret: string, version?: number | "latest"): Promise<WrappedSecretVersion>;
+    /**
+     * 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.
+     */
+    unwrap(secret: string, customerKey: CustomerKey | readonly CustomerKey[], options?: UnwrapSecretOptions): Promise<UnwrappedSecretReference>;
+    /**
+     * 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.
+     */
+    rewrap(secret: string, params: RewrapSecretParams): Promise<WrappedSecretVersion[]>;
+    /**
+     * 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.
+     */
+    replaceVersionWrapping(secret: string, version: number, params: ReplaceSecretVersionWrappingParams): Promise<WrappedSecretVersion>;
     /**
      * 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
@@ -45,8 +80,14 @@ export declare class SecretsService extends BaseService {
     delete(secret: string): Promise<SecretDeleteResult>;
     /** Delete one stored version. The latest version cannot be deleted. */
     deleteVersion(secret: string, version: number): Promise<SecretVersionDeleteResult>;
-    /** Sealed to the context the API returned for the secret; never one built here. */
+    /**
+     * 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.
+     */
     private uploadVersion;
+    private fetchWrapped;
+    private putWrapping;
     private resolve;
     private resolveDetail;
     /** Found by ID, the result already includes the versions. */