@hyperbrowser/sdk 1.1.0 → 1.2.1

package/dist/secrets-envelope.d.ts

@@ -0,0 +1,25 @@
+import { SecretsPublicKey, SecretValue } from "./types/secret";
+/** The largest secret value the platform accepts. */
+export declare const MAX_SECRET_VALUE_BYTES: number;
+/**
+ * Apply the platform's value rules locally, so a bad value is reported before
+ * anything is created rather than when a sandbox starts.
+ */
+export declare const secretValueBytes: (value: SecretValue) => Buffer;
+/** Encrypts values to a verified secrets public key. */
+export declare class SecretsSealer {
+    private readonly kid;
+    private readonly publicKey;
+    private constructor();
+    /**
+     * Check that `key` is a supported RSA key whose ID matches the key itself. A
+     * mismatch means a corrupted response or a misconfigured server; where the
+     * key comes from rests on TLS to the API.
+     */
+    static fromPublicKey(key: SecretsPublicKey): SecretsSealer;
+    /**
+     * Encrypt `value` as a compact JWE (RSA-OAEP-256 + A256GCM) bound to a
+     * secret's encryption context.
+     */
+    seal(encryptionContext: string, value: SecretValue): string;
+}

package/dist/secrets-envelope.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretsSealer = exports.secretValueBytes = exports.MAX_SECRET_VALUE_BYTES = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const error_1 = require("./error");
+/** The largest secret value the platform accepts. */
+exports.MAX_SECRET_VALUE_BYTES = 32 * 1024;
+const MIN_SECRETS_KEY_BITS = 3072;
+const SECRETS_KEY_EXPONENT = 65537;
+const invalid = (message) => new error_1.HyperbrowserError(message, { code: "invalid_secret_value", retryable: false });
+const base64Url = (data) => Buffer.from(data).toString("base64url");
+/**
+ * Apply the platform's value rules locally, so a bad value is reported before
+ * anything is created rather than when a sandbox starts.
+ */
+const secretValueBytes = (value) => {
+    if (typeof value !== "string" && !(value instanceof Uint8Array)) {
+        throw invalid("Secret value must be a string or bytes");
+    }
+    const bytes = Buffer.from(value);
+    if (bytes.length === 0) {
+        throw invalid("Secret value is empty");
+    }
+    if (bytes.length > exports.MAX_SECRET_VALUE_BYTES) {
+        throw invalid(`Secret value is more than ${exports.MAX_SECRET_VALUE_BYTES} bytes`);
+    }
+    if (bytes.includes(0)) {
+        throw invalid("Secret value must not contain NUL bytes");
+    }
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw invalid("Secret value must be valid UTF-8");
+    }
+    return bytes;
+};
+exports.secretValueBytes = secretValueBytes;
+const minimalBytes = (value) => {
+    let start = 0;
+    while (start < value.length - 1 && value[start] === 0)
+        start += 1;
+    return value.subarray(start);
+};
+/** RFC 7638 JWK SHA-256 thumbprint of an RSA key. */
+const rsaThumbprint = (n, e) => base64Url(crypto_1.default
+    .createHash("sha256")
+    .update(`{"e":"${base64Url(e)}","kty":"RSA","n":"${base64Url(n)}"}`)
+    .digest());
+/** Encrypts values to a verified secrets public key. */
+class SecretsSealer {
+    constructor(kid, publicKey) {
+        this.kid = kid;
+        this.publicKey = publicKey;
+    }
+    /**
+     * Check that `key` is a supported RSA key whose ID matches the key itself. A
+     * mismatch means a corrupted response or a misconfigured server; where the
+     * key comes from rests on TLS to the API.
+     */
+    static fromPublicKey(key) {
+        const unsupported = (message) => new error_1.HyperbrowserError(message, { code: "invalid_secrets_public_key", retryable: false });
+        if (key?.alg !== "RSA-OAEP-256" || key.enc !== "A256GCM" || key.jwk?.kty !== "RSA") {
+            throw unsupported(`Unsupported secrets public key (${key?.alg}/${key?.enc})`);
+        }
+        const n = minimalBytes(Buffer.from(key.jwk.n ?? "", "base64url"));
+        const e = minimalBytes(Buffer.from(key.jwk.e ?? "", "base64url"));
+        if (n.length === 0 || n[0] === 0 || e.length === 0 || e.length > 4) {
+            throw unsupported("Secrets public key is malformed");
+        }
+        // The same policy the server and vm-service enforce for their keys.
+        const bits = n.length * 8 - Math.clz32(n[0]) + 24;
+        if (bits < MIN_SECRETS_KEY_BITS || e.readUIntBE(0, e.length) !== SECRETS_KEY_EXPONENT) {
+            throw unsupported(`Secrets public key must be at least ${MIN_SECRETS_KEY_BITS}-bit RSA with exponent ${SECRETS_KEY_EXPONENT}`);
+        }
+        if (rsaThumbprint(n, e) !== key.kid) {
+            throw unsupported("Secrets public key does not match its key ID");
+        }
+        const publicKey = crypto_1.default.createPublicKey({
+            key: { kty: "RSA", n: base64Url(n), e: base64Url(e) },
+            format: "jwk",
+        });
+        return new SecretsSealer(key.kid, publicKey);
+    }
+    /**
+     * Encrypt `value` as a compact JWE (RSA-OAEP-256 + A256GCM) bound to a
+     * secret's encryption context.
+     */
+    seal(encryptionContext, value) {
+        const plaintext = (0, exports.secretValueBytes)(value);
+        const protectedHeader = base64Url(Buffer.from(JSON.stringify({
+            alg: "RSA-OAEP-256",
+            enc: "A256GCM",
+            kid: this.kid,
+            ctx: encryptionContext,
+        })));
+        const cek = crypto_1.default.randomBytes(32);
+        const iv = crypto_1.default.randomBytes(12);
+        try {
+            const encryptedKey = crypto_1.default.publicEncrypt({
+                key: this.publicKey,
+                padding: crypto_1.default.constants.RSA_PKCS1_OAEP_PADDING,
+                oaepHash: "sha256",
+            }, cek);
+            const cipher = crypto_1.default.createCipheriv("aes-256-gcm", cek, iv);
+            cipher.setAAD(Buffer.from(protectedHeader, "ascii"));
+            const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+            return [
+                protectedHeader,
+                base64Url(encryptedKey),
+                base64Url(iv),
+                base64Url(ciphertext),
+                base64Url(cipher.getAuthTag()),
+            ].join(".");
+        }
+        finally {
+            cek.fill(0);
+        }
+    }
+}
+exports.SecretsSealer = SecretsSealer;

package/dist/services/base.js

@@ -10,6 +10,28 @@ const retry_1 = require("../retry");
 const getRequestId = (response) => {
     return response.headers.get("x-request-id") || response.headers.get("request-id") || undefined;
 };
+/** 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"]);
+/** The sandbox and secret an error is about, when the API names them. */
+const errorMessageContext = (errorData) => {
+    let context = "";
+    // A failed create may leave a sandbox the caller has to stop.
+    if (typeof errorData.sandboxId === "string" && errorData.sandboxId.trim()) {
+        context += ` (sandbox ${errorData.sandboxId.trim()})`;
+    }
+    // Which of several secrets could not be used.
+    const secret = errorData.details;
+    if (secret && typeof secret.env === "string" && secret.env.trim()) {
+        const parts = [
+            typeof secret.secretId === "string" ? `secret ${secret.secretId}` : undefined,
+            typeof secret.version === "number" ? `version ${secret.version}` : undefined,
+        ].filter(Boolean);
+        context += ` (${secret.env.trim()}${parts.length > 0 ? `: ${parts.join(", ")}` : ""})`;
+    }
+    return context;
+};
 class BaseService {
     constructor(apiKey, baseUrl, timeout = 30000) {
         this.apiKey = apiKey;
@@ -71,25 +93,51 @@ class BaseService {
                 let errorMessage;
                 let errorDetails;
                 let errorCode;
+                let decodingFailed = false;
+                let decodingCause;
+                let retryable = retry_1.RETRYABLE_STATUS_CODES.has(response.status);
                 try {
                     const errorData = await response.json();
                     errorDetails = errorData;
                     errorCode = typeof errorData?.code === "string" ? errorData.code : undefined;
+                    // Some routes send the code as "error" next to a message, for
+                    // example API_KEY_SCOPE_DENIED.
+                    if (errorCode === undefined &&
+                        errorData?.message &&
+                        typeof errorData.error === "string" &&
+                        SERVER_ERROR_CODE_PATTERN.test(errorData.error)) {
+                        errorCode = errorData.error;
+                    }
+                    // The server knows better when it says so: an ambiguous process
+                    // start with secrets is a 502 that must not be retried blindly.
+                    if (typeof errorData?.retryable === "boolean") {
+                        retryable = errorData.retryable;
+                    }
+                    else if (errorCode !== undefined && NON_RETRYABLE_ERROR_CODES.has(errorCode)) {
+                        retryable = false;
+                    }
+                    const message = errorData.message || errorData.error;
                     errorMessage =
-                        errorData.message || errorData.error || `HTTP error! status: ${response.status}`;
+                        typeof message === "string" && message
+                            ? `${message}${errorMessageContext(errorData)}`
+                            : message || `HTTP error! status: ${response.status}`;
                 }
                 catch (error) {
                     if (init?.signal?.aborted)
                         throw error;
+                    decodingFailed = true;
+                    decodingCause = error;
                     errorMessage = `HTTP error! status: ${response.status}`;
                 }
-                throw new error_1.HyperbrowserError(errorMessage, {
+                const ErrorType = decodingFailed ? error_1.ResponseDecodingError : error_1.HyperbrowserError;
+                throw new ErrorType(errorMessage, {
                     statusCode: response.status,
                     code: errorCode,
                     requestId: getRequestId(response),
-                    retryable: retry_1.RETRYABLE_STATUS_CODES.has(response.status),
+                    retryable,
                     service: "control",
                     details: errorDetails,
+                    cause: decodingCause,
                     method: init?.method ?? "GET",
                     path: (0, error_1.errorRequestPath)(path),
                 });

package/dist/services/sandboxes.d.ts

@@ -1,5 +1,5 @@
 import { SandboxFilesApi } from "../sandbox/files";
-import { SandboxProcessHandle, SandboxProcessesApi } from "../sandbox/process";
+import { SandboxProcessHandle, SandboxProcessesApi, SecretProcessStartPayload, SecretProcessStartResponse } from "../sandbox/process";
 import { SandboxTerminalApi } from "../sandbox/terminal";
 import { BasicResponse } from "../types/session";
 import { BuildSandboxImageFromDockerImageOptions, BuildSandboxImageFromDockerfileOptions, CompleteSandboxImageBuildParams, CreateSandboxImageBuildParams, CreateSandboxParams, StartSandboxFromSnapshotParams, SandboxRuntimeSession, SandboxRuntimeTarget, GetOrBuildSandboxImageOptions, ReuseSandboxDockerImageParams, SandboxDockerImageReuseResult, SandboxImageBuildResolution, SandboxImageBuildWaitOptions, SandboxImageSummary, SandboxDetail, SandboxExposeParams, SandboxExposeResult, SandboxExecParams, SandboxExecOptions, SandboxImageBuild, SandboxImageBuildCreateResult, SandboxImageBuildListParams, SandboxImageBuildListResponse, SandboxImageListParams, SandboxImageListResponse, SandboxListParams, SandboxListResponse, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxNetworkPolicyPatch, SandboxNetworkUpdateResult, SandboxProcessResult, SandboxImageDeleteResult, SandboxSnapshotDeleteResult, SandboxSnapshotListParams, SandboxSnapshotListResponse, SandboxSnapshotSummary, SandboxUnexposeResult } from "../types/sandbox";
@@ -110,7 +110,16 @@ export declare class SandboxesService extends BaseService {
     /** Create a build, upload requested artifacts, complete it, and optionally wait. */
     private submitImageBuild;
     private completeImageBuildResilient;
+    /**
+     * Start a process with secrets through the control API. Never retried: a
+     * failed start may still have run the command.
+     */
+    startSecretProcess(id: string, payload: SecretProcessStartPayload, signal?: AbortSignal): Promise<SecretProcessStartResponse>;
     updateNetwork(id: string, policy: SandboxNetworkPolicyPatch): Promise<SandboxNetworkUpdateResult>;
     unexpose(id: string, port: number): Promise<SandboxUnexposeResult>;
+    /**
+     * With secrets, a create whose result is unknown is never retried: the
+     * sandbox may exist and be running its startup command with the secrets.
+     */
     private createDetail;
 }

package/dist/services/sandboxes.js

@@ -6,12 +6,15 @@ const files_1 = require("../sandbox/files");
 const base_1 = require("../sandbox/base");
 const runtime_path_1 = require("../sandbox/runtime-path");
 const process_1 = require("../sandbox/process");
+const secret_references_1 = require("../sandbox/secret-references");
 const terminal_1 = require("../sandbox/terminal");
 const image_build_1 = require("../sandbox/image-build");
 const retry_1 = require("../retry");
 const normalize_1 = require("./normalize");
 const base_2 = require("./base");
 const RUNTIME_SESSION_REFRESH_BUFFER_MS = 60000;
+/** Runtime waits for secret processes stay well under the request timeout. */
+const SECRET_PROCESS_WAIT_CHUNK_MS = 20000;
 const normalizeSandbox = (sandbox) => {
     const { vcpus, memMiB, diskSizeMiB, ...rest } = sandbox;
     return {
@@ -27,6 +30,7 @@ const normalizeSandbox = (sandbox) => {
         timeoutMinutes: (0, normalize_1.optionalInteger)(rest.timeoutMinutes),
         creditsUsed: (0, normalize_1.optionalNumber)(rest.creditsUsed) ?? null,
         exposedPorts: rest.exposedPorts ?? [],
+        containsSecrets: rest.containsSecrets ?? false,
         network: rest.network ? { ...rest.network, allowOut: rest.network.allowOut ?? [], denyOut: rest.network.denyOut ?? [] } : rest.network,
     };
 };
@@ -66,6 +70,10 @@ const serializeCreateSandboxParams = (params) => {
         params.runtimeClass !== "gvisor-cpu")
         throw new error_1.HyperbrowserError("Unsupported sandbox runtimeClass");
     if (typeof params.imageName === "string") {
+        const secrets = (0, secret_references_1.serializeSecretReferences)(params.secrets);
+        // The startup command with secrets runs only in Firecracker sandboxes.
+        if (secrets !== undefined && params.runtimeClass === "gvisor-cpu")
+            throw new error_1.HyperbrowserError("secrets are not supported with runtimeClass gvisor-cpu");
         return {
             runtimeClass: params.runtimeClass,
             imageName: params.imageName,
@@ -81,9 +89,14 @@ const serializeCreateSandboxParams = (params) => {
             allowInternetAccess: params.allowInternetAccess,
             allowOut: params.allowOut,
             denyOut: params.denyOut,
+            secrets,
         };
     }
     const snapshotParams = params;
+    if (snapshotParams.secrets !== undefined) {
+        // Snapshot launches do not run a startup command.
+        throw new error_1.HyperbrowserError("secrets are only supported for image launches");
+    }
     if (snapshotParams.cpu !== undefined ||
         snapshotParams.memoryMiB !== undefined ||
         snapshotParams.diskMiB !== undefined) {
@@ -194,7 +207,11 @@ class SandboxHandle {
         this.detail = detail;
         this.runtimeSession = SandboxHandle.toRuntimeSession(detail);
         this.transport = new base_1.RuntimeTransport((forceRefresh) => this.resolveRuntimeConnection(forceRefresh), service.runtimeTimeout, service.runtimeProxyOverride);
-        this.processes = new process_1.SandboxProcessesApi(this.transport);
+        this.processes = new process_1.SandboxProcessesApi(this.transport, {
+            sandboxId: detail.id,
+            waitChunkMs: Math.max(1, Math.floor(Math.min(SECRET_PROCESS_WAIT_CHUNK_MS, service.runtimeTimeout / 2))),
+            start: (payload, signal) => service.startSecretProcess(this.id, payload, signal),
+        });
         this.files = new files_1.SandboxFilesApi(this.transport, () => this.resolveRuntimeSocketConnectionInfo(), service.runtimeProxyOverride);
         this.terminal = new terminal_1.SandboxTerminalApi(this.transport, () => this.resolveRuntimeSocketConnectionInfo(), service.runtimeProxyOverride);
         this.pty = this.terminal;
@@ -1053,6 +1070,27 @@ class SandboxesService extends base_2.BaseService {
             return this.completeImageBuild(buildId, params);
         }
     }
+    /**
+     * Start a process with secrets through the control API. Never retried: a
+     * failed start may still have run the command.
+     */
+    async startSecretProcess(id, payload, signal) {
+        try {
+            return await this.request(`/sandbox/${encodeURIComponent(id)}/processes`, {
+                method: "POST",
+                body: JSON.stringify(payload),
+                signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof error_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new error_1.HyperbrowserError(`Failed to start a process with secrets in sandbox ${id}`, {
+                cause: error,
+            });
+        }
+    }
     async updateNetwork(id, policy) {
         try {
             return await this.request(`/sandbox/${id}/network`, {
@@ -1081,15 +1119,36 @@ class SandboxesService extends base_2.BaseService {
             throw new error_1.HyperbrowserError(`Failed to unexpose port ${port} for sandbox ${id}`);
         }
     }
+    /**
+     * With secrets, a create whose result is unknown is never retried: the
+     * sandbox may exist and be running its startup command with the secrets.
+     */
     async createDetail(params) {
+        const body = serializeCreateSandboxParams(params);
         try {
             const detail = await this.request("/sandbox", {
                 method: "POST",
-                body: JSON.stringify(serializeCreateSandboxParams(params)),
+                body: JSON.stringify(body),
             });
+            if (body.secrets !== undefined &&
+                (typeof detail?.id !== "string" || !detail.id.trim())) {
+                throw new Error("The API accepted the create but returned no sandbox ID");
+            }
             return normalizeSandboxDetail(detail);
         }
         catch (error) {
+            if (body.secrets !== undefined && (0, process_1.requestMayHaveArrived)(error)) {
+                throw new error_1.HyperbrowserError(`could not confirm the create result: ${error instanceof Error
+                    ? error.message.replace(/^\[Hyperbrowser\]: /, "")
+                    : String(error)}; a sandbox may have been created with the secrets, so list sandboxes before retrying`, {
+                    code: "secret_process_outcome_unknown",
+                    retryable: false,
+                    service: "control",
+                    cause: error,
+                    method: "POST",
+                    path: "/sandbox",
+                });
+            }
             if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }

package/dist/services/secrets.d.ts

@@ -0,0 +1,39 @@
+import { CreateSecretParams, Secret, SecretDeleteResult, SecretDetail, SecretListParams, SecretListResponse, SecretsPublicKey, SecretValue, SecretVersion, SecretVersionDeleteResult, UpdateSecretParams } 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.
+ *
+ * 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.
+ */
+export declare class SecretsService extends BaseService {
+    /** The key secret values are encrypted to. */
+    getPublicKey(): Promise<SecretsPublicKey>;
+    list(params?: SecretListParams): Promise<SecretListResponse>;
+    /**
+     * Create a secret, and store its first version when `value` is given. The
+     * value and the platform key are checked before the secret is created, so a
+     * bad value never leaves an empty secret behind.
+     */
+    create(params: CreateSecretParams): Promise<Secret>;
+    /** Metadata and versions; never the value. */
+    get(secret: string): Promise<SecretDetail>;
+    update(secret: string, params: UpdateSecretParams): Promise<Secret>;
+    /** Encrypt `value` locally and store it as the secret's next version. */
+    addVersion(secret: string, value: SecretValue): Promise<SecretVersion>;
+    /**
+     * Permanently delete a secret and its versions. Values already delivered to
+     * sandboxes are not revoked.
+     */
+    delete(secret: string): Promise<SecretDeleteResult>;
+    /** Delete one stored version. The latest version cannot be deleted. */
+    deleteVersion(secret: string, version: number): Promise<SecretVersionDeleteResult>;
+    private prepareSealer;
+    private uploadVersion;
+    private resolve;
+    private resolveDetail;
+    /** Found by ID, the result already includes the versions. */
+    private lookup;
+}

package/dist/services/secrets.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretsService = 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");
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The most secrets one list page can hold. */
+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 rethrow = (error, message) => {
+    if (error instanceof error_1.HyperbrowserError) {
+        throw error;
+    }
+    throw new error_1.HyperbrowserError(message, { cause: error });
+};
+/**
+ * Secrets are encrypted locally to the platform's public key; the API only
+ * ever receives envelopes, and values are never returned.
+ *
+ * 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.
+ */
+class SecretsService extends base_1.BaseService {
+    /** The key secret values are encrypted to. */
+    async getPublicKey() {
+        try {
+            return await this.request("/secrets/public-key");
+        }
+        catch (error) {
+            return rethrow(error, "Failed to get the secrets public key");
+        }
+    }
+    async list(params = {}) {
+        const { page, limit } = params;
+        if (page !== undefined && (!Number.isSafeInteger(page) || page < 1)) {
+            throw new error_1.HyperbrowserError("page must be a positive integer");
+        }
+        if (limit !== undefined &&
+            (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIST_LIMIT)) {
+            throw new error_1.HyperbrowserError(`limit must be an integer from 1 to ${MAX_LIST_LIMIT}`);
+        }
+        try {
+            return await this.request("/secrets", undefined, {
+                search: params.search,
+                page: params.page,
+                limit: params.limit,
+            });
+        }
+        catch (error) {
+            return rethrow(error, "Failed to list secrets");
+        }
+    }
+    /**
+     * Create a secret, and store its first version when `value` is given. The
+     * value and the platform key are checked before the secret is created, so a
+     * bad value never leaves an empty secret behind.
+     */
+    async create(params) {
+        const { name, description, value } = 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");
+        }
+        const sealer = value === undefined ? undefined : await this.prepareSealer(value);
+        let secret;
+        try {
+            secret = await this.request("/secrets", {
+                method: "POST",
+                body: JSON.stringify({ name, description }),
+            });
+        }
+        catch (error) {
+            return rethrow(error, `Failed to create secret ${name}`);
+        }
+        if (sealer === undefined) {
+            return secret;
+        }
+        try {
+            const version = await this.uploadVersion(secret, sealer, value);
+            return { ...secret, latestVersion: version.version };
+        }
+        catch (error) {
+            // Retrying create would fail with "name taken"; the value has to be
+            // stored on the secret that now exists.
+            throw new error_1.HyperbrowserError(`Secret ${secret.name} (${secret.id}) was created, but storing its value failed: ${error instanceof Error ? error.message.replace(/^\[Hyperbrowser\]: /, "") : String(error)}. Store it with secrets.addVersion(${JSON.stringify(secret.name)}, value).`, {
+                code: "secret_value_not_stored",
+                retryable: false,
+                service: "control",
+                details: { secret },
+                cause: error,
+            });
+        }
+    }
+    /** Metadata and versions; never the value. */
+    async get(secret) {
+        try {
+            return await this.resolveDetail(secret);
+        }
+        catch (error) {
+            return rethrow(error, `Failed to get secret ${secret}`);
+        }
+    }
+    async update(secret, params) {
+        try {
+            const { id } = await this.resolve(secret);
+            return await this.request(secretPath(id), {
+                method: "PATCH",
+                body: JSON.stringify({ description: params.description }),
+            });
+        }
+        catch (error) {
+            return rethrow(error, `Failed to update secret ${secret}`);
+        }
+    }
+    /** Encrypt `value` locally and store it as the secret's next version. */
+    async addVersion(secret, value) {
+        const sealer = await this.prepareSealer(value);
+        try {
+            return await this.uploadVersion(await this.resolve(secret), sealer, value);
+        }
+        catch (error) {
+            return rethrow(error, `Failed to add a version to secret ${secret}`);
+        }
+    }
+    /**
+     * Permanently delete a secret and its versions. Values already delivered to
+     * sandboxes are not revoked.
+     */
+    async delete(secret) {
+        try {
+            const { id } = await this.resolve(secret);
+            return await this.request(secretPath(id), { method: "DELETE" });
+        }
+        catch (error) {
+            return rethrow(error, `Failed to delete secret ${secret}`);
+        }
+    }
+    /** 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}`);
+        }
+        try {
+            const { id } = await this.resolve(secret);
+            return await this.request(`${secretPath(id)}/versions/${version}`, {
+                method: "DELETE",
+            });
+        }
+        catch (error) {
+            return rethrow(error, `Failed to delete version ${version} of secret ${secret}`);
+        }
+    }
+    async prepareSealer(value) {
+        (0, secrets_envelope_1.secretValueBytes)(value);
+        return secrets_envelope_1.SecretsSealer.fromPublicKey(await this.getPublicKey());
+    }
+    uploadVersion(secret, sealer, value) {
+        return this.request(`${secretPath(secret.id)}/versions`, {
+            method: "POST",
+            body: JSON.stringify({ envelope: sealer.seal(secret.encryptionContext, value) }),
+        });
+    }
+    async resolve(secret) {
+        return (await this.lookup(secret)).secret;
+    }
+    async resolveDetail(secret) {
+        const found = await this.lookup(secret);
+        return found.detail ?? (await this.request(secretPath(found.secret.id)));
+    }
+    /** Found by ID, the result already includes the versions. */
+    async lookup(key) {
+        if (typeof key !== "string" || !key.trim()) {
+            throw new error_1.HyperbrowserError("A secret ID or name is required");
+        }
+        key = key.trim();
+        if (UUID_PATTERN.test(key)) {
+            try {
+                const detail = await this.request(secretPath(key));
+                return { secret: detail, detail };
+            }
+            catch (error) {
+                if (!(error instanceof error_1.HyperbrowserError) || error.statusCode !== 404) {
+                    throw error;
+                }
+            }
+        }
+        const { secrets } = await this.list({ search: key, limit: NAME_LOOKUP_LIMIT });
+        const secret = secrets.find((candidate) => candidate.name === key);
+        if (!secret) {
+            throw new error_1.HyperbrowserError(`Secret ${JSON.stringify(key)} not found`, {
+                statusCode: 404,
+                code: "SECRET_NOT_FOUND",
+                service: "control",
+            });
+        }
+        return { secret };
+    }
+}
+exports.SecretsService = SecretsService;

package/dist/services/sessions.d.ts

@@ -1,5 +1,6 @@
 import { BasicResponse, CaptchaEvaluationParams, CaptchaEvaluationResponse, CreateSessionParams, CreateSessionSnapshotResponse, GetActiveSessionsCountResponse, GetSessionDownloadsUrlResponse, GetSessionRecordingUrlResponse, GetSessionVideoRecordingUrlResponse, SessionDetail, SessionListParams, SessionListResponse, SessionRecording, UploadFileOptions, UploadFileResponse, SessionEventLogListParams, SessionEventLogListResponse, UpdateSessionProfileParams, UpdateSessionProxyParams, UpdateSessionScreenParams, UpdateSessionSolveCaptchasParams, UpdateSessionSolveCaptchasResponse, SessionGetParams } from "../types/session";
 import { BaseService } from "./base";
+import { WebMCPService } from "./webmcp";
 /**
  * Service for managing session event logs
  */
@@ -13,6 +14,7 @@ declare class SessionEventLogsService extends BaseService {
 }
 export declare class SessionsService extends BaseService {
     readonly eventLogs: SessionEventLogsService;
+    readonly webmcp: WebMCPService;
     constructor(apiKey: string, baseUrl: string, timeout: number);
     /**
      * Create a new browser session

package/dist/services/sessions.js

@@ -31,6 +31,7 @@ const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const form_data_1 = __importDefault(require("form-data"));
 const base_1 = require("./base");
+const webmcp_1 = require("./webmcp");
 const client_1 = require("../client");
 const CAPTCHA_EVALUATION_REQUEST_TIMEOUT_MS = 185000;
 /**
@@ -61,6 +62,7 @@ class SessionsService extends base_1.BaseService {
     constructor(apiKey, baseUrl, timeout) {
         super(apiKey, baseUrl, timeout);
         this.eventLogs = new SessionEventLogsService(apiKey, baseUrl, timeout);
+        this.webmcp = new webmcp_1.WebMCPService(apiKey, baseUrl, timeout);
     }
     /**
      * Create a new browser session