open-standards/joule-code/joule-code-rs/crates/joule-moq-room

joule-moq-room

A room service for WAI live rooms (wai/extensions/live-rooms.md) over joule-moq-relay. It holds one room's authority and clock keys and:

• issues grants. A visitor's page makes an Ed25519 key and asks for a grant for it (POST /grant). The service signs a short-lived WRG1 grant: a publisher's (its own audio and video, one of the room's places) or a viewer's (the room to watch). A grant is public, so it is useless without its key: the relay, configured with the authority's key ([[auth.authorities]]), honours it only beside a proof of possession over the relay's own challenge (§10.5), which only the page that holds the key can make. Grants are bounded per client address and overall, and publishers per room. Every role, and so every grant, holds the seek power (live-rooms §3.3, bit 4): a visitor may fetch a track below its live edge (§10.6), from the relay's cache or its DVR window, as a late joiner does for the groups before it joined. A relay refuses such a fetch to a grant without it.

• authors the lifecycle (§7.2). The service's clock is a session on the relay. It watches each publisher's video track (a SUBSCRIBE that asks for no objects): when the track appears the clock signs join and publish for the publisher on its events track (live-events §8.1), and when the relay ends the track (the publisher's session closed) it signs leave. Pages author none of it.

• serves the room. GET /room gives the signed descriptor, the composition descriptor and the publishers' grants, which a page verifies the room with (live-rooms §9).

• keeps end-to-end encrypted rooms ([room] e2ee = true, WAI extensions/confidentiality.md). Each room then has a confidentiality record (WRE1) the authority signs, and one MLS group whose only external sender is the room's clock: the clock proposes the Add of each publisher it records joining and the Remove of each it records leaving, and follows the group from its public messages, holding no key. The service is the room's carrier of MLS messages (§5.1, §15.2): one log per room holding the clock's lifecycle records, its proposals, and every GroupInfo, commit and Welcome a member posts, in the order the clock took them; a post the clock refuses (§5.5) is not carried.

A room lasts while anyone publishes in it. When the last publisher has left, the next one starts a new room: a new descriptor at a new t0, under the same authority and clock, so each room's grants and chain hold one stretch of company.

Running it

joule-moq-room keygen <keys.toml>       new keys (mode 0600, never over a file); prints the
                                        relay configuration lines that trust them
joule-moq-room relay-lines <keys.toml>  those lines again
joule-moq-room --config <room.toml>     serve (room.example.toml shows every field)

The keys file must be readable by its owner alone; the service refuses it otherwise. Keys has no Debug, so that no log prints a seed.

The relay needs, beside its listener and limits, the lines relay-lines prints:

[[auth.authorities]]
key = "<authority>"

[[auth.grants]]                  # the clock's events track, in any room
prefix = ["*", "<clock>", "events"]
token_sha256 = "<SHA-256 of the clock's token>"
publish = true
unlimited = true                 # no session or ingress limit for the clock's session

[[auth.grants]]                  # the clock watches the publishers
prefix = []
token_sha256 = "<SHA-256 of the clock's token>"
subscribe = true

and a door that holds each publisher's media to its own key:

[[receipts.door]]
prefix = ["*", "*", "video"]
trust_field = 1

HTTP

Request	Answer
GET /, GET /health	{"ok", "relay": the clock's session is open, "room"}
GET /room	the room: room, t0_us, descriptor, compose, grants (hex), present, publishers, max_publishers, and e2ee ({"record": <hex>, "log"}, or null)
POST /grant {"principal": <64 hex>, "role": "publisher" | "viewer"}	{"grant", "digest", "exp", "role", "room": <as GET /room>}; 409 full or busy; 429 rate with retry_after_s; 503 relay while the clock has no session
GET /mls?room=<id>&from=<n>[&wait_ms=<ms>]	an end-to-end encrypted room's log from entry n: {"room", "entries": [{"seq", "event" or "mls": <hex>}], "next", "end"}, held up to 8 s while nothing is past n; 410 for a room since replaced, 404 for a room that is not end-to-end encrypted
POST /mls/key-package {"room", "key_package": <hex>}	kept for the principal's Add: {"ok", "principal"}; 403 for a principal the room has not granted
POST /mls/post {"room", "frames": [<hex>]}	a GroupInfo, or a commit and its Welcome, checked by the clock as a member checks it, then carried: {"ok", "seq"}; 409 {"error": <reason>} when the clock refuses it

Every answer is JSON with Cache-Control: no-store. The client's address is CF-Connecting-IP, else the first X-Forwarded-For, else the connection's: the service listens on loopback behind the front that sets them.

Tests

cargo test (this crate is a workspace of its own, with its own lock file, since it builds on wai-rs): the keys file, the grants checked against the descriptor and read by the relay's reader, the places, the limiter, and tests/room_service.rs, the service against a relay on loopback: a grant and its proof open a session and the clock announces the publisher, the grant alone opens none, the room verifies, a third publisher is refused, clients are bounded, and a new room starts when the last publisher has left; and an end-to-end encrypted room on a relay, two members keying through the service as pages do (a GroupInfo, the clock's Add, a commit and its Welcome), the posts the clock refuses not carried, each opening what the other seals, and a member that leaves removed by the next commit.

Licence

Apache-2.0.