Add sandbox flag + per-key à-la-carte scopes (payment-connect foundation)

Foundation for agent-delegable payment-provider connect
(plans/agent-payment-connect-scope.md, slices 1-2 of 5). Not yet wired to any
connect endpoint — the gate (require_provider_connect + BTCPay non-mainnet
network check) is a follow-up.

- Config.sandbox_mode from KEYSAT_SANDBOX_MODE (daemon-level, never settable
  via any API); surfaced read-only in /v1/admin/tier as "sandbox".
- Migration 0024: additive scoped_api_keys.extra_scopes column (JSON array).
- Per-key à-la-carte scopes: require_scope grants via role OR a key's
  extra_scopes; GRANTABLE_EXTRA_SCOPES allowlist (payment_providers:write
  only), validated on create and echoed in create/list responses.
- payment_providers:write is in NO role: grants() carves the à-la-carte set
  out of full-admin's wildcard, so even a scoped full-admin key can't reach
  it through its role — only a per-key grant does. extra_scopes parsing
  fails closed (NULL/malformed -> no grant).
- Tests: invariant (no role grants the à-la-carte set), fail-closed parsing,
  create/list round-trip, reject ungrantable scope. Suite green: lib 13, api 59.
This commit is contained in:
Grant
2026-06-16 21:16:20 -05:00
parent 069cf1eb40
commit 3afac078d4
8 changed files with 247 additions and 22 deletions
@@ -0,0 +1,13 @@
-- Migration 0024: per-key à-la-carte scopes on scoped API keys.
--
-- Roles (read-only | license-issuer | support | merchant-onboard | full-admin)
-- expand to a fixed scope set. Some capabilities are too sensitive to bake into
-- any role but still need to be grantable to a SPECIFIC key. The first is
-- `payment_providers:write` — agent-delegated payment-provider connect, itself
-- gated further by the daemon sandbox flag + a non-mainnet network check (see
-- plans/agent-payment-connect-scope.md).
--
-- `extra_scopes` holds a JSON array of additional scope strings granted to THIS
-- key on top of its role. NULL / absent = role scopes only (every existing key),
-- so this is a pure additive column — no table rebuild.
ALTER TABLE scoped_api_keys ADD COLUMN extra_scopes TEXT;