@claw-link/gateway-host 0.3.2 → 0.3.4

package/native/index.d.ts

@@ -34,20 +34,35 @@ export declare function assemble(parts: Array<Buffer>, expectedCid: string): Buf
 /** Native-core version (so the host can log which acceleration tier is active). */
 export declare function coreVersion(): string
 /**
- * A QUIC peer-to-peer Capsule-byte transport (AHP H2H data plane).
+ * An **iroh** peer-to-peer Capsule-byte transport (AHP H2H data plane).
  *
  * Bytes are AEAD-encrypted, content-addressed (`b3_<blake3>`), stored locally, and fetched from a
- * peer's announced socket address over QUIC. See `transport.rs` for the full design + TLS posture.
+ * peer over iroh's mutually-authenticated, NAT-traversing QUIC (hole-punch + relay fallback). Peers
+ * are addressed by their full `EndpointAddr` (NodeId + relay + direct addrs), handed over your own
+ * signaling — NOT via public discovery. See `transport.rs` for the full security posture.
  */
 export declare class Transport {
-  /** Create a transport: bind a QUIC endpoint on an OS-assigned port and start serving. */
-  static create(): Promise<Transport>
-  /** The socket address to announce to peers, e.g. "127.0.0.1:54321". */
-  localAddr(): string
+  /**
+   * Build the iroh endpoint and start serving.
+   *
+   * * `secretKeyHex` — 32-byte Ed25519 secret key as hex (the node's persistent identity; its
+   *   public key is the iroh NodeId). If omitted, a fresh key is generated — read it back via
+   *   `secretKeyHex()` and persist it for a stable identity across restarts.
+   * * `relayUrl` — optional relay base URL for connectivity / hole-punch. The relay is UNTRUSTED
+   *   (it only ever relays E2E-encrypted QUIC). Omit to use iroh's standard n0 relays.
+   */
+  static create(secretKeyHex?: string | undefined | null, relayUrl?: string | undefined | null): Promise<Transport>
+  /**
+   * This node's full reachability as a JSON string (NodeId + relay url + known direct socket
+   * addrs). Store it and hand it to a peer so it can dial us — no public discovery involved.
+   */
+  nodeAddr(): Promise<string>
+  /** The node's Ed25519 secret key as hex (so the host can persist a stable identity). */
+  secretKeyHex(): string
   /** AEAD-encrypt `bytes` with the 32-byte `key`, store the ciphertext, and return its cid. */
   add(bytes: Buffer, key: Buffer): string
-  /** Fetch `cid` from `peerAddr` over QUIC, verify integrity, and AEAD-decrypt with `key`. */
-  fetch(cid: string, peerAddr: string, key: Buffer): Promise<Buffer>
+  /** Fetch `cid` from `peerNodeAddr` over iroh, verify integrity, and AEAD-decrypt with `key`. */
+  fetch(cid: string, peerNodeAddr: string, key: Buffer): Promise<Buffer>
   /** Does the local store hold this cid? */
   has(cid: string): boolean
   /** Close the endpoint (stops serving; in-flight transfers drain). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claw-link/gateway-host",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "ClawLink Host Gateway — a secure, outbound-only worker that bridges a local agent CLI (OpenClaw, Hermes, Claude, Codex, Cursor) to your ClawLink agents. No inbound ports; authenticated per-agent by a Host Token.",
   "homepage": "https://claw-link.co",
   "bin": {

package/scripts/p2p-test.js

@@ -6,22 +6,26 @@ const crypto = require('crypto');
 const core = require('../src/transport/core');
 
 async function run() {
+  // The self-test transfers over loopback, which the SSRF address-filter blocks by default — allow
+  // LAN/loopback just for this in-process test (does not affect the running service).
+  process.env.CLAWHOST_ALLOW_LAN = process.env.CLAWHOST_ALLOW_LAN || '1';
   if (!core.available || !core.Transport) {
     console.log('Native H2H core is NOT installed for this platform.');
     console.log('The host works fine — Capsule bytes route through the central relay (no P2P speedup).');
     console.log('To enable acceleration, install the @claw-link/harness-core binary for your platform.');
     return;
   }
-  console.log(`Native H2H core v${core.version} — running QUIC P2P self-test (loopback)…\n`);
+  console.log(`Native H2H core v${core.version} — running iroh QUIC P2P self-test (loopback)…\n`);
   const a = await core.Transport.create();
   const b = await core.Transport.create();
+  const aAddr = await a.nodeAddr();
   try {
     const key = crypto.randomBytes(32);
     for (const n of [4 * 1024, 1024 * 1024, 8 * 1024 * 1024]) {
       const data = crypto.randomBytes(n);
       const cid = a.add(data, key);
       const t0 = Date.now();
-      const got = await b.fetch(cid, a.localAddr(), key);
+      const got = await b.fetch(cid, aAddr, key);
       const ms = Date.now() - t0;
       if (Buffer.compare(got, data) !== 0) throw new Error(`integrity mismatch at ${n} bytes`);
       const mib = (n / (1024 * 1024));
@@ -29,9 +33,9 @@ async function run() {
     }
     const cid = a.add(Buffer.from('secret'), key);
     let wrongKey = false;
-    try { await b.fetch(cid, a.localAddr(), crypto.randomBytes(32)); } catch { wrongKey = true; }
+    try { await b.fetch(cid, aAddr, crypto.randomBytes(32)); } catch { wrongKey = true; }
     let unknown = false;
-    try { await b.fetch('b3_0000', a.localAddr(), key); } catch { unknown = true; }
+    try { await b.fetch('b3_0000', aAddr, key); } catch { unknown = true; }
     console.log(`\n  AEAD: wrong key rejected   ${wrongKey ? 'OK' : 'FAIL'}`);
     console.log(`  integrity: unknown cid rejected   ${unknown ? 'OK' : 'FAIL'}`);
     if (!wrongKey || !unknown) throw new Error('security checks failed');

package/src/bridge.js

@@ -46,7 +46,7 @@ class Bridge {
   capsuleGet(path) { return this._post('capsule_get', { path }); }
   // H2H peer discovery for the QUIC P2P transport (central relay is the fallback).
   transportAnnounce(cid, addr) { return this._post('transport_announce', { cid, addr }); }
-  transportResolve(cid) { return this._post('transport_resolve', { cid }); }
+  transportResolve(cid, jobId) { return this._post('transport_resolve', { cid, job_id: jobId }); }
   transportSession(cid, mode, bytes) { return this._post('transport_session', { cid, mode, bytes }); }
   // DB floor for a transport ref: fetch the inline plaintext for a transport_cid this job may see.
   capsuleContent(cid, jobId) { return this._post('capsule_content', { cid, job_id: jobId }); }

package/src/transport/p2p.js

@@ -1,84 +1,98 @@
 'use strict';
-// Host-side H2H transport orchestration: wraps the native QUIC Transport (when a prebuilt core is
-// present) with central-relay discovery + fallback. ACCELERATION, NEVER A DEPENDENCY — if the core
-// is absent or a P2P fetch fails, callers fall back to host-bridge capsule_put/capsule_get.
+// Host-side H2H transport orchestration over the native iroh core: secure, NAT-traversing QUIC.
+// Peers are addressed by their iroh NodeAddr (NodeId = Ed25519 public key → mutual auth, no MITM;
+// hole-punch + relay fallback handle NAT). Discovery rides our authenticated host-bridge signaling
+// (transport_announce/resolve), NOT iroh's public DNS. ACCELERATION, NEVER A DEPENDENCY — no core,
+// or a fetch that can't connect, falls back to the central relay (the caller handles that).
 //
-// Flow:
-//   producer:  cid = await p2p.offer(bridge, plaintext, key)   // encrypt+store locally, announce
-//   consumer:  buf = await p2p.fetch(bridge, cid, key)         // resolve a peer + P2P fetch, else null
+//   producer:  cid = await p2p.offer(bridge, plaintext, key)   // store + announce our NodeAddr
+//   consumer:  buf = await p2p.fetch(bridge, cid, key)         // resolve peer NodeAddr + fetch, else null
 //
-// `key` is a 32-byte Buffer (the per-transfer AEAD key, derived from the capsule's authorization).
-const os = require('os');
+// `key` is the 32-byte per-blob AEAD key (the authorization layer on top of the authenticated link).
+const fs = require('fs');
+const path = require('path');
 const core = require('./core');
+const config = require('../config');
 
-// The QUIC socket binds 0.0.0.0 (all interfaces), but the native local_addr() reports 127.0.0.1 —
-// dialable only on THIS machine. For Mac↔Mac on a LAN we must announce a routable IPv4 instead.
-// (Cross-network/NAT hole-punching is a later rung; a peer that can't be reached falls back to relay.)
-function lanIpv4() {
-  for (const list of Object.values(os.networkInterfaces())) {
-    for (const i of list || []) {
-      if (i && i.family === 'IPv4' && !i.internal) return i.address;
-    }
-  }
-  return null;
-}
+// Stable node identity (Ed25519 secret key) so a host keeps the same NodeId across restarts.
+const KEY_PATH = path.join(config.HOME_DIR, 'transport.key');
 
 class P2P {
   constructor(logger) {
     this.logger = logger || { info() {}, warn() {} };
     this.node = null;
     this.starting = null;
-    this.announceAddr = null; // routable addr we hand to peers (LAN IP : QUIC port)
+    this.addr = null; // our NodeAddr (JSON string) to hand to peers
   }
 
   available() {
     return !!(core.available && core.Transport);
   }
 
-  /** Start the native QUIC node once (idempotent). Returns the routable announce addr, or null. */
+  _loadKey() {
+    try {
+      const st = fs.statSync(KEY_PATH);
+      // The node secret is impersonation-grade — tighten perms if a backup/umask left it loose.
+      if (st.mode & 0o077) { try { fs.chmodSync(KEY_PATH, 0o600); this.logger.warn('tightened transport.key permissions to 600'); } catch { /* best effort */ } }
+      const k = fs.readFileSync(KEY_PATH, 'utf8').trim();
+      if (/^[0-9a-f]{64}$/i.test(k)) return k;
+    } catch { /* none */ }
+    return null;
+  }
+  _saveKey(hex) {
+    try { if (config.ensureHomeDir) config.ensureHomeDir(); fs.writeFileSync(KEY_PATH, hex, { mode: 0o600 }); }
+    catch (e) { this.logger.warn('could not persist transport identity:', e.message); }
+  }
+
+  /** Start the iroh node once (idempotent). Returns our NodeAddr string, or null. */
   async start() {
     if (!this.available()) return null;
-    if (this.announceAddr) return this.announceAddr;
+    if (this.addr) return this.addr;
     if (!this.starting) {
-      this.starting = core.Transport.create()
-        .then((n) => {
-          this.node = n;
-          const port = String(n.localAddr()).split(':').pop();
-          const ip = lanIpv4();
-          this.announceAddr = ip ? `${ip}:${port}` : n.localAddr(); // routable from other LAN hosts
-          this.logger.info(`p2p transport up (core ${core.version}) listening :${port}, announce ${this.announceAddr}`);
-          return n;
-        })
-        .catch((e) => { this.logger.warn('p2p transport start failed (using central relay):', e.message); this.node = null; return null; });
+      const relayUrl = process.env.CLAWHOST_RELAY_URL || undefined; // undefined → default relays
+      this.starting = (async () => {
+        const keyHex = this._loadKey() || undefined;
+        const node = await core.Transport.create(keyHex, relayUrl);
+        this.node = node;
+        if (!keyHex) this._saveKey(node.secretKeyHex()); // persist a freshly-generated identity
+        this.addr = await node.nodeAddr();
+        let id = '?'; try { id = JSON.parse(this.addr).id.slice(0, 12); } catch { /* keep ? */ }
+        this.logger.info(`p2p transport up (core ${core.version}) node ${id}…${relayUrl ? ` relay ${relayUrl}` : ' (default relays)'}`);
+        return node;
+      })().catch((e) => { this.logger.warn('p2p transport start failed (using central relay):', e.message); this.node = null; this.addr = null; return null; });
     }
     await this.starting;
-    return this.node ? this.announceAddr : null;
+    return this.addr;
   }
 
-  /** Offer a blob for P2P fetch: AEAD-encrypt + store locally, announce cid→addr. Returns cid|null. */
-  async offer(bridge, plaintext, key) {
+  /** AEAD-encrypt + store a blob locally for P2P serving; returns its cid. Does NOT announce yet —
+   *  the capsule must be persisted first so the server can authorize the announce. null if unavailable. */
+  async addBlob(plaintext, key) {
     const addr = await this.start();
     if (!addr || !this.node) return null;
-    let cid;
-    try { cid = this.node.add(plaintext, key); } catch (e) { this.logger.warn('p2p add failed:', e.message); return null; }
-    try { await bridge.transportAnnounce(cid, addr); } catch (e) { this.logger.warn('p2p announce failed:', e.message); }
-    return cid;
+    try { return this.node.add(plaintext, key); } catch (e) { this.logger.warn('p2p add failed:', e.message); return null; }
+  }
+
+  /** Announce a previously-added cid to the directory (call AFTER the capsule is persisted, so the
+   *  server can verify this host is the producer). */
+  async announce(bridge, cid) {
+    if (!this.addr || !cid) return;
+    try { await bridge.transportAnnounce(cid, this.addr); } catch (e) { this.logger.warn('p2p announce failed:', e.message); }
   }
 
-  /** Fetch a blob by cid via P2P (resolve peer → fetch). Returns the plaintext Buffer, or null to
-   *  signal the caller should fall back to the central relay. */
-  async fetch(bridge, cid, key) {
+  /** Fetch a blob by cid for a given job: resolve a peer NodeAddr (authorized via job.sees) + fetch
+   *  over iroh. Returns plaintext Buffer, or null to fall back to the central relay. */
+  async fetch(bridge, cid, key, jobId) {
     if (!this.available()) return null;
     await this.start();
     if (!this.node) return null;
     let peer = null;
-    try { const r = await bridge.transportResolve(cid); peer = r && r.peer; } catch { peer = null; }
-    if (!peer || !peer.addr) return null; // no P2P source → relay
+    try { const r = await bridge.transportResolve(cid, jobId); peer = r && r.peer; } catch { peer = null; }
+    if (!peer || !peer.addr) return null; // no authorized P2P source → relay
     try {
       const t0 = Date.now();
       const buf = await this.node.fetch(cid, peer.addr, key);
-      const ms = Date.now() - t0;
-      this.logger.info(`p2p fetch ${cid.slice(0, 14)}… ${buf.length}B from ${peer.addr} in ${ms}ms`);
+      this.logger.info(`p2p fetch ${cid.slice(0, 14)}… ${buf.length}B in ${Date.now() - t0}ms`);
       bridge.transportSession(cid, 'p2p', buf.length).catch(() => {});
       return buf;
     } catch (e) {
@@ -90,6 +104,7 @@ class P2P {
   close() {
     if (this.node) { try { this.node.close(); } catch { /* ignore */ } this.node = null; }
     this.starting = null;
+    this.addr = null;
   }
 }
 

package/src/worker.js

@@ -37,7 +37,7 @@ async function resolveTransport(bridge, p2p, job) {
     let text = null;
     if (p2p && p2p.available()) {
       try {
-        const buf = await p2p.fetch(bridge, ref.cid, Buffer.from(ref.key, 'hex'));
+        const buf = await p2p.fetch(bridge, ref.cid, Buffer.from(ref.key, 'hex'), job.id);
         if (buf) text = buf.toString('utf8');
       } catch (e) { logger.warn(`p2p resolve ${ref.cid.slice(0, 14)}… failed: ${e.message}`); }
     }
@@ -69,20 +69,23 @@ async function processJob(bridge, agentCfg, job, p2p) {
       try { await bridge.stream(job.id, seq++, evt.type, String(evt.content ?? '')); }
       catch (e) { logger.warn(`stream seq ${seq} failed: ${e.message}`); }
     }
-    // H2H: offer a large result for P2P fetch by the next node's host (inline copy stays the floor).
-    let transport;
+    // H2H: store a large result for P2P fetch by the next node's host (inline copy stays the floor).
+    // We add+ref it before complete(), but ANNOUNCE only AFTER complete() persists the capsule — so
+    // the directory can verify this host is the producer before listing it.
+    let transport, offerCid;
     try {
       const buf = Buffer.from(finalText, 'utf8');
       if (p2p && p2p.available() && job.harness && buf.length > TRANSPORT_MIN_BYTES) {
         const key = crypto.randomBytes(32);
-        const cid = await p2p.offer(bridge, buf, key);
-        if (cid) transport = { cid, key: key.toString('hex'), size: buf.length };
+        offerCid = await p2p.addBlob(buf, key);
+        if (offerCid) transport = { cid: offerCid, key: key.toString('hex'), size: buf.length };
       }
     } catch (e) { logger.warn(`p2p offer failed: ${e.message}`); }
     const meta = {};
     if (toolCalls.length) meta.tool_calls = toolCalls;
     if (transport) meta.transport = transport;
     await withRetry(() => bridge.complete(job.id, finalText, meta));
+    if (offerCid) await p2p.announce(bridge, offerCid);
     logger.info(`job ${job.id} done (${finalText.length} chars${transport ? `, P2P-offered ${transport.cid.slice(0, 14)}…` : ''})`);
   } catch (e) {
     logger.error(`job ${job.id} failed: ${e.message}`);