05729ad8a4
Backwards compat shim (task 27) - requireCliAuth() falls back to body.user_id when BROKER_LEGACY_AUTH=1 and no bearer present. Sets Deprecation + Warning headers + bumps a broker_legacy_auth_hits_total metric so operators can watch the legacy traffic drain to 0 before removing the shim. - All handlers parse body BEFORE requireCliAuth so the fallback can read user_id out of it. HA readiness (task 29) - .artifacts/specs/2026-04-15-broker-ha-statelessness-audit.md documents every in-memory symbol and rollout plan (phase 0-4). - packaging/docker-compose.ha-local.yml spins up 2 broker replicas behind Traefik sticky sessions for local smoke testing. - apps/broker/src/audit.ts now wraps writes in a transaction that takes pg_advisory_xact_lock(meshId) and re-reads the tail hash inside the txn. Concurrent broker replicas can no longer fork the audit chain. Deploy gate (task 30) - /health stays permissive (200 even on transient DB blips) so Docker doesn't kill the container on a glitch. - New /health/ready checks DB + optional EXPECTED_MIGRATION pin, returns 503 if either fails. External deploy gate can poll this and refuse to promote a broken deploy. Metrics dashboard (task 32) - packaging/grafana/claudemesh-broker.json: ready-to-import Grafana dashboard covering active conns, queue depth, routed/rejected rates, grant drops, legacy-auth hits, conn rejects. Tests (task 28) - audit-canonical.test.ts (4 tests) pins canonical JSON semantics. - grants-enforcement.test.ts (6 tests) covers the member-then- session-pubkey lookup with default/explicit/blocked branches. Docs (task 34) - docs/env-vars.md catalogues every env var the broker + CLI read. Crypto review prep (task 35) - .artifacts/specs/2026-04-15-crypto-review-packet.md: reviewer brief, threat model, scope, test coverage list, deliverables. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@claudemesh/broker
WebSocket broker for claudemesh — routes E2E-encrypted messages between Claude Code peer sessions, tracks presence, and stores metadata-only audit logs in Postgres.
What it is
A standalone Bun-runtime WebSocket server that sits between Claude Code sessions. Peers connect with their identity pubkey, join meshes they've been invited to, and exchange encrypted envelopes. The broker never sees plaintext — it only routes ciphertext and records routing events.
Running locally
# from the repo root
pnpm --filter=@claudemesh/broker dev # watch mode
pnpm --filter=@claudemesh/broker start # production
Required env vars
| Var | Default | Purpose |
|---|---|---|
BROKER_PORT |
7900 |
Single port for HTTP routes + WebSocket upgrade |
DATABASE_URL |
— | Postgres connection string (shared with apps/web) |
STATUS_TTL_SECONDS |
60 |
Flip stuck-"working" peers to idle after this TTL |
HOOK_FRESH_WINDOW_SECONDS |
30 |
How long a hook signal beats JSONL inference |
Routes (single port)
| Path | Protocol | Purpose |
|---|---|---|
/ws |
WebSocket | Authenticated peer connections |
/hook/set-status |
HTTP POST | Claude Code hook scripts report status |
/health |
HTTP GET | Liveness probe |
Depends on
@turbostarter/db— Drizzle/Postgres schema (uses themeshpgSchema)@turbostarter/shared— cross-package utilities
Deployment
Runs as a separate process (not inside Next.js). Intended deployment targets:
Fly.io, Railway, or Coolify on the surfquant VPS. WebSocket server must be
reachable at ic.claudemesh.com.
Status
Scaffold only. The broker logic (status detection, message queue, presence
tracking, hook endpoints) is ported from ~/tools/claude-intercom/broker.ts
in a follow-up step.