@aifinpay/mcp 2.0.0-rc.5 → 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AiFinPay
+
+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

@@ -1,105 +1,197 @@
 # @aifinpay/mcp
 
-MCP server exposing AiFinPay payment and quote primitives to MCP-aware
-agent runtimes. Canonical domain: **aifinpay.io**.
+AiFinPay MCP server for persistent agent identity, Agent Passport resolution,
+route discovery and non-signing settlement invoices. Canonical domain:
+**aifinpay.io**.
 
-AIFP-1 is gross-inclusive: payer total equals the quote, merchant receives 99%,
-AiFinPay receives 1%, creator/referral receives 0%. AIFP-2/x402 currently
-charges 0% at the protocol layer. Fund-moving paths fail closed until the exact
-deployment, runtime hash, governance profile, merchant target, asset and paid
-E2E evidence are verified.
+Source candidate **2.2.0**, paired with Node SDK **2.1.0**. The published
+MCP 2.1.0 remains read-only; publish the coordinated dependencies before using
+this candidate through npm. Source builds support owner-enabled native Polygon
+v1.4 purchases with `payable_fetch`. Without payment configuration, the server
+keeps its inspection-only tool inventory.
+
+## Enable native paid GET requests
+
+Use a persistent wallet created with public `npx @aifinpay/mcp init` or an
+existing configured identity. Keep its passphrase private. The owner must set:
+
+```json
+{
+  "AIFINPAY_PAYMENTS_ENABLED": "1",
+  "AIFINPAY_GATEWAY_ORIGINS": "https://merchant.example",
+  "AIFINPAY_GATEWAY_PATH_MODE": "direct",
+  "AIFINPAY_MAX_USD": "0.12",
+  "AIFINPAY_DAILY_USD": "1.00",
+  "AIFINPAY_MAX_GAS_POL": "0.05"
+}
+```
+
+Limits are examples, not authorization. USD limits cover purchases; gas has its
+own per-transaction POL cap. Origins are exact HTTPS origins authorized by the
+owner. `direct` uses the full path for self-hosted sites; `gateway` uses the
+merchant slug on the hosted gateway. Restart/reconnect the MCP process after
+changing its environment.
+
+Call `payable_fetch({"url":"https://merchant.example/api/data"})`. The tool
+uses the original signed v1.4 quote, independent fresh POL/USD pricing, SDK
+runtime/signer verification and owner limits. It persists the prepared transaction
+before sending, verifies the receipt, and reuses the purchased batch. No special
+merchant script, alternate contract or facilitator fallback is used. GET, native
+POL, Polygon live mode only; Amoy payment receipts and stable-token execution are
+not part of this candidate.
+
+Private recovery state lives at `AIFINPAY_HOME/payments/<evm-address>/state.json`
+(default home `~/.aifinpay`). State is mode600 in mode700 directories, atomically
+written and fsynced. One operation lock serializes the wallet across processes.
+A retry recovers a pending receipt before allowing another purchase. A process
+crash leaves the lock for owner reconciliation; it is never stolen automatically.
+If a prepared transaction was never broadcast or reverted, reconcile its exact
+hash before clearing anything. Never put raw transactions, receipt JWTs or the
+state file in chat. Unconfirmed payments consume the budget conservatively.
 
 ## Tools
 
-| Tool | What it does |
-|---|---|
-| `payable_fetch(url, opts?)` | Fetch any URL. On 402, auto-detect facilitator, sign, retry. |
-| `agent_address()` | Return the agent's funding addresses on **both** chains — Polygon `0x…` (default settlement: io.net, Exa, Venice bridges) and Solana base58 (Seat PDA / leaderboard). One seed, two chains — fund either. |
-| `agent_quote(url)` | Inspect a 402 challenge without paying. Shows the merchant's quoted amount + facilitator flavor. |
-| `agent_call(provider, …)` | Call a live provider from the AiFinPay directory (io.net, Exa, Venice, …) with automatic payment. |
-| `pay_with_split(…)` | Retired compatibility tool. Returns `legacy_split_route_retired`; never creates an invoice or moves funds. |
-| `quote_split(…)` | Retired compatibility tool. Use a canonical AIFP-1 quote. |
-| `agent_claim_self(magic_link_url)` | Link this agent to your dashboard account via a one-shot magic link from `aifinpay.io/login` — spend history shows up in the dashboard. |
+| Tool                     | Purpose                                                  |
+| ------------------------ | -------------------------------------------------------- |
+| `agent_address`          | Read the current Solana, EVM and Casper addresses.       |
+| `agent_reload`           | Reload local wallet files in the current MCP connection. |
+| `agent_quota`            | Read the agent's quota.                                  |
+| `agent_passport_resolve` | Resolve the global Agent Passport identity.              |
+| `settlement_routes`      | Read the available verified settlement routes.           |
+| `settlement_invoice`     | Prepare a non-signing settlement invoice.                |
+
+`payable_fetch` appears only with valid owner payment configuration and a persistent wallet.
+Legacy `agent_call`, `agent_quote`, `pay_with_split`, `quote_split` and
+`agent_claim_self` remain unregistered.
+
+## Persistent wallet selection
+
+The CLI (`init` and stdio), programmatic server and `agent_reload` use the same
+priority:
+
+1. `SEED_HASH`: an existing 32-byte seed encoded as 64 hex characters, optionally
+   prefixed with `0x`. It is passed directly to `AiFinPayAgent.fromSeed`; do not
+   hash it again or supply a mnemonic.
+2. `./aifinpay/agents.json`, relative to the MCP process's working directory.
+   Set an absolute `AIFINPAY_AGENTS_FILE` when a desktop client's working
+   directory differs from the project directory. The file contains an `agents`
+   array of records with `id` and private `seed_hash` fields. If there is more
+   than one record, select exactly one with `AIFINPAY_AGENT_ID`.
+3. `AIFINPAY_AGENT_SECRET`: a legacy base58 Solana secret.
+4. `~/.aifinpay/agent.json`, or `AIFINPAY_HOME/agent.json`: the legacy CLI
+   keystore. Encrypted files require `AIFINPAY_WALLET_PASSPHRASE`.
 
-## Install
+Keep seeds and wallet files private and out of chat, source control and logs.
+Invalid or ambiguous configured inputs fail; they never generate a replacement
+wallet. With no configured wallet at all the server has an ephemeral identity:
+**do not fund it**.
+
+## Initialize and connect
+
+A quote or invoice is not a completed payment. Enable the owner-configured
+`payable_fetch` tool only after installing the coordinated candidate dependencies.
+
+## Local configuration
 
 ```bash
-# Globally — usable as `npx @aifinpay/mcp` from any client config
-# (installs the latest stable — the old @alpha tag is retired, don't use it)
-npm install -g @aifinpay/mcp
+npx @aifinpay/mcp init
 ```
 
-## Use with Claude Desktop
+Select the wallet in this order: `SEED_HASH` → `./aifinpay/agents.json` →
+legacy `AIFINPAY_AGENT_SECRET` → `~/.aifinpay/agent.json`.
+SEED_HASH means a 32-byte hex seed, passed directly to SDK `fromSeed`.
+See the skill for the exact project-file schema and multi-agent selection.
+`init` prints the selected wallet's public addresses. If a seed or project wallet
+is already configured, it does not create a second legacy wallet. With no
+wallet, it creates the legacy keystore with mode `600`; existing keystores are
+retained. Back up that file privately. Use the published release or
+build this source checkout.
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Use an absolute `AIFINPAY_AGENTS_FILE` path when the host's working directory
+is not your project directory. Do not put the seed itself in a shared config.
+A client configuration can use the keystore without embedding its secret:
 
 ```json
 {
   "mcpServers": {
     "aifinpay": {
       "command": "npx",
-      "args": ["@aifinpay/mcp"],
+      "args": ["-y", "@aifinpay/mcp@2.2.0"],
       "env": {
-        "AIFINPAY_AGENT_SECRET": "<base58 secret — see below>",
-        "AIFINPAY_MAX_USD": "0.50"
+        "AIFINPAY_AGENTS_FILE": "/absolute/project/aifinpay/agents.json",
+        "AIFINPAY_AGENT_ID": "research-agent"
       }
     }
   }
 }
 ```
 
-Restart Claude Desktop. Now Claude can call `payable_fetch`, `agent_address`,
-and `agent_quote` like any other tool.
-
-## First run — generating an agent
-
-If `AIFINPAY_AGENT_SECRET` is not set, the server generates an ephemeral
-keypair and **prints it to stderr** at startup:
+The release above must be published before this npx command can install it.
+After the pinned dependencies are published, source checkouts can run
+`npm ci && npm run build` in mcp/ and configure
+`node /absolute/path/to/mcp/bin/aifinpay-mcp.js` instead.
+
+If using the legacy keystore, run `npx @aifinpay/mcp init` once and omit the
+project-file variables. Optional `AIFINPAY_WALLET_PASSPHRASE` encrypts that
+legacy file at creation. An already connected server can load it with
+`agent_reload`; it does not need a new conversation. A changed package or
+launch environment requires a server reconnect, subject to host support.
+
+## History
+
+Connect the MCP server once. After `init` or a wallet file update, call
+`agent_reload` in that same connection; no new conversation is required. A
+failed reload keeps the previous wallet. Changed shell environment variables
+require reconnecting the MCP process, since its environment is a startup
+snapshot. Verify `agent_address` against the wallet you intend to use.
+
+## Other environment variables
+
+| Variable                     | Default               | Purpose                                                                              |
+| ---------------------------- | --------------------- | ------------------------------------------------------------------------------------ |
+| `AIFINPAY_BASE_URL`          | `https://aifinpay.io` | Backend URL.                                                                         |
+| `AIFINPAY_TIMEOUT_MS`        | `30000`               | Request timeout.                                                                     |
+| `AIFINPAY_MAX_USD`           | —                     | Configures the underlying agent's per-call cap; it does not enable signing.          |
+| `AIFINPAY_GATEWAY_ORIGINS`   | SDK default           | Comma-separated exact HTTPS origins trusted for AIFP-1 settlement.                   |
+| `AIFINPAY_GATEWAY_PATH_MODE` | `gateway`             | Use `gateway` for merchant-slug identity or `direct` for full request-path identity. |
+
+`agent_history({address, source:"transactions"})` reads indexed Polygon
+settlements; `source:"receipts"` reads retained batches, including test-mode
+payments. Pass `passport` instead of, or alongside, `address` to resolve a
+public passport first. A backend without the passport resolver cannot satisfy
+passport-only queries. No secret API key is needed for public metadata.
+
+Responses do not include bearer receipts. Limits are 1..100; follow
+`next_offset`. History source/coverage is explicit: it is not a full wallet
+explorer. Dev networks currently use receipt history, not the Polygon ledger.
 
 ```
-[warn] no AIFINPAY_AGENT_SECRET set — generated EPHEMERAL agent.
-  address: 9xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-  secret:  4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-  >> Save this secret to AIFINPAY_AGENT_SECRET to keep the agent across restarts.
+const { server } = await createServer(loadConfigFromEnv());
+await server.connect(new StdioServerTransport());
 ```
 
-Save the secret to `AIFINPAY_AGENT_SECRET` in your client config so the
-agent identity (and any funded Seat) persists across restarts.
+The programmatic equivalents of identity environment options are `seedHash`,
+`agentsFile`, `agentId`, `agentSecretB58`, `walletHome` and `walletPassphrase`.
 
-## Environment variables
-
-| Var | Default | Purpose |
-|---|---|---|
-| `AIFINPAY_AGENT_SECRET` | — | Base58 secret. If absent → ephemeral agent printed to stderr. |
-| `AIFINPAY_BASE_URL` | `https://aifinpay.io` | Backend URL for nonce + funding probes. |
-| `AIFINPAY_TIMEOUT_MS` | `30000` | Request timeout. |
-| `AIFINPAY_MAX_USD` | — | Mandatory positive finite operator ceiling for any fund-moving tool. |
-
-## Programmatic use
-
-```ts
-import { createServer, loadConfigFromEnv } from "@aifinpay/mcp";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-const { server } = await createServer({
-  ...loadConfigFromEnv(),
-  agentSecretB58: "your-secret-here",
-  maxAmountUsd: 0.10,
-});
-await server.connect(new StdioServerTransport());
-```
+- AIFINPAY_BASE_URL: backend origin; default https://aifinpay.io.
+- AIFINPAY_HOME: directory of the legacy agent.json keystore.
+- AIFINPAY_MODE=dev: expose dev_payment_quote; requires a separate dev base URL.
 
-## How `payable_fetch` works
+- AIFINPAY_TIMEOUT_MS: SDK request timeout.
+- AIFINPAY_MAX_USD: legacy per-call budget; does not enable signing.
+- AIFINPAY_TRUSTED_HOSTS: exact hosts allowed to bypass the DNS pre-check.
+- AIFINPAY_ALLOW_PRIVATE_FETCH=1: explicit local-development network access.
+  Never enable this on the public hosted MCP.
 
-1. Sends the request unauthenticated.
-2. On `402`, the underlying [`@aifinpay/agent`](../node) SDK detects the
-   facilitator flavor (AiFinPay native, Coinbase x402, …).
-3. Signs a payment payload and retries.
-4. Returns `{ status, ok, headers, body }` to the agent.
+For a self-hosted AIFP-1 gateway, set `AIFINPAY_GATEWAY_ORIGINS` to exact HTTPS
+origins. `AIFINPAY_GATEWAY_PATH_MODE=direct` makes the process use each request's
+full pathname as its AIFP-1 resource identity; `gateway` uses the merchant slug.
+The mode is process-wide, does not broaden the trusted-origin allowlist, and
+does not enable the retired signing tools in the production RC.
 
-The flow is identical to calling `agent.pay(url)` directly — this
-package just wraps it as an MCP tool surface so LLM agents can call it
-without writing payment code.
+Dev quoting does not bypass wallet signatures, issuer verification or
+receipt metering. See the bundled skill for backend prerequisites. The low-level SDK has an Amoy
+executor; this MCP candidate does not expose Amoy paid receipt purchases.
 
 ## License
 

package/bin/aifinpay-mcp.js

@@ -22,12 +22,25 @@
  *
  * Configure via env (all optional; the secret is read from the keystore below
  * when the variable is unset):
- *   AIFINPAY_AGENT_SECRET   base58 secret — overrides the keystore
+ *   SEED_HASH              32-byte hex seed — highest priority
+ *   AIFINPAY_AGENTS_FILE    project agents file — second priority
+ *   AIFINPAY_AGENT_SECRET   legacy base58 secret — overrides the legacy keystore
  *   AIFINPAY_BASE_URL       default https://aifinpay.io
  *   AIFINPAY_TIMEOUT_MS     default 30000
  *   AIFINPAY_MAX_USD        hard cap per single payment (no default)
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, chmodSync } from "node:fs";
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  openSync,
+  closeSync,
+  fchmodSync,
+  fsyncSync,
+  linkSync,
+  unlinkSync,
+} from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { createRequire } from "node:module";
@@ -62,7 +75,7 @@ Run init once. It writes ${KEYSTORE} with mode 600 and the server picks
 it up automatically — you do not have to put the secret in a config file.
 
 Env (all optional):
-  AIFINPAY_AGENT_SECRET   base58 secret; overrides the keystore
+  SEED_HASH              32-byte hex seed; highest priority\n  AIFINPAY_AGENTS_FILE    default ./aifinpay/agents.json; second priority\n  AIFINPAY_AGENT_ID       select one record when the file has multiple agents\n  AIFINPAY_AGENT_SECRET   legacy base58 secret; after project wallet sources
   AIFINPAY_MAX_USD        hard cap per single payment — set this
   AIFINPAY_BASE_URL       default https://aifinpay.io
   AIFINPAY_TIMEOUT_MS     default 30000
@@ -88,27 +101,50 @@ const PASSPHRASE = process.env.AIFINPAY_WALLET_PASSPHRASE || null;
 // is unaffected: no passphrase => plaintext, exactly as before. scrypt to
 // stretch, AES-256-GCM so tampering is detected rather than decrypting to junk.
 function encryptSecret(secretB58) {
-  const salt = randomBytes(16), iv = randomBytes(12);
-  const key = scryptSync(PASSPHRASE, salt, 32, { N: 1 << 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 });
+  const salt = randomBytes(16),
+    iv = randomBytes(12);
+  const key = scryptSync(PASSPHRASE, salt, 32, {
+    N: 1 << 15,
+    r: 8,
+    p: 1,
+    maxmem: 64 * 1024 * 1024,
+  });
   const cipher = createCipheriv("aes-256-gcm", key, iv);
   const ct = Buffer.concat([cipher.update(secretB58, "utf8"), cipher.final()]);
-  return { enc: "scrypt-aes-256-gcm", salt: salt.toString("base64"), iv: iv.toString("base64"),
-           tag: cipher.getAuthTag().toString("base64"), ct: ct.toString("base64"),
-           created: new Date().toISOString() };
+  return {
+    enc: "scrypt-aes-256-gcm",
+    salt: salt.toString("base64"),
+    iv: iv.toString("base64"),
+    tag: cipher.getAuthTag().toString("base64"),
+    ct: ct.toString("base64"),
+    created: new Date().toISOString(),
+  };
 }
 function decryptSecret(store) {
   if (!PASSPHRASE) throw new Error(`${KEYSTORE} is encrypted but AIFINPAY_WALLET_PASSPHRASE is not set.`);
-  const key = scryptSync(PASSPHRASE, Buffer.from(store.salt, "base64"), 32, { N: 1 << 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 });
+  const key = scryptSync(PASSPHRASE, Buffer.from(store.salt, "base64"), 32, {
+    N: 1 << 15,
+    r: 8,
+    p: 1,
+    maxmem: 64 * 1024 * 1024,
+  });
   const dc = createDecipheriv("aes-256-gcm", key, Buffer.from(store.iv, "base64"));
   dc.setAuthTag(Buffer.from(store.tag, "base64"));
-  try { return Buffer.concat([dc.update(Buffer.from(store.ct, "base64")), dc.final()]).toString("utf8"); }
-  catch { throw new Error(`could not decrypt ${KEYSTORE}: wrong AIFINPAY_WALLET_PASSPHRASE or the file was modified.`); }
+  try {
+    return Buffer.concat([dc.update(Buffer.from(store.ct, "base64")), dc.final()]).toString("utf8");
+  } catch {
+    throw new Error(`could not decrypt ${KEYSTORE}: wrong AIFINPAY_WALLET_PASSPHRASE or the file was modified.`);
+  }
 }
 
 function readKeystore() {
   if (!existsSync(KEYSTORE)) return null;
   let parsed;
-  try { parsed = JSON.parse(readFileSync(KEYSTORE, "utf8")); } catch { return null; }
+  try {
+    parsed = JSON.parse(readFileSync(KEYSTORE, "utf8"));
+  } catch {
+    return null;
+  }
   // A decrypt failure THROWS rather than returning null — null reads as "no
   // wallet" and mints a new one, which is how a mistyped passphrase loses a key.
   if (parsed?.enc) return { secretB58: decryptSecret(parsed), created: parsed.created, encrypted: true };
@@ -118,47 +154,82 @@ function readKeystore() {
 if (arg === "init") {
   const { Agent, AiFinPayAgent } = await import("@aifinpay/agent");
 
+  const { loadConfigFromEnv } = await import("../dist/config.js");
+  const { loadWalletIdentity } = await import("../dist/identity.js");
+  const selected = loadWalletIdentity(loadConfigFromEnv());
+  if (selected && selected.source !== "legacy-keystore") {
+    const agent = selected.seedHash
+      ? await AiFinPayAgent.fromSeed(selected.seedHash)
+      : await AiFinPayAgent.fromSolanaSecret(selected.secretB58);
+    process.stdout.write(
+      `Using ${selected.source}; no replacement wallet created.\n` +
+        `EVM ${agent.evmAddress}\nSolana ${agent.solanaAddress}\nCasper ${agent.casperAddress}\n` +
+        `Keep your configured seed backed up privately. Call agent_reload in an already connected MCP server.\n`
+    );
+    process.exit(0);
+  }
+
   let store = readKeystore();
-  const freshlyCreated = !store;
-  if (store) {
-    // Never silently overwrite. The file is the only copy of a key that may
-    // already hold funds; a second `init` that regenerated it would destroy a
-    // wallet to save one line of output.
-    process.stdout.write(`Existing wallet found at ${KEYSTORE} — keeping it.\n\n`);
-  } else {
+  let freshlyCreated = false;
+  if (!store) {
     mkdirSync(HOME, { recursive: true, mode: 0o700 });
     const secretB58 = Agent.new().secretB58;
-    store = { secretB58, created: new Date().toISOString() };
-    const onDisk = PASSPHRASE ? encryptSecret(secretB58) : store;
-    writeFileSync(KEYSTORE, JSON.stringify(onDisk, null, 2) + "\n", { mode: 0o600 });
-    chmodSync(KEYSTORE, 0o600); // writeFileSync honours umask; this does not
+    const candidate = { secretB58, created: new Date().toISOString() };
+    const onDisk = PASSPHRASE ? encryptSecret(secretB58) : candidate;
+    const temporary = join(HOME, `.agent-init-${process.pid}-${randomBytes(12).toString("hex")}.tmp`);
+    // Publish a complete file without replacing an existing wallet. Two init
+    // processes may both see no keystore; only one exclusive link can win.
+    // A direct exclusive write would expose a partially written file to readers.
+    let fd;
+    let ownsTemporary = false;
+    try {
+      fd = openSync(temporary, "wx", 0o600);
+      ownsTemporary = true;
+      fchmodSync(fd, 0o600);
+      writeFileSync(fd, JSON.stringify(onDisk, null, 2) + "\n");
+      fsyncSync(fd);
+      closeSync(fd);
+      fd = undefined;
+      try {
+        linkSync(temporary, KEYSTORE);
+        store = candidate;
+        freshlyCreated = true;
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        store = readKeystore();
+        if (!store) throw new Error(`Existing ${KEYSTORE} is unreadable; refusing to replace it.`);
+      }
+    } finally {
+      if (fd !== undefined) closeSync(fd);
+      if (ownsTemporary) unlinkSync(temporary);
+    }
+  }
+  if (freshlyCreated) {
     process.stdout.write(
       PASSPHRASE
         ? `Created ${KEYSTORE} (mode 600, ENCRYPTED). Keep AIFINPAY_WALLET_PASSPHRASE — the wallet is unrecoverable without it.\n\n`
-        : `Created ${KEYSTORE} (mode 600, plaintext). For at-rest encryption, set AIFINPAY_WALLET_PASSPHRASE before init.\n\n`,
+        : `Created ${KEYSTORE} (mode 600, plaintext). For at-rest encryption, set AIFINPAY_WALLET_PASSPHRASE before init.\n\n`
     );
+  } else {
+    process.stdout.write(`Existing wallet found at ${KEYSTORE} — keeping it.\n\n`);
   }
 
   // The one-time recovery output.
   //
-  // Shown ONLY on creation, ONLY in the terminal, and ONLY when the keystore is
-  // plaintext. This is NOT the leak the audit (AIFINP-220 §3) forbids — that is
-  // a key written to CHAT or LOGS, where an LLM provider or a log shipper keeps
-  // it forever. This is the deliberate one-time backup prompt every wallet CLI
-  // shows, on a channel the user controls. Opposite things: the owner reading
-  // their own recovery phrase once, vs a secret leaking into a transcript.
+  // Shown only to the successful creator of a plaintext wallet on a TTY.
+  // Piped output (including agent subprocess logs) contains public data only.
   //
   // Encrypted keystores print nothing here: recovery there IS the keystore file
   // plus the passphrase, and re-printing the plaintext secret would defeat the
   // encryption the user just asked for.
-  if (freshlyCreated && !PASSPHRASE) {
+  if (freshlyCreated && !PASSPHRASE && process.stdout.isTTY) {
     process.stdout.write(
       `\n  RECOVERY KEY (shown once, never again):\n\n` +
-      `    ${store.secretB58}\n\n` +
-      `  Save this off this machine NOW. Anyone with it controls the wallet and\n` +
-      `  its funds. Do NOT paste it into a chat, an issue, or a config file — the\n` +
-      `  keystore at ${KEYSTORE} already holds it (encrypt it with\n` +
-      `  AIFINPAY_WALLET_PASSPHRASE). This line is your OFF-machine backup.\n\n`,
+        `    ${store.secretB58}\n\n` +
+        `  Save this off this machine NOW. Anyone with it controls the wallet and\n` +
+        `  its funds. Do NOT paste it into a chat, an issue, or a config file — the\n` +
+        `  keystore at ${KEYSTORE} already holds it (encrypt it with\n` +
+        `  AIFINPAY_WALLET_PASSPHRASE). This line is your OFF-machine backup.\n\n`
     );
   }
 
@@ -169,26 +240,26 @@ if (arg === "init") {
       `  EVM     ${agent.evmAddress}\n` +
       `  Solana  ${agent.solanaAddress}\n` +
       `  Casper  ${agent.casperAddress}\n\n` +
-      `Add this to your MCP client config and restart it:\n\n` +
+      `Add this to your MCP client config and connect/reconnect this MCP server:\n\n` +
       JSON.stringify(
         {
           mcpServers: {
             aifinpay: {
               command: "npx",
-              args: ["-y", "@aifinpay/mcp"],
+              args: ["-y", `@aifinpay/mcp@${VERSION}`],
               env: { AIFINPAY_MAX_USD: "0.10" },
             },
           },
         },
         null,
-        2,
+        2
       ) +
       `\n\nThe secret is NOT in that block on purpose — the server reads the\n` +
-      `keystore. Config files get pasted into chats and committed to git.\n\n` +
+      `keystore. If this server is already connected, call agent_reload after init.\nA new conversation is not required by this server.\n\n` +
       `Back up ${KEYSTORE}. It is the only copy. The derivation is not\n` +
       `BIP-39, so no standard wallet can recover this from a phrase.\n\n` +
-      `The addresses hold nothing yet. Send POL to the EVM address to let the\n` +
-      `agent pay for calls.\n`,
+      `The EVM address is used for Polygon payments. Check its balance before\n` +
+      `funding it or paying for calls.\n`
   );
   process.exit(0);
 }
@@ -200,31 +271,8 @@ if (arg && !arg.startsWith("-")) {
 
 // ── server ────────────────────────────────────────────────────────────────
 
-// Fall back to the keystore so `init` once is genuinely enough. Env still wins:
-// a caller that sets AIFINPAY_AGENT_SECRET explicitly means it.
-if (!process.env.AIFINPAY_AGENT_SECRET) {
-  const store = readKeystore();
-  if (store) {
-    try {
-      const mode = statSync(KEYSTORE).mode & 0o777;
-      if (mode & 0o077) {
-        process.stderr.write(
-          `[warn] [aifinpay-mcp] ${KEYSTORE} is mode ${mode.toString(8)} — readable beyond your user. ` +
-            `Run: chmod 600 ${KEYSTORE}\n`,
-        );
-      }
-    } catch {
-      /* stat failure is not a reason to refuse to start */
-    }
-    process.env.AIFINPAY_AGENT_SECRET = store.secretB58;
-  } else {
-    process.stderr.write(
-      `[info] [aifinpay-mcp] no wallet configured. Run \`npx @aifinpay/mcp init\` once ` +
-        `for a persistent one; starting with a throwaway identity for now.\n`,
-    );
-  }
-}
-
+// Identity selection is shared with the programmatic server and agent_reload.
+// Do not copy a file secret into process.env: it would mask later file updates.
 const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
 const { createServer, loadConfigFromEnv } = await import("../dist/index.js");
 

package/dist/api.d.ts

@@ -0,0 +1,2 @@
+export declare function apiUrl(base: string, path: string): string;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGzD"}

package/dist/api.js

@@ -0,0 +1,6 @@
+export function apiUrl(base, path) {
+    if (new URL(base).hostname === "api.aifinpay.io" && path.startsWith("/api/"))
+        path = path.slice(4);
+    return `${base.replace(/\/+$/, "")}${path}`;
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,IAAY;IAC/C,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,KAAK,iBAAiB,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnG,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC;AAC9C,CAAC"}

package/dist/config.d.ts

@@ -1,12 +1,23 @@
 /** Runtime configuration loaded from env. */
 export interface McpConfig {
-    /** Base58 secret to load the agent identity. If absent, a fresh keypair is
-     *  generated AND printed to stderr at startup with a "save this!" warning. */
+    /** Legacy base58 secret, after SEED_HASH and the project agents file. */
     agentSecretB58?: string;
+    /** 32-byte hex seed, consumed exactly as AiFinPayAgent.fromSeed does. */
+    seedHash?: string;
+    agentsFile?: string;
+    agentId?: string;
+    walletHome?: string;
+    walletPassphrase?: string;
+    /** Enables dev discovery/quoting only; never enables settlement signing. */
+    devMode?: boolean;
     /** Custom AiFinPay backend URL. Defaults to production. */
     baseUrl?: string;
     /** Request timeout in ms. */
     timeoutMs?: number;
+    /** Owner opt-in; never accepted from tool arguments. */
+    paymentsEnabled?: boolean;
+    dailyAmountUsd?: number;
+    maxGasPol?: string;
     /** Hard cap on a single payment to prevent runaway agents. */
     maxAmountUsd?: number;
     /** Gateway origins this agent may settle against.
@@ -22,6 +33,8 @@ export interface McpConfig {
      *  unrecognised host means paying whoever answered. Naming a host here is a
      *  statement that you know who that is. */
     gatewayOrigins?: string[];
+    /** AIFP-1 resource identity: merchant slug or full direct request path. */
+    gatewayPathMode?: "gateway" | "direct";
     /** Hosts whose DNS pre-check is skipped, exact names only.
      *
      *  safe-fetch resolves a hostname and refuses if any answer is a private
@@ -37,4 +50,6 @@ export interface McpConfig {
     logFn?: (level: "info" | "warn" | "error", msg: string) => void;
 }
 export declare function loadConfigFromEnv(): McpConfig;
+/** Signing is available only after the owner configures all spending boundaries. */
+export declare function validatePaymentConfig(config: McpConfig): bigint;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,MAAM,WAAW,SAAS;IACxB;kFAC8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;+CAW2C;IAC3C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;;;;;;;8CAS0C;IAC1C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB,qDAAqD;IACrD,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjE;AAED,wBAAgB,iBAAiB,IAAI,SAAS,CAa7C"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,MAAM,WAAW,SAAS;IACxB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,wDAAwD;IACxD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;+CAW2C;IAC3C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,2EAA2E;IAC3E,eAAe,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAEvC;;;;;;;;;8CAS0C;IAC1C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB,qDAAqD;IACrD,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjE;AAED,wBAAgB,iBAAiB,IAAI,SAAS,CAyB7C;AA0DD,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CA+B/D"}