@aifinpay/mcp 1.5.3 → 2.0.0-rc.12

package/README.md

@@ -1,109 +1,156 @@
 # @aifinpay/mcp
 
-MCP server exposing AiFinPay's autonomous x402 payment loop as
-agent-callable tools. Drop it into Claude Desktop, MCP Inspector, or any
-MCP-aware agent runtime — your agent can now buy services autonomously.
-
-Canonical domain: **aifinpay.io** (the legacy `aifinpay.company` host is
-retired — ignore any docs pointing there). SDK settlement runs on
-**Polygon (default) and Solana**; the underlying Node SDK (≥ 1.3.0) also
-supports direct splitter settlement on Base, Optimism, Unichain, BOT Chain
-and XRPL EVM (native-token path), while the MCP `pay_with_split` /
-`quote_split` tools stay Polygon + Solana (backend invoice flow). The
-protocol itself is live across 13 networks — see
-[aifinpay.io/llms.txt](https://aifinpay.io/llms.txt).
+AiFinPay MCP server for persistent agent identity, Agent Passport resolution,
+route discovery and non-signing settlement invoices. Canonical domain:
+**aifinpay.io**.
+
+This 2.0 release candidate does not expose payment-signing tools. Returning a
+wallet address or preparing an invoice does not authorize or execute a payment.
+Signing remains gated on the verified SDK v2 executor and its release evidence.
+Local MCP tools for wallet discovery, payment history, quotas and non-signing
+payment preparation. Read the bundled [skill](skills/SKILL.md), also exposed
+as the MCP resource `aifinpay://skill`.
 
 ## Tools
 
-| Tool | What it does |
+| Tool | Purpose |
 |---|---|
-| `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(chain, merchant, amount, …)` | Direct fee-on-top payment to any merchant wallet — merchant receives 100% of the amount, AiFinPay adds 1% on top. |
-| `quote_split(chain, amount)` | Preview the exact on-chain amounts of a `pay_with_split` before paying. |
-| `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. |
-
-## Install
-
+| `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. |
+
+Legacy `payable_fetch`, `agent_call`, `agent_quote`, `pay_with_split`,
+`quote_split` and `agent_claim_self` tools are not registered by this RC.
+
+## 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`.
+
+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
+This RC does not register payment-signing tools. Its legacy SDK dependency
+supplies wallet derivation only; installing this MCP does not enable v2
+settlement. An invoice or quote is not a completed payment.
+
+## 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@next 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. The `@next` tag selects the 2.0 RC lane;
+use the release containing these changes, 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.0.0-rc.12"],
       "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.
+The release above must be published before this npx command can install it.
+For a source checkout, run `npm ci && npm run build` in mcp/ and configure
+`node /absolute/path/to/mcp/bin/aifinpay-mcp.js` instead.
 
-## First run — generating an agent
+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.
 
-If `AIFINPAY_AGENT_SECRET` is not set, the server generates an ephemeral
-keypair and **prints it to stderr** at startup:
-
-```
-[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.
-```
+## 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.
 
-Save the secret to `AIFINPAY_AGENT_SECRET` in your client config so the
-agent identity (and any funded Seat) persists across restarts.
+## Other environment variables
 
-## Environment variables
-
-| Var | Default | Purpose |
+| Variable | 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_BASE_URL` | `https://aifinpay.io` | Backend URL. |
 | `AIFINPAY_TIMEOUT_MS` | `30000` | Request timeout. |
-| `AIFINPAY_MAX_USD` | — | Hard cap per single payment. Strongly recommended. |
+| `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. |
 
-## Programmatic use
+`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.
 
-```ts
-import { createServer, loadConfigFromEnv } from "@aifinpay/mcp";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+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.
 
-const { server } = await createServer({
-  ...loadConfigFromEnv(),
-  agentSecretB58: "your-secret-here",
-  maxAmountUsd: 0.10,
-});
+```
+const { server } = await createServer(loadConfigFromEnv());
 await server.connect(new StdioServerTransport());
 ```
 
-## How `payable_fetch` works
+The programmatic equivalents of identity environment options are `seedHash`,
+`agentsFile`, `agentId`, `agentSecretB58`, `walletHome` and `walletPassphrase`.
+
+
+- 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.
+
+- 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 and the
+remaining Amoy executor requirement.
 
 ## License
 

package/bin/aifinpay-mcp.js

@@ -22,15 +22,18 @@
  *
  * 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";
+import { scryptSync, randomBytes, createCipheriv, createDecipheriv } from "node:crypto";
 
 const HOME = process.env.AIFINPAY_HOME || join(homedir(), ".aifinpay");
 const KEYSTORE = join(HOME, "agent.json");
@@ -61,7 +64,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
@@ -77,31 +80,121 @@ if (arg === "--version" || arg === "-v" || arg === "version") {
 
 // ── init ──────────────────────────────────────────────────────────────────
 
+const PASSPHRASE = process.env.AIFINPAY_WALLET_PASSPHRASE || null;
+
+// Optional at-rest encryption. Mode 600 keeps the keystore from OTHER users; it
+// does nothing against malware running as YOU — the threat the OSINT write-up of
+// a compromised dev machine described. A passphrase makes the on-disk file
+// ciphertext; the secret is only in memory while the passphrase is supplied.
+// Opt-in and env-supplied so the non-interactive `npx @aifinpay/mcp` launch path
+// 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 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() };
+}
+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 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.`); }
+}
+
 function readKeystore() {
   if (!existsSync(KEYSTORE)) return null;
-  try {
-    const parsed = JSON.parse(readFileSync(KEYSTORE, "utf8"));
-    return typeof parsed?.secretB58 === "string" ? parsed : null;
-  } catch {
-    return null;
-  }
+  let parsed;
+  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 };
+  return typeof parsed?.secretB58 === "string" ? parsed : null;
 }
 
 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();
-  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 });
-    store = { secretB58: Agent.new().secretB58, created: new Date().toISOString() };
-    writeFileSync(KEYSTORE, JSON.stringify(store, null, 2) + "\n", { mode: 0o600 });
-    chmodSync(KEYSTORE, 0o600); // writeFileSync honours umask; this does not
-    process.stdout.write(`Created ${KEYSTORE} (mode 600).\n\n`);
+    const secretB58 = Agent.new().secretB58;
+    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`,
+    );
+  } else {
+    process.stdout.write(`Existing wallet found at ${KEYSTORE} — keeping it.\n\n`);
+  }
+
+  // The one-time recovery output.
+  //
+  // 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 && 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`,
+    );
   }
 
   const agent = await AiFinPayAgent.fromSolanaSecret(store.secretB58);
@@ -111,13 +204,13 @@ 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" },
             },
           },
@@ -126,11 +219,11 @@ if (arg === "init") {
         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);
 }
@@ -142,31 +235,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,14 +1,47 @@
 /** 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;
     /** Hard cap on a single payment to prevent runaway agents. */
     maxAmountUsd?: number;
+    /** Gateway origins this agent may settle against.
+     *
+     *  The SDK has always supported this (parseGatewayUrl in @aifinpay/agent) and
+     *  this wrapper never exposed it, so a self-hosted merchant was unreachable:
+     *  payable_fetch reached the 402 and then refused with "dev.ratersapp.com is
+     *  not a known AiFinPay gateway; allowed: https://gateway.aifinpay.io".
+     *  Observed in an external E2E run on 2026-08-27.
+     *
+     *  Set by the OPERATOR, exact origins only, never a wildcard. The refusal it
+     *  relaxes is not paranoia: a 402 is unauthenticated, so paying an
+     *  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
+     *  address — an SSRF guard. Behind an HTTP proxy the client cannot resolve at
+     *  all (getaddrinfo EAI_AGAIN), so every host is refused for the wrong reason.
+     *
+     *  This is deliberately NOT a proxy-detection switch that disables the check
+     *  globally: that would turn one environment quirk into a blanket SSRF
+     *  bypass. An operator names the hosts they vouch for, one at a time, and the
+     *  guard stays on for everything else. */
+    trustedHosts?: string[];
     /** Optional log destination (defaults to stderr). */
     logFn?: (level: "info" | "warn" | "error", msg: string) => void;
 }

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,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,CAW7C"}
+{"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,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,CAuB7C"}

package/dist/config.js

@@ -1,5 +1,14 @@
 export function loadConfigFromEnv() {
+    if (process.env.AIFINPAY_MODE && !['live', 'dev'].includes(process.env.AIFINPAY_MODE)) {
+        throw new Error('AIFINPAY_MODE must be live or dev');
+    }
     return {
+        devMode: process.env.AIFINPAY_MODE === 'dev',
+        seedHash: process.env.SEED_HASH,
+        agentsFile: process.env.AIFINPAY_AGENTS_FILE || undefined,
+        agentId: process.env.AIFINPAY_AGENT_ID || undefined,
+        walletHome: process.env.AIFINPAY_HOME || undefined,
+        walletPassphrase: process.env.AIFINPAY_WALLET_PASSPHRASE || undefined,
         agentSecretB58: process.env.AIFINPAY_AGENT_SECRET || undefined,
         baseUrl: process.env.AIFINPAY_BASE_URL || undefined,
         timeoutMs: process.env.AIFINPAY_TIMEOUT_MS
@@ -8,6 +17,60 @@ export function loadConfigFromEnv() {
         maxAmountUsd: process.env.AIFINPAY_MAX_USD
             ? Number(process.env.AIFINPAY_MAX_USD)
             : undefined,
+        gatewayOrigins: splitOrigins(process.env.AIFINPAY_GATEWAY_ORIGINS),
+        gatewayPathMode: parseGatewayPathMode(process.env.AIFINPAY_GATEWAY_PATH_MODE),
+        trustedHosts: splitList(process.env.AIFINPAY_TRUSTED_HOSTS),
     };
 }
+function parseGatewayPathMode(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return "gateway";
+    if (raw === "gateway" || raw === "direct")
+        return raw;
+    throw new Error("AIFINPAY_GATEWAY_PATH_MODE must be either gateway or direct");
+}
+/** Comma-separated list → trimmed entries, or undefined when unset/empty.
+ *  Undefined and [] mean different things downstream: undefined keeps the SDK
+ *  default, [] would mean "no origin is payable". An operator who sets the
+ *  variable to an empty string means the former. */
+function splitList(raw) {
+    if (!raw)
+        return undefined;
+    const out = raw.split(",").map((s) => s.trim()).filter(Boolean);
+    return out.length ? out : undefined;
+}
+/** Same, but each entry must be a bare https origin.
+ *  A path or a wildcard here would read as allowed and match nothing, which is
+ *  the failure that looks like the feature is broken rather than misconfigured. */
+function splitOrigins(raw) {
+    const list = splitList(raw);
+    if (!list)
+        return undefined;
+    for (const entry of list) {
+        let u;
+        try {
+            u = new URL(entry);
+        }
+        catch {
+            throw new Error(`AIFINPAY_GATEWAY_ORIGINS: "${entry}" is not a URL`);
+        }
+        if (u.origin !== entry.replace(/\/+$/, "")) {
+            throw new Error(`AIFINPAY_GATEWAY_ORIGINS: "${entry}" must be a bare origin like https://dev.example.com `
+                + `(got path/query "${u.pathname}${u.search}")`);
+        }
+        // WHATWG URL accepts "*" in a hostname, so new URL("https://*.example.com")
+        // parses and its origin round-trips — the entry would be stored, matched
+        // against nothing, and read as "I allowed this host". Rejecting it here is
+        // the difference between a misconfiguration that says so and one that looks
+        // like the feature is broken.
+        if (!/^[a-z0-9.-]+$/i.test(u.hostname) || u.hostname.startsWith("-") || u.hostname.includes("..")) {
+            throw new Error(`AIFINPAY_GATEWAY_ORIGINS: "${entry}" is not a plain hostname. `
+                + `Wildcards are not supported — name each origin you settle against.`);
+        }
+        if (u.protocol !== "https:" && u.hostname !== "localhost" && u.hostname !== "127.0.0.1") {
+            throw new Error(`AIFINPAY_GATEWAY_ORIGINS: "${entry}" is not https — refusing to settle over plaintext`);
+        }
+    }
+    return list;
+}
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAmBA,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,SAAS;QAC9D,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,SAAS;QACnD,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB;YACxC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;YACzC,CAAC,CAAC,SAAS;QACb,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;YACxC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;YACtC,CAAC,CAAC,SAAS;KACd,CAAC;AACJ,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/identity.d.ts

@@ -0,0 +1,9 @@
+import type { McpConfig } from "./config.js";
+export type WalletIdentity = {
+    source: string;
+    seedHash?: string;
+    secretB58?: string;
+};
+/** Local inputs only. Never put the returned secrets in an MCP response/log. */
+export declare function loadWalletIdentity(config: McpConfig): WalletIdentity | null;
+//# sourceMappingURL=identity.d.ts.map