path: root/docs/USERGUIDE.md

# MeshBay User Guide

This guide covers MeshBay in depth — architecture, configuration, security, and the full API. Read the [Quickstart](QUICKSTART.md) first if you have not set up a node yet.

---

## Table of Contents

1. [Architecture overview](#1-architecture-overview)
2. [Account management](#2-account-management)
3. [Groups](#3-groups)
4. [Setting up a node](#4-setting-up-a-node)
5. [Sharing files](#5-sharing-files)
6. [Accessing files](#6-accessing-files)
7. [Video streaming](#7-video-streaming)
8. [Security model](#8-security-model)
9. [Moderation and legal](#9-moderation-and-legal)
10. [Troubleshooting](#10-troubleshooting)
11. [API reference](#11-api-reference)

---

## 1. Architecture Overview

MeshBay has three components. Understanding which role each plays avoids a lot of confusion.

```
┌─────────────────────────────────────────────┐
│  Mesh Hub  (meshbay.org)                    │
│                                             │
│  • User accounts and public keys            │
│  • Group registry (name, membership)        │
│  • Encrypted GEK bundles (opaque blobs)     │
│  • JWT issuance and verification key        │
│  • Connection logs (legal compliance)       │
│  • No file content, no indexes, no GEKs    │
└──────────────┬──────────────────────────────┘
               │ HTTPS  (identity + routing only)
               │
    ┌──────────┴──────────┐
    │                     │
┌───▼────────┐     ┌──────▼───────┐
│ Mesh Node  │     │ Mesh Client  │
│            │     │              │
│ Your files │ MNP │ Browser or   │
│ Your keys  │◄───►│ Android app  │
│ TCP+TLS    │     │              │
└────────────┘     └──────────────┘
```

**Mesh Hub** — a lightweight registrar. Its job is to vouch for identities, track group membership, and store encrypted GEK bundles. After login, clients talk directly to nodes. The hub is never in the data path for file transfers.

**Mesh Node** — the program you run on your server or home machine. It watches a directory, maintains a group index, handles connections from clients, encrypts files at read time, and holds your private keys. You are the legal host of everything in your shared directory.

**Mesh Client** — a web browser or Android app. It authenticates with the hub, fetches the encrypted GEK bundle, and connects directly to nodes for file browsing and download.

**Protocol versioning:** MNP (Mesh Node Protocol) is currently at v0.1 over TCP+TLS 1.3. QUIC transport is planned for v2 with no protocol changes. Every wire message carries a `v` field; N-2 minor version backward compatibility is guaranteed.

---

## 2. Account Management

### Register

Registration creates an account and nothing else: a username, an email, and a value derived from your passphrase that lets the hub check it without ever seeing it.

**No keys are generated here.** An identity keypair belongs to a *node*, not to the hub: one is created the first time you join a given node, encrypted under your passphrase, and left with that node. So an operator who takes their own disk holds a key that is worthless on anyone else's, and the hub has no key directory to publish — which is what finding H3 read.

**Deux modes de génération de clés :**

**Mode CLI / native node** (`setup_demo.py`, `meshbay-node`) :
Les clés sont *dérivées* de votre username + password via Argon2id — pas besoin de
fichier de clés séparé. Même identifiants → mêmes clés sur n'importe quelle machine.
Implémenté dans `meshbay_common.keyderive.derive_keys_from_password()`.

```python
from meshbay_common.keyderive import derive_keys_from_password
sk_ed, sk_x = derive_keys_from_password("alice", "MonMotDePasse!")
```

**Mode navigateur** (interface web) :
Le navigateur génère des clés aléatoires via WebCrypto, les chiffre avec une clé
dérivée du mot de passe (PBKDF2-SHA512), et envoie le bundle chiffré au hub.
À la prochaine connexion, le hub retourne le bundle et le navigateur le déchiffre
localement. Le hub stocke le bundle mais ne peut pas le lire.
Implémenté dans `static/keyderive.js`.

```
POST /v1/users/register
{
  "username": "string",
  "email":    "string",
  "auth_key": "base64 (PBKDF2-SHA512 of your passphrase — the hub never sees the passphrase itself)"
}
→ 201 {"user_id": "uuid"}
→ 409 if username is taken
```
POST /v1/users/login
{"username": "yourname", "password": "yourpassword"}
→ {
    "access_token":   "JWT (Ed25519, 4 hour validity)",
    "refresh_token":  "opaque 256-bit token (30 days)",
    "token_type":     "bearer",
    "expires_in":     14400,
  }
```

Le trousseau ne vient pas d'ici : chaque nœud conserve celui qui lui est propre,
chiffré par votre phrase de passe, et un nouveau navigateur le récupère auprès du
nœud auquel il se connecte.

```bash
curl -s -X POST https://meshbay.org/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice_test","password":"AliceTest2026!"}'
```

### Token refresh

Access tokens are valid for 4 hours. **The web app does this for itself** — it
renews ten minutes before expiry, on returning to the tab, and on any 401, then
replays the request. Nobody should meet an expired token in the browser; what
follows is for other clients.

The endpoint **rotates**: it revokes the refresh token you present and returns a
new one, so store the replacement. Presenting a revoked token is treated as
theft and revokes the whole family, which is a full sign-out.

```
POST /v1/users/token/refresh
{"refresh_token": "your-refresh-token"}
→ {"access_token": "new JWT", "refresh_token": "USE THIS NEXT TIME",
   "token_type": "bearer", "expires_in": 14400}
```

```bash
curl -s -X POST https://meshbay.org/v1/users/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"YOUR_REFRESH_TOKEN"}'
```

Refresh tokens are valid for 30 days — that is the session — and can be
invalidated by the hub at once on account compromise. Revoking one means the
next renewal fails; an access token already issued keeps working for up to 4
hours. That window is not the whole story: the hub reloads the account on every
request and refuses a suspended one immediately, and it pushes signed
revocations to nodes, so suspending an account or revoking a membership takes
effect at once regardless of the token's remaining life.

### Access token structure

The JWT payload contains:

| Claim | Value |
|---|---|
| `iss` | Hub ID (`meshbay.org`) |
| `sub` | Your `user_id` (UUID4) |
| `hub_id` | `meshbay.org` |
| `jti` | UUID4 — unique per token, enables revocation, prevents replay |
| `groups` | The `group_id`s you are a member of, for node-side authorization |
| `scope` | `user` for a browser, `node` for a daemon |
| `iat` | Issued at (Unix timestamp) |
| `exp` | Expires at (Unix timestamp, 4 hours from issue — `[jwt] access_token_ttl`) |

The token carries **no public key of yours**. It used to carry `pk_user`, and a node
recorded that key as the uploader of a file — which meant the party issuing tokens
decided who was allowed to delete it. The hub certifies *accounts*; keys are generated
on each node and pinned there (§4).

Nodes verify this JWT locally using the hub's cached Ed25519 public key. No hub roundtrip is needed — verified at 884µs in testing. This means your files remain accessible even if the hub is temporarily unreachable.

### Deleting your account

**Settings → Delete account.** You re-enter your passphrase: a live session may be a
borrowed laptop or a tab left open, and this cannot be undone. A hub administrator can
also delete an account, from Administration → Users.

What deletion does:

- Releases the username — someone else may register it afterwards
- Clears the email and password hash, and drops the node linking key
- Removes group memberships, notifications and refresh tokens
- Refuses any access token still within its validity, immediately

What deletion does **not** do:

- **It does not touch anything on a node.** Your files stay where you uploaded them, and
  so do the identity pinned in the node's roster and the keypair bundle it holds for you.
  Nodes are other people's machines; the hub cannot command them. To be removed there,
  ask the operator — `meshbay-node member unpin <user>` and deleting your files are
  their commands to run (§4).
- **It does not erase the connection log.** IP records are kept for their legal retention
  period and stay attributable: the username is copied onto those rows as the account is
  deleted, so the log still says *who*, and does not answer `deleted-3f9a1c` for exactly
  the records anyone would be asking about. Releasing the name for re-registration and
  keeping it in the log are separate things.

Deletion is refused while you still own a group. Hand the group over or delete it first —
otherwise its members would be stranded. The error names the groups blocking you.

```
DELETE /v1/users/me
Authorization: Bearer <access_token>
{"auth_key": "<derived from your passphrase, as at login>"}
→ 200 {"status": "deleted", "username": "alice_test"}
→ 403 {"detail": "Passphrase does not match"}
→ 409 {"detail": "This account still owns groups: ..."}
```

Node registrations are removed as well, so a deleted operator's nodes stop being
announced. The daemons keep running and keep their data — again, the hub does not
command them.

---

## 3. Groups

Groups are the primary unit of organization. Every file on a node belongs to a group.

### Create a group

```bash
TOKEN="your-access-token"

curl -s -X POST https://meshbay.org/v1/groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "my-group"}'
```

Response:
```json
{"group_id": "uuid", "name": "my-group"}
```

Save `group_id` — you will need it in your `node.toml` and when adding members.

### The description

Set it at creation with `"description"`, or later from the group's page — the owner
sees an **Edit description** link under the name. Members see it on their home page
and, for public groups, in Explore.

```
PATCH /v1/groups/{group_id}
Authorization: Bearer <access_token>   (the group's owner)
{"description": "host grenoble"}
→ 200 {"group_id": "...", "description": "host grenoble"}
```

An empty string clears it; anything past 512 characters is trimmed rather than
refused. The description is all this endpoint changes: the name, the visibility and
the join policy are the terms members joined on, and a private group that could
quietly become public is not the group they agreed to be in. Changing those needs a
decision about who gets told, so it is not a field on a form.

### Public vs. private groups

| | Public | Private |
|---|---|---|
| File index | Plaintext + Ed25519 signed | GEK-encrypted, members only |
| Content | TLS transport only (no application-layer encryption) | GEK-encrypted per chunk |
| Join | Open / approval-gated | By invitation only |
| GEK | Not applicable | Required |

For private groups the node holds a Group Encryption Key (GEK) — a random 32-byte key that is never sent over the wire in cleartext. Each member receives a copy wrapped for their own X25519 public key (ECIES: X25519 + HKDF + AEAD).

**The node does the wrapping, and it never asks the hub for anybody's key.** That matters: the hub is the account directory, so a hub that answered a key lookup with its own key would be handed the group key by an honest member following the protocol exactly (finding H3). Instead the recipient presents their own public keys over the authenticated P2P channel, signed by their identity key, and the node wraps for what it just verified.

### Add a member to a private group

The node operator issues a one-time code, from the server or from their browser:

```bash
# On the node, over SSH — no browser needed
meshbay-node member invite bob

INVITATION CODE  R3H8-TB6V
valid until      2026-08-21T12:00:00+00:00
```

Send the code to Bob however you already talk to him — it never passes through the hub, which is what stops the hub from claiming to be Bob. He enters it the first time he opens the group, and the node then wraps the group key for the key he proved he holds.

After that first time the pin is his credential: he is recognised on every later connection, and asked for nothing. You do not need to be online when he joins.

| | |
|---|---|
| Code lifetime | 7 days (`[node] invite_ttl_hours`) |
| Reuse | Single use; re-inviting supersedes the previous code |
| If it expires | Issue another one — nothing else is affected |
| Wrong code, repeatedly | Bounded per connection and node-wide, and logged in the node's audit log |

The same operation is available in the web app: the group's **Members** tab, if your browser is paired with the node (`meshbay-node operator pair`).

### Removing a member

```bash
meshbay-node member revoke bob
meshbay-node gek-init            # rotate: Bob still holds the old key
```

Revoking stops the node serving Bob the key from his next connection onward — there is no stored bundle left behind that could outlive the decision. It does **not** take back the key he already has, which is why the second command exists.

### What revocation does and does not do

Rotating the GEK (`meshbay-node gek-init`) makes the node encrypt new content with a new key, which every remaining member picks up automatically on their next connection — nothing has to be re-uploaded or re-wrapped by hand.

A former member can still decrypt content they already received: there is no retroactive re-encryption, and there is no way to reach into someone's disk. Revocation controls what happens next, not what already happened.

### Notifications

The bell in the top bar counts what you have not read. Clicking an entry takes you to
what it is about and dismisses it.

- **Chat is one entry per group, not one per message.** A conversation that has been busy
  all afternoon is a single line whose date moves to the last thing said and which turns
  unread again each time. Opening the group clears it.
- **You are never notified of your own messages.** The node names the author when it
  tells the hub a message was posted, and the hub skips them.
- **An invitation disappears once you have joined**, i.e. after you enter the pairing
  code — not when you first look at it.
- **Muting a group works from anywhere.** The setting lives on the hub with your
  membership, so a muted group creates no notification at all rather than hiding one
  after the fact. It follows you to another browser. (It used to be a checkbox in the
  browser's local storage that nothing read, so it did nothing.)
- **Clear all** empties the list in one action.

```
GET    /v1/notifications              → {"notifications": [{id, kind, group_id, title, link, read, created_at}], "unread": 3}
DELETE /v1/notifications/{id}         → dismiss one — the row is deleted
POST   /v1/notifications/{id}/read    → the same thing, under the name older clients use
POST   /v1/notifications/read-all     → dismiss every one
DELETE /v1/notifications              → delete them all
POST   /v1/groups/{group_id}/mute     {"muted": true}
```

`GET /v1/groups/mine` reports `muted` for each group, so the browser shows the checkbox
in the state the hub actually holds.

---

## 4. Setting up a Node

### Configuration file

Full `~/.config/meshbay/node.toml` reference:

```toml
[hub]
url = "https://meshbay.org"

[auth]
username = "yourname"
password = "YourPassword123!"

# Each group this node hosts gets its own [[groups]] block
[[groups]]
group_id   = "uuid-of-your-group"
shared_dir = "/srv/meshbay/my-group"

[[groups]]
group_id   = "uuid-of-second-group"
shared_dir = "/srv/meshbay/second-group"

[node]
# MNP listener port (must be internet-reachable)
listen_port  = 19001

# Local web UI port (loopback only, not exposed externally)
ui_port      = 18000

# Announce this address to the hub (auto-detected via STUN if not set)
# endpoint_hint = "203.0.113.42:19001"

[keystore]
# "secure"    — password prompt at each startup
# "lazy_file" — password read from ~/.config/meshbay/unlock.key (chmod 600)
# "service"   — password read from MESHBAY_UNLOCK_KEY env var
unlock_mode = "secure"
path        = "~/.config/meshbay/keystore.enc"

[crypto]
# Argon2id parameters for keystore password derivation.
# Run `meshbay-node --calibrate-argon2` to tune for your hardware.
# Target: ~500ms on your machine.
argon2_iterations   = 4
argon2_memory_cost  = 262144  # 256 MB
argon2_parallelism  = 1
```

### Hosting another of your groups

A node can host several groups, each with its own directory and its own key.
Create the group in the web app first, then, on the node:

```bash
meshbay-node group add grenet --dir ~/grenet-share
# grenet (480d553f) added to /home/cbesson/.config/meshbay/node.toml
#   shared_dir   /home/cbesson/grenet-share

# restart the daemon, then:
meshbay-node gek-init --group grenet
```

`group add` looks the name up among your groups on the hub, appends a
`[[groups]]` block to your `node.toml` — comments and all, it is appended, not
rewritten — and creates the directory. The daemon reads its config at startup, so
it needs a restart before the group exists for it; `gek-init` then generates that
group's key.

Three things follow from the design, and are worth being explicit about:

- **Each group's key is its own.** Members of one group cannot read another's
  files, and admitting someone to one says nothing about the other. That is why
  `gek-init` is per group.
- **Pairing is not.** `meshbay-node operator pair` pairs a *browser* with the
  *node*: one paired browser can invite to, and delete files in, every group the
  node hosts. It takes no `--group`.
- **Members are per group.** `meshbay-node member invite alice --group grenet`
  admits alice to that group only. The roster keeps one row per group.

`meshbay-node status` prints what the node hosts, with each directory — the
quickest way to see whether a group made in the browser is attached here yet.

### Environment variables (alternative to node.toml)

| Variable | Equivalent config |
|---|---|
| `MESHBAY_HUB_URL` | `[hub] url` |
| `MESHBAY_USERNAME` | `[auth] username` |
| `MESHBAY_PASSWORD` | `[auth] password` |
| `MESHBAY_UNLOCK_KEY` | keystore unlock key (for `service` mode) |
| `MESHBAY_LISTEN_PORT` | `[node] listen_port` |

### Keystore unlock modes

The keystore is an Argon2id-derived AES-256-GCM encrypted file holding your Ed25519 and X25519 private keys plus GEK copies.

**secure (default):** prompts for a password at startup. Suitable for interactive use. The password is not stored anywhere.

**lazy_file:** reads the password from `~/.config/meshbay/unlock.key` (must be `chmod 600`). Use on a physically secure home server where you want unattended restarts.

```bash
echo -n "YourKeystorePassword" > ~/.config/meshbay/unlock.key
chmod 600 ~/.config/meshbay/unlock.key
```

**service:** reads the unlock key from the `MESHBAY_UNLOCK_KEY` environment variable. Standard practice for systemd deployments:

```ini
# /etc/systemd/system/meshbay-node.service
[Unit]
Description=MeshBay Node
After=network.target

[Service]
User=meshbay
EnvironmentFile=/etc/meshbay/unlock.env   # chmod 600, owned by meshbay
ExecStart=/usr/bin/meshbay-node --config /etc/meshbay/node.toml
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

```bash
# /etc/meshbay/unlock.env  (chmod 600, owned by meshbay user)
MESHBAY_UNLOCK_KEY=YourKeystorePassword
```

### Argon2id calibration

The keystore password derivation is intentionally slow. Tune it to your hardware:

```bash
meshbay-node --calibrate-argon2
```

This prints the derivation time for several parameter combinations. Choose the set that gives ~500ms. The default (iterations=4, memory=256MB) is calibrated for a modern home server.

### Hardware sizing (upload bandwidth is the constraint)

| Scenario | Simultaneous users | Upload needed | RAM |
|---|---|---|---|
| Files + chat, no streaming | 10 | 20–50 Mbps | 512 MB |
| 1080p streaming, 5–6 streams | 10 | 50–80 Mbps | 1 GB |
| Mixed, light streaming | 50 | 200–300 Mbps | 2 GB |
| Heavy streaming | 50 | 400 Mbps | 2–4 GB |

A standard home fiber line (100–500 Mbps symmetric) handles 10–30 concurrent users. Beyond that, a dedicated server is needed.

---

## 5. Sharing Files

### How indexing works

The node watches `shared_dir` for file changes using filesystem events (`watchdog` library). When a file is added, modified, or removed:

1. The node computes `blake3(file)` as the file identifier
2. It builds or updates a Mesh Group Index entry for that file
3. The index entry is serialized as msgpack, compressed with zstd, then encrypted with the GEK (for private groups) or signed with the node's Ed25519 key (for public groups)
4. Connected members receive an index delta push; new connections receive the full index

### Index entry structure

```python
{
  "version":    1,
  "id":         "<blake3_hash_hex>",   # file identity and chunk key input
  "name":       "filename.mkv",
  "path":       "Movies/2024/",        # relative path within shared_dir
  "size":       4294967296,            # bytes
  "type":       "video",               # video | audio | image | document | archive | other
  "duration":   7245,                  # seconds (media files only)
  "thumb_hash": "<blake3>",            # thumbnail, also GEK-encrypted
  "added_at":   1720000000             # Unix timestamp
}
```

### Supported file types

The node detects type by file extension and MIME sniffing:

| Type | Extensions |
|---|---|
| `video` | mp4, mkv, avi, mov, webm |
| `audio` | mp3, flac, ogg, opus, m4a |
| `image` | jpg, jpeg, png, gif, webp, avif |
| `document` | pdf, txt, md, epub, doc, docx, odt |
| `archive` | zip, tar, gz, bz2, xz, 7z |
| `other` | everything else |

### Where uploaded files land

Everything a member sends arrives in **`shared_dir/uploads/`** — both files uploaded from
the Files panel and attachments sent in the chat. One visible directory, so an operator can
look at what was sent, move it, or empty it without hunting through the tree.

- Filenames are checked against a conservative allowlist and nothing is ever overwritten:
  a colliding name gets a suffix, and the sender is told the name it was stored under.
- Chat thumbnails are scaled by the browser from the file itself. The node writes no
  derived images, so nothing accumulates beside your files.
- Uploads are attributed to the identity the node pinned for that member, and that is what
  decides who may delete the file later — not anything the hub says.

### Selecting files, and where transfers live

The Files panel has a **Select** button. Turning it on puts a checkbox on every
row — files and folders — and the **⋮ Actions** button next to it acts on what is
ticked: download, play, view, download folders as a zip, delete. There is no
per-row menu: several transfers at once is the normal case, and starting them one
context menu at a time was the thing that made it awkward.

Selection is remembered as you walk into folders, so you can tick something in
one and something else in another before choosing an action.

**Where downloads are written** is a setting, under Settings → Downloads:

- **Save automatically** (the default) writes into a folder you pick once, with
  no dialog. Downloading twenty files puts twenty files there. A name already in
  use gets a suffix — `clip (2).mp4` — rather than replacing what is there.
- **Ask every time** opens a Save As dialog per file, which is right for one file
  and wrong for a selection of twenty.

With no folder chosen, automatic still does not put a dialog in your way, and it
still does not hold the file in memory: a service worker hands the browser a
stream, which it writes to its own download folder as the bytes arrive. That is
how this works in Firefox and Safari, which have no way to open a file for writing
from a page. If even that is unavailable, a download under 512 MB is collected in
memory and handed over; a larger one asks where to put it, because a tab does not
survive a multi-gigabyte blob.

**What has been exercised**, as of 2026-08-15, so the next person knows which of
this is measured and which is designed:

| Path | Browser | State |
|---|---|---|
| Streamed into a granted folder | Chrome | works |
| Streamed by the service worker | Firefox | works — 180 MB, written to disk |
| Collected in memory (no folder, no worker) | any | works, bounded at 512 MB |
| Save As for a download over 512 MB | Chrome | works |
| Multi-gigabyte download, any path | — | designed for, not yet measured |

The 180 MB run is the one that matters most, because the service worker is the
only way Firefox writes a download to disk rather than building it in a tab. It
has not been tried at the scale it exists for.

A finished download offers **Open** in the transfers widget when it went into a
folder you granted: the file is handed to a new tab and the browser decides what
to do with it. That is the whole of what a web page can do here — it cannot start
a desktop application, and it cannot show you a file manager. No browser offers an
API for either, deliberately.

A web page cannot be given a filesystem path, and cannot read one either: there
is no `~/Downloads` to configure, on any operating system, and nothing changes
here on Windows for the same reason. What a browser grants is access to a folder
the user picked in a dialog, and MeshBay only ever writes inside it. That grant
is remembered, but the browser may ask you to confirm it once per session.

Firefox and Safari have no File System Access API, so no folder can be granted:
downloads go to the browser's own download folder, and Settings says so instead
of offering a choice that would do nothing.

**Transfers run outside the page.** They are listed in the widget next to the
bell, with a progress bar, the current rate, and a cancel button each:

- Leaving the group, or the group page, does not stop them. The connection stays
  open until the last transfer using it is finished.
- **Signing out cancels them all** — they are moving data on a token that is about
  to stop being yours.
- Cancelling stops the work, not just the display; a partly written file is left
  where you told the browser to put it.
- Rates are measured over the last few seconds, so a stalled transfer reads as
  stalled rather than reporting the average it once managed.

### Downloading a folder as a zip

Any member can take a whole folder: **⋮ → Download as zip** on the folder's row.
The archive is built in the browser as the files arrive and written straight to
disk, so a 40 GB folder costs 40 GB of disk and a few megabytes of memory.

- Nothing is compressed. Group content is video, images and archives — already
  compressed — so deflating would spend CPU on every byte to save nothing, in the
  same thread that is decrypting.
- The archive opens as the folder you asked for: a zip of `Holidays/2026` unpacks
  as `2026/…`, not as a chain of empty parents.
- Files over 4 GiB, and archives over 4 GiB, use zip64. Anything current reads
  them; a tool from before 2003 may not.
- **Firefox and Safari cannot write a download straight to disk** (no File System
  Access API). There, the archive has to be assembled in memory first, and the
  browser says so, with the size, before starting. Use Chrome or Edge for a large
  one.

### Removing a member

The group's owner can remove someone from the Members tab. It does two things, in
the order that fails safe:

1. **The node stops serving them the group key** — an operator-signed request, so
   it works only from a paired browser (§3). This is the half that matters.
2. **The hub drops their membership**, which is what stops them reaching the node
   through signaling at all.

What it does **not** do:

- It does not delete their account. Their other groups, their files and their
  identity are untouched — one group's owner cannot erase someone from the hub.
- It does not make the node forget them. The pinned key stays, so they can be
  admitted again without a new pairing code; `meshbay-node member unpin` forgets.
- It does not take back the key they already hold. Anyone who has connected has
  unwrapped the current GEK, and no protocol reaches into their browser to remove
  it. Rotate it with `meshbay-node gek-init --group <name>` if that matters —
  members still in the group pick the new one up on their next connection.

Removal is per group: on a node hosting several, someone removed from one keeps
the others.

### Deleting a directory

**⋮ → Delete folder**, for the node operator, from a paired browser (§3). The
directory must be **empty** — nothing here is recursive, and a folder with
anything in it is refused before a signature is even asked for. Delete the files
first, where you can see what you are losing.

Like every privileged action on a node, it is signed with the key the node pinned
for that browser and refused otherwise: hub membership, or an admin role on the
hub, grants nothing here.

### Creating a directory

Any active member can create a directory from the Files panel (**New folder**). It is
created relative to the folder you are looking at, under `shared_dir`, and the same name
rules apply. Paths that try to leave the shared root are refused.

### Files are stored in plaintext on disk

The node holds your files in plaintext. Encryption happens at read time — the node encrypts each 1 MB chunk using a per-chunk key derived from the GEK before sending it over the wire. This means:

- Disk-level encryption (LUKS, etc.) is your responsibility if you need at-rest protection
- Backups of the shared directory are plaintext
- Node compromise exposes all files in plaintext

---

## 6. Accessing Files

**There is no HTTP file API.** Files are requested over MNP — the node's authenticated
message channel, carried by WebRTC DataChannel or QUIC — and nothing on the node answers
an unauthenticated request. The `GET /index`, `GET /file/{id}` and `GET /stream/...`
endpoints documented before 0.2.0 were removed (findings C1 and C6): they served the index
and file bytes to anyone holding a token, outside the handshake that decides what a peer
is allowed to see. Port 19001 is the MNP listener, not a web server.

The node's only HTTP surface is its admin UI, bound to loopback and requiring a token
(§4). It is for the operator, on the machine, over SSH.

### Browse the index

After the handshake, ask for the index:

```
→ {"type": "index_sync", "v": "0.1"}
← {"type": "index_sync", "entries": [{"id": "<blake3 hex>", "name": "...", "size": 1234,
                                      "type": "video", "path": "uploads/"}, ...]}
```

For a private group the index itself is encrypted with the GEK, so a peer that never
proved possession of the key is served nothing to read.

### Download a file, chunk by chunk

```
→ {"type": "file_req", "v": "0.1", "file_id": "<blake3 hex>", "chunk_index": 0}
← {"type": "file_chunk", "file_id": ..., "chunk_index": 0,
   "nonce": <bytes>, "ct": <bytes>, "plaintext_size": 1048576}
```

Chunks are 1 MB. Chunk 0 is the first megabyte; for a 5 MB file, request 0–4.

**Per-chunk key derivation** — each chunk has an independent key derived from the GEK and
the chunk's position, so a leaked chunk key opens exactly one chunk of one file, and a
player can seek without decrypting from the start:

```python
chunk_key = HKDF(
    algorithm=hashes.SHA256(), length=32, salt=None,
    info=b"file:" + file_hash_bytes + b":chunk:" + chunk_index.to_bytes(4, "big"),
).derive(gek)

plaintext = ChaCha20Poly1305(chunk_key).decrypt(nonce, ciphertext, None)
```

The browser client derives the same key the same way but uses **AES-GCM**: WebCrypto has
no ChaCha20-Poly1305. The node picks the cipher from what the peer negotiated at
handshake; the key schedule above is identical in both.

### Identifying the node

The node's `pk_node` (Ed25519) comes from the hub — `GET /v1/nodes/{node_id}` — and the
client checks the handshake signature against it. A node that cannot sign the transcript
with the key the hub published for it is refused, so hub signaling can introduce you to a
node but cannot substitute one.

---

## 7. Video Streaming

Video is streamed over the same MNP channel and played through Media Source Extensions.
The node remuxes to fragmented MP4 on the fly — the container changes, the video and audio
streams are copied untouched — and encrypts each segment exactly like a file chunk, so a
standard `<video src=...>` cannot play it: the segments are ciphertext until the client
decrypts them.

```
→ {"type": "stream_req", "v": "0.1", "file_id": "<blake3 hex>"}
← {"type": "stream_init", "codec": "video/mp4; codecs=\"avc1.640028,mp4a.40.2\"",
   "duration": 5124.3}
← {"type": "stream_data", "segment_index": 0, "nonce": <bytes>, "ct": <bytes>}
← ... one message per segment ...
← {"type": "stream_end"}
```

Each `stream_data` segment is decrypted with the chunk key for its `segment_index` and
appended to a `SourceBuffer`. The web client does this in `static/app.js` (`VideoPlayer`);
ffmpeg must be installed on the node for transcoding.

**Flow control.** The client says how many segments it can take — `stream_req`
carries a credit count — and the node sends no more than that until `stream_more`
grants more. Segments are 256 KB.

What governs the credit is the playhead, not the append: the client grants more
only while it holds less than **90 seconds of film ahead of where you are
watching**. That bound is the whole point. ffmpeg runs with `-c copy` — a remux,
not a re-encode — so the bytes on the wire are the file's own, and a 500 MB film
really does try to put 500 MB somewhere. Granting credit per append instead meant
taking it as fast as the network could deliver, which filled the browser's
SourceBuffer ceiling (a few hundred megabytes) in the first minute and wedged the
player at "buffering" for good. Buffering by time costs the same for a two-hour
film as for a two-minute clip — around 20 MB at a typical bitrate.

A client that sends no credit count gets the old unpaced behaviour.

**A viewer that is well ahead still says so.** Holding credit back means granting
nothing for minutes at a time, which the node would otherwise read as a closed
tab. The client sends `stream_more` with `n = 0` every 20 seconds: it grants no
room but proves someone is there. The node ends a stream on silence, not on
stinginess.

**Closing the viewer stops the stream.** `stream_stop` tells the node nobody is
watching, so ffmpeg is killed and its slot released at once. Before this, leaving
a video held one for the two-minute credit timeout, which is what made the next
video answer "server busy".

**How many people may watch at once.** A slot is now held for as long as someone
is watching, so it is a limit on simultaneous viewers rather than on bursts. The
default is 8. The operator sets it in `node.toml`:

```toml
[node]
max_concurrent_streams = 8
```

or with `MESHBAY_MAX_CONCURRENT_STREAMS` in the environment. One ffmpeg runs per
viewer, remuxing rather than encoding — little CPU, roughly 50 MB of memory, idle
most of the film — so raise it on a machine with memory to spare and lower it on
a Pi. Past the limit a viewer is told the server is busy. Zero, a negative number
or a non-number is refused with a warning naming the setting, because a limit of
zero is a node where no video ever plays and nothing says why.

**The player drops what has been watched.** A SourceBuffer is not a file: browsers
cap it and refuse the append that goes past, so anything more than a minute behind
the playhead is evicted. A segment refused for want of room is retried rather than
dropped — dropping it leaves a hole in the middle of the film and no error
anywhere. The retry is driven by a timer and by playback progress, never by the
arrival of the next segment: an append refused for want of room produces no
`updateend` and so grants no credit, and a pipeline whose only wakeup is the
segment it is waiting for cannot restart itself.

---

## 8. Security Model

Understanding what the hub knows — and does not know — is essential for evaluating MeshBay's threat model.

### Cipher choices — symmetric, not asymmetric

Clarification terminology : Ed25519 et X25519 sont des algorithmes **asymétriques** (paire clé publique/privée). Ils servent à la signature et à l'échange de clés. Les ciphers de chiffrement de contenu sont eux **symétriques** (une seule clé partagée, la GEK) :

| Cipher | Usage | Où |
|---|---|---|
| **ChaCha20-Poly1305** | Chiffrement contenu (MNP) | Node → client natif (Python, Android) |
| **AES-256-GCM** | Chiffrement contenu (navigateur) | Variante pour les groupes accessibles depuis un browser (WebCrypto ne supporte pas ChaCha20) |

Les deux sont des AEAD 256 bits avec authentification intégrée. ChaCha20 est le cipher **principal** — AES-GCM est une variante optionnelle pour la compat navigateur, pas un remplacement. Un groupe ne peut pas mélanger les deux : un groupe "browser-accessible" utilise AES-GCM pour tous ses membres.

### What the hub stores

| Data | Stored as |
|---|---|
| Username, email, optional phone | Encrypted at rest |
| Password | Argon2id hash (never cleartext) |
| Ed25519 and X25519 public keys | Plaintext (they are public) |
| GEK bundles (private groups) | Opaque ciphertext — hub cannot decrypt |
| Connection logs | IP + timestamp, retained ≥1 year (legal) |
| Node endpoint hints | Ephemeral (signaling only, not persisted) |

### What the hub never stores

- File content or any file metadata
- Private group indexes
- Message content
- The GEK in cleartext
- Your private keys

### GEK wrapping — why the hub cannot decrypt your files

When Alice adds Bob to a private group, she wraps the GEK with Bob's X25519 public key using an ECIES-like construction:

```
sk_eph, pk_eph  ← X25519.generate()             fresh ephemeral keypair per bundle
shared          ← X25519(sk_eph, pk_bob)
wrap_key        ← HKDF(shared, salt=pk_eph, info="meshbay:gek_wrap:v1")
bundle          ← ChaCha20-Poly1305(wrap_key).encrypt(nonce, GEK, aad=pk_bob)
```

The hub receives `{pk_eph, nonce, bundle}` and stores it opaquely. To decrypt it, an attacker would need `sk_bob` (Bob's X25519 private key), which never leaves Bob's device. The AAD (`pk_bob`) also binds the bundle to its intended recipient — a bundle cannot be repurposed for a different member.

Each call to `wrap_gek` uses a fresh `sk_eph`, so the same GEK wrapped for the same member twice produces different ciphertext. The hub sees only different random-looking blobs.

Wrap and unwrap operations each take ~0.5–1.2ms (measured in testing).

### Forward secrecy

Two layers:

1. **Per-connection session keys:** each MNP connection performs X25519 ECDH + HKDF to derive ephemeral session keys independent of the GEK. Compromise of the GEK does not expose historical session traffic.

2. **Per-chunk keys:** each 1 MB chunk uses a distinct key derived from the GEK + file hash + chunk index. Compromise of one chunk key does not compromise other chunks.

### JWT security properties

- `jti` (UUID4) is mandatory in every token — prevents replay (Ed25519 signing is deterministic; without `jti`, two tokens issued in the same second are byte-for-byte identical) and enables individual revocation
- Nodes verify JWTs offline using the hub's cached public key — no hub roundtrip, no hub downtime dependency
- Revocation: hub invalidates refresh token → next access token renewal fails → node access expires within the access token's life. For immediate revocation: hub adds `jti` to a denylist that nodes periodically fetch

### What node compromise exposes

If an attacker gains access to your node:
- All files in `shared_dir` (stored in plaintext)
- The keystore file (protected by Argon2id-derived AES-256-GCM; requires the keystore password to open)
- The GEK copies in the keystore (if the keystore is unlocked)

If the keystore password is not stored on the node (`unlock_mode = "secure"`), a node compromise does not immediately expose the GEK or private keys — the attacker gets the encrypted keystore and must break Argon2id. At the production parameters (iterations=4, memory=256MB, target=500ms), this is designed to limit offline attacks to a tractable rate.

---

### Where a node is, in the administration panel

The **Nodes** tab lists every registered node with two addresses, and the
difference between them matters:

- **Seen from** is the address the node's announcement arrived from. That request
  carries an Ed25519 signature over a fresh timestamp made with the node key, so
  the address belongs to whoever holds that key. It is IPv4 or IPv6, whichever
  the node connected over, and it is the one to answer a question with.
- **Announced hint** is what the node believes its own address to be, discovered
  through a STUN server and sent to us. It is useful for reaching the node
  directly and it is a claim, not evidence.

Clients are recorded the same way: `webrtc_offer` in the log is written when a
browser starts a peer connection, with the address the hub saw it come from.
Whatever the two peers then discover through STUN is theirs to negotiate and does
not belong in a log.

Deleted accounts are not counted or listed anywhere in the panel. The tombstone
row exists so the connection log stays readable (§2) and is not a user.

---

## 9. Moderation and Legal

### Who is the legal host

**You, the node operator, are the legal host of all content you serve.** MeshBay is a protocol and a registrar service, not a content host. By running a node, you take full legal responsibility for what your node shares.

The hub (`meshbay.org`) is a registrar analogous to a domain registrar — it handles identity and routing, not content. Its legal exposure is similar to that of a registrar, not a hosting provider.

### Content reports (public groups)

```
Report #1 → public access suspended automatically
           → node operator notified via email
One republication allowed
Report #2 → escalated to hub moderators
Confirmed → group revoked on local hub
           → revocation token propagated to federated hubs
```

Mechanism: the file's `blake3` hash is added to the hub blocklist. A signed revocation token (Ed25519) is sent to the node. Nodes verify the revocation token offline.

### CSAM policy

All public content hashes are checked against the NCMEC and IWF databases at the time of indexing. Any match results in immediate revocation of the group and the account, and mandatory reporting to NCMEC. No scanning of private encrypted content is performed — it is technically infeasible.

This hash-matching step is mandatory for hub operators and reduces legal exposure under applicable law (NCMEC CyberTipline obligations).

### Copyright

Takedown on receipt of a valid DMCA notice or equivalent. The hub can revoke a group on confirmed legal request. No automated technical blocking (high false-positive risk, fair use concerns).

### Private content

Private group content is E2E encrypted. The hub cannot read it. Action available on a formal legal request: revoke the user or group at the hub level. The hub issues an Ed25519-signed revocation token verifiable offline by all member nodes. This terminates future access without retroactively decrypting past content.

### Connection logging

The hub logs the following events with timestamp and source IP for a minimum of one year (LCEN, EU e-Commerce Directive, DSA compliance):

| Event |
|---|
| Account creation |
| Login (success and failure) |
| Group creation |
| Group join / leave |
| Group deletion |
| Revocation actions |

These logs are not used for any purpose other than responding to legal requests. They are not exposed to users, group operators, or third parties without a legal order.

---

## 10. Troubleshooting

### JWT expired

**Symptom:** node returns 401, error says "expired" or "Token signature expired".

In the web app this should not happen: it renews before expiry and retries once
on a 401. If you see it there, the renewal path itself is broken — check the
browser console rather than the token.

**Fix (other clients):** your access token is over 4 hours old. Refresh it, and
**keep the refresh token that comes back** — the one you sent is now revoked:

```bash
curl -s -X POST https://meshbay.org/v1/users/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"YOUR_REFRESH_TOKEN"}'
```

If the refresh token is also expired (>30 days), log in again.

### GEK bundle not found (404 on `/v1/groups/{id}/gek`)

**Symptom:** `404 {"detail": "No GEK bundle for this user in this group"}`.

**Causes:**
- You are not a member of this group — the admin needs to add you and upload a GEK bundle for you
- Your public key registered on the hub differs from your current keypair — this happens if you regenerated your keys after registration (see below)

### GEK decryption fails (`InvalidTag`)

**Symptom:** `ChaCha20Poly1305.decrypt()` raises `cryptography.exceptions.InvalidTag`.

**Cause:** your local X25519 private key does not match the public key that was on the hub when the GEK bundle was created. This happens when:

- You ran the registration script more than once without persisting `my_keys.json`
- You deleted and recreated your keystore

**Fix:** contact the group admin. They need to fetch your current public key from the hub and re-wrap the GEK for you.

### Node is not reachable from outside

**Symptom:** curl to `http://YOUR-IP:19001/` times out from another machine.

**Checklist:**
1. Is the port open in your firewall? (`sudo ufw allow 19001/tcp` on Ubuntu)
2. If behind a home router: have you set up a port forward for `19001/tcp` to your machine's local IP?
3. Is the node actually listening? (`ss -tlnp | grep 19001`)
4. Is your ISP blocking inbound connections on that port? (Some mobile ISPs do this — use a VPS)

NAT traversal without manual port configuration (STUN/hole-punching for most residential connections) is coming in v2.

### `Connection refused` on port 19001

The node is not running, or it started on a different port. Check your `node.toml` `listen_port` and the node's startup log output.

### Hub returns 422 (Unprocessable Entity)

Usually a malformed request body. Check that:
- `Content-Type: application/json` header is present
- Your public keys are base64-encoded raw 32-byte values (not PEM, not hex)
- Password is at least 8 characters

### Node announces but no files appear in index

- Check that `shared_dir` exists and contains files
- Check the node log for indexing errors (permission denied, symlinks, etc.)
- The node re-indexes on startup and watches for changes. If a file was added while the node was down, restart the node or touch the file to trigger a watch event.

### `AEAD decryption failed` on chunk download

- Verify you fetched the GEK bundle for the correct group
- Verify `chunk_index` in the HKDF `info` matches the `chunk_index` field in the JSON response
- Verify `file_hash_b64` is decoded to bytes before use in HKDF `info`
- Verify the GEK itself is correct by re-fetching and re-unwrapping the bundle

---

## 11. API Reference

All hub endpoints are under `https://meshbay.org`. **Nodes have no public HTTP API** —
they speak MNP (§6), and their only HTTP surface is the operator's admin UI on loopback.

### Hub API

**Hub metadata**

| Method | Path | Auth | Description |
|---|---|---|---|
| GET | `/v1/hub/info` | None | Hub metadata: hub_id, MNP/MHP versions, user count, node count |
| GET | `/v1/hub/pubkey` | None | Hub Ed25519 public key (PEM) — cache this for offline JWT verification |

**User management**

| Method | Path | Auth | Description |
|---|---|---|---|
| POST | `/v1/users/register` | None | Register account. Body: `username, email, auth_key`. No keys — identity keypairs are per node. Returns `user_id`. |
| POST | `/v1/users/login` | None | Authenticate. Body: `username, password`. Returns `access_token, refresh_token`. |
| POST | `/v1/users/token/refresh` | Refresh token | Issue new access token. Body: `refresh_token`. |
| GET | `/v1/users/{username}/pubkeys` | Access token | Returns `user_id`, `username` and `pk_node_ed25519` only. It no longer returns identity keys: wrapping the group key for whatever this endpoint answered was finding H3, and the node wraps it now (§3). |
| DELETE | `/v1/users/me` | Access token | Delete your own account. Body: `auth_key` — the passphrase is re-checked. `409` if you still own groups. |
| DELETE | `/v1/admin/users/{user_id}` | Access token (hub admin) | Delete someone else's account. Same tombstone, same refusal if they own groups. |

**Node management**

| Method | Path | Auth | Description |
|---|---|---|---|
| POST | `/v1/nodes/announce` | Access token | Register node. Body: `pk_node, endpoint_hint`. Returns `node_id`. |
| GET | `/v1/nodes/{node_id}` | Access token | Retrieve node record: `pk_node, endpoint_hint, username`. |

**Group management**

| Method | Path | Auth | Description |
|---|---|---|---|
| POST | `/v1/groups` | Access token | Create group. Body: `name`. Returns `group_id`. |
| GET | `/v1/groups` | None / Access token | List/search groups. Private groups require membership. |
| GET | `/v1/groups/{group_id}` | None / Access token | Group metadata. |
| PATCH | `/v1/groups/{group_id}` | Access token (owner) | Edit the description. Body: `description`. Nothing else is editable — see §3. |
| DELETE | `/v1/groups/{group_id}` | Access token (admin) | Revoke and delete group. |

**GEK distribution — removed.** The hub used to carry wrapped group keys between members.
It does not any more: the node holds the GEK and wraps it itself, for a key the recipient
proved possession of over an authenticated channel (§3, and `docs/invite-pairing-v1.md`).
There is no hub endpoint that touches group key material.

**Notifications**

| Method | Path | Auth | Description |
|---|---|---|---|
| GET | `/v1/notifications` | Access token | Your notifications, newest first, plus an `unread` count. Chat is one entry per group. |
| DELETE | `/v1/notifications/{id}` | Access token | Dismiss one. The row is deleted — a notification is a signal, not a record, and the group, the message and the invitation it pointed at are all still there. |
| POST | `/v1/notifications/{id}/read` | Access token | The same thing. Kept because the interface ships inside the desktop package, so a hub is always answering some client older than itself. |
| POST | `/v1/notifications/read-all` | Access token | Dismiss every one. Same as `DELETE /v1/notifications`. |
| DELETE | `/v1/notifications` | Access token | Delete all of yours. |
| POST | `/v1/groups/{group_id}/mute` | Access token (member) | Body: `muted`. A muted group creates no notifications at all. |

**Revocation**

| Method | Path | Auth | Description |
|---|---|---|---|
| POST | `/v1/revoke/user/{user_id}` | Access token (hub admin) | Revoke a user account. |
| POST | `/v1/revoke/group/{group_id}` | Access token (hub admin) | Revoke a group. |
| GET | `/v1/revoke/denylist` | None | Current `jti` denylist for active access tokens. Nodes poll this to enable individual token revocation. |

### Node API

The unauthenticated HTTP API (`/`, `/index`, `/file/{id}`, `/stream/...`) was **removed in
0.2.0**, findings C1 and C6. Everything a member does now goes through MNP after a
handshake that establishes what they are allowed to see:

| Client → node | Node → client | Purpose |
|---|---|---|
| `handshake` | `handshake_ack` | Token, group, and the node's signature over the transcript |
| `handshake_challenge` (node first) | `handshake_response` | Proof the peer holds the GEK |
| `join_request` | `join_result` | Pairing code, or recognition of a pinned identity; carries the wrapped GEK on success |
| `index_sync` | `index_sync` / `index_delta` | The group index |
| `file_req` | `file_chunk` | One encrypted 1 MB chunk |
| `file_upload` | `file_upload_ack` | One chunk into the folder you are browsing; both halves sealed under the group key, so the filename and the bytes never appear on the wire in clear. The ack names the file as stored |
| `dir_create` | `dir_create_ack` | Create a directory |
| `file_delete` | `file_delete_ack` | Delete a file you uploaded |
| `stream_req` | `stream_init`, `stream_data`, `stream_end` | MSE video |
| `chat_msg`, `chat_hist` | `chat_hist_resp` | Chat and its history |
| `gek_bundle_fetch` | `gek_bundle_resp` | Your own wrapped group key |
| `keypair_bundle_fetch` / `_store` / `_delete` | `keypair_bundle_resp` | Your encrypted keypair backup on that node |

**Auth:** the JWT is verified offline against the hub's Ed25519 public key — the hub is not
contacted (~884µs). The token proves which account you are; it does not decide what the
node serves you. That is the node's roster and the GEK proof.

**The node's admin UI** (`/api/*`, loopback, token required) is the operator's, not a
member API.

---

*MeshBay protocol: MNP v0.1 over WebRTC DataChannel (browsers) and QUIC (native). The
TCP+TLS transport was removed in 0.2.0 — finding C6.*
*Hub: https://meshbay.org — FastAPI + PostgreSQL + Caddy.*
*Packages: python3-meshbay-common, meshbay-hub, meshbay-node.*