docs: protocol + roadmap stubs for v0.1.0 launch

docs/protocol.md

@@ -0,0 +1,98 @@
+# claudemesh protocol
+
+claudemesh uses signed ed25519 identities, `crypto_box` for direct
+peer-to-peer messages, and `crypto_secretbox` for group/channel fanout,
+carried over a WebSocket to a routing-only broker. Plaintext never
+leaves the peer.
+
+> **Status:** stable for v0.1.0 peers. The wire format and crypto
+> primitives below are frozen. Higher-level semantics (channels, tags)
+> are still evolving — see [`docs/roadmap.md`](./roadmap.md).
+
+---
+
+## Wire messages
+
+All broker ↔ peer traffic is line-delimited JSON on a single WebSocket.
+
+| Type         | Direction     | Purpose                                            |
+|--------------|---------------|----------------------------------------------------|
+| `hello`      | peer → broker | signed handshake — proves control of ed25519 key   |
+| `hello_ack`  | broker → peer | confirms identity + returns current mesh presence  |
+| `send`       | peer → broker | ciphertext envelope addressed to one or more peers |
+| `ack`        | broker → peer | broker-side delivery receipt for a `send`          |
+| `push`       | broker → peer | an inbound envelope the broker is forwarding       |
+| `error`      | broker → peer | handshake or authorization failure                 |
+
+Each message carries a monotonic `seq`, a mesh id, and the sender's
+public key fingerprint. The broker verifies the `hello` signature and
+then only routes — it never inspects payloads.
+
+---
+
+## Crypto
+
+- **Signing** — ed25519 (libsodium `crypto_sign`). One keypair per peer
+  per mesh, generated on the client at enrollment.
+- **Direct messages** — X25519 + XSalsa20-Poly1305 via libsodium
+  `crypto_box_easy`. Peer A encrypts to peer B's public key.
+- **Channel / group messages** — `crypto_secretbox` with a per-channel
+  symmetric key, rotated on membership change.
+- **Nonces** — 24-byte random nonces, bundled with ciphertext.
+
+Keys live on the client in `~/.claudemesh/config.json` (or
+`$CLAUDEMESH_CONFIG_DIR`). The broker operator has nothing to decrypt.
+
+Canonical implementations:
+- broker side: [`apps/broker/src/crypto.ts`](../apps/broker/src/crypto.ts)
+- client side: [`apps/cli/src/crypto/`](../apps/cli/src/crypto/)
+
+---
+
+## Invite links
+
+A mesh owner issues signed invite links in the form:
+
+```
+ic://join/<base64url(JSON)>
+```
+
+The inner JSON looks like:
+
+```jsonc
+{
+  "mesh":    "acme-payments",   // mesh slug
+  "broker":  "wss://ic.claudemesh.com/ws",
+  "exp":     1717459200,        // unix seconds
+  "role":    "peer",            // peer | admin
+  "enroll":  "<ed25519 pubkey of the mesh owner>",
+  "sig":     "<ed25519 signature over the above fields>"
+}
+```
+
+The CLI verifies `sig` with `enroll`, checks `exp`, generates a fresh
+peer keypair, and posts enrollment to the broker. The broker records
+the new peer and rebroadcasts presence.
+
+Invite-link issuance: [`apps/cli/src/invite/`](../apps/cli/src/invite/).
+
+---
+
+## Self-hosting
+
+Point the CLI at your own broker:
+
+```sh
+export CLAUDEMESH_BROKER_URL="wss://broker.yourteam.local/ws"
+```
+
+The broker is `apps/broker` — a single Node/Bun process with Postgres
+for presence + offline queueing. No secrets to share. Anyone holding a
+valid invite can join; anyone whose signature fails is dropped.
+
+---
+
+## What's next
+
+Tag-based routing, channel pub/sub, and federation between brokers are
+on the [v0.2 roadmap](./roadmap.md). Full protocol spec is in progress.