diff --git a/.oss-scanner/Dockerfile b/.oss-scanner/Dockerfile index b16764819e2..87281d83048 100644 --- a/.oss-scanner/Dockerfile +++ b/.oss-scanner/Dockerfile @@ -22,7 +22,7 @@ RUN rustup show active-toolchain || rustup toolchain install \ && curl -LsSf "https://get.nexte.st/$NEXTEST_VERSION/$nextest" | tar zxf - -C "$CARGO_HOME/bin" \ && cargo nextest --version -ARG CRATES="kio hang moq-auth moq-e2ee moq-hls moq-ice moq-json moq-loc moq-msf moq-mux moq-net moq-pattern moq-quic moq-relay moq-rtc moq-rtmp moq-rtsp moq-sock moq-srt moq-stats moq-tokio moq-uring moq-cli" +ARG CRATES="kio hang moq-auth moq-crypto moq-hls moq-ice moq-json moq-loc moq-msf moq-mux moq-net moq-pattern moq-quic moq-relay moq-rtc moq-rtmp moq-rtsp moq-sock moq-srt moq-stats moq-tokio moq-uring moq-cli" # Path specs, because the lockfile also has published copies of some workspace crates. # io-uring compiles the relay's io_uring QUIC workers (`--runtime-io-uring`), which the default features leave out. diff --git a/.oss-scanner/threat_model.md b/.oss-scanner/threat_model.md index 3e5c46bcceb..033fd571837 100644 --- a/.oss-scanner/threat_model.md +++ b/.oss-scanner/threat_model.md @@ -25,7 +25,7 @@ The relay is deployed on the public internet as shared infrastructure: one proce - **Cache integrity.** The relay caches and forwards groups by broadcast, track, and group. A publisher must not be able to overwrite or inject into a broadcast it was not granted, and a subscriber must never receive one tenant's data under another tenant's name. - **Cluster trust.** Peer relays authenticate with tokens or mTLS and get broader rights than clients. A relay dials only configured or discovered peers, never a URL learned from an announcement. LAN discovery over mDNS (`[cluster.lan]`) is open to anyone on the network unless `secret` is set, which is documented; with `secret` set, an unkeyed host must not be able to join. - **Amplification and reflection.** QUIC's anti-amplification limit and address validation, the opt-in public STUN responder (`rs/moq-relay/src/stun.rs`), and ICE in the WebRTC gateway all answer unauthenticated UDP. A response larger than the request toward a spoofed source is a finding. -- **End-to-end encryption.** `moq-e2ee` encrypts groups, datagrams, and track names so a relay cannot read them. A flaw in its construction (nonce reuse, a key or name leaking to the relay, a forgeable group) is in scope. +- **End-to-end encryption and signing.** `moq-crypto` encrypts groups, datagrams, and track names so a relay cannot read them, and signs frames so a relay cannot forge them. A flaw in either construction (nonce reuse, a key or name leaking to the relay, a forgeable group or signature) is in scope. ## Components that matter most / least @@ -35,7 +35,7 @@ Most important, in this order: 2. Authorization: a session publishing, subscribing, or seeing announcements outside its grant, or reaching another root (tenant) through path tricks, revalidation, mounts, or cluster links. 3. `rs/moq-mux` and `rs/hang`: container, codec, and catalog parsing of publisher-controlled bytes. 4. The ingest gateways: `rs/moq-rtmp`, `rs/moq-rtsp`, `rs/moq-srt`, `rs/moq-rtc`, `rs/moq-ice`, `rs/moq-hls`. -5. `rs/moq-e2ee`, `rs/moq-cli`, `rs/moq-json`, `rs/moq-stats`, `rs/kio`. +5. `rs/moq-crypto`, `rs/moq-cli`, `rs/moq-json`, `rs/moq-stats`, `rs/kio`. `unsafe` is rare and worth reading closely where it appears: `rs/moq-quic`, `rs/moq-net/src/model`, `rs/moq-net/src/util/cell.rs`, `rs/moq-net/src/transport.rs`, and `rs/moq-relay/src/uring.rs`. diff --git a/Cargo.lock b/Cargo.lock index 155cdfa41c7..d55007c9cf4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4692,17 +4692,20 @@ dependencies = [ ] [[package]] -name = "moq-e2ee" +name = "moq-crypto" version = "0.0.11" dependencies = [ + "aws-lc-rs", "base64 0.23.1", "bench-harness", "bytes", + "data-encoding", "hex", "kio", "moq-net", "rind", "serde_json", + "tempfile", "thiserror 2.0.21", "tokio", "uuid", @@ -4710,6 +4713,13 @@ dependencies = [ "zeroize", ] +[[package]] +name = "moq-e2ee" +version = "0.0.11" +dependencies = [ + "workspace-hack", +] + [[package]] name = "moq-ffi" version = "0.4.12" @@ -5198,25 +5208,6 @@ dependencies = [ "workspace-hack", ] -[[package]] -name = "moq-sign" -version = "0.0.1" -dependencies = [ - "aws-lc-rs", - "bench-harness", - "bytes", - "data-encoding", - "hex", - "kio", - "moq-net", - "serde_json", - "tempfile", - "thiserror 2.0.21", - "tokio", - "workspace-hack", - "zeroize", -] - [[package]] name = "moq-sock" version = "0.2.0" diff --git a/Cargo.toml b/Cargo.toml index 284ae42569e..589c40b2216 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -15,7 +15,7 @@ default-members = [ "rs/moq-audio", "rs/moq-bench", "rs/moq-cli", - "rs/moq-e2ee", + "rs/moq-crypto", # "rs/moq-ffi", # requires Python/maturin # "rs/moq-gst", # requires GStreamer "rs/moq-hls", @@ -36,7 +36,6 @@ default-members = [ "rs/moq-rtmp", "rs/moq-rtsp", "rs/moq-shaper", - "rs/moq-sign", "rs/moq-sock", "rs/moq-srt", "rs/moq-stats", diff --git a/bun.lock b/bun.lock index fc9233c400c..a0247cc4e94 100644 --- a/bun.lock +++ b/bun.lock @@ -161,8 +161,8 @@ "typescript": "7.0.2", }, }, - "js/e2ee": { - "name": "@moq/e2ee", + "js/crypto": { + "name": "@moq/crypto", "version": "0.0.0", "dependencies": { "@moq/net": "workspace:^", @@ -362,18 +362,6 @@ "vite": "^8.3.5", }, }, - "js/sign": { - "name": "@moq/sign", - "version": "0.0.0", - "dependencies": { - "@moq/net": "workspace:^", - }, - "devDependencies": { - "@moq/clock": "workspace:^", - "@types/bun": "^1.4.4", - "typescript": "7.0.2", - }, - }, "js/signals": { "name": "@moq/signals", "version": "0.2.5", @@ -861,7 +849,7 @@ "@moq/drain-test": ["@moq/drain-test@workspace:test/drain"], - "@moq/e2ee": ["@moq/e2ee@workspace:js/e2ee"], + "@moq/crypto": ["@moq/crypto@workspace:js/crypto"], "@moq/hang": ["@moq/hang@workspace:js/hang"], @@ -895,8 +883,6 @@ "@moq/room": ["@moq/room@workspace:js/room"], - "@moq/sign": ["@moq/sign@workspace:js/sign"], - "@moq/signals": ["@moq/signals@workspace:js/signals"], "@moq/ui": ["@moq/ui@workspace:js/ui"], diff --git a/doc/concept/hang.md b/doc/concept/hang.md index 547dc5d9b54..c60c0366b59 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -237,7 +237,7 @@ under one credential, whether for a replica or a later run: two instances on one epoch derive the same keys from the same group sequences and repeat AES-GCM nonces. The broadcast path is an opaque name derived from the credential and a semantic name such as `foo.hang`; it carries -no format marker. `moq-e2ee` is the Rust implementation. Relays need no +no format marker. `moq-crypto` is the Rust implementation. Relays need no configuration to carry it. ## Your own format diff --git a/doc/lib/js/index.md b/doc/lib/js/index.md index 79b7f0aa322..5134987f200 100644 --- a/doc/lib/js/index.md +++ b/doc/lib/js/index.md @@ -31,8 +31,7 @@ small examples. The [API reference](/lib/js/api/) covers every package; source l | [@moq/clock](/lib/js/clock) | Logical monotonic time, wall time, and deterministic timers. | | [@moq/signals](/lib/js/signals) | The reactive primitives every package exposes its state through. | | [@moq/json](/lib/js/json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. | -| [@moq/e2ee](https://github.com/moq-dev/moq/tree/main/js/e2ee) | End-to-end encryption of groups, datagrams, and track names, scoped to a publisher run's epoch. Workspace-only until the browser components use it. | -| [@moq/sign](https://github.com/moq-dev/moq/tree/main/js/sign) | Per-frame Ed25519 signatures, so relays forward content they cannot forge, retime, or relocate. Workspace-only until the mesh uses it. | +| [@moq/crypto](https://github.com/moq-dev/moq/tree/main/js/crypto) | End-to-end encryption of groups, datagrams, and track names, scoped to a publisher run's epoch, and per-frame Ed25519 signatures, so relays forward content they cannot read, forge, retime, or relocate. Workspace-only until the browser components or the mesh use it. | | [@moq/loc](/lib/js/api/loc), [@moq/msf](/lib/js/api/msf) | The IETF LOC container and MSF catalog. | | [@moq/boy](/lib/js/api/boy) | The [MoQ Boy](/bin/demo) player element. | diff --git a/doc/lib/rs/index.md b/doc/lib/rs/index.md index d3988ae292b..84141192e1d 100644 --- a/doc/lib/rs/index.md +++ b/doc/lib/rs/index.md @@ -35,8 +35,7 @@ see [Applications](/bin/). [Examples](/setup/examples) links runnable consumers; | [moq-auth](/lib/rs/moq-auth) | Relay authorization: JWT signing and verification, and the auth server contract. | | [moq-room](/lib/rs/moq-room) | Workspace-only native rooms; use the published JS room API for applications. | | [moq-json](/lib/rs/moq-json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. | -| [moq-e2ee](https://github.com/moq-dev/moq/tree/main/rs/moq-e2ee) | Workspace-only end-to-end encryption of groups, datagrams, and track names, scoped to a publisher run's epoch. | -| [moq-sign](https://github.com/moq-dev/moq/tree/main/rs/moq-sign) | Workspace-only per-frame Ed25519 signatures, so relays forward content they cannot forge, retime, or relocate. | +| [moq-crypto](https://github.com/moq-dev/moq/tree/main/rs/moq-crypto) | Workspace-only end-to-end encryption of groups, datagrams, and track names, scoped to a publisher run's epoch, and per-frame Ed25519 signatures, so relays forward content they cannot read, forge, retime, or relocate. | | [moq-loc](https://docs.rs/moq-loc), [moq-msf](https://docs.rs/moq-msf) | The IETF LOC container and MSF catalog. | | [moq-stats](https://docs.rs/moq-stats) | Publish and consume relay traffic counters as tracks. | | [kio](/lib/rs/kio) | The async primitives everything polls through, and one clock for time and timers on tokio and a deterministic test simulator. | diff --git a/doc/setup/repository.md b/doc/setup/repository.md index 25484f05a86..63294c31374 100644 --- a/doc/setup/repository.md +++ b/doc/setup/repository.md @@ -31,8 +31,8 @@ wrap the Rust core. [Layers](/lib/layers) maps the binding namespaces. | CLI commands and protocol gateways | [`rs/moq-cli`](https://github.com/moq-dev/moq/tree/main/rs/moq-cli), then the corresponding `rs/moq-{rtmp,srt,rtc,rtsp,hls}` crate | [Applications](/bin/) | | Language bindings | [`rs/moq-ffi`](https://github.com/moq-dev/moq/tree/main/rs/moq-ffi), [`rs/moq-c`](https://github.com/moq-dev/moq/tree/main/rs/moq-c), then `py/`, `swift/`, `kt/`, `go/`, `dart/`, or `cpp/moq/` | [Binding layers](/lib/layers) | | Rooms, chat, and application data | [`rs/moq-room`](https://github.com/moq-dev/moq/tree/main/rs/moq-room), [`js/room`](https://github.com/moq-dev/moq/tree/main/js/room), `rs/moq-json`, `js/json` | [Rooms](/lib/js/room), [JSON tracks](/lib/js/json) | -| End-to-end encryption | [`rs/moq-e2ee`](https://github.com/moq-dev/moq/tree/main/rs/moq-e2ee), [`js/e2ee`](https://github.com/moq-dev/moq/tree/main/js/e2ee) | [Media encryption](/concept/hang), [E2EE draft](/draft/moq-e2ee) | -| Signed content | [`rs/moq-sign`](https://github.com/moq-dev/moq/tree/main/rs/moq-sign), [`js/sign`](https://github.com/moq-dev/moq/tree/main/js/sign) | [Signing draft](/draft/moq-sign) | +| End-to-end encryption | [`rs/moq-crypto`](https://github.com/moq-dev/moq/tree/main/rs/moq-crypto), [`js/crypto`](https://github.com/moq-dev/moq/tree/main/js/crypto) | [Media encryption](/concept/hang), [E2EE draft](/draft/moq-e2ee) | +| Signed content | [`rs/moq-crypto`](https://github.com/moq-dev/moq/tree/main/rs/moq-crypto), [`js/crypto`](https://github.com/moq-dev/moq/tree/main/js/crypto) | [Signing draft](/draft/moq-sign) | | Async primitives and deterministic time | [`rs/kio`](https://github.com/moq-dev/moq/tree/main/rs/kio), [`js/clock`](https://github.com/moq-dev/moq/tree/main/js/clock) | [Rust conventions](/lib/rs/#conventions), [clock](/lib/js/clock) | ## Find the surrounding work diff --git a/doc/setup/upgrade.md b/doc/setup/upgrade.md index aae3f512612..2a9eeb73060 100644 --- a/doc/setup/upgrade.md +++ b/doc/setup/upgrade.md @@ -27,7 +27,7 @@ replaces it. - **Binaries:** [moq-relay](https://github.com/moq-dev/moq/blob/main/rs/moq-relay/MIGRATE.md), [moq-cli (`moq`)](https://github.com/moq-dev/moq/blob/main/rs/moq-cli/MIGRATE.md), [moq-gst](https://github.com/moq-dev/moq/blob/main/rs/moq-gst/MIGRATE.md), [obs-moq](https://github.com/moq-dev/moq/blob/main/cpp/obs/MIGRATE.md) - **Bindings:** [moq-ffi (UniFFI)](https://github.com/moq-dev/moq/blob/main/rs/moq-ffi/MIGRATE.md), [moq-c (C)](https://github.com/moq-dev/moq/blob/main/rs/moq-c/MIGRATE.md), [Python](https://github.com/moq-dev/moq/blob/main/py/moq-rs/MIGRATE.md), [Go](https://github.com/moq-dev/moq/blob/main/go/wrapper/MIGRATE.md), [Swift](https://github.com/moq-dev/moq/blob/main/swift/MIGRATE.md), [Kotlin](https://github.com/moq-dev/moq/blob/main/kt/moq/MIGRATE.md), [Dart](https://github.com/moq-dev/moq/blob/main/dart/moq/MIGRATE.md), [C++](https://github.com/moq-dev/moq/blob/main/cpp/moq/MIGRATE.md) -- **Rust:** [hang](https://github.com/moq-dev/moq/blob/main/rs/hang/MIGRATE.md), [kio](https://github.com/moq-dev/moq/blob/main/rs/kio/MIGRATE.md), [kio-macros](https://github.com/moq-dev/moq/blob/main/rs/kio/macros/MIGRATE.md), [moq-archive](https://github.com/moq-dev/moq/blob/main/rs/moq-archive/MIGRATE.md), [moq-audio](https://github.com/moq-dev/moq/blob/main/rs/moq-audio/MIGRATE.md), [moq-auth](https://github.com/moq-dev/moq/blob/main/rs/moq-auth/MIGRATE.md), [moq-boy](https://github.com/moq-dev/moq/blob/main/rs/moq-boy/MIGRATE.md), [moq-e2ee](https://github.com/moq-dev/moq/blob/main/rs/moq-e2ee/MIGRATE.md), [moq-hls](https://github.com/moq-dev/moq/blob/main/rs/moq-hls/MIGRATE.md), [moq-ice](https://github.com/moq-dev/moq/blob/main/rs/moq-ice/MIGRATE.md), [moq-json](https://github.com/moq-dev/moq/blob/main/rs/moq-json/MIGRATE.md), [moq-loc](https://github.com/moq-dev/moq/blob/main/rs/moq-loc/MIGRATE.md), [moq-msf](https://github.com/moq-dev/moq/blob/main/rs/moq-msf/MIGRATE.md), [moq-mux](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/MIGRATE.md), [moq-net](https://github.com/moq-dev/moq/blob/main/rs/moq-net/MIGRATE.md), [moq-nvenc](https://github.com/moq-dev/moq/blob/main/rs/moq-nvenc/MIGRATE.md), [moq-pattern](https://github.com/moq-dev/moq/blob/main/rs/moq-pattern/MIGRATE.md), [moq-quic](https://github.com/moq-dev/moq/blob/main/rs/moq-quic/MIGRATE.md), [moq-room](https://github.com/moq-dev/moq/blob/main/rs/moq-room/MIGRATE.md), [moq-rtc](https://github.com/moq-dev/moq/blob/main/rs/moq-rtc/MIGRATE.md), [moq-rtmp](https://github.com/moq-dev/moq/blob/main/rs/moq-rtmp/MIGRATE.md), [moq-sock](https://github.com/moq-dev/moq/blob/main/rs/moq-sock/MIGRATE.md), [moq-srt](https://github.com/moq-dev/moq/blob/main/rs/moq-srt/MIGRATE.md), [moq-stats](https://github.com/moq-dev/moq/blob/main/rs/moq-stats/MIGRATE.md), [moq-tokio](https://github.com/moq-dev/moq/blob/main/rs/moq-tokio/MIGRATE.md), [moq-transcode](https://github.com/moq-dev/moq/blob/main/rs/moq-transcode/MIGRATE.md), [moq-uring](https://github.com/moq-dev/moq/blob/main/rs/moq-uring/MIGRATE.md), [moq-v4l](https://github.com/moq-dev/moq/blob/main/rs/moq-v4l/MIGRATE.md), [moq-video](https://github.com/moq-dev/moq/blob/main/rs/moq-video/MIGRATE.md), [qmux](https://github.com/moq-dev/moq/blob/main/rs/qmux/MIGRATE.md) +- **Rust:** [hang](https://github.com/moq-dev/moq/blob/main/rs/hang/MIGRATE.md), [kio](https://github.com/moq-dev/moq/blob/main/rs/kio/MIGRATE.md), [kio-macros](https://github.com/moq-dev/moq/blob/main/rs/kio/macros/MIGRATE.md), [moq-archive](https://github.com/moq-dev/moq/blob/main/rs/moq-archive/MIGRATE.md), [moq-audio](https://github.com/moq-dev/moq/blob/main/rs/moq-audio/MIGRATE.md), [moq-auth](https://github.com/moq-dev/moq/blob/main/rs/moq-auth/MIGRATE.md), [moq-boy](https://github.com/moq-dev/moq/blob/main/rs/moq-boy/MIGRATE.md), [moq-crypto](https://github.com/moq-dev/moq/blob/main/rs/moq-crypto/MIGRATE.md), [moq-hls](https://github.com/moq-dev/moq/blob/main/rs/moq-hls/MIGRATE.md), [moq-ice](https://github.com/moq-dev/moq/blob/main/rs/moq-ice/MIGRATE.md), [moq-json](https://github.com/moq-dev/moq/blob/main/rs/moq-json/MIGRATE.md), [moq-loc](https://github.com/moq-dev/moq/blob/main/rs/moq-loc/MIGRATE.md), [moq-msf](https://github.com/moq-dev/moq/blob/main/rs/moq-msf/MIGRATE.md), [moq-mux](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/MIGRATE.md), [moq-net](https://github.com/moq-dev/moq/blob/main/rs/moq-net/MIGRATE.md), [moq-nvenc](https://github.com/moq-dev/moq/blob/main/rs/moq-nvenc/MIGRATE.md), [moq-pattern](https://github.com/moq-dev/moq/blob/main/rs/moq-pattern/MIGRATE.md), [moq-quic](https://github.com/moq-dev/moq/blob/main/rs/moq-quic/MIGRATE.md), [moq-room](https://github.com/moq-dev/moq/blob/main/rs/moq-room/MIGRATE.md), [moq-rtc](https://github.com/moq-dev/moq/blob/main/rs/moq-rtc/MIGRATE.md), [moq-rtmp](https://github.com/moq-dev/moq/blob/main/rs/moq-rtmp/MIGRATE.md), [moq-sock](https://github.com/moq-dev/moq/blob/main/rs/moq-sock/MIGRATE.md), [moq-srt](https://github.com/moq-dev/moq/blob/main/rs/moq-srt/MIGRATE.md), [moq-stats](https://github.com/moq-dev/moq/blob/main/rs/moq-stats/MIGRATE.md), [moq-tokio](https://github.com/moq-dev/moq/blob/main/rs/moq-tokio/MIGRATE.md), [moq-transcode](https://github.com/moq-dev/moq/blob/main/rs/moq-transcode/MIGRATE.md), [moq-uring](https://github.com/moq-dev/moq/blob/main/rs/moq-uring/MIGRATE.md), [moq-v4l](https://github.com/moq-dev/moq/blob/main/rs/moq-v4l/MIGRATE.md), [moq-video](https://github.com/moq-dev/moq/blob/main/rs/moq-video/MIGRATE.md), [qmux](https://github.com/moq-dev/moq/blob/main/rs/qmux/MIGRATE.md) - **JavaScript:** [`@moq/auth`](https://github.com/moq-dev/moq/blob/main/js/auth/MIGRATE.md), [`@moq/boy`](https://github.com/moq-dev/moq/blob/main/js/moq-boy/MIGRATE.md), [`@moq/clock`](https://github.com/moq-dev/moq/blob/main/js/clock/MIGRATE.md), [`@moq/hang`](https://github.com/moq-dev/moq/blob/main/js/hang/MIGRATE.md), [`@moq/json`](https://github.com/moq-dev/moq/blob/main/js/json/MIGRATE.md), [`@moq/loc`](https://github.com/moq-dev/moq/blob/main/js/loc/MIGRATE.md), [`@moq/msf`](https://github.com/moq-dev/moq/blob/main/js/msf/MIGRATE.md), [`@moq/net`](https://github.com/moq-dev/moq/blob/main/js/net/MIGRATE.md), [`@moq/p2p`](https://github.com/moq-dev/moq/blob/main/js/p2p/MIGRATE.md), [`@moq/pattern`](https://github.com/moq-dev/moq/blob/main/js/pattern/MIGRATE.md), [`@moq/publish`](https://github.com/moq-dev/moq/blob/main/js/publish/MIGRATE.md), [`@moq/qmux`](https://github.com/moq-dev/moq/blob/main/js/qmux/MIGRATE.md), [`@moq/room`](https://github.com/moq-dev/moq/blob/main/js/room/MIGRATE.md), [`@moq/signals`](https://github.com/moq-dev/moq/blob/main/js/signals/MIGRATE.md), [`@moq/ui`](https://github.com/moq-dev/moq/blob/main/js/ui/MIGRATE.md), [`@moq/video`](https://github.com/moq-dev/moq/blob/main/js/video/MIGRATE.md), [`@moq/watch`](https://github.com/moq-dev/moq/blob/main/js/watch/MIGRATE.md) ## Unreleased diff --git a/js/e2ee/README.md b/js/crypto/README.md similarity index 59% rename from js/e2ee/README.md rename to js/crypto/README.md index a66dcd143c6..29316633daf 100644 --- a/js/e2ee/README.md +++ b/js/crypto/README.md @@ -2,16 +2,73 @@ Media over QUIC

-# @moq/e2ee +# @moq/crypto + +Content signing and end-to-end encryption for [Media over QUIC](https://moq.dev), mirroring the +Rust `moq-crypto` crate. `Sign` signs every frame so relays cannot forge it, and `E2ee` encrypts +groups, datagrams, and track names so relays cannot read them. Both wrap `@moq/net` and check each +timestamp with `@moq/net`'s `Track.rescale(info, timestamp)` before signing or encrypting, so a frame either accepts is +one `@moq/net` accepts. + +## Signing + +Per-frame Ed25519 signatures for [Media over QUIC](https://moq.dev) broadcasts. Profile +`moq-sign-00` from [draft-lcurley-moq-sign](https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/), +interoperable with Rust's `moq_crypto::sign`. + +Relays forward and cache signed frames; they cannot forge, retime, or relocate them. Signatures +authenticate content, not liveness: a relay that recorded an instance can replay it whole. + +### Shape + +An endpoint's `SecretKey` signs; its `PublicKey` is the endpoint ID, displayed as 52 z-base-32 +characters (a DNS label). `SecretKey.generate()` keeps the private half a nonextractable `CryptoKey`. + +`Broadcast.Producer` wraps the `@moq/net` broadcast, mints a fresh instance, and signs each frame +over the application path, instance, track, group, frame index, and timestamp (rounded down to the +track's timescale, as the wire carries it). Announce the broadcast with that instance on its route: + +```ts +import { Sign } from "@moq/crypto"; +import { Path } from "@moq/net"; + +const { Broadcast, SecretKey } = Sign; + +const key = await SecretKey.generate(); +const path = Path.from(`mesh/${key.public}/agent`); +const publication = origin.createBroadcast(path); +const signed = new Broadcast.Producer(publication.broadcast, key, path); +const messages = signed.createTrack("messages"); +publication.announce({ instance: signed.instance }); + +const group = messages.appendGroup(); +await group.writeFrame(undefined, payload); +group.finish(); +``` + +A subscriber wraps the broadcast an origin resolved in a `Broadcast.Consumer` with the key it +expects and the same application path; it takes the instance from the route. A frame reaches the +application only after it verifies. A forged or relocated frame ends its group with `Failure` +code `signature`, and the track keeps delivering other groups. Every hop must carry the instance and +timestamps unchanged, which means moq-lite-07. A group's end is not signed: a relay may drop a +group's tail, as MoQ already allows. + +### Processing + +WebCrypto Ed25519 is asynchronous, so writes return promises. Each track producer runs one serial +pump: one signature in flight, net writes in call order, so a frame's index always matches its +transport position. Await each write for backpressure. + +## Encryption End-to-end encryption for [Media over QUIC](https://moq.dev) groups, datagrams, and track names. Profile `moq-e2ee-00` from [draft-lcurley-moq-e2ee](https://datatracker.ietf.org/doc/draft-lcurley-moq-e2ee/), -interoperable with the Rust [`moq-e2ee`](https://crates.io/crates/moq-e2ee) crate. +interoperable with Rust's `moq_crypto::e2ee`. Relays forward ciphertext. Content keys never enter `@moq/net`. -## Shape +### Shape The application distributes a `Credential { context, kid, secret }` over its own authenticated channel. `credential.produce()` mints a fresh epoch and returns a @@ -27,9 +84,11 @@ learns only its length rounded up to 16 bytes. `createTrack` resolves once the n every write is checked against it. `close()` ends the wrapped broadcast. ```ts -import { Broadcast, Credential } from "@moq/e2ee"; +import { E2ee } from "@moq/crypto"; import { Time } from "@moq/net"; +const { Broadcast, Credential } = E2ee; + const credential = new Credential({ context, kid, secret }); const generation = credential.produce(); const publication = origin.createBroadcast(await credential.path("meeting.hang")); @@ -57,7 +116,7 @@ A cloned process image (a `fork` without `exec`, a restored VM snapshot or check producing generation copied to another process) is a new instance too: each copy must call `produce()` itself, since copies of one generation reuse its nonces. -## Processing +### Processing WebCrypto AES-GCM is asynchronous, so writes return promises. Each track producer and consumer runs one serial pump: one AEAD call in flight. Producer net writes land in call diff --git a/js/e2ee/bench/pump.ts b/js/crypto/bench/pump.ts similarity index 97% rename from js/e2ee/bench/pump.ts rename to js/crypto/bench/pump.ts index 02d5974af98..63f65ebef74 100644 --- a/js/e2ee/bench/pump.ts +++ b/js/crypto/bench/pump.ts @@ -2,7 +2,7 @@ // Bun's WebCrypto stands in for the browser's, so compare runs on the same runtime. import { Milli } from "@moq/clock"; import { Broadcast, Time } from "@moq/net"; -import { Credential } from "../src/index.ts"; +import { Credential } from "../src/e2ee/index.ts"; const GROUP_FRAMES = 64; const BUDGET = 32 * 1024 * 1024; diff --git a/js/e2ee/bench/tsconfig.json b/js/crypto/bench/tsconfig.json similarity index 100% rename from js/e2ee/bench/tsconfig.json rename to js/crypto/bench/tsconfig.json diff --git a/js/e2ee/package.json b/js/crypto/package.json similarity index 83% rename from js/e2ee/package.json rename to js/crypto/package.json index e01a4ca6f46..7b226921fca 100644 --- a/js/e2ee/package.json +++ b/js/crypto/package.json @@ -1,13 +1,13 @@ { - "name": "@moq/e2ee", + "name": "@moq/crypto", "type": "module", "version": "0.0.0", - "description": "End-to-end encryption for MoQ groups, datagrams, and track names.", + "description": "Content signing and end-to-end encryption for MoQ broadcasts.", "license": "(MIT OR Apache-2.0)", "repository": { "type": "git", "url": "git+https://github.com/moq-dev/moq.git", - "directory": "js/e2ee" + "directory": "js/crypto" }, "private": true, "sideEffects": false, diff --git a/js/e2ee/src/broadcast.ts b/js/crypto/src/e2ee/broadcast.ts similarity index 100% rename from js/e2ee/src/broadcast.ts rename to js/crypto/src/e2ee/broadcast.ts diff --git a/js/e2ee/src/credential.ts b/js/crypto/src/e2ee/credential.ts similarity index 100% rename from js/e2ee/src/credential.ts rename to js/crypto/src/e2ee/credential.ts diff --git a/js/e2ee/src/datagram.ts b/js/crypto/src/e2ee/datagram.ts similarity index 100% rename from js/e2ee/src/datagram.ts rename to js/crypto/src/e2ee/datagram.ts diff --git a/js/e2ee/src/derive.ts b/js/crypto/src/e2ee/derive.ts similarity index 100% rename from js/e2ee/src/derive.ts rename to js/crypto/src/e2ee/derive.ts diff --git a/js/e2ee/src/e2ee.test.ts b/js/crypto/src/e2ee/e2ee.test.ts similarity index 99% rename from js/e2ee/src/e2ee.test.ts rename to js/crypto/src/e2ee/e2ee.test.ts index dbb8d7c3505..01db429f0cc 100644 --- a/js/e2ee/src/e2ee.test.ts +++ b/js/crypto/src/e2ee/e2ee.test.ts @@ -1,6 +1,7 @@ import { expect, spyOn, test } from "bun:test"; import { Milli } from "@moq/clock"; import { Broadcast, Error as NetError, Group as NetGroup, Track as NetTrack, StreamCode, Time } from "@moq/net"; +import { Pump } from "../pump.ts"; import * as Protected from "./broadcast.ts"; import { Credential } from "./credential.ts"; import type * as Datagram from "./datagram.ts"; @@ -20,7 +21,6 @@ import { MAX_PLAINTEXT_BYTES, MAX_U53, } from "./limits.ts"; -import { Pump } from "./pump.ts"; import { Terminal } from "./terminal.ts"; import type * as Track from "./track.ts"; @@ -866,10 +866,10 @@ test("a timestamp out of range at the track's timescale spends nothing", async ( const producer = await generation.produce(net, "video"); const huge = new Time.Timestamp(Number.MAX_SAFE_INTEGER, Time.Timescale.MILLI); - await expect(producer.insertDatagram(0n, huge, text("x"))).rejects.toThrow(RangeError); + await expect(producer.insertDatagram(0n, huge, text("x"))).rejects.toBeInstanceOf(NetError.TimestampMismatch); await producer.insertDatagram(0n, ms(1), text("datagram")); const group = producer.createGroup(1n); - await expect(group.writeFrame(huge, text("x"))).rejects.toThrow(RangeError); + await expect(group.writeFrame(huge, text("x"))).rejects.toBeInstanceOf(NetError.TimestampMismatch); await group.writeFrame(ms(2), text("frame")); group.finish(); expect(datagramText(await consumer.recvDatagram())).toBe("datagram"); diff --git a/js/e2ee/src/epoch.test.ts b/js/crypto/src/e2ee/epoch.test.ts similarity index 78% rename from js/e2ee/src/epoch.test.ts rename to js/crypto/src/e2ee/epoch.test.ts index af1119e64d8..f70c75df017 100644 --- a/js/e2ee/src/epoch.test.ts +++ b/js/crypto/src/e2ee/epoch.test.ts @@ -7,8 +7,8 @@ test("mint parses as canonical and orders successive epochs", () => { expect(Epoch.mint() > epoch).toBe(true); }); -// Shared with rs/moq-e2ee's `epoch_vectors`, so both parse and order alike. -const vectors = (await Bun.file(new URL("../../../rs/moq-e2ee/src/epoch.json", import.meta.url)).json()) as { +// Shared with moq-crypto's `epoch_vectors`, so both parse and order alike. +const vectors = (await Bun.file(new URL("../../../../rs/moq-crypto/src/e2ee/epoch.json", import.meta.url)).json()) as { valid: string[]; invalid: string[]; ordered: string[]; diff --git a/js/e2ee/src/epoch.ts b/js/crypto/src/e2ee/epoch.ts similarity index 95% rename from js/e2ee/src/epoch.ts rename to js/crypto/src/e2ee/epoch.ts index 642cfadaa2e..cffee22f9dd 100644 --- a/js/e2ee/src/epoch.ts +++ b/js/crypto/src/e2ee/epoch.ts @@ -3,7 +3,7 @@ * instance announces it as its route's instance, so a subscriber reads it back from the * broadcast it resolved ({@link of}). A wire that carries no instance hands the subscriber one * its relay minted, which is no epoch: the application supplies the epoch over its own - * authenticated channel then. Mirrors `Epoch` in rs/moq-e2ee. + * authenticated channel then. Mirrors `moq_crypto::e2ee::Epoch`. * * @module */ diff --git a/js/e2ee/src/failure.ts b/js/crypto/src/e2ee/failure.ts similarity index 100% rename from js/e2ee/src/failure.ts rename to js/crypto/src/e2ee/failure.ts diff --git a/js/e2ee/src/generation-internal.ts b/js/crypto/src/e2ee/generation-internal.ts similarity index 98% rename from js/e2ee/src/generation-internal.ts rename to js/crypto/src/e2ee/generation-internal.ts index aecbc2e8d5e..aad83278fc0 100644 --- a/js/e2ee/src/generation-internal.ts +++ b/js/crypto/src/e2ee/generation-internal.ts @@ -157,6 +157,6 @@ export class Producer { this.#claims.delete(semantic); throw err; } - return Track.Producer.make(track, info.timescale ?? undefined, keys(this.credential, this.epoch, semantic)); + return Track.Producer.make(track, info, keys(this.credential, this.epoch, semantic)); } } diff --git a/js/e2ee/src/generation.ts b/js/crypto/src/e2ee/generation.ts similarity index 100% rename from js/e2ee/src/generation.ts rename to js/crypto/src/e2ee/generation.ts diff --git a/js/e2ee/src/group.ts b/js/crypto/src/e2ee/group.ts similarity index 95% rename from js/e2ee/src/group.ts rename to js/crypto/src/e2ee/group.ts index e06d6ca41d1..f88b4f61150 100644 --- a/js/e2ee/src/group.ts +++ b/js/crypto/src/e2ee/group.ts @@ -3,9 +3,9 @@ * * @module */ -import type { Group as NetGroup, Time } from "@moq/net"; +import { type Group as NetGroup, Track as NetTrack, type Time } from "@moq/net"; import { Failure } from "./failure.ts"; -import { checkTimestamp, type Reader, type Writer } from "./internal.ts"; +import type { Reader, Writer } from "./internal.ts"; import { MAX_GROUPED_PAYLOAD, TAG_LEN } from "./limits.ts"; /** A decrypted grouped frame. */ @@ -61,9 +61,9 @@ export class Producer { if (this.#closed || this.#writer.closed) throw this.#aborted ?? this.#writer.aborted ?? new Error("group is closed"); if (plaintext.byteLength + TAG_LEN > MAX_GROUPED_PAYLOAD) throw new Failure("oversize"); - checkTimestamp(this.#writer, timestamp); + const at = NetTrack.rescale(this.#writer.track, timestamp); const owned = plaintext.slice(); - return this.#writer.pump.run(() => this.#write(timestamp, owned)); + return this.#writer.pump.run(() => this.#write(at, owned)); } async #write(timestamp: Time.Timestamp | undefined, plaintext: Uint8Array): Promise { diff --git a/js/e2ee/src/index.ts b/js/crypto/src/e2ee/index.ts similarity index 98% rename from js/e2ee/src/index.ts rename to js/crypto/src/e2ee/index.ts index de4c4b29293..d58d299accc 100644 --- a/js/e2ee/src/index.ts +++ b/js/crypto/src/e2ee/index.ts @@ -3,7 +3,7 @@ * * Implements profile `moq-e2ee-00` from * [draft-lcurley-moq-e2ee](https://datatracker.ietf.org/doc/draft-lcurley-moq-e2ee/). Relays - * forward ciphertext; content keys never enter `@moq/net`. Mirrors the Rust `moq-e2ee` crate. + * forward ciphertext; content keys never enter `@moq/net`. Mirrors `moq_crypto::e2ee` in Rust. * * A {@link Credential} is what the application distributes out of band. Each publisher instance * calls {@link Credential.produce} to mint a {@link Generation.Producer} and wraps its `@moq/net` diff --git a/js/e2ee/src/internal.ts b/js/crypto/src/e2ee/internal.ts similarity index 51% rename from js/e2ee/src/internal.ts rename to js/crypto/src/e2ee/internal.ts index 732940b2e60..18104a494cd 100644 --- a/js/e2ee/src/internal.ts +++ b/js/crypto/src/e2ee/internal.ts @@ -1,7 +1,7 @@ // Package-private state the public modules share without exporting it. -import { Error as NetError, type Time } from "@moq/net"; +import type { Track as NetTrack } from "@moq/net"; +import type { Pump } from "../pump.ts"; import type { TrackKey } from "./key.ts"; -import type { Pump } from "./pump.ts"; import type { Terminal } from "./terminal.ts"; /** A track's grouped-frame and datagram keys. */ @@ -14,8 +14,8 @@ export interface Keys { export interface Writer { pump: Pump; key: TrackKey; - // The net track's committed timescale, or undefined when untimed. - timescale?: Time.Timescale; + // The net track's committed info, which every timestamp is rescaled to before encryption. + track: Pick; // Set by release or abort: no new writes, including on existing groups. closed: boolean; aborted?: Error; @@ -28,12 +28,3 @@ export interface Reader { key: TrackKey; terminal: Terminal; } - -/** Refuse a timestamp the track could not encode: wrong presence, or out of range at its timescale. */ -export function checkTimestamp(writer: Writer, timestamp: Time.Timestamp | undefined): void { - if ((writer.timescale !== undefined) !== (timestamp !== undefined)) { - throw new NetError.TimestampMismatch(); - } - // Throws a RangeError for a conversion that would only fail at encode, after the identity is spent. - if (timestamp && writer.timescale !== undefined) timestamp.as(writer.timescale); -} diff --git a/js/e2ee/src/key.ts b/js/crypto/src/e2ee/key.ts similarity index 100% rename from js/e2ee/src/key.ts rename to js/crypto/src/e2ee/key.ts diff --git a/js/e2ee/src/limits.ts b/js/crypto/src/e2ee/limits.ts similarity index 100% rename from js/e2ee/src/limits.ts rename to js/crypto/src/e2ee/limits.ts diff --git a/js/e2ee/src/name.ts b/js/crypto/src/e2ee/name.ts similarity index 100% rename from js/e2ee/src/name.ts rename to js/crypto/src/e2ee/name.ts diff --git a/js/e2ee/src/secret.ts b/js/crypto/src/e2ee/secret.ts similarity index 100% rename from js/e2ee/src/secret.ts rename to js/crypto/src/e2ee/secret.ts diff --git a/js/e2ee/src/terminal.ts b/js/crypto/src/e2ee/terminal.ts similarity index 100% rename from js/e2ee/src/terminal.ts rename to js/crypto/src/e2ee/terminal.ts diff --git a/js/e2ee/src/track.ts b/js/crypto/src/e2ee/track.ts similarity index 92% rename from js/e2ee/src/track.ts rename to js/crypto/src/e2ee/track.ts index 6686f15a310..4823b804e0a 100644 --- a/js/e2ee/src/track.ts +++ b/js/crypto/src/e2ee/track.ts @@ -3,15 +3,15 @@ * * @module */ -import type { Group as NetGroup, Track as NetTrack, Time } from "@moq/net"; +import { type Group as NetGroup, Track as NetTrack, type Time } from "@moq/net"; +import { Pump } from "../pump.ts"; import type { Event } from "./datagram.ts"; import { checkGroup } from "./derive.ts"; import { Failure } from "./failure.ts"; import * as Group from "./group.ts"; -import { checkTimestamp, type Keys, type Reader, type Writer } from "./internal.ts"; +import type { Keys, Reader, Writer } from "./internal.ts"; import type { TrackKey } from "./key.ts"; import { MAX_DATAGRAM_PAYLOAD } from "./limits.ts"; -import { Pump } from "./pump.ts"; import { Terminal } from "./terminal.ts"; import { DatagramWindow } from "./window.ts"; @@ -32,16 +32,16 @@ export class Producer { #next = 0n; #finished = false; - private constructor(inner: NetTrack.Producer, timescale: Time.Timescale | undefined, keys: Keys) { + private constructor(inner: NetTrack.Producer, info: NetTrack.Info, keys: Keys) { this.#inner = inner; this.name = inner.name; - this.#writer = { pump: new Pump(), key: keys.group, timescale, closed: false }; + this.#writer = { pump: new Pump(), key: keys.group, track: info, closed: false }; this.#datagramKey = keys.datagram; } /** @internal */ - static make(inner: NetTrack.Producer, timescale: Time.Timescale | undefined, keys: Keys): Producer { - return new Producer(inner, timescale, keys); + static make(inner: NetTrack.Producer, info: NetTrack.Info, keys: Keys): Producer { + return new Producer(inner, info, keys); } /** The track's final outcome, once its declared end is reached or it aborts. */ @@ -90,7 +90,7 @@ export class Producer { ): Promise { this.#writable(); this.#reserve(sequence); - checkTimestamp(this.#writer, timestamp); + const at = NetTrack.rescale(this.#writer.track, timestamp); const iv = this.#datagramKey.admitSeal(sequence, 0, plaintext.byteLength, MAX_DATAGRAM_PAYLOAD); this.#next = sequence + 1n; const owned = plaintext.slice(); @@ -98,7 +98,7 @@ export class Producer { if (this.#writer.aborted) throw this.#writer.aborted; const payload = await this.#datagramKey.encrypt(iv, owned); if (this.#writer.aborted) throw this.#writer.aborted; - this.#inner.insertDatagram(sequence, timestamp, payload); + this.#inner.insertDatagram(sequence, at, payload); }); } diff --git a/js/e2ee/src/transport.test.ts b/js/crypto/src/e2ee/transport.test.ts similarity index 98% rename from js/e2ee/src/transport.test.ts rename to js/crypto/src/e2ee/transport.test.ts index c569ce88905..93393471fcd 100644 --- a/js/e2ee/src/transport.test.ts +++ b/js/crypto/src/e2ee/transport.test.ts @@ -3,7 +3,7 @@ import { expect, test } from "bun:test"; import { Milli } from "@moq/clock"; import { type Broadcast, Connection, Origin, type Path, Time } from "@moq/net"; // The in-memory WebTransport pair @moq/net tests with; not part of its published surface. -import { createMockTransportPair } from "../../net/src/mock.ts"; +import { createMockTransportPair } from "../../../net/src/mock.ts"; import * as Protected from "./broadcast.ts"; import { Credential } from "./credential.ts"; import * as Epoch from "./epoch.ts"; diff --git a/js/e2ee/src/vectors.test.ts b/js/crypto/src/e2ee/vectors.test.ts similarity index 98% rename from js/e2ee/src/vectors.test.ts rename to js/crypto/src/e2ee/vectors.test.ts index 36b9aa0b37c..fdbb4412c28 100644 --- a/js/e2ee/src/vectors.test.ts +++ b/js/crypto/src/e2ee/vectors.test.ts @@ -11,7 +11,7 @@ import { expand } from "./secret.ts"; type Row = Record; -const vectors = (await Bun.file(new URL("../../../drafts/moq-e2ee-00.json", import.meta.url)).json()) as { +const vectors = (await Bun.file(new URL("../../../../drafts/moq-e2ee-00.json", import.meta.url)).json()) as { profile: string; constants: Row; generation: Row; diff --git a/js/e2ee/src/window.ts b/js/crypto/src/e2ee/window.ts similarity index 100% rename from js/e2ee/src/window.ts rename to js/crypto/src/e2ee/window.ts diff --git a/js/crypto/src/index.ts b/js/crypto/src/index.ts new file mode 100644 index 00000000000..fd455ace1b8 --- /dev/null +++ b/js/crypto/src/index.ts @@ -0,0 +1,14 @@ +/** + * Content signing and end-to-end encryption for MoQ. + * + * {@link Sign} signs every grouped frame so a relay can proxy and cache a broadcast without + * forging it. {@link E2ee} encrypts groups, datagrams, and track names so a relay forwards + * ciphertext it cannot read. Mirrors the Rust `moq-crypto` crate's `sign` and `e2ee` modules. + * + * @module + */ + +/** End-to-end encryption of groups, datagrams, and track names. */ +export * as E2ee from "./e2ee/index.ts"; +/** Per-frame Ed25519 signatures. */ +export * as Sign from "./sign/index.ts"; diff --git a/js/e2ee/src/pump.ts b/js/crypto/src/pump.ts similarity index 100% rename from js/e2ee/src/pump.ts rename to js/crypto/src/pump.ts diff --git a/js/sign/src/broadcast.ts b/js/crypto/src/sign/broadcast.ts similarity index 95% rename from js/sign/src/broadcast.ts rename to js/crypto/src/sign/broadcast.ts index 0577e158dab..07ff923b78b 100644 --- a/js/sign/src/broadcast.ts +++ b/js/crypto/src/sign/broadcast.ts @@ -42,12 +42,14 @@ export class Producer { /** Create a track whose frames are signed; throws the net error if the broadcast already holds it. */ createTrack(name: string, info: Partial = {}): Track.Producer { const inner = this.#inner.createTrack(name, info); - const timescale = info.timescale ?? undefined; let sequences = this.#sequences.get(name); if (!sequences) { sequences = { next: 0n }; this.#sequences.set(name, sequences); } + // Snapshot the timescale, as the net track does, so a caller reusing its options cannot + // change the scale frames are signed at. + const timescale = { timescale: info.timescale }; return Track.Producer.make(inner, this.#key, new Scope(this.#path, this.instance, name), sequences, timescale); } diff --git a/js/sign/src/failure.ts b/js/crypto/src/sign/failure.ts similarity index 100% rename from js/sign/src/failure.ts rename to js/crypto/src/sign/failure.ts diff --git a/js/sign/src/group.ts b/js/crypto/src/sign/group.ts similarity index 88% rename from js/sign/src/group.ts rename to js/crypto/src/sign/group.ts index 6daf4ccff35..8f35ea70ab5 100644 --- a/js/sign/src/group.ts +++ b/js/crypto/src/sign/group.ts @@ -3,10 +3,10 @@ * * @module */ -import { type Group as NetGroup, Time } from "@moq/net"; +import { type Group as NetGroup, Track as NetTrack, type Time } from "@moq/net"; +import type { Pump } from "../pump.ts"; import { Failure } from "./failure.ts"; import type { PublicKey, SecretKey } from "./key.ts"; -import type { Pump } from "./pump.ts"; import type { Scope } from "./scope.ts"; /** A grouped frame whose signature verified. */ @@ -23,8 +23,8 @@ export interface Writer { pump: Pump; key: SecretKey; scope: Scope; - // The track's timescale, which every timestamp is signed at; undefined when untimed. - timescale?: Time.Timescale; + // The track's info, which every frame's timestamp is rescaled to before it is signed. + track: Pick; // Set by release or abort: no new writes, including on existing groups. closed: boolean; aborted?: Error; @@ -70,12 +70,8 @@ export class Producer { async writeFrame(timestamp: Time.Timestamp | undefined, payload: Uint8Array): Promise { if (this.#closed || this.#writer.closed) throw this.#writer.aborted ?? new Error("group is closed"); const owned = payload.slice(); - // Signed at the track's timescale, rounded as the wire rounds it, and written that way so a - // local reader sees the signed value too. A frame whose timedness disagrees with the track - // is left for the net write to refuse. - const scale = this.#writer.timescale; - const at = - timestamp && scale !== undefined ? new Time.Timestamp(Math.round(timestamp.as(scale)), scale) : timestamp; + // Signed at the track's timescale, and written that way so a local reader sees the signed value too. + const at = NetTrack.rescale(this.#writer.track, timestamp); return this.#writer.pump.run(async () => { this.#check(); const body = await this.#writer.scope.sign(this.#writer.key, this.sequence, this.#next, at, owned); diff --git a/js/sign/src/index.ts b/js/crypto/src/sign/index.ts similarity index 97% rename from js/sign/src/index.ts rename to js/crypto/src/sign/index.ts index af0700c6bea..b840f107158 100644 --- a/js/sign/src/index.ts +++ b/js/crypto/src/sign/index.ts @@ -8,7 +8,7 @@ * frame to the application only after it verifies against the {@link PublicKey} it expects, so a * relay can proxy and cache without forging, retiming, relocating, or splicing content. Signatures * authenticate content, not liveness: a relay that recorded an instance can replay it whole under - * its instance. Mirrors the Rust `moq-sign` crate. + * its instance. Mirrors `moq_crypto::sign` in Rust. * * ```ts * const key = await SecretKey.generate(); diff --git a/js/sign/src/key.ts b/js/crypto/src/sign/key.ts similarity index 100% rename from js/sign/src/key.ts rename to js/crypto/src/sign/key.ts diff --git a/js/sign/src/scope.ts b/js/crypto/src/sign/scope.ts similarity index 100% rename from js/sign/src/scope.ts rename to js/crypto/src/sign/scope.ts diff --git a/js/sign/src/sign.test.ts b/js/crypto/src/sign/sign.test.ts similarity index 89% rename from js/sign/src/sign.test.ts rename to js/crypto/src/sign/sign.test.ts index d3e764b9952..d2f1d01da46 100644 --- a/js/sign/src/sign.test.ts +++ b/js/crypto/src/sign/sign.test.ts @@ -1,9 +1,9 @@ // Signed tracks over a real moq-lite session: the subscriber delivers only what verifies. import { expect, test } from "bun:test"; import { Milli } from "@moq/clock"; -import { type Broadcast, Connection, Origin, Path, Time } from "@moq/net"; +import { type Broadcast, Connection, Error as NetError, Origin, Path, Time } from "@moq/net"; // The in-memory WebTransport pair @moq/net tests with; not part of its published surface. -import { createMockTransportPair } from "../../net/src/mock.ts"; +import { createMockTransportPair } from "../../../net/src/mock.ts"; import * as Signed from "./broadcast.ts"; import { Failure } from "./failure.ts"; import type * as Group from "./group.ts"; @@ -55,7 +55,8 @@ async function publish(key: SecretKey, path: Path.Valid) { /** A signed track over a net track the test can also write forged frames to. */ track(name: string) { const raw = publication.broadcast.createTrack(name); - return { signed: Track.Producer.make(raw, key, new Scope(path, signed.instance, name), { next: 0n }), raw }; + const scope = new Scope(path, signed.instance, name); + return { signed: Track.Producer.make(raw, key, scope, { next: 0n }, {}), raw }; }, async consume(expected: PublicKey): Promise { return new Signed.Consumer(await active(net.subscriber, path), expected, path); @@ -72,11 +73,14 @@ test("frames roundtrip signed, timestamps included", async () => { const key = await SecretKey.generate(); const path = Path.from(`mesh/${key.public}/agent`); const published = await publish(key, path); - const video = published.signed.createTrack("video", { timescale: Time.Timescale.MILLI }); + const options: { timescale: Time.Timescale } = { timescale: Time.Timescale.MILLI }; + const video = published.signed.createTrack("video", options); + // The track committed its scale; reusing the options object changes nothing it signs. + options.timescale = Time.Timescale.MICRO; const group = video.appendGroup(); await group.writeFrame(Time.Timestamp.fromMillis(1), encoder.encode("keyframe")); - // Signed at the track's scale, rounded as the wire rounds it. + // Signed at the track's scale, rounded down as the wire rounds it. await group.writeFrame(Time.Timestamp.fromMicros(2_400), new Uint8Array()); const consumer = await published.consume(key.public); @@ -91,6 +95,10 @@ test("frames roundtrip signed, timestamps included", async () => { expect(second?.timestamp?.value).toBe(2); expect(second?.timestamp?.scale).toBe(Time.Timescale.MILLI); + // An untimed frame on a timed track is refused before it is signed, so it spends no index. + await expect(group.writeFrame(undefined, encoder.encode("untimed"))).rejects.toBeInstanceOf( + NetError.TimestampMismatch, + ); await group.writeFrame(Time.Timestamp.fromMillis(3), encoder.encode("late")); group.finish(); expect(await payload(received)).toBe("late"); diff --git a/js/sign/src/track.ts b/js/crypto/src/sign/track.ts similarity index 91% rename from js/sign/src/track.ts rename to js/crypto/src/sign/track.ts index a726314ea5d..f469d0c5b0a 100644 --- a/js/sign/src/track.ts +++ b/js/crypto/src/sign/track.ts @@ -3,10 +3,10 @@ * * @module */ -import type { Track as NetTrack, Time } from "@moq/net"; +import type { Track as NetTrack } from "@moq/net"; +import { Pump } from "../pump.ts"; import * as Group from "./group.ts"; import type { PublicKey, SecretKey } from "./key.ts"; -import { Pump } from "./pump.ts"; import type { Scope } from "./scope.ts"; /** The lowest group sequence an instance has not signed on a track, shared with the track's replacements. @internal */ @@ -38,23 +38,23 @@ export class Producer { key: SecretKey, scope: Scope, sequences: Sequences, - timescale?: Time.Timescale, + info: Pick, ) { this.#inner = inner; this.name = inner.name; - this.#writer = { pump: new Pump(), key, scope, timescale, closed: false }; + this.#writer = { pump: new Pump(), key, scope, track: info, closed: false }; this.#sequences = sequences; } - /** Sign `inner`, whose info declared `timescale` (undefined when untimed). @internal */ + /** Sign `inner`, created with `info`. @internal */ static make( inner: NetTrack.Producer, key: SecretKey, scope: Scope, sequences: Sequences, - timescale?: Time.Timescale, + info: Pick, ): Producer { - return new Producer(inner, key, scope, sequences, timescale); + return new Producer(inner, key, scope, sequences, info); } /** The track's final outcome, once its declared end is reached or it aborts. */ diff --git a/js/sign/src/vectors.test.ts b/js/crypto/src/sign/vectors.test.ts similarity index 96% rename from js/sign/src/vectors.test.ts rename to js/crypto/src/sign/vectors.test.ts index 0ce219efe2e..018d098ec6d 100644 --- a/js/sign/src/vectors.test.ts +++ b/js/crypto/src/sign/vectors.test.ts @@ -7,7 +7,7 @@ import { Scope } from "./scope.ts"; type Row = Record; -const vectors = (await Bun.file(new URL("../../../drafts/moq-sign-00.json", import.meta.url)).json()) as { +const vectors = (await Bun.file(new URL("../../../../drafts/moq-sign-00.json", import.meta.url)).json()) as { keys: Row[]; frames: Row[]; negative: Row[]; diff --git a/js/sign/src/zbase32.ts b/js/crypto/src/sign/zbase32.ts similarity index 100% rename from js/sign/src/zbase32.ts rename to js/crypto/src/sign/zbase32.ts diff --git a/js/e2ee/test-dts/constructors.ts b/js/crypto/test-dts/constructors.ts similarity index 55% rename from js/e2ee/test-dts/constructors.ts rename to js/crypto/test-dts/constructors.ts index 6e3d0f5952c..ce6d3acc119 100644 --- a/js/e2ee/test-dts/constructors.ts +++ b/js/crypto/test-dts/constructors.ts @@ -1,16 +1,16 @@ -import { Consumer, Producer } from "../dist/generation-internal.js"; -import { Credential, type Generation } from "../dist/index.js"; +import { Consumer, Producer } from "../dist/e2ee/generation-internal.js"; +import { E2ee } from "../dist/index.js"; // @ts-expect-error A credential binds a consuming generation to an epoch. new Consumer(); // @ts-expect-error A credential mints a producing generation and its epoch. new Producer(); // @ts-expect-error The internal factory is not a package export, including type-only namespaces. -export type Factory = typeof Generation.makeProducer; +export type Factory = typeof E2ee.Generation.makeProducer; -const credential = new Credential({ context: new Uint8Array(), kid: 1, secret: new Uint8Array(32) }); -const producer: Generation.Producer = credential.produce(); -const consumer: Generation.Consumer = credential.consume(producer.epoch); +const credential = new E2ee.Credential({ context: new Uint8Array(), kid: 1, secret: new Uint8Array(32) }); +const producer: E2ee.Generation.Producer = credential.produce(); +const consumer: E2ee.Generation.Consumer = credential.consume(producer.epoch); void consumer.name("test"); // @ts-expect-error Construction stays private even with valid arguments. new Consumer(credential, producer.epoch); diff --git a/js/e2ee/test-dts/tsconfig.json b/js/crypto/test-dts/tsconfig.json similarity index 100% rename from js/e2ee/test-dts/tsconfig.json rename to js/crypto/test-dts/tsconfig.json diff --git a/js/e2ee/tsconfig.build.json b/js/crypto/tsconfig.build.json similarity index 100% rename from js/e2ee/tsconfig.build.json rename to js/crypto/tsconfig.build.json diff --git a/js/e2ee/tsconfig.json b/js/crypto/tsconfig.json similarity index 100% rename from js/e2ee/tsconfig.json rename to js/crypto/tsconfig.json diff --git a/js/justfile b/js/justfile index 3f3a5cacb69..0a08acd26c9 100644 --- a/js/justfile +++ b/js/justfile @@ -189,7 +189,7 @@ p2p-bench: # Sweep E2EE frame size against writes in flight through the WebCrypto pump. e2ee-bench: bun install --frozen-lockfile - bun e2ee/bench/pump.ts + bun crypto/bench/pump.ts # Sweep audio renditions x raw retention through native WebCodecs in Chromium. raw-audio-bench: diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 8dbad0d2958..b13274940bd 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -4,6 +4,16 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A timestamp out of range at the track's timescale is a `TimestampMismatch` ([#7702](https://github.com/moq-dev/moq/pull/7702)) + +A frame or datagram whose timestamp leaves the safe range once converted to the track's timescale is refused at the write with `TimestampMismatch`, as Rust refuses it, rather than with a `RangeError` when it is encoded. +Catch `TimestampMismatch` where you caught that `RangeError`. + +### A timestamp finer than the track's timescale is rounded down ([#7702](https://github.com/moq-dev/moq/pull/7702)) + +A timestamp that is fractional at the track's timescale, such as 1500µs on a millisecond track or a fractional `Timestamp.now()`, now goes out rounded down instead of to the nearest unit: 1500µs is 1 ms, not 2. Rust's `Timestamp::convert` and `track::Info::rescale` already round down, and `Track.rescale` does too. +Write timestamps at the track's own scale where the exact value matters. + ### Group sequences are `bigint` ([#7681](https://github.com/moq-dev/moq/pull/7681)) Every group sequence is a `bigint`, so a group ID past 2^53 decodes, relays, and encodes again instead of being refused: `Group.Producer`/`Consumer.sequence`, `Track.Position.group`, `Track.Bound`, an `absolute` `Track.Anchor`, `Track.Datagram.sequence`, `Track.Demand.wanted`, the `group` of `Ordered.readFrame()`, and the `sequence` that `createGroup`, `insertDatagram`, and `fetchGroup` take and `appendDatagram` returns. diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index e3db0dc361f..b4cbf30c9c5 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -724,6 +724,7 @@ export namespace Track { ranges?: Track.Range[]; } export function infoDefaults(info?: Partial): Track.Info; + export function rescale(info: Pick, timestamp: Time.Timestamp | undefined): Time.Timestamp | undefined; } export namespace Varint { diff --git a/js/net/src/group.ts b/js/net/src/group.ts index f725378a3ed..7bf33c7b158 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -9,7 +9,9 @@ import { FrameTooLarge, ProtocolViolation, StreamCode, StreamError, TimestampMis import { Compression, encodable, stored } from "./flate/group.ts"; import { type Expiry, type GroupRecover, hooks, type ReadGroupFrame, type Replacement } from "./internal.ts"; import { Queue } from "./queue.ts"; +import { rescale } from "./rescale.ts"; import type { Timestamp } from "./time.ts"; +import type { Info as TrackInfo } from "./track.ts"; import { MAX_FRAME_BYTES, SEGMENT_BYTES } from "./util/limits.ts"; import { checkSequence } from "./util/sequence.ts"; @@ -211,9 +213,10 @@ class GroupState { cacheBytes = 0; compressed?: boolean; flate?: Compression; - // Whether the owning track has a timescale, so every frame must carry a timestamp (true) - // or none may (false). Undefined for a group no track has claimed yet, which takes either. - timed?: boolean; + // The owning track's info, which every frame's timestamp must `rescale` to: a timed track's frames + // carry a timestamp its scale holds, an untimed track's carry none. Undefined for a group + // no track has claimed yet, which takes either. + track?: TrackInfo; // The first frame's timestamp, retained after reads. Media time only: an untimed group // never has one, so it says nothing about whether a frame was written. timestamp?: Timestamp; @@ -253,9 +256,9 @@ class Landed implements Frame { } } -// Refuse a frame whose timedness disagrees with the track's. -function checkTimed(timed: boolean | undefined, frame: Frame) { - if (timed !== undefined && timed !== (frame.timestamp !== undefined)) throw new TimestampMismatch(); +// Refuse a frame whose timestamp the track's timeline refuses. +function checkTimed(track: TrackInfo | undefined, frame: Frame) { + if (track) rescale(track, frame.timestamp); } function appendFrame(state: GroupState, frame: Frame) { @@ -393,13 +396,14 @@ export class Producer { state.progress.add(fn); return () => state.progress.delete(fn); }; - hooks.bindGroupTimed = (group, timed) => { + hooks.bindGroupTimed = (group, track) => { const state = group.#state; - if (state.timed === timed) return; + const timed = track.timescale != null; + if (state.track !== undefined && (state.track.timescale != null) === timed) return; // Another track already holds it to the opposite timedness, empty or not. - if (state.timed !== undefined) throw new TimestampMismatch(); - for (const frame of state.frames.peek()) checkTimed(timed, frame); - state.timed = timed; + if (state.track !== undefined) throw new TimestampMismatch(); + for (const frame of state.frames.peek()) checkTimed(track, frame); + state.track = track; }; hooks.admitGroupStart = (group, admit) => { group.#admits ??= []; @@ -603,7 +607,7 @@ export class Producer { if (this.#open) throw new Error("a frame is still being written"); if (this.#state.total.peek() === Number.MAX_SAFE_INTEGER) throw new ProtocolViolation("group frame index exceeds the safe integer range"); - checkTimed(this.#state.timed, frame); + checkTimed(this.#state.track, frame); if (this.#limit !== undefined && this.#state.total.peek() >= this.#limit) { throw new Error(`frame ${this.#state.total.peek()} is past the track's end`); } diff --git a/js/net/src/ietf/object.test.ts b/js/net/src/ietf/object.test.ts index 22ee0d368f5..9150c5fe905 100644 --- a/js/net/src/ietf/object.test.ts +++ b/js/net/src/ietf/object.test.ts @@ -22,7 +22,13 @@ test("a same-scale timestamp is written exactly, up to the largest a Timestamp h test("a timestamp is converted to the track's scale", () => { expect(roundtrip(Timestamp.fromMillis(1234), Timescale.NANO)?.value).toBe(1_234_000_000); - expect(roundtrip(Timestamp.fromMicros(1_500), Timescale.MILLI)?.value).toBe(2); + // Rounded down, as Rust converts it. + expect(roundtrip(Timestamp.fromMicros(1_500), Timescale.MILLI)?.value).toBe(1); + // Exact for an aligned value, where float division gives 4611686020.999999. + expect(roundtrip(new Timestamp(4_611_686_021_000_000, Timescale.NANO), Timescale.MILLI)?.value).toBe(4_611_686_021); + // The same binary value at two scales encodes alike: 116 ms, as Rust converts it. + expect(roundtrip(new Timestamp(0.11699999999999999, Timescale.SECOND), Timescale.MILLI)?.value).toBe(116); + expect(roundtrip(new Timestamp(131730289100587, Timescale(1125899906842624)), Timescale.MILLI)?.value).toBe(116); }); test("a conversion past what a Timestamp holds is refused before anything is written", () => { diff --git a/js/net/src/ietf/object.ts b/js/net/src/ietf/object.ts index 6731b80910c..9630317c62f 100644 --- a/js/net/src/ietf/object.ts +++ b/js/net/src/ietf/object.ts @@ -2,7 +2,7 @@ import { ProtocolViolation, StreamCode, Stream as StreamError } from "../error.t import { decodePayload } from "../payload.ts"; import type { Cursor, Reader } from "../stream.ts"; import { concat, encodeVarint, Writer } from "../stream.ts"; -import { type Timescale, Timestamp } from "../time.ts"; +import { floorAt, type Timescale, Timestamp } from "../time.ts"; import { U64 } from "../util/u64.ts"; import { DEFAULT_WIRE } from "./priority.ts"; import { type IetfVersion, Version } from "./version.ts"; @@ -41,10 +41,10 @@ export function encodeObjectExtensions( // The units come from the track's TIMESCALE property, not from here: repeating the // timescale on every object would cost bytes per frame to restate something fixed for // the track's lifetime. The timestamp is converted into the track's units so the value - // on the wire matches what the track declared. The shared conversion is exact at the same - // scale, and refused before anything is written when the result leaves the range a - // Timestamp, and so the receiver, can hold. - const value = Math.round(timestamp.as(timescale)); + // on the wire matches what the track declared, rounded down exactly as Rust does, and + // refused before anything is written when the result leaves the range a Timestamp, and so + // the receiver, can hold. + const value = floorAt(timestamp, timescale); // The only property, so its type's delta from the previous one is from zero. return concat([encodeVarint(PROP_TIMESTAMP, version), encodeVarint(value, version)]); } diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 0be942d71c1..c99f3aac334 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -617,10 +617,10 @@ export const hooks: { /** Apply a FETCH reader budget without inheriting SUBSCRIBE's zero default. */ fetchBudget: (subscriber: Subscriber, maxDelay: Milli | undefined) => void; /** - * Bind a group to its track's timedness, so a frame whose timestamp disagrees is refused. - * Throws `TimestampMismatch` if a buffered frame already disagrees. + * Bind a group to its track's info, so a frame whose timestamp doesn't `rescale` to the track + * is refused. Throws `TimestampMismatch` if a buffered frame already disagrees. */ - bindGroupTimed: (group: GroupProducer, timed: boolean) => void; + bindGroupTimed: (group: GroupProducer, track: Info) => void; /** Admit a datagram in its stored wire form. */ writeDatagram: (producer: Producer, datagram: Datagram, inflated?: number) => void; /** Bind the group to its immutable track codec. */ diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 0b084e85f15..80394a11a91 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -25,8 +25,9 @@ import type { Consumer as OriginConsumer } from "../origin.ts"; import * as Path from "../path.ts"; import { readSize, sendPayload } from "../payload.ts"; import { Priority, sendOrder } from "../priority.ts"; +import { rescale } from "../rescale.ts"; import { concat, encodeVarint, type Reader, type Stream, type StreamVersion, Writer } from "../stream.ts"; -import { type Timescale, Timestamp } from "../time.ts"; +import { floorAt, type Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { nextChange } from "../util/change.ts"; @@ -100,21 +101,25 @@ interface Stamp { /** The wire timescale TRACK_INFO declared (see `wireTimescale`). */ timescale: Timescale; /** - * Whether each frame's own timestamp goes out. Lite-05/06 cannot encode an untimed track, so - * an untimed one carries its send time instead. + * The timed track whose frames' own timestamps go out, at its timescale, which the wire's + * equals. Lite-05/06 cannot encode an untimed track, so an untimed one carries its send time + * instead. */ - timed: boolean; + timed?: Pick; } -/** How `version` stamps a track with `timescale`, or undefined when it carries none. */ -function stamping(version: Version, timescale: Timescale | undefined): Stamp | undefined { +/** How `version` stamps a track with `info`, or undefined when it carries no timestamps. */ +function stamping(version: Version, info: Pick): Stamp | undefined { + const timescale = info.timescale ?? undefined; const wire = wireTimescale(version, timescale); - return wire === undefined ? undefined : { timescale: wire, timed: timescale !== undefined }; + if (wire === undefined) return undefined; + return timescale === undefined ? { timescale: wire } : { timescale: wire, timed: info }; } /** A frame or datagram's `timestamp` as its raw wire value, or its send time when the track goes out untimed. */ function wireTime(timestamp: Timestamp | undefined, stamp: Stamp): number { - return Math.round(((stamp.timed ? timestamp : undefined) ?? Timestamp.now()).as(stamp.timescale)); + const own = stamp.timed && rescale(stamp.timed, timestamp); + return own ? own.value : floorAt(Timestamp.now(), stamp.timescale); } /** @@ -988,7 +993,7 @@ export class Publisher { // The timescale is an immutable property, so serving MUST use exactly // what TRACK_INFO advertised. It comes from the producer's accept(), so // they always agree. - stamp = stamping(this.version, info.timescale ?? undefined); + stamp = stamping(this.version, info); compress = hasCompression(this.version) && !!info.compress; } else { // Older drafts acknowledge with SUBSCRIBE_OK and stream frames verbatim. @@ -1163,7 +1168,7 @@ export class Publisher { return; } await this.#runFetchGroup(group, stream.writer, { - stamp: stamping(this.version, info.timescale), + stamp: stamping(this.version, info), compress: info.compress, start: msg.startFrame, end: msg.endFrame, diff --git a/js/net/src/rescale.ts b/js/net/src/rescale.ts new file mode 100644 index 00000000000..216eb487733 --- /dev/null +++ b/js/net/src/rescale.ts @@ -0,0 +1,23 @@ +// Kept apart from track.ts so group.ts can import it without a cycle; track.ts re-exports it. +import { TimestampMismatch } from "./error.ts"; +import { floorAt, Timestamp } from "./time.ts"; +import type { Info } from "./track.ts"; + +/** + * `timestamp` at `info`'s {@link Info.timescale}, rounded down, as Rust's `Timestamp::convert` does. + * + * A track is all timed or all untimed, so a frame must match it: a timestamp on an untimed track, + * none on a timed one, or one the scale can't hold throws {@link TimestampMismatch}. A writer that + * changes state before its frame reaches the track, such as signing or encrypting it, rescales + * first so a refused timestamp changes nothing. Mirrors the Rust `track::Info::rescale`. + */ +export function rescale(info: Pick, timestamp: Timestamp | undefined): Timestamp | undefined { + const timescale = info.timescale ?? undefined; + if ((timescale !== undefined) !== (timestamp !== undefined)) throw new TimestampMismatch(); + if (timestamp === undefined || timescale === undefined) return undefined; + try { + return new Timestamp(floorAt(timestamp, timescale), timescale); + } catch (cause) { + throw new TimestampMismatch({ cause }); + } +} diff --git a/js/net/src/time.ts b/js/net/src/time.ts index febc6eac4c8..0cdb6596e7a 100644 --- a/js/net/src/time.ts +++ b/js/net/src/time.ts @@ -49,8 +49,8 @@ function assertTimestampValue(value: number): void { * own scale, so a track can pick its units and conversions can't silently mix them up. * * The value must be finite and in `[0, Number.MAX_SAFE_INTEGER]`. Fractions are allowed - * ({@link Timestamp.now}, scale conversion). Encoding rounds to the nearest integer at the - * track timescale. Integer timestamps are exact through `2^53 - 1` units; this package + * ({@link Timestamp.now}, scale conversion). Encoding rounds down to an integer at the + * track timescale, as the Rust `Timestamp::convert` does. Integer timestamps are exact through `2^53 - 1` units; this package * does not use BigInt for timestamps. {@link Timestamp.as} also refuses a converted * value that leaves that range, so a legal source timestamp cannot become an unencodable * wire timestamp after a scale change. @@ -112,6 +112,26 @@ export class Timestamp { } } +/** + * `timestamp`'s value at `scale`, rounded down exactly, as Rust's integer `Timestamp::convert`. + * + * A double is a dyadic rational, so the conversion runs in BigInt with no rounding before the + * floor: an aligned value keeps it (4611686021000000 ns is 4611686021 ms, where `as` gives + * 4611686020.999999), and one instant gives one result whatever scale it came from. Throws a + * `RangeError` past the safe integer range. + * + * @internal + */ +export function floorAt(timestamp: Timestamp, scale: Timescale): number { + if (timestamp.scale === scale) return Math.floor(timestamp.value); + const [mantissa, exponent] = binary(timestamp.value); + const result = Number((mantissa * BigInt(scale)) / (BigInt(timestamp.scale) << BigInt(-exponent))); + if (!Number.isSafeInteger(result)) { + throw new RangeError(`timestamp ${timestamp.value} at ${timestamp.scale} exceeds the safe range at ${scale}`); + } + return result; +} + // A finite, non-negative `value` exactly as `mantissa * 2^exponent`. Doubling is exact, so // a fraction becomes an integer within its binary digits. function binary(value: number): [bigint, number] { diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 5eb5c49227f..abad37e2ff9 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -9,7 +9,7 @@ import { Version as IetfVersion } from "./ietf/version.ts"; import { hooks } from "./internal.ts"; import { textFrame } from "./mock.ts"; import { Timescale, Timestamp } from "./time.ts"; -import { infoDefaults, Subscription, Producer as TrackProducer } from "./track.ts"; +import { infoDefaults, rescale, Subscription, Producer as TrackProducer } from "./track.ts"; import { unwanted } from "./util/demand.ts"; const enc = new TextEncoder(); @@ -504,6 +504,34 @@ test("refresh must be a u32 ratio", () => { expect(infoDefaults({ refresh: 0 }).refresh).toBe(0); }); +test("rescale matches the track's timeline, rounded down as Rust's convert does", () => { + const timed = { timescale: Timescale.MILLI }; + const rescaled = rescale(timed, Timestamp.fromMicros(2_400)); + expect(rescaled?.value).toBe(2); + expect(rescaled?.scale).toBe(Timescale.MILLI); + // Halfway and fractional values round down too, where Math.round would give 2 and 3. + expect(rescale(timed, Timestamp.fromMicros(1_500))?.value).toBe(1); + expect(rescale(timed, new Timestamp(2.6, Timescale.MILLI))?.value).toBe(2); + expect(rescale(timed, new Timestamp(1_500.7, Timescale.MICRO))?.value).toBe(1); + // An aligned value keeps it exactly, where float division gives 4611686020.999999. + expect(rescale(timed, new Timestamp(4_611_686_021_000_000, Timescale.NANO))?.value).toBe(4_611_686_021); + // One instant, one result, whatever scale it came from: 2.5/3 s and 5/6 s agree exactly. + const fine = { timescale: Timescale(Number.MAX_SAFE_INTEGER) }; + const half = rescale(fine, new Timestamp(2.5, Timescale(3)))?.value; + expect(half).toBe(7_505_999_378_950_825); + expect(rescale(fine, new Timestamp(5, Timescale(6)))?.value).toBe(half); + // The same binary value at two scales floors alike, below 0.117 s: 116 ms, as Rust converts it. + expect(rescale(timed, new Timestamp(0.11699999999999999, Timescale.SECOND))?.value).toBe(116); + expect(rescale(timed, new Timestamp(131730289100587, Timescale(1125899906842624)))?.value).toBe(116); + expect(() => rescale(timed, undefined)).toThrow(TimestampMismatch); + const huge = new Timestamp(Number.MAX_SAFE_INTEGER, Timescale.MILLI); + expect(() => rescale({ timescale: Timescale.NANO }, huge)).toThrow(TimestampMismatch); + + expect(rescale({}, undefined)).toBeUndefined(); + expect(rescale({ timescale: null }, undefined)).toBeUndefined(); + expect(() => rescale({}, Timestamp.fromMillis(1))).toThrow(TimestampMismatch); +}); + test("appendDatagram shares the group sequence counter", () => { const producer = new TrackProducer("test"); const ts = Timestamp.fromMillis(10); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 0a9c1013844..cac4583b0f0 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -42,6 +42,7 @@ import { type TrackRequestOptions, } from "./internal.ts"; import { CACHE_EXPIRY, grace, Ledger } from "./ledger.ts"; +import { rescale } from "./rescale.ts"; import { Timescale, type Timestamp } from "./time.ts"; import { checkSequence, max, min } from "./util/sequence.ts"; import { @@ -179,6 +180,8 @@ export interface Info { unchecked?: boolean; } +export { rescale }; + // Normalize a duration for the wire, which carries it as an unsigned varint. // // Callers derive it from measurements (a jitter estimate scaled off RTT), so a fractional @@ -1090,17 +1093,16 @@ export class Producer { accept(info: Partial = {}): this { if (this.#state.closed.peek() !== undefined) return this; const resolved = infoDefaults(info); - const timed = resolved.timescale != null; // Anything written before accept() must match too. A mismatch closes the track, so // nothing waiting on info() hangs on a half-bound cache. try { for (const { group } of this.#cache) { - hooks.bindGroupTimed(group, timed); + hooks.bindGroupTimed(group, resolved); hooks.bindGroupCompression(group, resolved.compress ?? false); } for (const sink of this.#sinks) { for (const datagram of sink.datagrams.peek()) { - if ((datagram.timestamp !== undefined) !== timed) throw new TimestampMismatch(); + rescale(resolved, datagram.timestamp); } } } catch (err) { @@ -1546,7 +1548,7 @@ export class Producer { #bind(group: GroupProducer): void { const info = this.#state.info.peek(); if (info) { - hooks.bindGroupTimed(group, info.timescale != null); + hooks.bindGroupTimed(group, info); hooks.bindGroupCompression(group, info.compress ?? false); } } @@ -1554,7 +1556,7 @@ export class Producer { // Refuse a datagram whose timedness disagrees with this track's. #checkDatagram(timestamp: Timestamp | undefined): void { const info = this.#state.info.peek(); - if (info && (info.timescale != null) !== (timestamp !== undefined)) throw new TimestampMismatch(); + if (info) rescale(info, timestamp); } // Refuse a write once the track is closed, or at or past its declared end. diff --git a/js/sign/README.md b/js/sign/README.md deleted file mode 100644 index 518de64c645..00000000000 --- a/js/sign/README.md +++ /dev/null @@ -1,50 +0,0 @@ -

- Media over QUIC -

- -# @moq/sign - -Per-frame Ed25519 signatures for [Media over QUIC](https://moq.dev) broadcasts. Profile -`moq-sign-00` from [draft-lcurley-moq-sign](https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/), -interoperable with the Rust `moq-sign` crate. - -Relays forward and cache signed frames; they cannot forge, retime, or relocate them. Signatures -authenticate content, not liveness: a relay that recorded an instance can replay it whole. - -## Shape - -An endpoint's `SecretKey` signs; its `PublicKey` is the endpoint ID, displayed as 52 z-base-32 -characters (a DNS label). `SecretKey.generate()` keeps the private half a nonextractable `CryptoKey`. - -`Broadcast.Producer` wraps the `@moq/net` broadcast, mints a fresh instance, and signs each frame -over the application path, instance, track, group, frame index, and timestamp (rounded to the -track's timescale, as the wire carries it). Announce the broadcast with that instance on its route: - -```ts -import { Broadcast, SecretKey } from "@moq/sign"; -import { Path } from "@moq/net"; - -const key = await SecretKey.generate(); -const path = Path.from(`mesh/${key.public}/agent`); -const publication = origin.createBroadcast(path); -const signed = new Broadcast.Producer(publication.broadcast, key, path); -const messages = signed.createTrack("messages"); -publication.announce({ instance: signed.instance }); - -const group = messages.appendGroup(); -await group.writeFrame(undefined, payload); -group.finish(); -``` - -A subscriber wraps the broadcast an origin resolved in a `Broadcast.Consumer` with the key it -expects and the same application path; it takes the instance from the route. A frame reaches the -application only after it verifies. A forged or relocated frame ends its group with `Failure` -code `signature`, and the track keeps delivering other groups. Every hop must carry the instance and -timestamps unchanged, which means moq-lite-07. A group's end is not signed: a relay may drop a -group's tail, as MoQ already allows. - -## Processing - -WebCrypto Ed25519 is asynchronous, so writes return promises. Each track producer runs one serial -pump: one signature in flight, net writes in call order, so a frame's index always matches its -transport position. Await each write for backpressure. diff --git a/js/sign/package.json b/js/sign/package.json deleted file mode 100644 index 4fa00d26eff..00000000000 --- a/js/sign/package.json +++ /dev/null @@ -1,30 +0,0 @@ -{ - "name": "@moq/sign", - "type": "module", - "version": "0.0.0", - "description": "Per-frame Ed25519 signatures for MoQ broadcasts, so relays proxy without forging content.", - "license": "(MIT OR Apache-2.0)", - "repository": { - "type": "git", - "url": "git+https://github.com/moq-dev/moq.git", - "directory": "js/sign" - }, - "private": true, - "sideEffects": false, - "exports": { - ".": "./src/index.ts" - }, - "scripts": { - "build": "rm -rf dist && tsc -b tsconfig.build.json && bun ../common/package.ts", - "check": "tsc --noEmit", - "test": "bun test --only-failures" - }, - "dependencies": { - "@moq/net": "workspace:^" - }, - "devDependencies": { - "@moq/clock": "workspace:^", - "@types/bun": "^1.4.4", - "typescript": "7.0.2" - } -} diff --git a/js/sign/src/pump.ts b/js/sign/src/pump.ts deleted file mode 100644 index c2689acbcd2..00000000000 --- a/js/sign/src/pump.ts +++ /dev/null @@ -1,16 +0,0 @@ -/** - * Runs tasks one at a time in submit order: one AEAD call in flight, completions in order. - * - * A producer's depth one keeps a frame's ordinal equal to its `@moq/net` write order without - * reservations; the queue is the callers' own pending promises, so awaiting each write is the - * backpressure. A consumer runs only opens through it, never net waits. - */ -export class Pump { - #tail: Promise = Promise.resolve(); - - run(task: () => Promise | T): Promise { - const result = this.#tail.then(task); - this.#tail = result.catch(() => {}); - return result; - } -} diff --git a/js/sign/tsconfig.build.json b/js/sign/tsconfig.build.json deleted file mode 100644 index b58733f6162..00000000000 --- a/js/sign/tsconfig.build.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - // Build-only variant of tsconfig.json that keeps tests out of dist/, so they - // are neither published nor discovered by `bun test` at the package root. - // `tsc --noEmit` still uses tsconfig.json, so tests stay type-checked. - "extends": "./tsconfig.json", - "compilerOptions": { - "rootDir": "./src" - }, - "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"] -} diff --git a/js/sign/tsconfig.json b/js/sign/tsconfig.json deleted file mode 100644 index bfbf10ed73c..00000000000 --- a/js/sign/tsconfig.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "extends": "../tsconfig.json", - "compilerOptions": { - "outDir": "dist", - // The transport test borrows `@moq/net`'s mock transport by relative path, so the - // type-check spans the workspace. The build pins `rootDir` to src and skips tests. - "rootDir": "..", - "types": ["bun"] - }, - "include": ["src"] -} diff --git a/package.json b/package.json index db5e5f3fdef..f6f034cebea 100644 --- a/package.json +++ b/package.json @@ -43,8 +43,7 @@ "js/clock", "js/pattern", "js/auth", - "js/e2ee", - "js/sign", + "js/crypto", "js/json", "js/libav", "js/hang", diff --git a/quest/m1/README.md b/quest/m1/README.md index 5ef950dd8f4..267a30f1731 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -158,7 +158,6 @@ per-frame CPU growth since #5926. - [Sockets](/quest/m1/socket/README.md) - a generic dial/accept `Socket` in moq-net, Rust, JS, and Python, with tracks as streams; moq-boy and CARLA move onto it - [Moxygen pin bump](/quest/m1/moxygen-pin-bump.md) - waiting on moxygen#264, then the TRACK_STATUS patch is dropped - [A smaller, safer API than release](/quest/m1/api-audit/README.md) - every surface added since release has a consumer or is gone, overlapping operations are collapsed, names mirror across Rust, JS, and the bindings, and every break says how to migrate -- [moq-crypto replaces moq-sign and moq-e2ee](/quest/m1/moq-crypto.md) - one Rust crate and one JS package hold signing and end-to-end encryption, sharing moq-net's timestamp check - [Register moq-dev draft 20 in the interop runner](/quest/m1/ietf-drop/README.md) - land the external registry, notes, and README correction for drafts 18, 20, and 22 - [moq-quic's API improves on quinn's](/quest/m1/quic-api/README.md) - moq-quic and both QUIC drivers ship one mirrored API: `send::`/`recv::` namespaces, one error per direction, consuming terminal operations, plain configs, no quinn baggage - [On-demand JavaScript FETCH](/quest/m1/js-fetch-on-demand.md) - browser publishers answer IETF FETCH for evicted or uncached groups through the JS ranges request surface @@ -188,7 +187,7 @@ per-frame CPU growth since #5926. - [A cancelled MoqTrackDemand wait never loses the next change](/quest/m1/demand-cancel-race.md) - cancelling a `MoqTrackDemand::wanted_changed` call, from any binding, never consumes a demand change - [moq-ffi reports an unsupported media configuration as a typed error](/quest/m1/ffi-unsupported-config.md) - `MoqAudioConsumer::subscribe` and the matching video subscribe fail with a typed "unsupported configuration" error - [A live keyframe interval change never outruns the declared HLS duration](/quest/m1/js-hls-keyframe-duration.md) - raising a live keyframe interval, even to infinite, never pushes a segment past the declared HLS target duration, and the browser interop cell asserts the catalog `hls` field -- [One Ed25519 public key type with one z-base-32 codec](/quest/m1/mesh-key-codec.md) - `moq_auth::mesh::EndpointId` is merged into `moq_sign::PublicKey` +- [One Ed25519 public key type with one z-base-32 codec](/quest/m1/mesh-key-codec.md) - `moq_auth::mesh::EndpointId` is merged into `moq_crypto::sign::PublicKey` - [moqsink reports track demand only once the track is in the catalog](/quest/m1/moqsink-demand-catalog.md) - A `moqsink` request pad's `track-demand` stays null until its track is listed in the published catalog, and only then reports `wanted` - [Ordered reads can skip owed holes, and snapshot latest() does](/quest/m1/ordered-owed-holes.md) - moq-net's `Ordered` gains a read that skips past an owed hole to the newest buffered group, while keeping the reader's bounds - [A Rust relay never replays from group 0 to a lite-03/04 subscriber](/quest/m1/relay-inflight-replay.md) - A Rust relay or publisher serving a lite-03 or lite-04 SUBSCRIBE from a track copy that is still resolving starts at the newest group once the copy resolves diff --git a/quest/m1/mesh-key-codec.md b/quest/m1/mesh-key-codec.md index f533e46b06e..0f9712db4c4 100644 --- a/quest/m1/mesh-key-codec.md +++ b/quest/m1/mesh-key-codec.md @@ -2,10 +2,10 @@ ## Goal -`moq_auth::mesh::EndpointId` is merged into `moq_sign::PublicKey`: one Rust +`moq_auth::mesh::EndpointId` is merged into `moq_crypto::sign::PublicKey`: one Rust type for a mesh endpoint's Ed25519 public key, with one z-base-32 text codec (52 lowercase characters, zero trailing bits, no other text form) that -moq-auth and moq-sign share. JS has one codec too, used by `@moq/sign` and +moq-auth and moq-crypto share. JS has one codec too, used by `@moq/crypto` and by `@moq/auth` if it grows one. The text form, vectors, and refusals stay as both PRs specified. @@ -25,24 +25,23 @@ is related. `rs/moq-sign` with `SecretKey`/`PublicKey` using the same specification, and a separate JS codec in `js/sign/src/zbase32.ts`. Both chose z-base-32 so they would share one format; whichever landed second was to dedupe. -- Merge `EndpointId` into `moq_sign::PublicKey` (moq-auth depends on - moq-sign for it, or the type moves to a small shared crate if the +- Merge `EndpointId` into `moq_crypto::sign::PublicKey` (moq-auth depends on + moq-crypto for it, or the type moves to a small shared crate if the dependency direction is wrong; say which in the PR). Keep the shared vectors in `drafts/moq-sign-00.json` as the single source of test vectors. - Both copies are still on `main` at be39188000: `rs/moq-auth/src/mesh/mod.rs:52` (the specification) and `:65` - (`EndpointId`), beside `rs/moq-sign/src/key.rs:18`. -- [moq-crypto replaces moq-sign](/quest/m1/moq-crypto.md) renames - `moq-sign`/`@moq/sign` to `moq-crypto`/`@moq/crypto`. If it lands first, - merge `EndpointId` into its public key type and use its JS codec instead. + (`EndpointId`), beside what is now `rs/moq-crypto/src/sign/key.rs`. +- [moq-dev/moq#7702](https://github.com/moq-dev/moq/pull/7702) merged + `moq-sign`/`@moq/sign` into `moq-crypto`/`@moq/crypto`; the JS codec is + `js/crypto/src/sign/zbase32.ts`. - Note, not in scope: persist a browser JS `SecretKey` (a nonextractable `CryptoKey`) in IndexedDB only once a browser mesh node needs a stable endpoint ID. Public API: breaking for moq-auth (`mesh::EndpointId` becomes -`moq_sign::PublicKey` or a re-export). Wire: none. +`moq_crypto::sign::PublicKey` or a re-export). Wire: none. ## Related - [Mesh](/quest/m2/mesh/README.md) - the epic both types serve -- [moq-crypto replaces moq-sign](/quest/m1/moq-crypto.md) - renames the crate this quest merges into diff --git a/quest/m1/moq-crypto.md b/quest/m1/moq-crypto.md deleted file mode 100644 index a36fc566047..00000000000 --- a/quest/m1/moq-crypto.md +++ /dev/null @@ -1,38 +0,0 @@ -# [M] moq-crypto replaces moq-sign and moq-e2ee - -## Goal - -One crate, `moq-crypto`, and one JS package, `@moq/crypto`, hold MoQ's -content signing and end-to-end encryption, replacing `moq-sign`/`@moq/sign` -and `moq-e2ee`/`@moq/e2ee` before `main` is next cut into `release`. Both -halves share one timestamp check with moq-net, so they cannot drift from it. - -## Plan - -Planned 2026-11-02 (maintainer, follow-up planning after the 2026-11-02 /quest-complete run). The follow-up started from -[moq-dev/moq#7614](https://github.com/moq-dev/moq/pull/7614), which made -`moq_net::group::on_track` public; the maintainer asked to combine the two -packages instead of only deduplicating the check. - -Decisions: - -- ✅ Name it `moq-crypto` (Rust) and `@moq/crypto` (JS). Not chosen: - `moq-secure`; keeping `moq-e2ee` and absorbing signing into it. -- ✅ Merge JS too, for parity. `@moq/sign` and `@moq/e2ee` are private and - unpublished, so the rename costs nothing outside the repository. Not chosen: - Rust only. -- ✅ Plain `sign` and `e2ee` modules, always built. Not chosen: Cargo features - per half. -- ✅ `moq-e2ee` 0.0.19 is already on crates.io: at the cut, publish a final - `moq-e2ee` whose README points at `moq-crypto`. No yank. Not chosen: - leaving it as is; yanking it. Version levels stay with the maintainer. -- Both halves call `moq_net::group::on_track` instead of their own copies - (for example `rs/moq-sign/src/group.rs:48`). - -Keep the crate independent of hang and codec-specific publisher policy, as the -[E2EE epic](/quest/m2/e2ee/README.md) requires. Update every crate, package, -doc, binding, and quest that names the old packages, including the m2 E2EE -quests. - -Public API: the crate and package names and their import paths change. -Wire: none. diff --git a/quest/m1/poll-first/async-feature.md b/quest/m1/poll-first/async-feature.md index 8d7b31b3c20..fd71c7603ad 100644 --- a/quest/m1/poll-first/async-feature.md +++ b/quest/m1/poll-first/async-feature.md @@ -51,7 +51,7 @@ What remains: converted by hand, since the macro stays straight-line only (decided 2026-10-28). - **Sibling libraries:** the poll-based libraries with hand-written wrappers - (moq-mux, moq-hls, moq-auth, moq-stats, moq-room, moq-json, moq-sign, moq-e2ee, + (moq-mux, moq-hls, moq-auth, moq-stats, moq-room, moq-json, moq-crypto, qmux, and others) gain an `async` feature, generate their wrappers, and join `just rs coroutines`. - **Default off:** moq-net's `async` feature is still on by default. Turn it off, diff --git a/quest/m1/time-addressing/e2ee.md b/quest/m1/time-addressing/e2ee.md index d8a6040c30c..9a2337a2259 100644 --- a/quest/m1/time-addressing/e2ee.md +++ b/quest/m1/time-addressing/e2ee.md @@ -8,8 +8,8 @@ the cut. ## Plan -Update `drafts/draft-lcurley-moq-e2ee.md`, `rs/moq-e2ee`, and the JS side, -which has landed: `js/e2ee/src/derive.ts` builds `nonce(group, frame)` (about +Update `drafts/draft-lcurley-moq-e2ee.md`, `rs/moq-crypto`, and the JS side, +which has landed: `js/crypto/src/e2ee/derive.ts` builds `nonce(group, frame)` (about line 156). The start is unique per track because starts strictly increase. Run `just drafts check`. diff --git a/quest/m2/audit-perf.md b/quest/m2/audit-perf.md index ec0ae144ed3..9a4ac34bfb9 100644 --- a/quest/m2/audit-perf.md +++ b/quest/m2/audit-perf.md @@ -117,7 +117,7 @@ did not move. (`moq-mux/src/container/ts/schedule.rs`) scan and sort every queued unit per PCR slot. - e2ee expands the AES-GCM key on every frame (`aead` in - `moq-e2ee/src/protect.rs`), about a quarter of `protect`; release does too. + `moq-crypto/src/e2ee/protect.rs`), about a quarter of `protect`; release does too. ### Method: attribute with instruction counts, not wall time diff --git a/quest/m2/e2ee/README.md b/quest/m2/e2ee/README.md index 53f1580d475..1309eb370e2 100644 --- a/quest/m2/e2ee/README.md +++ b/quest/m2/e2ee/README.md @@ -19,7 +19,7 @@ The contract is [draft-lcurley-moq-e2ee](/drafts/draft-lcurley-moq-e2ee.md), pro ### Epoch and identity -- Every publisher instance mints an epoch, a UUIDv7 in lowercase text, and publishes at `` with the epoch on its route, where `` derives from the credential and the semantic broadcast name without the epoch. The epoch is an input to every HKDF derivation, so a restart, takeover, or explicit group sequence cannot repeat a nonce under a key: nothing is persisted across instances and no generation counter is redistributed. The epoch is moq-e2ee's own `Epoch`, announced as the route's [instance](/doc/concept/moq-lite.md#publisher-instances). Subscribers resolve `` and take the epoch from its route's instance; on a wire that carries no instance the session mints one, so the application supplies the epoch. +- Every publisher instance mints an epoch, a UUIDv7 in lowercase text, and publishes at `` with the epoch on its route, where `` derives from the credential and the semantic broadcast name without the epoch. The epoch is an input to every HKDF derivation, so a restart, takeover, or explicit group sequence cannot repeat a nonce under a key: nothing is persisted across instances and no generation counter is redistributed. The epoch is `moq_crypto::e2ee::Epoch`, announced as the route's [instance](/doc/concept/moq-lite.md#publisher-instances). Subscribers resolve `` and take the epoch from its route's instance; on a wire that carries no instance the session mints one, so the application supplies the epoch. - An encrypting publisher refuses a shared or explicit epoch (maintainer, 2026-10-08). Two producers handed one epoch would derive the same keys and repeat every nonce. Both cores produce only under an epoch they minted themselves; consuming still binds a discovered one. Rejected: a per-instance salt. State the rule in the draft's epoch section. - The epoch is untrusted and unauthenticated. A wrong epoch fails authentication and a withheld one denies service; neither can make a nonce repeat, because only the publisher instance chooses what it encrypts under. This is the same trust a cache needs to serve the right instance. First-party plaintext publishers already mint the same route epoch. - Nothing in the path says the bytes are encrypted. The format after decryption (`meeting.hang`) is inside the opaque name; a plaintext player, exporter, or matcher that opens a protected broadcast finds no catalog it can read and fails with its usual typed refusal, the same as for any format it does not support. @@ -69,14 +69,14 @@ Noted 2026-10-31 from [moq-dev/moq#7307](https://github.com/moq-dev/moq/pull/730 neither the e2ee wrapper nor the trait mirror has them. Add them to the wrapper once moq-net does. -Before `@moq/e2ee` is first published, add its entrypoints to the API +Before `@moq/crypto` is first published, add its entrypoints to the API Extractor declaration checks, which analyze only published packages since [moq-dev/moq#6794](https://github.com/moq-dev/moq/pull/6794). ## Required - [JS undeclared track names](/quest/m2/e2ee/js-undeclared-names.md) - - `@moq/net` exposes a broadcast request handler and `@moq/e2ee` serves + `@moq/net` exposes a broadcast request handler and `@moq/crypto` serves undeclared names through it - [Rust protected publisher seams](/quest/m2/e2ee/rust-publish.md) - Rust publishers emit encrypted catalogs and no plaintext semantic catalog in diff --git a/quest/m2/e2ee/cli.md b/quest/m2/e2ee/cli.md index d7b0866f1a9..6a1c8050512 100644 --- a/quest/m2/e2ee/cli.md +++ b/quest/m2/e2ee/cli.md @@ -8,7 +8,7 @@ Existing plaintext commands remain the default; an explicit application credenti ## Plan -Make `moq-e2ee` publishable with this CLI consumer; the crate currently sets +Make `moq-crypto` publishable with this CLI consumer; the crate currently sets `publish = false` while it is workspace-only. - Hand the [trait-generic CLI paths](/quest/m2/net-wrap/cli.md) an encrypted broadcast for publication and playback. Keep codec, capture, playback, and synchronization logic outside the crypto layer. diff --git a/quest/m2/e2ee/consumer.md b/quest/m2/e2ee/consumer.md index 1e86ea2ae92..11a2164bee0 100644 --- a/quest/m2/e2ee/consumer.md +++ b/quest/m2/e2ee/consumer.md @@ -9,7 +9,7 @@ reinvent decryption and physical-name mapping. ## Plan Decided 2026-10-20 (maintainer): the shape is the moq-net consumer traits. -`moq_e2ee::broadcast::Consumer` and its track and group consumers implement +`moq_crypto::e2ee::broadcast::Consumer` and its track and group consumers implement them ([net-wrap](/quest/m2/net-wrap/README.md)), so a Rust player, the CLI, and `@moq/watch` open an encrypted broadcast as they open any other, because every reader already takes the traits. Kept in m2 (decided @@ -29,7 +29,7 @@ What remains here: - Rust and JS only (decided 2026-10-20, maintainer): the e2ee publisher has no moq-ffi half either, so an FFI consumer waits for a quest that adds both. -Public API: an e2ee consumer entry point in `moq-e2ee` and `@moq/e2ee`. +Public API: an e2ee consumer entry point in `moq-crypto` and `@moq/crypto`. Wire: none. ## Required diff --git a/quest/m2/e2ee/js-undeclared-names.md b/quest/m2/e2ee/js-undeclared-names.md index 0218c6f0413..8dcb8c66946 100644 --- a/quest/m2/e2ee/js-undeclared-names.md +++ b/quest/m2/e2ee/js-undeclared-names.md @@ -2,9 +2,9 @@ ## Goal -`@moq/net` exposes a public broadcast request handler, and `@moq/e2ee`'s +`@moq/net` exposes a public broadcast request handler, and `@moq/crypto`'s broadcast producer answers requests for track names it never created -through it, under semantic names, as `moq_e2ee::broadcast::Requests` does in +through it, under semantic names, as `moq_crypto::e2ee::broadcast::Requests` does in Rust. A JS application then serves on-demand tracks from a plaintext or encrypted broadcast the same way. @@ -18,7 +18,7 @@ Decided with the maintainer on 2026-10-24: layers, and only the origin has a public `requests()`. Expose the broadcast's handler under Rust's name and shape (`requests()` returning `Requests`), and keep the internal wire path on it. -- `@moq/e2ee` mirrors the Rust handler exactly: it opens each request's +- `@moq/crypto` mirrors the Rust handler exactly: it opens each request's physical name, claims it, and yields a request whose `name` is semantic. A name that does not open is answered as missing and keeps no state. A re-requested or re-created name resumes above its high-water marks, as in @@ -26,7 +26,7 @@ Decided with the maintainer on 2026-10-24: 2026-10-17 refusal, so every identity stays unique and a handler can serve a dropped name again). - The handler offers the lister, taking semantic names and listing their - physical names, as Rust's `moq_e2ee::broadcast::Lister` does. `@moq/net`'s broadcast lister is + physical names, as Rust's `moq_crypto::e2ee::broadcast::Lister` does. `@moq/net`'s broadcast lister is internal today (tests reach it through `wireOf`), so export it with the handler. - Port Rust's `requests_refuse_names_the_generation_did_not_issue` and @@ -34,8 +34,8 @@ Decided with the maintainer on 2026-10-24: and a burst of forged names that leaves no state behind. Public API: a public broadcast `requests()` in `@moq/net`, and a request -handler on `@moq/e2ee`'s broadcast producer. Wire: none. +handler on `@moq/crypto`'s broadcast producer. Wire: none. ## Required -- [JS mirror](/quest/m2/net-wrap/js.md) - the `@moq/net` interfaces the `@moq/e2ee` wrappers implement +- [JS mirror](/quest/m2/net-wrap/js.md) - the `@moq/net` interfaces the `@moq/crypto` wrappers implement diff --git a/quest/m2/e2ee/rust-publish.md b/quest/m2/e2ee/rust-publish.md index e1e4c7b2949..f6191bc983c 100644 --- a/quest/m2/e2ee/rust-publish.md +++ b/quest/m2/e2ee/rust-publish.md @@ -20,7 +20,7 @@ timeline publishers already publish into an encrypted broadcast under semantic names with no change here. This quest keeps only what the traits do not cover. Every track these publishers serve is declared in advance, so it never needed the undeclared-name handler (maintainer, -2026-10-19), which `moq_e2ee::broadcast::Producer::requests` now provides. +2026-10-19), which `moq_crypto::e2ee::broadcast::Producer::requests` now provides. - Catalog naming: derive the protected catalog name from its well-known logical role, then put media roles, codecs, quality, timelines, and @@ -33,13 +33,13 @@ in advance, so it never needed the undeclared-name handler (maintainer, - Cover every current Rust importer and capture path so a convenience API cannot emit a plaintext semantic catalog. - A re-created track resumes (decided 2026-10-25, maintainer, replacing the - 2026-10-17 refusal): moq-e2ee never releases a name's claim, and a track + 2026-10-17 refusal): moq-crypto never releases a name's claim, and a track created again under a claimed name continues above its high-water marks, - so nonces never repeat. moq-e2ee's `create_track` already does this. + so nonces never repeat. moq-crypto's `create_track` already does this. Public API: none. Wire: none. ## Required -- [moq-e2ee implements the traits](/quest/m2/net-wrap/e2ee.md) - the encrypted broadcast moq-mux publishes into +- [moq-crypto's e2ee implements the traits](/quest/m2/net-wrap/e2ee.md) - the encrypted broadcast moq-mux publishes into - [moq-mux takes the traits](/quest/m2/net-wrap/mux.md) - the mux and capture publishers this relies on to stay unchanged diff --git a/quest/m2/mesh/README.md b/quest/m2/mesh/README.md index 604ba6da015..8b0a645ef54 100644 --- a/quest/m2/mesh/README.md +++ b/quest/m2/mesh/README.md @@ -58,7 +58,7 @@ Decided 2026-10-25 with the maintainer (planning interview), still in force: token only; a Tailnet-Lock analog was declined. - Protection is per broadcast, with levels that nest: identity (the token only), authentication (per-frame Ed25519 signatures, the default), and - later encryption (signed plus moq-e2ee, waiting on + later encryption (signed plus moq-crypto's e2ee, waiting on [mesh keys](/quest/m3/mesh-keys.md)). - Enrollment is automated, with no human in the loop (decided 2026-10-30): a device presents an enrollment key the owner created and then refreshes by diff --git a/quest/m2/mesh/endpoint.md b/quest/m2/mesh/endpoint.md index 82f6ebc79a4..fbb6adbbc37 100644 --- a/quest/m2/mesh/endpoint.md +++ b/quest/m2/mesh/endpoint.md @@ -23,10 +23,10 @@ Decided 2026-10-25 (maintainer): iroh-shaped, not drop-in compatible; tickets, `mesh/*/*/.dial/`, and update `doc/bin/relay/auth.md`. - Streams are [byte streams](/quest/m2/stream/rust.md) at the protection level the service declares: identity reads `moq-net` directly, and - authentication, the mesh default, reads through `moq-sign` against the + authentication, the mesh default, reads through `moq_crypto::sign` against the `PublicKey` parsed from the path it subscribes to: the listener's `mesh//` for a dialer, and the `.dial/` segment for a listener. -- The secret key comes from `moq_sign::SecretKey::load_or_generate`. +- The secret key comes from `moq_crypto::sign::SecretKey::load_or_generate`. - A mesh daemon (Kixel's, outside this repository, decided 2026-11-02) is built on this API, so a process either embeds an `Endpoint` or talks to a local [mesh relay node](/quest/m2/mesh/node.md). diff --git a/quest/m2/net-wrap/README.md b/quest/m2/net-wrap/README.md index ad910010b86..85ac12834f5 100644 --- a/quest/m2/net-wrap/README.md +++ b/quest/m2/net-wrap/README.md @@ -39,7 +39,7 @@ and its trait-versus-bridge comparison: `recv_group`, `recv_datagram`, `read_frame`, `next_frame`, `read_chunk`, the broadcast consumer's `tracks` listing (maintainer, 2026-10-24), and their `poll_*` forms. A wrapper adapts - to moq-net, not the other way around: moq-e2ee's error converts into + to moq-net, not the other way around: `moq_crypto::e2ee::Error` converts into `moq_net::Error`. - **Datagrams follow the datagram types.** [Datagram tracks](/quest/m1/datagram-tracks/README.md) (m1) replaces `append_datagram`, `insert_datagram`, and `recv_datagram` on stream tracks @@ -72,11 +72,11 @@ above. ## Required - [moq-net traits](/quest/m2/net-wrap/traits.md) - moq-net exports producer and consumer traits at every level, implemented by its own types -- [moq-e2ee implements the traits](/quest/m2/net-wrap/e2ee.md) - the e2ee broadcast, track, and group wrappers implement the traits, proving them before the adopters land +- [moq-crypto's e2ee implements the traits](/quest/m2/net-wrap/e2ee.md) - the e2ee broadcast, track, and group wrappers implement the traits, proving them before the adopters land - [moq-json, moq-stats, and hang take the traits](/quest/m2/net-wrap/json.md) - json snapshots, streams, windows, the stats producer, and hang's tracks write and read through the traits - [moq-mux takes the traits](/quest/m2/net-wrap/mux.md) - importers, catalog, container, timeline, json tracks, `Source`, TS export, and the moq-video and moq-audio encoders are generic over the traits - [CLI paths take the traits](/quest/m2/net-wrap/cli.md) - the CLI's publish and play paths hand moq-mux any broadcast that implements them -- [JS mirror](/quest/m2/net-wrap/js.md) - `@moq/net` exports the same interfaces, taken by `@moq/hang`, `@moq/publish`, and `@moq/watch`, and implemented by `@moq/e2ee` +- [JS mirror](/quest/m2/net-wrap/js.md) - `@moq/net` exports the same interfaces, taken by `@moq/hang`, `@moq/publish`, and `@moq/watch`, and implemented by `@moq/crypto` ## Related diff --git a/quest/m2/net-wrap/e2ee.md b/quest/m2/net-wrap/e2ee.md index 6aa6af87b2c..12c9cc3684c 100644 --- a/quest/m2/net-wrap/e2ee.md +++ b/quest/m2/net-wrap/e2ee.md @@ -1,8 +1,8 @@ -# [M] moq-e2ee implements the moq-net traits +# [M] moq-crypto's e2ee implements the moq-net traits ## Goal -moq-e2ee's broadcast, track, and group wrappers implement the +moq-crypto's e2ee broadcast, track, and group wrappers implement the [moq-net traits](/quest/m2/net-wrap/traits.md), so anything generic over them publishes or consumes an encrypted broadcast unchanged, under semantic track names. @@ -17,7 +17,7 @@ the reverse (decided 2026-10-20, maintainer): - `track::Producer::create_group(u64)` takes `group::Info`. - `broadcast::Consumer::subscribe(semantic, ..)`, which returns a `kio::Pending`, becomes `track(semantic)` then `.subscribe(..)`. -- `moq_e2ee::Error` converts into `moq_net::Error`, keeping the draft's +- `moq_crypto::e2ee::Error` converts into `moq_net::Error`, keeping the draft's typed codes (such as an authentication failure) distinguishable rather than collapsing into `Error::Dropped`. - Datagrams: the wrapper's datagram producer and consumer match the @@ -25,7 +25,7 @@ the reverse (decided 2026-10-20, maintainer): [Datagram tracks](/quest/m1/datagram-tracks/README.md), so the trait read yields only authenticated datagrams. A datagram that fails authentication, or a duplicate, is dropped there and the track continues. The draft's `authentication` - event stays on moq-e2ee's own consumer, outside the trait, for callers + event stays on moq-crypto's own consumer, outside the trait, for callers that hold the concrete type. A trait read can't carry it without breaking the exact mirror. - `track::Info.compress` is logical. Ciphertext doesn't compress, so the @@ -44,7 +44,7 @@ the reverse (decided 2026-10-20, maintainer): This keeps [rust-publish](/quest/m2/e2ee/rust-publish.md)'s rule that protected catalogs compress before encryption, and needs moq-net to expose its group - codec to the wrapper. `@moq/e2ee` does the same in + codec to the wrapper. `@moq/crypto` does the same in [JS](/quest/m2/net-wrap/js.md). - The subscriber's wrapper learns the logical flag from authenticated E2EE metadata, never from the physical track (decided 2026-10-20, maintainer): @@ -54,15 +54,15 @@ the reverse (decided 2026-10-20, maintainer): catalog track is itself compressed, so a subscriber would need the flag before it could inflate the catalog that carries it. The [E2EE epic](/quest/m2/e2ee/README.md) also keeps catalog formats out of - moq-e2ee, and the [compression migration](https://github.com/moq-dev/moq/pull/7046) dropped hang's + moq-crypto, and the [compression migration](https://github.com/moq-dev/moq/pull/7046) dropped hang's `compression` field. The subscriber needs the flag before inflating, without changing moq-net's `track(name)`; propose the encoding in the PR. Record it in `draft-lcurley-moq-e2ee.md`, replacing the Catalogs section's `.z` sibling rule. - Datagram header allowance (decided 2026-10-31, maintainer, a follow-up of [moq-dev/moq#7435](https://github.com/moq-dev/moq/pull/7435)): - `MAX_DATAGRAM_HEADER` (`rs/moq-e2ee/src/limits.rs`, - `js/e2ee/src/limits.ts`; 28 after #7435, lite-07's Type plus three 9-byte + `MAX_DATAGRAM_HEADER` (`rs/moq-crypto/src/e2ee/limits.rs`, + `js/crypto/src/e2ee/limits.ts`; 28 after #7435, lite-07's Type plus three 9-byte varints) also counts the optional lite datagram fields: the relayed fields the lite `ietf` extension adds, and moq-net's Inflated Size header field, which a compressed physical track's datagram carries outside the AEAD @@ -84,8 +84,8 @@ the reverse (decided 2026-10-20, maintainer): counting that cap) or documenting that relay properties are outside the allowance, so such a datagram may be dropped, and record the choice in the PR. Sealing and opening share - `MAX_DATAGRAM_PAYLOAD` today (`rs/moq-e2ee/src/track.rs`, - `js/e2ee/src/track.ts`), so a wider allowance would also make `open` + `MAX_DATAGRAM_PAYLOAD` today (`rs/moq-crypto/src/e2ee/track.rs`, + `js/crypto/src/e2ee/track.ts`), so a wider allowance would also make `open` refuse a datagram an older sender sealed under the narrower one. Split the seal and open limits, or pick the limit by wire version, so a receiver still opens anything that fits the body. Update the e2ee @@ -112,12 +112,12 @@ the reverse (decided 2026-10-20, maintainer): - Keep the nonce rules the epic specifies: a group producer still owns its frame numbering, and a re-created or re-served track name resumes above its high-water marks (decided 2026-10-25, maintainer, replacing the - refusal; moq-e2ee's claims already resume). + refusal; moq-crypto's claims already resume). - Test the wrappers against the questline's pass-through test cases. The moq-json round trip through an encrypted track waits for [moq-json to take the traits](/quest/m2/net-wrap/json.md). -Public API: the moq-e2ee wrapper signatures change to moq-net's. Wire: +Public API: the moq-crypto wrapper signatures change to moq-net's. Wire: `draft-lcurley-moq-e2ee.md` gains the authenticated logical `compress` flag and each compressed object's authenticated inflated size. diff --git a/quest/m2/net-wrap/js.md b/quest/m2/net-wrap/js.md index f256a2d09d3..86bdb461508 100644 --- a/quest/m2/net-wrap/js.md +++ b/quest/m2/net-wrap/js.md @@ -4,7 +4,7 @@ `@moq/net` exports interfaces with the Rust traits' names and methods, and `@moq/hang`, `@moq/publish`, and `@moq/watch` accept them where they take a -concrete broadcast, track, or group today. `@moq/e2ee`'s wrappers implement +concrete broadcast, track, or group today. `@moq/crypto`'s wrappers implement them, so a browser publisher or player handles an encrypted broadcast without its own decryption path. @@ -16,18 +16,18 @@ its own decryption path. - Take the interfaces only where a wrapper must pass through, as needed: `@moq/hang`'s catalog and container code, `@moq/publish`'s broadcast, and `@moq/watch`'s subscriptions. -- `@moq/e2ee`'s broadcast, track, and group wrappers adapt to `@moq/net`'s - method shapes, as moq-e2ee does in Rust, with its errors mapped to - `@moq/net`'s. Like moq-e2ee, it compresses a `compress` track before +- `@moq/crypto`'s broadcast, track, and group wrappers adapt to `@moq/net`'s + method shapes, as moq-crypto does in Rust, with its errors mapped to + `@moq/net`'s. Like moq-crypto, it compresses a `compress` track before encryption, publishes the physical track uncompressed, and carries the logical flag in the same authenticated E2EE metadata ([e2ee](/quest/m2/net-wrap/e2ee.md)). - Demand and preference cross the wrapper: a publisher with no viewer through an encrypted track stays idle. - Test publish and watch round trips through a pass-through wrapper and - through `@moq/e2ee`. + through `@moq/crypto`. -Public API: new `@moq/net` interfaces; `@moq/e2ee` wrapper signatures change. +Public API: new `@moq/net` interfaces; `@moq/crypto` wrapper signatures change. Wire: the `draft-lcurley-moq-e2ee.md` compress flag from [e2ee](/quest/m2/net-wrap/e2ee.md). @@ -35,4 +35,4 @@ Wire: the `draft-lcurley-moq-e2ee.md` compress flag from - [moq-net traits](/quest/m2/net-wrap/traits.md) - the names and methods this mirrors -- [moq-e2ee implements the traits](/quest/m2/net-wrap/e2ee.md) - owns the authenticated logical compression encoding this mirrors +- [moq-crypto's e2ee implements the traits](/quest/m2/net-wrap/e2ee.md) - owns the authenticated logical compression encoding this mirrors diff --git a/quest/m2/net-wrap/json.md b/quest/m2/net-wrap/json.md index a35c764e618..b0190226c9b 100644 --- a/quest/m2/net-wrap/json.md +++ b/quest/m2/net-wrap/json.md @@ -23,7 +23,7 @@ types, so each publishes into and reads from a wrapped track unchanged. wrapper, as do demand-gated encoders. - Existing tests keep passing with the defaults. Add one round trip per crate through moq-net's shared pass-through test wrapper, and a moq-json snapshot - round trip through an encrypted track in moq-e2ee's tests. + round trip through an encrypted track in moq-crypto's tests. Public API: generic type parameters with moq-net defaults on moq-json, moq-stats, and hang. Wire: none. @@ -31,4 +31,4 @@ moq-stats, and hang. Wire: none. ## Required - [moq-net traits](/quest/m2/net-wrap/traits.md) - the traits these take -- [moq-e2ee implements the traits](/quest/m2/net-wrap/e2ee.md) - the encrypted track the snapshot round trip runs through +- [moq-crypto's e2ee implements the traits](/quest/m2/net-wrap/e2ee.md) - the encrypted track the snapshot round trip runs through diff --git a/quest/m2/net-wrap/mux.md b/quest/m2/net-wrap/mux.md index b2a950c381d..cb78d5d14d8 100644 --- a/quest/m2/net-wrap/mux.md +++ b/quest/m2/net-wrap/mux.md @@ -30,7 +30,7 @@ exporter reads one, without knowing. - No behavior change with the defaults. Keep the `containers` Criterion bench flat before and after. - Test an import and export round trip (fMP4 and TS) through the moq-net - pass-through test wrapper, plus one through moq-e2ee's wrappers once + pass-through test wrapper, plus one through moq-crypto's wrappers once [they implement the traits](/quest/m2/net-wrap/e2ee.md). Public API: generic type parameters with moq-net defaults across moq-mux. diff --git a/quest/m2/net-wrap/traits.md b/quest/m2/net-wrap/traits.md index d0a07879f6d..c1132c289ee 100644 --- a/quest/m2/net-wrap/traits.md +++ b/quest/m2/net-wrap/traits.md @@ -29,7 +29,7 @@ the methods exactly as moq-net has them today. - Requests: a broadcast producer's `requests` returns its own `broadcast::Requests`, whose `requested_track` yields its own `track::Request`, so generic code serves undeclared names (as - `moq_e2ee::broadcast::Requests` does). A + `moq_crypto::e2ee::broadcast::Requests` does). A `track::Requests`'s `requested_fill` yields its own `track::Fill`, whose `accept` returns its own group producer and whose `drop_groups` names the rest dropped. diff --git a/quest/m2/release/cut.md b/quest/m2/release/cut.md index b1bb4f5bd0f..0633405d1ad 100644 --- a/quest/m2/release/cut.md +++ b/quest/m2/release/cut.md @@ -48,6 +48,14 @@ From the 2026-10-25 pre-cut run: `MOQ_FFI_RANGE`) to the release that ships the `implementation` field from [moq-dev/moq#6775](https://github.com/moq-dev/moq/pull/6775). +From [moq-dev/moq#7702](https://github.com/moq-dev/moq/pull/7702), which +merged moq-e2ee and moq-sign into moq-crypto (decided 2026-11-02, no yank): + +- Publish `main`'s code-free `rs/moq-e2ee` stub, whose README points at + moq-crypto, as moq-e2ee's final release. It must take a version above + crates.io's current `max_version` (0.0.20 on 2026-11-02); check with + `curl -s https://crates.io/api/v1/crates/moq-e2ee`. + The [2026-10-22 release audit](https://github.com/moq-dev/moq/pull/7176) closed with its fixes rechecked together. At source candidate [main 487759f62a](https://github.com/moq-dev/moq/commit/487759f62a9ef39d916fe5b92df06dcff83478ce), diff --git a/quest/m2/stream/README.md b/quest/m2/stream/README.md index 87cd7854dcb..e4862999940 100644 --- a/quest/m2/stream/README.md +++ b/quest/m2/stream/README.md @@ -25,7 +25,7 @@ Decided 2026-10-25 with the maintainer (mesh planning interview): `TCP_NODELAY` still applies). - The receiver flushes a frame's bytes to its TCP socket as they arrive, never waiting for the whole frame, unless the mesh's authentication level - (`moq-sign`) must verify it first; a frame that fails verification ends its + (`moq_crypto::sign`) must verify it first; a frame that fails verification ends its group with a typed error, surfaced as a reset. Group finish is a FIN (half-close); a group abort with a code is a reset. The implementer measures and records a frame-size cap. diff --git a/quest/m3/ffi-e2ee.md b/quest/m3/ffi-e2ee.md index ee85239e6d5..8c2efecbbd7 100644 --- a/quest/m3/ffi-e2ee.md +++ b/quest/m3/ffi-e2ee.md @@ -2,9 +2,9 @@ ## Goal -The Swift and Kotlin bindings publish and consume moq-e2ee protected +The Swift and Kotlin bindings publish and consume moq-crypto protected broadcasts under an application-supplied `(context, kid, secret)` credential, -interoperating with `@moq/e2ee` in both directions, with the same epoch rules +interoperating with `@moq/crypto` in both directions, with the same epoch rules and typed authentication failures as Rust and JS. ## Plan @@ -15,7 +15,7 @@ to, adding both halves. The named consumer is moq.pro's [T3 Code over MoQ](https://github.com/moq-dev/moq.pro/blob/main/quest/m3/t3/README.md) mobile app, which receives its credential in a pairing link. -Wrap `moq-e2ee`'s producer and consumer entry points without new crypto in +Wrap `moq-crypto`'s producer and consumer entry points without new crypto in the binding layer, and keep the encrypting publisher's refusal of a shared or explicit epoch. Add a binding test that decrypts a JS-published broadcast and the reverse to the interop suite. diff --git a/quest/m3/mesh-keys.md b/quest/m3/mesh-keys.md index 12712e5ef6a..1f39d52bc5f 100644 --- a/quest/m3/mesh-keys.md +++ b/quest/m3/mesh-keys.md @@ -14,7 +14,7 @@ Parked 2026-10-25 (maintainer): encryption is out of the first mesh; identity and authentication ship first. Research recorded in the planning PR: SFrame and IETF secure objects leave key distribution open and give no sender authenticity; MLS per broadcast is heavy for churning viewers; a sender-keys -style wrapped key track fans out like media. The AEAD stays moq-e2ee. +style wrapped key track fans out like media. The AEAD stays moq-crypto's e2ee. Revisit when a mesh user needs confidentiality from relays. ## Related diff --git a/rs/justfile b/rs/justfile index 0419da5a6b6..8fafe882020 100644 --- a/rs/justfile +++ b/rs/justfile @@ -498,7 +498,7 @@ gst-smoke *args: # rind is built to skip that one startup check, or it refuses the simulated CPU. codspeed: VALGRIND_BUG_494162=1 cargo codspeed build --locked -m simulation \ - -p kio -p moq-audio -p moq-e2ee -p moq-json -p moq-mux -p moq-net -p moq-pattern -p moq-quic -p moq-rtmp \ + -p kio -p moq-audio -p moq-crypto -p moq-json -p moq-mux -p moq-net -p moq-pattern -p moq-quic -p moq-rtmp \ --features moq-audio/bus,moq-net/fuzz,moq-quic/fuzz \ --bench tasks --bench waiter --bench bus --bench protect --bench codec --bench table \ --bench catalog --bench containers --bench decode_clock --bench export --bench jitter \ diff --git a/rs/moq-e2ee/CHANGELOG.md b/rs/moq-crypto/CHANGELOG.md similarity index 100% rename from rs/moq-e2ee/CHANGELOG.md rename to rs/moq-crypto/CHANGELOG.md diff --git a/rs/moq-sign/Cargo.toml b/rs/moq-crypto/Cargo.toml similarity index 63% rename from rs/moq-sign/Cargo.toml rename to rs/moq-crypto/Cargo.toml index bcad6ad0373..9950ffd9c45 100644 --- a/rs/moq-sign/Cargo.toml +++ b/rs/moq-crypto/Cargo.toml @@ -1,35 +1,43 @@ [package] publish = false -name = "moq-sign" -description = "Per-frame Ed25519 signatures for MoQ broadcasts, so relays proxy without forging content." +name = "moq-crypto" +description = "Content signing and end-to-end encryption for MoQ broadcasts." authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.0.1" +version = "0.0.11" edition = "2024" rust-version.workspace = true -keywords = ["quic", "http3", "webtransport", "signature", "live"] +keywords = ["quic", "webtransport", "encryption", "signature", "live"] categories = ["cryptography", "multimedia", "network-programming"] [dependencies] aws-lc-rs = { workspace = true } +base64 = { workspace = true } bytes = { workspace = true } data-encoding = { workspace = true } kio = { workspace = true } moq-net = { workspace = true } +rind = { workspace = true } thiserror = { workspace = true } +uuid = { workspace = true } zeroize = { workspace = true } [dev-dependencies] criterion = { package = "bench-harness", path = "../bench-harness" } hex = { workspace = true } +kio = { workspace = true, features = ["runtime"] } serde_json = { workspace = true } tempfile = { workspace = true } -tokio = { workspace = true, features = ["macros", "rt", "test-util"] } +tokio = { workspace = true, features = ["macros", "rt", "sync", "test-util", "time"] } workspace-hack = { path = "../workspace-hack" } +[[bench]] +name = "protect" +harness = false + [[bench]] name = "sign" harness = false diff --git a/rs/moq-e2ee/MIGRATE.md b/rs/moq-crypto/MIGRATE.md similarity index 60% rename from rs/moq-e2ee/MIGRATE.md rename to rs/moq-crypto/MIGRATE.md index 56e235fc672..3cd3abc1cc7 100644 --- a/rs/moq-e2ee/MIGRATE.md +++ b/rs/moq-crypto/MIGRATE.md @@ -1,9 +1,22 @@ -# Migrating moq-e2ee +# Migrating moq-crypto How to update your code for each breaking change, newest first. ## Unreleased +### moq-e2ee and moq-sign are moq-crypto (#7702) + +`moq-e2ee` and the workspace-only `moq-sign` merged into `moq-crypto`, as its `e2ee` and `sign` modules. +The profiles and wire are unchanged; each module keeps its own `Error` and `Result`. +Depend on `moq-crypto` and rename the imports: + +| Before | After | +| --- | --- | +| `moq_e2ee::…` | `moq_crypto::e2ee::…` | +| `moq_sign::…` | `moq_crypto::sign::…` | + +`moq_e2ee`'s entries below predate the merge; their `Before` code keeps the old paths, and their instructions name the `moq_crypto::e2ee` ones. + ### Tracks are named semantically through `broadcast` wrappers (#5876) `generation::Producer::produce` and `generation::Consumer::consume` are private. @@ -17,8 +30,8 @@ let subscriber = remote.track(name.as_str())?.subscribe(subscription).await?; let reader = consuming.consume(subscriber)?; // After -let video = moq_e2ee::broadcast::Producer::new(broadcast, generation).create_track("video", info)?; -let reader = moq_e2ee::broadcast::Consumer::new(remote, consuming) +let video = moq_crypto::e2ee::broadcast::Producer::new(broadcast, generation).create_track("video", info)?; +let reader = moq_crypto::e2ee::broadcast::Consumer::new(remote, consuming) .subscribe("video", subscription)? .await?; ``` @@ -29,7 +42,7 @@ A track served on demand is reserved up front with `broadcast::Producer::reserve The protected path is the opaque broadcast path; the publisher epoch is read from the route's instance instead of a path suffix. On wires that do not carry an instance, the session mints one, so the application supplies the epoch. -Drop `join_epoch` and `split_epoch`: announce the generation's `moq_e2ee::Epoch` as the route's instance with `Route::default().with_instance(generation.epoch().instance(), 0)`, and read it back from the resolved broadcast with `moq_e2ee::Epoch::of(&broadcast)`. +Drop `join_epoch` and `split_epoch`: announce the generation's `moq_crypto::e2ee::Epoch` as the route's instance with `Route::default().with_instance(generation.epoch().instance(), 0)`, and read it back from the resolved broadcast with `moq_crypto::e2ee::Epoch::of(&broadcast)`. ### Timestamps are optional diff --git a/rs/moq-crypto/README.md b/rs/moq-crypto/README.md new file mode 100644 index 00000000000..4281ab09a79 --- /dev/null +++ b/rs/moq-crypto/README.md @@ -0,0 +1,102 @@ +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/moq-dev/moq/blob/main/LICENSE-MIT) + +# moq-crypto + +Workspace-only implementation; this crate is not published. + +Content signing and end-to-end encryption for [Media over QUIC](https://moq.dev): the `sign` +module signs every frame so relays cannot forge it, and the `e2ee` module encrypts groups, +datagrams, and track names so relays cannot read them. Both wrap `moq-net` and check timestamps +with its `track::Info::rescale`, so a frame either half accepts is one `moq-net` accepts. + +## Signing + +Per-frame Ed25519 signatures for [Media over QUIC](https://moq.dev) broadcasts. Profile +`moq-sign-00` from [draft-lcurley-moq-sign](https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/). + +Relays forward and cache signed frames; they cannot forge, retime, or relocate them. Signatures +authenticate content, not liveness: a relay that recorded an instance can replay it whole. + +### Shape + +An endpoint's `SecretKey` signs; its `PublicKey` is the endpoint ID, displayed as 52 z-base-32 +characters (a DNS label). `SecretKey::load_or_generate(path)` keeps one key for the life of a host, +as 52 z-base-32 characters in a `0600` file it never replaces implicitly. + +`broadcast::Producer` wraps the `moq-net` broadcast, mints a fresh instance, and signs each frame +over the application path, instance, track, group, frame index, and timestamp (at the track's +timescale). Announce the broadcast with that instance on its route: + +```rust +let key = SecretKey::load_or_generate("/var/lib/moq/endpoint.key")?; +let path = moq_net::Path::new(&format!("mesh/{}/agent", key.public()))?; +let publication = origin.create_broadcast(&path)?; +let signed = broadcast::Producer::new(publication.broadcast().clone(), key, path); +let messages = signed.create_track("messages", None)?; +publication.announce(Route::default().with_instance(signed.instance().clone(), 0))?; +``` + +A subscriber wraps the broadcast an origin resolved in a `broadcast::Consumer` with the key it +expects and the same application path; it takes the instance from the route. A frame reaches the +application only after it verifies. A forged or relocated frame ends its group with +`Error::Signature`, and the track keeps delivering other groups. Every hop must carry the instance +and timestamps unchanged, which means moq-lite-07. A group's end is not signed: a relay may drop +a group's tail, as MoQ already allows. + +A broadcast at the identity level, which trusts the relay's token check alone, uses `moq-net` +directly. + +### Processing + +Signing is inline and synchronous. `cargo bench -p moq-crypto --bench sign` measures it: a 1 KiB frame costs +about 8 µs to sign and 32 µs to sign and verify through an origin on one core. + +## Encryption + +End-to-end encryption for [Media over QUIC](https://moq.dev) groups, datagrams, +and track names. Profile `moq-e2ee-00` from +[draft-lcurley-moq-e2ee](https://datatracker.ietf.org/doc/draft-lcurley-moq-e2ee/). + +Relays forward ciphertext. Content keys never enter `moq-net`. + +### Shape + +The application distributes a `Credential { context, kid, secret }` over its own +authenticated channel. `credential.produce()` mints a fresh epoch and returns a +`generation::Producer`, which derives opaque track names and keys for that instance alone. +It accepts no explicit epoch; its clones share permanent track claims. + +The application names tracks by their semantic names. `broadcast::Producer` wraps the +`moq-net` broadcast and creates each track under its physical name, so only physical names +reach the relays. A physical name is the semantic name encrypted under the generation: a relay +learns only its length rounded up to 16 bytes. A track served on demand is reserved with +`reserve_track` and accepted once its demand shows a subscriber. + +```rust +let credential = Credential::new(credential::Config { context, kid, secret })?; +let generation = credential.produce(); +let publication = origin.create_broadcast(&credential.path("meeting.hang")?)?; +let protected = broadcast::Producer::new(publication.broadcast().clone(), generation.clone()); +let video = protected.create_track("video", None)?; +publication.announce(Route::default().with_instance(generation.epoch().instance(), 0))?; +``` + +A subscriber follows `credential.path(semantic)` with `origin.follow(path, None)`. It takes +each instance's epoch from the broadcast it resolved, `Epoch::of(&broadcast)` (or from the +application's channel on a wire that carries no instance, older than lite-07), so the key always matches the instance +it reads. It binds the epoch with `credential.consume(epoch)` and wraps the broadcast in a +`broadcast::Consumer`. Its `subscribe(semantic, subscription)` opens the track a decrypted +catalog names. A consuming generation cannot produce. Nothing survives a publisher instance: a restart mints a new epoch. +A cloned process image (a `fork` without `exec`, a restored VM snapshot or checkpoint, or a +producing generation copied to another process) is a new instance too: each copy must call +`produce()` itself, since copies of one generation reuse its nonces. + +### Processing + +AES-128-GCM is inline and synchronous. `cargo bench -p moq-crypto --bench protect` measures the whole +protected write path, including the `moq-net` group: a 1 KiB grouped frame and a +160-byte Opus-sized datagram each cost a few microseconds on one core, so encryption +is a tiny fraction of real time and there is no async pump. + +Memory is bounded: a producer retains no ciphertext, and a consumer keeps a 1024-bit +datagram duplicate window below the greatest sequence it opened. diff --git a/rs/moq-e2ee/benches/protect.rs b/rs/moq-crypto/benches/protect.rs similarity index 83% rename from rs/moq-e2ee/benches/protect.rs rename to rs/moq-crypto/benches/protect.rs index b2a567560d2..286c30cc30e 100644 --- a/rs/moq-e2ee/benches/protect.rs +++ b/rs/moq-crypto/benches/protect.rs @@ -1,13 +1,13 @@ //! AES-128-GCM throughput for grouped frames and datagrams through the public API. //! -//! Run with `cargo bench -p moq-e2ee`. +//! Run with `cargo bench -p moq-crypto --bench protect`. use std::hint::black_box; use std::time::Duration; use criterion::{Criterion, Throughput, criterion_group, criterion_main}; -use moq_e2ee::Credential; -use moq_e2ee::credential::Config; +use moq_crypto::e2ee::Credential; +use moq_crypto::e2ee::credential::Config; use moq_net::Timestamp; fn credential() -> Credential { @@ -20,12 +20,12 @@ fn credential() -> Credential { } /// Each producer is its own publisher instance, so it gets its own epoch. -fn produce(credential: &Credential, semantic: &str) -> moq_e2ee::track::Producer { +fn produce(credential: &Credential, semantic: &str) -> moq_crypto::e2ee::track::Producer { // Advancing timestamps plus a zero max age keep only the newest group cached. let info = moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MILLI) .with_max_age(Duration::ZERO); - moq_e2ee::broadcast::Producer::new(moq_net::broadcast::Info::new().produce(), credential.produce()) + moq_crypto::e2ee::broadcast::Producer::new(moq_net::broadcast::Info::new().produce(), credential.produce()) .create_track(semantic, info) .unwrap() } diff --git a/rs/moq-sign/benches/sign.rs b/rs/moq-crypto/benches/sign.rs similarity index 91% rename from rs/moq-sign/benches/sign.rs rename to rs/moq-crypto/benches/sign.rs index 22fcd30b525..fad191fd460 100644 --- a/rs/moq-sign/benches/sign.rs +++ b/rs/moq-crypto/benches/sign.rs @@ -1,15 +1,15 @@ //! Ed25519 cost per grouped frame through the public API: signing on write, verifying on read. //! -//! Run with `cargo bench -p moq-sign`. +//! Run with `cargo bench -p moq-crypto --bench sign`. use std::hint::black_box; use std::task::Poll; use std::time::Duration; use criterion::{Criterion, Throughput, criterion_group, criterion_main}; -use moq_sign::{SecretKey, broadcast}; +use moq_crypto::sign::{SecretKey, broadcast}; -fn produce(key: &SecretKey) -> (moq_sign::track::Producer, moq_net::broadcast::Producer) { +fn produce(key: &SecretKey) -> (moq_crypto::sign::track::Producer, moq_net::broadcast::Producer) { // A zero max age keeps only the newest group cached. let info = moq_net::track::Info::default().with_max_age(Duration::ZERO); let inner = moq_net::broadcast::Info::new().produce(); @@ -24,8 +24,8 @@ fn produce(key: &SecretKey) -> (moq_sign::track::Producer, moq_net::broadcast::P async fn roundtrip( key: &SecretKey, ) -> ( - moq_sign::track::Producer, - moq_sign::track::Consumer, + moq_crypto::sign::track::Producer, + moq_crypto::sign::track::Consumer, moq_net::origin::Publication, ) { let (origin, driver) = moq_net::origin::Producer::new(moq_net::origin::Config::default()); diff --git a/rs/moq-e2ee/src/broadcast.rs b/rs/moq-crypto/src/e2ee/broadcast.rs similarity index 97% rename from rs/moq-e2ee/src/broadcast.rs rename to rs/moq-crypto/src/e2ee/broadcast.rs index 72ddf0d0f18..42abf367a62 100644 --- a/rs/moq-e2ee/src/broadcast.rs +++ b/rs/moq-crypto/src/e2ee/broadcast.rs @@ -6,14 +6,14 @@ use std::task::{Poll, ready}; -use crate::error::{Error, Result}; -use crate::{Name, generation, track}; +use crate::e2ee::error::{Error, Result}; +use crate::e2ee::{Name, generation, track}; /// The publishing side of a protected broadcast. /// -/// Wraps the `moq-net` broadcast at [`Credential::path`](crate::Credential::path). Announce that +/// Wraps the `moq-net` broadcast at [`Credential::path`](crate::e2ee::Credential::path). Announce that /// broadcast with [`generation().epoch()`](generation::Producer::epoch)'s -/// [`instance`](crate::Epoch::instance) on its route once the tracks a subscriber needs first +/// [`instance`](crate::e2ee::Epoch::instance) on its route once the tracks a subscriber needs first /// exist. #[derive(Clone)] pub struct Producer { @@ -256,7 +256,7 @@ impl Lister { /// The subscribing side of a protected broadcast. /// -/// Wraps the `moq-net` broadcast found at [`Credential::path`](crate::Credential::path), bound to +/// Wraps the `moq-net` broadcast found at [`Credential::path`](crate::e2ee::Credential::path), bound to /// the epoch on its route. #[derive(Clone)] pub struct Consumer { diff --git a/rs/moq-e2ee/src/credential.rs b/rs/moq-crypto/src/e2ee/credential.rs similarity index 96% rename from rs/moq-e2ee/src/credential.rs rename to rs/moq-crypto/src/e2ee/credential.rs index 7a3003d294f..59d2303e851 100644 --- a/rs/moq-e2ee/src/credential.rs +++ b/rs/moq-crypto/src/e2ee/credential.rs @@ -9,10 +9,10 @@ use bytes::Bytes; use rind::hkdf; use zeroize::{Zeroize, ZeroizeOnDrop}; -use crate::Epoch; -use crate::error::{Error, Result}; -use crate::generation; -use crate::limits::{PATH_LABEL, PATH_LEN, PROFILE, SECRET_LEN, check_bytes, check_u53}; +use crate::e2ee::Epoch; +use crate::e2ee::error::{Error, Result}; +use crate::e2ee::generation; +use crate::e2ee::limits::{PATH_LABEL, PATH_LEN, PROFILE, SECRET_LEN, check_bytes, check_u53}; /// What the application distributes over its own authenticated channel. pub struct Config { diff --git a/rs/moq-e2ee/src/datagram.rs b/rs/moq-crypto/src/e2ee/datagram.rs similarity index 100% rename from rs/moq-e2ee/src/datagram.rs rename to rs/moq-crypto/src/e2ee/datagram.rs diff --git a/rs/moq-e2ee/src/epoch.json b/rs/moq-crypto/src/e2ee/epoch.json similarity index 100% rename from rs/moq-e2ee/src/epoch.json rename to rs/moq-crypto/src/e2ee/epoch.json diff --git a/rs/moq-e2ee/src/epoch.rs b/rs/moq-crypto/src/e2ee/epoch.rs similarity index 97% rename from rs/moq-e2ee/src/epoch.rs rename to rs/moq-crypto/src/e2ee/epoch.rs index 881eff38bea..f17812f0064 100644 --- a/rs/moq-e2ee/src/epoch.rs +++ b/rs/moq-crypto/src/e2ee/epoch.rs @@ -83,7 +83,7 @@ mod tests { assert!(Epoch::mint() > epoch); } - /// Shared with `js/e2ee/src/epoch.test.ts`, so both parse and order alike. + /// Shared with `js/crypto/src/e2ee/epoch.test.ts`, so both parse and order alike. #[test] fn epoch_vectors() { let vectors: serde_json::Value = serde_json::from_str(include_str!("epoch.json")).unwrap(); diff --git a/rs/moq-e2ee/src/error.rs b/rs/moq-crypto/src/e2ee/error.rs similarity index 94% rename from rs/moq-e2ee/src/error.rs rename to rs/moq-crypto/src/e2ee/error.rs index db51a762c86..81c87068898 100644 --- a/rs/moq-e2ee/src/error.rs +++ b/rs/moq-crypto/src/e2ee/error.rs @@ -33,5 +33,5 @@ pub enum Error { Net(#[from] moq_net::Error), } -/// A [`Result`](std::result::Result) using this crate's [`Error`]. +/// A [`Result`](std::result::Result) using this module's [`Error`]. pub type Result = std::result::Result; diff --git a/rs/moq-e2ee/src/generation.rs b/rs/moq-crypto/src/e2ee/generation.rs similarity index 87% rename from rs/moq-e2ee/src/generation.rs rename to rs/moq-crypto/src/e2ee/generation.rs index b16028b1719..fd6b57a90c8 100644 --- a/rs/moq-e2ee/src/generation.rs +++ b/rs/moq-crypto/src/e2ee/generation.rs @@ -4,13 +4,13 @@ use std::collections::HashMap; use std::fmt; use std::sync::{Arc, Mutex}; -use crate::Epoch; -use crate::credential::{Credential, append_bytes}; -use crate::error::Result; -use crate::key::TrackKey; -use crate::limits::{KEY_LABEL, NAME_KEY_LABEL, NAME_MAC_LABEL}; -use crate::name::{self, Name}; -use crate::track; +use crate::e2ee::Epoch; +use crate::e2ee::credential::{Credential, append_bytes}; +use crate::e2ee::error::Result; +use crate::e2ee::key::TrackKey; +use crate::e2ee::limits::{KEY_LABEL, NAME_KEY_LABEL, NAME_MAC_LABEL}; +use crate::e2ee::name::{self, Name}; +use crate::e2ee::track; use rind::{aead, hmac}; /// Grouped-frame versus datagram key domain. @@ -39,8 +39,8 @@ struct Inner { /// A discovered epoch cannot produce tracks: /// /// ```compile_fail -/// fn encrypt(generation: moq_e2ee::generation::Consumer, broadcast: moq_net::broadcast::Producer) { -/// moq_e2ee::broadcast::Producer::new(broadcast, generation); +/// fn encrypt(generation: moq_crypto::e2ee::generation::Consumer, broadcast: moq_net::broadcast::Producer) { +/// moq_crypto::e2ee::broadcast::Producer::new(broadcast, generation); /// } /// ``` #[derive(Clone)] @@ -83,7 +83,7 @@ impl Consumer { /// /// # Errors /// - /// [`Error::Identity`](crate::Error::Identity) if `semantic` exceeds 65535 bytes. + /// [`Error::Identity`](crate::e2ee::Error::Identity) if `semantic` exceeds 65535 bytes. pub fn name(&self, semantic: &str) -> Result { self.0.names.seal(semantic) } @@ -92,7 +92,7 @@ impl Consumer { /// /// # Errors /// - /// [`Error::Identity`](crate::Error::Identity) if `semantic` exceeds 65535 bytes. + /// [`Error::Identity`](crate::e2ee::Error::Identity) if `semantic` exceeds 65535 bytes. pub(crate) fn consume(&self, track: moq_net::track::Subscriber, semantic: &str) -> Result { Ok(track::Consumer::new(track, self.keys(semantic)?)) } @@ -194,7 +194,7 @@ impl Producer { /// /// # Errors /// - /// [`Error::Authentication`](crate::Error::Authentication) if this generation did not issue `name`. + /// [`Error::Authentication`](crate::e2ee::Error::Authentication) if this generation did not issue `name`. pub(crate) fn open(&self, name: &Name) -> Result { self.consumer.0.names.open(name) } @@ -203,7 +203,7 @@ impl Producer { /// /// # Errors /// - /// [`Error::Identity`](crate::Error::Identity) if `semantic` exceeds 65535 bytes, and then `track` is aborted. + /// [`Error::Identity`](crate::e2ee::Error::Identity) if `semantic` exceeds 65535 bytes, and then `track` is aborted. pub(crate) fn produce(&self, track: moq_net::track::Producer, semantic: &str) -> Result { match self.claim(semantic) { Ok(keys) => Ok(track::Producer::new(track, keys)), @@ -220,7 +220,7 @@ impl Producer { /// /// # Errors /// - /// [`Error::Identity`](crate::Error::Identity) if `semantic` exceeds 65535 bytes. + /// [`Error::Identity`](crate::e2ee::Error::Identity) if `semantic` exceeds 65535 bytes. pub(crate) fn claim(&self, semantic: &str) -> Result { self.consumer.keys(semantic) } @@ -230,7 +230,7 @@ impl Producer { /// /// # Errors /// - /// [`Error::Identity`](crate::Error::Identity) if `semantic` exceeds 65535 bytes. + /// [`Error::Identity`](crate::e2ee::Error::Identity) if `semantic` exceeds 65535 bytes. pub(crate) fn peek(&self, semantic: &str) -> Result { if let Some(keys) = self.consumer.0.keys.lock().expect("generation keys").get(semantic) { return Ok(keys.clone()); diff --git a/rs/moq-e2ee/src/group.rs b/rs/moq-crypto/src/e2ee/group.rs similarity index 90% rename from rs/moq-e2ee/src/group.rs rename to rs/moq-crypto/src/e2ee/group.rs index 012e2d32a5a..f0b94d601ec 100644 --- a/rs/moq-e2ee/src/group.rs +++ b/rs/moq-crypto/src/e2ee/group.rs @@ -6,10 +6,10 @@ use std::task::{Poll, ready}; use bytes::Bytes; -use crate::error::{Error, Result}; -use crate::key::TrackKey; -use crate::limits::MAX_GROUPED_PAYLOAD; -use crate::terminal::Terminal; +use crate::e2ee::error::{Error, Result}; +use crate::e2ee::key::TrackKey; +use crate::e2ee::limits::MAX_GROUPED_PAYLOAD; +use crate::e2ee::terminal::Terminal; /// A decrypted grouped frame. #[derive(Clone, Debug, PartialEq, Eq)] @@ -26,16 +26,19 @@ pub struct Frame { pub struct Producer { // The error that aborted the group once a write failed after encryption. inner: std::result::Result, + // The parent track's info, which rescales each timestamp before it is encrypted. + track: moq_net::track::Info, sequence: u64, key: Arc>, next_frame: u32, } impl Producer { - pub(crate) fn new(inner: moq_net::group::Producer, key: Arc>) -> Self { + pub(crate) fn new(inner: moq_net::group::Producer, track: moq_net::track::Info, key: Arc>) -> Self { Self { sequence: inner.sequence, inner: Ok(inner), + track, key, next_frame: 0, } @@ -64,22 +67,13 @@ impl Producer { /// [`Error::Identity`] if the next frame exceeds 32 bits, [`Error::Exhausted`], /// [`Error::Oversize`], or a net write error. pub fn write_frame(&mut self, timestamp: impl Into>, plaintext: &[u8]) -> Result<()> { - let timestamp = timestamp.into(); let inner = self.inner.as_mut().map_err(|err| err.clone())?; let frame = self.next_frame; if frame == u32::MAX { return Err(Error::Identity); } - // Checked before the frame identity is spent: a track is all timed or all untimed. - match (timestamp, inner.timescale()) { - (Some(timestamp), Some(timescale)) => { - timestamp - .convert(timescale) - .map_err(|_| Error::Net(moq_net::Error::TimestampMismatch))?; - } - (None, None) => {} - _ => return Err(Error::Net(moq_net::Error::TimestampMismatch)), - } + // Checked before the frame identity is spent. + let timestamp = self.track.rescale(timestamp.into())?; let payload = self.key.lock().expect("track key").protect( self.sequence, u64::from(frame), diff --git a/rs/moq-e2ee/src/key.rs b/rs/moq-crypto/src/e2ee/key.rs similarity index 94% rename from rs/moq-e2ee/src/key.rs rename to rs/moq-crypto/src/e2ee/key.rs index 125d3514ebf..5eb308aa72f 100644 --- a/rs/moq-e2ee/src/key.rs +++ b/rs/moq-crypto/src/e2ee/key.rs @@ -3,9 +3,9 @@ use std::fmt; use bytes::Bytes; use rind::aead; -use crate::error::{Error, Result}; -use crate::limits::{MAX_INVOCATIONS, MAX_PLAINTEXT_BYTES, TAG_LEN}; -use crate::protect::{nonce, open, protect}; +use crate::e2ee::error::{Error, Result}; +use crate::e2ee::limits::{MAX_INVOCATIONS, MAX_PLAINTEXT_BYTES, TAG_LEN}; +use crate::e2ee::protect::{nonce, open, protect}; /// Per-track, per-domain AES-128-GCM key with invocation and byte accounting. /// diff --git a/rs/moq-e2ee/src/limits.rs b/rs/moq-crypto/src/e2ee/limits.rs similarity index 92% rename from rs/moq-e2ee/src/limits.rs rename to rs/moq-crypto/src/e2ee/limits.rs index c465668b993..448114db925 100644 --- a/rs/moq-e2ee/src/limits.rs +++ b/rs/moq-crypto/src/e2ee/limits.rs @@ -61,17 +61,17 @@ pub(crate) const DATAGRAM_WINDOW: u64 = 1024; /// Maximum length of a `bytes` field: context, epoch, or semantic name. pub(crate) const MAX_BYTES: usize = 0xffff; -pub(crate) fn check_u53(value: u64) -> crate::Result<()> { +pub(crate) fn check_u53(value: u64) -> crate::e2ee::Result<()> { if value > MAX_U53 { - Err(crate::Error::Identity) + Err(crate::e2ee::Error::Identity) } else { Ok(()) } } -pub(crate) fn check_bytes(len: usize) -> crate::Result<()> { +pub(crate) fn check_bytes(len: usize) -> crate::e2ee::Result<()> { if len > MAX_BYTES { - Err(crate::Error::Identity) + Err(crate::e2ee::Error::Identity) } else { Ok(()) } diff --git a/rs/moq-crypto/src/e2ee/mod.rs b/rs/moq-crypto/src/e2ee/mod.rs new file mode 100644 index 00000000000..b2b6697694c --- /dev/null +++ b/rs/moq-crypto/src/e2ee/mod.rs @@ -0,0 +1,52 @@ +//! End-to-end encryption for MoQ groups, datagrams, and track names. +//! +//! Implements profile `moq-e2ee-00` from [draft-lcurley-moq-e2ee]. Relays forward +//! ciphertext; content keys never enter `moq-net`. +//! +//! [draft-lcurley-moq-e2ee]: https://datatracker.ietf.org/doc/draft-lcurley-moq-e2ee/ +//! +//! A [`Credential`] is what the application distributes out of band. Each publisher +//! instance calls [`Credential::produce`] to mint a [`generation::Producer`] and wraps its +//! `moq-net` broadcast in a [`broadcast::Producer`], announcing the generation's +//! [`Epoch::instance`] on its route. Subscribers follow the path, read each instance's +//! epoch with [`Epoch::of`] from the broadcast it resolved, bind a [`generation::Consumer`] with +//! [`Credential::consume`], and wrap the broadcast in a [`broadcast::Consumer`]. Both sides name tracks by their semantic names; only +//! the derived physical names reach `moq-net`. +//! +//! A caller cannot reopen an explicit epoch for production: +//! +//! ```compile_fail,E0624 +//! fn reopen(credential: moq_crypto::e2ee::Credential, epoch: moq_crypto::e2ee::Epoch) { +//! let _ = moq_crypto::e2ee::generation::Producer::new(credential, epoch); +//! } +//! ``` +//! +//! AES-128-GCM is inline and synchronous: a 1 KiB frame costs about a microsecond +//! on one core (see the `protect` bench), so there is no async encryption pump. + +#![warn(missing_docs)] + +pub mod broadcast; +pub mod credential; +pub mod datagram; +mod epoch; +pub mod group; +pub mod track; + +mod error; +pub mod generation; +mod key; +mod limits; +mod name; +mod protect; +mod terminal; +mod window; + +pub use credential::Credential; +pub use epoch::{Epoch, InvalidEpoch}; +pub use error::{Error, Result}; +pub use limits::{MAX_DATAGRAM_PLAINTEXT, MAX_GROUPED_PLAINTEXT, SECRET_LEN}; +pub use name::Name; + +#[cfg(test)] +mod tests; diff --git a/rs/moq-e2ee/src/name.rs b/rs/moq-crypto/src/e2ee/name.rs similarity index 97% rename from rs/moq-e2ee/src/name.rs rename to rs/moq-crypto/src/e2ee/name.rs index 9ff0c88015d..b3865106ddf 100644 --- a/rs/moq-e2ee/src/name.rs +++ b/rs/moq-crypto/src/e2ee/name.rs @@ -5,8 +5,8 @@ use base64::Engine; use base64::engine::general_purpose::URL_SAFE_NO_PAD; use rind::{aead, hmac}; -use crate::error::{Error, Result}; -use crate::limits::{NAME_BLOCK, NAME_NONCE_LEN, TAG_LEN, check_bytes}; +use crate::e2ee::error::{Error, Result}; +use crate::e2ee::limits::{NAME_BLOCK, NAME_NONCE_LEN, TAG_LEN, check_bytes}; /// An opaque physical track name: unpadded base64url of a semantic name sealed under its generation. #[derive(Clone, PartialEq, Eq, Hash)] diff --git a/rs/moq-e2ee/src/protect.rs b/rs/moq-crypto/src/e2ee/protect.rs similarity index 95% rename from rs/moq-e2ee/src/protect.rs rename to rs/moq-crypto/src/e2ee/protect.rs index e8143854b74..f716fa89ffd 100644 --- a/rs/moq-e2ee/src/protect.rs +++ b/rs/moq-crypto/src/e2ee/protect.rs @@ -1,8 +1,8 @@ use bytes::Bytes; use rind::aead; -use crate::error::{Error, Result}; -use crate::limits::{TAG_LEN, check_u53}; +use crate::e2ee::error::{Error, Result}; +use crate::e2ee::limits::{TAG_LEN, check_u53}; /// 96-bit AES-GCM nonce: `u64(group) || u32(frame)`. pub(crate) fn nonce(group: u64, frame: u64) -> Result<[u8; 12]> { diff --git a/rs/moq-e2ee/src/terminal.rs b/rs/moq-crypto/src/e2ee/terminal.rs similarity index 98% rename from rs/moq-e2ee/src/terminal.rs rename to rs/moq-crypto/src/e2ee/terminal.rs index 391ef7afd62..bc98c89ea48 100644 --- a/rs/moq-e2ee/src/terminal.rs +++ b/rs/moq-crypto/src/e2ee/terminal.rs @@ -7,7 +7,7 @@ use std::sync::{Arc, Mutex}; use std::task::Poll; -use crate::error::{Error, Result}; +use crate::e2ee::error::{Error, Result}; pub(crate) struct Terminal { flag: kio::Producer, diff --git a/rs/moq-e2ee/src/tests.rs b/rs/moq-crypto/src/e2ee/tests.rs similarity index 96% rename from rs/moq-e2ee/src/tests.rs rename to rs/moq-crypto/src/e2ee/tests.rs index 18fee02477b..77891114bea 100644 --- a/rs/moq-e2ee/src/tests.rs +++ b/rs/moq-crypto/src/e2ee/tests.rs @@ -9,19 +9,19 @@ use bytes::Bytes; use rind::{aead, hmac}; use serde_json::Value; -use crate::Epoch; -use crate::credential::{Config, Credential}; -use crate::datagram::Event; -use crate::error::Error; -use crate::generation::{Consumer, Domain, Producer, name_key_info, name_mac_info}; -use crate::limits::{ +use crate::e2ee::Epoch; +use crate::e2ee::credential::{Config, Credential}; +use crate::e2ee::datagram::Event; +use crate::e2ee::error::Error; +use crate::e2ee::generation::{Consumer, Domain, Producer, name_key_info, name_mac_info}; +use crate::e2ee::limits::{ DATAGRAM_WINDOW, KEY_LABEL, MAX_DATAGRAM_BODY, MAX_DATAGRAM_HEADER, MAX_DATAGRAM_PAYLOAD, MAX_DATAGRAM_PLAINTEXT, MAX_GROUPED_PAYLOAD, MAX_GROUPED_PLAINTEXT, MAX_INVOCATIONS, MAX_PLAINTEXT_BYTES, MAX_U53, NAME_BLOCK, NAME_KEY_LABEL, NAME_MAC_LABEL, NAME_NONCE_LEN, PATH_LABEL, PATH_LEN, PROFILE, SECRET_LEN, TAG_LEN, }; -use crate::name::{Name, pad}; -use crate::protect::{nonce, protect}; -use crate::{group, track}; +use crate::e2ee::name::{Name, pad}; +use crate::e2ee::protect::{nonce, protect}; +use crate::e2ee::{group, track}; /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { @@ -32,7 +32,7 @@ fn timed() -> moq_net::track::Info { const KEY_LEN: usize = 16; const NAME_MAC_LEN: usize = 32; -const VECTORS: &str = include_str!("../../../drafts/moq-e2ee-00.json"); +const VECTORS: &str = include_str!("../../../../drafts/moq-e2ee-00.json"); fn vectors() -> Value { serde_json::from_str(VECTORS).unwrap() @@ -490,6 +490,19 @@ fn oversize_datagram_keeps_the_sequence() { assert_eq!(pair.producer.append_datagram(ms(1), &max).unwrap(), 0); } +#[test] +fn refused_datagram_timestamp_keeps_the_sequence() { + let mut pair = pair("audio"); + // (2^61-1) seconds overflows conversion to the milli-scale track. + let huge = moq_net::Timestamp::from_secs((1 << 61) - 1).unwrap(); + for timestamp in [None, Some(huge)] { + let err = pair.producer.append_datagram(timestamp, b"x").unwrap_err(); + assert!(matches!(err, Error::Net(moq_net::Error::TimestampMismatch)), "{err:?}"); + } + assert_eq!(pair.producer.datagram_invocations(), 0); + assert_eq!(pair.producer.append_datagram(ms(1), b"x").unwrap(), 0); +} + #[test] fn reproduced_track_resumes_above_its_marks() { let generation = test_generation(); @@ -553,8 +566,8 @@ fn refused_track_is_aborted() { /// One broadcast seen through the wrappers and, raw, the way a relay sees it. struct Protected { - producer: crate::broadcast::Producer, - consumer: crate::broadcast::Consumer, + producer: crate::e2ee::broadcast::Producer, + consumer: crate::e2ee::broadcast::Consumer, raw: moq_net::broadcast::Consumer, } @@ -562,9 +575,9 @@ fn protected() -> Protected { let generation = test_generation(); let net = moq_net::broadcast::Info::new().produce(); Protected { - consumer: crate::broadcast::Consumer::new(net.consume(), consume(&generation)), + consumer: crate::e2ee::broadcast::Consumer::new(net.consume(), consume(&generation)), raw: net.consume(), - producer: crate::broadcast::Producer::new(net, generation), + producer: crate::e2ee::broadcast::Producer::new(net, generation), } } @@ -622,14 +635,14 @@ fn reserved_track_serves_on_demand() { #[test] fn broadcast_claims_span_outputs() { let generation = test_generation(); - let first = crate::broadcast::Producer::new(moq_net::broadcast::Info::new().produce(), generation.clone()); + let first = crate::e2ee::broadcast::Producer::new(moq_net::broadcast::Info::new().produce(), generation.clone()); let mut video = first.create_track("video", timed()).unwrap(); video.create_group(2).unwrap(); let mut audio = first.reserve_track("audio").unwrap().accept(timed()); audio.append_datagram(ms(1), b"opus").unwrap(); // A clone of the generation on another output resumes either name above its marks. - let second = crate::broadcast::Producer::new(moq_net::broadcast::Info::new().produce(), generation); + let second = crate::e2ee::broadcast::Producer::new(moq_net::broadcast::Info::new().produce(), generation); let mut video = second.create_track("video", timed()).unwrap(); assert_eq!(video.append_group().unwrap().sequence(), 3); let request = second.reserve_track("audio").unwrap(); @@ -650,7 +663,7 @@ fn recovery_claims_nothing() { } /// Poll a handler once, expecting a request. -fn requested(requests: &mut crate::broadcast::Requests) -> track::Request { +fn requested(requests: &mut crate::e2ee::broadcast::Requests) -> track::Request { match requests.poll_requested_track(&kio::Waiter::noop()) { Poll::Ready(Ok(request)) => request, other => panic!("expected a request, got {other:?}"), @@ -761,7 +774,7 @@ fn requests_claim_only_accepted_names() { let _ = subscribing.poll_ok(&kio::Waiter::noop()); let request = requested(&mut requests); assert_eq!(generation.claims(), 0); - let other = crate::broadcast::Producer::new(moq_net::broadcast::Info::new().produce(), generation.clone()); + let other = crate::e2ee::broadcast::Producer::new(moq_net::broadcast::Info::new().produce(), generation.clone()); other.create_track("video", timed()).unwrap().create_group(5).unwrap(); let mut video = request.accept(timed()); assert_eq!(generation.claims(), 1); @@ -1352,7 +1365,7 @@ fn resumed_group_opens_at_transport_index() { }; net_group.skip_to(1); let key = Arc::new(Mutex::new(consume(&generation).key("video", Domain::Group).unwrap())); - let mut group = group::Consumer::new(net_group, key, crate::terminal::Terminal::new(None)); + let mut group = group::Consumer::new(net_group, key, crate::e2ee::terminal::Terminal::new(None)); assert_eq!(read_frame(&mut group).plaintext, &b"one"[..]); } diff --git a/rs/moq-e2ee/src/track.rs b/rs/moq-crypto/src/e2ee/track.rs similarity index 92% rename from rs/moq-e2ee/src/track.rs rename to rs/moq-crypto/src/e2ee/track.rs index 7343dbea3c1..60994a7ef3d 100644 --- a/rs/moq-e2ee/src/track.rs +++ b/rs/moq-crypto/src/e2ee/track.rs @@ -4,13 +4,13 @@ use std::fmt; use std::sync::{Arc, Mutex}; use std::task::{Poll, ready}; -use crate::datagram::{Datagram, Event}; -use crate::error::{Error, Result}; -use crate::group; -use crate::key::TrackKey; -use crate::limits::{MAX_DATAGRAM_PAYLOAD, check_u53}; -use crate::terminal::Terminal; -use crate::window::DatagramWindow; +use crate::e2ee::datagram::{Datagram, Event}; +use crate::e2ee::error::{Error, Result}; +use crate::e2ee::group; +use crate::e2ee::key::TrackKey; +use crate::e2ee::limits::{MAX_DATAGRAM_PAYLOAD, check_u53}; +use crate::e2ee::terminal::Terminal; +use crate::e2ee::window::DatagramWindow; /// Exclusive producer for one physical track. /// @@ -82,7 +82,11 @@ impl Producer { sequence }; let inner = self.inner.create_group(moq_net::group::Info { sequence })?; - Ok(group::Producer::new(inner, Arc::clone(&self.keys.group))) + Ok(group::Producer::new( + inner, + self.inner.info().clone(), + Arc::clone(&self.keys.group), + )) } /// Encrypt `plaintext` at the next sequence and insert the datagram, returning that sequence. @@ -100,7 +104,7 @@ impl Producer { /// Encrypt `plaintext` at an explicit sequence and insert the datagram. /// - /// Plaintext is capped at [`MAX_DATAGRAM_PLAINTEXT`](crate::MAX_DATAGRAM_PLAINTEXT). + /// Plaintext is capped at [`MAX_DATAGRAM_PLAINTEXT`](crate::e2ee::MAX_DATAGRAM_PLAINTEXT). /// A predictable failure is refused before the sequence is allocated; once /// encrypted, the identity is spent even if the net write fails. /// @@ -124,6 +128,8 @@ impl Producer { timestamp: Option, plaintext: &[u8], ) -> Result { + // Checked before the sequence is spent. + let timestamp = self.inner.info().rescale(timestamp)?; // Held across encryption, so another producer of this name cannot take the sequence. let (sequence, payload) = { let mut next = self.keys.next.lock().expect("track sequence"); @@ -189,15 +195,15 @@ fn reserve(next: u64, sequence: Option) -> Result { /// A requested or reserved track its subscribers wait on until it is accepted. /// -/// Yielded by [`broadcast::Requests::poll_requested_track`](crate::broadcast::Requests::poll_requested_track) -/// or made by [`broadcast::Producer::reserve_track`](crate::broadcast::Producer::reserve_track), +/// Yielded by [`broadcast::Requests::poll_requested_track`](crate::e2ee::broadcast::Requests::poll_requested_track) +/// or made by [`broadcast::Producer::reserve_track`](crate::e2ee::broadcast::Producer::reserve_track), /// which claims its name up front. A requested name is claimed only once accepted, so a /// subscriber cannot make the publisher hold names it never serves. Accept it once its /// [`demand`](Self::demand) shows a subscriber, or up front. Dropping it without /// [`accept`](Self::accept) rejects the waiting subscribers. pub struct Request { inner: moq_net::track::Request, - generation: crate::generation::Producer, + generation: crate::e2ee::generation::Producer, // From `generation::Producer::peek` or `claim`; claimed by `accept`. keys: Keys, semantic: String, @@ -206,7 +212,7 @@ pub struct Request { impl Request { pub(crate) fn new( inner: moq_net::track::Request, - generation: crate::generation::Producer, + generation: crate::e2ee::generation::Producer, keys: Keys, semantic: String, ) -> Self { @@ -246,11 +252,11 @@ impl fmt::Debug for Request { } } -/// The pollable state of a [`broadcast::Consumer::subscribe`](crate::broadcast::Consumer::subscribe); +/// The pollable state of a [`broadcast::Consumer::subscribe`](crate::e2ee::broadcast::Consumer::subscribe); /// awaited via the [`kio::Pending`] wrapper, whose `DerefMut` exposes [`Self::update`]. pub struct Subscribing { inner: kio::Pending, - generation: crate::generation::Consumer, + generation: crate::e2ee::generation::Consumer, // Keys derive from the name subscribed to, never from the name a relay hands back. semantic: String, } @@ -258,7 +264,7 @@ pub struct Subscribing { impl Subscribing { pub(crate) fn new( inner: kio::Pending, - generation: crate::generation::Consumer, + generation: crate::e2ee::generation::Consumer, semantic: String, ) -> Self { Self { diff --git a/rs/moq-e2ee/src/window.rs b/rs/moq-crypto/src/e2ee/window.rs similarity index 98% rename from rs/moq-e2ee/src/window.rs rename to rs/moq-crypto/src/e2ee/window.rs index 467a8f4985e..1f3a69bdf5a 100644 --- a/rs/moq-e2ee/src/window.rs +++ b/rs/moq-crypto/src/e2ee/window.rs @@ -1,4 +1,4 @@ -use crate::limits::DATAGRAM_WINDOW; +use crate::e2ee::limits::DATAGRAM_WINDOW; /// Datagram duplicate suppression: a 1024-bit sliding bitmask below the greatest opened sequence. /// diff --git a/rs/moq-crypto/src/lib.rs b/rs/moq-crypto/src/lib.rs new file mode 100644 index 00000000000..e33db807d36 --- /dev/null +++ b/rs/moq-crypto/src/lib.rs @@ -0,0 +1,11 @@ +//! Content signing and end-to-end encryption for MoQ. +//! +//! [`sign`] signs every grouped frame so a relay can proxy and cache a broadcast without +//! forging it. [`e2ee`] encrypts groups, datagrams, and track names so a relay forwards +//! ciphertext it cannot read. Both wrap `moq-net` and check a frame's timestamp with +//! [`moq_net::track::Info::rescale`], so neither accepts a frame the net track would refuse. + +#![warn(missing_docs)] + +pub mod e2ee; +pub mod sign; diff --git a/rs/moq-sign/src/broadcast.rs b/rs/moq-crypto/src/sign/broadcast.rs similarity index 96% rename from rs/moq-sign/src/broadcast.rs rename to rs/moq-crypto/src/sign/broadcast.rs index 3c626c1d1be..7a5c1372d01 100644 --- a/rs/moq-sign/src/broadcast.rs +++ b/rs/moq-crypto/src/sign/broadcast.rs @@ -6,10 +6,10 @@ use std::collections::HashMap; use std::sync::{Arc, Mutex}; -use crate::error::{Error, Result}; -use crate::key::{PublicKey, SecretKey}; -use crate::scope::Scope; -use crate::track; +use crate::sign::error::{Error, Result}; +use crate::sign::key::{PublicKey, SecretKey}; +use crate::sign::scope::Scope; +use crate::sign::track; /// The publishing side of a signed broadcast. /// diff --git a/rs/moq-sign/src/error.rs b/rs/moq-crypto/src/sign/error.rs similarity index 89% rename from rs/moq-sign/src/error.rs rename to rs/moq-crypto/src/sign/error.rs index 24d022ad9db..9ff1974d2af 100644 --- a/rs/moq-sign/src/error.rs +++ b/rs/moq-crypto/src/sign/error.rs @@ -15,5 +15,5 @@ pub enum Error { Net(#[from] moq_net::Error), } -/// A [`Result`](std::result::Result) using this crate's [`Error`]. +/// A [`Result`](std::result::Result) using this module's [`Error`]. pub type Result = std::result::Result; diff --git a/rs/moq-sign/src/group.rs b/rs/moq-crypto/src/sign/group.rs similarity index 88% rename from rs/moq-sign/src/group.rs rename to rs/moq-crypto/src/sign/group.rs index f304aab3438..faf09b1d72e 100644 --- a/rs/moq-sign/src/group.rs +++ b/rs/moq-crypto/src/sign/group.rs @@ -6,9 +6,9 @@ use std::task::{Poll, ready}; use bytes::Bytes; -use crate::error::{Error, Result}; -use crate::key::{PublicKey, SecretKey}; -use crate::scope::Scope; +use crate::sign::error::{Error, Result}; +use crate::sign::key::{PublicKey, SecretKey}; +use crate::sign::scope::Scope; /// A grouped frame whose signature verified. #[derive(Clone, Debug, PartialEq, Eq)] @@ -22,13 +22,25 @@ pub struct Frame { /// Exclusive writer for one group, signing each frame at the index it lands on. pub struct Producer { inner: moq_net::group::Producer, + // The parent track's info, which rescales each timestamp before it is signed. + track: moq_net::track::Info, key: SecretKey, scope: Arc, } impl Producer { - pub(crate) fn new(inner: moq_net::group::Producer, key: SecretKey, scope: Arc) -> Self { - Self { inner, key, scope } + pub(crate) fn new( + inner: moq_net::group::Producer, + track: moq_net::track::Info, + key: SecretKey, + scope: Arc, + ) -> Self { + Self { + inner, + track, + key, + scope, + } } /// The group's sequence number. @@ -44,11 +56,7 @@ impl Producer { /// signed frame exceeds the frame size limit. pub fn write_frame(&mut self, timestamp: impl Into>, payload: &[u8]) -> Result<()> { // Signed at the track's timescale, the value the net group stores and every hop carries. - // A frame whose timedness disagrees with the track is left for the write to refuse. - let timestamp = match (timestamp.into(), self.inner.timescale()) { - (Some(at), Some(timescale)) => Some(at.convert(timescale).map_err(|_| moq_net::Error::TimestampMismatch)?), - (timestamp, _) => timestamp, - }; + let timestamp = self.track.rescale(timestamp.into())?; let frame = self.inner.frame_count() as u64; let body = self .scope diff --git a/rs/moq-sign/src/key.rs b/rs/moq-crypto/src/sign/key.rs similarity index 99% rename from rs/moq-sign/src/key.rs rename to rs/moq-crypto/src/sign/key.rs index aa977c818bc..ff87370e844 100644 --- a/rs/moq-sign/src/key.rs +++ b/rs/moq-crypto/src/sign/key.rs @@ -8,7 +8,7 @@ use std::sync::Arc; use aws_lc_rs::signature::{ED25519, Ed25519KeyPair, KeyPair, UnparsedPublicKey}; use zeroize::Zeroizing; -use crate::scope::SIGNATURE_LEN; +use crate::sign::scope::SIGNATURE_LEN; /// Ed25519 key length in bytes, for both the secret seed and the public key. const KEY_LEN: usize = 32; diff --git a/rs/moq-sign/src/lib.rs b/rs/moq-crypto/src/sign/mod.rs similarity index 100% rename from rs/moq-sign/src/lib.rs rename to rs/moq-crypto/src/sign/mod.rs diff --git a/rs/moq-sign/src/scope.rs b/rs/moq-crypto/src/sign/scope.rs similarity index 97% rename from rs/moq-sign/src/scope.rs rename to rs/moq-crypto/src/sign/scope.rs index 67645b6b6cc..c256f5788f2 100644 --- a/rs/moq-sign/src/scope.rs +++ b/rs/moq-crypto/src/sign/scope.rs @@ -4,8 +4,8 @@ use std::sync::Arc; use bytes::{BufMut, Bytes, BytesMut}; -use crate::error::{Error, Result}; -use crate::key::{PublicKey, SecretKey}; +use crate::sign::error::{Error, Result}; +use crate::sign::key::{PublicKey, SecretKey}; /// Length of the Ed25519 signature appended to every signed frame. pub(crate) const SIGNATURE_LEN: usize = 64; diff --git a/rs/moq-sign/src/tests.rs b/rs/moq-crypto/src/sign/tests.rs similarity index 95% rename from rs/moq-sign/src/tests.rs rename to rs/moq-crypto/src/sign/tests.rs index 58ed38af99b..3400c5ba22c 100644 --- a/rs/moq-sign/src/tests.rs +++ b/rs/moq-crypto/src/sign/tests.rs @@ -5,10 +5,10 @@ use bytes::Bytes; use serde_json::Value; use zeroize::Zeroizing; -use crate::scope::Scope; -use crate::{Error, PublicKey, SecretKey, broadcast, group, track}; +use crate::sign::scope::Scope; +use crate::sign::{Error, PublicKey, SecretKey, broadcast, group, track}; -const VECTORS: &str = include_str!("../../../drafts/moq-sign-00.json"); +const VECTORS: &str = include_str!("../../../../drafts/moq-sign-00.json"); fn vectors() -> Value { serde_json::from_str(VECTORS).unwrap() @@ -432,7 +432,7 @@ async fn group_resumed_above_frame_zero_verifies_at_its_index() { let track = broadcast.create_track("stream", None).unwrap(); let net = track.append_group().unwrap(); let raw = net.consume(); - let mut signed = group::Producer::new(net, key.clone(), Arc::clone(&scope)); + let mut signed = group::Producer::new(net, track.info().clone(), key.clone(), Arc::clone(&scope)); signed.write_frame(None, b"zero").unwrap(); signed.write_frame(None, b"one").unwrap(); signed.finish().unwrap(); @@ -509,6 +509,7 @@ fn sign_interop() { }; let stamps = [10, 20, 30]; + let fractional = [1_500, 2_600, 3_000]; let output = bun(serde_json::json!({ "seed": hex::encode(seed.as_ref()), "path": path.as_str(), @@ -519,8 +520,9 @@ fn sign_interop() { sign_group(9, 9, Some((stamps, stamps))), sign_group(10, 10, Some((stamps, [11, 20, 30]))), ], - // Microseconds on a millisecond track: JS signs the rounded value the wire carries. - "js": [write("js", None), write("js", None), write("js-video", Some([2_400, 2_600, 3_000]))], + // Microseconds on a millisecond track: JS signs the value the wire carries, rounded down + // as `track::Info::rescale` rounds it. + "js": [write("js", None), write("js", None), write("js-video", Some(fractional))], })); assert_eq!(output["public"], key.public().to_string()); @@ -561,5 +563,14 @@ fn sign_interop() { .iter() .map(|frame| frame["timestamp"].as_u64().unwrap()) .collect(); - assert_eq!(timed, [2, 3, 3]); + let track = moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI); + let rescaled: Vec = fractional + .iter() + .map(|µs| { + let at = moq_net::Timestamp::from_micros(micros).unwrap(); + track.rescale(Some(at)).unwrap().unwrap().as_millis() as u64 + }) + .collect(); + assert_eq!(timed, rescaled); + assert_eq!(timed, [1, 2, 3]); } diff --git a/rs/moq-sign/src/track.rs b/rs/moq-crypto/src/sign/track.rs similarity index 94% rename from rs/moq-sign/src/track.rs rename to rs/moq-crypto/src/sign/track.rs index b08664b0fea..820344435cc 100644 --- a/rs/moq-sign/src/track.rs +++ b/rs/moq-crypto/src/sign/track.rs @@ -4,10 +4,10 @@ use std::fmt; use std::sync::{Arc, Mutex}; use std::task::{Poll, ready}; -use crate::error::Result; -use crate::group; -use crate::key::{PublicKey, SecretKey}; -use crate::scope::Scope; +use crate::sign::error::Result; +use crate::sign::group; +use crate::sign::key::{PublicKey, SecretKey}; +use crate::sign::scope::Scope; /// Producer for one signed track. /// @@ -76,7 +76,12 @@ impl Producer { } fn group(&self, inner: moq_net::group::Producer) -> group::Producer { - group::Producer::new(inner, self.key.clone(), Arc::clone(&self.scope)) + group::Producer::new( + inner, + self.inner.info().clone(), + self.key.clone(), + Arc::clone(&self.scope), + ) } /// Finish the track after the last group. @@ -106,7 +111,7 @@ impl fmt::Debug for Producer { } } -/// The pollable state of a [`broadcast::Consumer::subscribe`](crate::broadcast::Consumer::subscribe); +/// The pollable state of a [`broadcast::Consumer::subscribe`](crate::sign::broadcast::Consumer::subscribe); /// awaited via the [`kio::Pending`] wrapper, whose `DerefMut` exposes [`Self::update`]. pub struct Subscribing { inner: kio::Pending, diff --git a/rs/moq-e2ee/tests/support/harness.rs b/rs/moq-crypto/tests/support/harness.rs similarity index 100% rename from rs/moq-e2ee/tests/support/harness.rs rename to rs/moq-crypto/tests/support/harness.rs diff --git a/rs/moq-e2ee/tests/support/mod.rs b/rs/moq-crypto/tests/support/mod.rs similarity index 100% rename from rs/moq-e2ee/tests/support/mod.rs rename to rs/moq-crypto/tests/support/mod.rs diff --git a/rs/moq-e2ee/tests/transport.rs b/rs/moq-crypto/tests/transport.rs similarity index 86% rename from rs/moq-e2ee/tests/transport.rs rename to rs/moq-crypto/tests/transport.rs index a79dce71f36..a43973ed8cb 100644 --- a/rs/moq-e2ee/tests/transport.rs +++ b/rs/moq-crypto/tests/transport.rs @@ -4,8 +4,8 @@ mod support; use std::time::Duration; -use moq_e2ee::Credential; -use moq_e2ee::credential::Config; +use moq_crypto::e2ee::Credential; +use moq_crypto::e2ee::credential::Config; use moq_net::{Hop, Timestamp, Version}; use support::harness::{MockConnectOptions, MockPair, connect_mock}; @@ -23,8 +23,8 @@ fn produce_origin(hop: u64) -> moq_net::origin::Producer { } struct Fixture { - producer: moq_e2ee::track::Producer, - consumer: moq_e2ee::track::Consumer, + producer: moq_crypto::e2ee::track::Producer, + consumer: moq_crypto::e2ee::track::Consumer, _broadcast: moq_net::origin::Publication, _pair: MockPair, } @@ -43,7 +43,7 @@ async fn connect_protected(version: Version, track: &str) -> Fixture { let consumer_origin = produce_origin(2); let broadcast = publisher.create_broadcast(&path).unwrap(); - let protected = moq_e2ee::broadcast::Producer::new(broadcast.broadcast().clone(), generation.clone()); + let protected = moq_crypto::e2ee::broadcast::Producer::new(broadcast.broadcast().clone(), generation.clone()); let producer = protected.create_track(track, timed()).unwrap(); broadcast .announce(moq_net::origin::Route::default().with_instance(generation.epoch().instance(), 0)) @@ -60,13 +60,13 @@ async fn connect_protected(version: Version, track: &str) -> Fixture { let remote = consumer.follow(&path, None).unwrap().available().await.unwrap(); if version.to_string().starts_with("moq-lite-07") { assert_eq!( - moq_e2ee::Epoch::of(&remote).as_ref(), + moq_crypto::e2ee::Epoch::of(&remote).as_ref(), Some(generation.epoch()), "lite-07 announces the epoch" ); } - let epoch = moq_e2ee::Epoch::of(&remote).unwrap_or_else(|| generation.epoch().clone()); - let consumer = moq_e2ee::broadcast::Consumer::new(remote, cred.consume(epoch)) + let epoch = moq_crypto::e2ee::Epoch::of(&remote).unwrap_or_else(|| generation.epoch().clone()); + let consumer = moq_crypto::e2ee::broadcast::Consumer::new(remote, cred.consume(epoch)) .subscribe( track, moq_net::track::Subscription::default() @@ -126,7 +126,7 @@ async fn datagram_roundtrip(version: &str, plaintext: &[u8]) { .append_datagram(Timestamp::from_millis(9).unwrap(), plaintext) .unwrap(); match fixture.consumer.recv_datagram().await.unwrap() { - Some(moq_e2ee::datagram::Event::Datagram(d)) => { + Some(moq_crypto::e2ee::datagram::Event::Datagram(d)) => { assert_eq!(&d.plaintext[..], plaintext); assert_eq!(d.sequence, 0); } @@ -145,7 +145,7 @@ async fn datagrams_over_lite() { /// The largest plaintext still fits once lite-07 prefixes the datagram with its Type. #[tokio::test] async fn max_datagram_over_lite_07() { - datagram_roundtrip("moq-lite-07-wip", &[7; moq_e2ee::MAX_DATAGRAM_PLAINTEXT]).await; + datagram_roundtrip("moq-lite-07-wip", &[7; moq_crypto::e2ee::MAX_DATAGRAM_PLAINTEXT]).await; } #[tokio::test] diff --git a/rs/moq-e2ee/Cargo.toml b/rs/moq-e2ee/Cargo.toml index 33ef5d87505..96a0d95ab56 100644 --- a/rs/moq-e2ee/Cargo.toml +++ b/rs/moq-e2ee/Cargo.toml @@ -1,7 +1,6 @@ [package] -publish = false name = "moq-e2ee" -description = "End-to-end encryption for MoQ groups, datagrams, and track names." +description = "Renamed to moq-crypto: end-to-end encryption for MoQ groups, datagrams, and track names" authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" @@ -10,30 +9,11 @@ version = "0.0.11" edition = "2024" rust-version.workspace = true -keywords = ["quic", "http3", "webtransport", "encryption", "live"] +keywords = ["quic", "webtransport", "encryption", "live"] categories = ["cryptography", "multimedia", "network-programming"] -[dependencies] -base64 = { workspace = true } -bytes = { workspace = true } -kio = { workspace = true } -moq-net = { workspace = true } -rind = { workspace = true } -thiserror = { workspace = true } -uuid = { workspace = true } -zeroize = { workspace = true } - [dev-dependencies] -criterion = { package = "bench-harness", path = "../bench-harness" } -hex = { workspace = true } -kio = { workspace = true, features = ["runtime"] } -serde_json = { workspace = true } -tokio = { workspace = true, features = ["macros", "rt", "sync", "time"] } workspace-hack = { path = "../workspace-hack" } -[[bench]] -name = "protect" -harness = false - [lints] workspace = true diff --git a/rs/moq-e2ee/README.md b/rs/moq-e2ee/README.md index 4f847876de8..390a410948a 100644 --- a/rs/moq-e2ee/README.md +++ b/rs/moq-e2ee/README.md @@ -1,53 +1,10 @@ -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/moq-dev/moq/blob/main/LICENSE-MIT) - # moq-e2ee -Workspace-only implementation; this crate is not published. - -End-to-end encryption for [Media over QUIC](https://moq.dev) groups, datagrams, -and track names. Profile `moq-e2ee-00` from -[draft-lcurley-moq-e2ee](https://datatracker.ietf.org/doc/draft-lcurley-moq-e2ee/). - -Relays forward ciphertext. Content keys never enter `moq-net`. - -## Shape - -The application distributes a `Credential { context, kid, secret }` over its own -authenticated channel. `credential.produce()` mints a fresh epoch and returns a -`generation::Producer`, which derives opaque track names and keys for that instance alone. -It accepts no explicit epoch; its clones share permanent track claims. - -The application names tracks by their semantic names. `broadcast::Producer` wraps the -`moq-net` broadcast and creates each track under its physical name, so only physical names -reach the relays. A physical name is the semantic name encrypted under the generation: a relay -learns only its length rounded up to 16 bytes. A track served on demand is reserved with -`reserve_track` and accepted once its demand shows a subscriber. - -```rust -let credential = Credential::new(credential::Config { context, kid, secret })?; -let generation = credential.produce(); -let broadcast = origin.create_broadcast(&credential.path("meeting.hang")?)?; -let protected = broadcast::Producer::new(broadcast.clone(), generation.clone()); -let video = protected.create_track("video", None)?; -broadcast.announce(Route::default().with_instance(generation.epoch().instance(), 0))?; -``` - -A subscriber follows `credential.path(semantic)` with `origin.follow(path, None)`. It takes -each instance's epoch from the broadcast it resolved, `Epoch::of(&broadcast)` (or from the -application's channel on a wire that carries no instance, older than lite-07), so the key always matches the instance -it reads. It binds the epoch with `credential.consume(epoch)` and wraps the broadcast in a -`broadcast::Consumer`. Its `subscribe(semantic, subscription)` opens the track a decrypted -catalog names. A consuming generation cannot produce. Nothing survives a publisher instance: a restart mints a new epoch. -A cloned process image (a `fork` without `exec`, a restored VM snapshot or checkpoint, or a -producing generation copied to another process) is a new instance too: each copy must call -`produce()` itself, since copies of one generation reuse its nonces. - -## Processing - -AES-128-GCM is inline and synchronous. `cargo bench -p moq-e2ee` measures the whole -protected write path, including the `moq-net` group: a 1 KiB grouped frame and a -160-byte Opus-sized datagram each cost a few microseconds on one core, so encryption -is a tiny fraction of real time and there is no async pump. +`moq-e2ee` is now the `e2ee` module of +[`moq-crypto`](https://github.com/moq-dev/moq/tree/main/rs/moq-crypto), which +also holds content signing, and this final release contains no code. -Memory is bounded: a producer retains no ciphertext, and a consumer keeps a 1024-bit -datagram duplicate window below the greatest sequence it opened. +The profile and wire are unchanged. Depend on `moq-crypto` and import from +`moq_crypto::e2ee` in place of `moq_e2ee`; see its +[MIGRATE.md](https://github.com/moq-dev/moq/blob/main/rs/moq-crypto/MIGRATE.md) +for the rest of the changes since `moq-e2ee` 0.0.20. diff --git a/rs/moq-e2ee/src/lib.rs b/rs/moq-e2ee/src/lib.rs index a559dedc4c6..7913c79d6bc 100644 --- a/rs/moq-e2ee/src/lib.rs +++ b/rs/moq-e2ee/src/lib.rs @@ -1,52 +1 @@ -//! End-to-end encryption for MoQ groups, datagrams, and track names. -//! -//! Implements profile `moq-e2ee-00` from [draft-lcurley-moq-e2ee]. Relays forward -//! ciphertext; content keys never enter `moq-net`. -//! -//! [draft-lcurley-moq-e2ee]: https://datatracker.ietf.org/doc/draft-lcurley-moq-e2ee/ -//! -//! A [`Credential`] is what the application distributes out of band. Each publisher -//! instance calls [`Credential::produce`] to mint a [`generation::Producer`] and wraps its -//! `moq-net` broadcast in a [`broadcast::Producer`], announcing the generation's -//! [`Epoch::instance`] on its route. Subscribers follow the path, read each instance's -//! epoch with [`Epoch::of`] from the broadcast it resolved, bind a [`generation::Consumer`] with -//! [`Credential::consume`], and wrap the broadcast in a [`broadcast::Consumer`]. Both sides name tracks by their semantic names; only -//! the derived physical names reach `moq-net`. -//! -//! A caller cannot reopen an explicit epoch for production: -//! -//! ```compile_fail,E0624 -//! fn reopen(credential: moq_e2ee::Credential, epoch: moq_e2ee::Epoch) { -//! let _ = moq_e2ee::generation::Producer::new(credential, epoch); -//! } -//! ``` -//! -//! AES-128-GCM is inline and synchronous: a 1 KiB frame costs about a microsecond -//! on one core (see the `protect` bench), so there is no async encryption pump. - -#![warn(missing_docs)] - -pub mod broadcast; -pub mod credential; -pub mod datagram; -mod epoch; -pub mod group; -pub mod track; - -mod error; -pub mod generation; -mod key; -mod limits; -mod name; -mod protect; -mod terminal; -mod window; - -pub use credential::Credential; -pub use epoch::{Epoch, InvalidEpoch}; -pub use error::{Error, Result}; -pub use limits::{MAX_DATAGRAM_PLAINTEXT, MAX_GROUPED_PLAINTEXT, SECRET_LEN}; -pub use name::Name; - -#[cfg(test)] -mod tests; +#![doc = include_str!("../README.md")] diff --git a/rs/moq-json/src/snapshot/producer.rs b/rs/moq-json/src/snapshot/producer.rs index aa858fba387..66ebd029bdc 100644 --- a/rs/moq-json/src/snapshot/producer.rs +++ b/rs/moq-json/src/snapshot/producer.rs @@ -362,7 +362,7 @@ impl Inner { impl Inner { fn update(&mut self, payload: Timed<&T>) -> Result> { - let timestamp = self.track.on_track(payload.at)?; + let timestamp = self.track.rescale(payload.at)?; // Split the borrow so `frame` can hold the encoder while `track` is written through. let Inner { track, encoder, .. } = self; @@ -436,11 +436,11 @@ impl Track { /// An update checks this before encoding. Found by `write_frame` instead, the mismatch would /// come after a snapshot published its group, leaving an empty newest group in place of the /// last value, and the dropped frame would reset the encoder, rolling a group for nothing. - fn on_track(&self, timestamp: Option) -> Result> { - Ok(moq_net::group::on_track(timestamp, self.inner.info().timescale)?) + fn rescale(&self, timestamp: Option) -> Result> { + Ok(self.inner.info().rescale(timestamp)?) } - /// Write one encoded frame at a timestamp already [on the track](Self::on_track), rolling a + /// Write one encoded frame at a timestamp already [rescaled](Self::rescale) to the track, rolling a /// group when it's a snapshot. fn write(&mut self, timestamp: Option, encoded: &Encoded) -> Result<()> { // Check before touching a group. `write_snapshot` closes the previous group and publishes a diff --git a/rs/moq-json/src/stream/producer.rs b/rs/moq-json/src/stream/producer.rs index c4a6f42ce9c..a5c481f263e 100644 --- a/rs/moq-json/src/stream/producer.rs +++ b/rs/moq-json/src/stream/producer.rs @@ -127,7 +127,7 @@ impl Inner { // A timestamp that doesn't match the track, or that its scale can't hold, is refused before // anything changes: found by `write`, it would be a hole that ends the whole log. - let at = moq_net::group::on_track(payload.at, track.inner.info().timescale)?; + let at = track.inner.info().rescale(payload.at)?; // Encode first, so a value that can't be serialized doesn't publish an empty group that // subscribers would advance into and wait on. Opening the group afterwards is safe because diff --git a/rs/moq-json/src/window/producer.rs b/rs/moq-json/src/window/producer.rs index 5da7a120a93..f155afd4286 100644 --- a/rs/moq-json/src/window/producer.rs +++ b/rs/moq-json/src/window/producer.rs @@ -157,7 +157,7 @@ struct Inner { impl Inner { fn pop(&mut self, count: Timed) -> Result<()> { self.ensure_open()?; - let at = self.track.on_track(count.at)?; + let at = self.track.rescale(count.at)?; let Inner { track, encoder, .. } = self; let Some(frame) = encoder.pop(count.value)? else { @@ -225,7 +225,7 @@ impl Inner { impl Inner { fn push(&mut self, value: Timed<&T>) -> Result<()> { self.ensure_open()?; - let at = self.track.on_track(value.at)?; + let at = self.track.rescale(value.at)?; let Inner { track, encoder, .. } = self; let frame = encoder.push(value.value)?; @@ -255,11 +255,11 @@ impl Track { /// An edit checks this before encoding. Found by `write_frame` instead, the mismatch would /// come after a header published its group, leaving an empty newest group behind, and the /// dropped frame would reset the encoder, rolling a group for an edit that changed nothing. - fn on_track(&self, timestamp: Option) -> Result> { - Ok(moq_net::group::on_track(timestamp, self.inner.info().timescale)?) + fn rescale(&self, timestamp: Option) -> Result> { + Ok(self.inner.info().rescale(timestamp)?) } - /// Write one encoded frame at a timestamp already [on the track](Self::on_track), rolling a + /// Write one encoded frame at a timestamp already [rescaled](Self::rescale) to the track, rolling a /// group when it is a header. fn write(&mut self, timestamp: Option, encoded: &Encoded) -> Result<()> { match encoded.keyframe { diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 2c39bcddc6d..723247be902 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### `group::on_track` is `track::Info::rescale` ([#7702](https://github.com/moq-dev/moq/pull/7702)) + +The free function `moq_net::group::on_track(timestamp, timescale)` is removed. +Call `rescale(timestamp)` on the track's `Info` instead (`track.info().rescale(timestamp)` on a producer); it returns the same result and the same `Error::TimestampMismatch`. + ### `Subscription::max_delay` is `delay: track::Delay` ([#7597](https://github.com/moq-dev/moq/pull/7597)) `track::Subscription` carries a `track::Delay { min, max }` in place of `max_delay`, and `with_max_delay(d)` is `with_delay(Delay)`. diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index fb3f2ee76f2..2b3c4570184 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -1196,7 +1196,7 @@ impl GroupState { /// Record a frame's place in presentation time: the first frame starts the group, /// and later frames can extend a timed group's end. Every frame matches its track - /// ([`on_track`]), so a group never mixes the two. + /// ([`track::Info::rescale`]), so a group never mixes the two. fn stamp(&mut self, timestamp: Option) { self.timeline = match (self.timeline, timestamp) { (Timeline::Timed { start, latest }, Some(timestamp)) => Timeline::Timed { @@ -1364,24 +1364,6 @@ impl Drop for GroupState { } } -/// `timestamp` at the track's `timescale`. -/// -/// A track is all timed or all untimed, so a frame must match it: a timed frame on an -/// untimed track, or an untimed one on a timed track, is [`Error::TimestampMismatch`], -/// as is a timestamp the track's scale can't hold. -/// -/// A writer that changes state before its frame reaches [`Producer::write_frame`], such as -/// publishing a group for it, checks with this first so a refused timestamp changes nothing. -pub fn on_track(timestamp: Option, timescale: Option) -> Result> { - match (timestamp, timescale) { - (Some(timestamp), Some(timescale)) => Ok(Some( - timestamp.convert(timescale).map_err(|_| Error::TimestampMismatch)?, - )), - (None, None) => Ok(None), - _ => Err(Error::TimestampMismatch), - } -} - fn modify(state: &kio::Producer) -> Result> { state.write().map_err(|r| r.abort.clone().unwrap_or(Error::Dropped)) } @@ -1718,7 +1700,7 @@ impl Producer { /// `timestamp` is converted into the parent track's timescale. Pass `None` on an /// untimed track; a frame that doesn't match its track is [`Error::TimestampMismatch`]. pub fn write_frame(&mut self, timestamp: impl Into>, data: B) -> Result<()> { - let timestamp = on_track(timestamp.into(), self.handle.track.timescale)?; + let timestamp = self.handle.track.rescale(timestamp.into())?; let payload = data.into_bytes(); if payload.len() as u64 > MAX_CACHE_BYTES { return Err(Error::FrameTooLarge); @@ -1801,7 +1783,7 @@ impl Producer { /// unless it fails the group: too large, or held differently by another copy. pub fn write_frames(&mut self, frames: &mut frame::Buffer) -> Result<()> { for frame in frames.filled() { - on_track(frame.timestamp, self.handle.track.timescale)?; + self.handle.track.rescale(frame.timestamp)?; if frame.payload.len() as u64 > MAX_CACHE_BYTES { return Err(Error::FrameTooLarge); } @@ -1828,7 +1810,10 @@ impl Producer { let origin = match first { Some(timestamp) => state.check_start( neighbors.as_ref(), - on_track(timestamp, self.handle.track.timescale).expect("timestamp scale checked above"), + self.handle + .track + .rescale(timestamp) + .expect("timestamp scale checked above"), )?, None => state.origin, }; @@ -1858,8 +1843,11 @@ impl Producer { let canonical = state.content.is_some(); let mut prepared = arrayvec::ArrayVec::::new(); for (index, frame) in frames.drain().enumerate() { - let timestamp = - on_track(frame.timestamp, self.handle.track.timescale).expect("timestamp scale checked above"); + let timestamp = self + .handle + .track + .rescale(frame.timestamp) + .expect("timestamp scale checked above"); let (payload, inflated) = match state.flate.is_some() { true => ( deflated.next().expect("one slice per frame"), @@ -1964,7 +1952,7 @@ impl Producer { /// size is only a promise until they arrive. fn open_frame(&mut self, header: frame::Header) -> Result<(frame::Info, FrameBuf, Option)> { let frame = header.info; - let timestamp = on_track(frame.timestamp, self.handle.track.timescale)?; + let timestamp = self.handle.track.rescale(frame.timestamp)?; if frame.size > MAX_CACHE_BYTES || header.inflated.is_some_and(|inflated| inflated > MAX_CACHE_BYTES) { return Err(Error::FrameTooLarge); } diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index f87ab6dfa06..98f989780ea 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -562,7 +562,7 @@ impl Route { /// The highest epoch wins over every older one of the instance, cheaper or not. /// /// Do not start a named instance with `~`: that marks one a relay minted - /// ([`Instance::is_minted`]), which moq-sign refuses to bind and a catalog's instance + /// ([`Instance::is_minted`]), which moq-crypto's signing refuses to bind and a catalog's instance /// check skips. The mark is not refused, since a relay forwarding a route keeps the /// instance it received. pub fn with_instance(mut self, instance: Instance, epoch: u64) -> Self { diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index e7a598b0dba..53923575a2f 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -257,6 +257,23 @@ impl Info { self } + /// `timestamp` at this track's [`timescale`](Self::timescale). + /// + /// A track is all timed or all untimed, so a frame must match it: a timed frame on an + /// untimed track, or an untimed one on a timed track, is [`Error::TimestampMismatch`], + /// as is a timestamp the track's scale can't hold. A writer that changes state before + /// its frame reaches the track, such as signing or encrypting it, rescales first so a + /// refused timestamp changes nothing. + pub fn rescale(&self, timestamp: Option) -> Result> { + match (timestamp, self.timescale) { + (Some(timestamp), Some(timescale)) => Ok(Some( + timestamp.convert(timescale).map_err(|_| Error::TimestampMismatch)?, + )), + (None, None) => Ok(None), + _ => Err(Error::TimestampMismatch), + } + } + /// The original moq-transport publisher's draft, whose timestamps may rewind, or /// `None` for a native moq-lite track. pub(crate) fn ietf(&self) -> Option { @@ -3462,8 +3479,7 @@ impl Producer { let meter = self.stats.meter(); let mut state = self.modify()?; // Normalize into the track's timescale, like frames (see `group::Producer::create_frame`). - let timescale = state.info.as_ref().unwrap().timescale; - let timestamp = group::on_track(timestamp.into(), timescale)?; + let timestamp = state.info.as_ref().unwrap().rescale(timestamp.into())?; let sequence = state.next_sequence()?; if let Some(fin) = state.final_sequence() && sequence >= fin @@ -3526,14 +3542,13 @@ impl Producer { let meter = self.stats.meter(); let mut state = self.modify()?; let info = state.info.as_ref().unwrap(); - let timescale = info.timescale; let status = datagram.wire.as_ref().and_then(|wire| wire.status); // A datagram is its own group, so it compresses alone. A status has no payload. if info.compress && datagram.deflated.is_none() && status.is_none() { datagram.deflated = Some(super::flate::Encoder::new().frame(&datagram.payload)); } if status.is_none_or(|status| status == 0) { - datagram.datagram.timestamp = group::on_track(datagram.timestamp, timescale)?; + datagram.datagram.timestamp = info.rescale(datagram.timestamp)?; } if state.final_sequence().is_some_and(|fin| datagram.sequence >= fin) { return Err(Error::Closed); @@ -3586,8 +3601,7 @@ impl Producer { return Err(Error::FrameTooLarge); } // Checked before the group exists, so a refused frame leaves no empty group behind. - let timescale = self.modify()?.info.as_ref().unwrap().timescale; - let timestamp = group::on_track(timestamp.into(), timescale)?; + let timestamp = self.modify()?.info.as_ref().unwrap().rescale(timestamp.into())?; let mut group = self.append_group()?; if let Err(err) = group.write_frame(timestamp, frame) { // A rewind is only known once the group exists; end it rather than leave it open. @@ -17153,6 +17167,25 @@ mod test { assert!(consumer.next_group().now_or_never().unwrap().unwrap().is_none()); } + #[test] + fn rescale_matches_the_track_timeline() { + let timed = Info::timed(); + let ms = Timestamp::from_micros(2_400).unwrap(); + let rescaled = timed.rescale(Some(ms)).unwrap().unwrap(); + assert_eq!(rescaled, Timestamp::from_millis(2).unwrap()); + // Halfway rounds down too, as `@moq/net`'s `Track.rescale` does. + let half = timed.rescale(Timestamp::from_micros(1_500).ok()).unwrap().unwrap(); + assert_eq!(half, Timestamp::from_millis(1).unwrap()); + assert!(matches!(timed.rescale(None), Err(Error::TimestampMismatch))); + // (2^61-1) seconds overflows conversion to the milli-scale track. + let huge = Timestamp::from_secs((1 << 61) - 1).unwrap(); + assert!(matches!(timed.rescale(Some(huge)), Err(Error::TimestampMismatch))); + + let untimed = Info::default(); + assert_eq!(untimed.rescale(None).unwrap(), None); + assert!(matches!(untimed.rescale(Some(ms)), Err(Error::TimestampMismatch))); + } + #[test] fn write_frame_rejects_an_oversized_frame_before_appending_its_group() { let mut producer = track_producer("test", Info::timed()); diff --git a/rs/moq-sign/README.md b/rs/moq-sign/README.md deleted file mode 100644 index 89e820c7ecd..00000000000 --- a/rs/moq-sign/README.md +++ /dev/null @@ -1,45 +0,0 @@ -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/moq-dev/moq/blob/main/LICENSE-MIT) - -# moq-sign - -Workspace-only implementation; this crate is not published. - -Per-frame Ed25519 signatures for [Media over QUIC](https://moq.dev) broadcasts. Profile -`moq-sign-00` from [draft-lcurley-moq-sign](https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/). - -Relays forward and cache signed frames; they cannot forge, retime, or relocate them. Signatures -authenticate content, not liveness: a relay that recorded an instance can replay it whole. - -## Shape - -An endpoint's `SecretKey` signs; its `PublicKey` is the endpoint ID, displayed as 52 z-base-32 -characters (a DNS label). `SecretKey::load_or_generate(path)` keeps one key for the life of a host, -as 52 z-base-32 characters in a `0600` file it never replaces implicitly. - -`broadcast::Producer` wraps the `moq-net` broadcast, mints a fresh instance, and signs each frame -over the application path, instance, track, group, frame index, and timestamp (at the track's -timescale). Announce the broadcast with that instance on its route: - -```rust -let key = SecretKey::load_or_generate("/var/lib/moq/endpoint.key")?; -let path = moq_net::Path::new(&format!("mesh/{}/agent", key.public()))?; -let publication = origin.create_broadcast(&path)?; -let signed = broadcast::Producer::new(publication.broadcast().clone(), key, path); -let messages = signed.create_track("messages", None)?; -publication.announce(Route::default().with_instance(signed.instance().clone(), 0))?; -``` - -A subscriber wraps the broadcast an origin resolved in a `broadcast::Consumer` with the key it -expects and the same application path; it takes the instance from the route. A frame reaches the -application only after it verifies. A forged or relocated frame ends its group with -`Error::Signature`, and the track keeps delivering other groups. Every hop must carry the instance -and timestamps unchanged, which means moq-lite-07. A group's end is not signed: a relay may drop -a group's tail, as MoQ already allows. - -A broadcast at the identity level, which trusts the relay's token check alone, uses `moq-net` -directly. - -## Processing - -Signing is inline and synchronous. `cargo bench -p moq-sign` measures it: a 1 KiB frame costs -about 8 µs to sign and 32 µs to sign and verify through an origin on one core. diff --git a/sh/gh/nightly.sh b/sh/gh/nightly.sh index 811b6e75243..44365384f64 100755 --- a/sh/gh/nightly.sh +++ b/sh/gh/nightly.sh @@ -141,7 +141,7 @@ case "$1" in rust-extra) # The allocation/window/play-buffer/batch/receive-bursts tables keep their stdout in the run; # only Criterion estimates enter the trend report. - criterion extra --no-fail-fast -p moq-e2ee -p moq-sign -p moq-json -p moq-archive -p moq-cli -p moq-mux -p moq-audio \ + criterion extra --no-fail-fast -p moq-crypto -p moq-json -p moq-archive -p moq-cli -p moq-mux -p moq-audio \ -p moq-quic -p moq-sock -p moq-tokio -p moq-transcode --features moq-quic/fuzz \ --bench protect --bench sign --bench codec --bench table --bench allocations --bench window \ --bench producer --bench play_buffer --bench jitter --bench decode_clock --bench ts_programs --bench ts_video \ diff --git a/test/interop/sign.ts b/test/interop/sign.ts index f7fc0f7ab89..5350943c000 100644 --- a/test/interop/sign.ts +++ b/test/interop/sign.ts @@ -1,11 +1,11 @@ /** Exchange signed groups with Rust: verify the ones Rust signed, and sign through the JS wrappers. */ import assert from "node:assert/strict"; +import * as Signed from "../../js/crypto/src/sign/broadcast.ts"; +import { Failure } from "../../js/crypto/src/sign/failure.ts"; +import { SecretKey } from "../../js/crypto/src/sign/key.ts"; +import { Scope } from "../../js/crypto/src/sign/scope.ts"; +import * as Track from "../../js/crypto/src/sign/track.ts"; import { Broadcast, Instance, type Track as NetTrack, Path, Time } from "../../js/net/src/index.ts"; -import * as Signed from "../../js/sign/src/broadcast.ts"; -import { Failure } from "../../js/sign/src/failure.ts"; -import { SecretKey } from "../../js/sign/src/key.ts"; -import { Scope } from "../../js/sign/src/scope.ts"; -import * as Track from "../../js/sign/src/track.ts"; /** One frame as it crosses the wire: its body, signature included, and its timestamp at the track's timescale. */ type Frame = { body: string; timestamp?: number | null }; diff --git a/test/justfile b/test/justfile index a03400dbef0..6cc495eebd9 100644 --- a/test/justfile +++ b/test/justfile @@ -65,7 +65,7 @@ harness: [positional-arguments] interop *args: cd .. && bun install --frozen-lockfile - just rs test -p moq-net -p moq-sign --lib \ + just rs test -p moq-net -p moq-crypto --lib \ auth_unsupported_interop \ ietf_compression_fallback_interop \ ietf_datagram_interop \