@stellar-agent-services/dev-mcp 0.0.0-stage → 0.1.0

package/repository/README.md

@@ -0,0 +1,78 @@
+# Stellar Agent Services
+
+Phase 2 of [Stellar Agent Search](https://github.com/berkingurcan/stellar-agent-search). It makes it easy for
+developers to offer paid AI services on Stellar, and easy for users to find, hire and pay them safely.
+
+Stellar Agent Search finds and evaluates agents (read-only, keyless). This repository adds the provider and
+payment side:
+
+| Package | Purpose |
+| --- | --- |
+| [`packages/protocol`](packages/protocol) | Provider Standard v1 as code (manifest, jobs, receipts) |
+| [`packages/provider-kit`](packages/provider-kit) | Turn a function, or an existing API in any language (gateway mode), into a paid service: pricing, x402 USDC payments, Job Recovery, capacity and queuing |
+| [`packages/payment-client`](packages/payment-client) | Buyer side: approval, spending controls, payment, recovery (proof of concept) |
+| [`packages/verifier`](packages/verifier) | Checks a provider against the standard (C1–C7), issues verification receipts and badges, publishes to the Stellar 8004 Validation Registry. `verifier watch` answers validation requests by itself. |
+| [`packages/dev-mcp`](packages/dev-mcp) | MCP server for coding agents: spec rules, docs, manifest validation, unpaid provider checks. It never pays. |
+| [`packages/create-stellar-service`](packages/create-stellar-service) | `npm create stellar-service`: a new project (an existing API, a TypeScript or a Python service), ready to run, try and deploy |
+| [`apps/wallet`](apps/wallet) | Web page where a person approves and pays a service (testnet) |
+| [`examples/paid-service`](examples/paid-service) | Sample provider and template for pilot providers |
+| [`examples/python-upstream`](examples/python-upstream) | An existing Python API made a paid service with gateway mode |
+
+**Status:** Week 3 of the plan. A paid call works end to end, from a provider (library or gateway mode, with a
+durable job queue) to the payment client's CLI and web page. Job Recovery is complete in code: providers decide
+uncertain payments from on-chain data ([docs/job-recovery.md](docs/job-recovery.md)). The verifier runs every check
+(C1–C7), proves payments on chain, and issues receipts, badges and Validation Registry responses
+([docs/verification.md](docs/verification.md)). The plan is in
+[IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md). Development runs on Stellar **testnet**.
+
+To offer a service, start with [`npm create stellar-service`](packages/create-stellar-service), then:
+
+```bash
+npm create stellar-service my-service
+cd my-service
+npm run dev       # runs it, paid to a throwaway testnet account: no wallet needed yet
+npm run try       # pays for one call with test money
+npm run launch    # goes live: one approval in your wallet registers and verifies it, then Fly.io
+npm run status    # where it stands, and what to run next
+```
+
+The [provider setup guide](docs/provider-setup-guide.md) explains each step.
+
+**The standard in short:** [for people](docs/standard/README.md) and [for AI coding agents](docs/standard/README-AI.md).
+The full text is [docs/provider-standard.md](docs/provider-standard.md).
+
+## For AI coding agents
+
+- [AGENTS.md](AGENTS.md) picks a path (new service, existing API, another language, paying client, verification,
+  contributing) and names its reference, rules and definition of done. `CLAUDE.md` points to it.
+- [llms.txt](llms.txt) indexes every document, and [llms-full.txt](llms-full.txt) holds them all in one file.
+- The [Claude Code plugin](plugins/stellar-agent-services) adds a skill for each path:
+  `/plugin marketplace add AlgoriaLabs/stellar-agent-services`.
+- The [MCP server](packages/dev-mcp) answers spec questions and checks manifests and providers.
+
+## Compatibility
+
+We stay compatible with ERC-8126 (agent verification) and ERC-8196 (agent authenticated wallet). See
+[docs/erc-compatibility.md](docs/erc-compatibility.md). Copies of both specs are in [docs/references/](docs/references).
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+
+Requires Node 22.13 or later (`.node-version` pins 24).
+
+## Security
+
+See [SECURITY.md](SECURITY.md). In short:
+
+- discovery and provider servers hold no keys
+- only the payment client signs, once, after explicit approval
+- nobody pays twice for one job
+
+## License
+
+MIT

package/repository/SECURITY.md

@@ -0,0 +1,22 @@
+# Security
+
+These boundaries apply to every package in this repository.
+
+1. **Discovery holds no keys.** `stellar-agent-search` stays read-only and keyless. It may import only the
+   dependency-free `protocol` package.
+2. **Provider runtimes hold no keys.** A provider server knows only its `payTo` public address. Owner
+   operations are signed in the owner's own wallet, on an approval page the CLI serves on 127.0.0.1 behind a
+   one-time token, or with `--source` through the Stellar CLI keychain; never through environment variables. The
+   CLI checks that a signed transaction is the one it built before sending it. In gateway mode, the only
+   credential is the upstream API's own key, if it has one, and never a Stellar secret key. The only keys the CLI
+   makes are throwaway testnet ones, held in memory and never written: `provider-kit try`'s payer, and the payout
+   account `provider-kit dev` makes while `PAY_TO` is empty. That key signs the account's USDC trustline and is
+   dropped; the provider gets only the public address.
+3. **Only the payment client signs payments**, once per approved job, after the user approves the exact
+   price, recipient, asset and network.
+4. **Never pay twice.** The job identity is fixed before payment. Recovery never re-sends a payment
+   credential, and an uncertain settlement is never re-charged.
+5. **Fail closed.** Unknown or unverifiable states stop the flow.
+6. **One network per flow.** Testnet and mainnet are never mixed in one run.
+
+To report a vulnerability, contact the maintainers privately rather than opening a public issue.

package/repository/apps/wallet/README.md

@@ -0,0 +1,78 @@
+# Agent Wallet (web approval page)
+
+The page where a person sees the exact payment and approves it before anything is paid: the "web app" surface
+of the payment client ([docs/payment-client.md](../../docs/payment-client.md)). It is a static page with no
+backend. Every safety step runs in [`packages/payment-client`](../../packages/payment-client), in the browser.
+
+**Status: minimal page (Week 1), Stellar testnet only.** It creates a test wallet, loads any Provider Standard v1
+provider, builds the request form from the service's input schema, shows the approval screen, pays once, confirms
+the transfer on chain and recovers lost jobs.
+
+## Run it
+
+```bash
+npm install && npm run build                                  # builds the packages the page uses
+
+# The sample provider (any public G... address with a USDC trustline receives the payments)
+PAY_TO=G... node examples/paid-service/dist/server.js
+
+# The page, on http://localhost:5173
+npm run dev --workspace @stellar-agent-services/wallet
+```
+
+Then:
+
+1. **Create test wallet.** This makes a key in the browser, gets test XLM from Friendbot and buys 5 test USDC on
+   the testnet exchange.
+2. **Use localhost:8787.** This loads the sample provider's manifest.
+3. **Pick a service and review the payment.** The approval screen shows the price, the full payee address, when you
+   are charged, and the challenge and spending-limit checks.
+4. **Approve.** The page follows the payment and shows "Paid" only once the `transfer` on chain matches what you
+   approved.
+
+To show spending control, set the limit per payment to 0.01 and review `delayed-report` (0.02): the payment is
+blocked before anything is signed.
+
+For the Job Recovery demo, start the provider with `DRILL_LOSE_RESPONSE=1 REPORT_DELAY_SECONDS=10` and pay
+`delayed-report`. The page says it can't tell whether the payment went through. **Recover job** then collects
+the result with no second payment.
+
+`npm run build --workspace @stellar-agent-services/wallet` writes the static page to `apps/wallet/dist`.
+
+## How it keeps payments safe
+
+- **Core.** The page never decides whether something is paid. It calls `quote()`, `pay()`, `decline()` and
+  `recover()` on the core, and the core runs every check (docs/payment-client.md, "One payment, step by step").
+- **Decline by default.** Closing the approval screen in any way declines: the Decline button, the close button,
+  or Escape. The Decline button has the focus, so a stray Enter never pays.
+- **Journal.** The journal and job tokens live in IndexedDB (`@stellar-agent-services/payment-client/browser`).
+  - Writes use strict durability, so `sending` is on disk before the paid request goes out.
+  - The page runs in one tab at a time (a Web Lock), so the journal has one writer.
+  - If the journal can't be opened, nothing can be paid.
+- **Key.** The test wallet's key is in this browser's site storage. That is fine for test money, never for real
+  money: real wallets will plug in as signers (Stellar Wallets Kit, passkey accounts).
+- **No outside code.** The page loads no third-party code, and a Content Security Policy blocks inline and outside
+  scripts. `'unsafe-eval'` is allowed for Ajv, which compiles the manifest schema.
+- **Local providers.** `http://localhost` providers are accepted only while the page itself runs on localhost, as
+  with `stellar-pay --dev`.
+
+## Files
+
+| File | Contents |
+| --- | --- |
+| `src/lib/agent-wallet.svelte.ts` | The page's state and actions on top of the core; follows the journal for progress |
+| `src/lib/schema-form.ts` | A service's `inputSchema` → form fields; anything else gets a JSON editor |
+| `src/lib/jobs.ts` | Each job's state from the journal, for Recent payments |
+| `src/lib/stellar.ts` | Test wallet balances and funding (Horizon, Friendbot, testnet exchange) |
+| `src/lib/storage.ts` | The test wallet, the spending policy and service titles in site storage |
+| `src/lib/format.ts` | Amounts, addresses and times for people |
+| `src/components/` | `PayFlow` (provider, service, request), `ApprovalDialog`, `PaymentCard`, `WalletCard`, `LimitsCard`, `RecentPayments` |
+
+## Not done yet
+
+- Signers other than the test key: Stellar Wallets Kit (Freighter and others) and passkey accounts.
+- Approval links from the MCP server, so an agent above its budget can send its human here.
+- Verification badges on the approval screen (they need the verifier).
+- Paying without a prompt below an amount (`autoApproveUpTo`). The page always asks.
+- Precompiling the manifest validator, so the CSP can drop `'unsafe-eval'`.
+- Hosting: any static host works, and it should send `frame-ancestors 'none'` as a header.