open-standards/joule-code/joule-code-rs/crates/joule-moq-room/README.md

joule-moq-room

A room service for WAI live rooms (wai/extensions/live-rooms.md) over joule-moq-relay. Its binary is wai-room (the crate keeps its name). 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. The events track is published with the room's first grant, before anything is signed on it, so a viewer who enters a room nobody has joined subscribes to a track that is there.

• 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).

• admits AI captioners ([ai], WAI live-rooms §4.4, src/ai.rs). With captioners above 0, every room's descriptor has a role captioner holding the ai power (§3.3): no media to publish, the room to subscribe to, the seek power, and its kinds a caption and its annotation (timed-text §4.2). An AI participant asks for its grant as any participant does (POST /grant, the role captioner, ai the pin of the model that acts for it); the grant carries the pin in its attribute ai, is listed with the room's, and holds no publisher's place, and the clock records the captioner joining when its events track appears and leaving when it ends. models names the pins a captioner may name (403 ai_model_not_admitted otherwise), and captioners how many hold a place at once (409 full). Since a role of the descriptor holds the ai power, ai asked under a role without it is refused, 403 ai_role_not_permitted, as every verifier of the room refuses such a grant (§4.3 step 9); in a room with co-performance that takes AI participants, the publishers' roles hold the power too. Not an end-to-end encrypted room, a watch room, a world room, a remote desktop room, a conversation or a call. The captioner itself is joule-moq-agent's (wai-room-agent caption).

• keeps remote desktop rooms ([remote], WAI extensions/remote-desktop.md). Every room is then one host's screen shared into it, its descriptor's roles a host (it publishes the screen kind and holds the direct power), a controller and a viewer, and every grant's policy permits meta, so that each principal sends the extension's statements. The host's grant carries remote_host; a controller's the control power, remote_control = control; a viewer's neither. The host is the key host names or, when it names none, the first key that presents an invitation the room's authority signed (wai-room invite), to which the invitation is then bound. Who may ask for a controller's grant is allow: all, listed (the keys controllers lists) or none. The host hands control over by a grant exchange (POST /remote/control, its grant and a proof over the service's challenge), which takes effect at a tick at least lead_ms ahead, so that every party holds the clock's grant_exchange before the instant it governs. The clock watches the host's screen track (its join and its publish of the screen when the track appears, its leave when it ends) and every other principal's events track, and follows every principal's events: it takes each record in its chain's order, under the policy of its author's grant in effect and after its join, each statement read and held to who may sign it, and the host's screen statements to §3.4 and to the age bound max_age_ms. It computes the host's floor in the merged order by wai-rs's §7.2 rule: a floor statement the rule refuses is kept, stated, and changes nothing, as the host and a verifier have it (GET /room's remote.holder). A principal whose record is out of that order is cut there and removed (leave reason 2), and the host's agent cuts it at the same record: the room the clock holds stays one a verifier accepts. The clock bounds the records it holds of a session, per principal first. At max_records_per_principal (100000 by default) it holds none of a principal's records past the bound, cuts the principal there (max_records_per_principal) and removes it (leave reason 2), and the session goes on; the host's agent reads the bound from GET /room and cuts the principal at the same record, so the two hold the same records. The host has no bound of its own: its outcomes answer the others' inputs. The default: a two-hour session at an average of ten input statements a second is 72000 records, and a principal flooding at the policy's 120 events a second reaches the bound in about 14 minutes, and is removed alone. max_records (1000000 by default) bounds the whole session, the host's records among them, and is the safety net: ten times the bound per principal, above a host and four controllers each at its bound (800000), so the bound per principal bites first for any one principal. When a record would pass the total the clock holds none past it and ends the session, every present principal's leave (reason 2) signed, the host's last, and GET /room's remote.ended states max_records; the session it holds stays whole and verifies, and the next host starts a new room. It ends the session rather than refuse inputs past the total: a record it did not hold would leave a hole in its author's chain, the host would decide inputs the clock never held, and an input's refusal is the host's to state. At the total the clock holds about a gigabyte. Key, text and clipboard actions reach the clock sealed to the host (WAI remote-desktop §5.5): it holds and serves ciphertext, and no opening key. A remote room is not also end-to-end encrypted, a watch room, a room with co-performance, one admitted by age or a world room: the service refuses such a configuration. The relay holds the host's screen to its key with a door like the publishers' (prefix = ["*", "*", "screen"]).

• 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.

• admits by age ([age], WAI extensions/age-assurance.md §5.6), as the Privacy Pass origin of RFC 9577. Each room then has an age policy (§4) naming the configured issuers with one key per threshold, and a rating (§3), a room claim, both signed by the authority. A grant request without a token is answered 401 with a PrivateToken challenge for each key (WWW-Authenticate, RFC 9577 §2.1.2): its redemption context HMAC-SHA-256 over the room and a window of token_window_s under a key drawn at start (a restart turns outstanding challenges away), its origin_info the service's server name (origin, else the request's Host). A request with Authorization: PrivateToken token="…" has the token checked by wai-rs's §5.2 against the room's age, and its grant states the token's threshold in age (§5.4), from which the relay holds every track to the serving rule (§5.5). The nonces redeemed are kept for the current window and the one before, at most max_nonces a window (past it, 503 and nothing spent), and dropped as a window ages out. Each admission is counted by its window, issuer and threshold, and nothing else of it is kept: GET /age/receipt gives the room's wai-age-admissions receipt so far (§7), signed by the clock, every count under 50 suppressed, and with receipts_out each window's is appended there as it closes, and the rest of a room's when it ends. The room's rating rides the clock's events track and the grant answer's room, which a publisher's page carries on its tracks (§5.7). The clock's own session proves both room keys in its SETUP (a GRANT_PROOF naming no grant, §5.5, over a challenge the relay's SETUP gave on a first session, the relay reading a client's SETUP before it sends its own), so the relay serves it the room's rated tracks as the room's own service: it follows each publisher and, with [co], logs every performer's objects. Operating an issuer, or the attester that establishes an age, is not the service's.

• keeps co-performance ([co], WAI extensions/co-performance.md). With audience_input above 0, every viewer's grant carries the audience-input power (the attribute audience_input, the most inputs it may send to one selection window) and may send meta events and reactions, and the viewers' grants are listed with the room (co.audience) so a page verifies their inputs; with latency_budget_ms above 0, every publisher's grant carries that budget. Either gives the room a co-performance policy (WPP1) the authority signs (co.policy), its publishers meta events (their intents), a lead role with the direct power for the first publisher (lead), and, with ai, a grant marked as an AI participant's for a page that asks ("ai": <model digest>). The clock then keeps what only it knows (src/co.rs, co-performance §8): it records each audience member joining when its events track appears, holds the room as a verifier does (every member's chain, by FETCH where it has a gap), logs each publisher's media objects with their arrival and their due instant (GET /co/objects, the objects a verifier is given), and signs a mark (WPM1) for each object out of turn under a schedule that marks or later than its budget, the commitment (WPK1) and selection (WPS1) of each window once it closes, and the periodic fidelity statement (WPF1). A page asks the clock for a turn schedule (WPT1), a handover (WPH1) or a window (WPW1) over HTTP (POST /co/...), with its grant and a proof of possession over a challenge the service issued (live-rooms §10.5.3); its powers decide what it may ask. The relay holds the floor and the audience's inputs (its [floor], which relay-lines prints commented out).

• keeps watch rooms ([room] watch_source, WAI extensions/co-watch.md). Each room then watches that file together: the authority signs a co-watch policy (WXP1) naming it, an object sequence of one object, by the SHA-256 of its bytes and its duration, and the service serves the bytes. A visitor enters the room's co-watch log by a proof of its grant's key over a challenge the service issued, for the request it makes (live-rooms §10.5.3), and the clock signs its join; every grant carries watch_control, the actions its principal may control. The service is the room's carrier of its viewers' events: one log per room, holding every record of the clock's chain and every control and presentation statement a viewer posts, each carried only when a verifier would accept it (its chain, its signature, its grant's policy and rate, and co-watch §5 and §7.2). Each window, the clock signs the skew statements of co-watch §8.4 from what the log holds; and a viewer silent for four seconds, or whose grant has ended, leaves. One that enters again before the clock has signed that leave has it signed first, then its join, so that no join comes while it is present. A watch room is never end-to-end encrypted (its source is served in the clear), admitted by age (its source is served without a grant) or a room with co-performance: the service refuses such a configuration.

• has a library for playout timing (the tempo module, WAI co-watch §15, draft-nandakumar-moq-tempo-00): the draft's CaptureTimestamp, PlayoutDelay and HopTime read and written, the instant a source's object is due under the controlled position, a timing claim held to it and to the track's bound, and a change of delay as the controls that make it. Corpus wai/moqt-conformance/tempo/, written with JOULE_MOQ_ROOM_WRITE_TEMPO=1 cargo test --test tempo_vectors. A watch room's file is still served over HTTP and stamped by nothing; the room's own source below is stamped.

• publishes the room's own source over MOQT ([source], src/source.rs). A package wai-pack wrote (package, its video and audio rungs) is published into each room in real time, looped, as a principal of its own: its key derived from the clock's seed, its grant a publisher's the authority signs, with meta events among its kinds. It holds one of the room's publisher places, the clock signs its join and publish when its video appears, and GET /room names it (source.principal) with its delay, its bound and the property types its stamps are written under (source.types), which the room page reads them by. Its catalog is MSF's (tests/catalogs/source.json, held by wai/ietf/catalog_check.py --strict): each media track a CMSF track with its receipts track and its wai_tempo, and the source's events track. Each object is a CMAF chunk (video_part_frames frames of video at framerate, 3 at 30 by default; audio_part_frames of sound, 5) stamped with playout timing (draft-nandakumar-moq-tempo-00): inside Immutable Properties a CaptureTimestamp, the instant its last sample was captured, and a PlayoutDelay, playout_delay_ms (500 by default, at most max_delay_ms, 2000); beside them a HopTime of the source's clock, which the relay rewrites. The property types are playout_delay_type, capture_timestamp_type and hop_time_type, as the relay's [tempo] names them, with its defaults: a deployment that sets them on the relay sets the same here. A live source plays no controlled position, so its instants are its captures plus its delay, and every object states one capture clock. For each object as it is sent the source signs a running receipt (WAI live-http-egress §3.5): a meta event anchored to the object, the next of its chain on its events track; the group's receipts are signed and sent at the group's end, at a transport priority above its media's and its events' above both. A relay door over the source's namespace ([[receipts.door]], as wai dev writes it) reads those running receipts and passes each object as soon as its group's run covers it; the group's receipts close the run there. The service's tests hold the source to that door: every object passed on its run, none refused. The source is not published in an end-to-end encrypted room, one admitted by age, a world, remote desktop or call room, or a conversation, and the service refuses such a configuration.

• stitches the source's breaks for each session ([ads], src/ads.rs; WAI live-ads §14.8). In each room the source publishes into, the authority signs the room's ad policy (claims required), the decider's grant (a key derived from the clock's, the room's budget as funds_ceiling in currency) and the traffic policy ([ads.traffic]: the session cap, the edges and the lists it pins). The source cues each break of the schedule (first_break, every, breaks, break_groups, in video Groups) at the Group's instant, signed before the Group's first Object; the stitcher reads the cues back over the relay, each held to its signature, chain and principal. A session subscribes, under its session key K, to [room, source, video, stitched, D, K] (D the traffic policy's digest): K its composed video, receipts its group receipts, ads its creative records, catalog its catalog with wai_creative_signing (tests/catalogs/stitched.json). Each break is decided for each session from the SCTE 224 documents scte224 names (read again at each decision) and the region the session stated, then by the fill over the fixture creatives ([[ads.creative]], rungs of wai-pack packages, each with its sound where audio_package names a package's sound rung); a receipt is sealed claim_grace_ms after its break ends. With sound, a session's composed sound is K in [room, source, audio, stitched, D, K], with its receipts, each Group taken from the ingredient its video Group of that ID was taken from. Each composed Group's receipts are signed as the Group ends, and each composed Object has a running receipt (WAI live-http-egress §3.5) as it is sent, a meta event of the source's own chain on its events track, anchored to the composed Object: so an HTTP egress serves each part as it is covered, not at the Group's end. A creative's Objects are sent at the programme's pace, its Object j as the programme's Object j arrives and what is left of its Group with the programme's last, so a composed Group's parts come as its time goes. The source's grant states the event policy that admits them, the default rate for each of its own tracks and each session's composed two (epoch::stitcher_policy). An injector the configuration names ([ads] injectors, WAI cue-injection) takes a grant of the role injector (meta and cue, no media); the clock signs its join when its events track appears, and the stitcher reads its cues as the source's. A break whose cue falls inside a programme Group is stitched from the next Group, each session's receipt stating the offset (start_offset_ms, live-ads §14.3). Every composed Object carries its timing (live-ads §14.3, Its timing): a CaptureTimestamp of the programme's capture clock at its end on the composed timeline, the source's PlayoutDelay, and a HopTime; the session's catalog states the source's wai_tempo on each composed track. While no creative lasts otherwise than the Groups it fills, each programme Object carries the stamp its source gave it.

• keeps a shared world ([world], WAI extensions/live-worlds.md). Each room then has a world statement (WLW1) the authority signs: the world its operations replay in (for wai.world.model, the model header) and the bounds of an op and of an object, served with the room (GET /room's world). A publisher's grant is an actor's: it lets its principal publish its world track (the attribute world = act, §5.1) and no media. The clock watches each actor's world track, [room, actor, world], as it watches a publisher's video: it signs the actor's join when the track appears and its leave when the track ends, and no publish. The world's ops are the actors' own, signed by their keys and receipted on their tracks; the service neither reads nor keeps them, and a page that enters late fetches every track from the relay (§7), which the relay-lines' commented [[dvr.window]] keeps. With e2ee, the world is private: every actor is a member of the room's group, and the world tracks are sealed (§8). A world room is not also a watch room, a room with co-performance, one admitted by age or a remote desktop room: the service refuses such a configuration.

• keeps a conversation ([messaging], WAI extensions/live-messaging.md). The service's room is then an end-to-end encrypted conversation, kept in a history store on disk (store): conversation.json, its descriptor, confidentiality record and conversation statement (WMC1), written once; and journal, every record the service took, appended and on stable storage before it answers. A key that proves itself (a proof naming no grant, over a challenge the service issued) is admitted (admit), the first as the conversation's owner, and the clock signs its join; an owner removes a member and the clock signs its leave. The clock is the MLS group's external sender, any member commits (live-messaging §7.2), and after each GroupInfo or commit the clock signs an epoch statement (WME1). Members post sealed messages and acknowledgements, which wai-rs's conversation verifier checks before the service takes them (§9.2), and read the log as §9.3 owes it: a removed member nothing past its removal. A restart replays the journal, regenerating the clock's proposals and statements and checking each against the one journalled, so the conversation goes on where it stopped. The service holds no key of the group and no plaintext. A service that keeps a conversation keeps nothing else (no watch room, co-performance, admission by age, shared world, remote desktop, [room] e2ee or call): it refuses such a configuration.

• keeps calls ([call], live-messaging §10). A caller proves its key and places a call: the authority signs its descriptor (WCT1) and the caller's grant; the caller's invitations (WCI1), checked by wai-rs's call verifier, are held in each invitee's inbox, which it reads on a proof of its key; its answers (WCA1) are checked the same way, and an accept comes with its grant. At each invitation's deadline the clock signs a missed call. The media is the room's audio and video, as in any room. POST /grant is refused: the grants come with the call. A call room is not also a watch room, a room with co-performance, one admitted by age, a world room or a remote desktop room: the service refuses such a configuration.

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

wai-room keygen <keys.toml>       new keys (mode 0600, never over a file); prints the
                                  relay configuration lines that trust them
wai-room relay-lines <keys.toml>  those lines again
wai-room invite <keys.toml> [<s>] an invitation to host a remote desktop room, signed by
                                  the room's authority, good for <s> seconds (3600)
wai-room --config <room.toml>     serve (room.example.toml shows every field)
wai-room participant --service <url> --relay <url> [--quic <addr> --cert-sha256 <hex> ...]
                                  synthetic participants of a development stack on this
                                  machine, driven by JSON control lines: what `wai dev` runs

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

The image

deploy/Containerfile builds wai-room as an OCI image from the repository's root: the binary built with the pinned toolchain from the locked dependencies, on a slim base pinned by digest, run as the unprivileged user wai (uid 10001), its keys in the volume /var/lib/wai-room, and a configuration (deploy/room.toml) that serves HTTP on port 9682 and reaches a relay container named relay at ws://relay:4480/moq. The keys are made once, and the lines that make the relay trust them are printed:

docker run --rm -v wai-room:/var/lib/wai-room wai-room keygen /var/lib/wai-room/keys.toml
docker run -v wai-room:/var/lib/wai-room -p 9682:9682 wai-room

deploy/check-image.sh builds it and runs it beside the relay's image on one network, both with a read-only root and no capabilities, and requires /health with the clock's session to the relay up. A release pushes it to the forge's container registry as git.transaction.science/transaction-science/wai-room:<version>.

Synthetic participants

wai-room participant (src/participant.rs) is the client half of WAI's one local stack, wai dev: test principals that enter a room through a relay and a room service on this machine, each running as its own process from its configuration. It reaches the service over HTTP, for grants and for the room it serves, and the relay over its WebSocket binding or, impaired, its native QUIC binding, the relay's development certificate pinned by its SHA-256. The service and the relay must be on loopback addresses, checked before anything is sent. Each object goes out with its receipt: a group receipt signed by the publisher's key on the track's receipts track, sent before the group's first object, and the receipt as the object's WAI_RECEIPT property, so a relay that holds each publisher's tracks to its own key passes them. On the QUIC binding each session goes through a UDP proxy of its own (joule-contrib's lossy) that drops, delays and spreads its datagrams from a fixed seed; loss applies to datagrams, so to QUIC alone. A session over a path that drops datagrams waits for the answer to a request (a PUBLISH, a SUBSCRIBE, a FETCH) as long as it waits for an object, a minute, where a session otherwise waits ten seconds: a request and its response are each recovered at QUIC's probe timeout when dropped, which on a session that has measured no round trip yet starts near a second and doubles. The relay's own ten seconds for a session's SETUP stand. wai dev --impair writes its relay's doors that same minute's hold, where it otherwise writes two seconds.

Its first line on standard output is {"ready": true, "participant": true, "development_only": true, "service", "relay", "transport", "impair"}, and it answers JSON control lines on standard input, each with an op and an optional id:

op	Fields	Answer
join	seed (a test principal's Ed25519 seed, 64 hex), grant (a publisher's grant for that key, hex), objects (per track, 1 to 64), receipts (default true)	the principal enters with its grant and a proof, publishes audio and video with that many objects on each, and the answer comes once the clock has signed its join and both publishes: {"principal", "room", "tracks", "receipts", "objects_published", "objects_served", "events"}
leave	principal (64 hex)	its session closes; the answer comes once the clock has signed its leave
session		the room as live-rooms §9 gives it to a verifier: {"room", "t0_us", "descriptor", "grants", "key_log_head": null, "chains"}
test	objects (50), every_ms (20)	a publisher and a viewer of fresh keys: {"transport", "impair", "objects_sent", "objects_received", "objects_lost", "undelivered", "latency_ms", "path", "impaired", "seconds"}; path is QUIC's own count of packets sent and declared lost and its round trip, impaired what the proxy dropped, and undelivered (null when every object arrived) each missing object's group with where it stands at the viewer: its stream never opened there (the relay forwarded nothing of it: its door refused it, or it never reached the relay), open and unfinished, ended without it, or failed with its error
load	viewers (8, at most 64), objects, every_ms	one publisher and that many viewers: {"viewers", "deliveries_owed", "deliveries_made", "delivered", "latency_ms", "enter_s", "path", ...}, the client half alone
describe		the ready line's fields

Standard input closing ends it. tests/participants.rs holds it to a relay with doors: a participant without receipts is dropped there (and served where there is no door), impairment changes the loss QUIC measures, and a load is delivered in full.

src/dev.rs is a test fixture, not a mode of the binary: the relay and the service in one process on loopback, keys in memory, for this crate's tests.

HTTP

openapi.json describes this API (OpenAPI 3.1): every path, its requests, answers and statuses, in every mode the service keeps. Each operation's operationId is its name in the WAI toolchain's catalogue, noun.verb (room.show is GET /room, room.grant is POST /grant), the name the other doors derive theirs from (wai mcp's tool room_grant). tests/openapi_contract.rs holds it to the code: every operation is named as the catalogue names it, the routes the routers match are exactly its operations, every status it lists for an operation is one that operation's handlers return and every status they return is listed, and the service, run in each mode, answers every operation with a status it lists.

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, e2ee ({"record": <hex>, "log"}, or null), co ({"policy": <hex>, "audience": [<hex>]}, or null), and world ({"statement": <hex>, "receipt_alias": 4}, 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
POST /grant {"principal", "role": "captioner", "ai": <64 hex>} in a room that admits captioners ([ai])	an AI captioner's grant, its ai the model's pin; 400 with no ai or in a room with no captioner role; 403 ai_model_not_admitted; 409 full while the captioners hold every place. ai asked under any other role, in such a room: 403 ai_role_not_permitted
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
POST /grant in a room that admits by age	without a token: 401 {"error": "token_required", "age"} and a WWW-Authenticate: PrivateToken challenge=…, token-key=…, max-age=… for each key; with Authorization: PrivateToken token="…": the grant, its age the token's threshold, or 403 {"error": <age-assurance §11's reason>} and the challenges again; 503 busy when the window's nonces are at their bound. GET /room's age is {"policy", "ratings", "age", "token_window_s"}
GET /age/receipt	{"receipt", "policy"}: the room's admission receipt so far, signed by its clock
GET /watch/time	a watch room: {"now_us", "t0_us"}, the service's clock, for a page's estimate of the room clock
GET /watch/source	a watch room's source, its bytes whole, of its media type
GET /watch/challenge	{"challenge": <hex>}: single-use, good for a minute
POST /watch/join {"room", "grant": <hex>, "proof": <hex>}	the proof (live-rooms §10.5.1) over a challenge, for POST //<host><public_prefix>/watch/join; the clock signs the principal's join, after its leave if the room took it for gone and that is not signed yet: {"ok", "t"}; 401 {"error": <reason>} for a proof that fails
POST /watch/post {"room", "events": [<hex>]} (at most 8)	the viewer's events, each checked and carried in order: {"ok", "carried", "log"}; 409 {"error": <reason>, "carried"} at the first refused
GET /watch?room=<id>&from=<n>[&wait_ms=<ms>]	the watch room's log from entry n: {"room", "entries": [{"seq", "event": <hex>}], "next", "end"}, held up to 8 s while nothing is past n
GET /watch/room	the room as a co-watch verifier is given it (descriptor, grants, chains, policies, sources), the latest window's skew statements read, and the refusals by reason
POST /grant in a remote desktop room {"principal", "role": "host" | "controller" | "viewer", "invitation"?}	the grant; 403 {"error": "not_the_host" | "invitation_required" | "invitation_used" | "invitation_expired" | "invitation_bad_signature" | "control_not_allowed"}; 409 hosted while the room's host holds its place. GET /room's remote is {"host", "allow", "control", "max_age_ms", "screen": {"digest", "statement"} or null, "holder", "floor_refused", "inputs", "floor_statements", "cut", "refused", "records", "max_records", "max_records_per_principal", "records_over", "ended"}
POST /remote/control {"to", "control": 0 to 15}	the host's grant exchange, its grant and proof presented as a co-performance request presents them: {"ok", "grant", "digest", "effective"}; 403 for a grant that is not the host's, 409 {"error": "not_present"}
GET /remote/room	the session as the clock holds it: {"room", "descriptor", "grants", "key_log", "chains"}, what a remote desktop verifier is given. The records hold what controllers typed and pasted, so they are the room's: a request presents a grant this room issued and its proof over the service's challenge, as a co-performance request does; 401 with a challenge otherwise, 403 for a grant of another room. Bounded per client
GET /remote/state	that session verified by wai-rs, to a grant of this room and its proof as /remote/room: the outcome, the screens, each input's fate, the floor's changes and the floor statements §7.2 refused, the latencies, each host's totals, the clock's own floor, and each principal the clock cut and why; bounded per client
POST /offer {"offer", "item", "anchor": {"track", "group", "object"}}	an offer the clock presents (WAI shoppable-events), for a grant with the direct power, presented and proved as a co-performance request is: the offer's document and the item's signed description, read as a verifier reads them, then signed by the clock as meta events of its events track, the description (WOI1) and then the offer (WOF1) anchored to the object the programme shows it at: {"ok", "offer": <its id>, "t", "record", "item_record"} (records in base64url); 400 {"error": "offer", "reason": <the extension's reason>} with nothing signed; 403 power. The service sells nothing: a viewer's intent goes to the merchant's own endpoint

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.

GET /metrics is the operator's: the service's counters in the text exposition format (wai/wai-metrics), answered before the routes of the API, so openapi.json does not describe it and the catalogue does not name it. It holds the requests by route, method and status (wai_room_requests_total), the grants issued at POST /grant by role (wai_room_grants_total; a call's and a conversation's grants come with their own requests, and are not among them), the rooms kept since the start, whether the clock's session at the relay is open, and the room now: the principals present (wai_room_present: a watch room's viewers who joined among them, and in a conversation its members), the publishers holding a place, the audience members holding one (a room with co-performance's, or a remote desktop room's controllers and viewers), and the viewers' grants, its fan-out (wai_room_viewer_grants: a remote desktop room's controllers among them; a conversation has none). No room, principal, grant or client is a label. It is read at the service's own address: a request that came through a front, one carrying X-Forwarded-For, CF-Connecting-IP or another of the fields a front sets, is answered 404, and a front that sets none of them is configured not to pass the path on.

A conversation's requests (each, but GET /msg and GET /msg/challenge, with a grant the conversation issued and its proof, or for /msg/join a proof naming no grant):

Request	Answer
GET /msg	the conversation: room, t0_us, descriptor, record, statement, clock, grants, members, the latest epoch, the log's length
GET /msg/challenge	{"challenge": <hex>}, single-use
POST /msg/join {}	{"grant", "digest", "exp", "role": "owner" | "member", "conversation"}; 403 not_listed or removed, 409 full
POST /msg/key-package {"key_package"}	kept for the member's Add
POST /msg/mls {"frames": [<hex>]}	a GroupInfo, or a commit and its Welcome: {"ok", "seq", "end"}, or 409 with the clock's reason
POST /msg/post {"group", "properties", "payload", "receipts"}	a message, taken after §9.2's checks: {"ok", "seq"}, or 409 with the reason
POST /msg/ack {"ack"}	an acknowledgement, taken after §8's checks
POST /msg/leave, POST /msg/remove {"principal"}	the clock's leave, reason 1, or reason 2 by an owner
GET /msg/log?from=<n>[&wait_ms=<ms>]	the entries owed from n ({"entries": [{"seq", "event" | "mls" | "epoch" | "message" | "ack"}], "withheld", "next", "end"}), held up to 8 s while nothing is new; 403 not_a_member

A room with ads ([ads]) answers, too: POST /ads/session {"player", "region"} (the session's key and the region it aggregated, or null); POST /ads/binding (a device binding, WDB1, held to the room's traffic policy and its two signatures); POST /ads/claim (a presentation claim, WPC1, held to its signature); GET /ads/list/wai-ad-<digest>.json and .mpd with player= and _HLS_start_offset= (the asset list filled for that session); GET /ads/creative/<hash>.m3u8 and its files; GET /ads (the room's ads); and GET /ads/records (?seal=all seals every fill first), what ads::audit verifies: the operator's, answered at the service's own address and 404 through a front, since its claims and bindings link the sessions of one device key. A binding and a claim are the record's bytes, or, as the toolchain's command line sends a body, {"record": <hex>}. openapi.json describes each of these paths, the asset list's and the creative's by their templates (/ads/list/{file}, /ads/creative/{hash}.m3u8, /ads/creative/{hash}/{file}), and the catalogue names them (ad.show, ad.export, viewer.join, binding.create, claim.create, asset.list, creative.show, creative.fetch); wai asset list --query file=wai-ad-<digest>.json --query player=<key> fills the template from the query. A path of [ads] answers 404 in a service without it, and 405 to a method it does not take.

A call's requests (/call/ring with the caller's grant and proof, the rest on a proof naming no grant): GET /call/challenge; POST /call/place {"invitees": [<64 hex>]} (the call descriptor, its digest and the caller's grant, 409 busy while a call has its places); POST /call/ring {"invitations": [<hex>]}; GET /inbox; POST /call/answer {"answer"} (an accept answered with the callee's grant); GET /call, to the call's parties.

Load

src/bench.rs is the service's load harness, and examples/room_bench.rs runs it with the relay and the service each a process of its own on loopback, so that the service's processor time is read apart: viewers' grants at a number in flight, publishers entering and leaving at once (the clock's join, publishes and leave read off its events track as they come), the room's own source with ads stitched for a number of sessions (each session's catalog, records, composed video and sound and their receipts), and AI captioners (joule-moq-agent's, its scripted test recognizer) beside speakers. Each run is a record signed by its host's key, under the relay harness's idle rule, stating each operation done of those owed, its 50th and 99th percentile against its bound, and the service's time a unit of its work. results/ holds one host's dated records, what stopped each size past the largest it held, and the guard (results/guard.sh) that holds later commits to them.

The stitcher answers every session's six subscriptions of its stitched tracks on the source's one session and holds them open, each a request stream of that session, so the session declares source::SOURCE_REQUESTS (six for each session a room holds, ads::MAX_SESSIONS, and 64 for its own); and each session's composed video and sound each hold a data stream open for their Group. A relay's default bound on one session's open data streams (limits.max_uni_streams, 1024) is reached at 512 sessions: a deployment that stitches for more raises it for its relay.

Tests

tests/openapi_contract.rs holds openapi.json to the service (above). tests/mcp_dev_room.rs builds wai with the feature mcp, in a target directory of its own, and drives wai mcp --toolset core,dev with an MCP client: the tool room_grant and the API's POST /grant named alike (room.grant), a development room started on loopback, grants for two test principals, each joining and publishing, the session verified as live-rooms §9 verifies a room, a changed record refused, a leave verified, and a grant from a service off the machine refused.

tests/ads_room.rs, the room's ads through the relay: two breaks the source cues, two sessions in two regions under an SCTE 224 document that blacks one of them out over the second break; every composed Group held to the stitcher's receipt, each session's records bound to its receipts and its composed track to its recipe, each audience decision held to its document, and the second break refused by the region rule for one session alone.

tests/offer_room.rs, an offer through the service and the relay: POST /offer refused for a viewer's grant, for an unknown stock written as zero, for another item's description and with no anchor, with nothing signed for any; the lead's offer signed by the clock, read from the relay by a subscriber as WAI shoppable-events reads it, with the description the room carried, the room's keys admitted, presented inside its window and not after; the same record refused where only a guest's key is admitted, and with one digit of its price changed.

tests/source_room.rs, the room's own source through the relay, its door (as wai dev's, each publisher's video and sound held to its own key) and the HTTP egress gateway: the door passes every object on its group's run and refuses nothing, no running receipt refused and no run contradicted; a viewer subscribed with Sync Support holds every object to its stamps (the configured types inside Immutable Properties, the catalog's delay within its bound, one capture clock across the two tracks read from each chunk's own media time, a HopTime of the relay's clock, arrival before the instant, every group whole and in order); the gateway serves each part on the run served beside it and every part of a closed segment on its group's receipts, nothing withheld or refused, its trace checked. And a real-time measurement: thirty seconds of 30 fps video and sound through the door with every part served within 500 ms of its capture stamp and none missing or withheld, and how long the door held each object against how long after it its group's receipts came (what a door that reads no running receipt holds it for), refused (and said so) on a host whose one-minute load is above a quarter of its processors.

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. Admission by age: unit tests of src/age.rs over published RSA test keys (tests/common/rfc_test_keys.rs: RFC 7517 A.2's, RFC 9500's testRSA2048 and RFC 9578 A.2's), whose tokens they sign directly, as the blind protocol's output is the same signature: the challenges by window, a token admitted once and at the room's age, the window before accepted and the one before that, another origin's and another service's challenge refused, the nonces bounded and dropped by window, and the receipt's cells the reference's and its signature the clock's; and tests/age_admission.rs, the service with [age] and a relay: the 401 and its challenges, tokens at 16 and 18 admitted and their grants' age read by the relay, one of 13 refused below_threshold, one spent twice token_replayed, one for another origin token_wrong_challenge, one that does not read token_malformed, a publisher challenged too, the relay serving the viewer at 16 the audio and refusing it the video the publisher rates 18, and the receipt read and checked by wai-rs. A room with co-performance: its policy, the audience-input power and the budgets on its grants, and two viewers' votes in a window the clock opens, commits and selects, verified as co-performance §9 verifies a room. A watch room against a relay on loopback: its source served and named by its policy, viewers admitted by a proof for the request they make (a proof for another target, or presented again, refused), their controls and statements carried and a control in the past refused, the clock's skew statements of each window, each viewer's leave once silent, and the room the log carries verified as co-watch §11 verifies it, every viewer in sync. A remote desktop room (tests/remote_room.rs, with the host agent and headless viewer of joule-moq-remote): the host reaches the service over https:// and the relay over wss:// through TLS fronts, enters by an invitation, and a second key presenting it is refused, two viewers make their keys and get viewers' grants, the host hands control to one by a grant exchange it proves its key for (the grant with no proof, a proof by another key, and a proven request by a principal that is not the host, each refused), her click under the floor is applied and the viewer's move refused input_not_permitted, her typing goes sealed to the host, is injected as typed, and neither a viewer following her events nor the session the service serves to a viewer holds a trace of it, her text in the clear refused input_unsealed, control and the floor pass to the second, a give by a controller that does not hold the floor and a release that crosses the host's take are each stated and change nothing (the clock, the host and the verifier hold the same floor, and neither author is cut), a record out of its chain's order is cut and its author removed by the clock and by the host, the session's records are refused with no grant (401) and with another room's (403) and read with a viewer's, a controller's and the host's grant and proof, and the session verified by wai-rs as the clock serves it and as the host holds it, at the commitment level and at the opened level under the host's opening key; a viewer flooding past a bound of 24 records of its own, cut there and removed by the clock and by the host while the host and a controller go on and the session verifies at both levels; a session the clock ends at a bound of 40 records, every principal removed, the host last, the store within the bound, the session whole and verified, and a new room for the next host; and unit tests of src/remote.rs: the grants' attributes checked against the descriptor and read by the relay's reader, an exchange chained to the grant it replaces on a tick, invitations, the configuration's rules, and the grant in effect from the clock's lifecycle.

A conversation (tests/messaging_room.rs), its members keying through real MLS groups and sealing with joule-moq's secure objects: three members message; one goes offline, the service restarts from its history store and the log is as it was, a fourth joins and a member other than the lowest commits; the one offline catches up, opening every message of both epochs; a thread, reactions, an edit and a retraction verify, the retracted message stated retracted; acknowledgements taken and refused; a member removed opens nothing sealed after its removal, is served nothing past it (not_a_member), and the service takes nothing more from it; every record of the log verifies offline, and the store holds no plaintext. And wai-rs's sealing of a message object and joule-moq's secure objects open what the other seals. A call (tests/call_room.rs) through a relay: placed, an invitation with a bad signature and one to a principal not invited refused, the callee's inbox read and verified, the call accepted, both parties publishing audio and video and each receiving the other's, the clock's join and publish for each; then a call among three in which one declines and the other is missed, signed by the clock and in its inbox, and a late accept refused; each call verified as live-messaging §10 verifies it.

Licence

Apache-2.0.