@hyperbrowser/sdk 1.4.0 → 1.5.0

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/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.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")

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. */

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,122 @@ 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);
+        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.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 to.wrap(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 +314,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 +325,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 customerKey.wrap(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/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;
 }