keysat-plans/agent-payment-connect-scope.md

# Plan: agent-delegable payment-provider connect (without making it a fund-redirection key)

Status: **APPROVED — agreed shape, ready to build. No urgency** (doc-harness Path 1, no
payments, ships first; this work feeds Path 2, the full regtest buyer-pays walkthrough).
Author: this session, 2026-06-16. Sign-off: other dev, 2026-06-16.
Related: `merchant-onboard` role shipped in `0.2.0:57` (`src/api/api_keys.rs`); multi-provider
model (`plans/multi-provider-payment-model.md`).

## 1. Problem / motivation

Make Keysat **fully agent-compatible**: an operator hands an agent a scoped credential and
says *"add Keysat licensing to this software and connect a Bitcoin wallet on BTCPay,"* and
the agent does the whole thing over the API. Two use cases:

1. **Production delegation** — a real operator delegates first-time setup (catalog + connect
   their BTCPay) to an agent.
2. **Doc-onboarding test harness** — a fresh AI agent integrates Keysat from the docs alone
   against a disposable server, published as marketing ("all the agent had to do was X, Y,
   Z"). For dev/testing the agent uses **regtest** (private Bitcoin network — mine blocks on
   demand, no faucets, no real money).

`merchant-onboard` (shipped `:57`) covers catalog + manual license issuance end-to-end but
**cannot connect a payment provider** — that stays master-key only. So the agent story stops
one step short of "accept buyer payments."

## 2. The core risk (why connect is the crown jewel) — ratified

Creating products/policies/licenses is *"what you sell."* Connecting — or **re**-connecting —
a payment provider is **"where the money goes":** a credential that can do it can repoint
settlement at an **attacker-controlled wallet/store**, after which every buyer payment lands
there. Direct **theft-of-funds**, strictly worse than any catalog write. The value of a
scoped key is **bounded blast radius**; folding connect into `merchant-onboard` would make it
"near-total financial control with a friendly name."

**Binding decision (both devs): do NOT fold connect into `merchant-onboard`.** A key that can
repoint settlement is a fund-redirection key; bounding that blast radius is the whole point.

## 3. Current state (verified against code, 2026-06-16)

- All provider-mutating endpoints are **master-key only** (`require_admin`):
  - BTCPay connect — `api/btcpay_authorize.rs:87` (OAuth-style: returns an `authorize_url`; a
    human approves on BTCPay, then the callback persists store id / API key / webhook secret).
  - BTCPay disconnect — `btcpay_authorize.rs:426`.
  - Zaprite connect — `api/zaprite_authorize.rs:56` (API-key paste; **no** OAuth step).
  - Zaprite disconnect — `zaprite_authorize.rs:207`.
- Only `payment_providers:read` exists as a scope; there is **no** `payment_providers:write`
  today. `merchant-onboard` grants all `:read` + `products:write` + `policies:write` +
  `licenses:write`. Master-only ops sit behind `require_admin`, never consulting `Role::grants`.
- Asymmetry: **BTCPay is self-hosted, can run regtest/testnet** (the safe case). **Zaprite is
  a hosted mainnet SaaS** — no regtest equivalent assumed, so scoped Zaprite-connect stays
  master-only and the demo uses BTCPay (the motivating case anyway).

## 4. Options (B rejected; built shape is C + D, gated by E)

| # | Option | Verdict |
|---|--------|---------|
| A | Keep connect master-only (status quo) | Safe, not fully agent-compatible |
| B | Fold connect into `merchant-onboard` | **Rejected (binding)** — fund-redirection key |
| C | À-la-carte scope `payment_providers:write`, never in any default role | **Chosen** packaging |
| D | Network gate: scoped connect only regtest/testnet/signet; mainnet → master | **Chosen** (inner defense) |
| E | Sandbox-mode daemon flag for disposable instances | **Chosen as the OUTER gate** (see §5) |

## 5. Agreed design — gate order matters

A *scoped* `payment_providers:write` connect is permitted **iff ALL** hold, checked in this
order:

1. **OUTER — sandbox-mode daemon flag is ON.** On a production (non-sandbox) daemon, scoped
   payment-connect is **disabled entirely — even regtest.** *(Refinement, dev:* a scoped key
   connecting a regtest provider on a production box would knock out the live store's real
   payments — denial-of-revenue, not theft, but still bad. So the flag, not the network, is
   the first gate.*)*
2. **INNER — target network is non-mainnet** (regtest/testnet/signet). Defense-in-depth so
   that even on a sandbox daemon a scoped key can't wire up mainnet. **Fail closed:** if the
   network can't be positively determined as non-mainnet, treat it as mainnet → deny.
3. **BTCPay OAuth human-approve** still happens (someone approves on BTCPay's side).

Master key bypasses 1–2 and may connect any network (still subject to BTCPay's own OAuth).

**The sandbox flag is daemon-level config (env / launch), read at boot — NEVER settable via
any API, scoped or otherwise.** *(Refinement, dev:* otherwise a scoped key flips sandbox on,
then connects. Keep it strictly out-of-band.*)*

Net: full agent-compatibility for dev/testing on a sandbox+regtest instance (zero master-key
steps — the doc-harness Path 2), and production stays locked: no scoped key can connect,
reconnect, or disconnect a provider on a live box.

## 6. Resolved decisions (the dev's open-question answers)

1. **BTCPay network detection — VERIFIED.** Greenfield's `GET /api/v1/server/info`
   (`ServerInfoData`) has **no** network/chainType field (only `syncStatus[].chainHeight`
   etc.). Determine the network from a **network-encoding artifact**, not a field:
   - Primary: fetch a store on-chain receive address —
     `GET /api/v1/stores/{storeId}/payment-methods/{pmid}/wallet/address` →
     `OnChainWalletAddressData.address` — and classify by prefix: bech32 HRP `bc1…`=mainnet,
     `tb1…`=testnet/signet, `bcrt1…`=regtest (legacy base58 `1`/`3`=mainnet vs `m`/`n`/`2`=
     test/regtest).
   - Secondary: the on-chain payment method's `derivationScheme` (NBXplorer format) — xpub/
     ypub/zpub=mainnet, tpub/upub/vpub=testnet. (Fetching config needs
     `btcpay.store.canmodifystoresettings`.)
   - **Fail closed:** Lightning-only store / no address / unrecognized prefix → treat as
     mainnet → require master.
2. **Zaprite** — no non-mainnet mode assumed → scoped Zaprite-connect stays master-only;
   demo uses BTCPay. (Agreed.)
3. **Reconnect / rotate of an already-connected mainnet provider — always master-only.**
   (Strong yes — that's the exact attack.) Sandbox/regtest reconnect follows the §5 scoped
   rules; mainnet reconnect is never scoped.
4. **Packaging — à-la-carte `payment_providers:write`** (composes with `merchant-onboard`,
   avoids role sprawl), **not** a new fixed role. Implementation note: "composes with" means
   moving from one-role-per-key to **role + optional extra scopes per key** (or full per-key
   scope sets) — a schema addition (`scoped_api_keys` gains a scopes column, migration
   `0024`). Acceptable given no urgency; flagged so it's not a surprise at build time.

## 7. Design sketch (build)

- **Scope string**: add `"payment_providers:write"`. Granted per-key (à-la-carte, §6.4), never
  via a `:write` suffix match, never in `merchant-onboard`'s grant set.
- **Sandbox flag**: e.g. `KEYSAT_SANDBOX_MODE=1`, read at boot into `AppState`; surfaced
  read-only in `/v1/admin/tier`-style status + a prominent "SANDBOX" banner in the admin UI so
  a sandbox instance is never mistaken for production. **No setter endpoint of any kind.**
- **Gate helper**: replace `require_admin` on the connect handlers with
  `require_provider_connect(state, headers, target_network)`:
  - master → allow any network;
  - scoped w/ `payment_providers:write` → allow **iff** `state.sandbox_mode` **and**
    `target_network != mainnet`;
  - else 403.
  Resolve `target_network` (§6.1) **before** persisting anything.
- **Reconnect/disconnect**: mainnet reconnect always master-only (§6.3); disconnect on a
  production daemon stays master-only (denial-of-revenue, consistent with §5.1). In sandbox,
  both follow the scoped rule.
- **Audit**: every scoped connect writes an audit row with actor hash + resolved network +
  provider.

## 8. Migration / back-compat

- New scope string + gate helper + sandbox flag. Migration `0024` only for §6.4 (per-key extra
  scopes column on `scoped_api_keys`).
- Master-key automation unaffected; existing `merchant-onboard` keys unaffected (capability
  unchanged); existing keys default to no extra scopes.

## 9. Testing

- Scoped `payment_providers:write` key on a **sandbox** daemon: connect regtest BTCPay →
  allowed; connect mainnet BTCPay → 403; Lightning-only / unknown network → 403 (fail-closed).
- Same key on a **production** (non-sandbox) daemon: connect regtest → **403** (outer gate);
  proves §5.1.
- Sandbox flag is not flippable via API (assert no endpoint mutates it).
- Master key: connect any network → allowed.
- `merchant-onboard` without the extra scope → 403 on connect everywhere (proves no role widen).
- Mainnet reconnect/rotate → master-only even in sandbox.

## 10. Status

Shape **approved by both devs**: C (à-la-carte `payment_providers:write`) + D (network gate,
fail-closed) gated by E (sandbox flag as the outer gate, daemon-level only), BTCPay OAuth
preserved, B explicitly rejected. Build when it suits — Path 1 ships first.