spendctl 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,83 @@
+spendctl Proprietary Software License
+
+Copyright (c) 2026 Mirai Studio, Inc. (株式会社みらいスタジオ), Tokyo, Japan.
+All rights reserved.
+
+This software and its documentation (the "Software") are licensed, not sold.
+By installing or running the Software you agree to these terms. If you do not
+agree, do not install or run it.
+
+1. Grant. Subject to these terms and to the spendctl Terms of Service
+   (https://spendctl.dev/terms), Mirai Studio grants you a non-exclusive,
+   non-transferable, non-sublicensable, revocable licence to install and run
+   the Software, in the form distributed by Mirai Studio (for example through
+   the npm registry or a container image), on systems you control, solely to
+   use the spendctl service within the limits of your plan.
+
+2. Restrictions. Except as expressly permitted by Mirai Studio in writing or
+   by applicable law notwithstanding this restriction, you may not:
+   (a) copy, modify, translate, adapt or create derivative works of the
+       Software;
+   (b) distribute, publish, sublicense, sell, rent, lease, lend or otherwise
+       make the Software available to third parties;
+   (c) reverse engineer, decompile, disassemble or otherwise attempt to derive
+       the source code of the Software;
+   (d) remove, obscure or alter any proprietary notice in the Software;
+   (e) circumvent or disable licence keys, plan limits, usage metering or
+       security measures in the Software;
+   (f) use the Software to build or train a product that competes with
+       spendctl.
+
+3. Third-party components. The Software incorporates third-party components
+   under their own licences. Their notices are provided with the distributed
+   package (THIRD_PARTY_NOTICES). Nothing in this licence limits your rights
+   under those licences. The spendctl client SDKs are separately licensed
+   under the Apache License 2.0 (https://github.com/miraistudio/spendctl-sdk).
+
+4. Ownership. The Software is protected by copyright and other laws. Mirai
+   Studio and its licensors retain all right, title and interest in the
+   Software. No rights are granted except those expressly stated here.
+
+5. Your data and keys. The Software signs payments with a wallet you control
+   and keeps its ledger on systems you control. The Software may send
+   licence-validation and billing metadata to Mirai Studio as described in
+   the documentation; it does not send private keys, signed payment
+   authorizations, request bodies or response bodies to Mirai Studio.
+
+6. Feedback. If you send suggestions about the Software, Mirai Studio may use
+   them without obligation to you.
+
+7. Term and termination. This licence remains in effect until terminated. It
+   terminates automatically if you breach these terms or if your plan ends.
+   On termination you must stop using and delete the Software. Sections 2,
+   4, 8, 9 and 10 survive termination.
+
+8. Disclaimer of warranty. THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE"
+   WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND
+   NON-INFRINGEMENT. Spend policies are a safeguard, not a guarantee: Mirai
+   Studio does not warrant that the Software will prevent every unauthorised,
+   unintended or erroneous payment, that sellers or facilitators will behave
+   correctly, or that any blockchain or payment network will be available.
+   You remain responsible for the policies you configure and for the wallets
+   you connect.
+
+9. Limitation of liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, MIRAI
+   STUDIO SHALL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
+   CONSEQUENTIAL OR PUNITIVE DAMAGES, OR FOR ANY LOSS OF FUNDS, PROFITS, DATA
+   OR GOODWILL, ARISING OUT OF OR RELATED TO THE SOFTWARE, EVEN IF ADVISED OF
+   THE POSSIBILITY. MIRAI STUDIO'S TOTAL LIABILITY UNDER THIS LICENCE SHALL
+   NOT EXCEED THE AMOUNT YOU PAID FOR THE SPENDCTL SERVICE IN THE TWELVE
+   MONTHS BEFORE THE CLAIM. Nothing here limits liability that cannot be
+   limited under applicable law.
+
+10. Governing law. This licence is governed by the laws of Japan. The Tokyo
+    District Court has exclusive jurisdiction in the first instance over any
+    dispute arising from it.
+
+11. Export and sanctions. You may not use the Software in violation of
+    applicable export-control or sanctions laws.
+
+12. Entire agreement. This licence and the Terms of Service are the entire
+    agreement about the Software. If any provision is unenforceable, the rest
+    remains in effect.

package/README.md

@@ -1,3 +1,221 @@
-# Temporary Holding Version
+<p align="center"><img src="https://spendctl.dev/demo.gif" alt="spendctl demo: an agent pays for three API calls, hits its daily budget, waits for a human, gets approved, and the receipts are exported" width="860"></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://spendctl.dev/brand/spendctl-lockup-dark.svg"><img src="https://spendctl.dev/brand/spendctl-lockup-light.svg" alt="spendctl" height="44"></picture></h1>
+
+<p align="center"><b>A corporate card and expense policy for your AI agents.</b><br>
+spendctl is the spend-policy control plane for AI agents: budgets, approvals, receipts and chain tracing across every wallet and every HTTP&nbsp;402 protocol — enforced in a sidecar you run, never by holding your keys or funds.</p>
+
+<p align="center"><a href="https://spendctl.dev/ja/">日本語</a> · <a href="https://spendctl.dev/zh-cn/">简体中文</a> · <a href="https://spendctl.dev/docs">Docs</a> · <a href="https://spendctl.dev/#pricing">Pricing</a></p>
+
+---
+
+- **What it is:** a local sidecar your agents send HTTP requests through. When a seller answers `402 Payment Required` ([x402](https://www.x402.org), [MPP](https://mpp.dev)), spendctl checks the agent's policy, asks a human if needed, signs with *your* wallet, and writes the receipt to a ledger.
+- **Why it exists:** agents can now pay per request, but the protocols leave buyer-side budgets to "the implementation", the SDK guardrails run inside the agent's own process, and wallet vendors only govern the wallet they hold. Per-agent caps are free everywhere; what is missing is one policy, one approval flow and one ledger across all of them.
+- **What you get:** per-agent budgets (per request / hour / day / week / month), host allowlists, recipient pinning, approval thresholds, price-jump and first-payment checks, agent→agent chain limits, dry-run, CSV/JSON export, MCP tools, a dashboard. Non-custodial: signing happens in the sidecar you run, against a wallet you own — a Coinbase CDP server wallet or your own key. spendctl never holds keys or funds.
+
+## Why a sidecar
+
+> "Hard limits (validation, approval gates) and anything else that comes up mid-conversation (e.g. memory lookup) move into the **tools**."
+> — Anthropic, [*Building agents: When to fold subagents into your main agent loop*](https://claude.com/resources/articles/building-agents-when-to-fold-subagents-into-your-main-agent-loop)
+
+spendctl is that tool for money. **The agent can be talked into asking. It cannot be talked into paying.** The key, the policy and the ledger live in a separate process the model cannot edit; refusals come back as plain sentences the model can read.
+
+Where spendctl fits:
+
+| | Where it runs | Per-payment cap | Time-window budgets | Human approval | Exportable ledger | Host/endpoint budgets + price pinning | Your wallet, your sidecar (non-custodial) | Wallet- & protocol-neutral |
+|---|---|---|---|---|---|---|---|---|
+| x402 SDK `spendControls` (`@x402/core` 2.28) | inside the agent | ✓ (`$1` default) | — | hook only | — | — | your wallet, in-process | x402 only |
+| CDP SDK x402 spend controls (≥ 1.53) | inside the agent | ✓ | ✓ rolling, in-memory by default | — | — | — | CDP wallet, in-process | CDP + x402 |
+| Wallet-bundled caps (Coinbase Agentic Wallet, AWS AgentCore payments) | wallet UI / Bedrock | ✓ free | per session | — | some | — | one or two wallet providers | their rails |
+| Wallet policy engines (Privy, Turnkey, Circle, CDP Policies…) | wallet vendor | ✓ | some | some | some | — | their wallet | own keys only |
+| Hosted agent-payment platforms (Catena, Locus, xpay, Nevermined…) | their cloud | ✓ | ✓ | some | ✓ | some | their wallet or proxy | their rails |
+| **spendctl** | **your sidecar** | ✓ | ✓ per agent | ✓ CLI / webhook / link | ✓ CSV / JSON | ✓ + payee pinning, price-jump | ✓ any signer you already have | ✓ any EVM signer; x402 v1/v2, MPP |
+
+Hosted platforms govern the wallet they hold; spendctl governs the wallets you already have — one policy, one approval flow and one ledger in front of whichever wallet and payment protocol your agents meet. The x402 v2 spec lists *"Client-side budget management"* as out of scope, and builders are hitting it: [x402#3703](https://github.com/x402-foundation/x402/issues/3703) (a cumulative budget can't be built correctly on the client hooks), [x402#3866](https://github.com/x402-foundation/x402/issues/3866) (the official client paid a server that inflated its price ×10).
+
+## Quickstart (5 minutes, no keys, no chain)
+
+Requires Node.js 22.13+ (or Bun 1.1+).
+
+```bash
+mkdir spend-demo && cd spend-demo
+npx spendctl init                 # writes spendctl.yaml + .spendctl/ (git-ignored)
+npx spendctl mock                 # terminal 1: mock facilitator + two paid APIs
+npx spendctl start                # terminal 2: the sidecar on 127.0.0.1:8402
+```
+
+In a third terminal, be the agent:
+
+```bash
+npx spendctl fetch "http://localhost:4021/weather?city=Tokyo" --agent researcher
+# ✔ 200 paid $0.01
+npx spendctl fetch "http://localhost:4021/weather?city=Tokyo" --agent researcher   # 2nd, 3rd …
+# the 4th call exceeds the $0.03/day budget → the request is held for a human:
+npx spendctl pending
+npx spendctl approve --latest
+npx spendctl ledger
+npx spendctl export --format csv --out receipts.csv
+```
+
+`spendctl mock` never touches a chain: its facilitator verifies real EIP-712 signatures and fakes settlement. When you're ready for testnet money, see [Real payments](#real-payments-base-sepolia). Full walkthrough: [spendctl.dev/docs/quickstart](https://spendctl.dev/docs/quickstart/).
+
+## The policy
+
+```yaml
+# spendctl.yaml
+version: 1
+signer:
+  type: cdp                      # Coinbase CDP server wallet: keys stay in CDP
+
+approvals:
+  timeout: 10m                   # nobody answered → denied
+  webhooks:
+    - url: https://hooks.slack.com/services/T000/B000/XXXX
+      format: slack              # json | slack | discord (HMAC-signed with secretEnv)
+
+defaults:
+  networks: ["eip155:84532"]     # Base Sepolia only until you opt in
+  assets: ["USDC"]
+  maxChainDepth: 3               # agent → agent → agent, then stop
+  priceJumpFactor: 3             # >3× the last price paid for an endpoint → human
+  firstPaymentMax: "0.05"        # first payment to a new recipient above this → human
+
+agents:
+  researcher:
+    budget: { perRequest: "0.05", daily: "1.00", monthly: "20.00" }
+    onBudgetExceeded: approve    # deny | approve
+    requireApprovalAbove: "0.50"
+    allow: ["api.weather.dev", "*.search.dev/v1/*"]
+    deny: ["*.casino.example"]
+    payTo:
+      "api.weather.dev": ["0x209693Bc6afc0C5328bA36FaF03C514EF312287C"]   # refuse recipient swaps
+```
+
+Every rule fails closed: unknown agent, unknown asset, unsupported scheme or flow → denied, with a reason.
+
+## How it works
+
+```mermaid
+sequenceDiagram
+    participant A as Agent (no keys)
+    participant S as spendctl sidecar
+    participant H as Human
+    participant API as Paid API
+    A->>S: GET https://api.weather.dev/forecast
+    S->>API: GET /forecast
+    API-->>S: 402 + payment requirements (x402 v1/v2 or MPP)
+    S->>S: policy: allowlist, budgets, payee, price, chain depth
+    alt over a limit with onBudgetExceeded: approve
+        S->>H: webhook / CLI / review link
+        H->>S: spendctl approve apr_…
+    end
+    S->>S: reserve budget (SQLite BEGIN IMMEDIATE), sign once
+    S->>API: GET /forecast + payment header
+    API-->>S: 200 + settlement (tx hash)
+    S-->>A: 200 response + x-spendctl-* headers
+```
+
+The payment path stays in your network. Pro and Team will sync policies, approvals and ledgers to the spendctl control plane (in development); there is no round trip to us on the payment path, and the hosted service never relays a signature.
+
+## What is guaranteed
+
+Each rule has an end-to-end scenario that runs real HTTP servers (mock sellers, mock facilitator, sidecar). Every scenario runs **twice** on every CI run.
+
+| # | Rule |
+|---|---|
+| S01 | A payment inside every limit is signed once, settled, and recorded with its tx hash. |
+| S02 | Spending exactly up to the daily budget is allowed. |
+| S03 | A payment that would exceed a budget is never signed. |
+| S04 | Over-budget spend with `onBudgetExceeded: approve` waits for a human and pays only after approval. |
+| S05 | If nobody approves in time, the payment is denied. |
+| S06 | Hosts outside the allowlist are never paid. |
+| S07 | When a recipient is pinned for a host, a 402 naming another recipient is refused. |
+| S08 | A seller that suddenly inflates its price (×10, as in x402#3866) needs a human before it is paid. |
+| S09 | An agent cannot attach or replay a payment header itself; only spendctl signs. |
+| S10 | A retried request with the same `Idempotency-Key` is not paid twice. |
+| S11 | Payments deeper than `maxChainDepth` in an agent→agent chain are refused; parents are recorded. |
+| S12 | When settlement fails, spendctl never retries a signed payment and stops paying that host (circuit breaker). |
+| S13 | A payment the seller could not settle does not consume budget. |
+| S14 | Concurrent requests can never overspend a budget, not even by one payment. |
+| S15 | Dry-run records the decision and never signs. |
+| S16 | An agent cannot approve its own payment; approvals need the admin token. |
+| S17 | Agents that are not in the policy cannot spend. |
+| S18 | Only allowed networks and assets are paid; the cheapest acceptable option is chosen. |
+| S19 | Schemes spendctl cannot budget safely (e.g. `upto`) are refused with a readable reason. |
+
+## Integrations
+
+| How your agent talks to spendctl | Use it when |
+|---|---|
+| **Gateway URL** — `http://127.0.0.1:8402/https://api.example.com/path` + `X-Spendctl-Agent` | any language, any HTTP client |
+| **`wrapFetch()`** from `@spendctl/client` (Apache-2.0) | TypeScript/JavaScript agents (zero dependencies) |
+| **MCP server** — `spendctl mcp` (tools `pay`, `check_budget`, `list_receipts`) | Claude Code, Claude Desktop, Cursor, any MCP client |
+| **`spendctl run --agent A -- <cmd>`** — sets `HTTP_PROXY` | plain-HTTP tools; HTTPS is tunnelled unpaid (use the gateway for paid HTTPS) |
+
+Framework examples (Claude Agent SDK, OpenAI Agents SDK, LangGraph), typechecked against the real SDKs: [spendctl.dev/docs/integrations](https://spendctl.dev/docs/integrations/).
+
+```ts
+import { wrapFetch, readRefusal } from "@spendctl/client";
+
+const pay = wrapFetch({ agent: "researcher" });        // talks to the sidecar, holds no keys
+const res = await pay("https://api.weather.dev/forecast?city=Tokyo");
+const refusal = await readRefusal(res);                 // { error, message, approval?, reasons }
+```
+
+MCP (Claude Code):
+
+```bash
+claude mcp add spendctl -e SPENDCTL_AGENT=researcher -- npx spendctl mcp
+```
+
+Protocols: **x402 v1 and v2** (`exact` on EVM — Base, Base Sepolia, any EIP-3009 token), **MPP** (`charge` intent via a pluggable credential provider; parsing, policy and receipts today, no live MPP payment yet).
+
+## Real payments (Base Sepolia)
+
+```bash
+npx spendctl init --signer cdp --force   # then fill .env (see .env.example)
+npx spendctl wallet fund                 # 1 testnet USDC from the CDP faucet
+npx spendctl start
+```
+
+The CDP server wallet signs EIP-712 authorizations; the private key never exists in your process. A live run against the official `@x402/hono` middleware and the public x402.org facilitator is documented at [spendctl.dev/docs/real-payments](https://spendctl.dev/docs/real-payments/) ([tx on BaseScan](https://sepolia.basescan.org/tx/0x40d06e55d7d516080593b9f3a62e255edaca17f69ec64a472e0e6402077f9124)).
+
+## Commands
+
+```
+spendctl init | start [--dry-run] | mock
+spendctl fetch <url> --agent A [--dry-run] | run --agent A -- <cmd> | mcp | token <agent>
+spendctl pending | approve <id>|--latest|--all | deny <id>
+spendctl budget | ledger | export --format csv|json | trace <id> | resolve <id> --settled|--failed
+spendctl dashboard [--open] | wallet [address|fund] | license [set <key> | remove]
+```
+
+## Security model
+
+- Agents never hold keys or the admin token. Approvals require the admin token (CLI, dashboard) or an HMAC-bound review link that only acts on POST.
+- Budgets are reserved inside SQLite `BEGIN IMMEDIATE` transactions before signing; failed settlements release them; unknown outcomes count until reconciled.
+- The ledger stores no headers or bodies and drops query strings.
+- The sidecar binds to `127.0.0.1`. Run agents as a different OS user (or container) if they have shell access, so they can't read `.spendctl/admin.token`.
+
+Full security model and threat notes: [spendctl.dev/docs/security](https://spendctl.dev/docs/security/). Report vulnerabilities to security@spendctl.dev.
+
+## Pricing
+
+Every enforcement feature above is in the Free tier. Paid tiers add the spendctl control plane — policy sync across sidecars, pooled budgets, Slack/Discord approvals, SSO/RBAC, hosted ledger retention and a fleet dashboard — still non-custodial. The control plane is in development; Pro and Team are founding pre-orders until it ships. The sidecar enforces the Free limits itself — 2 agents, checked at `spendctl start`, and 1,000 governed payments per month; refusals and the mock sandbox never count — and reads a licence key for Pro and Team ([how it works](https://spendctl.dev/docs/plans/)).
+
+| Tier | Price | Includes |
+|---|---|---|
+| **Free** | $0, no card | 2 agents, 1 policy, 1,000 governed payments/month, local ledger + CSV/JSON export, 7-day hosted ledger copy, CLI/webhook approvals, 1 seat, local sandbox |
+| **Pro** | $29/mo (founding $19) | 10 agents, 25k events/month, 90-day hosted ledger, Slack/Discord approvals, scheduled exports + accounting templates, 3 seats |
+| **Team** | $249/mo (founding $149) | unlimited agents, 500k events/month, 1-year immutable ledger, SSO/RBAC, pooled budgets, chain trace across sidecars, policy-as-code CI, region pinning (US/EU/JP) |
+| **Enterprise** | contact us | SIEM export, SCIM, custom retention (up to 7 years), private control plane, four-eyes approvals, SLA |
+
+Overage $5 per 100k events (Pro, Team); 14-day Team trial without a card. Founding members: the first 100, price locked for 12 months from GA, full refund if GA slips past 2027-03-31. No percentage of spend, ever. [Join the waitlist →](https://spendctl.dev/#pricing)
+
+## Status
+
+v0.1 — early. Tested: unit + integration (57), golden scenarios (19 × 2), one live Base Sepolia payment. Not yet: Solana signing, `upto`/`batch-settlement` schemes, live MPP payments, HTTPS interception for `HTTP_PROXY` mode, and the control plane (in development). Docs: [spendctl.dev/docs](https://spendctl.dev/docs).
+
+## License
+
+spendctl — the sidecar, CLI and MCP server published on npm — is proprietary software, distributed as bundled JavaScript under its own licence terms; there is no public source repository for it. The thin client `@spendctl/client` is Apache-2.0 and lives at [github.com/miraistudio/spendctl-sdk](https://github.com/miraistudio/spendctl-sdk). © Mirai Studio, Inc. (株式会社みらいスタジオ), Tokyo.