@hyperbrowser/sdk 1.4.1 → 1.5.0

package/README.md

@@ -154,10 +154,11 @@ try {
 ```
 
 - `credentials` takes up to 20 items: a secret's name (or `{ secret }`),
-  `{ vault }` for the secrets a stored vault names when the session is created,
-  or `{ onePassword }` for an `op_token` secret (see
-  [Fill from 1Password](#fill-from-1password)); the API validates names and limits.
-  `session.credentials` lists the attached secrets as `{ id, name }`. Fill a
+  `{ vault }` for a stored vault, or `{ onePassword }` for an `op_token` secret
+  (see [Fill from 1Password](#fill-from-1password)); the API validates names
+  and limits. A vault is attached by reference, so each fill uses the secrets
+  its entries name at that moment. `session.credentials` lists the attached
+  secrets as `{ id, name }`, and `session.vaults` the vaults. Fill a
   single secret with `{ credential: "github-password", fields: [{ selector }] }`;
   with `vault`, each field names its entry in `field`.
 - Each input reports an `outcome`: `filled`, `not_found` (no input matched),
@@ -339,6 +340,82 @@ console.log(result.fields);
 - `CredentialFillTool` can't fill from 1Password; call
   `sessions.credentials.fill` directly (see [Use with LLM SDKs](#use-with-llm-sdks)).
 
+### Customer-protected secrets
+
+A secret created with `protection: "customer"` is also wrapped with your own
+key, so the platform stores nothing it can open alone. Each version is sealed
+to the platform key as usual, then wrapped locally with your key. To use one,
+unwrap it locally and pass the result. Only the platform can open the
+unwrapped envelope, and it checks that the envelope belongs to the version
+you pinned.
+
+```typescript
+import { createCustomerKey } from "@hyperbrowser/sdk";
+
+// RSA (2048 bits or more), EC P-256/P-384/P-521, X25519 or X448: a KeyObject,
+// PEM/DER or a JWK. A public key can wrap; unwrapping needs the private key.
+const customerKey = createCustomerKey(process.env.HB_CUSTOMER_KEY_PEM!);
+
+await client.secrets.create({ name: "db-pass", value: "hunter2", customerKey });
+await client.secrets.addVersion("db-pass", "hunter3", { customerKey });
+
+// A reference pinned to the version unwrapped: { name, version, unwrapped }.
+const dbPass = await client.secrets.unwrap("db-pass", customerKey);
+const sandbox = await client.sandboxes.create({
+  imageName: "my-image",
+  secrets: { DB_PASS: dbPass },
+});
+await sandbox.exec("node migrate.js", { secrets: { DB_PASS: dbPass } });
+
+// A vault's customer-protected entries, unwrapped together. Its other entries
+// are delivered as usual.
+const appEnv = await client.vaults.unwrap("app-env", customerKey);
+await sandbox.processes.start("node worker.js", { vault: appEnv });
+
+// A customer-protected op_token, for sandboxes and 1Password fills.
+const token = await client.secrets.unwrap("op-token", customerKey);
+await sandbox.exec("node app.js", {
+  onePassword: { token, vault: "Engineering", fields: { DB_PASS: { item: "Postgres", field: "password" } } },
+});
+```
+
+- `protection` is `"platform"` (the default) or `"customer"`, and is fixed when
+  the secret is created. Passing `customerKey` to `create` implies
+  `"customer"`. Creating one without a value gives an empty secret; add its
+  first version with `addVersion(secret, value, { customerKey })`.
+- The key's `kid` is its RFC 7638 thumbprint unless the JWK has a `kid` or you
+  pass `createCustomerKey(key, { kid })`. RSA keys wrap with `RSA-OAEP-256`.
+  EC and OKP keys default to `ECDH-ES+A256KW`; pass `{ algorithm: "ECDH-ES" }`
+  for direct key agreement. To keep the private key in a KMS or HSM, implement
+  `CustomerKey` yourself: `kid`, `wrap(innerEnvelope, encryptionContext)` and
+  `unwrap(wrappedEnvelope)` produce and open a compact JWE with protected
+  header `{ alg, enc: "A256GCM", kid, ctx }`. `ctx` must be the secret's
+  `encryptionContext`. Either method may return a promise.
+- `unwrap(secret, keys, { version })` unwraps the latest version by default.
+  `vaults.unwrap(vault, keys)` unwraps the versions the vault's entries
+  resolve to now. Both take several keys, such as during a rotation, and use
+  the one whose `kid` wrapped each version (`customer_key_mismatch` if none
+  did). The unwrapped envelope is checked against the version's `innerDigest`
+  locally, and again by the API.
+- An unwrapped reference must pin a number, never `"latest"`. A vault reference
+  is refused with `SECRET_VAULT_CHANGED` when an entry was repointed or moved
+  to a newer version since it was unwrapped; unwrap it again.
+- Customer-protected secrets can't be typed into browser pages, including as
+  vault entries in a fill (`SECRET_REQUIRES_CUSTOMER_UNWRAP`). A
+  customer-protected `op_token` can still sign 1Password fills: pass the
+  unwrapped reference as `onePassword.token`.
+- Rotate your key with `rewrap(secret, { from, to })`. It unwraps each version
+  still wrapped with another key and rewraps it with `to`, all locally; the
+  value and the version numbers don't change. It skips versions already
+  wrapped with `to`, so an interrupted rotation resumes where it stopped.
+  `getWrappedVersion` and `replaceVersionWrapping` are the single-version
+  steps, for wrapping done elsewhere.
+- Version details include `outerKid`, the customer key that wrapped them, and
+  `retiresAt`. A version whose platform key is retired is refused with
+  `SECRET_KEY_RETIRED`: add a new version.
+- Fetching wrapped versions needs `secrets.use`, and rewrapping needs
+  `secrets.manage`. Signed-in users must be team owners or admins.
+
 ### Errors
 
 API errors are `HyperbrowserError`s with `statusCode`, `code` and `retryable`
@@ -347,7 +424,7 @@ own `details` holds the specifics (such as `error.details.details.origin`).
 
 | Code | Meaning |
 |---|---|
-| `CREDENTIAL_NOT_ATTACHED` | The secret, vault or 1Password token wasn't attached to the session, or a vault entry was repointed since. |
+| `CREDENTIAL_NOT_ATTACHED` | The secret, vault or 1Password token wasn't attached to the session, directly or as an entry of an attached vault. |
 | `CREDENTIAL_ORIGIN_NOT_ALLOWED` | The page isn't on the secret's allowed origins (for 1Password, the request's); nothing was typed. |
 | `CREDENTIAL_NOT_READY` | The secret has no allowed origins or no value. |
 | `CREDENTIAL_PAGE_NOT_FOUND`, `CREDENTIAL_FRAME_NOT_FOUND` | No tab or iframe matched. |
@@ -367,6 +444,12 @@ own `details` holds the specifics (such as `error.details.details.origin`).
 | `SECRET_ONEPASSWORD_AUTH_FAILED` | 1Password refused the token, or the token is malformed or signs in somewhere other than `1password.com`, `.ca` or `.eu` (or their subdomains). |
 | `SECRET_ONEPASSWORD_RATE_LIMITED`, `SECRET_ONEPASSWORD_FAILED` | Retryable. |
 | `SECRET_SOURCES_INVALID` | Bad `vault`/`onePassword`/`secrets`/`env` combination, such as a `onePassword` variable also set by the vault, more than 32 variables, or a vault with no entries. |
+| `SECRET_REQUIRES_CUSTOMER_UNWRAP` | A customer-protected secret was used without its unwrapped envelope, unwrapped with `"latest"` instead of a pinned version, or used where it can't be (a fill). |
+| `SECRET_PROTECTION_MISMATCH` | An unwrapped envelope for a secret that isn't customer-protected, or a version uploaded in the other protection's form. |
+| `SECRET_DIGEST_MISMATCH` | The unwrapped envelope (or a rewrap's `innerDigest`) doesn't match the version. |
+| `SECRET_VERSION_DUPLICATE` | Another version already holds this inner envelope; rewrap that version instead. |
+| `SECRET_VAULT_CHANGED` | A vault entry resolves to another secret or version than the one unwrapped; unwrap the vault again. |
+| `SECRET_KEY_RETIRED` | The version was sealed to a retired platform key; add a new version. |
 | `VAULT_NOT_FOUND`, `VAULT_ENTRY_NOT_FOUND` | |
 | `VAULT_NAME_TAKEN`, `VAULT_LIMIT_REACHED`, `VAULT_ENTRY_LIMIT_REACHED` | |
 | `SECRETS_FEATURE_DISABLED` | The team doesn't have secrets enabled. |

package/dist/customer-key.d.ts

@@ -0,0 +1,71 @@
+import crypto from "crypto";
+import type { WrappedSecretVersion } from "./types/secret";
+/**
+ * How a customer key wraps an envelope (JWE key management). RSA keys use
+ * `RSA-OAEP-256`; EC and X25519/X448 keys use `ECDH-ES+A256KW` unless
+ * `ECDH-ES` is chosen. Content is always encrypted with A256GCM.
+ */
+export type CustomerKeyAlgorithm = "RSA-OAEP-256" | "ECDH-ES" | "ECDH-ES+A256KW";
+/**
+ * The customer's own key for customer-protected secrets. Each version's
+ * envelope, already encrypted to the platform, is wrapped with this key
+ * before upload, so nothing the platform stores can be decrypted without it.
+ * Each use of the secret passes the envelope unwrapped with this key.
+ *
+ * `createCustomerKey` builds one from a local key. Implement this interface
+ * to keep the private key elsewhere, such as in a KMS or HSM.
+ */
+export interface CustomerKey {
+    /**
+     * The key's ID, written as the `kid` of every envelope it wraps: 1-256
+     * printable ASCII characters.
+     */
+    readonly kid: string;
+    /**
+     * Wrap an inner envelope as a compact JWE (RSA-OAEP-256, ECDH-ES or
+     * ECDH-ES+A256KW with A256GCM) whose protected header holds exactly `alg`,
+     * `enc`, `kid` and `ctx` (plus `epk`, and optionally `apu` and `apv`, with
+     * ECDH-ES), with `ctx` set to `encryptionContext`.
+     */
+    wrap(innerEnvelope: string, encryptionContext: string): string | Promise<string>;
+    /** Decrypt an envelope this key wrapped and return the inner envelope. */
+    unwrap(wrappedEnvelope: string): string | Promise<string>;
+}
+/**
+ * A key as `createCustomerKey` takes it: a `KeyObject`, a PEM (or DER
+ * `Buffer`) private or public key, or a JWK. A public key can only wrap.
+ */
+export type CustomerKeyInput = crypto.KeyObject | string | Buffer | crypto.JsonWebKey;
+export interface CustomerKeyOptions {
+    /** Defaults to the JWK's `kid`, or else the key's RFC 7638 thumbprint. */
+    kid?: string;
+    /** For EC and X25519/X448 keys; defaults to `ECDH-ES+A256KW`. */
+    algorithm?: CustomerKeyAlgorithm;
+}
+/** Throws unless `kid` is a key ID the API stores: 1-256 printable ASCII characters. */
+export declare const assertCustomerKeyId: (kid: unknown) => string;
+/**
+ * A customer key from a local key: RSA (at least 2048 bits), EC (P-256,
+ * P-384 or P-521), X25519 or X448. With only the public key it can wrap
+ * (upload versions) but not unwrap (use them).
+ *
+ * The key ID defaults to the JWK's `kid`, or else the RFC 7638 thumbprint of
+ * the public key, so the same key always gets the same ID.
+ */
+export declare const createCustomerKey: (key: CustomerKeyInput, options?: CustomerKeyOptions) => CustomerKey & {
+    readonly canUnwrap: boolean;
+};
+/**
+ * Identifies an inner envelope as the API does: the unpadded base64url
+ * SHA-256 of its compact form.
+ */
+export declare const secretEnvelopeDigest: (envelope: string) => string;
+/** @internal Checks that `key` looks like a CustomerKey before anything is sent. */
+export declare const assertCustomerKey: (key: unknown, what?: string) => CustomerKey;
+/**
+ * @internal Unwrap a wrapped version with the key among `keys` that wrapped
+ * it, and check the result is the inner envelope the version holds.
+ */
+export declare const unwrapVersion: (wrapped: Pick<WrappedSecretVersion, "outerKid" | "innerDigest" | "envelope">, keys: CustomerKey | readonly CustomerKey[], label: string) => Promise<string>;
+/** @internal The key among `keys` that wrapped an envelope with this `kid`. */
+export declare const customerKeyFor: (keys: CustomerKey | readonly CustomerKey[], kid: string, label: string) => CustomerKey;

package/dist/customer-key.js

@@ -0,0 +1,394 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.customerKeyFor = exports.unwrapVersion = exports.assertCustomerKey = exports.secretEnvelopeDigest = exports.createCustomerKey = exports.assertCustomerKeyId = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const error_1 = require("./error");
+const ENC = "A256GCM";
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const CEK_BYTES = 32;
+/** The server's limits: an inner envelope of 64 KiB, an RSA encrypted key of 256 bytes. */
+const MAX_INNER_ENVELOPE_LENGTH = 64 * 1024;
+const MIN_RSA_BITS = 2048;
+const MAX_KID_LENGTH = 256;
+const KID_PATTERN = /^[\x20-\x7E]+$/;
+const AES_KW_IV = Buffer.from("A6A6A6A6A6A6A6A6", "hex");
+const EC_CURVES = {
+    prime256v1: "P-256",
+    secp384r1: "P-384",
+    secp521r1: "P-521",
+};
+const keyError = (message, code = "invalid_customer_key") => new error_1.HyperbrowserError(message, { code, retryable: false });
+const unwrapFailed = (message) => keyError(message, "customer_key_unwrap_failed");
+const base64Url = (data) => Buffer.from(data).toString("base64url");
+const decodeSegment = (segment, what) => {
+    const decoded = /^[A-Za-z0-9_-]*$/.test(segment) ? Buffer.from(segment, "base64url") : null;
+    if (!decoded || decoded.toString("base64url") !== segment) {
+        throw unwrapFailed(`Wrapped envelope ${what} is not canonical base64url`);
+    }
+    return decoded;
+};
+const uint32 = (value) => {
+    const buffer = Buffer.alloc(4);
+    buffer.writeUInt32BE(value);
+    return buffer;
+};
+const lengthPrefixed = (data) => Buffer.concat([uint32(data.length), data]);
+/** RFC 7518 §4.6.2 Concat KDF with SHA-256, for one 256-bit key. */
+const concatKdf = (sharedSecret, algorithmId, apu, apv) => crypto_1.default
+    .createHash("sha256")
+    .update(Buffer.concat([
+    uint32(1),
+    sharedSecret,
+    lengthPrefixed(Buffer.from(algorithmId, "ascii")),
+    lengthPrefixed(apu),
+    lengthPrefixed(apv),
+    uint32(CEK_BYTES * 8),
+]))
+    .digest();
+/** The members of a public JWK that RFC 7638 thumbprints (and `epk` headers) hold. */
+const publicMembers = (jwk) => {
+    switch (jwk.kty) {
+        case "RSA":
+            return { e: jwk.e, kty: "RSA", n: jwk.n };
+        case "EC":
+            return { crv: jwk.crv, kty: "EC", x: jwk.x, y: jwk.y };
+        default:
+            return { crv: jwk.crv, kty: jwk.kty, x: jwk.x };
+    }
+};
+/** The RFC 7638 SHA-256 thumbprint of a public key. */
+const thumbprint = (publicKey) => base64Url(crypto_1.default
+    .createHash("sha256")
+    .update(JSON.stringify(publicMembers(publicKey.export({ format: "jwk" }))))
+    .digest());
+const isJwk = (input) => !!input &&
+    typeof input === "object" &&
+    !Buffer.isBuffer(input) &&
+    !(input instanceof crypto_1.default.KeyObject) &&
+    typeof input.kty === "string";
+const loadKeys = (input) => {
+    if (input instanceof crypto_1.default.KeyObject) {
+        if (input.type === "private") {
+            return { publicKey: crypto_1.default.createPublicKey(input), privateKey: input };
+        }
+        if (input.type === "public") {
+            return { publicKey: input };
+        }
+        throw keyError("A customer key must be an asymmetric key, not a secret key");
+    }
+    if (isJwk(input)) {
+        const jwkKid = typeof input.kid === "string" ? input.kid : undefined;
+        try {
+            if (typeof input.d === "string") {
+                const privateKey = crypto_1.default.createPrivateKey({ key: input, format: "jwk" });
+                return { publicKey: crypto_1.default.createPublicKey(privateKey), privateKey, jwkKid };
+            }
+            return { publicKey: crypto_1.default.createPublicKey({ key: input, format: "jwk" }), jwkKid };
+        }
+        catch (cause) {
+            throw new error_1.HyperbrowserError("The customer key JWK could not be read", {
+                code: "invalid_customer_key",
+                cause,
+            });
+        }
+    }
+    if (typeof input === "string" || Buffer.isBuffer(input)) {
+        try {
+            const privateKey = crypto_1.default.createPrivateKey(input);
+            return { publicKey: crypto_1.default.createPublicKey(privateKey), privateKey };
+        }
+        catch {
+            try {
+                return { publicKey: crypto_1.default.createPublicKey(input) };
+            }
+            catch (cause) {
+                throw new error_1.HyperbrowserError("The customer key is not a PEM or DER key", {
+                    code: "invalid_customer_key",
+                    cause,
+                });
+            }
+        }
+    }
+    throw keyError("A customer key must be a KeyObject, a PEM or DER key, or a JWK");
+};
+/** Throws unless `kid` is a key ID the API stores: 1-256 printable ASCII characters. */
+const assertCustomerKeyId = (kid) => {
+    if (typeof kid !== "string" || kid.length > MAX_KID_LENGTH || !KID_PATTERN.test(kid)) {
+        throw keyError(`A customer key's kid must be 1-${MAX_KID_LENGTH} printable ASCII characters`);
+    }
+    return kid;
+};
+exports.assertCustomerKeyId = assertCustomerKeyId;
+const keyKind = (publicKey) => {
+    const type = publicKey.asymmetricKeyType;
+    if (type === "rsa") {
+        const bits = publicKey.asymmetricKeyDetails?.modulusLength ?? 0;
+        if (bits < MIN_RSA_BITS) {
+            throw keyError(`RSA customer keys must be at least ${MIN_RSA_BITS} bits`);
+        }
+        return { type };
+    }
+    if (type === "ec") {
+        const curve = publicKey.asymmetricKeyDetails?.namedCurve ?? "";
+        if (!EC_CURVES[curve]) {
+            throw keyError("EC customer keys must be on P-256, P-384 or P-521");
+        }
+        return { type, curve };
+    }
+    if (type === "x25519" || type === "x448") {
+        return { type };
+    }
+    throw keyError("A customer key must be RSA, EC (P-256, P-384, P-521), X25519 or X448");
+};
+/** A customer key held in this process. */
+class LocalCustomerKey {
+    constructor(publicKey, privateKey, options) {
+        this.publicKey = publicKey;
+        this.privateKey = privateKey;
+        this.kind = keyKind(publicKey);
+        const algorithm = options.algorithm ?? (this.kind.type === "rsa" ? "RSA-OAEP-256" : "ECDH-ES+A256KW");
+        if ((algorithm === "RSA-OAEP-256") !== (this.kind.type === "rsa")) {
+            throw keyError(this.kind.type === "rsa"
+                ? "RSA customer keys wrap with RSA-OAEP-256"
+                : "EC and X25519/X448 customer keys wrap with ECDH-ES or ECDH-ES+A256KW");
+        }
+        if (!["RSA-OAEP-256", "ECDH-ES", "ECDH-ES+A256KW"].includes(algorithm)) {
+            throw keyError(`Unsupported customer key algorithm ${String(algorithm)}`);
+        }
+        this.algorithm = algorithm;
+        this.kid = (0, exports.assertCustomerKeyId)(options.kid ?? options.jwkKid ?? thumbprint(publicKey));
+    }
+    /** Whether this key can unwrap, that is, holds its private key. */
+    get canUnwrap() {
+        return this.privateKey !== undefined;
+    }
+    wrap(innerEnvelope, encryptionContext) {
+        if (typeof innerEnvelope !== "string" || innerEnvelope.length === 0) {
+            throw keyError("The envelope to wrap must be a non-empty string", "invalid_request");
+        }
+        if (innerEnvelope.length > MAX_INNER_ENVELOPE_LENGTH) {
+            throw keyError("The envelope to wrap is larger than 64 KiB", "invalid_request");
+        }
+        if (typeof encryptionContext !== "string" || encryptionContext.length === 0) {
+            throw keyError("An encryption context is required to wrap an envelope", "invalid_request");
+        }
+        const header = {
+            alg: this.algorithm,
+            enc: ENC,
+            kid: this.kid,
+            ctx: encryptionContext,
+        };
+        let cek;
+        let encryptedKey = Buffer.alloc(0);
+        if (this.kind.type === "rsa") {
+            cek = crypto_1.default.randomBytes(CEK_BYTES);
+            encryptedKey = crypto_1.default.publicEncrypt({
+                key: this.publicKey,
+                padding: crypto_1.default.constants.RSA_PKCS1_OAEP_PADDING,
+                oaepHash: "sha256",
+            }, cek);
+        }
+        else {
+            const ephemeral = this.kind.type === "ec"
+                ? crypto_1.default.generateKeyPairSync("ec", { namedCurve: this.kind.curve })
+                : crypto_1.default.generateKeyPairSync(this.kind.type);
+            header.epk = publicMembers(ephemeral.publicKey.export({ format: "jwk" }));
+            const shared = crypto_1.default.diffieHellman({
+                privateKey: ephemeral.privateKey,
+                publicKey: this.publicKey,
+            });
+            const derived = concatKdf(shared, this.algorithm === "ECDH-ES" ? ENC : this.algorithm, Buffer.alloc(0), Buffer.alloc(0));
+            shared.fill(0);
+            if (this.algorithm === "ECDH-ES") {
+                cek = derived;
+            }
+            else {
+                cek = crypto_1.default.randomBytes(CEK_BYTES);
+                const wrapper = crypto_1.default.createCipheriv("id-aes256-wrap", derived, AES_KW_IV);
+                encryptedKey = Buffer.concat([wrapper.update(cek), wrapper.final()]);
+                derived.fill(0);
+            }
+        }
+        try {
+            const protectedHeader = base64Url(Buffer.from(JSON.stringify(header), "utf8"));
+            const iv = crypto_1.default.randomBytes(IV_BYTES);
+            const cipher = crypto_1.default.createCipheriv("aes-256-gcm", cek, iv);
+            cipher.setAAD(Buffer.from(protectedHeader, "ascii"));
+            const ciphertext = Buffer.concat([cipher.update(innerEnvelope, "utf8"), cipher.final()]);
+            return [
+                protectedHeader,
+                base64Url(encryptedKey),
+                base64Url(iv),
+                base64Url(ciphertext),
+                base64Url(cipher.getAuthTag()),
+            ].join(".");
+        }
+        finally {
+            cek.fill(0);
+        }
+    }
+    unwrap(wrappedEnvelope) {
+        if (!this.privateKey) {
+            throw keyError(`Customer key ${this.kid} has no private key, so it can wrap but not unwrap`, "customer_key_private_key_required");
+        }
+        if (typeof wrappedEnvelope !== "string") {
+            throw unwrapFailed("The wrapped envelope must be a string");
+        }
+        const segments = wrappedEnvelope.split(".");
+        if (segments.length !== 5) {
+            throw unwrapFailed("The wrapped envelope must have five segments");
+        }
+        const [headerSegment, keySegment, ivSegment, ciphertextSegment, tagSegment] = segments;
+        let header;
+        try {
+            header = JSON.parse(decodeSegment(headerSegment, "header").toString("utf8"));
+        }
+        catch (error) {
+            if (error instanceof error_1.HyperbrowserError)
+                throw error;
+            throw unwrapFailed("The wrapped envelope header is not JSON");
+        }
+        if (!header || typeof header !== "object" || Array.isArray(header)) {
+            throw unwrapFailed("The wrapped envelope header is not a JSON object");
+        }
+        if (header.kid !== this.kid) {
+            throw keyError(`The envelope was wrapped with key ${JSON.stringify(header.kid)}, not ${JSON.stringify(this.kid)}`, "customer_key_mismatch");
+        }
+        if (header.enc !== ENC) {
+            throw unwrapFailed(`Unsupported wrapped envelope encryption ${String(header.enc)}`);
+        }
+        const alg = header.alg;
+        const encryptedKey = decodeSegment(keySegment, "encrypted key");
+        const iv = decodeSegment(ivSegment, "IV");
+        const ciphertext = decodeSegment(ciphertextSegment, "ciphertext");
+        const tag = decodeSegment(tagSegment, "tag");
+        if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) {
+            throw unwrapFailed("The wrapped envelope IV or tag has the wrong length");
+        }
+        let cek;
+        try {
+            if (alg === "RSA-OAEP-256" && this.kind.type === "rsa") {
+                cek = crypto_1.default.privateDecrypt({
+                    key: this.privateKey,
+                    padding: crypto_1.default.constants.RSA_PKCS1_OAEP_PADDING,
+                    oaepHash: "sha256",
+                }, encryptedKey);
+            }
+            else if ((alg === "ECDH-ES" || alg === "ECDH-ES+A256KW") && this.kind.type !== "rsa") {
+                const optional = (name) => header[name] === undefined ? Buffer.alloc(0) : decodeSegment(String(header[name]), name);
+                const epk = crypto_1.default.createPublicKey({
+                    key: header.epk,
+                    format: "jwk",
+                });
+                const shared = crypto_1.default.diffieHellman({ privateKey: this.privateKey, publicKey: epk });
+                const derived = concatKdf(shared, alg === "ECDH-ES" ? ENC : alg, optional("apu"), optional("apv"));
+                shared.fill(0);
+                if (alg === "ECDH-ES") {
+                    cek = derived;
+                }
+                else {
+                    const unwrapper = crypto_1.default.createDecipheriv("id-aes256-wrap", derived, AES_KW_IV);
+                    cek = Buffer.concat([unwrapper.update(encryptedKey), unwrapper.final()]);
+                    derived.fill(0);
+                }
+            }
+            else {
+                throw unwrapFailed(`Customer key ${this.kid} can't unwrap an envelope wrapped with ${String(alg)}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof error_1.HyperbrowserError)
+                throw error;
+            throw new error_1.HyperbrowserError("The wrapped envelope's key could not be decrypted", {
+                code: "customer_key_unwrap_failed",
+                cause: error,
+            });
+        }
+        try {
+            if (cek.length !== CEK_BYTES) {
+                throw unwrapFailed("The wrapped envelope's content key has the wrong length");
+            }
+            const decipher = crypto_1.default.createDecipheriv("aes-256-gcm", cek, iv);
+            decipher.setAAD(Buffer.from(headerSegment, "ascii"));
+            decipher.setAuthTag(tag);
+            return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+        }
+        catch (error) {
+            if (error instanceof error_1.HyperbrowserError)
+                throw error;
+            throw new error_1.HyperbrowserError("The wrapped envelope could not be decrypted", {
+                code: "customer_key_unwrap_failed",
+                cause: error,
+            });
+        }
+        finally {
+            cek.fill(0);
+        }
+    }
+}
+/**
+ * A customer key from a local key: RSA (at least 2048 bits), EC (P-256,
+ * P-384 or P-521), X25519 or X448. With only the public key it can wrap
+ * (upload versions) but not unwrap (use them).
+ *
+ * The key ID defaults to the JWK's `kid`, or else the RFC 7638 thumbprint of
+ * the public key, so the same key always gets the same ID.
+ */
+const createCustomerKey = (key, options = {}) => {
+    const { publicKey, privateKey, jwkKid } = loadKeys(key);
+    return new LocalCustomerKey(publicKey, privateKey, { ...options, jwkKid });
+};
+exports.createCustomerKey = createCustomerKey;
+/**
+ * Identifies an inner envelope as the API does: the unpadded base64url
+ * SHA-256 of its compact form.
+ */
+const secretEnvelopeDigest = (envelope) => crypto_1.default.createHash("sha256").update(envelope, "utf8").digest("base64url");
+exports.secretEnvelopeDigest = secretEnvelopeDigest;
+/** @internal Checks that `key` looks like a CustomerKey before anything is sent. */
+const assertCustomerKey = (key, what = "customerKey") => {
+    const candidate = key;
+    if (!candidate ||
+        typeof candidate !== "object" ||
+        typeof candidate.wrap !== "function" ||
+        typeof candidate.unwrap !== "function") {
+        throw new error_1.HyperbrowserError(`${what} must be a customer key, such as one from createCustomerKey()`, { code: "invalid_request", retryable: false });
+    }
+    (0, exports.assertCustomerKeyId)(candidate.kid);
+    return candidate;
+};
+exports.assertCustomerKey = assertCustomerKey;
+/**
+ * @internal Unwrap a wrapped version with the key among `keys` that wrapped
+ * it, and check the result is the inner envelope the version holds.
+ */
+const unwrapVersion = async (wrapped, keys, label) => {
+    const key = (0, exports.customerKeyFor)(keys, wrapped.outerKid, label);
+    const inner = await key.unwrap(wrapped.envelope);
+    if (typeof inner !== "string" || (0, exports.secretEnvelopeDigest)(inner) !== wrapped.innerDigest) {
+        throw new error_1.HyperbrowserError(`${label} unwrapped to an envelope that doesn't match its innerDigest; it may have been uploaded with the wrong digest`, { code: "customer_key_unwrap_failed", retryable: false });
+    }
+    return inner;
+};
+exports.unwrapVersion = unwrapVersion;
+/** @internal The key among `keys` that wrapped an envelope with this `kid`. */
+const customerKeyFor = (keys, kid, label) => {
+    const list = (Array.isArray(keys) ? keys : [keys]);
+    if (list.length === 0) {
+        throw new error_1.HyperbrowserError("Pass at least one customer key", {
+            code: "invalid_request",
+            retryable: false,
+        });
+    }
+    list.forEach((key, index) => (0, exports.assertCustomerKey)(key, `customerKey[${index}]`));
+    const key = list.find((candidate) => candidate.kid === kid);
+    if (!key) {
+        throw new error_1.HyperbrowserError(`${label} was wrapped with customer key ${JSON.stringify(kid)}, which none of the keys given has`, { code: "customer_key_mismatch", retryable: false });
+    }
+    return key;
+};
+exports.customerKeyFor = customerKeyFor;

package/dist/index.d.ts

@@ -2,6 +2,9 @@ import { dockerBuildContextFingerprint, DockerBuildContextChangedError, imageBui
 export { dockerBuildContextFingerprint, DockerBuildContextChangedError, imageBuildName, dockerImageDigest, DockerCommandError, };
 export type { DockerBuildContextOptions, ImageBuildNameOptions, ImageBuildSource, } from "./image-builds";
 import { HyperbrowserClient, HyperbrowserError } from "./client";
+import { createCustomerKey, secretEnvelopeDigest } from "./customer-key";
+export { createCustomerKey, secretEnvelopeDigest };
+export type { CustomerKey, CustomerKeyAlgorithm, CustomerKeyInput, CustomerKeyOptions, } from "./customer-key";
 export declare const Hyperbrowser: typeof HyperbrowserClient;
 export type Hyperbrowser = HyperbrowserClient;
 export { HyperbrowserClient, HyperbrowserError };

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HyperbrowserError = exports.HyperbrowserClient = exports.Hyperbrowser = exports.DockerCommandError = exports.dockerImageDigest = exports.imageBuildName = exports.DockerBuildContextChangedError = exports.dockerBuildContextFingerprint = void 0;
+exports.HyperbrowserError = exports.HyperbrowserClient = exports.Hyperbrowser = exports.secretEnvelopeDigest = exports.createCustomerKey = exports.DockerCommandError = exports.dockerImageDigest = exports.imageBuildName = exports.DockerBuildContextChangedError = exports.dockerBuildContextFingerprint = void 0;
 const image_builds_1 = require("./image-builds");
 Object.defineProperty(exports, "dockerBuildContextFingerprint", { enumerable: true, get: function () { return image_builds_1.dockerBuildContextFingerprint; } });
 Object.defineProperty(exports, "DockerBuildContextChangedError", { enumerable: true, get: function () { return image_builds_1.DockerBuildContextChangedError; } });
@@ -10,6 +10,9 @@ Object.defineProperty(exports, "DockerCommandError", { enumerable: true, get: fu
 const client_1 = require("./client");
 Object.defineProperty(exports, "HyperbrowserClient", { enumerable: true, get: function () { return client_1.HyperbrowserClient; } });
 Object.defineProperty(exports, "HyperbrowserError", { enumerable: true, get: function () { return client_1.HyperbrowserError; } });
+const customer_key_1 = require("./customer-key");
+Object.defineProperty(exports, "createCustomerKey", { enumerable: true, get: function () { return customer_key_1.createCustomerKey; } });
+Object.defineProperty(exports, "secretEnvelopeDigest", { enumerable: true, get: function () { return customer_key_1.secretEnvelopeDigest; } });
 // Export HyperbrowserClient as Hyperbrowser for named imports
 exports.Hyperbrowser = client_1.HyperbrowserClient;
 exports.default = client_1.HyperbrowserClient;
@@ -24,5 +27,7 @@ if (typeof module !== "undefined" && module.exports) {
     module.exports.imageBuildName = image_builds_1.imageBuildName;
     module.exports.dockerImageDigest = image_builds_1.dockerImageDigest;
     module.exports.DockerCommandError = image_builds_1.DockerCommandError;
+    module.exports.createCustomerKey = customer_key_1.createCustomerKey;
+    module.exports.secretEnvelopeDigest = customer_key_1.secretEnvelopeDigest;
     module.exports.default = client_1.HyperbrowserClient;
 }

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);