cli-chat-mcp 0.2.0

package/README.md

@@ -0,0 +1,133 @@
+# CLI Messenger
+
+A peer-to-peer messaging layer for coding-agent CLIs. You tell your agent
+*"write Sam: …"*; it resolves the contact, encrypts the message end-to-end, and
+delivers it through a hosted mailbox. When the recipient opens their CLI, their
+agent surfaces the message and helps them reply.
+
+- **Works across CLIs** — Claude Code, Gemini CLI, Copilot CLI, Cursor, … (any
+  MCP-capable agent). Behavior ships inside the server's MCP `instructions`.
+- **End-to-end encrypted** — libsodium sealed boxes; the mailbox only ever holds
+  ciphertext. Every request is Ed25519-signed.
+- **Phone-number-style codes** — share a 6-character handle; a server registry
+  maps it to your keys.
+- **Hosted mailbox** — Cloudflare Worker + D1 (store-and-forward), already
+  deployed; runs on Node locally too.
+
+See [PLAN.md](./PLAN.md) for the full concept and roadmap.
+
+## Requirements
+Node 22.6+ (uses built-in `node:sqlite`). That's all an end user needs — `npx`
+fetches the rest. State (identity, contacts, inbox cache) lives in `~/.cli-chat`,
+not next to the code, so it survives across `npx` runs.
+
+## Set up to message someone (no clone)
+
+**1. Wire up your CLI** — add one MCP server entry. On Claude Code:
+```bash
+claude mcp add cli-chat --scope user \
+  --env MESSENGER_MAILBOX_URL=https://mailbox.cli-chat-mcp.workers.dev \
+  -- npx -y cli-chat-mcp
+```
+Or paste this into any MCP-capable CLI's config (Gemini, Cursor, Codex, …):
+```json
+{
+  "mcpServers": {
+    "cli-chat": {
+      "command": "npx",
+      "args": ["-y", "cli-chat-mcp"],
+      "env": { "MESSENGER_MAILBOX_URL": "https://mailbox.cli-chat-mcp.workers.dev" }
+    }
+  }
+}
+```
+(From a clone, `npm run install-clis` auto-writes this entry for every detected CLI.)
+
+**2. Restart your CLI**, approve the `cli-chat` server once, then say *"set me
+up"* — `create_account` mints your identity and prints your 6-char code (e.g.
+`dC0v6m`) to share.
+
+**3. Swap 6-char codes** with whoever you're messaging (both directions).
+
+**4. Message:**
+```
+write Sam at dC0v6m: hey      # first time: by code (saves them)
+write Sam: hey                # after that: by name
+```
+When the recipient opens their CLI they're told a message is waiting and asked if
+they want it read; they reply the same way.
+
+## Develop from a clone
+```bash
+npm install
+npm test          # unit + integration (92 checks): encryption, server-only-ciphertext, spoofing
+npm run test:mcp  # real MCP server processes against the live cloud mailbox
+npm run build     # bundle src/ → dist/ (what gets published)
+```
+Running from a checkout keeps state in the repo's `users/` dir (back-compat);
+set `MESSENGER_HOME` to override where state lives.
+
+> Two-way chat needs both codes shared once — a message can't safely carry a
+> reply-to key (that would let the server MITM). Mutual, out-of-band exchange is
+> the secure choice.
+
+## The MCP tools
+`create_account` · `send_message` · `messages_available` · `watch` ·
+`read_message` · `draft_reply` · `add_contact` · `my_key` · `list_contacts`.
+Behavior (when to check, how to reply) is carried in the server's MCP
+`instructions`, so it's the same in every CLI.
+
+- **`create_account`** mints your identity + 6-char code from inside the CLI, so
+  you don't need `npm run init` first. The server now boots even with no identity
+  on the device — until you have one, the other tools report `no_account` and the
+  agent offers to run `create_account`.
+- **`watch`** is a cross-CLI watch loop: it long-polls ~25s for new mail (marking
+  it read) and the agent re-calls it to keep watching. It needs no OS service and
+  works in any MCP CLI, but it's not silent — each return is a turn you see.
+
+## Receiving: on-open or on-demand
+- **On open** — Claude Code runs a `SessionStart` hook (`src/check-inbox.ts`)
+  that pulls waiting mail and tells you how many are waiting and from whom, then
+  offers to read them (the bodies stay private to the agent until you say yes).
+  Other CLIs check on their first turn (via the server instructions).
+- **On demand** — ask "any messages?" anytime, or have the agent `watch` to
+  long-poll for new mail while you wait.
+
+## Layout
+| Path | Role |
+|---|---|
+| `src/server-net.ts` | the MCP server (tools + `instructions`) |
+| `src/core-net.ts` | seal-on-send, drain+decrypt-to-cache, read locally |
+| `src/crypto.ts` · `auth.ts` · `canonical.ts` | sealed boxes + signed-request auth |
+| `src/key-code.ts` · `identity.ts` · `contacts.ts` · `db.ts` | codes, identity, contacts, local cache |
+| `src/mailbox-client.ts` | signed HTTP client |
+| `src/init-identity.ts` · `install.ts` · `add-contact.ts` | onboarding helpers |
+| `src/check-inbox.ts` | on-open read (SessionStart hook) |
+| `server-mailbox/` | the Hono mailbox: `app.ts`, `node.ts` (local), `worker.ts`+`wrangler.toml` (Cloudflare/D1), `store*.ts`, `verify.ts`, `schema.sql` |
+| `test/live-net.ts` · `live-net-mcp.ts` | in-process + real-MCP tests |
+
+## Deploy your own mailbox (optional)
+The mailbox is already deployed. To run your own:
+```bash
+npx wrangler d1 create cli-chat          # put the id in wrangler.toml
+npx wrangler d1 execute cli-chat --remote --file server-mailbox/schema.sql
+npm run deploy
+```
+Point clients at it with `MESSENGER_MAILBOX_URL=https://…`.
+
+## Notes
+- **Storage is keyed by handle, not name.** Each identity lives in
+  `users/<handle>/` (your 6-char code), and the device default `users/.current`
+  holds that handle. Your name is a cosmetic `name` field inside `identity.json`
+  — local only, never sent to the server, and free to change. `MESSENGER_USER`
+  accepts a handle, a display name, or a `signPub` and resolves to the right
+  identity. Upgrading from the older name-keyed layout? Run `npm run migrate`
+  (it claims a handle for any identity missing one, renames the dirs, and fixes
+  `.current`). After migrating, restart any running CLI so its server reloads.
+- **Secrets:** `users/*/identity.json` holds private keys and is gitignored; only
+  public keys ever leave your machine.
+- The deployed mailbox is currently open (no API token) — it only holds
+  ciphertext, but anyone with the URL could post blobs to a known address. Fine
+  for a small trusted group; add a token / rate-limiting before wider use.
+- One identity per machine for now (no recovery-passphrase yet, so you can't move
+  an identity to another device).

package/dist/add-contact.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+// src/add-contact.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
+
+// src/crypto.ts
+var s = null;
+async function initCrypto() {
+  if (s) return;
+  const mod = await import("libsodium-wrappers");
+  const sodium = mod.default ?? mod;
+  await sodium.ready;
+  s = sodium;
+}
+
+// src/identity.ts
+import { readFileSync } from "node:fs";
+function loadIdentity(path) {
+  const id2 = JSON.parse(readFileSync(path, "utf8"));
+  for (const k of ["boxPub", "boxSec", "signPub", "signSec"]) {
+    if (!id2[k]) throw new Error(`identity at ${path} missing ${k}`);
+  }
+  return id2;
+}
+
+// src/current-user.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync, writeFileSync } from "node:fs";
+import { join as join2 } from "node:path";
+
+// src/paths.ts
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+var codeRoot = resolve(import.meta.dirname, "..");
+function dataHome() {
+  const env = process.env.MESSENGER_HOME?.trim();
+  if (env) return env;
+  if (existsSync(join(codeRoot, "users"))) return codeRoot;
+  return join(homedir(), ".cli-chat");
+}
+function usersDir() {
+  return join(dataHome(), "users");
+}
+function userDir(user2) {
+  return join(usersDir(), user2);
+}
+function identityFile(user2) {
+  return join(userDir(user2), "identity.json");
+}
+function contactsFile(user2) {
+  return join(userDir(user2), "contacts.json");
+}
+
+// src/current-user.ts
+var pointerPath = () => join2(usersDir(), ".current");
+function identityDirs() {
+  const dir = usersDir();
+  if (!existsSync2(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).filter((name2) => existsSync2(identityFile(name2)));
+}
+function readMeta(dir) {
+  try {
+    return JSON.parse(readFileSync2(identityFile(dir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function resolveDir(sel) {
+  const dirs = identityDirs();
+  if (dirs.includes(sel)) return sel;
+  const low = sel.toLowerCase();
+  for (const d of dirs) {
+    const id2 = readMeta(d);
+    if (!id2) continue;
+    if (id2.handle === sel || id2.signPub === sel) return d;
+    if (id2.name && id2.name.toLowerCase() === low) return d;
+  }
+  return null;
+}
+function currentUser() {
+  const env = process.env.MESSENGER_USER?.trim();
+  if (env) return resolveDir(env) ?? env;
+  const pointer = pointerPath();
+  if (existsSync2(pointer)) {
+    const val = readFileSync2(pointer, "utf8").trim();
+    if (val) return resolveDir(val) ?? val;
+  }
+  const dirs = identityDirs();
+  if (dirs.length === 1) return dirs[0];
+  return null;
+}
+
+// src/add-contact.ts
+var user = currentUser();
+if (!user) {
+  console.error("No identity on this device. Run `npm run init`, or set MESSENGER_USER.");
+  process.exit(1);
+}
+var [name, signPub, boxPub] = process.argv.slice(2);
+if (!name || !signPub || !boxPub) {
+  console.error("Usage: node src/add-contact.ts <Name> <signPub> <boxPub>");
+  process.exit(1);
+}
+var isHex64 = (s2) => /^[0-9a-f]{64}$/i.test(s2);
+if (!isHex64(signPub) || !isHex64(boxPub)) {
+  console.error("signPub and boxPub must each be 64 hex chars. Check what was pasted.");
+  process.exit(1);
+}
+await initCrypto();
+var idPath = identityFile(user);
+if (!existsSync3(idPath)) {
+  console.error(`No identity yet for "${user}". Run:  node src/init-identity.ts`);
+  process.exit(1);
+}
+var me = loadIdentity(idPath);
+var contactsPath = contactsFile(user);
+var book = existsSync3(contactsPath) ? JSON.parse(readFileSync3(contactsPath, "utf8")) : { me: me.signPub, contacts: [] };
+book.me = me.signPub;
+var id = name.toLowerCase();
+book.contacts = book.contacts.filter((c) => c.id !== id && c.signPub !== signPub);
+book.contacts.push({ id, name, signPub, boxPub });
+writeFileSync2(contactsPath, JSON.stringify(book, null, 2) + "\n");
+console.log(`Added "${name}". You can now message them:  write ${name}: <your message>`);

package/dist/check-inbox.js

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+
+// src/check-inbox.ts
+import { readFileSync as readFileSync4 } from "node:fs";
+
+// src/crypto.ts
+var s = null;
+async function initCrypto() {
+  if (s) return;
+  const mod = await import("libsodium-wrappers");
+  const sodium = mod.default ?? mod;
+  await sodium.ready;
+  s = sodium;
+}
+var B64 = () => s.base64_variants.ORIGINAL;
+function open(cipherB64, boxPubHex, boxSecHex) {
+  const pt = s.crypto_box_seal_open(
+    s.from_base64(cipherB64, B64()),
+    s.from_hex(boxPubHex),
+    s.from_hex(boxSecHex)
+  );
+  return s.to_string(pt);
+}
+function signDetached(message, signSecHex) {
+  const sig = s.crypto_sign_detached(s.from_string(message), s.from_hex(signSecHex));
+  return s.to_hex(sig);
+}
+
+// src/identity.ts
+import { readFileSync } from "node:fs";
+function loadIdentity(path) {
+  const id = JSON.parse(readFileSync(path, "utf8"));
+  for (const k of ["boxPub", "boxSec", "signPub", "signSec"]) {
+    if (!id[k]) throw new Error(`identity at ${path} missing ${k}`);
+  }
+  return id;
+}
+
+// src/contacts.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+function loadContacts(path) {
+  const raw = readFileSync2(path, "utf8");
+  const book = JSON.parse(raw);
+  if (!book.me || !Array.isArray(book.contacts)) {
+    throw new Error(`Invalid contact book at ${path}: needs { me, contacts[] }`);
+  }
+  return book;
+}
+function displayNameByKey(book, signPub) {
+  const c = book.contacts.find((c2) => c2.signPub === signPub);
+  return c?.name ?? `${signPub.slice(0, 8)}\u2026`;
+}
+
+// src/db.ts
+import { DatabaseSync } from "node:sqlite";
+function openMailbox(path) {
+  const db = new DatabaseSync(path);
+  try {
+    db.exec(`PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 3000;`);
+  } catch {
+  }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS messages (
+      id          TEXT PRIMARY KEY,
+      recipient   TEXT NOT NULL,
+      sender      TEXT NOT NULL,
+      body        TEXT NOT NULL,
+      tags        TEXT,
+      created_at  INTEGER NOT NULL,
+      fetched_at  INTEGER,
+      read_at     INTEGER,
+      in_reply_to TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_recipient ON messages (recipient, created_at);
+  `);
+  return db;
+}
+function insertMessage(db, m) {
+  db.prepare(
+    `INSERT INTO messages
+       (id, recipient, sender, body, tags, created_at, fetched_at, read_at, in_reply_to)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  ).run(
+    m.id,
+    m.recipient,
+    m.sender,
+    m.body,
+    m.tags,
+    m.created_at,
+    m.fetched_at,
+    m.read_at,
+    m.in_reply_to
+  );
+}
+function unreadFor(db, me) {
+  return db.prepare(
+    `SELECT * FROM messages
+       WHERE recipient = ? AND read_at IS NULL
+       ORDER BY created_at ASC`
+  ).all(me);
+}
+function getMessage(db, id) {
+  return db.prepare(`SELECT * FROM messages WHERE id = ?`).get(id);
+}
+function markRead(db, id, now) {
+  db.prepare(`UPDATE messages SET read_at = ?, fetched_at = COALESCE(fetched_at, ?) WHERE id = ?`).run(
+    now,
+    now,
+    id
+  );
+}
+
+// src/canonical.ts
+var MAX_SKEW_MS = 5 * 60 * 1e3;
+function canonical(method, path, timestamp, body) {
+  return `${method.toUpperCase()}
+${path}
+${timestamp}
+${body}`;
+}
+
+// src/auth.ts
+function makeAuthHeaders(signPubHex, signSecHex, method, path, body, now) {
+  const sig = signDetached(canonical(method, path, now, body), signSecHex);
+  return {
+    "x-pubkey": signPubHex,
+    "x-timestamp": String(now),
+    "x-signature": sig
+  };
+}
+
+// src/mailbox-client.ts
+function createMailboxClient(baseUrl, identity, now) {
+  const base = baseUrl.replace(/\/$/, "");
+  function headers(method, path, body) {
+    return makeAuthHeaders(
+      identity.signPub,
+      identity.signSec,
+      method,
+      path,
+      body,
+      now()
+    );
+  }
+  async function fail(res, what) {
+    let detail = "";
+    try {
+      detail = JSON.stringify(await res.json());
+    } catch {
+    }
+    throw new Error(`${what} failed: ${res.status} ${detail}`);
+  }
+  return {
+    async send(msg) {
+      const body = JSON.stringify(msg);
+      const res = await fetch(`${base}/messages`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...headers("POST", "/messages", body) },
+        body
+      });
+      if (!res.ok) await fail(res, "send");
+    },
+    async summary() {
+      const res = await fetch(`${base}/mailbox`, {
+        headers: headers("GET", "/mailbox", "")
+      });
+      if (!res.ok) await fail(res, "summary");
+      return await res.json();
+    },
+    async drain() {
+      const res = await fetch(`${base}/messages`, {
+        headers: headers("GET", "/messages", "")
+      });
+      if (!res.ok) await fail(res, "drain");
+      const data = await res.json();
+      return data.messages;
+    },
+    async registerHandle(handle) {
+      const body = JSON.stringify({ handle, signPub: identity.signPub, boxPub: identity.boxPub });
+      const res = await fetch(`${base}/register`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...headers("POST", "/register", body) },
+        body
+      });
+      if (res.status === 409) return "taken";
+      if (!res.ok) await fail(res, "register");
+      return "ok";
+    },
+    async resolveHandle(handle) {
+      const res = await fetch(`${base}/resolve/${encodeURIComponent(handle)}`);
+      if (res.status === 404) return null;
+      if (!res.ok) await fail(res, "resolve");
+      return await res.json();
+    }
+  };
+}
+
+// src/core-net.ts
+async function sync(ctx) {
+  const blobs = await ctx.client.drain();
+  let added = 0;
+  for (const b of blobs) {
+    if (getMessage(ctx.cache, b.id)) continue;
+    let body;
+    try {
+      body = open(b.body, ctx.me.boxPub, ctx.me.boxSec);
+    } catch {
+      body = "[unable to decrypt \u2014 not sealed to this identity]";
+    }
+    const row = {
+      id: b.id,
+      recipient: ctx.me.signPub,
+      sender: b.sender,
+      body,
+      tags: b.tags,
+      created_at: b.created_at,
+      fetched_at: ctx.now(),
+      read_at: null,
+      in_reply_to: b.in_reply_to
+    };
+    insertMessage(ctx.cache, row);
+    added++;
+  }
+  return added;
+}
+
+// src/current-user.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3, readdirSync, writeFileSync } from "node:fs";
+import { join as join2 } from "node:path";
+
+// src/paths.ts
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve as resolve2 } from "node:path";
+var codeRoot = resolve2(import.meta.dirname, "..");
+function dataHome() {
+  const env = process.env.MESSENGER_HOME?.trim();
+  if (env) return env;
+  if (existsSync(join(codeRoot, "users"))) return codeRoot;
+  return join(homedir(), ".cli-chat");
+}
+function usersDir() {
+  return join(dataHome(), "users");
+}
+function userDir(user2) {
+  return join(usersDir(), user2);
+}
+function identityFile(user2) {
+  return join(userDir(user2), "identity.json");
+}
+function contactsFile(user2) {
+  return join(userDir(user2), "contacts.json");
+}
+function inboxFile(user2) {
+  return join(userDir(user2), "inbox.db");
+}
+
+// src/current-user.ts
+var pointerPath = () => join2(usersDir(), ".current");
+function identityDirs() {
+  const dir = usersDir();
+  if (!existsSync2(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).filter((name) => existsSync2(identityFile(name)));
+}
+function readMeta(dir) {
+  try {
+    return JSON.parse(readFileSync3(identityFile(dir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function resolveDir(sel) {
+  const dirs = identityDirs();
+  if (dirs.includes(sel)) return sel;
+  const low = sel.toLowerCase();
+  for (const d of dirs) {
+    const id = readMeta(d);
+    if (!id) continue;
+    if (id.handle === sel || id.signPub === sel) return d;
+    if (id.name && id.name.toLowerCase() === low) return d;
+  }
+  return null;
+}
+function currentUser() {
+  const env = process.env.MESSENGER_USER?.trim();
+  if (env) return resolveDir(env) ?? env;
+  const pointer = pointerPath();
+  if (existsSync2(pointer)) {
+    const val = readFileSync3(pointer, "utf8").trim();
+    if (val) return resolveDir(val) ?? val;
+  }
+  const dirs = identityDirs();
+  if (dirs.length === 1) return dirs[0];
+  return null;
+}
+
+// src/config.ts
+var DEFAULT_MAILBOX_URL = "https://mailbox.cli-chat-mcp.workers.dev";
+function resolveMailboxUrl() {
+  return process.env.MESSENGER_MAILBOX_URL?.trim() || DEFAULT_MAILBOX_URL;
+}
+
+// src/check-inbox.ts
+var user = currentUser();
+var hookEventName = "SessionStart";
+try {
+  const payload = JSON.parse(readFileSync4(0, "utf8"));
+  if (payload?.hook_event_name) hookEventName = payload.hook_event_name;
+} catch {
+}
+var setUp = false;
+if (user) {
+  try {
+    loadIdentity(identityFile(user));
+    setUp = true;
+  } catch {
+  }
+}
+if (!setUp) {
+  if (hookEventName === "SessionStart") {
+    const text = `You don't have a cli-chat account on this device yet \u2014 I'll create one automatically the first time you message someone. Say "set me up as Sam" if you'd like to choose your name (and get your 6-character code) now.`;
+    console.log(
+      JSON.stringify({
+        systemMessage: text,
+        hookSpecificOutput: {
+          hookEventName,
+          additionalContext: text + " (No identity exists on this device. The other messaging tools return no_account until then; when that happens, or if the user asks to get set up, call create_account automatically \u2014 defaulting the name to the OS login unless the user gave one \u2014 then continue.)"
+        }
+      })
+    );
+  }
+  process.exit(0);
+}
+var url = resolveMailboxUrl();
+try {
+  await initCrypto();
+  const me = loadIdentity(identityFile(user));
+  const book = loadContacts(contactsFile(user));
+  const cache = openMailbox(inboxFile(user));
+  const now = () => Date.now();
+  const ctx = {
+    me,
+    book,
+    cache,
+    client: createMailboxClient(url, me, now),
+    now
+  };
+  const whoami = `You are acting as the messenger for ${me.name ?? user}` + (me.handle ? ` (their code is ${me.handle})` : "") + ".";
+  await sync(ctx);
+  const unread = unreadFor(cache, me.signPub);
+  if (unread.length === 0) {
+    if (hookEventName === "SessionStart") {
+      console.log(JSON.stringify({ hookSpecificOutput: { hookEventName, additionalContext: whoami } }));
+    }
+    process.exit(0);
+  }
+  const senders = [...new Set(unread.map((m) => displayNameByKey(book, m.sender)))];
+  const noun = `${unread.length} new message${unread.length > 1 ? "s" : ""}`;
+  let summary = `\u{1F4EC} ${noun} from ${senders.join(", ")} \u2014 want me to read ${unread.length > 1 ? "them" : "it"}?`;
+  if (hookEventName === "SessionStart") {
+    summary += `
+   \u21B3 Tip: write "watch" in a new terminal for auto-reading new messages into our chat.`;
+  }
+  const bodies = [];
+  for (const m of unread) {
+    bodies.push(`
+From ${displayNameByKey(book, m.sender)} (id ${m.id}):
+  ${m.body}`);
+    markRead(cache, m.id, now());
+  }
+  console.log(
+    JSON.stringify({
+      systemMessage: summary,
+      hookSpecificOutput: {
+        hookEventName,
+        additionalContext: whoami + `
+
+[inbox] ${noun} waiting (already marked read). The user has ONLY been shown a count, NOT the contents. Do NOT print the bodies below unless the user asks to hear them (e.g. "read it", "go on", "yes"); then print the relevant message in full. Do NOT call messages_available/read_message for these \u2014 use the bodies here. To reply, use draft_reply with the id, asking for any missing fact first. The on-open summary already shows a "say watch" tip, so don't repeat it; if the user says "watch", call the \`watch\` tool and auto-read new mail in full as it arrives.
+` + bodies.join("\n")
+      }
+    })
+  );
+} catch {
+  process.exit(0);
+}