Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions doc/bin/relay/cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -289,3 +289,13 @@ filters with `origin::Consumer::local()`.

The `/nodes` [internal endpoint](/bin/relay/http#get-nodes) lists the peers
this relay dialed and holds a session with.

### Epoch identity and failover

Upgraded Lite peers carry publisher epochs as announcement and request metadata.
A relay can resume a subscription through another route only when its requested
epoch matches. Plain-path subscriptions with no epoch remain pinned and end
when their serving route disappears, including GOAWAY reconnects. The client
must resubscribe. Legacy Lite and moq-transport links carry no epoch; they keep
plain paths and cannot establish cross-route content identity. See
[Publisher epochs](/concept/moq-lite#publisher-epochs) for cache compatibility.
61 changes: 42 additions & 19 deletions doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,9 +97,9 @@ always a prefix, on every wire version and on moq-transport alike; a service
that serves only some of the paths beneath its prefix refuses the rest as they
are requested. Each route carries the chain of relay identities it passed
through, which is how forwarding loops are caught, and a cost, which is how a
subscriber picks among several routes to the same broadcast. A path names one
broadcast whoever publishes it, so a subscription moves between routes without
a seam; a publisher must not reuse a path for different content. A hop of 0 is
subscriber picks among routes to the same broadcast. A subscription with a known
epoch can resume through routes attesting that epoch; an unidentified subscription
stays on its first serving route. A publisher must not reuse an identity for different content. A hop of 0 is
the anonymous mark and travels the chain unchanged; when it is the first hop, a
relay puts a random ID, fresh per connection, in front of it. A route that passed through an
anonymous hop at any depth ranks below every fully identified route, whatever
Expand Down Expand Up @@ -136,22 +136,45 @@ without waiting, since it has no FIN to acknowledge.

### Publisher epochs

An application can identify each publisher instance with a shared `Epoch` from
`moq-net` or `@moq/net`. It is a lowercase hyphenated UUIDv7, ordered newest
last, with its wall-clock creation time available as `Epoch::time()` in Rust
or `Epoch.time(epoch)` in TypeScript. Minting is explicit; publishing does not
add an epoch automatically.

`Path::join_epoch(Some(&epoch))` and `Path.joinEpoch(name, epoch)` append an
`@<uuidv7>` segment. `Path::split_epoch()` and `Path.splitEpoch(path)` return
the name and optional epoch. Only the final segment and canonical UUIDv7 text
count: `@alice`, bare UUIDs, uppercase UUIDs, and other UUID versions remain
ordinary path segments. Existing path normalization still applies.

The segment travels as part of the ordinary broadcast path on every supported
wire version. Pattern grants still match the full path: `room/**` covers an
epoch-qualified instance, while `room/camera` is an exact name. Epochs do not
hide a broadcast; a leading `.` in a name segment still does.
A broadcast identity is its path plus an optional publisher epoch. An epoch is
an immutable lowercase UUIDv7. Creating a local broadcast through Origin mints
one automatically; an explicit epoch lets replicas declare the same content.
Every track, group and frame position within an identity must remain immutable.
`Epoch::time()` and `Epoch.time()` expose the UUID's creation time; route selection
does not rank publishers by that clock.

Rust accepts `broadcast::Id::from("room/camera").with_epoch(epoch)` for publication
and requests. JavaScript accepts `{ path: Path.from("room/camera"), epoch }` when
creating a broadcast, and exposes `broadcast.epoch` on consumers. Announcements
carry `route.epoch`. The path stays `room/camera`: authentication, wildcard grants,
relative references, and hidden-name rules are unchanged. There is no special
`@epoch` path syntax or implicit bare-to-epoch binding.

Lite peers negotiate the Epoch SETUP parameter (0x6, value 1). When both support
it, announcements and TRACK, SUBSCRIBE and FETCH requests carry an optional
trailing epoch. A request with an epoch can only use a matching route; it never
falls back to a different instance. Replacing an announced epoch sends END then
START at the same path. Repricing the same epoch preserves the announcement.

Without an epoch, a Rust subscription pins its first serving route, including
when that route has a known epoch. It ends when that route disappears, including
a cluster reconnect after GOAWAY. It never shares a front with an explicit-epoch
request. Clients follow announcement changes by requesting a fresh broadcast and
resetting their catalog and decoders. JavaScript's `request.active` delivers a
new broadcast handle when its selected source changes; it does not splice frames.
Native clients must select an announced epoch explicitly to retain seamless failover.

Lite peers without the capability, pre-05 Lite, and moq-transport receive the same
plain paths and no epoch metadata. An incoming route from such a peer has unknown
identity, even if its name happens to resemble a UUID. Relays never invent an
epoch for it or resume it through a different route. Known identity can survive
between upgraded relays even when a downstream peer cannot represent it.

This preserves legacy discovery and subscriptions, but does not invalidate caches
in third-party moq-transport relays. Those deployments still need immutable wire
names and object positions across publisher restarts. Applications that require
end-to-end generation identity must use an epoch-aware path through the network
or arrange unique names themselves.

### Hidden broadcasts

Expand Down
6 changes: 3 additions & 3 deletions doc/lib/js/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ description: The pub/sub layer in TypeScript

The TypeScript twin of [`moq-net`](/lib/rs/moq-net): connections, origins,
broadcasts, tracks, groups, and frames, negotiating moq-lite or moq-transport
at setup. `Epoch` provides the shared publisher identity, and `Path.splitEpoch`
and `Path.joinEpoch` carry it in the broadcast path; see
[publisher epochs](/concept/moq-lite#publisher-epochs).
at setup. `Epoch` identifies a publisher instance separately from its path.
Origin mints it on local broadcast creation; received broadcasts expose it as
`broadcast.epoch`. See [Publisher epochs](/concept/moq-lite#publisher-epochs).

```ts
import * as Moq from "@moq/net";
Expand Down
8 changes: 7 additions & 1 deletion doc/lib/rs/moq-net.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,17 @@ prioritization on top of QUIC. It negotiates [moq-lite](/concept/moq-lite) or
IETF moq-transport at setup and presents one API either way. Media is a layer
above ([hang](/lib/rs/hang)); relays and CDNs implement only this.

A local broadcast gets a fresh epoch by default. Use
`broadcast::Id::from(path).with_epoch(epoch)` to publish replicas or request a
specific announced instance. Plain-path requests remain pinned to their first
serving route; only explicit epochs permit seamless route failover. See
[Publisher epochs](/concept/moq-lite#publisher-epochs).

## What it gives you

- **Origins** scope what a session can see, and merge duplicate subscriptions so a broadcast is pulled upstream once no matter how many local readers.
- **Broadcasts** are created unannounced and invisible to everyone, then announced as an exact route, or served below a prefix with `dynamic`. A consumer of the same origin sees exactly what a peer sees. Discovery accepts pattern unions; events carry the advertised prefix and captures for a complete match.
- **Epochs** identify publisher instances with a canonical UUIDv7 and explicit path helpers; see [publisher epochs](/concept/moq-lite#publisher-epochs).
- **Epochs** identify publisher instances with a canonical UUIDv7 carried as announcement and request metadata; see [publisher epochs](/concept/moq-lite#publisher-epochs).
- **Patterns** (`Pattern`, `Patterns`) are re-exported from [`moq-pattern`](https://docs.rs/moq-pattern). Literal `Path` stays a coordinate.
- **Tracks** carry groups with a priority, an optional publisher retention window (`Info::max_age`), and a timescale. Subscribers set their own priority and max age and can change them live.
- **Groups** are written frame by frame and delivered on independent streams. Old groups are cached for fetch-by-sequence; stale groups are skipped per the subscriber's budget.
Expand Down
24 changes: 12 additions & 12 deletions drafts/draft-lcurley-moq-e2ee.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ informative:

This document specifies moq-e2ee-00, a versioned profile for end-to-end encryption of MoQ application payloads.
Authorized publishers and subscribers share a 32-byte broadcast secret out of band.
Each publisher instance mints an epoch and publishes under an opaque broadcast path ending in it.
Each publisher instance mints an epoch and publishes at an opaque broadcast path with that epoch as identity metadata.
HKDF-SHA-256 derives opaque physical track names and per-track AES-128-GCM keys from the secret and the epoch; grouped frames and datagrams use separate key domains.
Media frames and datagrams carry only ciphertext plus a 16-byte tag.
The profile binds object identity through derivation and the nonce, not an on-wire header.
Expand Down Expand Up @@ -69,7 +69,7 @@ It differs where the models diverge:

- One 32-byte broadcast secret authorizes every track. Per-track keys are derived, not supplied.
- The Key ID is part of the out-of-band credential. No per-frame header or immutable property carries it.
- The salt is not derived from the key. The publisher instance's epoch is an input to every derivation and the last segment of the broadcast path ({{epoch}}), so a restarted publisher derives new keys instead of needing a new Key ID.
- The salt is not derived from the key. The publisher instance's epoch is an input to every derivation and the broadcast's identity metadata ({{epoch}}), so a restarted publisher derives new keys instead of needing a new Key ID.
- The nonce is the identity counter itself, not a salt XOR. The derived key is already unique per credential, epoch, physical name, and domain.
- The payload is ciphertext concatenated with the 16-byte tag, with no inner length prefix, encrypted properties, or padding.
- moq-lite frame indices are implied by position in the group ({{moql}} Section "Frame"), not an on-wire object ID. This profile still uses that index as the 32-bit nonce half, because it is the only canonical end-to-end frame identity on both moq-lite and MoQ Transport.
Expand Down Expand Up @@ -132,13 +132,13 @@ Each instance of a broadcast MUST mint an epoch that no other instance under the
Two instances MUST NOT share an epoch: they would derive the same keys and collide on nonces.
Its leading 48-bit timestamp makes epochs sort by creation time and its random bits make collisions negligible.

A protected broadcast is published at `<opaque>/@<epoch>`, where `<opaque>` is the 22-character base64url segment derived from the credential and the application's semantic broadcast name according to {{derive}}, and `<epoch>` is the UUID text.
The `@` marker is part of the path segment only; the HKDF `bytes(epoch)` input remains the UUID text without `@`.
The opaque derivation does not include the epoch, so every instance of the same semantic broadcast shares a discovery prefix.
The path carries no format or protection marker; for example, the semantic name `meeting.hang` appears only as an input to the opaque derivation.
A plaintext consumer that opens the protected broadcast fails because it cannot find the plaintext catalog it expects, not because of a path naming rule.
Subscribers discover instances by the `<opaque>/` prefix and select the greatest epoch, where greatest is newest.
A subscriber that already knows the full path parses the epoch from its last segment after removing `@`.
A protected broadcast is published at `<opaque>`, the 22-character base64url segment derived from the credential and the application's semantic broadcast name according to {{derive}}.
The publisher conveys its epoch using negotiated MoQ Lite epoch metadata, or through the application's authenticated channel when the transport cannot represent it.
The HKDF `bytes(epoch)` input is the canonical UUID text.
The opaque derivation does not include the epoch, so every instance of the same semantic broadcast shares a discovery path.
The path carries no format or protection marker; the semantic name `meeting.hang` appears only as an input to the opaque derivation.
A subscriber MUST bind the selected epoch to every track request where the transport supports it, and MUST create a new generation when the epoch changes.
Legacy intermediaries that cache solely by wire names and positions require application-assigned immutable names; epoch metadata cannot invalidate their caches.

The epoch and the path are not secret and are not authenticated.
A relay that presents a wrong epoch causes authentication failure; a relay that withholds a newer instance denies service.
Expand Down Expand Up @@ -335,7 +335,7 @@ Relays, caches, recorders, and control planes are untrusted for content.
Authorized endpoints that hold the broadcast secret are trusted.
Sender authenticity against another endpoint that also holds the secret is not a goal of `moq-e2ee-00`.

A relay can still observe the outer broadcast path including the opaque segment and epoch, opaque physical names, group and frame structure, timestamps, sizes, and traffic patterns.
A relay can still observe the outer opaque broadcast path and any conveyed epoch metadata, opaque physical names, group and frame structure, timestamps, sizes, and traffic patterns.
Padding and metadata-flow confidentiality are out of scope.

The opaque segment hides the application's semantic broadcast name from a relay only while the application does not publish or otherwise expose the same name in plaintext.
Expand Down Expand Up @@ -364,8 +364,8 @@ This document requests no registrations.
## draft-lcurley-moq-e2ee-00
{:numbered="false"}

- Require canonical UUIDv7 epochs and carry them in `@<epoch>` path segments, leaving HKDF UUID inputs unchanged.
- Initial `moq-e2ee-00` profile: out-of-band credential, opaque broadcast path with a publisher-minted epoch as its last segment, HKDF physical names and keys, AES-128-GCM payloads, identity bounds, typed failures, and shared primitive vectors.
- Require canonical UUIDv7 epochs and convey them as identity metadata or through the application channel, leaving HKDF UUID inputs unchanged.
- Initial `moq-e2ee-00` profile: out-of-band credential, opaque broadcast path with a publisher-minted epoch, HKDF physical names and keys, AES-128-GCM payloads, identity bounds, typed failures, and shared primitive vectors.


# Acknowledgments
Expand Down
Loading
Loading