Add credential fill, vaults, TOTP and 1Password tokens, with LLM tools

[AHarmlessPyro]

Adds browser credential fill, vaults and typed secrets to the SDK, plus fill_credential tool definitions for OpenAI, Anthropic and Gemini. It matches browserctrl master at 08c5d5232: #1572 (fill on plain secrets), #1551 (vaults), #1552 (op_token, per-request 1Password fields and 1Password browser fill) and #1573 (totp).

The credential secret type from #1537 is gone. A login is plain secrets that have allowed origins, usually grouped in a vault (USERNAME, PASSWORD, and optionally OTP from a totp secret). Values are encrypted locally and typed into pages by the platform, so neither the caller's code nor an LLM ever sees them.

API

Secrets

• client.secrets.create({ name, value?, description?, type?: "secret" | "totp" | "op_token", allowedOrigins? })
  • Values are checked locally per type before anything is created.
  • totp: a base32 seed or an otpauth://totp/ URI. The parsing mirrors vm-service's parseTOTPSeed: spaces, hyphens and line breaks are ignored, = padding is allowed only at the end, and lengths 1, 3 or 6 past a multiple of 8 are refused, as vm-service also does since #1573. In a URI, algorithm, digits and period are range-checked, and HOTP is refused.
  • op_token: a 1Password service account token, named by onePassword.token. It takes no allowed origins.
  • Values are always sealed with the encryptionContext the API returns.
• addVersion(secret, value) checks the value against the secret's stored type.
• setAllowedOrigins(secret, origins | null), update(secret, { description?, metadata? }) and list({ type }).
• Secret.type is a plain string, so types added later still parse.
• createCredential and object values are removed.

Vaults (new client.vaults, by ID or exact name)

• list, get, delete.
• create({ name, description?, entries? }) and update(vault, { description?, entries?: { ENV: { name, version? } | null } }), where null removes an entry. Vaults hold stored secrets only, as on master.

Sandboxes

• vault on sandboxes.create (image launches) and on process exec/start. secrets wins on a clash.
• onePassword: { token, vault, fields: { ENV: { item, section?, field } } } on the same calls reads fields of a 1Password vault when the process starts.
• Bindings (startupSecrets, process secrets) are either stored ({ env, name, secretId, version, secretType?, source: vault | secrets, overrides? }) or 1Password ({ env, reference, tokenSecret, source: { type: "onePassword" } }).
• The sandbox handle keeps startupSecrets across refreshes.

Sessions

• credentials?: Array<string | { secret } | { vault } | { onePassword }> on create. { onePassword: "op-token" } attaches an op_token so fills can read 1Password fields. The response lists the attached secrets.
• client.sessions.credentials.fill(sessionId, { credential? | vault?, fields: [{ selector, field? }], pageId? | pageUrl?, frameUrl? })
  • It returns { version?, pageId, origin, fields: [{ selector, outcome, secretId, version, field?, expiresAt? }] }.
  • The request is checked locally, the timeout is at least 30 s, and errors keep the server's code and retryable.
• 1Password fill: fill(sessionId, { onePassword: { token, vault, allowedOrigins }, fields: [{ selector, ref: { item, section?, field } }] }). Each field result gains reference, and there's no top-level version. One source, ref on every field, origins, part rules and 512-byte references are checked locally.

Tools: CredentialFillTool / fill_credential (OpenAI strict, Anthropic, Gemini)

• The model picks credential or vault, fields[{selector, field}], and optionally page_id, page_url and frame_url. The application binds the session.
• It doesn't offer 1Password fills: those name their allowed origins in the request, and a model shouldn't choose them. Apps call fill directly.
• null and "" count as absent.
• Results and errors come back as JSON that never contains values.
• Every existing tool also gains a Gemini definition.

README: the secrets, vaults and credential fill section is rewritten. It covers onePassword, error codes and the tool loops.

Validation split: the SDK checks request shapes, secret values (UTF-8, size, no NUL) and TOTP seeds locally, since the API can't see an encrypted value. Policy rules (allowed-origin syntax, 1Password names and the 512-byte reference, field and entry limits, source clashes) are left to the API, which returns its status, code, retryable flag and details unchanged. See docs/credentials-cleanup.md.

Version

The package is bumped to 1.3.1 (published: 1.2.2).

Validation

• Local checks: after the rebase onto main and the validation cleanup, yarn test passes 837 tests. Lint, typecheck and build are clean.
• Audit against master 08c5d5232 (before the validation cleanup): every request, response, error and README claim was checked against the merged server. Fixes:
  • a vault description is now limited after trimming, as the server does;
  • the README says a fill with frameUrl doesn't narrow tabs by allowed origin;
  • the README says SECRET_ONEPASSWORD_AUTH_FAILED also covers a malformed token.
• End to end (before the validation cleanup): 33/33 checks passed against a local stack running #1552 and #1573:
  • secrets with origins;
  • TOTP create and add-version, with bad seeds refused locally;
  • a stored vault, and a session with [{ vault }];
  • vault, single-secret and TOTP fills (expiresAt);
  • the ambiguous-page retry with pageId, and origin refusal;
  • SECRET_IN_USE;
  • a real login on practicetestautomation.com.
• Model loop: one gpt-5-mini loop logged in by vault fill.
• TOTP parsing: compared with #1573's parseTOTPSeed (including its line-break fix, 456995310) on 143 edge cases, alongside python-sdk, hx and the dashboard: no differences.
• 1Password, live (run before the validation cleanup; not repeated since): 26/26 checks passed against the same stack with a real 1Password service account:
  • onePassword on sandbox create (the startup command), exec and processes.start; the values matched by hash;
  • the bindings and the clash, missing-item, wrong-type and missing-token errors;
  • an op_token refused as a plain credential;
  • 1Password fill with origin, not-attached and missing-item refusals, then a real login on scrapingcourse.com;
  • no response contains the token.

Needs browserctrl #1552 and #1573 (both merged) to be deployed for op_token, onePassword and totp.

🤖 Generated with Claude Code

https://claude.ai/code/session_019dbwbLvQGyzwkxNetvqf3v

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 80e2b69. Configure here.}