@hyperbrowser/sdk 1.2.2 → 1.4.0

package/dist/secret-values.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secretPlaintext = exports.checkTotpSeed = void 0;
+const secrets_envelope_1 = require("./secrets-envelope");
+const TOTP_ALGORITHMS = new Set(["SHA1", "SHA256", "SHA512"]);
+const MAX_TOTP_PERIOD_SECONDS = 300;
+/**
+ * Unpadded base32 can't end with 1, 3 or 6 characters of a block, so such a
+ * seed was copied incompletely. vm-service refuses it too (older hosts
+ * dropped the extra characters and gave wrong codes).
+ */
+const BASE32_TAIL_LENGTHS = new Set([0, 2, 4, 5, 7]);
+const BYTE_ORDER_MARK = "\uFEFF";
+const INVALID_TOTP = "A TOTP value must be a base32 seed or an otpauth://totp/ URI with a base32 secret, " +
+    "and optionally algorithm SHA1, SHA256 or SHA512, digits 6 or 8, and a period of 1 to 300 seconds";
+// vm-service parses seeds with Go: these mirror strings.TrimSpace,
+// url.Parse and url.ParseQuery, so a value is refused here whenever it would
+// be refused there.
+/** Go's unicode.IsSpace: ASCII spaces, U+0085, U+00A0 and the Unicode White_Space spaces. */
+const GO_SPACE = "\t\n\v\f\r \u0085             

  　";
+const trimGoSpace = (value) => {
+    let start = 0;
+    let end = value.length;
+    while (start < end && GO_SPACE.includes(value[start]))
+        start++;
+    while (end > start && GO_SPACE.includes(value[end - 1]))
+        end--;
+    return value.slice(start, end);
+};
+const isHex = (char) => char !== undefined && /^[0-9A-Fa-f]$/.test(char);
+/** Every '%' starts a two-digit hex escape, as url.Parse requires outside the query. */
+const hasValidEscapes = (text) => {
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === "%" && !(isHex(text[i + 1]) && isHex(text[i + 2])))
+            return false;
+    }
+    return true;
+};
+/** url.QueryUnescape; undefined for a bad escape. Bytes are read as Latin-1. */
+const queryUnescape = (text) => {
+    if (!hasValidEscapes(text))
+        return undefined;
+    return text
+        .replace(/\+/g, " ")
+        .replace(/%([0-9A-Fa-f]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+};
+/** url.Values.Get after url.ParseQuery: pairs with bad escapes or ';' are skipped. */
+const queryGet = (query, key) => {
+    for (const pair of query.split("&")) {
+        if (!pair || pair.includes(";"))
+            continue;
+        const separator = pair.indexOf("=");
+        const name = queryUnescape(separator < 0 ? pair : pair.slice(0, separator));
+        const value = queryUnescape(separator < 0 ? "" : pair.slice(separator + 1));
+        if (name === key && value !== undefined)
+            return value;
+    }
+    return "";
+};
+/** Characters url.Parse accepts in the userinfo before '@'. */
+const USERINFO_PATTERN = /^[A-Za-z0-9\-._:~!$&'()*+,;=%@]*$/;
+/**
+ * The otpauth:// URI's query, after the checks url.Parse and vm-service make.
+ * `uri` starts with "otpauth://" in any case.
+ */
+const otpauthQuery = (uri) => {
+    if ([...uri].some((char) => char.charCodeAt(0) < 0x20 || char.charCodeAt(0) === 0x7f)) {
+        throw (0, secrets_envelope_1.invalidSecretValue)("A TOTP otpauth:// URI must not contain control characters");
+    }
+    const hash = uri.indexOf("#");
+    const fragment = hash < 0 ? "" : uri.slice(hash + 1);
+    const beforeFragment = hash < 0 ? uri : uri.slice(0, hash);
+    const question = beforeFragment.indexOf("?");
+    const query = question < 0 ? "" : beforeFragment.slice(question + 1);
+    const rest = (question < 0 ? beforeFragment : beforeFragment.slice(0, question)).slice("otpauth://".length);
+    const slash = rest.indexOf("/");
+    const authority = slash < 0 ? rest : rest.slice(0, slash);
+    const path = slash < 0 ? "" : rest.slice(slash);
+    const at = authority.lastIndexOf("@");
+    const userinfo = at < 0 ? "" : authority.slice(0, at);
+    const host = (at < 0 ? authority : authority.slice(at + 1)).toLowerCase();
+    if (!USERINFO_PATTERN.test(userinfo) || ![userinfo, path, fragment].every(hasValidEscapes)) {
+        throw (0, secrets_envelope_1.invalidSecretValue)(INVALID_TOTP);
+    }
+    if (host === "hotp") {
+        throw (0, secrets_envelope_1.invalidSecretValue)("HOTP (otpauth://hotp/) is not supported; a TOTP value must be a base32 seed or an otpauth://totp/ URI");
+    }
+    if (host !== "totp") {
+        throw (0, secrets_envelope_1.invalidSecretValue)(INVALID_TOTP);
+    }
+    return query;
+};
+/**
+ * The bytes a base32 seed decodes to, read the way the platform reads it:
+ * spaces, '-', line breaks, lowercase and trailing '=' padding are accepted. Undefined
+ * when it isn't ASCII base32 or has an impossible length.
+ */
+const base32SeedBytes = (seed) => {
+    // Upper-cased one character at a time, as Go does, so "ß" can't turn into
+    // "SS" while "ı" still reads as "I".
+    const upper = Array.from(seed.replace(/[ \r\n-]/g, ""), (char) => {
+        const mapped = char.toUpperCase();
+        return mapped.length === 1 ? mapped : char;
+    }).join("");
+    if (!/^[A-Z2-7]+=*$/.test(upper))
+        return undefined;
+    const normalized = upper.replace(/=+$/, "");
+    return BASE32_TAIL_LENGTHS.has(normalized.length % 8)
+        ? Math.floor((normalized.length * 5) / 8)
+        : undefined;
+};
+const isIntegerIn = (text, allowed) => /^[+-]?\d+$/.test(text) && allowed(Number(text));
+/**
+ * Check a TOTP seed as the platform will read it at fill or process time; the
+ * API can't see values, so a bad seed would otherwise only fail then. Seeds
+ * under 10 bytes (16 base32 characters) are accepted, though they are
+ * unusually short.
+ */
+const checkTotpSeed = (value) => {
+    let seed = trimGoSpace(value.startsWith(BYTE_ORDER_MARK) ? value.slice(1) : value);
+    if (seed.toLowerCase().startsWith("otpauth://")) {
+        const query = otpauthQuery(seed);
+        const algorithm = queryGet(query, "algorithm");
+        const digits = queryGet(query, "digits");
+        const period = queryGet(query, "period");
+        if ((algorithm && !TOTP_ALGORITHMS.has(algorithm.toUpperCase())) ||
+            (digits && !isIntegerIn(digits, (n) => n === 6 || n === 8)) ||
+            (period && !isIntegerIn(period, (n) => n >= 1 && n <= MAX_TOTP_PERIOD_SECONDS))) {
+            throw (0, secrets_envelope_1.invalidSecretValue)(INVALID_TOTP);
+        }
+        seed = queryGet(query, "secret");
+    }
+    else if (/^[a-z][a-z0-9+.-]*:\/\//i.test(seed)) {
+        throw (0, secrets_envelope_1.invalidSecretValue)(INVALID_TOTP);
+    }
+    if (base32SeedBytes(seed) === undefined) {
+        throw (0, secrets_envelope_1.invalidSecretValue)(INVALID_TOTP);
+    }
+};
+exports.checkTotpSeed = checkTotpSeed;
+/**
+ * The plaintext stored for a secret of `type`, after the platform's rules
+ * for every value (1 byte to 32 KiB of UTF-8, no NUL) and the type's own.
+ * Types this SDK doesn't know get the common rules only.
+ */
+const secretPlaintext = (type, value) => {
+    const bytes = (0, secrets_envelope_1.secretValueBytes)(value);
+    if (type === "totp") {
+        (0, exports.checkTotpSeed)(bytes.toString("utf8"));
+    }
+    return bytes;
+};
+exports.secretPlaintext = secretPlaintext;

package/dist/secrets-envelope.d.ts

@@ -1,11 +1,16 @@
+import { HyperbrowserError } from "./error";
 import { SecretsPublicKey, SecretValue } from "./types/secret";
 /** The largest secret value the platform accepts. */
 export declare const MAX_SECRET_VALUE_BYTES: number;
+/** @internal A value the platform would refuse. Messages never include the value. */
+export declare const invalidSecretValue: (message: string) => HyperbrowserError;
 /**
  * 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;
+/** A plain object, as opposed to an array, bytes or a class instance. */
+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;

package/dist/secrets-envelope.js

@@ -3,14 +3,16 @@ 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;
+exports.SecretsSealer = exports.isPlainObject = exports.secretValueBytes = exports.invalidSecretValue = 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 });
+/** @internal A value the platform would refuse. Messages never include the value. */
+const invalidSecretValue = (message) => new error_1.HyperbrowserError(message, { code: "invalid_secret_value", retryable: false });
+exports.invalidSecretValue = invalidSecretValue;
 const base64Url = (data) => Buffer.from(data).toString("base64url");
 /**
  * Apply the platform's value rules locally, so a bad value is reported before
@@ -18,27 +20,35 @@ const base64Url = (data) => Buffer.from(data).toString("base64url");
  */
 const secretValueBytes = (value) => {
     if (typeof value !== "string" && !(value instanceof Uint8Array)) {
-        throw invalid("Secret value must be a string or bytes");
+        throw (0, exports.invalidSecretValue)("Secret value must be a string or bytes");
     }
     const bytes = Buffer.from(value);
     if (bytes.length === 0) {
-        throw invalid("Secret value is empty");
+        throw (0, exports.invalidSecretValue)("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`);
+        throw (0, exports.invalidSecretValue)(`Secret value is more than ${exports.MAX_SECRET_VALUE_BYTES} bytes`);
     }
     if (bytes.includes(0)) {
-        throw invalid("Secret value must not contain NUL bytes");
+        throw (0, exports.invalidSecretValue)("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");
+        throw (0, exports.invalidSecretValue)("Secret value must be valid UTF-8");
     }
     return bytes;
 };
 exports.secretValueBytes = secretValueBytes;
+/** A plain object, as opposed to an array, bytes or a class instance. */
+const isPlainObject = (value) => {
+    if (value === null || typeof value !== "object")
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+exports.isPlainObject = isPlainObject;
 const minimalBytes = (value) => {
     let start = 0;
     while (start < value.length - 1 && value[start] === 0)

package/dist/services/credentials.d.ts

@@ -0,0 +1,24 @@
+import { CredentialFillResult, FillCredentialParams } from "../types/credential";
+import { BaseService } from "./base";
+/** Fill secrets attached to a browser session into its pages. */
+export declare class CredentialsService extends BaseService {
+    /**
+     * Type a secret, a vault's entries, or 1Password fields into inputs on one
+     * of the session's pages. A TOTP secret types its current code. Only types;
+     * never submits, so click the login button or press Enter afterwards.
+     * Values never leave the platform: the result lists an outcome per input.
+     * Safe to retry; it is not retried automatically.
+     *
+     * With `onePassword`, each field's `ref` names the 1Password field, the
+     * `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`.
+     *
+     * 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`
+     * for `CREDENTIAL_PAGE_AMBIGUOUS`, or `selectors` and `reasons` (by
+     * selector) for `SECRET_ONEPASSWORD_REFERENCE_FAILED`.
+     */
+    fill(sessionId: string, params: FillCredentialParams): Promise<CredentialFillResult>;
+}

package/dist/services/credentials.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CredentialsService = void 0;
+const error_1 = require("../error");
+const secrets_envelope_1 = require("../secrets-envelope");
+const base_1 = require("./base");
+/** The API gives up on a fill after about 18 seconds. */
+const MIN_FILL_TIMEOUT_MS = 30000;
+/** Fill secrets attached to a browser session into its pages. */
+class CredentialsService extends base_1.BaseService {
+    /**
+     * Type a secret, a vault's entries, or 1Password fields into inputs on one
+     * of the session's pages. A TOTP secret types its current code. Only types;
+     * never submits, so click the login button or press Enter afterwards.
+     * Values never leave the platform: the result lists an outcome per input.
+     * Safe to retry; it is not retried automatically.
+     *
+     * With `onePassword`, each field's `ref` names the 1Password field, the
+     * `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`.
+     *
+     * 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`
+     * for `CREDENTIAL_PAGE_AMBIGUOUS`, or `selectors` and `reasons` (by
+     * selector) for `SECRET_ONEPASSWORD_REFERENCE_FAILED`.
+     */
+    async fill(sessionId, params) {
+        if (typeof sessionId !== "string" || !sessionId.trim()) {
+            throw (0, error_1.invalidRequest)("A session ID is required");
+        }
+        if (!(0, secrets_envelope_1.isPlainObject)(params)) {
+            throw (0, error_1.invalidRequest)("Fill parameters must be an object");
+        }
+        if ("frame" in params) {
+            throw (0, error_1.invalidRequest)("Use frameUrl to select an iframe");
+        }
+        // Preserve request members so the API can reject unknown or conflicting options.
+        const { frameUrl, ...body } = params;
+        return this.request(`/session/${encodeURIComponent(sessionId)}/credentials/fill`, {
+            method: "POST",
+            body: JSON.stringify({ ...body, frame: frameUrl == null ? undefined : { url: frameUrl } }),
+            timeout: Math.max(this.timeout, MIN_FILL_TIMEOUT_MS),
+        });
+    }
+}
+exports.CredentialsService = CredentialsService;

package/dist/services/sandboxes.d.ts

@@ -118,8 +118,9 @@ export declare class SandboxesService extends BaseService {
     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.
+     * With secrets, a vault or onePassword, 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

@@ -71,9 +71,12 @@ 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;
         // 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");
+        if ((secrets !== undefined || vault !== undefined || onePassword !== undefined) &&
+            params.runtimeClass === "gvisor-cpu")
+            throw new error_1.HyperbrowserError("secrets, vault and onePassword are not supported with runtimeClass gvisor-cpu");
         return {
             runtimeClass: params.runtimeClass,
             imageName: params.imageName,
@@ -90,12 +93,16 @@ const serializeCreateSandboxParams = (params) => {
             allowOut: params.allowOut,
             denyOut: params.denyOut,
             secrets,
+            vault,
+            onePassword,
         };
     }
     const snapshotParams = params;
-    if (snapshotParams.secrets !== undefined) {
+    if (snapshotParams.secrets !== undefined ||
+        snapshotParams.vault !== undefined ||
+        snapshotParams.onePassword !== undefined) {
         // Snapshot launches do not run a startup command.
-        throw new error_1.HyperbrowserError("secrets are only supported for image launches");
+        throw new error_1.HyperbrowserError("secrets, vault and onePassword are only supported for image launches");
     }
     if (snapshotParams.cpu !== undefined ||
         snapshotParams.memoryMiB !== undefined ||
@@ -320,7 +327,9 @@ class SandboxHandle {
         return this.processes.get(processId);
     }
     hydrate(detail) {
-        this.detail = detail;
+        // Only the create response reports what the startup command received.
+        const startupSecrets = detail.startupSecrets ?? this.detail?.startupSecrets;
+        this.detail = startupSecrets === undefined ? detail : { ...detail, startupSecrets };
         this.runtimeSession = SandboxHandle.toRuntimeSession(detail);
     }
     async resolveRuntimeConnection(forceRefresh = false) {
@@ -1120,24 +1129,25 @@ class SandboxesService extends base_2.BaseService {
         }
     }
     /**
-     * With secrets, a create whose result is unknown is never retried: the
-     * sandbox may exist and be running its startup command with the secrets.
+     * With secrets, a vault or onePassword, 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);
+        const withSecrets = body.secrets !== undefined || body.vault !== undefined || body.onePassword !== undefined;
         try {
             const detail = await this.request("/sandbox", {
                 method: "POST",
                 body: JSON.stringify(body),
             });
-            if (body.secrets !== undefined &&
-                (typeof detail?.id !== "string" || !detail.id.trim())) {
+            if (withSecrets && (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)) {
+            if (withSecrets && (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`, {

package/dist/services/secrets.d.ts

@@ -14,15 +14,30 @@ export declare class SecretsService extends BaseService {
     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.
+     * value is checked against its type's rules, and the platform key is
+     * 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>;
+    /**
+     * Change a secret's description or metadata. Metadata members sent replace
+     * the stored ones, `null` removes a member, and members not sent are kept.
+     */
     update(secret: string, params: UpdateSecretParams): Promise<Secret>;
-    /** Encrypt `value` locally and store it as the secret's next version. */
+    /**
+     * Encrypt `value` locally and store it as the secret's next version. The
+     * 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>;
+    /**
+     * 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
+     * again). Not for `op_token` secrets.
+     */
+    setAllowedOrigins(secret: string, allowedOrigins: string[] | null): Promise<Secret>;
     /**
      * Permanently delete a secret and its versions. Values already delivered to
      * sandboxes are not revoked.
@@ -30,7 +45,7 @@ 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>;
-    private prepareSealer;
+    /** Sealed to the context the API returned for the secret; never one built here. */
     private uploadVersion;
     private resolve;
     private resolveDetail;

package/dist/services/secrets.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SecretsService = void 0;
 const error_1 = require("../error");
 const secret_references_1 = require("../sandbox/secret-references");
+const secret_values_1 = require("../secret-values");
 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;
@@ -44,11 +45,15 @@ class SecretsService extends base_1.BaseService {
             (!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}`);
         }
+        if (params.type !== undefined && (typeof params.type !== "string" || !params.type)) {
+            throw (0, error_1.invalidRequest)('type must be a secret type such as "secret" or "totp"');
+        }
         try {
             return await this.request("/secrets", undefined, {
                 search: params.search,
                 page: params.page,
                 limit: params.limit,
+                type: params.type,
             });
         }
         catch (error) {
@@ -57,30 +62,36 @@ class SecretsService extends base_1.BaseService {
     }
     /**
      * 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.
+     * value is checked against its type's rules, and the platform key is
+     * checked, before the secret is created, so a bad value never leaves an
+     * empty secret behind.
      */
     async create(params) {
-        const { name, description, value } = params ?? {};
+        const { name, description, type, allowedOrigins, 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);
+        if (type !== undefined && (typeof type !== "string" || !type)) {
+            throw (0, error_1.invalidRequest)('type must be "secret", "totp" or "op_token"');
+        }
+        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 } };
         let secret;
         try {
             secret = await this.request("/secrets", {
                 method: "POST",
-                body: JSON.stringify({ name, description }),
+                body: JSON.stringify({ name, description, type, metadata }),
             });
         }
         catch (error) {
             return rethrow(error, `Failed to create secret ${name}`);
         }
-        if (sealer === undefined) {
+        if (sealer === undefined || plaintext === undefined) {
             return secret;
         }
         try {
-            const version = await this.uploadVersion(secret, sealer, value);
+            const version = await this.uploadVersion(secret, sealer, plaintext);
             return { ...secret, latestVersion: version.version };
         }
         catch (error) {
@@ -104,28 +115,56 @@ class SecretsService extends base_1.BaseService {
             return rethrow(error, `Failed to get secret ${secret}`);
         }
     }
+    /**
+     * Change a secret's description or metadata. Metadata members sent replace
+     * the stored ones, `null` removes a member, and members not sent are kept.
+     */
     async update(secret, params) {
+        const { description, metadata } = params ?? {};
+        if (description === undefined && metadata === undefined) {
+            throw (0, error_1.invalidRequest)("Pass a description or metadata to update");
+        }
+        if (metadata !== undefined && !(0, secrets_envelope_1.isPlainObject)(metadata)) {
+            throw (0, error_1.invalidRequest)("Secret metadata must be an object");
+        }
         try {
             const { id } = await this.resolve(secret);
             return await this.request(secretPath(id), {
                 method: "PATCH",
-                body: JSON.stringify({ description: params.description }),
+                body: JSON.stringify({ description, metadata }),
             });
         }
         catch (error) {
             return rethrow(error, `Failed to update secret ${secret}`);
         }
     }
-    /** Encrypt `value` locally and store it as the secret's next version. */
+    /**
+     * Encrypt `value` locally and store it as the secret's next version. The
+     * 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) {
-        const sealer = await this.prepareSealer(value);
+        (0, secrets_envelope_1.secretValueBytes)(value);
+        const sealer = secrets_envelope_1.SecretsSealer.fromPublicKey(await this.getPublicKey());
         try {
-            return await this.uploadVersion(await this.resolve(secret), sealer, value);
+            const resolved = await this.resolve(secret);
+            const plaintext = (0, secret_values_1.secretPlaintext)(resolved.type ?? "secret", value);
+            return await this.uploadVersion(resolved, sealer, plaintext);
         }
         catch (error) {
             return rethrow(error, `Failed to add a version to 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
+     * again). Not for `op_token` secrets.
+     */
+    async setAllowedOrigins(secret, allowedOrigins) {
+        return this.update(secret, {
+            metadata: { browser: allowedOrigins === null ? null : { allowedOrigins } },
+        });
+    }
     /**
      * Permanently delete a secret and its versions. Values already delivered to
      * sandboxes are not revoked.
@@ -154,14 +193,11 @@ class SecretsService extends base_1.BaseService {
             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) {
+    /** Sealed to the context the API returned for the secret; never one built here. */
+    uploadVersion(secret, sealer, plaintext) {
         return this.request(`${secretPath(secret.id)}/versions`, {
             method: "POST",
-            body: JSON.stringify({ envelope: sealer.seal(secret.encryptionContext, value) }),
+            body: JSON.stringify({ envelope: sealer.seal(secret.encryptionContext, plaintext) }),
         });
     }
     async resolve(secret) {

package/dist/services/sessions.d.ts

@@ -1,6 +1,7 @@
 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";
+import { CredentialsService } from "./credentials";
 /**
  * Service for managing session event logs
  */
@@ -15,6 +16,7 @@ declare class SessionEventLogsService extends BaseService {
 export declare class SessionsService extends BaseService {
     readonly eventLogs: SessionEventLogsService;
     readonly webmcp: WebMCPService;
+    readonly credentials: CredentialsService;
     constructor(apiKey: string, baseUrl: string, timeout: number);
     /**
      * Create a new browser session

package/dist/services/sessions.js

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

package/dist/services/vaults.d.ts

@@ -0,0 +1,26 @@
+import { CreateVaultParams, UpdateVaultParams, Vault, VaultDeleteResult, VaultListParams, VaultListResponse } 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.
+ *
+ * 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.
+ */
+export declare class VaultsService extends BaseService {
+    list(params?: VaultListParams): Promise<VaultListResponse>;
+    get(vault: string): Promise<Vault>;
+    /** Create a vault. Entries name secrets, never values. */
+    create(params: CreateVaultParams): Promise<Vault>;
+    /**
+     * Change a vault's description or its entries:
+     * each entry given replaces that variable, `null` removes it, and entries
+     * not given are kept.
+     */
+    update(vault: string, params: UpdateVaultParams): Promise<Vault>;
+    /** Delete a vault. The secrets its entries name are kept. */
+    delete(vault: string): Promise<VaultDeleteResult>;
+    private resolve;
+}