diff --git a/agent-payment-connect-scope.md b/agent-payment-connect-scope.md new file mode 100644 index 0000000..b90af36 --- /dev/null +++ b/agent-payment-connect-scope.md @@ -0,0 +1,156 @@ +# 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.