openzoo 0.4.1 → 0.5.0

package/README.md

@@ -126,6 +126,39 @@ npx openzoo contexts --forget all     # drop everything
 
 Opt out with `OPENZOO_NO_CONTEXT_CACHE=1` (always ship the full body); tune the threshold with `OPENZOO_CONTEXT_MIN_CHARS` (default 16384 chars).
 
+## Using openzoo from a cloud IDE (Cursor, Windsurf, hosted agents)
+
+Some IDEs run their model calls **from their own servers**, not your machine. Point one of those at `http://localhost:8402` and you get, verbatim:
+
+```
+Provider returned error: Access to private networks is forbidden
+```
+
+That is reachability, not payment — their cloud cannot dial your laptop. Give it a public URL instead:
+
+```bash
+npx openzoo tunnel
+```
+
+It installs `cloudflared` itself (one-time, cached in `~/.openzoo/bin`; a Cloudflare account is not needed), opens a quick tunnel to your local proxy, and prints:
+
+```
+base_url = https://<random>.trycloudflare.com/v1
+api_key  = oz_<random>          # in tunnel mode the key is REAL auth
+```
+
+**Tunnel mode is the one mode where the api key matters.** A public URL in front of a wallet is a public URL in front of your money, so:
+
+- every request without `Authorization: Bearer <that key>` is refused **401** before anything is forwarded, quoted or paid;
+- the per-call cap (`OPENZOO_MAX_USD_PER_CALL`, default $0.50) still applies;
+- a session ceiling stops all spending at `OPENZOO_TUNNEL_MAX_USD` (default **$1.00**);
+- every served request prints its receipt and the running session total;
+- the URL dies when you Ctrl-C, and the session's total spend is printed on exit.
+
+Pin the key with `OPENZOO_TUNNEL_TOKEN` if your IDE stores it. Keys never leave your machine either way — the tunnel forwards to the same local proxy, which signs with the same local wallet.
+
+**MCP clients don't need any of this.** If your tool speaks MCP, use the hosted server at `https://mcp.openzoo.fun/mcp` — cloud-reachable, no local process, mint a wallet with `zoo_wallet`.
+
 ## The wallet model
 
 - **Burner, local, yours.** A keypair in `~/.openzoo/wallet.json`, created on first run, chmod 600. Keys never leave your machine — the zoo only ever sees signed transfers.
@@ -152,8 +185,10 @@ The receipt names which base you got; `extra.directUsd` / `extra.savesVsDirect`
 | rail | network | status |
 |---|---|---|
 | **Solana** (default) | `solana:5eykt…` | **live** — Token-2022 `TransferChecked`, partial-signed, gateway pays fees. Tested end-to-end against the production 402. Settlement uses a wrapped settlement mint as internal plumbing; you only ever hold and send USDC or TOKEN. |
-| Base | `eip155:8453` | implemented (standard x402 EIP-3009 `transferWithAuthorization`), **live-untested** — the zoo's 402s currently offer only Solana rows. |
-| Robinhood Chain | `eip155:4663` | experimental, behind `OPENZOO_ENABLE_RH=1` — the zoo ships this rail dark and facilitator settlement there is unverified. |
+| Base | `eip155:8453` | **offered by the zoo** — standard x402 EIP-3009 `transferWithAuthorization` against native USDC. Fund the wallet's EVM address with USDC on Base; nothing is converted. Settlement from this package is live-untested. |
+| Robinhood Chain | `eip155:4663` | experimental, behind `OPENZOO_ENABLE_RH=1`. The zoo quotes it, but its settlement asset has no conversion path here (conversion is Solana-only), so there is no plain balance you can fund and have the shim spend — use Solana or Base. |
+
+`npx openzoo` prints the rails off a live 402 at startup, and the funding line is derived from those rails — so a new chain shows up without this package shipping again.
 
 The rail is chosen from the 402's `accepts[]` itself (Solana first). Amounts are always taken as raw units from the 402, and Solana decimals are read from the mint **on-chain** — never hardcoded. (The zoo's own pasted prompt hardcodes `decimals = 6`; that's wrong for 18-decimal mints and this package deliberately does not copy the bug.)
 

package/bin/openzoo.js

@@ -6,6 +6,8 @@ const HELP = `openzoo — local x402-paying proxy + MCP server for openzoo.fun
 usage:
   npx openzoo            start the proxy on http://localhost:8402/v1
   npx openzoo mcp        stdio MCP server (tools: zoo_ask, zoo_models, zoo_wallet)
+  npx openzoo tunnel     public HTTPS url for cloud IDEs that cannot reach localhost
+                         (installs cloudflared itself; mints a required api key)
   npx openzoo demo       ~1M-token needle demo: direct refuses, the zoo answers
                          (run it twice — the second run reuses the bound corpus and is near-free)
   npx openzoo contexts   list corpora bound to the zoo (never re-uploaded)
@@ -24,7 +26,8 @@ env:
   OPENZOO_MAX_USD_PER_CALL (0.5)  OPENZOO_DEMO_MAX_USD (0.01)
   OPENZOO_CONTEXT_MIN_CHARS (16384 — bodies bigger than this bind once + reuse)
   OPENZOO_NO_CONTEXT_CACHE (0 — set 1 to always ship the full body)
-  OPENZOO_ENABLE_RH (0 — Robinhood Chain rail, experimental)`;
+  OPENZOO_ENABLE_RH (0 — Robinhood Chain rail, experimental)
+  OPENZOO_TUNNEL_MAX_USD (1.00 — tunnel session ceiling)  OPENZOO_TUNNEL_TOKEN (pin the api key)`;
 
 async function main() {
   switch (cmd) {
@@ -35,6 +38,9 @@ async function main() {
     case 'mcp':
       await (await import('../lib/mcp.js')).startMcp();
       break;
+    case 'tunnel':
+      await (await import('../lib/tunnel.js')).runTunnel();
+      break;
     case 'demo':
       await (await import('../lib/demo.js')).runDemo();
       break;

package/lib/config.js

@@ -28,9 +28,57 @@ export const FUNDING_ASSETS = [
 export const USDC_MINT = FUNDING_ASSETS[0].mint;
 export const TOKEN_MINT = FUNDING_ASSETS[1].mint;
 
-/** The one canonical way to tell a user how to fund. */
+/**
+ * The one canonical way to tell a user how to fund the SOLANA rail. Callers
+ * pass the Solana address; the rail is named explicitly because the wallet
+ * also has an EVM address for the Base / Robinhood rails.
+ */
 export function fundingLine(address) {
-  return `send a few cents of USDC (${USDC_MINT}) or TOKEN (${TOKEN_MINT}) to ${address}`;
+  return `send a few cents of USDC (${USDC_MINT}) or TOKEN (${TOKEN_MINT}) on Solana to ${address}`;
+}
+
+/**
+ * What a user funds each rail with — UNDERLYING assets only, and only assets
+ * this shim can actually spend from. The settlement mints the 402 quotes are
+ * internal plumbing and never appear in user-facing copy.
+ *
+ * Solana: quoted in settlement mints, converted from plain USDC / TOKEN at
+ *   payment time (lib/wrap.js).
+ * Base:   quoted in native USDC — funded and spent as-is, no conversion.
+ * Robinhood: quoted in a settlement asset with no conversion path on EVM
+ *   (wrapping is Solana-only), so there is no plain balance a user can fund
+ *   and have the shim pay from — hence no assets, and no funding line.
+ */
+export const RAIL_FUNDING = {
+  solana: { label: 'Solana', assets: ['USDC', 'TOKEN'] },
+  base: { label: 'Base', assets: ['USDC'] },
+  robinhood: { label: 'Robinhood Chain', assets: [] },
+};
+
+/**
+ * "USDC or TOKEN on Solana · USDC on Base" — the funding hint for exactly the
+ * rails a live 402 is offering, derived from liveRails().live. Rails with no
+ * fundable underlying, and networks we have no funding copy for (an
+ * unrecognised chain the zoo starts quoting), are left out rather than guessed
+ * at. Returns '' when nothing is fundable.
+ */
+export function railFundingHint(liveRailNames) {
+  return (liveRailNames || [])
+    .map((rail) => RAIL_FUNDING[rail])
+    .filter((spec) => spec?.assets.length)
+    .map((spec) => `${spec.assets.join(' or ')} on ${spec.label}`)
+    .join(' · ');
+}
+
+/**
+ * Rails the zoo is quoting right now that this shim cannot pay from a plain
+ * funded balance — named so a live rail never silently disappears from the
+ * funding advice.
+ */
+export function unfundableRails(liveRailNames) {
+  return (liveRailNames || [])
+    .filter((rail) => RAIL_FUNDING[rail] && !RAIL_FUNDING[rail].assets.length)
+    .map((rail) => RAIL_FUNDING[rail].label);
 }
 
 /**

package/lib/info.js

@@ -8,7 +8,7 @@ export function printAddress() {
   const { keypair, evmPrivateKey, created, path } = loadOrCreateWallet();
   if (created) console.log(`new burner wallet created at ${path} (chmod 600)`);
   console.log(keypair.publicKey.toBase58());
-  console.log(`(evm, for Base/RH rails — untested: ${privateKeyToAccount(evmPrivateKey).address})`);
+  console.log(`(evm, for the Base / Robinhood rails: ${privateKeyToAccount(evmPrivateKey).address})`);
 }
 
 export async function printBalance() {

package/lib/mcp.js

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { config, FUNDING_ASSETS } from './config.js';
+import { config, FUNDING_ASSETS, liveRails, railFundingHint } from './config.js';
 import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { tokenBalance } from './x402.js';
 import { askWithContext, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
@@ -94,10 +94,17 @@ export async function startMcp() {
     ]);
     const balances = { SOL: lamports / 1e9 };
     FUNDING_ASSETS.forEach((a, i) => { balances[a.symbol] = bals[i].ui ?? 0; });
+    // Funding advice follows the rails the zoo is quoting right now, not a
+    // hardcoded Solana assumption. Fail soft: the probe is advisory.
+    const rails = await liveRails().catch(() => null);
+    const hint = rails ? railFundingHint(rails.live) : '';
     return text({
       solanaAddress: client.address,
-      fundWith: FUNDING_ASSETS.map((a) => `${a.symbol} (${a.mint})`).join(' or '),
-      fundHint: 'send a few cents of either to this address — the shim wraps whichever the 402 quotes, at payment time',
+      evmAddress: client.evmAddress,
+      railsLiveNow: rails?.live ?? null,
+      fundWith: hint || `${FUNDING_ASSETS.map((a) => a.symbol).join(' or ')} on Solana`,
+      solanaMints: Object.fromEntries(FUNDING_ASSETS.map((a) => [a.symbol, a.mint])),
+      fundHint: 'send a few cents of a listed asset to the address for that rail — Solana assets to solanaAddress, Base assets to evmAddress. The shim converts to whatever the 402 quotes, at payment time.',
       balances,
       receipts: client.receipts.map((r) => ({ at: r.at, line: r.line })),
     });

package/lib/proxy.js

@@ -1,6 +1,8 @@
 import http from 'node:http';
 import { Readable } from 'node:stream';
-import { config, FUNDING_ASSETS, fundingLine, liveRails } from './config.js';
+import {
+  config, FUNDING_ASSETS, fundingLine, liveRails, railFundingHint, unfundableRails, RAIL_FUNDING,
+} from './config.js';
 import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { tokenBalance } from './x402.js';
 import { bindCorpus, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
@@ -102,12 +104,32 @@ async function maybeCacheCorpus(req, bodyBuf, log) {
   };
 }
 
-export async function startProxy({ silent = false } = {}) {
+/**
+ * `requireToken` / `sessionMaxUsd` are TUNNEL MODE (see lib/tunnel.js): once the
+ * proxy is reachable from the internet, the api key stops being decorative and
+ * becomes the only thing between a stranger and your wallet. Both are off by
+ * default, so localhost behaviour is unchanged.
+ */
+export async function startProxy({ silent = false, requireToken = null, sessionMaxUsd = null } = {}) {
   const client = new PayClient();
   const log = silent ? () => {} : (...a) => console.log(...a);
+  let sessionSpent = 0;
 
   const server = http.createServer(async (req, res) => {
     const url = `${config.apiBase}${req.url}`;
+    // Auth first: refuse before reading a body, forwarding, quoting or paying.
+    if (requireToken) {
+      const got = (req.headers.authorization || '').replace(/^Bearer\s+/i, '').trim();
+      if (got !== requireToken) {
+        log(`tunnel: 401 ${req.method} ${req.url} from ${req.socket.remoteAddress}`);
+        jsonErr(res, 401, 'unauthorized: this openzoo tunnel requires the api key printed at startup');
+        return;
+      }
+      if (sessionMaxUsd != null && sessionSpent >= sessionMaxUsd) {
+        jsonErr(res, 402, `openzoo tunnel session cap reached ($${sessionMaxUsd}) — restart the tunnel or raise OPENZOO_TUNNEL_MAX_USD`);
+        return;
+      }
+    }
     let bodyBuf;
     try {
       bodyBuf = await readBody(req);
@@ -152,7 +174,13 @@ export async function startProxy({ silent = false } = {}) {
         result = await client.fetch(url, init);
       }
       const { response, paid, receipt } = result;
-      if (paid && receipt) log(receipt.ok ? receipt.line : `paid retry -> HTTP ${receipt.status}`);
+      if (paid && receipt) {
+        if (receipt.ok && typeof receipt.billedUsd === 'number') sessionSpent += receipt.billedUsd;
+        const line = receipt.ok ? receipt.line : `paid retry -> HTTP ${receipt.status}`;
+        // In tunnel mode the running total is the thing you actually want to
+        // watch, so it rides on every receipt.
+        log(requireToken ? `${line}  ·  session $${sessionSpent.toFixed(6)}` : line);
+      }
       await relay(res, response);
     } catch (err) {
       if (err instanceof QuoteTooHighError) {
@@ -194,7 +222,17 @@ export async function startProxy({ silent = false } = {}) {
     try {
       const rails = await liveRails();
       if (rails) {
-        console.log(`rails live now: ${rails.live.join(' · ')}  (fund with USDC or TOKEN on solana)`);
+        console.log(`rails live now: ${rails.live.join(' · ')}`);
+        // Funding advice is derived from those rails, never hardcoded — the
+        // zoo can add a chain without this package shipping again.
+        const hint = railFundingHint(rails.live);
+        if (hint) console.log(`fund with:      ${hint}`);
+        const unfundable = unfundableRails(rails.live);
+        if (unfundable.length) {
+          const fundable = rails.live.filter((r) => RAIL_FUNDING[r]?.assets.length).map((r) => RAIL_FUNDING[r].label);
+          const instead = fundable.length ? `pay from ${fundable.join(' or ')} instead` : 'no fundable rail is offered right now';
+          console.log(`note:           ${unfundable.join(' / ')} is offered by the zoo but not fundable from a plain balance here — ${instead}.`);
+        }
         if (rails.dark.length) {
           const rh = rails.dark.includes('robinhood') ? ' — robinhood also needs OPENZOO_ENABLE_RH=1' : '';
           console.log(`rails implemented but not offered by the zoo right now: ${rails.dark.join(' · ')}${rh}`);
@@ -206,5 +244,5 @@ export async function startProxy({ silent = false } = {}) {
     console.log(`  base_url = http://localhost:${config.port}/v1`);
     console.log('  api_key  = sk-openzoo   (any value works; the zoo takes payment, not keys)');
   }
-  return { server, client };
+  return { server, client, spent: () => sessionSpent };
 }

package/lib/tunnel.js

@@ -0,0 +1,156 @@
+/**
+ * `npx openzoo tunnel` — make the local paying proxy reachable from a CLOUD-run
+ * harness.
+ *
+ * WHY THIS EXISTS: IDEs that execute model calls from their own servers cannot
+ * dial your laptop. Pointing one at http://localhost:8402 returns, verbatim:
+ *   "Provider returned error: Access to private networks is forbidden"
+ * The payment path is fine — the harness just can't reach it. A tunnel gives
+ * that harness a public HTTPS URL while your keys stay on this machine.
+ *
+ * SELF-PROVISIONING: we do not ask you to install anything. If `cloudflared`
+ * isn't on PATH we fetch the single static binary for this platform into
+ * ~/.openzoo/bin and cache it. Quick tunnels need no Cloudflare account.
+ *
+ * SECURITY IS THE DESIGN. A public URL in front of a wallet is a public URL in
+ * front of your money, so tunnel mode is the ONE mode where the api key is real:
+ *   - a random bearer token is minted per session and REQUIRED (401 otherwise),
+ *     checked before anything is forwarded, quoted, or paid;
+ *   - the per-call cap (OPENZOO_MAX_USD_PER_CALL) still applies, and a session
+ *     ceiling (OPENZOO_TUNNEL_MAX_USD, default $1) stops paying when reached;
+ *   - every tunnel-served request is logged with its running spend.
+ */
+import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+
+const BIN_DIR = path.join(os.homedir(), '.openzoo', 'bin');
+
+/** cloudflared publishes one static binary per platform; pick ours. */
+function cloudflaredAsset() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === 'darwin') return { name: 'cloudflared-darwin-amd64.tgz', tgz: true };
+  if (p === 'linux') {
+    const arch = a === 'arm64' ? 'arm64' : a === 'arm' ? 'arm' : 'amd64';
+    return { name: `cloudflared-linux-${arch}`, tgz: false };
+  }
+  if (p === 'win32') return { name: 'cloudflared-windows-amd64.exe', tgz: false };
+  return null;
+}
+
+function onPath(bin) {
+  const dirs = (process.env.PATH || '').split(path.delimiter);
+  for (const d of dirs) {
+    const f = path.join(d, bin);
+    try { fs.accessSync(f, fs.constants.X_OK); return f; } catch { /* keep looking */ }
+  }
+  return null;
+}
+
+/**
+ * Return a usable cloudflared path, downloading it if needed. Order: PATH, our
+ * cache, then the official GitHub release. macOS ships a .tgz; the others are
+ * bare binaries.
+ */
+export async function ensureCloudflared(log = console.log) {
+  const found = onPath(process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared');
+  if (found) return found;
+
+  const cached = path.join(BIN_DIR, process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared');
+  try { fs.accessSync(cached, fs.constants.X_OK); return cached; } catch { /* fetch it */ }
+
+  const asset = cloudflaredAsset();
+  if (!asset) throw new Error(`no cloudflared build for ${process.platform}/${process.arch} — install it manually and re-run`);
+
+  fs.mkdirSync(BIN_DIR, { recursive: true, mode: 0o700 });
+  const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/${asset.name}`;
+  log(`fetching cloudflared for ${process.platform}/${process.arch} (one-time, ~35MB)...`);
+  const r = await fetch(url, { redirect: 'follow' });
+  if (!r.ok) throw new Error(`cloudflared download failed: HTTP ${r.status}`);
+
+  if (asset.tgz) {
+    const tgz = path.join(BIN_DIR, 'cloudflared.tgz');
+    await pipeline(Readable.fromWeb(r.body), createWriteStream(tgz));
+    await new Promise((resolve, reject) => {
+      const t = spawn('tar', ['xzf', tgz, '-C', BIN_DIR], { stdio: 'ignore' });
+      t.on('exit', (c) => (c === 0 ? resolve() : reject(new Error(`tar exited ${c}`))));
+      t.on('error', reject);
+    });
+    fs.rmSync(tgz, { force: true });
+  } else {
+    await pipeline(Readable.fromWeb(r.body), createWriteStream(cached));
+  }
+  fs.chmodSync(cached, 0o755);
+  log(`cloudflared cached at ${cached}`);
+  return cached;
+}
+
+/** Start a quick tunnel to localhost:<port>; resolve with its public URL. */
+export function startCloudflared(bin, port, log) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(bin, ['tunnel', '--url', `http://localhost:${port}`, '--no-autoupdate'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let settled = false;
+    const scan = (buf) => {
+      const m = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i.exec(buf.toString());
+      if (m && !settled) { settled = true; resolve({ url: m[0], proc }); }
+    };
+    proc.stdout.on('data', scan);
+    proc.stderr.on('data', scan); // cloudflared prints the URL on stderr
+    proc.on('error', reject);
+    proc.on('exit', (c) => { if (!settled) reject(new Error(`cloudflared exited ${c} before printing a URL`)); });
+    setTimeout(() => { if (!settled) reject(new Error('cloudflared did not produce a URL in 60s')); }, 60000);
+  });
+}
+
+export function mintToken() {
+  return process.env.OPENZOO_TUNNEL_TOKEN || `oz_${crypto.randomBytes(24).toString('base64url')}`;
+}
+
+export async function runTunnel() {
+  const { startProxy } = await import('./proxy.js');
+  const { config } = await import('./config.js');
+
+  const token = mintToken();
+  const sessionCap = Number(process.env.OPENZOO_TUNNEL_MAX_USD || 1);
+
+  // The proxy enforces the gate itself: nothing is forwarded, quoted or paid
+  // without the bearer token, and the session ceiling stops spend cold.
+  const { spent } = await startProxy({
+    silent: true,
+    requireToken: token,
+    sessionMaxUsd: sessionCap,
+  });
+
+  const bin = await ensureCloudflared();
+  const { url, proc } = await startCloudflared(bin, config.port, console.log);
+
+  console.log('');
+  console.log('  ┌─────────────────────────────────────────────────────────────');
+  console.log('  │  THIS URL SPENDS REAL MONEY FROM YOUR WALLET.');
+  console.log('  │  The token below is the only thing protecting it.');
+  console.log(`  │  Session ceiling: $${sessionCap.toFixed(2)} — then it stops paying.`);
+  console.log('  │  Ctrl-C when you are done; the URL dies with this process.');
+  console.log('  └─────────────────────────────────────────────────────────────');
+  console.log('');
+  console.log('point your cloud IDE at:');
+  console.log(`  base_url = ${url}/v1`);
+  console.log(`  api_key  = ${token}`);
+  console.log('');
+
+  const shutdown = () => {
+    try { proc.kill('SIGTERM'); } catch { /* already gone */ }
+    const total = typeof spent === 'function' ? spent() : 0;
+    console.log(`\ntunnel closed — session spend $${total.toFixed(6)}`);
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openzoo",
-  "version": "0.4.1",
-  "description": "Local x402-paying proxy + MCP server for openzoo.fun — point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana rail live; Base/Robinhood rails experimental.",
+  "version": "0.5.0",
+  "description": "Local x402-paying proxy + MCP server for openzoo.fun — point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental.",
   "license": "MIT",
   "type": "module",
   "bin": {