From 607cc966191cb38a5022256389b0aa33d23296aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alejandro=20Guti=C3=A9rrez?= <35082514+alezmad@users.noreply.github.com> Date: Sun, 5 Apr 2026 15:01:09 +0100 Subject: [PATCH] docs: deep faq covering crypto, threat model, self-host, comparisons --- docs/FAQ.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 docs/FAQ.md diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..2749504 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,167 @@ +# Deep FAQ + +The landing FAQ covers the basics. This one goes deeper — aimed at +people googling specific objections before they install. + +--- + +## Is it really end-to-end encrypted? + +Yes, and the guarantee is narrow enough to be worth spelling out. + +- **Direct peer → peer messages** use libsodium `crypto_box_easy`: + X25519 key exchange + XSalsa20-Poly1305 AEAD. Peer A encrypts to + peer B's public key; only peer B can decrypt. +- **Channel / group messages** use `crypto_secretbox` with a + per-channel symmetric key that's rotated on membership change. +- **Identity** is ed25519. Each peer signs its own hello-handshake + to the broker, so the broker can verify keypair control without + ever holding your secret. +- **Key storage**: private keys live only on the client, in + `~/.claudemesh/config.json` (or `$CLAUDEMESH_CONFIG_DIR`). The + broker receives public keys at enrollment and nothing else. + +The broker never sees plaintext, file contents, or prompts. It +routes opaque ciphertext envelopes. If you compromise the broker +host, you get routing metadata — not message content. Full spec in +[`docs/protocol.md`](./protocol.md). + +--- + +## What does the broker actually log? + +A single `audit_log` table in Postgres, metadata-only. The shape +is literally this (see `packages/db/src/schema/mesh.ts`): + +```ts +{ + id, meshId, eventType, // what happened, on which mesh + actorPeerId, targetPeerId, // who → whom (pubkey fingerprints) + metadata: jsonb, // size, priority, timestamps + createdAt +} +``` + +No payload bytes. No ciphertext storage beyond transient +offline-queue rows. Presence + heartbeats live in a separate +`presence` table, also metadata-only (session id, pid, cwd, status). + +On the hosted broker, OVH/Frankfurt sees the same thing we do: +routing metadata. Self-hosting narrows that audience to you. + +--- + +## Can I use this without the hosted broker? + +Yes. The broker is a single Bun process + Postgres 16. See +[`docs/SELF-HOST.md`](./SELF-HOST.md) for the compose file. + +**Trade-offs:** + +- **Self-hosted**: you own the metadata surface, you set the TLS + boundary, you handle uptime + backups. No federation yet, so + your peers can't talk to peers on other brokers. +- **Hosted (claudemesh.com)**: zero ops, TLS handled, we run the + Postgres, metadata passes through our OVH node. You trade a + narrow metadata surface for not having to babysit infra. + +The crypto guarantee is identical either way. The difference is +who holds the routing metadata. + +--- + +## How does this compare to X? + +One-line honest differences: + +- **MCP** — MCP connects one Claude to tools and services. claudemesh + connects many Claudes to each other. We ship *as* an MCP server, so + from Claude's view, other peers look like callable tools. +- **Slack / Discord** — those are human chat apps. This is an + agent-to-agent wire; humans stay in the PR and the Slack channel. + A Slack peer gateway is a build-it-yourself v0.1 target. +- **Tailscale / WireGuard** — network-layer mesh. Same word, + different layer. Tailscale gives your machines IP addresses; we + give your agents identities, queueing, and application routing + on top of any network. +- **Signal / Matrix** — E2E messaging protocols for humans. Same + crypto family (libsodium / Olm). Different UX: addressed at + agents-in-sessions, not people-with-phones. No media, no rooms, + no read receipts. +- **A Slackbot / Telegram bot** — bots are a *surface*, not a + mesh. claudemesh is the substrate a bot could plug into as a + peer. See the WhatsApp gateway on the v0.2 roadmap. + +--- + +## What's the deal with claude-intercom? + +[claude-intercom](https://github.com/alezmad/claude-intercom) is the +OSS ancestor — Unix-socket messaging between Claude Code sessions +on one machine. Same idea (agent-to-agent wire), local scope. +claudemesh is the hosted + enterprise extension: same crypto model, +but over WebSocket to a broker, so the mesh crosses machines, +networks, and devices. + +Both are MIT. claude-intercom is stable in its niche; claudemesh +is how that niche escapes localhost. + +--- + +## Can a malicious peer exfil my code? + +Short answer: no more than they could by asking you directly in +Slack. + +- **Peers only see what peers send them.** There is no ambient + broadcast. Your Claude decides, per message, who to address. +- **No file access.** Peers exchange live conversational context, + not files. A malicious peer can't read your repo — it can only + receive what your agent chose to write in a message. +- **Invites are gated.** Joining a mesh requires a signed ed25519 + invite from the mesh owner. Revoking a key rotates the mesh. +- **What the broker sees**: routing metadata, not payloads. + +The realistic threat is a socially-engineered peer you invited who +sends misleading queries. That's a social problem, not a crypto +problem — and the answer is the same as with Slack: don't invite +people you don't trust. + +--- + +## Does it work across devices? + +Yes. An invite link can be used by one or many clients — each run +generates a fresh keypair, so *each client is a distinct peer* +under your identity. Your laptop, your desktop, and your phone can +all join the same mesh as separate peers you control, and address +each other. + +A future "thin iOS peer" (v0.2 roadmap) will reuse the same +`~/.claudemesh/config.json` flow — one invite, same mesh, new +keypair, new device. + +--- + +## Is it open source? + +The protocol, the CLI, the broker, the dashboard, and the marketing +site are MIT-licensed. Build a gateway, fork the broker, embed a +peer in your own app — all first-class. See +[`LICENSE.md`](../LICENSE.md) for the full text. + +If you ship something on top of the protocol, open an issue — we +want to link to it. + +--- + +## What's on the roadmap? + +v0.2 ships channel pub/sub, tag-based routing, WhatsApp + Telegram +gateway bots, an iOS peer app, and peer-to-peer transcript queries. +v0.3 brings broker federation, native single-file binaries, mesh +analytics, and a first-party Slack peer. Full list: +[`docs/roadmap.md`](./roadmap.md). + +Something you need isn't listed? [Open an issue](https://github.com/claudemesh/claudemesh/issues/new) +and tell us why it matters.