path: root/CLAUDE.md

# MeshBay — Project Conventions

## What this project is

MeshBay is a decentralized peer-to-peer platform for file sharing, video streaming, and group messaging.
See `docs/meshbay-draft-v5.md` for the architecture specification (v3/v4 superseded).

## Repository structure

```
meshbay/
├── packages/
│   ├── meshbay-common/   # Shared crypto + protocol — python3-meshbay-common RPM
│   ├── meshbay-hub/      # Hub server (FastAPI + PostgreSQL) — meshbay-hub RPM
│   └── meshbay-node/     # Node daemon + local UI — meshbay-node RPM
├── poc/                  # POC spike scripts (reference, not production)
├── docs/                 # Architecture drafts and POC plans
├── packaging/            # RPM spec files, DEB control files, systemd units
└── QE/                   # NOT versioned (.gitignore) — test artefacts, credentials, demos
    ├── demo-v1/          #   Scripts démo opérationnels (setup_demo.py, run_node.py, download.py)
    ├── spikes/           #   Expérimentations futures (remplace ~/draft/)
    └── server-state/     #   Inventaire de ce qui tourne sur meshbay.org
```

**Règle QE/** : tout test sur meshbay.org doit ouvrir le port UFW, tester, et
fermer le port + tuer les processus dans le MÊME bloc de commandes.
Jamais de processus orphelins ni de ports ouverts après un test.

## Python environment

- **Minimum Python:** 3.12
- **Build backend:** hatchling (per package `pyproject.toml`)

```bash
# Créer le venv (--clear si recréation sur une autre machine/OS)
python3 -m venv .venv --clear
source .venv/bin/activate

# Toutes les dépendances sont déclarées dans les pyproject.toml — un seul pip install suffit
pip install -e packages/meshbay-common -e packages/meshbay-hub -e packages/meshbay-node
pip install pytest pytest-asyncio aiosqlite   # extras dev
```

Les deps clés (aioquic, watchdog, fastapi, blake3, etc.) sont dans les `pyproject.toml`
et installées automatiquement. Ne pas ajouter manuellement des packages sans les déclarer
dans le bon `pyproject.toml`.

> **Ne jamais copier `.venv/` entre machines d'OS différents.** Si rsync depuis Fedora vers Ubuntu,
> exclure `.venv/` et recréer sur la cible avec `python3 -m venv .venv --clear`.
> Sans `--clear`, `certifi.where()` pointe vers un chemin Fedora inexistant sur Ubuntu → `FileNotFoundError`.

```bash
# Lancer les tests
.venv/bin/pytest
```

## Code conventions

- **Linter/formatter:** ruff (`uv run ruff check .` / `uv run ruff format .`)
- **Line length:** 100
- **Type hints:** required on all public functions
- **Comments:** only when the WHY is non-obvious; no docstrings restating the function name
- **No prints in library code** — use `logging` module

## Versioning

### Package versions (SemVer)
- Format: `MAJOR.MINOR.PATCH`
- Pre-1.0: breaking changes bump MINOR, not MAJOR
- All three packages share the same version number (released together)

### Protocol versions (independent)
- MNP: `0.2` → bumped independently of package version
  - 0.2 added `PING`/`PONG` and backward chat paging (`before` / `has_more`).
    Additive, so an 0.1 peer still works: it sends no `before` and is answered
    with the newest page, which is what it wanted
- MHP: `0.1` → bumped independently of package version
- Every wire message carries a `v` field
- Breaking change → MAJOR bump; backward-compatible → MINOR bump
- N-2 MINOR backward compatibility guaranteed

## Commit messages (Conventional Commits)

```
feat(node): add directory watcher with watchdog
fix(hub): include jti in all JWT tokens
chore(common): add Argon2id calibration to crypto.py
docs: update draft v3 with POC findings
test(common): add wrap/unwrap GEK round-trip test
```

Types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `perf`
Scope: `hub`, `node`, `common`, or omitted for cross-cutting

## Security rules

- **Never commit private keys** (hub_private.pem, *.key, unlock.key, keystore.enc)
- **Never commit QE/** — credentials, test keys, demo data go there
- **Never log GEK, private keys, or plaintext passwords** — even at DEBUG level
- **meshbay.org is internet-facing** — open port → test → close port + kill processes in same block

## First security review (2026-08-10) — see `first-review.md`

**Critical (before Phase 7):**
- **C1** Chat: Sender Keys protocol, NOT shared Double Ratchet (pairwise protocol
  would cause key/nonce reuse in group context). `ratchet.py` kept for future 1:1 DM.
- **C2** JWT must carry `"groups": [group_ids]` claim. Node MNP handshake must verify
  group membership before serving content. Without this, any authenticated user
  accesses any group.

**Significant (Phase 7-8):**
- **S1** Admin revocation endpoint has no authz check ✅ DONE (Phase 8.1 — config-based require_admin)
- **S2** Email stored in plaintext (spec says encrypted at rest) ✅ DONE (Phase 8.2 — AES-256-GCM, HKDF from hub key)
- **S3** jti denylist push via hub→node WebSocket → Phase 7.2
- **S4** AES-GCM keystore IV fixed: 128-bit → 96-bit (NIST SP 800-38D) ✅ DONE
- **S5** Refresh token rotation (one-time use) ✅ DONE (Phase 8.3 — family-based reuse detection)

**Node sovereignty (2026-08-12):**
- **NS1** GEK-HMAC proof in handshake — blocks hub admin from accessing any group content ✅ DONE
- **NS2** Ed25519 challenge-response for admin operations — blocks hub admin impersonation ✅ DONE
- **NS3** `gek_req` endpoint removed — node never serves GEK in plaintext ✅ DONE
- **NS4** ~~`admin_pk_ed25519` auto-pinned from keystore~~ ❌ **that was finding M3.** The
  keystore key is not the key the browser signs with, so every admin operation failed
  closed. Authority now comes from the node's roster — `meshbay-node operator pair`
  (2026-08-14). `admin_pk_ed25519` was kept as a legacy form and is now **removed**
  (2026-08-15) — one source of authority, the roster. A config still naming it is
  warned about at startup, never obeyed. Never auto-pin again, and never resolve the
  operator's key through the hub
- **NS5** DTLS channel binding in GEK-HMAC — `HMAC(GEK, nonce || offer_fp || answer_fp)` detects WebRTC signaling MitM ✅ DONE
- **NS6** Chat `sender_id` enforced from authenticated session — prevents impersonation ✅ DONE
- **NS7** Node Ed25519 auth — node daemon authenticates to hub via `POST /v1/nodes/auth` (Ed25519 signed timestamp), no auth_key/password on node. JWT `scope: "node"` blocks group management (create/add/delete/join). Operator manages groups from browser only. ✅ DONE
- **NS8** GEK-required enforcement — node REFUSES connections when GEK is None (no `gek_required: false` bypass). GEK initialization via node local admin UI only. ✅ DONE

**Known remaining trust assumptions (Phase 12 — all actionable items done):**
- **T1** ✅ DONE: password split (auth_key / bundle_key, independent PBKDF2). Legacy migration on first login.
- **T2** ✅ **CLOSED 2026-08-14** (the finding is H3). Not by safety numbers: the invite
  path stopped reading the directory. The node holds the GEK and wraps it for a key the
  recipient proves possession of; identities are bound to accounts by one-time codes the
  hub never sees. See `docs/invite-pairing-v1.md`
- **T3** SPA served by hub → fundamentally unsolvable in browser. Fix: native client or browser extension

**T3 attack surface reduction (2026-08-12, all phases complete):**
- **Phase 1** ✅ DONE: GEK bundles moved from hub to node P2P (WebRTC DataChannel). No hub fallback.
- **Phase 2** ✅ DONE: Keypair bundles moved from hub to node P2P. Registration stores locally, pushed to node on first connect. Hub never stores keypair bundles.
- **Phase 3** ✅ DONE: Hub GEK cleanup — `GET /gek` endpoint removed, `GEKBundle` model removed, `gek_bundles` table dropped, `keypair_bundle` column removed, member-add URL cleaned (`/gek` suffix removed), Alembic migrations updated.

**Browser crypto hardening (2026-08-13):**
- `_bundleKey` persisted in IndexedDB (CryptoKey survives page refresh)
- `_sessionKeys` persisted in sessionStorage (survives refresh, cleared on tab close)
- `_pkFromSk()`: derive X25519 public key from recovered private key via JWK export (no hub fetch)
- `regenerateKeys()` is gone entirely (2026-08-14): identity keys are per node, so
  rotation is `meshbay-node member unpin <user>` plus a fresh code
- Raw answer SDP saved before `setRemoteDescription` (Chrome strips sha-256 from multi-hash SDP)
- Upload chunk size: 48KB (fits aiortc SCTP limit after msgpack overhead)

**Architecture validated:** crypto primitives, GEK wrapping (ECIES), trust model,
key hierarchy, on-the-fly encryption, transport abstraction, DTLS channel binding.

## Second security review (2026-08-13) — see `second-review.md`

**6 critical, 7 high findings. Phase 11.5 is BLOCKING — see `devel-phases-next.md`.**
The current build must not host real private data.

The claims above about node sovereignty and P2P crypto material were **overstated**. The
GEK-HMAC proof, Ed25519 admin challenge and channel binding are real, but they are enforced
on the WebRTC path only, and three other paths into the node were left behind.

- **C1** Node HTTP API (`http_server.py`) serves private group **index and plaintext files
  with no authentication**, on `0.0.0.0`, for every group — bypasses the entire sovereignty layer
- **C2** `/v1/nodes/ws` trusts a client-supplied `node_id` → any user hijacks a node's
  signaling identity and impersonates it to browsers
- **C3** The node never authenticates itself to the client (`node_pk` is never verified, no proof of possession)
- **C4** Keypair bundles are served pre-proof and pushed to every node joined; PBKDF2-only → offline password attack
- **C5** Any member can overwrite arbitrary shared files (upload) and seize the group GEK (`gek_bundle_store` + auto-activation)
- **C6** GEK proof exists on WebRTC only — QUIC and TCP accept a bare JWT (chat injection)
- **H1** Multi-group nodes share one `chat_store` and one peer registry → cross-group chat leak
- **H2** Stored XSS in the node admin UI via uploaded filename → node takeover
- **H3** Hub is the key directory → key substitution at invite yields the GEK. "Unreadable
  even by the hub" is true against a *passive* hub only

## Invite redesign (2026-08-14) — closes H3 and M3

See `docs/invite-pairing-v1.md`. Read it before touching invites, admin authority or
`gek_bundle_store`.

- **The node wraps the group key**, on every connection, for the X25519 key the joiner
  signed with their pinned Ed25519 identity. **Nothing fetches a public key from the hub
  to wrap for** — not the SPA, not `gek-init`. That lookup *was* H3
- **`gek_bundle_store` is deleted**, not gated. No member hands the node key material
- **The node's roster decides who gets the key**, not hub membership: a hub that invents
  an account and mints it a token gets `not_authorized_for_group`
- **One-time codes** bind a key to an account without the directory. 40 bits, single use,
  one account, node-wide lockout. 7 days for invitations, 24 h for operator pairing, both
  in `[node]` of node.toml
- **`join_policy`** (`invite`|`open`) is read from **node.toml, never the hub** — a hub
  able to declare a group open would be handed its key. Unknown group ⇒ `invite`
- Operator surface over SSH: `operator pair`, `member list|invite|revoke|unpin`. Deleting
  a file is the last browser-only operation
- Revocation now works for key delivery (nothing stored survives it) — but **still rotate
  the GEK**, the ex-member holds the current one

## Keypair bundles and the browser KDF (2026-08-14)

- The bundle key is **Argon2id 128 MB / t=3 / p=1**, WebAssembly vendored under
  `static/vendor/` (CSP forbids external hosts; 12.2 must keep `wasm-unsafe-eval`).
  **Do not change the parameters in one place**: `keyderive.js`, the QE harness and
  `test_bundle_kdf_parity.py` are held byte-identical by that test, and a mismatch
  presents as an account nobody can open
- Bundles carry an `MBK2` marker; the PBKDF2 form is still readable and is
  re-encrypted on the next backup. Both keys are derived at sign-in because the
  passphrase is deliberately not retained
- Cost is paid **once per sign-in** (650 ms bundle + 239 ms auth_key); reloading a
  page derives nothing — the key lives in IndexedDB
- The bundle is stored on **every node its owner joins**. That is what makes a
  second browser work, and it is C4: cracking one yields identity keys, hence
  content on *other* nodes and the ability to sign as that user. Draft-v5 §7.1 has
  the measured numbers. **The passphrase is the wall; the KDF is a speed bump**
- Floor: 12 characters and ~60 estimated bits, enforced client-side only — with the
  password split (T1) the hub never sees a passphrase

## Identity keys are PER NODE (2026-08-14)

See `docs/per-node-identity-v1.md`. Read it before touching registration, the
keypair bundle, or anything that looks like a user's public key.

- A keypair is created at **first contact with a node**, encrypted under the
  passphrase, and left on that node. Never reused elsewhere. Cracking one yields
  the identity used with that operator and nothing anywhere else
- **The hub stores and publishes no user keys.** `users.pk_ed25519`/`pk_x25519`
  are dropped, `PUT /me/keys` is gone, `/pubkeys` returns an account id and the
  node linking key. Do not reintroduce a key directory — that was H3
- **Tokens carry no `pk_user`.** The node recorded it as the uploader's identity
  and authorized deletion against it, so whoever issued tokens decided who could
  delete a file. Attribution uses the roster pin (`_pinned_pk`)
- Registration generates nothing, so a scripted signup is a real account —
  `QE/deploy/demo.py bootstrap` takes a wiped hub and node to a working demo
- The key handed back on a join belongs to the **group of the connection**, not
  the group named in the invitation (an operator pairs node-wide while opening a
  group)

## Two lessons that cost four rounds of live testing

- **`QE/deploy/e2e.py` cannot test `app.js`.** It is a second implementation of the
  client, written in the right order by construction: it proves the protocol and
  nothing about the SPA. Three ordering bugs passed it and failed in a browser.
  `test_spa_ordering.py` exists for that class and is worth extending
- **An unbounded `await` on the hub socket makes a node silently unreachable.**
  Three instances found in `maintain_ws`: the offer handler awaited inside the read
  loop, `ws.recv()` for auth with no timeout, and `return` on auth refusal ending
  the task for good. Symptom is always the same — daemon running, logging nothing,
  `connected_nodes: 0`, socket in CLOSE-WAIT. Look there first

- **A background task nobody holds can be collected mid-flight.** asyncio keeps
  only a *weak* reference to a task, so `asyncio.ensure_future(coro)` with the
  result thrown away may be garbage-collected while still running — the loop
  logs "Task was destroyed but it is pending!" and nothing else happens. For
  `_stream_video` that meant its `async with sem` never reached `__aexit__` and
  a transcode slot was lost for good. `WebRTCPeerSession._spawn()` exists for
  this; never call `ensure_future` there directly, and `test_task_lifetime.py`
  fails the build if anyone does

- **`await proc.wait()` after `kill()` still deadlocks on a full pipe.** ffmpeg
  outruns a credit-paced viewer; stop reading its stdout — which is what closing
  the player does — and the transport cannot finish closing, SIGKILL or not.
  Measured 2026-08-16: closing a viewer after 99 segments held a slot past the
  15 s handover timeout, so the next video hung and the one after was refused.
  Drain the pipes, then wait with a timeout, and release the slot regardless

- **Losing a peer must *stop* its work, not merely forget it.** The WebRTC
  `connectionstatechange` handler popped the session from a dict and nothing
  else, so a closed tab went on transcoding for the full 120 s credit timeout.
  Anything holding a resource needs `shutdown_tasks()` on the way out

- **A service worker being *active* is not the page being *controlled*.** An
  uncontrolled page's requests never reach the worker's fetch handler, so the
  streamed-download path handed over its stream and was never asked for it —
  `writer.write()` then blocks on backpressure that will never lift, and the
  download freezes after exactly one chunk. Require
  `navigator.serviceWorker.controller`, and have the worker confirm it actually
  served the request before trusting the sink

- **A removed `useState` leaves its setter behind and nothing complains.**
  `setActionsOpen` outlived `actionsOpen` and shipped: every action in the Files
  panel threw ReferenceError on click. `grep actionsOpen` does not find
  `setActionsOpen` — the capital breaks the match, which is exactly how it got
  through. `test_transport_contracts.py` compares called setters against
  declared ones

- **`node --check` validates syntax, not names.** It caught none of the above.
  Neither can `e2e.py`, which is a second implementation of the client. Source-
  reading tests are weak evidence and are the only evidence available for the
  SPA; prefer ones that re-derive a value from the source over ones that restate
  it

- **A test that models a fix agrees with it by construction.** The first
  buffer-ceiling test transcribed the player's credit loop into a small model and
  passed, while the player it was written for still hung on a phone. The model and
  the fix had the same author and the same misunderstanding. `tests/harness/
  mse_harness.mjs` lifts `bufferedAhead`, `evictBehind`, `flushQueue` and `pump`
  out of `app.js` *as text* and executes them; what it models is the browser. When
  even that was not enough, a headless Chrome driven against real fragmented MP4
  reproduced the defect in one run. Model the environment, never the code under
  test

- **`Cache-Control: no-cache` only binds a browser that asks.** One that cached
  the SPA before that header existed applies heuristic freshness — a fraction of
  the file's age, days for a file dated weeks ago — and does not ask at all. A
  fix can be written, tested, deployed, served and still not be what runs, which
  is indistinguishable from a fix that does not work. The whole module graph is
  now served under `/a/<content-hash>/` so relative imports inherit the prefix and
  no cache can serve yesterday's build or half of each. `test_asset_versioning.py`

- **Redeploying during someone else's test destroys the evidence.** A node deploy
  restarts the daemon, which kills every live WebRTC session — the tester sees
  "transport not connected" caused by nothing they did — and `deploy-node.sh`
  truncates `/tmp/meshbay-node.log`, taking the reproduction with it. Ask before
  deploying while a reproduction is in flight

- **`updateend` fires for `remove()` as well as `appendBuffer()`.** Crediting the
  node from that event paid it for the player's own evictions: every time room was
  made, more was asked for to fill it. Credit now follows the buffer, decided in
  one place, and the append path grants nothing

- **Flow control on a media stream is a window, not a debt.** Granting a credit
  per append means pulling at network speed, which for a film is far faster than
  watching it and fills the browser's SourceBuffer ceiling; accumulating those
  credits and releasing the balance when the buffer finally drains sends the lot
  in one burst and then says nothing for forty-six seconds. Bound the read-ahead
  by *time past the playhead* and top a small window up as segments land. A viewer
  deliberately holding credit must still say so, or the node's stall timeout ends
  a film that is merely paused

- **`create_all()` is not a migration.** It creates missing *tables* and never a
  missing *column*, so a new column reaches the tests (fresh DB every run) and never
  reaches the deployed hub. Symptom: one endpoint answering 500 with an HTML body
  while everything else works, and a `psycopg` `UndefinedColumn` in the journal.
  `deploy-hub.sh` runs `alembic upgrade head` before restarting the service; a schema
  change that skips a migration file will still pass every test you have

- **Some paths only exist in a browser, and only one browser has them.** The
  download-to-disk story is three different mechanisms — File System Access
  (Chrome/Edge), a service worker streaming a response (Firefox/Safari), and a
  blob as the floor — and no test in this repo exercises any of them.
  `test_downloads.py` pins the contracts by reading the source; the behaviour
  needs a person with a large file. Confirmed by the operator on 2026-08-15:
  Firefox, 180 MB, written to disk. Nothing multi-gigabyte has been measured

**Corrections to remember:**
- `punch_nat()` is **not** a NAT traversal stack — one UDP probe, no STUN, no candidate
  gathering, one ISP validated. **ICE/STUN (WebRTC) is the traversal path**, for native
  clients too (via `aiortc` in Python)
- Argon2id 256 MB was applied to the **hub only**; `crypto.py` keystore is still 64 MB
- Sender keys must be distributed **pairwise to identity keys**, never GEK-derived
- Chat is plaintext on the wire and at rest; the index is plaintext on the WebRTC path

## Known calibration TODOs

- Argon2id `memory_cost`: ✅ DONE — bumped to 262144 (256 MB) in pw_version=2.
  Existing v1 users (64 MB) are transparently rehashed on next successful login.
  CLI `calibrate` command still TODO for per-hardware tuning.

## NAT traversal — empirical results

### QUIC native clients (demo-v2)

SFR residential Fedora 44 → meshbay.org OVH VPS:
- **NAT type**: Port-Restricted Cone
- **Mechanism**: `QuicChunkServer.punch_nat()` sends probe from QUIC server socket
- **Scripts**: `QE/demo-v2/`

### WebRTC browser clients (Phase 9 spike, 2026-08-10)

**SFR residential NAT** — Mobile 4G SFR → node behind SFR residential (Port-Restricted Cone + CGNAT 4G):

| Test | ICE path | Result |
|---|---|---|
| WiFi LAN | IPv6 direct | OK, ~100ms |
| 4G + IPv6 | IPv6 inter-network | OK, ~600ms |
| 4G + IPv4 only (IPv6 disabled) | STUN hole-punch IPv4 | OK, ~650ms |

**Orange Livebox NAT** — Firefox/Chrome laptop (SFR) → node behind Orange residential NAT:

| Test | ICE path | Result |
|---|---|---|
| Chrome laptop → Orange node | IPv6 inter-network | OK, ~7000ms |
| Firefox laptop → Orange node | IPv6 inter-network | OK, ~6700ms |
| Firefox laptop → Orange node (IPv6 disabled) | STUN hole-punch IPv4 | OK, ~6900ms |

- **Two ISPs validated** — SFR + Orange residential NAT, both work without TURN
- **No TURN relay needed** — ICE/STUN handles both NAT types automatically
- **Hub role**: signaling only (SDP/ICE relay via WebSocket, <1 KB)
- **Data path**: browser ↔ node P2P via WebRTC DataChannel
- **Scripts**: `QE/demo-v3/run_node_webrtc.py`, test page at `/webrtc-test.html`

## Key modules — où trouver quoi

| Need | Module | File |
|---|---|---|
| Chunk encryption (prod) | `meshbay_common.crypto` | `crypto.py` |
| Key derivation from password | `meshbay_common.keyderive` | `keyderive.py` |
| Key bundle (web) | `meshbay_common.keyderive` | `keyderive.py` + `static/keyderive.js` |
| GEK wrap/unwrap (ECIES) | `meshbay_common.crypto` | `crypto.py` |
| Double Ratchet (1:1 DM, future) | `meshbay_common.ratchet` | `ratchet.py` |
| Sender Keys (group chat) | `meshbay_common.senderkeys` | `senderkeys.py` (Phase 7.5) |
| AES-GCM (browser) | `meshbay_common.webcrypto` | `webcrypto.py` + `static/crypto.js` |
| Node keystore | `meshbay_node.keystore` | `keystore.py` |
| QUIC NAT punch (native) | `meshbay_node.transport.quic_server` | `QuicChunkServer.punch_nat()` |
| WebRTC transport (browser) | `meshbay_node.transport.webrtc_server` | Phase 9.3 — `aiortc` DataChannel |
| WebRTC signaling (hub) | `meshbay_hub.api.signaling` | Phase 9.2 — SDP/ICE relay |
| Browser transport client | `static/transport.js` | Phase 9.4 — WebRTC DataChannel |
| Web SPA | `static/app.js` | Phase 9.6 — Preact + preact-router |
| File download (large) | `static/app.js` | File System Access API (`showSaveFilePicker`) — stream to disk |
| Background tasks (node) | `meshbay_node.transport.webrtc_server` | `_spawn()` — the only way to start one; a bare `ensure_future` can be collected |
| Stream handover (node) | `meshbay_node.transport.webrtc_server` | `_replace_stream` + `shutdown_tasks` — one viewer, one film, and the slot comes back when they leave |
| Download backpressure (node) | `meshbay_node.transport.webrtc_server` | `DOWNLOAD_BUFFER_HIGH` — 8 × 1 MB answered blind queues 8 MB on the channel |
| Streamed download (browser) | `static/downloads.js` + `static/sw.js` | Needs the page *controlled*, and the worker confirms it served the request |
| Leave a group (hub) | `meshbay_hub.api.groups` | `POST /v1/groups/{id}/leave` — self only; the owner is refused |
| Public group cap (hub) | `meshbay_hub.api.groups` | `_check_public_group_quota` — 10 live public groups per owner, staff exempt. **Checked at creation only, because PATCH refuses to change visibility** |
| Node presence (hub) | `meshbay_hub.api.groups` | `node_online` on `/v1/groups/mine`, read from the signaling registry — no poll, no timer |
| Chat paging (node) | `meshbay_node.chat.store` | `get_recent` / `get_before` / `has_before`. `get_messages` pages *forwards* and is not what a chat opens with |
| Liveness (MNP) | `meshbay_common.protocol` | `PING`/`PONG` on an **already-open** channel; never for discovery — a handshake costs 0.6-7 s |
| Profile page (browser) | `static/app.js` | `ProfilePage` — identity, node link, pins, account deletion. Settings keeps behaviour |
| i18n (browser) | `static/i18n.js` | `t()` lookup + `Intl.PluralRules`, region-aware resolution, localStorage lang selection |
| Translation catalogues | `static/locales/*.js` | One per language, fetched on demand. `en.js` is the source; `test_locales.py` holds the other nine to its key set |
| Admin API (hub) | `meshbay_hub.api.admin` | Phase 10.2 — user/group mgmt, audit logs, stats |
| Admin UI (browser) | `static/app.js` | Phase 10.3–10.4 — AdminPage component, 5 tabs |
| Auth dependencies | `meshbay_hub.api.deps` | `require_admin`, `require_moderator`, `get_current_user`, `require_user_scope` |
| Node auth (hub) | `meshbay_hub.api.nodes` | `POST /v1/nodes/auth` — Ed25519 challenge-response, node-scoped JWT |
| Site overlay | `site/` | Phase 10.1 — landing, about, downloads (meshbay.org-specific) |
| Notifications (hub) | `meshbay_hub.api.notifications` | Phase 10.5 — CRUD, per-user, triggered by admin/group actions |
| Version check (hub) | `meshbay_hub.api.hub` | Phase 10.10 — `GET /v1/hub/version` |
| Group self-service (hub) | `meshbay_hub.api.groups` | Phase 10b — create, join, members (GEK exchange is P2P) |
| File upload (node) | `meshbay_node.transport.webrtc_server` | Phase 10b.4 — FILE_UPLOAD MNP handler |
| GEK wrap AES (browser) | `static/crypto.js` | Phase 10b.2 — AES-256-GCM ECIES for WebCrypto |
| GEK HMAC proof (browser) | `static/crypto.js` | `hmacGEK()` — HMAC-SHA256 with DTLS channel binding |
| DTLS fp extraction (browser) | `static/transport.js` | `_extractDtlsFingerprint()` — SDP fingerprint for channel binding |
| DTLS fp extraction (node) | `meshbay_node.transport.webrtc_server` | `_extract_dtls_fingerprint()` — SDP fingerprint for channel binding |
| Ed25519 sign (browser) | `static/keyderive.js` | `signChallenge()` — admin challenge-response |
| Auth key derivation (browser) | `static/keyderive.js` | `deriveAuthKey()` — password split, hub never sees raw password |
| GEK wrap AES (Python) | `meshbay_common.crypto` | Phase 10b.2 — `wrap_gek_aes()` / `unwrap_gek_aes()` |
| IndexedDB cache (browser) | `static/app.js` | Phase 10b.5 — group index caching |
| Cross-group search (browser) | `static/app.js` | Phase 10b.6 — SearchPage, client-side |
| MSE video streaming (node) | `meshbay_node.transport.webrtc_server` | Phase 10c — ffmpeg fMP4 remux + encrypted segments |
| MSE video streaming (browser) | `static/app.js` | Phase 10c — MediaSource + SourceBuffer progressive playback |
| Video codec detection | `meshbay_node.transport.webrtc_server` | Phase 10c — `_probe_video()` ffprobe + MSE codec strings |
| Node daemon (production) | `meshbay_node.daemon` | Phase 11 — WebRTC + WS + chat + HTTP + audit all wired |
| Node config | `meshbay_node.config` | `node.toml` loader, `data_dir` for chat/audit DBs |
| Hub WS client | `meshbay_node.hub_client` | `login()` (Ed25519) + `maintain_ws()` + `send_ws()` — no auth_key on node |
| Chat store | `meshbay_node.chat.store` | SQLite per-group, `data_dir/{group_id}/chat.db` |
| Audit store | `meshbay_node.audit` | SQLite IP/action log, `data_dir/audit.db` (legal compliance) |
| Bundle store (node) | `meshbay_node.bundle_store` | SQLite P2P GEK + keypair bundles, `data_dir/bundles.db` — hub never stores crypto |
| P2P bundle exchange (MNP) | `meshbay_common.protocol` | GEK + keypair bundle STORE/FETCH/RESP message types |
| Bundle via DataChannel | `static/transport.js` | GEK + keypair bundle fetch during handshake, store after connect |
| Key persistence (browser) | `static/app.js` | `_bundleKey` in IndexedDB, `_sessionKeys` in sessionStorage |
| pkX from private key | `static/transport.js` | `_pkFromSk()` — JWK export to derive X25519 public key |
| Group delete (hub) | `meshbay_hub.api.groups` | `DELETE /v1/groups/{group_id}` — admin only |
| JWT scope enforcement | `meshbay_hub.api.deps` | `require_user_scope` — blocks node-scoped tokens from mutations |
| Node local admin UI | `meshbay_node.ui.app` | Dashboard, peers, groups, audit log (localhost:18000) |
| Demo scripts | — | `QE/demo-v1/*.py`, `QE/demo-v2/*.py`, `QE/demo-v3/*.py` (not versioned) |
| Video flow control (browser) | `static/app.js` | `pump()` — the only place credit is granted. Read-ahead bounded by `BUFFER_AHEAD_S` of film, `STREAM_WINDOW` segments in flight, driven by a clock and by playback, never by arriving data |
| Player under test | `tests/harness/mse_harness.mjs` | Runs the real `pump`/`flushQueue`/`evictBehind` against a fake SourceBuffer with a ceiling. Do not write a second model of them |
| Asset versioning (hub) | `meshbay_hub.api.webapp` | `_asset_version()` — content hash; whole module graph served under `/a/<hash>/` so a cache cannot mix two builds |
| Stream capacity (node) | `meshbay_node.config` | `[node] max_concurrent_streams` (default 8) — a slot is held for the length of a film, so it counts simultaneous viewers |
| Stream diagnosis (node) | `webrtc_server.py` | `client_diag` at DEBUG — the player's own view (`ready`, `quota`, `ranges`, `err`) in the node's log. The only window into a phone |
| Stream probe (no browser) | — | `QE/deploy/stream_probe.py` — pulls a real film over real MNP. Answers "is it the node or the browser" in one run (not versioned) |

## meshbay.org server (état cible)

- OS: Ubuntu 26.04 LTS, Python 3.14.4
- SSH: `ssh cbesson@meshbay.org`
- Caddy : reverse proxy HTTPS sur 80/443
- UFW rules: **22/tcp, 80/tcp, 443/tcp uniquement**
- Services légitimes : `meshbay-hub.service`, Caddy, PostgreSQL (local)
- Inventaire détaillé : `QE/server-state/meshbay.org.md`
- Deploy hub : voir `QE/server-state/meshbay.org.md`

## new rules, from now
Documents and demo/comments are written in english unless requested in french.