openzoo 0.4.2 → 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.

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/proxy.js

@@ -104,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);
@@ -154,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) {
@@ -218,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,6 +1,6 @@
 {
   "name": "openzoo",
-  "version": "0.4.2",
+  "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",