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>
153 lines
7.0 KiB
Markdown
153 lines
7.0 KiB
Markdown
# claudemesh crypto — external review packet
|
|
|
|
**Goal:** 2-day review of the claudemesh cryptographic surface by an
|
|
external reviewer familiar with libsodium, x25519/ed25519, authenticated
|
|
encryption, and hash-chain audit logs.
|
|
|
|
**Status:** self-audited + Codex-reviewed. Not yet reviewed by an
|
|
independent human with security expertise.
|
|
|
|
## Scope
|
|
|
|
### Files in scope
|
|
|
|
| File | LoC | What it does |
|
|
|---|---|---|
|
|
| `apps/broker/src/crypto.ts` | ~400 | Hello signature verification, canonical invite bytes (v1+v2), `sealRootKeyToRecipient` via `crypto_box_seal`, `verifyInviteV2`, `claimInviteV2Core` (gated). |
|
|
| `apps/broker/src/broker-crypto.ts` | 70 | AES-256-GCM encryption-at-rest for MCP env vars. Key from `BROKER_ENCRYPTION_KEY` or ephemeral in dev. |
|
|
| `apps/broker/src/audit.ts` | ~250 | Hash-chained audit log. Canonical JSON payload hash, per-mesh `pg_advisory_xact_lock` for concurrent writers. |
|
|
| `apps/cli/src/services/crypto/box.ts` | 60 | `crypto_box_easy` / `crypto_box_open_easy` wrappers that accept ed25519 keys and convert to curve25519 via `crypto_sign_*_to_curve25519`. |
|
|
| `apps/cli/src/services/crypto/keypair.ts` | ~50 | `generateKeypair` wrapping `crypto_sign_keypair`. |
|
|
| `apps/cli/src/commands/backup.ts` | ~180 | Config backup via Argon2id + XChaCha20-Poly1305 (`crypto_aead_xchacha20poly1305_ietf_*`) from a user passphrase. |
|
|
| `apps/cli/src/services/invite/parse-v1.ts` | ~160 | Invite payload decode + signature verification, URL parsing, short-code resolution. |
|
|
|
|
### Out of scope
|
|
|
|
- TLS config (Traefik termination)
|
|
- Postgres at-rest disk encryption
|
|
- Homebrew/winget binary signing pipeline
|
|
- Secrets storage on the user's machine (we rely on OS file mode 0600)
|
|
|
|
## Threat model
|
|
|
|
### Adversary profile
|
|
|
|
- **Network attacker** on the wire between CLI and broker. Controls
|
|
DNS, can inject packets, can replay. TLS terminates at Traefik;
|
|
assume TLS is trusted.
|
|
- **Malicious broker** operator. Can read any row in Postgres.
|
|
- **Mesh peer** with a valid member record. Can try to escalate
|
|
privileges, impersonate other members, replay, DoS, exfiltrate
|
|
other members' messages.
|
|
- **Laptop thief** who has the user's `~/.claudemesh/` directory but
|
|
not the login password. (Keys on disk at mode 0600.)
|
|
|
|
### Must hold
|
|
|
|
- E2E: broker cannot read plaintext of direct messages.
|
|
- Signature: no member can forge messages signed as another member.
|
|
- Invite integrity: modifying an invite URL invalidates the signature.
|
|
- Backup secrecy: an attacker with the backup file but not the
|
|
passphrase learns nothing.
|
|
- Audit integrity: tampering with an audit row breaks chain
|
|
verification.
|
|
|
|
### Known weaknesses (deliberate)
|
|
|
|
- **root_key in v1 invite URL**: current long URL form carries the
|
|
mesh root key in base64(JSON). Short-URL mode (`/i/<code>`) resolves
|
|
to the same token server-side, so this does NOT reduce the exposure.
|
|
v2 protocol moves root_key out of the URL but CLI migration is not
|
|
yet shipped.
|
|
- **Session-key routing identity**: a peer can claim arbitrary
|
|
`sessionPubkey` in hello (validated as 64-hex in alpha.36 but not
|
|
proven-own). Proof-of-secret-key for session key is not enforced.
|
|
Impact: a peer can route messages as any session pubkey it chooses
|
|
but cannot decrypt replies without the matching secret, so the
|
|
impact is DoS/confusion, not impersonation.
|
|
- **mesh.owner_secret_key stored plaintext** in the DB. A malicious
|
|
broker can issue arbitrary invites. Mitigated only by DB access
|
|
control.
|
|
|
|
## Review checklist for the reviewer
|
|
|
|
1. **libsodium usage**
|
|
- Are nonces generated with `randombytes_buf` and never reused?
|
|
- `crypto_box_easy` / `crypto_box_open_easy` order and parameters correct?
|
|
- Are ed25519 keys converted to curve25519 on BOTH sides consistently?
|
|
- Is `crypto_sign_detached` / `crypto_sign_verify_detached` used with the right message bytes?
|
|
|
|
2. **Invite protocol**
|
|
- Canonical bytes v1 + v2 format strings stable across CLI and broker?
|
|
- Replay protection: is a v1 URL reusable? (short URL + usedCount)
|
|
- Is the `maxUses` counter race-safe? (atomic UPDATE with `lt`)
|
|
- v2 root_key sealing: does `crypto_box_seal` fit the trust model?
|
|
- Is recipient_x25519_pubkey validated on both shape and length?
|
|
|
|
3. **Audit chain**
|
|
- Is the canonical JSON serialization reviewable and stable?
|
|
- Does `pg_advisory_xact_lock` actually serialize writes on the same mesh under HA?
|
|
- Can a malicious broker rewrite history by dropping the `lastHash` cache + DROPping rows + replaying with a new chain? (Yes — documented. Mitigation is append-only at the DB level.)
|
|
|
|
4. **At-rest encryption (broker-crypto.ts)**
|
|
- AES-256-GCM with 12-byte IV + 16-byte tag — correct, but is the IV generation guaranteed random and unique per encryption?
|
|
- Any concern about auth tag truncation or nonce collision under high volume?
|
|
|
|
5. **Backup (cli/commands/backup.ts)**
|
|
- Argon2id params reasonable? (INTERACTIVE — should possibly be SENSITIVE.)
|
|
- XChaCha20-Poly1305 parameter order?
|
|
- Does the passphrase-minimum (12 chars) match the Argon2id parameters?
|
|
- Is the salt stored alongside the ciphertext and read back correctly?
|
|
|
|
6. **Session vs member key**
|
|
- When is which key used? Is there any path where one is trusted for the other's purpose?
|
|
|
|
7. **Hello signature**
|
|
- Timestamp skew window (`±60s`) — does the broker reject out-of-window replays?
|
|
- Is the canonical hello string covered by the signature exactly?
|
|
|
|
8. **Grants**
|
|
- Can a peer bypass server-side grant enforcement by lying about their
|
|
own sender key in hello? (Signature pins memberPubkey to a real
|
|
signing key, but sessionPubkey isn't proven.)
|
|
|
|
## Test coverage supplied
|
|
|
|
- `apps/broker/tests/invite-signature.test.ts`
|
|
- `apps/broker/tests/invite-v2.test.ts`
|
|
- `apps/broker/tests/hello-signature.test.ts`
|
|
- `apps/broker/tests/audit-canonical.test.ts`
|
|
- `apps/broker/tests/grants-enforcement.test.ts`
|
|
- `apps/broker/tests/rate-limit.test.ts`
|
|
- `apps/broker/tests/encoding.test.ts`
|
|
- `apps/broker/tests/dup-delivery.test.ts`
|
|
- `apps/cli/tests/unit/crypto-roundtrip.test.ts`
|
|
|
|
## Deliverables expected from reviewer
|
|
|
|
1. **Findings list** — severity (crit/high/med/low), file:line, fix recommendation.
|
|
2. **Protocol-level critique** — anything in the invite or hello flow that can be exploited with a valid account.
|
|
3. **Tooling recs** — libsodium best-practice they'd follow differently.
|
|
4. **Go/no-go** for v1.0.0 GA assuming the findings are addressed.
|
|
|
|
## Budget
|
|
|
|
2 person-days. Hourly rate acceptable; fixed-fee preferred. Request
|
|
for quote from reviewers with published libsodium / PKI experience
|
|
(see recommended list below).
|
|
|
|
## Recommended reviewers
|
|
|
|
- Filippo Valsorda (independent, ex-Go crypto lead, known for age/tink reviews)
|
|
- Trail of Bits (firm-rate; their Tamarin+reviewer combo is strong)
|
|
- Latacora (firm; expensive but thorough)
|
|
- NCC Group (firm; good for libsodium-specific)
|
|
- Cure53 (firm; EU, fast turnaround)
|
|
|
|
## Review deliverable format
|
|
|
|
Markdown report with:
|
|
- Findings table (id, severity, file:line, summary, recommended fix)
|
|
- Protocol notes
|
|
- One-page exec summary for non-technical stakeholders
|