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

package/repository/packages/provider-kit/schemas/gateway-config.schema.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://algorialabs.github.io/stellar-agent-services/schemas/provider-kit/gateway-config.schema.json",
+  "title": "Provider Kit gateway config",
+  "description": "Puts an existing HTTP API, in any language, behind Provider Standard v1: manifest, x402 payment, job recovery and capacity. Run it with `provider-kit serve --config <file>`. Values written \"env:NAME\" are read from the environment variable NAME, in the fields that say so. The gateway holds no Stellar secret key.",
+  "type": "object",
+  "required": ["baseUrl", "network", "payTo", "facilitator", "provider", "services"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "baseUrl": {
+      "description": "The public HTTPS URL job paths are under, such as https://api.example.com/agent. http://localhost only with dev. May be \"env:NAME\".",
+      "type": "string"
+    },
+    "network": { "enum": ["stellar:testnet", "stellar:pubnet"] },
+    "payTo": {
+      "description": "The G... or C... address that receives payments: public, never a secret key. Use the agent wallet of your 8004 registration [I3]. May be \"env:NAME\".",
+      "type": "string"
+    },
+    "facilitator": {
+      "description": "The x402 facilitator URL, such as https://x402.org/facilitator on testnet. May be \"env:NAME\".",
+      "type": "string"
+    },
+    "facilitatorHeaders": {
+      "description": "Headers sent to the facilitator, for one that wants an API key. Values may be \"env:NAME\".",
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "provider": {
+      "description": "Who you are, as the manifest shows it (§2.3).",
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "description": { "type": "string", "maxLength": 500 },
+        "homepage": { "type": "string" },
+        "agentId": { "description": "Your Stellar 8004 agent id, after `provider-kit launch` or `register`. May be \"env:NAME\": an unset or empty variable leaves it out, as before registering.", "type": ["integer", "string"] },
+        "termsUrl": { "type": "string" },
+        "dataUse": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": { "storesInputs": { "type": "boolean" }, "trainsOnInputs": { "type": "boolean" } }
+        }
+      }
+    },
+    "rpcUrl": {
+      "description": "The Soroban RPC the gateway reads the chain with, to decide payment_uncertain jobs and time on-success jobs by ledger. Default: the public RPC on testnet; pubnet has none, so set yours. May be \"env:NAME\".",
+      "type": "string"
+    },
+    "store": {
+      "description": "Where jobs are kept: a SQLite file path, relative to this config file (default ./jobs.sqlite), or \"memory\" for tests only. May be \"env:NAME\".",
+      "type": "string"
+    },
+    "listen": {
+      "description": "Where `serve` listens. Default port 8787 on 0.0.0.0. The PORT environment variable overrides the port.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "host": { "type": "string" }, "port": { "type": "integer", "minimum": 0, "maximum": 65535 } }
+    },
+    "maxTimeoutSeconds": { "description": "How long a signed payment is valid. Default 60.", "type": "integer", "minimum": 30, "maximum": 300 },
+    "settleTimeoutSeconds": { "description": "How long a settlement may take before the job is payment_uncertain. Default maxTimeoutSeconds + 30.", "type": "integer", "minimum": 1 },
+    "retentionSeconds": { "description": "How long finished jobs stay retrievable. Default 86400.", "type": "integer", "minimum": 3600 },
+    "manifestPath": { "description": "Default /.well-known/stellar-agent-services.json.", "type": "string", "pattern": "^/" },
+    "holdSeconds": { "description": "How long create-job waits before answering 202. Default 30.", "type": "integer", "minimum": 0, "maximum": 30 },
+    "runQueuedJobs": { "description": "Whether this process runs queued upfront jobs. Default true.", "type": "boolean" },
+    "leaseSeconds": { "type": "integer", "minimum": 3 },
+    "rateLimit": {
+      "description": "Per-caller limit on create-job (429). keyHeader names the header a trusted proxy sets to the caller's address.",
+      "type": "object",
+      "required": ["requests", "windowSeconds", "keyHeader"],
+      "additionalProperties": false,
+      "properties": {
+        "requests": { "type": "integer", "minimum": 1 },
+        "windowSeconds": { "type": "integer", "minimum": 1 },
+        "keyHeader": { "type": "string", "minLength": 1 }
+      }
+    },
+    "dev": { "description": "Allows http://localhost for baseUrl and the facilitator. Never in production.", "type": "boolean" },
+    "services": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 25,
+      "items": { "$ref": "#/$defs/service" }
+    }
+  },
+  "$defs": {
+    "service": {
+      "type": "object",
+      "required": ["name", "description", "price", "inputSchema", "outputSchema", "upstream"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$" },
+        "title": { "type": "string" },
+        "description": { "description": "What it does, when to use it, and its limits (§3.4).", "type": "string", "minLength": 1, "maxLength": 1000 },
+        "price": { "description": "USDC, as a decimal string such as \"0.05\".", "type": "string", "pattern": "^\\d+(\\.\\d{1,7})?$" },
+        "charge": { "enum": ["on-success", "upfront"] },
+        "expectedDurationSeconds": { "type": "integer", "minimum": 1 },
+        "timeoutSeconds": { "description": "Longest the upstream call may take. Default: twice expectedDurationSeconds, or 600.", "type": "integer", "minimum": 1 },
+        "inputSchema": { "description": "A JSON Schema object, or the path of a JSON file holding one, relative to this config file.", "type": ["object", "string"] },
+        "outputSchema": { "description": "A JSON Schema object, or the path of a JSON file holding one.", "type": ["object", "string"] },
+        "examples": {
+          "type": "array",
+          "maxItems": 5,
+          "items": {
+            "type": "object",
+            "required": ["input", "output"],
+            "additionalProperties": false,
+            "properties": { "input": { "type": "object" }, "output": { "type": "object" } }
+          }
+        },
+        "tags": { "type": "array", "maxItems": 10, "items": { "type": "string", "pattern": "^[a-z0-9-]{1,32}$" } },
+        "maxInputBytes": { "type": "integer", "minimum": 1, "maximum": 10485760 },
+        "capacity": {
+          "description": "What the upstream can take: calls at once, and how long a new job may wait (§5.8).",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "concurrency": { "type": "integer", "minimum": 1 },
+            "maxQueued": { "type": "integer", "minimum": 0 },
+            "maxQueueWaitSeconds": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "upstream": {
+          "type": "object",
+          "required": ["url"],
+          "additionalProperties": false,
+          "properties": {
+            "url": { "description": "Where the input is POSTed as JSON. May be \"env:NAME\".", "type": "string" },
+            "headers": {
+              "description": "Sent with every call, such as the upstream's own API key. Values may be \"env:NAME\".",
+              "type": "object",
+              "additionalProperties": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/repository/packages/verifier/README.md

@@ -0,0 +1,131 @@
+# @stellar-agent-services/verifier
+
+Checks a provider against [Provider Standard v1](../../docs/provider-standard.md) and turns the result into evidence
+anyone can check:
+
+1. **Checks C1–C7:** manifest, identity, payment challenge, paid call, recovery, hygiene and load. Each finding
+   cites a rule of the standard.
+2. **Verification receipt:** RFC 8785 canonical JSON, stored under its own SHA-256.
+3. **Badges:** SVGs drawn only from a receipt.
+4. **Validation Registry:** `validation_response` anchors the receipt's hash in the Stellar 8004 Validation
+   Registry.
+5. **Self-serve:** `verifier watch` does all of it by itself for every validation request that names the verifier.
+
+The full description, with every check and rule, is [docs/verification.md](../../docs/verification.md).
+
+## Use
+
+```bash
+npm install -g @stellar-agent-services/verifier   # or run each command as npx @stellar-agent-services/verifier
+
+# A provider testing itself, with no payment and no key:
+verifier check http://localhost:8787/.well-known/stellar-agent-services.json --dev
+
+# A verifier, answering every validation request that names it, until stopped:
+VERIFIER_PAYER_SECRET=S... verifier watch --source verifier --public-url https://verifier.example.com \
+  --data /var/lib/verifier
+
+# The same for one request, by hand: every check, paid by a dedicated testnet account, and a receipt.
+VERIFIER_PAYER_SECRET=S... verifier verify https://api.example.com/.well-known/stellar-agent-services.json \
+  --pay --validator G... --out evidence/receipts
+verifier publish evidence/receipts/<sha256>.json --request-hash <hex> --response-uri <https url> --source verifier
+verifier badge evidence/receipts/<sha256>.json --request-hash <hex>
+```
+
+```
+Provider Standard v1 check: http://localhost:8787/.well-known/stellar-agent-services.json
+  ✓ C1 Manifest
+  - C2 Identity: skipped, development mode: a loopback provider can't be registered
+  ✓ C3 Challenge
+  - C4 Paid call: skipped, no test payer: run verifier verify --pay
+  - C5 Recovery: skipped, no test payer: run verifier verify --pay
+  ✓ C6 Hygiene
+  ✓ C7 Load
+
+Level 1 (Described): score 33 of 100.
+Load (C7) passed: Load-safe.
+Every check that ran passed.
+```
+
+Exit codes: `0` every check that ran passed, `1` a check or the command failed, `2` a usage error. `--json` prints
+the report, or the receipt, on standard output. `watch` runs until SIGINT or SIGTERM, then exits `0`.
+
+The paid checks poll an uncertain job within their existing follow deadline, allowing the provider to reconcile
+it from the chain [J13]. They read the original job and never sign or send another payment while waiting [J11].
+Unresolved uncertainty is skipped and earns no paid check.
+
+As a library:
+
+```ts
+import { issueReceipt, localKeyPayer, verifyProvider, writeReceipt } from "@stellar-agent-services/verifier";
+
+const report = await verifyProvider({ manifestUrl, payer: localKeyPayer(process.env.VERIFIER_PAYER_SECRET!) });
+const receipt = issueReceipt(report, { validator: "G..." });
+const { path, sha256 } = await writeReceipt(receipt, "evidence/receipts");
+```
+
+`openWatcher()` is the engine of `verifier watch`: `tick()` runs one round, and `handle(request)` is its HTTP side,
+for any Fetch-API server.
+
+## Watch
+
+`verifier watch` answers validation requests with no hand-off. Every `--interval` (default 60 s) it reads the
+Validation Registry for new requests that name the `--source` key's address. For each one, it finds the manifest
+(the request document, which the agent's registration must agree with [I1], else the registration), runs every check
+with the test payer, serves the receipt at `<public-url>/receipts/<sha256>.json` with its badges, and publishes
+`validation_response` as `verifier publish` does. A provider that is not reachable yet is checked again with backoff
+for `--retry-for` hours (default 24), then answered with its failing result. The state is `<data>/state.json`, so a
+restart picks up where it stopped, and a request is never answered twice.
+
+| Path | What it serves |
+| --- | --- |
+| `/receipts/<sha256>.json` | The receipt, exactly as written: the `response_uri` on chain |
+| `/receipts/<sha256>.<badge>.svg` | Its badges |
+| `/requests/<request hash>.json` | Where a request stands, for its owner: `waiting`, `publishing`, `answered` or `refused`, and why |
+| `/healthz` | `ok`, or `degraded` with the verifier's own problems, such as a test payer to fund |
+
+**Deploying it.** A small server or VM is enough: Node.js 22.13 or later, the Stellar CLI holding the validator key
+(`stellar keys generate verifier --network testnet --fund`), and a persistent volume for `--data`. Put HTTPS in
+front of `--port` (default `$PORT`, or 8080) at `--public-url`, with a reverse proxy such as Caddy or the platform's
+TLS. Back the volume up and keep the URL stable: the chain links to the receipts in it. Keep at least `--max-spend`
+(1.00 USDC) in the test payer. Run one watcher per validator key, where it can reach only the public internet: it
+fetches URLs that agent owners chose. See
+[docs/verification.md](../../docs/verification.md#self-serve-verification-verifier-watch).
+
+## Keys
+
+| Key | Used for | Where it lives |
+| --- | --- | --- |
+| Test payer | C4, C5 and C7's paid part | `VERIFIER_PAYER_SECRET`: a dedicated testnet account holding a little USDC |
+| Validator | `validation_response` | The Stellar CLI keychain. `verifier publish --source <key>` and `verifier watch --source <key>` sign through it; the verifier never sees it. |
+
+The test payer pays only a provider whose manifest passed C1 and whose challenge matches it, at most 0.10 USDC for
+a job and 1.00 USDC in a run unless told otherwise, and never on pubnet without `--allow-pubnet`. The validator and
+the test payer are always different accounts.
+
+## Layout
+
+| Path | What it does |
+| --- | --- |
+| `src/verify.ts` | `verifyProvider()`: runs the checks, in order, and returns the report |
+| `src/checks/` | One module per check, C1–C7 |
+| `src/jobs.ts` | The job endpoints, called as a careful client calls them, and the job view checks (§5.5–§5.7) |
+| `src/http.ts` | The HTTP client for an untrusted provider: no redirects, deadlines, size limits, one origin |
+| `src/payments.ts` | The test payer and its limits |
+| `src/chain.ts` | Soroban RPC reads: the trustline, the test payer's balance, and the proofs that a payment did or did not settle |
+| `src/registry.ts` | Stellar 8004 reads: identity and validation records, and the requests that name a validator |
+| `src/receipt.ts`, `src/badges.ts`, `src/publish.ts` | Receipts, badges, and the Validation Registry response |
+| `src/requests.ts` | What a validation request asks to check: its document from the `validation_request` event, or the agent's registration [I1] |
+| `src/watch.ts` | `openWatcher()`: the engine of `verifier watch`, its retries and its HTTP side |
+| `src/watch-state.ts` | The watcher's state file and the lock on its data directory |
+| `src/cli/` | The `verifier` command; `cli/watch.ts` runs the watcher, `cli/serve.ts` serves it on Node's HTTP server |
+
+## Tests
+
+The tests run every check against the real Provider Kit in-process, with a facilitator that settles onto a fake
+Soroban chain and a test payer that signs real payments offline. A conforming provider must pass every check; for
+each rule, a provider made to break it must fail with that rule's id.
+
+The watcher's tests (`test/watch.test.ts`, `test/support/watch.ts`) add a fake Validation Registry with its request
+events, a fake Stellar CLI that records `validation_response`, a fetch that reaches the watcher's own HTTP side at its
+public URL, and a clock that jumps ahead hours. They cover retries, refusals, restarts and never answering twice.

package/repository/plugins/stellar-agent-services/README.md

@@ -0,0 +1,31 @@
+# stellar-agent-services plugin for Claude Code
+
+Skills that teach a coding agent to build on [Provider Standard v1](../../docs/provider-standard.md): paid AI
+services on Stellar, paid per job in USDC through x402.
+
+```text
+/plugin marketplace add AlgoriaLabs/stellar-agent-services
+/plugin install stellar-agent-services@stellar-agent-services
+```
+
+| Skill | Use it to |
+| --- | --- |
+| [`build-paid-service`](skills/build-paid-service/SKILL.md) | Build a new paid service in TypeScript with the Provider Kit |
+| [`wrap-existing-api`](skills/wrap-existing-api/SKILL.md) | Put an existing HTTP API, in any language, behind payments with the gateway and a JSON config |
+| [`implement-standard`](skills/implement-standard/SKILL.md) | Implement the provider side natively in another language |
+| [`build-payment-client`](skills/build-payment-client/SKILL.md) | Build an agent, wallet or app that pays providers, or a wallet adapter for the payment client |
+| [`verify-provider`](skills/verify-provider/SKILL.md) | Check a provider (C1–C7), fix failing rules, register on 8004 and get verified |
+
+The skills load when a task matches, and point to the references in this repository. They are plain Markdown, so
+agents without plugin support can read them directly. They start on testnet, with test money. Mainnet (real USDC)
+needs `--network mainnet` and a facilitator API key, and an agent never pays on mainnet unless the user asked.
+
+The skills use the packages from npm. For spec lookups, manifest validation and provider checks, also add the
+[MCP server](../../packages/dev-mcp):
+
+```bash
+claude mcp add stellar-agent-services -- npx -y @stellar-agent-services/dev-mcp
+```
+
+When you change a skill, keep it short. It routes to the reference documents and never restates the spec in
+competing words. The spec wins.