trusty-squire

<p align="center">
  <a href="https://trustysquire.ai" target="_blank" rel="noopener noreferrer">
    <img width="84" height="84" src="https://trustysquire.ai/logo.svg" alt="Trusty Squire shield" />
  </a>
</p>

<h1 align="center">Trusty Squire</h1>

<p align="center">
  <a href="https://www.npmjs.com/package/@trusty-squire/mcp"><img src="https://img.shields.io/npm/v/@trusty-squire/mcp?logo=npm&color=cb3837" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/@trusty-squire/mcp"><img src="https://img.shields.io/npm/dm/@trusty-squire/mcp?color=cb3837" alt="npm downloads" /></a>
  <a href="https://github.com/Trusty-Squire/trusty-squire/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Trusty-Squire/trusty-squire/ci.yml?branch=main&label=CI&logo=github" alt="CI status" /></a>
  <a href="https://github.com/Trusty-Squire/trusty-squire/stargazers"><img src="https://img.shields.io/github/stars/Trusty-Squire/trusty-squire?logo=github&color=eac54f" alt="GitHub stars" /></a>
  <a href="https://github.com/Trusty-Squire/trusty-squire/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license" /></a>
</p>

<p align="center"><strong>Empower agents with auth and payments.</strong></p>
<p align="center">MCP tools to automate auth and pay — your keys and card stay out of agent context.</p>

Trusty Squire is an **MCP server that lets Claude Code, Codex, Cursor, OpenCode, Goose, and other coding agents sign up, provision, and purchase on your behalf**. It opens a real browser, works through signup, sign-in, setup, and checkout flows one step at a time, clears the bot-detection and email-verification steps that make operator tools stall, and hands the job back to a person only when one is actually required. That covers wiring up OAuth and API keys for the app you're building as much as it covers paying a checkout, sending a gift, or booking something — the same operator primitives drive all of it.

Provider secrets and payment cards are write-only: the agent's credential tools return references and authenticated results, never stored plaintext. The raw secret never needs to enter the agent's context, so it can't be pasted into a commit, leaked in a log, or read back out over chat. When a task genuinely needs the plaintext somewhere the agent controls, `fetch_credential` releases it — for one credential, once, and only after you sign that exact request with your passkey. Backend access is a host-scoped, rate-limited, independently revocable grant, so a leaked token is killed without rotating the provider key — and you connect Google or GitHub yourself in a real browser, so the agent never types your password. Full [threat model below](#security-and-threat-model).

## Direct payment observation

The agent drives the live checkout from ordinary browser evidence. It reads the
amount, currency, DCC choice, card controls, validation errors, requests, and
rendered state with `operate_observe`, `operate_network`, and
`operate_screenshot`, then uses the ordinary click, type, select, press, scroll,
and wait loop to advance the purchase. A spinner is evidence; the operator does
not translate it into a payment stage.

When card fields are ready, call `list_payment_cards` and then
`inject_card` with the addressed session, the purchase terms, the selected
`card_ref`, and an observation ref for each field to fill. `inject_card` uses the
existing single human approval for that purchase, verifies the signed release,
and opens the card only inside the operator. A pending approval is resumed with
the returned `approval_id`; retries may supply changed field refs under that same
still-valid approval. The primitive fills only the named fields and returns a
per-field `filled`, `not_found`, `detached`, or `native_error` result. It never
searches for a provider, chooses a saved-card UI, rereads the total, submits,
clears fields, or diagnoses the checkout.

Hosted-field providers can render decoy autofill or focus-helper inputs beside
the actual field (notably Braintree and Stripe). Choose the ref for the visible
card control, not a helper input. Before placing the order, re-observe and
confirm that no competing merchant-saved-card radio or option remains selected.
If a 3-D Secure challenge appears, the operator detects it on the next
observation or action result, notifies the cardholder once through the purchase
notification path, and reports `three_ds`; keep observing the live checkout
while the cardholder completes it.

Before the first card write, the operator installs a session-lifetime output
mask for that released PAN and security code. Normal DOM/AX observations, raw
attribute/subtree reads, network headers and bodies, errors, console evidence,
and screenshots replace or cover complete values and ordinary PAN prefixes of
at least eight digits. Merchant last4, brand, name, expiry, billing address,
amounts, currency/DCC, HTTP errors, API keys, and 3-D Secure controls remain
visible. The agent re-observes partial fills, retries targets if needed, selects
currency, clicks place order, and follows 3-D Secure from the same generic
evidence stream. There is no `operate_payment_status` or operator-owned
submit/outcome state machine.

This is a narrow ordinary-checkout boundary, not hostile-page information-flow
containment. It is designed for ordinary forms and reachable hosted fields;
provider-specific behavior still has to be verified from the returned field
results and fresh observations. A hostile page can split, encode, or
canvas-render a card value so it no longer matches the released value; the
operator does not add a broad secret scanner or claim to defeat that page.

## Install

```bash
npx @trusty-squire/mcp connect
```

`connect` signs you in with Google or GitHub, detects your coding agent, and merges the `squire` MCP server into its existing configuration. On a machine with a user-visible desktop, sign-in opens a local Chrome window. On a headless Linux server, including an SSH/TTY session with an inherited virtual display, interactive login starts a login-scoped Xvfb and noVNC stack and prints a URL you can open on another device. The default quick tunnel and every local helper are torn down when that login completes, times out, fails, or is interrupted. Operators may instead set both `TS_LOGIN_PUBLIC_HOSTNAME` and `TS_LOGIN_LOCAL_PORT` to reuse an externally managed named tunnel; Trusty Squire still tears down its per-login display and local listener, but never creates or stops that external tunnel. If that tunnel's fixed local port is busy, login reports it and uses a one-off quick tunnel for that sign-in instead. Restart the agent and ask for the finished website outcome. Trusty Squire is free to start.

`connect` is also the only way to sign in again: `--force-relogin` switches the bound account and `--force-relogin=google` or `--force-relogin=github` refreshes one provider session. It reports success only after re-checking the browser profile and finding that Google session live, so a run that binds the machine but leaves no usable session fails loudly with the command to retry rather than reporting a working install.

Local state is kept separately for each connected account, and `connect` pins
that account in the agent's MCP configuration; connecting another account does
not replace the first account's state. To remove just one account, run
`npx @trusty-squire/mcp logout --account=<id>`; without `--account`, `logout`
removes the most recently connected account. `--account` requires a nonempty
account ID.

To choose a target explicitly:

```bash
npx @trusty-squire/mcp connect --target=codex
```

Supported targets: `claude-code`, `cursor`, `codex`, `opencode`, `goose`, `cline`, `continue`, and `hermes`.

The isolated `operate_*` browser runtime currently requires Linux and a local Chrome connection;
remote CDP, macOS, and Windows operator sessions are not supported in this migration stage.

## What happens

1. Your coding agent names the website and the outcome it needs: an account,
   authenticated setup, app publishing, a purchase, a gift, or a booking.
2. Trusty Squire works through the service flow one step at a time. Every task
   opens its own fresh browser profile and restores the snapshot's non-Google
   signed-in state, so independent sessions can run concurrently without opening
   the canonical login profile. Google state is restored inside the serialized
   `operate_login` boundary; sanctioned Gmail verification
   uses a separate temporary identity browser.
3. If the flow produces an API key or client secret, Trusty Squire captures it
   into the vault without returning the raw value through its credential tools.
4. The agent can make an authenticated request, create a host-scoped app grant,
   or use a saved card for a supported checkout after you approve the purchase.
5. Eligible successful flows can become signed registry skills, so later runs can replay verified steps instead of rediscovering every click.

If a site requires phone verification, a hard CAPTCHA, an unresolved 3-D Secure
challenge, an unsupported payment method, or another human decision, the run
hands control back and tells you. It does not guess or pretend the task completed.

## Supported services

Discovery pages are generated only for services with an active skill in the Trusty Squire registry. The first five detailed pages cover Braintrust, Cerebras, Clerk, DeepInfra, and Zilliz Cloud. Each sample has explicit signup evidence in its active registry record and a provider request checked against official API documentation. The service hub also lists every active registry entry; the remaining detail pages stay unpublished until their workflow and unique content pass review.

Browse the [active service catalog](https://trustysquire.ai/services). Maintainers can detect registry drift before merging with:

```bash
pnpm seo:verify-services
```

The registry controls which s