wokitoki 0.3.2 → 0.4.0

package/README.md

@@ -18,6 +18,8 @@ No server. No account. No tunnel. Free and open source.
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.pandeyvishwas51--oss%2Fwokitoki-2B1306)](https://registry.modelcontextprotocol.io/v0/servers?search=wokitoki)
 [![Node 22.18+](https://img.shields.io/badge/node-22.18%2B-2B1306)](https://nodejs.org)
 
+<img src="https://raw.githubusercontent.com/pandeyvishwas51-oss/wokitoki/main/assets/demo.gif" width="600" alt="Demo: two developers pair WokiToki with a 6-digit code, then one Claude Code asks the other developer's Codex whether the orders API returns paise and gets the answer back, end to end encrypted">
+
 **[▶ Watch the 1-minute demo (sound on)](https://pandeyvishwas51-oss.github.io/wokitoki/#demo)**
 
 [Website](https://pandeyvishwas51-oss.github.io/wokitoki/) · [Quick start](#quick-start) · [How it works](#how-it-works) · [FAQ](#faq) · [Security](#security-honestly)
@@ -155,6 +157,8 @@ Yes. It is open source under Apache-2.0, and there is no paid tier, hosted servi
 - Messages are end-to-end encrypted between the two daemons. In peer-to-peer mode, nothing is stored anywhere but the two machines.
 - Pairing needs a one-time invite **and** both people approving the same verify code. A leaked invite alone pairs no one, and nobody in the middle can swap keys without detection.
 - Message-layer keys are static per pairing (no ratchet yet). Keys live in `~/.wokitoki/identity.json` (mode 0600), and local history is stored unencrypted on disk.
+- A paired peer can't flood your agent: incoming messages are rate-limited per peer and capped at 500 unread; the rest wait in the sender's outbox.
+- Every parser that reads network input is fuzz-tested, and releases are built only by CI with signed provenance and a human approval step.
 - No external security audit has been done. Don't send secrets.
 
 Details: [threat model](https://github.com/pandeyvishwas51-oss/wokitoki/blob/main/docs/THREAT_MODEL.md) · [architecture](https://github.com/pandeyvishwas51-oss/wokitoki/blob/main/docs/ARCHITECTURE.md) · [protocol](https://github.com/pandeyvishwas51-oss/wokitoki/blob/main/docs/PROTOCOL.md) · [security policy](https://github.com/pandeyvishwas51-oss/wokitoki/blob/main/SECURITY.md) · [verification log](https://github.com/pandeyvishwas51-oss/wokitoki/blob/main/VERIFICATION.md)
@@ -190,11 +194,13 @@ Every command accepts `--json` and `--home <dir>` (default `~/.wokitoki`). The o
 
 ```bash
 pnpm install
-pnpm check      # strict TypeScript + 65 tests: unit, adversarial, P2P on a local DHT testnet, multi-process CLI e2e, real MCP calls
+pnpm check      # strict TypeScript + 73 tests: unit, adversarial, P2P on a local DHT testnet, multi-process CLI e2e, real MCP calls
 ```
 
 Releases come only from CI: bump the version, tag `vX.Y.Z` on `main` and push the tag. [release.yml](https://github.com/pandeyvishwas51-oss/wokitoki/blob/main/.github/workflows/release.yml) stages it on npm with signed provenance (trusted publishing, no tokens) for a maintainer to approve with 2FA, attaches a build attestation and an SBOM to the GitHub release, and updates the MCP Registry.
 
+Contributions welcome: see [CONTRIBUTING.md](https://github.com/pandeyvishwas51-oss/wokitoki/blob/main/CONTRIBUTING.md) and the [good first issues](https://github.com/pandeyvishwas51-oss/wokitoki/labels/good%20first%20issue).
+
 [Roadmap](https://github.com/pandeyvishwas51-oss/wokitoki/blob/main/ROADMAP.md): tasks, encrypted file transfer, multi-agent rooms and a web console are next. License: [Apache-2.0](https://github.com/pandeyvishwas51-oss/wokitoki/blob/main/LICENSE).
 
 <p align="center"><img src="https://raw.githubusercontent.com/pandeyvishwas51-oss/wokitoki/main/assets/logo.svg" width="72" alt="WokiToki mascot"></p>

package/dist/wokitoki.mjs

@@ -468,6 +468,14 @@ CREATE TABLE IF NOT EXISTS events (
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
         ).run(m.id, m.peer_id, m.pair_id, m.direction, m.text, m.reply_to, m.state, t, t);
       }
+      countUnread(peerId) {
+        return this.db.prepare(`SELECT COUNT(*) AS n FROM messages WHERE peer_id = ? AND direction = 'in' AND read_at IS NULL`).get(peerId).n;
+      }
+      peerActivity(peerId) {
+        const queued = this.db.prepare("SELECT COUNT(*) AS n FROM outbox WHERE peer_id = ?").get(peerId).n;
+        const last = this.db.prepare("SELECT MAX(created_at) AS t FROM messages WHERE peer_id = ?").get(peerId).t;
+        return { queued, lastMessageAt: last };
+      }
       getMessage(id) {
         return this.db.prepare("SELECT * FROM messages WHERE id = ?").get(id);
       }
@@ -595,6 +603,10 @@ var init_dht_mailbox = __esm({
         clearInterval(this.timer);
         await this.running;
       }
+      /** Sync now instead of waiting for the next interval (e.g. after the machine wakes from sleep). */
+      poke() {
+        this.round();
+      }
       round() {
         if (this.stopped || this.running) return;
         const peers = this.host.livePeers().filter((p) => p.state === "active" && !this.connected(p.device_id));
@@ -694,7 +706,7 @@ var init_dht_mailbox = __esm({
 import DHT from "hyperdht";
 import { randomUUID } from "node:crypto";
 import { StringDecoder } from "node:string_decoder";
-var CONNECT_TIMEOUT_MS, REQUEST_TIMEOUT_MS, P2PTransport;
+var CONNECT_TIMEOUT_MS, WAKE_CHECK_MS, WAKE_GAP_MS, REQUEST_TIMEOUT_MS, P2PTransport;
 var init_p2p_transport = __esm({
   async "apps/bridge/src/p2p-transport.ts"() {
     "use strict";
@@ -703,6 +715,8 @@ var init_p2p_transport = __esm({
     init_transport();
     await init_dht_mailbox();
     CONNECT_TIMEOUT_MS = 3e4;
+    WAKE_CHECK_MS = 1e4;
+    WAKE_GAP_MS = 3e4;
     REQUEST_TIMEOUT_MS = 2e4;
     P2PTransport = class {
       kind = "p2p";
@@ -717,6 +731,7 @@ var init_p2p_transport = __esm({
       bootstrap;
       mailboxIntervalMs;
       mailbox;
+      wakeTimer;
       startup;
       constructor(host, bootstrap, mailboxIntervalMs = 3e4) {
         this.host = host;
@@ -745,6 +760,7 @@ var init_p2p_transport = __esm({
             this.host.audit("p2p_online", null, { firewalled: this.dht.firewalled });
             this.mailbox = new DhtMailbox(this.dht, this.host, (id) => this.conns.has(id), this.mailboxIntervalMs);
             this.mailbox.start();
+            this.watchForWake();
             for (const peer of this.host.livePeers()) {
               this.dial(peer.device_id, this.host.signPubOf(peer)).then(
                 () => this.host.peerOnline(peer.device_id),
@@ -762,10 +778,34 @@ var init_p2p_transport = __esm({
           }
         }
       }
+      /** After sleep, connections are stale and queues wait on long backoffs: reconnect and flush right away. */
+      watchForWake() {
+        let last = Date.now();
+        this.wakeTimer = setInterval(() => {
+          const now = Date.now();
+          if (now - last > WAKE_GAP_MS) {
+            this.host.log(`woke after ${Math.round((now - last) / 1e3)} s; reconnecting to peers`);
+            this.host.audit("p2p_wake", null, { gapMs: now - last });
+            for (const peer of this.host.livePeers()) {
+              this.disconnect(peer.device_id);
+              this.dial(peer.device_id, this.host.signPubOf(peer)).then(
+                () => this.host.peerOnline(peer.device_id),
+                () => {
+                }
+              );
+            }
+            this.host.transportReady();
+            this.mailbox?.poke();
+          }
+          last = now;
+        }, WAKE_CHECK_MS);
+        this.wakeTimer.unref();
+      }
       async stop() {
         this.stopped = true;
         await this.startup?.catch(() => {
         });
+        clearInterval(this.wakeTimer);
         await this.mailbox?.stop();
         for (const c of this.conns.values()) c.stream.destroy();
         this.conns.clear();
@@ -944,7 +984,7 @@ var init_p2p_transport = __esm({
             }
             const r = this.host.handleItem(frame.item, conn.deviceId);
             if (r.ok) this.send(conn, { t: "ack", id: frame.item.id });
-            else if (r.permanent) this.send(conn, { t: "nack", id: frame.item.id, code: r.code, message: r.code, permanent: true });
+            else this.send(conn, { t: "nack", id: frame.item.id, code: r.code, message: r.code, permanent: r.permanent });
             break;
           }
           case "ack":
@@ -1183,6 +1223,9 @@ var init_bridge = __esm({
       keys = /* @__PURE__ */ new Map();
       // ponytail: failed-join counters live in memory; a daemon restart resets them. Invites expire in <=1h anyway.
       joinFailures = /* @__PURE__ */ new Map();
+      // ponytail: per-peer inbound buckets live in memory; a restart refills them, which is harmless.
+      buckets = /* @__PURE__ */ new Map();
+      throttleAudited = /* @__PURE__ */ new Map();
       stopped = false;
       flushing;
       flushAgain = false;
@@ -1258,6 +1301,7 @@ var init_bridge = __esm({
           remoteApproved: p.remote_ok === 1,
           role: p.role,
           online: this.transport.isPeerConnected(p.device_id),
+          ...this.store.peerActivity(p.device_id),
           createdAt: p.created_at,
           updatedAt: p.updated_at
         };
@@ -1557,6 +1601,10 @@ var init_bridge = __esm({
           this.audit("security.envelope_rejected", env.from, meta);
           return { ok: false, permanent: true, code: "rejected" };
         }
+        if (payload.type === "text" && !this.store.getMessage(env.id)) {
+          const refusal = this.inboundRefusal(peer.device_id);
+          if (refusal) return { ok: false, permanent: false, code: refusal };
+        }
         this.store.tx(() => {
           this.store.updatePeer(peer.device_id, { recv_seq: env.seq });
           if (payload.type === "receipt") {
@@ -1600,6 +1648,27 @@ var init_bridge = __esm({
           }
         });
       }
+      /** A paired peer cannot flood this agent: a token bucket per peer, and a cap on unread messages. */
+      inboundRefusal(peerId) {
+        const burst = this.opts.inboundBurst ?? 60;
+        const perMs = (this.opts.inboundPerMinute ?? 60) / 6e4;
+        let refusal = null;
+        if (this.store.countUnread(peerId) >= (this.opts.maxUnread ?? 500)) refusal = "inbox_full";
+        else {
+          const now = Date.now();
+          const b = this.buckets.get(peerId) ?? { tokens: burst, at: now };
+          b.tokens = Math.min(burst, b.tokens + (now - b.at) * perMs);
+          b.at = now;
+          this.buckets.set(peerId, b);
+          if (b.tokens < 1) refusal = "rate_limited";
+          else b.tokens -= 1;
+        }
+        if (refusal && Date.now() - (this.throttleAudited.get(peerId) ?? 0) > 6e4) {
+          this.throttleAudited.set(peerId, Date.now());
+          this.audit("security.inbound_throttled", peerId, { reason: refusal });
+        }
+        return refusal;
+      }
       // ---------------------------------------------------------------- outbox
       mustPeer(deviceId) {
         const p = this.store.getPeer(deviceId);
@@ -1910,6 +1979,12 @@ async function guard(fn) {
 }
 function createMcpServer(socketPath, version) {
   const daemon2 = (method, path, body) => callDaemon(socketPath, method, path, body);
+  let myName;
+  const header = async () => {
+    myName ??= (await daemon2("GET", "/identity")).name;
+    return `You are ${JSON.stringify(myName)} on WokiToki; received messages were sent to you.
+${UNTRUSTED}`;
+  };
   const server = new McpServer({ name: "wokitoki", version });
   server.registerTool(
     "wokitoki_get_status",
@@ -1935,7 +2010,7 @@ function createMcpServer(socketPath, version) {
     "wokitoki_send_message",
     {
       title: "Send WokiToki message",
-      description: `Send an end-to-end encrypted text message to an already-paired, active peer agent (by name or device id). The text leaves this machine: never include secrets, credentials or private code your user has not approved sharing. Returns the message id; state becomes "delivered" once the peer's bridge confirms receipt (check with wokitoki_list_messages).`,
+      description: 'Send an end-to-end encrypted text message to an already-paired, active peer agent (by name or device id). The text leaves this machine: never include secrets, credentials or private code your user has not approved sharing. Waits up to 3 seconds for the peer to confirm, then returns the message id and its state: "relayed" or "delivered" = the peer has it; "queued" = the peer is offline right now, and it is delivered automatically later (check with wokitoki_list_messages).',
       inputSchema: {
         to: z7.string().min(1).max(128).describe("peer name or device id"),
         text: z7.string().min(1).max(16e3).describe("message text"),
@@ -1943,7 +2018,15 @@ function createMcpServer(socketPath, version) {
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
-    ({ to, text, replyTo }) => guard(async () => ok(messageSummary(await daemon2("POST", "/messages", { to, text, replyTo }))))
+    ({ to, text, replyTo }) => guard(async () => {
+      let m = await daemon2("POST", "/messages", { to, text, replyTo });
+      for (let i = 0; i < 30 && m.state === "queued"; i++) {
+        await new Promise((r) => setTimeout(r, 100));
+        m = (await daemon2("GET", `/messages?peer=${encodeURIComponent(m.peer)}&limit=50`)).find((x) => x.id === m.id) ?? m;
+      }
+      const note = m.state === "queued" ? "The peer is offline right now; this is delivered automatically when it can be." : void 0;
+      return ok({ ...messageSummary(m), ...note ? { note } : {} });
+    })
   );
   server.registerTool(
     "wokitoki_read_inbox",
@@ -1963,7 +2046,7 @@ function createMcpServer(socketPath, version) {
       const msgs = await daemon2("GET", `/messages?${q}`);
       if (msgs.length && markRead !== false) await daemon2("POST", "/messages/read", { ids: msgs.map((m) => m.id) });
       if (!msgs.length) return ok([], "No unread WokiToki messages.");
-      return ok(msgs.map(messageSummary), UNTRUSTED);
+      return ok(msgs.map(messageSummary), await header());
     })
   );
   server.registerTool(
@@ -1979,7 +2062,7 @@ function createMcpServer(socketPath, version) {
     },
     ({ peer, limit }) => guard(async () => {
       const q = new URLSearchParams({ limit: String(limit ?? 20), ...peer ? { peer } : {} });
-      return ok((await daemon2("GET", `/messages?${q}`)).map(messageSummary), UNTRUSTED);
+      return ok((await daemon2("GET", `/messages?${q}`)).map(messageSummary), await header());
     })
   );
   return server;
@@ -2002,6 +2085,8 @@ var init_src3 = __esm({
       name: p.name,
       deviceId: p.deviceId,
       state: p.state,
+      online: p.online,
+      queued: p.queued,
       fingerprint: p.fingerprint
     });
     messageSummary = (m) => ({
@@ -2020,14 +2105,14 @@ var init_src3 = __esm({
 
 // apps/cli/src/main.ts
 import { Command } from "commander";
-import { execFileSync as execFileSync2, spawn, spawnSync } from "node:child_process";
+import { execFileSync as execFileSync2, spawn as spawn2, spawnSync } from "node:child_process";
 import { copyFileSync, existsSync as existsSync4, mkdirSync as mkdirSync3, openSync, readFileSync as readFileSync3, rmSync as rmSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
 import { fileURLToPath } from "node:url";
 import { dirname as dirname2, join as join3, resolve as resolve2 } from "node:path";
 
 // apps/cli/src/service.ts
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -2036,6 +2121,15 @@ var xml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&
 var sh = (s) => `"${s.replace(/(["\\$`])/g, "\\$1")}"`;
 var winQuote = (s) => `"${s.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1")}"`;
 var vbs = (s) => `"${s.replace(/"/g, '""')}"`;
+var windowsLauncher = (line) => [
+  "\uFEFF' WokiToki daemon: started at login by `wokitoki daemon install`; restarted 5 s after a crash",
+  'Set shell = CreateObject("WScript.Shell")',
+  "Do",
+  `  If shell.Run(${vbs(line)}, 0, True) = 0 Then Exit Do`,
+  "  WScript.Sleep 5000",
+  "Loop",
+  ""
+].join("\r\n");
 var appData = () => process.env.APPDATA ?? join(homedir(), "AppData", "Roaming");
 function servicePath() {
   if (process.platform === "darwin") return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
@@ -2061,7 +2155,7 @@ function startService() {
       execFileSync("launchctl", ["bootstrap", domain, servicePath()], { stdio: "ignore" });
     }
   } else if (process.platform === "win32") {
-    execFileSync("wscript.exe", ["//B", "//Nologo", servicePath()], { stdio: "ignore", cwd: homedir() });
+    spawn("wscript.exe", ["//B", "//Nologo", servicePath()], { stdio: "ignore", cwd: homedir(), detached: true, windowsHide: true }).unref();
   } else {
     execFileSync("systemctl", ["--user", "start", "wokitoki.service"], { stdio: "ignore" });
   }
@@ -2097,16 +2191,8 @@ ${argv.map((a) => `    <string>${xml(a)}</string>`).join("\n")}
     }
     execFileSync("launchctl", ["bootstrap", domain, path]);
   } else if (process.platform === "win32") {
-    const line = `cmd.exe /d /s /c "${argv.map(winQuote).join(" ")} >> ${winQuote(logPath)} 2>&1"`;
-    writeFileSync(path, `\uFEFF' WokiToki daemon: started at login by \`wokitoki daemon install\`\r
-CreateObject("WScript.Shell").Run ${vbs(line)}, 0, False\r
-`, "utf16le");
-    try {
-      startService();
-    } catch (e) {
-      rmSync(path, { force: true });
-      throw e;
-    }
+    writeFileSync(path, windowsLauncher(`cmd.exe /d /s /c "${argv.map(winQuote).join(" ")} >> ${winQuote(logPath)} 2>&1"`), "utf16le");
+    startService();
   } else {
     writeFileSync(
       path,
@@ -2189,7 +2275,8 @@ function parseDuration(s) {
 function peerLine(p) {
   const approvals = p.state === "pending" ? `  you:${p.localApproved ? "approved" : "waiting"} peer:${p.remoteApproved ? "approved" : "waiting"}` : "";
   const online = p.online === null ? "" : p.online ? "  [online]" : "  [offline]";
-  return `${p.deviceId}  ${safe(p.name).padEnd(20)} ${p.state.padEnd(8)}${approvals}${p.state === "active" ? online : ""}`;
+  const queued = p.queued ? `  ${p.queued} queued` : "";
+  return `${p.deviceId}  ${safe(p.name).padEnd(20)} ${p.state.padEnd(8)}${approvals}${p.state === "active" ? online + queued : ""}`;
 }
 var joinText = (x) => [
   "Pairing request sent.",
@@ -2285,7 +2372,7 @@ async function startDaemonInBackground(waitConnectedMs = 3e3) {
     if (serviceInstalledFor(home)) startService();
     else {
       const log = openSync(homePaths(home).log, "a", 384);
-      spawn(process.execPath, [SELF, "--home", home, "daemon", "run"], { cwd: home, detached: true, stdio: ["ignore", log, log], windowsHide: true }).unref();
+      spawn2(process.execPath, [SELF, "--home", home, "daemon", "run"], { cwd: home, detached: true, stdio: ["ignore", log, log], windowsHide: true }).unref();
     }
     for (let i = 0; i < 200 && !await up(); i++) await new Promise((r) => setTimeout(r, 100));
     if (!await up()) throw new Error(`wokitoki daemon failed to start; see ${homePaths(home).log}`);
@@ -2333,7 +2420,12 @@ async function enableAutostart() {
   loadHome(home);
   if (await callDaemon(socket, "GET", "/status").then(() => true, () => false)) await stopDaemon();
   const path = installService([process.execPath, BIN, "--home", home, "daemon", "run"], homePaths(home).log);
-  for (let i = 0; i < 100 && !await callDaemon(socket, "GET", "/status").then(() => true, () => false); i++) await new Promise((r) => setTimeout(r, 100));
+  const up = () => callDaemon(socket, "GET", "/status").then(() => true, () => false);
+  for (let i = 0; i < 100 && !await up(); i++) await new Promise((r) => setTimeout(r, 100));
+  if (!await up()) {
+    uninstallService();
+    throw new Error("the login service did not start the daemon");
+  }
   return path;
 }
 program.command("status").description("show daemon and network connection status").action(showStatus);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "wokitoki",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "wokitoki",
-      "version": "0.3.2",
+      "version": "0.4.0",
       "license": "Apache-2.0",
       "os": [
         "darwin",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wokitoki",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Walkie-talkies for AI coding agents: Claude Code and Codex message each other peer to peer, end-to-end encrypted, via MCP. No server, no account.",
   "license": "Apache-2.0",
   "author": "Vishwas Pandey",