@forum-labs/payfetch 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forum Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,467 @@
+# payfetch
+
+payfetch lets an AI agent fetch a URL and, when the server answers HTTP 402 (the
+x402 payment protocol), pay for it automatically, but only within a spending policy
+you control. It is non-custodial: you bring your own wallet, the key stays on your
+machine, and no MCP tool can raise the limits. It ships as a local stdio MCP server
+with a small library and CLI alongside it.
+
+The reference x402 clients pay whatever a 402 asks for. payfetch is the opposite:
+the policy and safety surface is the point. Per-call, per-day, and per-host spend
+caps; host allow and deny lists; a human-approval threshold; optional pre-payment
+trust and safety checks; and an append-only local receipt for every attempt,
+whether it paid, was denied, was a dry run, or failed.
+
+- Website: https://forum-labs.com
+- Source: https://github.com/forum-labs/payfetch
+
+## Status and scope
+
+- Version 1.0.0. Policy schema `p3f.policy.v1`, client schema `p3f-1.0.0`.
+- x402 only, Base USDC, the `exact` scheme. Solana-settled x402, the `upto` scheme,
+  and MPP are parsed and then refused with a reason recorded in your receipts.
+- Requires Node 22 or newer. Windows is not supported.
+- USD is treated as USDC at 1.00. Budgets are denominated in USD and settle in USDC,
+  so a depeg makes the caps wrong by the depeg factor.
+
+## Install
+
+The package ships compiled JavaScript, so there is no build step and no `tsx` for
+consumers. Run it on demand with `npx`:
+
+```bash
+# Operator CLI (status, verify, clear-autodeny, report):
+npx @forum-labs/payfetch status
+
+# MCP server (what an MCP client launches):
+npx -p @forum-labs/payfetch payfetch-mcp
+```
+
+The package exposes two binaries: `payfetch` (the operator CLI) and `payfetch-mcp`
+(the stdio MCP server). Because there are two, the server is launched with
+`npx -p @forum-labs/payfetch payfetch-mcp`; the `-p` flag selects the named binary.
+
+## Quickstart
+
+### 1. Configure a wallet (pick exactly one signer)
+
+payfetch refuses to start if zero or more than one signer source is set. It never
+guesses which wallet to spend from.
+
+Raw private key, the simplest option. Use a dedicated low-balance wallet:
+
+```bash
+export PAYFETCH_PRIVATE_KEY=0xabc...
+```
+
+Key file, which must be mode 600 (payfetch refuses to start otherwise):
+
+```bash
+printf '0xabc...' > ~/.payfetch-wallet.key && chmod 600 ~/.payfetch-wallet.key
+export PAYFETCH_KEY_FILE=~/.payfetch-wallet.key
+```
+
+Coinbase CDP server wallet, where the keys are managed by CDP under your account
+instead of being pasted into an environment variable:
+
+```bash
+export PAYFETCH_CDP_API_KEY_ID=...
+export PAYFETCH_CDP_API_KEY_SECRET=...
+export PAYFETCH_CDP_WALLET_SECRET=...
+export PAYFETCH_CDP_ACCOUNT_NAME=payfetch   # optional; stable name across restarts
+```
+
+### 2. Wire it into an MCP client
+
+Claude Desktop, in `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "payfetch": {
+      "command": "npx",
+      "args": ["-y", "-p", "@forum-labs/payfetch", "payfetch-mcp"],
+      "env": {
+        "PAYFETCH_PRIVATE_KEY": "0xabc...",
+        "PAYFETCH_TEST_MODE": "1"
+      }
+    }
+  }
+}
+```
+
+Claude Code:
+
+```bash
+claude mcp add payfetch \
+  --env PAYFETCH_PRIVATE_KEY=0xabc... \
+  --env PAYFETCH_TEST_MODE=1 \
+  -- npx -y -p @forum-labs/payfetch payfetch-mcp
+```
+
+The examples set `PAYFETCH_TEST_MODE=1` so your first runs settle on Base Sepolia
+and never touch mainnet. Drop it when you are ready to spend real USDC.
+
+### 3. First paid fetch
+
+Quote before you pay. `payment_quote` returns the terms, the selected quote, the
+trust-check result, your remaining budgets, and the policy decision (`would_pay` or
+`would_deny`). It signs nothing and reserves nothing:
+
+```json
+{ "url": "https://api.example.com/paid-endpoint" }
+```
+
+Dry run the whole pipeline. `paid_fetch` with `"dryRun": true` runs the exact code
+path a real payment takes, up to but not including the signature.
+
+Pay for real with `paid_fetch`:
+
+```json
+{ "url": "https://api.example.com/paid-endpoint", "maxAmountUsd": 0.25 }
+```
+
+`maxAmountUsd` tightens the per-call cap for this one call. It can only lower the
+limit, never raise it. If the price is above your approval threshold, a human is
+asked to confirm (see Approvals). The result carries the response body, the payment
+outcome and transaction reference, any warnings, and a `receiptId`.
+
+## The spending policy
+
+Policy lives in `{dataDir}/config.json` (the data dir defaults to `~/.payfetch`).
+On first run payfetch writes the defaults there so you can read and edit exactly
+what you are running. A missing file falls back to the defaults. An invalid file
+fails closed: every paying tool returns `policy_config_invalid` until you fix it, so
+a typo never silently restores a cap you lowered. The file is re-read when its mtime
+changes.
+
+Only you can change the policy. No MCP tool mutates it and no tool clears an
+auto-deny. Agent-supplied parameters such as `maxAmountUsd` can only tighten, never
+loosen. Every denied `paid_fetch` result repeats this back to the agent so a
+prompt-injected model cannot mistake the boundary for something negotiable.
+
+### Caps
+
+- `caps.perCallUsd` (default 1.00): maximum for a single payment.
+- `caps.dailyUsd` (default 2.00): maximum per UTC day.
+- `caps.perHostDailyUsd` (default 1.00): maximum per host per UTC day.
+- `caps.totalUsd` (default null): optional lifetime cap.
+
+Caps are hard and reserve before paying. A signed authorization is held against the
+budget until it provably expires, so budgets can over-count but never under-count.
+At most one payment attempt happens per request, so a retry loop cannot drain the
+wallet.
+
+There is deliberately no default lifetime cap. The dedicated wallet's balance
+already bounds lifetime spend on-chain (see Security), so a software lifetime ceiling
+would be one more field to forget. Set `totalUsd` only if you want a software
+ceiling on top of a larger-balance wallet.
+
+### Allow and deny lists
+
+`mode` is `open` by default. Set it to `allowlist` to pay only hosts listed in
+`allow`. Patterns in `deny` are always refused and win over `allow`. A pattern like
+`*.example.com` matches subdomains, not the apex.
+
+### Approvals
+
+A payment whose price is strictly above `approval.thresholdUsd` (default 0.10)
+triggers approval. An approval authorizes one payment only. There is no "always
+allow", and it never widens future authority.
+
+- `elicit` (default): the client prompts a human with the host, resource, amount,
+  network and asset, guard results, and today's remaining budgets. They approve once
+  or deny. The prompt times out after 120 seconds and is then treated as a denial.
+  Some MCP clients cannot service an elicitation prompt (Claude Desktop cancels it
+  immediately; Claude Code supports it). payfetch tells apart a real human "deny"
+  from a client that simply cannot ask, and it never treats "cannot ask" as a silent
+  denial. When a payment is blocked only because the client cannot elicit, the tool
+  result says so and names the ways to allow it.
+- `queue`: the payment is not executed. The result returns an `approvalId`. A human
+  with approval authority resolves it with the `approve_pending` tool. An approved
+  entry is a grant to re-run: the follow-up `paid_fetch` runs the full pipeline again
+  and matches on host and exact amount. It expires after one hour, and drifted terms
+  require a fresh approval.
+- `deny`: anything above the threshold is refused, for unattended fleets.
+
+For clients that cannot prompt a human, two config-only settings let above-threshold
+payments through without a dialog. Both are explicit operator authorization, not the
+agent's, and neither is reachable from a tool. `approval.preApprovedUpToUsd` (default
+null) auto-approves above-threshold payments up to a ceiling.
+`approval.preApprovedHosts` (default empty) auto-approves specific hosts. Both still
+pass through every cap and every guard.
+
+Approval never bypasses caps. An approved payment that fails budget reservation is
+still denied.
+
+`approve_pending` with `{"action":"list"}` is always allowed and shows the queue.
+Approving or denying an entry requires `PAYFETCH_APPROVER=1` in the server's
+environment; without it the tool returns `approver_not_enabled`. An agent must not
+approve its own payments, so the server refuses to start if `PAYFETCH_APPROVER=1` is
+combined with a queue-capable approval mode.
+
+### Receipts
+
+Every outcome, including free fetches, dry runs, denials, and unknown-settlement
+cases, appends one immutable JSON line to the ledger:
+
+```
+{dataDir}/ledger/{yyyy-mm}.jsonl   # append-only, monthly rotation, fsync on payments
+{dataDir}/state.json               # disposable cache, rebuildable from the ledger
+{dataDir}/downloads/{receiptId}    # response bodies when responseMode is "file"
+```
+
+A receipt records the URL, method, and host; the outcome and deny code; the pipeline
+steps traversed; the selected quote and a tally of rejected quotes; guard results;
+approval info; the payment (payer address, nonce, validBefore, settled amount,
+transaction reference, and whether it confirmed); the budgets at decision time; and
+an HTTP summary. Key material, signatures, full payment payloads, response bodies,
+and request header values are never stored. Response bodies are recorded as a
+SHA-256 hash plus a byte count. URL query strings are stored, because this is your
+own audit trail on your own disk; guard calls, by contrast, strip the query (see
+Security). Nothing is rewritten. Corrections append `p3f.adjust.v1` records.
+
+Query receipts with the `list_receipts` tool (filter by time, host, or outcome) or
+`spend_status` (today's totals, holds, and recent payments). After repeated
+paid-but-bad outcomes a host is auto-denied for 7 days; clear it out of band with
+`payfetch clear-autodeny <host>`, never from a tool.
+
+## Trust and safety checks
+
+payfetch can consult two checks before it pays. Both call paid Forum Labs APIs at
+`https://api.forum-labs.com`, and both are self-dealing that is disclosed here rather
+than buried: the guards call our own products. The default guard budget is 0, so by
+default the client uses only those products' free tier. Any paid guard usage is
+opt-in, budgeted with `guards.*.dailyBudgetUsd > 0`, and produces a receipt like any
+other spend.
+
+The trust check is on by default in advisory mode. Before paying, it asks whether the
+target endpoint has a reliable history. In advisory mode it warns; in enforce mode it
+blocks on the configured verdicts (`unreliable` by default). New endpoints without
+enough history come back `unrated` and pass by default, so the check does not
+strangle them. This check is the client's only outbound call to us; see Security for
+exactly what it sends and how to turn it off.
+
+The safety check is off by default. When enabled it screens a token mint you pass in
+(`tokenAddress`) against the Forum Labs token safety API and blocks on a `danger`
+verdict, or on a `serial_rugger` deployer verdict in `deep` mode. `deep` is always a
+paid screen, so it needs `dailyBudgetUsd > 0`.
+
+## Security and disclosure
+
+Read this before pointing payfetch at a funded wallet.
+
+### The wallet balance is your real limit
+
+The primary control on how much a bug or a prompt-injected agent can spend is the
+balance of the wallet you point payfetch at, not the software caps. A wallet's
+balance is a hard on-chain bound: payfetch cannot spend a dollar that is not in the
+wallet, whatever the config says or the agent is told to do. So the first thing to
+get right is the wallet.
+
+Create a fresh wallet, fund it with only the amount you are willing to lose entirely
+(a few dollars for a trial, a capped top-up for production), and give payfetch that
+wallet. Never your main wallet. Refill it deliberately rather than by standing order.
+
+The caps, lists, approval threshold, and guards are the fine-grained layer on top.
+They shape rate, per-target exposure, and detection within that balance. They are
+real and enforced, but the wallet balance is the circuit breaker and the caps are
+the scalpel. Set both.
+
+### Key custody
+
+Your key is never transmitted to us, never logged, and never written to the receipt
+ledger. The ledger stores addresses and amounts, not keys, and that is asserted by a
+test. Keys are read from the environment in-process to sign EIP-3009 payment
+authorizations. A signed authorization is bounded to one asset, one amount, one
+recipient, and one time window. If you use `PAYFETCH_KEY_FILE`, payfetch refuses to
+start when the file is group- or world-readable, so `chmod 600` it.
+
+### What the trust guard sends, and the off switch
+
+While the trust guard is on, it makes one call to the Forum Labs trust API on every
+paid fetch. That call is the client's only egress to us. It sends the target endpoint
+with the query string stripped, plus a random per-install id. The query is stripped
+because a target URL's query can carry your own secrets; server-side we store a hash
+of the input, never the raw target, and the install id is used for aggregate counting
+only, never per-install profiling or resale. The install id is a random 32-hex value
+generated on first run and stored in your state file; delete the state file and it
+regenerates.
+
+Turn the guard off with `guards.trust.enabled: false`. With it off, payfetch makes no
+external call at all: no guard result, no network request, nothing dialed. That is
+the complete off switch, and the honest cost of it is that operators who disable the
+guard are invisible to our adoption instrument.
+
+### Optional outcome reporting (off by default)
+
+Reporting is off by default and changes nothing unless you turn it on. When you report
+an outcome, currently only per-incident with `payfetch report <receiptId>`, the client
+reports the outcome of a completed payment attempt (paid and delivered, or paid and
+not delivered), signed by your payment wallet and tied to the on-chain settlement, to
+the trust API. This is a fact about the seller's conduct that you are reporting. It is
+never a record of what you looked at. Lookups (guard checks, quotes, dry runs) are
+never retained per consumer.
+
+A report sends exactly these fields and nothing else: the endpoint `{method, url}`
+with the query stripped; the `outcome`, derived from the receipt and never
+agent-supplied; structural `checks` (`settlementConfirmed`, a coarse HTTP status
+class, `contentTypeOk`, `nonEmpty`); the `termsHash` you paid under; the seller's
+`payTo` address, which is already on-chain; a coarse `amountBand` rather than the
+exact amount; the UTC day rather than an exact timestamp; and your payment wallet
+address plus an EIP-712 signature over the payload. A report never carries the query
+string, request headers or bodies, the response body, the receiptId, the exact
+amount, or the exact timestamp. The install id never rides on the report path, so the
+report wallet and the guard install id are never joined.
+
+A settled x402 payment is already public (payer, payee, amount, and time are on the
+chain). What a report adds is the outcome bit. On very-low-traffic endpoints a seller
+may be able to infer that a report came from you, since the anonymity set is small; we
+mitigate with day granularity and bucketed publication, and we state the residual here
+rather than hide it. In this version the trust API verifies the signature
+(`recover(sig) === payer`), so a stranger cannot report on your behalf, but it does
+not yet prove the settlement, so reports are shown as unverified until they are
+settlement-matched in a later version. We will not monetize, publish, or attempt to
+deanonymize reporter wallets.
+
+### SSRF and private targets
+
+Unless you set `allowPrivateTargets: true`, payfetch refuses non-http(s) schemes and
+any host that resolves to loopback, RFC1918, link-local `169.254/16`, CGNAT, or ULA.
+A paying-fetch must not become the tool that exfiltrates `169.254.169.254`. DNS is
+pinned, so the vetted IP is the one dialed; every redirect hop is re-checked; and an
+`https` to `http` downgrade aborts.
+
+### What payfetch does not protect against
+
+Fetched content is untrusted input to your agent. A malicious page can tell the agent
+to fetch or pay somewhere else. payfetch bounds the damage with the dedicated wallet's
+balance and the caps, lists, approval threshold, receipts, and SSRF block, but it
+cannot make the agent wise. It cannot stop an injected agent from spending within
+policy, so keep the wallet balance small. For untrusted-content workloads, tighten the
+defaults:
+
+```jsonc
+{
+  "mode": "allowlist",
+  "allow": ["api.trusted-vendor.com"],
+  "caps": { "perCallUsd": 0.05, "dailyUsd": 0.50, "perHostDailyUsd": 0.25 },
+  "approval": { "thresholdUsd": 0.0, "mode": "elicit", "elicitFallback": "deny" },
+  "guards": { "trust": { "enabled": true, "mode": "enforce" } }
+}
+```
+
+`thresholdUsd: 0.0` sends every payment to a human. `mode: "enforce"` blocks on an
+`unreliable` verdict instead of only warning.
+
+Two more limits worth stating plainly. There is no on-chain settlement verification
+yet: settlement facts come from the server's payment-response header, so a lying
+server can misreport. Both error directions over-count, which is the safe direction,
+and on-chain verification is planned. And the ledger is single-instance: one lockfile,
+one process, one machine. A fleet needs a policy plane that is not built here.
+
+## Configuration reference
+
+Defaults, from `{dataDir}/config.json`, schema `p3f.policy.v1`:
+
+| Field | Default | Meaning |
+|---|---|---|
+| `mode` | `"open"` | `"allowlist"` pays only hosts in `allow`. |
+| `allow` | `[]` | Host patterns permitted in allowlist mode. |
+| `deny` | `[]` | Host patterns always refused (wins over `allow`). |
+| `caps.perCallUsd` | `1.00` | Max per single payment. |
+| `caps.dailyUsd` | `2.00` | Max per UTC day. |
+| `caps.perHostDailyUsd` | `1.00` | Max per host per UTC day. |
+| `caps.totalUsd` | `null` | Optional lifetime cap. |
+| `approval.thresholdUsd` | `0.10` | Above this, a human approves. |
+| `approval.mode` | `"elicit"` | `elicit`, `queue`, or `deny`. |
+| `approval.elicitFallback` | `"deny"` | Used when the client cannot elicit. Fail-closed. |
+| `approval.preApprovedUpToUsd` | `null` | No-dialog ceiling for above-threshold payments. |
+| `approval.preApprovedHosts` | `[]` | Hosts pre-approved to auto-pay above threshold. |
+| `guards.trust.enabled` | `true` | The default-on trust check. |
+| `guards.trust.mode` | `"advisory"` | `advisory` warns; `enforce` blocks. |
+| `guards.trust.blockVerdicts` | `["unreliable"]` | Verdicts that block or warn. |
+| `guards.trust.blockUnrated` | `false` | `unrated` passes by default. |
+| `guards.trust.onUnavailable` | `"block"` | Enforce-mode behavior when the guard cannot answer. |
+| `guards.trust.dailyBudgetUsd` | `0` | 0 means free tier only. |
+| `guards.safety.enabled` | `false` | Token safety screen; needs `tokenAddress`. |
+| `guards.safety.depth` | `"basic"` | `deep` is always paid. |
+| `guards.safety.blockVerdicts` | `["danger"]` | Token verdicts that block. |
+| `guards.safety.blockDeployerVerdicts` | `["serial_rugger"]` | Deployer verdicts, deep only. |
+| `guards.safety.onUnavailable` | `"block"` | Enforce behavior when the safety guard is dead. |
+| `guards.safety.onDegraded` | `"block"` | Enforce behavior on a degraded screen. |
+| `allowPrivateTargets` | `false` | SSRF guard. Keep `false`. |
+| `autoDeny.enabled` | `true` | Per-host circuit breaker. |
+
+Environment variables read by both the server and the CLI:
+
+| Variable | Meaning |
+|---|---|
+| `PAYFETCH_PRIVATE_KEY` | 0x-hex EVM private key. One of three signer sources. |
+| `PAYFETCH_KEY_FILE` | Path to a mode-600 file holding a 0x-hex key. |
+| `PAYFETCH_CDP_API_KEY_ID` / `_SECRET`, `PAYFETCH_CDP_WALLET_SECRET` | Coinbase CDP server-wallet credentials (all three required together). |
+| `PAYFETCH_CDP_ACCOUNT_NAME` | Optional named CDP EVM account. Defaults to a stable name. |
+| `PAYFETCH_DATA_DIR` | Ledger, state, and config root. Default `~/.payfetch`. |
+| `PAYFETCH_TEST_MODE` | Any value marks receipts `test:true` and refuses Base mainnet quotes (Sepolia only). |
+| `PAYFETCH_APPROVER` | `1` grants approval authority. Refused with a queue-capable mode. |
+| `PAYFETCH_VIA` | Optional `via=` attribution slug sent on guard calls only. |
+
+## Test mode
+
+Set `PAYFETCH_TEST_MODE` to any value. Then every receipt is stamped `test: true` and
+excluded from metrics, and Base mainnet quotes are refused so a self-test can never
+touch mainnet spend. Only Base Sepolia settles. Use it to run the end-to-end Base
+Sepolia path before spending real USDC.
+
+## CLI
+
+The `payfetch` CLI reads the same environment as the MCP server.
+
+```bash
+# Reset a host's auto-deny circuit breaker (an operator action, not a tool).
+npx @forum-labs/payfetch clear-autodeny api.example.com
+
+# Print today's spend status as JSON.
+npx @forum-labs/payfetch status
+
+# Verify the ledger tamper-evidence sidecar (exits non-zero on any integrity gap).
+npx @forum-labs/payfetch verify
+
+# Report a paid outcome for a receipt (opt-in, off by default). Prints the exact
+# wallet-signed payload, asks for confirmation, then submits. Never an MCP tool, so
+# the agent can neither file nor suppress a report. Use --yes to skip the prompt.
+npx @forum-labs/payfetch report <receiptId>
+```
+
+`status` builds the engine and takes the single-writer lock. If the MCP server is
+already running, use the `spend_status` tool instead, or stop the server first.
+
+## Manual .mcpb install
+
+Directory submission is not offered for payment connectors, so payfetch is packaged
+for manual install. Build the bundle:
+
+```bash
+npm run build:mcpb        # produces dist-mcpb/payfetch.mcpb
+```
+
+This runs `tsc`, then esbuild-bundles the built server entry and its runtime
+dependencies into a single self-contained ESM file, and packs it with the mcpb tool.
+The result is a small `.mcpb` zip holding `manifest.json` alongside the bundled
+server. No `node_modules` is shipped, so Claude Desktop installs it without running
+`npm install`. In Claude Desktop, go to Settings, Extensions, Install from file,
+choose the `.mcpb`, then fill in exactly one signer option. The bundling logic is in
+`mcpb/build.mjs` and the manifest is `mcpb/manifest.json`.
+
+## From source
+
+```bash
+npm install         # dev dependencies, including tsx for the from-source flow
+npm run typecheck   # tsc --noEmit
+npm test            # vitest, hermetic, no network
+npm run build       # emit dist/, the compiled JS the package ships
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE). Copyright (c) 2026 Forum Labs.

package/dist/bin/payfetch-mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/payfetch-mcp.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { scrubSecrets } from "../src/config.js";
+import { runStdioServer } from "../src/mcp/server.js";
+runStdioServer().catch((err) => {
+    const message = scrubSecrets(String(err?.message ?? err), []);
+    const line = message.startsWith("payfetch") ? message : `payfetch-mcp: fatal: ${message}`;
+    process.stderr.write(`${line}\n`);
+    process.exit(1);
+});

package/dist/bin/payfetch.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/payfetch.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import { buildFromEnv, resolveDataDir, scrubSecrets, ConfigError, } from "../src/config.js";
+import { SCAFFOLD_BASE_URL } from "../src/core/constants.js";
+import { realFs } from "../src/core/fs.js";
+import { Ledger, LedgerLockedError } from "../src/core/ledger.js";
+import { clearAutoDeny, createPayfetch } from "../src/index.js";
+import { runReport } from "../src/report/report.js";
+function usage(message) {
+    if (message)
+        process.stderr.write(`payfetch: ${message}\n`);
+    process.stderr.write("usage:\n" +
+        "  payfetch clear-autodeny <host>   reset a host's auto-deny (SPEC §5.4)\n" +
+        "  payfetch status                  print today's spend status (JSON)\n" +
+        "  payfetch verify                  verify the ledger integrity sidecar (SPEC §8/§14)\n" +
+        "  payfetch report <receiptId>      report a paid outcome (opt-in; --yes skips prompt)\n");
+    process.exit(message ? 1 : 0);
+}
+function promptYesNo(prompt) {
+    return new Promise((resolve) => {
+        process.stdout.write(prompt);
+        process.stdin.resume();
+        process.stdin.once("data", (buf) => {
+            process.stdin.pause();
+            const answer = buf.toString().trim().toLowerCase();
+            resolve(answer === "y" || answer === "yes");
+        });
+    });
+}
+async function cmdClearAutoDeny(host) {
+    if (!host)
+        usage("clear-autodeny requires a <host> argument");
+    const dataDir = resolveDataDir(process.env);
+    const cleared = clearAutoDeny(dataDir, host);
+    process.stdout.write(`${JSON.stringify({ host, cleared }, null, 2)}\n`);
+}
+async function cmdStatus() {
+    let pf;
+    try {
+        pf = createPayfetch(buildFromEnv(process.env));
+    }
+    catch (err) {
+        if (err instanceof LedgerLockedError) {
+            process.stderr.write("payfetch: the MCP server appears to be running (ledger is locked). " +
+                "Use the spend_status tool, or stop the server first.\n");
+            process.exit(1);
+        }
+        throw err;
+    }
+    try {
+        const status = await pf.status();
+        process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+    }
+    finally {
+        pf.close();
+    }
+}
+async function cmdVerify() {
+    const dataDir = resolveDataDir(process.env);
+    const ledger = new Ledger(realFs, dataDir, () => Date.now());
+    try {
+        ledger.acquireLock();
+    }
+    catch (err) {
+        if (err instanceof LedgerLockedError) {
+            process.stderr.write("payfetch: the MCP server appears to be running (ledger is locked). " +
+                "Stop the server first to verify the ledger.\n");
+            process.exit(1);
+        }
+        throw err;
+    }
+    let ok;
+    try {
+        const report = ledger.verifyIntegrity();
+        ok = report.ok;
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    finally {
+        ledger.releaseLock();
+    }
+    if (!ok)
+        process.exit(1);
+}
+async function cmdReport(rest) {
+    const receiptId = rest.find((a) => !a.startsWith("-"));
+    if (!receiptId)
+        usage("report requires a <receiptId> argument");
+    const autoYes = rest.includes("--yes") || rest.includes("-y");
+    const signer = buildFromEnv(process.env).deps.signer;
+    const dataDir = resolveDataDir(process.env);
+    const receipts = new Ledger(realFs, dataDir, () => Date.now()).readAllReceipts();
+    const outcome = await runReport({
+        readReceipts: () => receipts,
+        receiptId: receiptId,
+        signer,
+        fetchImpl: (input, init) => fetch(input, init),
+        baseUrl: SCAFFOLD_BASE_URL,
+        confirm: async () => autoYes ? true : await promptYesNo("Submit this report? [y/N] "),
+        out: (line) => process.stdout.write(`${line}\n`),
+        err: (line) => process.stderr.write(`${line}\n`),
+    });
+    if (outcome.kind === "not_found" ||
+        outcome.kind === "not_reportable" ||
+        outcome.kind === "submit_failed") {
+        process.exit(1);
+    }
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    switch (cmd) {
+        case "clear-autodeny":
+            return cmdClearAutoDeny(rest[0]);
+        case "status":
+            return cmdStatus();
+        case "verify":
+            return cmdVerify();
+        case "report":
+            return cmdReport(rest);
+        default:
+            usage(cmd ? `unknown subcommand: ${cmd}` : "no subcommand given");
+    }
+}
+main().catch((err) => {
+    const raw = scrubSecrets(String(err?.message ?? err), []);
+    process.stderr.write(err instanceof ConfigError ? `${raw}\n` : `payfetch: ${raw}\n`);
+    process.exit(1);
+});

package/dist/src/config.d.ts

@@ -0,0 +1,35 @@
+import type { PayfetchDeps } from "./payer/types.js";
+import type { CreatePayfetchOpts } from "./index.js";
+export declare const ENV: {
+    readonly PRIVATE_KEY: "PAYFETCH_PRIVATE_KEY";
+    readonly KEY_FILE: "PAYFETCH_KEY_FILE";
+    readonly CDP_API_KEY_ID: "PAYFETCH_CDP_API_KEY_ID";
+    readonly CDP_API_KEY_SECRET: "PAYFETCH_CDP_API_KEY_SECRET";
+    readonly CDP_WALLET_SECRET: "PAYFETCH_CDP_WALLET_SECRET";
+    readonly CDP_ACCOUNT_NAME: "PAYFETCH_CDP_ACCOUNT_NAME";
+    readonly DATA_DIR: "PAYFETCH_DATA_DIR";
+    readonly TEST_MODE: "PAYFETCH_TEST_MODE";
+    readonly APPROVER: "PAYFETCH_APPROVER";
+    readonly VIA: "PAYFETCH_VIA";
+};
+export declare const DEFAULT_DATA_DIR_NAME = ".payfetch";
+export declare const APPROVER_ENABLED_VALUE = "1";
+export type EnvRecord = Record<string, string | undefined>;
+export type ConfigIo = {
+    readText: (path: string) => string;
+    statMode: (path: string) => number | null;
+    homedir: () => string;
+    fetch: typeof fetch;
+    now: () => number;
+    random: () => Uint8Array;
+    log: PayfetchDeps["log"];
+};
+export declare function realConfigIo(): ConfigIo;
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function scrubSecrets(text: string, secrets: string[]): string;
+export type SignerSource = "private_key" | "key_file" | "cdp";
+export declare function selectSignerSource(env: EnvRecord): SignerSource;
+export declare function resolveDataDir(env: EnvRecord, homedir?: () => string): string;
+export declare function buildFromEnv(env: EnvRecord, io?: ConfigIo): CreatePayfetchOpts;