From b2be135a6f5ddbf9e7594f44c7a17f0a25c1791e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 23:51:42 -0800 Subject: [PATCH 01/11] chore(quest): claim quest/m1/moq-crypto.md Quest-Claim: ec626ee42f3fe8f7 From 9273cc2e50b72ae265b6731ba5a8931441615e6b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 00:05:13 -0800 Subject: [PATCH 02/11] refactor!: merge moq-sign and moq-e2ee into moq-crypto One Rust crate, moq-crypto, and one JS package, @moq/crypto, hold content signing (`sign`) and end-to-end encryption (`e2ee`). Both halves check timestamps with moq_net::group::on_track (an internal mirror in JS), so neither accepts a frame its net track would refuse. rs/moq-e2ee becomes a code-free stub pointing at moq-crypto, for its final crates.io release at the cut. Co-Authored-By: Claude Opus 5.5 --- .oss-scanner/Dockerfile | 2 +- .oss-scanner/threat_model.md | 4 +- Cargo.lock | 31 ++---- Cargo.toml | 3 +- bun.lock | 20 +--- doc/concept/hang.md | 2 +- doc/lib/js/index.md | 3 +- doc/lib/rs/index.md | 3 +- doc/setup/repository.md | 4 +- doc/setup/upgrade.md | 2 +- js/{e2ee => crypto}/README.md | 68 +++++++++++- js/{e2ee => crypto}/bench/pump.ts | 2 +- js/{e2ee => crypto}/bench/tsconfig.json | 0 js/{e2ee => crypto}/package.json | 6 +- js/{e2ee/src => crypto/src/e2ee}/broadcast.ts | 0 .../src => crypto/src/e2ee}/credential.ts | 0 js/{e2ee/src => crypto/src/e2ee}/datagram.ts | 0 js/{e2ee/src => crypto/src/e2ee}/derive.ts | 0 js/{e2ee/src => crypto/src/e2ee}/e2ee.test.ts | 2 +- .../src => crypto/src/e2ee}/epoch.test.ts | 4 +- js/{e2ee/src => crypto/src/e2ee}/epoch.ts | 2 +- js/{e2ee/src => crypto/src/e2ee}/failure.ts | 0 .../src/e2ee}/generation-internal.ts | 0 .../src => crypto/src/e2ee}/generation.ts | 0 js/{e2ee/src => crypto/src/e2ee}/group.ts | 7 +- js/{e2ee/src => crypto/src/e2ee}/index.ts | 2 +- js/{e2ee/src => crypto/src/e2ee}/internal.ts | 13 +-- js/{e2ee/src => crypto/src/e2ee}/key.ts | 0 js/{e2ee/src => crypto/src/e2ee}/limits.ts | 0 js/{e2ee/src => crypto/src/e2ee}/name.ts | 0 js/{e2ee/src => crypto/src/e2ee}/secret.ts | 0 js/{e2ee/src => crypto/src/e2ee}/terminal.ts | 0 js/{e2ee/src => crypto/src/e2ee}/track.ts | 9 +- .../src => crypto/src/e2ee}/transport.test.ts | 2 +- .../src => crypto/src/e2ee}/vectors.test.ts | 2 +- js/{e2ee/src => crypto/src/e2ee}/window.ts | 0 js/crypto/src/index.ts | 14 +++ js/{e2ee => crypto}/src/pump.ts | 0 js/{sign/src => crypto/src/sign}/broadcast.ts | 0 js/{sign/src => crypto/src/sign}/failure.ts | 0 js/{sign/src => crypto/src/sign}/group.ts | 13 +-- js/{sign/src => crypto/src/sign}/index.ts | 2 +- js/{sign/src => crypto/src/sign}/key.ts | 0 js/{sign/src => crypto/src/sign}/scope.ts | 0 js/{sign/src => crypto/src/sign}/sign.test.ts | 8 +- js/{sign/src => crypto/src/sign}/track.ts | 2 +- .../src => crypto/src/sign}/vectors.test.ts | 2 +- js/{sign/src => crypto/src/sign}/zbase32.ts | 0 js/crypto/src/timestamp.ts | 19 ++++ js/{e2ee => crypto}/test-dts/constructors.ts | 12 +-- js/{e2ee => crypto}/test-dts/tsconfig.json | 0 js/{e2ee => crypto}/tsconfig.build.json | 0 js/{e2ee => crypto}/tsconfig.json | 0 js/sign/README.md | 50 --------- js/sign/package.json | 30 ------ js/sign/src/pump.ts | 16 --- js/sign/tsconfig.build.json | 10 -- js/sign/tsconfig.json | 11 -- package.json | 3 +- quest/m1/README.md | 1 - quest/m1/moq-crypto.md | 38 ------- quest/m1/poll-first/async-feature.md | 2 +- quest/m1/time-addressing/e2ee.md | 4 +- quest/m2/audit-perf.md | 2 +- quest/m2/e2ee/README.md | 6 +- quest/m2/e2ee/cli.md | 2 +- quest/m2/e2ee/consumer.md | 4 +- quest/m2/e2ee/js-undeclared-names.md | 12 +-- quest/m2/e2ee/rust-publish.md | 8 +- quest/m2/mesh/README.md | 2 +- quest/m2/mesh/endpoint.md | 4 +- quest/m2/net-wrap/README.md | 6 +- quest/m2/net-wrap/e2ee.md | 24 ++--- quest/m2/net-wrap/js.md | 14 +-- quest/m2/net-wrap/json.md | 4 +- quest/m2/net-wrap/mux.md | 2 +- quest/m2/net-wrap/traits.md | 2 +- quest/m2/release/cut.md | 8 ++ quest/m2/stream/README.md | 2 +- quest/m3/ffi-e2ee.md | 6 +- quest/m3/mesh-keys.md | 2 +- rs/justfile | 2 +- rs/{moq-e2ee => moq-crypto}/CHANGELOG.md | 0 rs/{moq-sign => moq-crypto}/Cargo.toml | 18 +++- rs/{moq-e2ee => moq-crypto}/MIGRATE.md | 15 ++- rs/moq-crypto/README.md | 102 ++++++++++++++++++ .../benches/protect.rs | 10 +- rs/{moq-sign => moq-crypto}/benches/sign.rs | 10 +- .../src => moq-crypto/src/e2ee}/broadcast.rs | 10 +- .../src => moq-crypto/src/e2ee}/credential.rs | 8 +- .../src => moq-crypto/src/e2ee}/datagram.rs | 0 .../src => moq-crypto/src/e2ee}/epoch.json | 0 .../src => moq-crypto/src/e2ee}/epoch.rs | 2 +- .../src => moq-crypto/src/e2ee}/error.rs | 2 +- .../src => moq-crypto/src/e2ee}/generation.rs | 30 +++--- .../src => moq-crypto/src/e2ee}/group.rs | 21 ++-- .../src => moq-crypto/src/e2ee}/key.rs | 6 +- .../src => moq-crypto/src/e2ee}/limits.rs | 8 +- rs/moq-crypto/src/e2ee/mod.rs | 52 +++++++++ .../src => moq-crypto/src/e2ee}/name.rs | 4 +- .../src => moq-crypto/src/e2ee}/protect.rs | 4 +- .../src => moq-crypto/src/e2ee}/terminal.rs | 2 +- .../src => moq-crypto/src/e2ee}/tests.rs | 51 +++++---- .../src => moq-crypto/src/e2ee}/track.rs | 32 +++--- .../src => moq-crypto/src/e2ee}/window.rs | 2 +- rs/moq-crypto/src/lib.rs | 11 ++ .../src => moq-crypto/src/sign}/broadcast.rs | 8 +- .../src => moq-crypto/src/sign}/error.rs | 2 +- .../src => moq-crypto/src/sign}/group.rs | 12 +-- .../src => moq-crypto/src/sign}/key.rs | 2 +- .../src/lib.rs => moq-crypto/src/sign/mod.rs} | 0 .../src => moq-crypto/src/sign}/scope.rs | 4 +- .../src => moq-crypto/src/sign}/tests.rs | 6 +- .../src => moq-crypto/src/sign}/track.rs | 10 +- .../tests/support/harness.rs | 0 .../tests/support/mod.rs | 0 .../tests/transport.rs | 20 ++-- rs/moq-e2ee/Cargo.toml | 24 +---- rs/moq-e2ee/README.md | 57 ++-------- rs/moq-e2ee/src/lib.rs | 53 +-------- rs/moq-net/src/model/origin.rs | 2 +- rs/moq-sign/README.md | 45 -------- sh/gh/nightly.sh | 2 +- test/interop/sign.ts | 10 +- test/justfile | 2 +- 125 files changed, 570 insertions(+), 631 deletions(-) rename js/{e2ee => crypto}/README.md (59%) rename js/{e2ee => crypto}/bench/pump.ts (97%) rename js/{e2ee => crypto}/bench/tsconfig.json (100%) rename js/{e2ee => crypto}/package.json (83%) rename js/{e2ee/src => crypto/src/e2ee}/broadcast.ts (100%) rename js/{e2ee/src => crypto/src/e2ee}/credential.ts (100%) rename js/{e2ee/src => crypto/src/e2ee}/datagram.ts (100%) rename js/{e2ee/src => crypto/src/e2ee}/derive.ts (100%) rename js/{e2ee/src => crypto/src/e2ee}/e2ee.test.ts (99%) rename js/{e2ee/src => crypto/src/e2ee}/epoch.test.ts (78%) rename js/{e2ee/src => crypto/src/e2ee}/epoch.ts (95%) rename js/{e2ee/src => crypto/src/e2ee}/failure.ts (100%) rename js/{e2ee/src => crypto/src/e2ee}/generation-internal.ts (100%) rename js/{e2ee/src => crypto/src/e2ee}/generation.ts (100%) rename js/{e2ee/src => crypto/src/e2ee}/group.ts (96%) rename js/{e2ee/src => crypto/src/e2ee}/index.ts (98%) rename js/{e2ee/src => crypto/src/e2ee}/internal.ts (57%) rename js/{e2ee/src => crypto/src/e2ee}/key.ts (100%) rename js/{e2ee/src => crypto/src/e2ee}/limits.ts (100%) rename js/{e2ee/src => crypto/src/e2ee}/name.ts (100%) rename js/{e2ee/src => crypto/src/e2ee}/secret.ts (100%) rename js/{e2ee/src => crypto/src/e2ee}/terminal.ts (100%) rename js/{e2ee/src => crypto/src/e2ee}/track.ts (97%) rename js/{e2ee/src => crypto/src/e2ee}/transport.test.ts (98%) rename js/{e2ee/src => crypto/src/e2ee}/vectors.test.ts (98%) rename js/{e2ee/src => crypto/src/e2ee}/window.ts (100%) create mode 100644 js/crypto/src/index.ts rename js/{e2ee => crypto}/src/pump.ts (100%) rename js/{sign/src => crypto/src/sign}/broadcast.ts (100%) rename js/{sign/src => crypto/src/sign}/failure.ts (100%) rename js/{sign/src => crypto/src/sign}/group.ts (91%) rename js/{sign/src => crypto/src/sign}/index.ts (97%) rename js/{sign/src => crypto/src/sign}/key.ts (100%) rename js/{sign/src => crypto/src/sign}/scope.ts (100%) rename js/{sign/src => crypto/src/sign}/sign.test.ts (95%) rename js/{sign/src => crypto/src/sign}/track.ts (99%) rename js/{sign/src => crypto/src/sign}/vectors.test.ts (96%) rename js/{sign/src => crypto/src/sign}/zbase32.ts (100%) create mode 100644 js/crypto/src/timestamp.ts rename js/{e2ee => crypto}/test-dts/constructors.ts (55%) rename js/{e2ee => crypto}/test-dts/tsconfig.json (100%) rename js/{e2ee => crypto}/tsconfig.build.json (100%) rename js/{e2ee => crypto}/tsconfig.json (100%) delete mode 100644 js/sign/README.md delete mode 100644 js/sign/package.json delete mode 100644 js/sign/src/pump.ts delete mode 100644 js/sign/tsconfig.build.json delete mode 100644 js/sign/tsconfig.json delete mode 100644 quest/m1/moq-crypto.md rename rs/{moq-e2ee => moq-crypto}/CHANGELOG.md (100%) rename rs/{moq-sign => moq-crypto}/Cargo.toml (63%) rename rs/{moq-e2ee => moq-crypto}/MIGRATE.md (78%) create mode 100644 rs/moq-crypto/README.md rename rs/{moq-e2ee => moq-crypto}/benches/protect.rs (83%) rename rs/{moq-sign => moq-crypto}/benches/sign.rs (91%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/broadcast.rs (97%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/credential.rs (96%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/datagram.rs (100%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/epoch.json (100%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/epoch.rs (97%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/error.rs (94%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/generation.rs (87%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/group.rs (91%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/key.rs (94%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/limits.rs (92%) create mode 100644 rs/moq-crypto/src/e2ee/mod.rs rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/name.rs (97%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/protect.rs (95%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/terminal.rs (98%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/tests.rs (96%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/track.rs (93%) rename rs/{moq-e2ee/src => moq-crypto/src/e2ee}/window.rs (98%) create mode 100644 rs/moq-crypto/src/lib.rs rename rs/{moq-sign/src => moq-crypto/src/sign}/broadcast.rs (96%) rename rs/{moq-sign/src => moq-crypto/src/sign}/error.rs (89%) rename rs/{moq-sign/src => moq-crypto/src/sign}/group.rs (91%) rename rs/{moq-sign/src => moq-crypto/src/sign}/key.rs (99%) rename rs/{moq-sign/src/lib.rs => moq-crypto/src/sign/mod.rs} (100%) rename rs/{moq-sign/src => moq-crypto/src/sign}/scope.rs (97%) rename rs/{moq-sign/src => moq-crypto/src/sign}/tests.rs (99%) rename rs/{moq-sign/src => moq-crypto/src/sign}/track.rs (96%) rename rs/{moq-e2ee => moq-crypto}/tests/support/harness.rs (100%) rename rs/{moq-e2ee => moq-crypto}/tests/support/mod.rs (100%) rename rs/{moq-e2ee => moq-crypto}/tests/transport.rs (86%) delete mode 100644 rs/moq-sign/README.md 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 884ded34ab1..3e0aa7c2da0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5153,17 +5153,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 0.6.2", "moq-net", "rind", "serde_json", + "tempfile", "thiserror 2.0.21", "tokio", "uuid", @@ -5171,6 +5174,13 @@ dependencies = [ "zeroize", ] +[[package]] +name = "moq-e2ee" +version = "0.0.11" +dependencies = [ + "workspace-hack", +] + [[package]] name = "moq-ffi" version = "0.4.12" @@ -5659,25 +5669,6 @@ dependencies = [ "workspace-hack", ] -[[package]] -name = "moq-sign" -version = "0.0.1" -dependencies = [ - "aws-lc-rs", - "bench-harness", - "bytes", - "data-encoding", - "hex", - "kio 0.6.2", - "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 fd42fd2a7ff..d7dcfbac1ae 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 8a34739da90..8a0c09c4067 100644 --- a/bun.lock +++ b/bun.lock @@ -160,8 +160,8 @@ "typescript": "7.0.2", }, }, - "js/e2ee": { - "name": "@moq/e2ee", + "js/crypto": { + "name": "@moq/crypto", "version": "0.0.0", "dependencies": { "@moq/net": "workspace:^", @@ -361,18 +361,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", @@ -860,7 +848,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"], @@ -894,8 +882,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 ddf1e7bf83b..7072bf6e852 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 bcaae6ad55c..db6ff59d68b 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..c13915d51fb 100644 --- a/js/e2ee/README.md +++ b/js/crypto/README.md @@ -2,16 +2,72 @@ 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 refuse a +timestamp its track would refuse before signing or encrypting. + +## 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 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 +83,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 +115,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 5235431636a..5675c75c114 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"; 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 100% rename from js/e2ee/src/generation-internal.ts rename to js/crypto/src/e2ee/generation-internal.ts 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 96% rename from js/e2ee/src/group.ts rename to js/crypto/src/e2ee/group.ts index d48ef73feca..9317458bd85 100644 --- a/js/e2ee/src/group.ts +++ b/js/crypto/src/e2ee/group.ts @@ -4,8 +4,9 @@ * @module */ import type { Group as NetGroup, Time } from "@moq/net"; +import { onTrack } from "../timestamp.ts"; 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 +62,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 = onTrack(timestamp, this.#writer.timescale); 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 57% rename from js/e2ee/src/internal.ts rename to js/crypto/src/e2ee/internal.ts index 732940b2e60..c75bb473fc5 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 { Time } 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. */ @@ -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 97% rename from js/e2ee/src/track.ts rename to js/crypto/src/e2ee/track.ts index b5472ce2c3b..6c61984557c 100644 --- a/js/e2ee/src/track.ts +++ b/js/crypto/src/e2ee/track.ts @@ -4,14 +4,15 @@ * @module */ import type { Group as NetGroup, Track as NetTrack, Time } from "@moq/net"; +import { Pump } from "../pump.ts"; +import { onTrack } from "../timestamp.ts"; import type { Event } from "./datagram.ts"; import { checkU53 } 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"; @@ -90,7 +91,7 @@ export class Producer { ): Promise { this.#writable(); this.#reserve(sequence); - checkTimestamp(this.#writer, timestamp); + const at = onTrack(timestamp, this.#writer.timescale); const iv = this.#datagramKey.admitSeal(sequence, 0, plaintext.byteLength, MAX_DATAGRAM_PAYLOAD); this.#next = sequence + 1; const owned = plaintext.slice(); @@ -98,7 +99,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 99569ecaf04..28140017ca9 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 5dafbf052de..7c314c06883 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 100% rename from js/sign/src/broadcast.ts rename to js/crypto/src/sign/broadcast.ts 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 91% rename from js/sign/src/group.ts rename to js/crypto/src/sign/group.ts index a1263e2222b..014a0a86e08 100644 --- a/js/sign/src/group.ts +++ b/js/crypto/src/sign/group.ts @@ -3,10 +3,11 @@ * * @module */ -import { type Group as NetGroup, Time } from "@moq/net"; +import type { Group as NetGroup, Time } from "@moq/net"; +import type { Pump } from "../pump.ts"; +import { onTrack } from "../timestamp.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. */ @@ -70,12 +71,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 = onTrack(timestamp, this.#writer.timescale); 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 95% rename from js/sign/src/sign.test.ts rename to js/crypto/src/sign/sign.test.ts index bc5ecae0522..594a5282526 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"; @@ -91,6 +91,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 99% rename from js/sign/src/track.ts rename to js/crypto/src/sign/track.ts index 359cc80d8b3..e43d670f8a5 100644 --- a/js/sign/src/track.ts +++ b/js/crypto/src/sign/track.ts @@ -4,9 +4,9 @@ * @module */ import type { Track as NetTrack, Time } 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 */ 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 380443140e9..627e1ae1efb 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/crypto/src/timestamp.ts b/js/crypto/src/timestamp.ts new file mode 100644 index 00000000000..5e0d4907981 --- /dev/null +++ b/js/crypto/src/timestamp.ts @@ -0,0 +1,19 @@ +// The timestamp check both halves share, so a frame either accepts is one `@moq/net` accepts. +import { Error as NetError, Time } from "@moq/net"; + +/** + * `timestamp` at the track's `timescale`, rounded as the wire rounds it. Mirrors Rust's + * `moq_net::group::on_track`, checked before a frame is signed or encrypted so a refused + * timestamp spends nothing. + * + * Throws `TimestampMismatch` when the frame's timedness disagrees with the track's, or a + * `RangeError` when the converted value leaves the safe range. + */ +export function onTrack( + timestamp: Time.Timestamp | undefined, + timescale: Time.Timescale | undefined, +): Time.Timestamp | undefined { + if ((timescale !== undefined) !== (timestamp !== undefined)) throw new NetError.TimestampMismatch(); + if (timestamp === undefined || timescale === undefined) return undefined; + return new Time.Timestamp(Math.round(timestamp.as(timescale)), timescale); +} 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/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 3891b7870c4..3eb6a949000 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -162,7 +162,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 - [moq-transport 18, 20, and 22 only](/quest/m1/ietf-drop/README.md) - drafts 14-17, 19, and 21 are deleted from Rust, JS, tests, interop lanes, and docs, removing the legacy control-stream adapter and its request limit - [A lapsed request token resets with EXPIRED_AUTH_TOKEN](/quest/m1/auth-expiry-reset.md) - group streams of a lapsed grant reset with the expiry code, so a client knows to renew - [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 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 54c1da9da72..c64f5c99a12 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 08ff5de6f01..52e6f009f46 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. @@ -57,14 +57,14 @@ Rejected: The broadcast wrappers merged in [#5876](https://github.com/moq-dev/moq/pull/5876) with `reserve_track`, which still serves declared names; [rust-publish](/quest/m2/e2ee/rust-publish.md) needs nothing more (maintainer, 2026-10-19). -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 5c6740d5aeb..ad4d06d7ecf 100644 --- a/rs/justfile +++ b/rs/justfile @@ -493,7 +493,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 78% rename from rs/moq-e2ee/MIGRATE.md rename to rs/moq-crypto/MIGRATE.md index 56e235fc672..706229d793e 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 and apply to `moq_crypto::e2ee`. + ### Tracks are named semantically through `broadcast` wrappers (#5876) `generation::Producer::produce` and `generation::Consumer::consume` are private. diff --git a/rs/moq-crypto/README.md b/rs/moq-crypto/README.md new file mode 100644 index 00000000000..9fd4f540af5 --- /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 `group::on_track`, 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 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-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 91% rename from rs/moq-e2ee/src/group.rs rename to rs/moq-crypto/src/e2ee/group.rs index 012e2d32a5a..e95e89b1e50 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)] @@ -64,22 +64,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 = moq_net::group::on_track(timestamp.into(), inner.timescale())?; 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 93% rename from rs/moq-e2ee/src/track.rs rename to rs/moq-crypto/src/e2ee/track.rs index 7343dbea3c1..9999b6194fc 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. /// @@ -100,7 +100,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 +124,8 @@ impl Producer { timestamp: Option, plaintext: &[u8], ) -> Result { + // Checked before the sequence is spent. + let timestamp = moq_net::group::on_track(timestamp, self.inner.info().timescale)?; // 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 +191,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 +208,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 +248,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 +260,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..641d4c4cf11 --- /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::group::on_track`], 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 91% rename from rs/moq-sign/src/group.rs rename to rs/moq-crypto/src/sign/group.rs index f304aab3438..238359ef9b5 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)] @@ -44,11 +44,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 = moq_net::group::on_track(timestamp.into(), self.inner.timescale())?; 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 99% rename from rs/moq-sign/src/tests.rs rename to rs/moq-crypto/src/sign/tests.rs index 58ed38af99b..0e6909c5363 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() diff --git a/rs/moq-sign/src/track.rs b/rs/moq-crypto/src/sign/track.rs similarity index 96% rename from rs/moq-sign/src/track.rs rename to rs/moq-crypto/src/sign/track.rs index b08664b0fea..24467dbc348 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. /// @@ -106,7 +106,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-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index bbf3a98691c..b0cdac162b7 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-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 30fa14f8392..8084fb2e7aa 100755 --- a/sh/gh/nightly.sh +++ b/sh/gh/nightly.sh @@ -124,7 +124,7 @@ case "$1" in rust-extra) # The allocation/window/play-buffer/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-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 02f05583d31..753bc26feb9 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 { 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"; +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"; /** 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 \ From 5e925662cf94ce74ce935ba74b0dee2084cf780f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 00:10:28 -0800 Subject: [PATCH 03/11] fix: point the e2ee bench recipe at js/crypto and sort interop imports Co-Authored-By: Claude Opus 5.5 --- js/justfile | 2 +- test/interop/sign.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/js/justfile b/js/justfile index 07865bbd705..7b9bb13876c 100644 --- a/js/justfile +++ b/js/justfile @@ -178,7 +178,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/test/interop/sign.ts b/test/interop/sign.ts index 753bc26feb9..3453b2fc741 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 { Broadcast, Instance, type Track as NetTrack, Path, Time } from "../../js/net/src/index.ts"; 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"; /** 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 }; From 123cdc0981d64a5754b7ebacaba7fdd85d3fdc22 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 09:35:08 -0800 Subject: [PATCH 04/11] feat!: track::Info::rescale replaces group::on_track, shared by moq-crypto The maintainer settled the timestamp check's API on #7702: a method on track info named rescale, in moq-net and @moq/net, which moq-net's own writes and both moq-crypto halves call. group::on_track is removed and @moq/crypto's onTrack mirror is deleted. Co-Authored-By: Claude Opus 5.5 --- js/crypto/README.md | 5 +-- js/crypto/src/e2ee/e2ee.test.ts | 4 +-- js/crypto/src/e2ee/generation-internal.ts | 2 +- js/crypto/src/e2ee/group.ts | 3 +- js/crypto/src/e2ee/internal.ts | 6 ++-- js/crypto/src/e2ee/track.ts | 11 +++--- js/crypto/src/sign/broadcast.ts | 11 ++++-- js/crypto/src/sign/group.ts | 9 +++-- js/crypto/src/sign/sign.test.ts | 5 +-- js/crypto/src/sign/track.ts | 12 +++---- js/crypto/src/timestamp.ts | 19 ---------- js/net/MIGRATE.md | 6 ++++ js/net/api/index.api.md | 1 + js/net/src/group.ts | 27 ++++++++------- js/net/src/internal.ts | 6 ++-- js/net/src/listing.ts | 8 ++--- js/net/src/lite/publisher.ts | 24 +++++++------ js/net/src/lite/subscriber.ts | 6 ++-- js/net/src/lite/tracks.test.ts | 9 ++++- js/net/src/resume.ts | 6 ++-- js/net/src/track.test.ts | 14 ++++++++ js/net/src/track.ts | 39 ++++++++++++++++----- rs/moq-crypto/README.md | 2 +- rs/moq-crypto/src/e2ee/group.rs | 7 ++-- rs/moq-crypto/src/e2ee/track.rs | 8 +++-- rs/moq-crypto/src/lib.rs | 2 +- rs/moq-crypto/src/sign/group.rs | 18 ++++++++-- rs/moq-crypto/src/sign/tests.rs | 2 +- rs/moq-crypto/src/sign/track.rs | 7 +++- rs/moq-json/src/snapshot/producer.rs | 8 ++--- rs/moq-json/src/stream/producer.rs | 2 +- rs/moq-json/src/window/producer.rs | 10 +++--- rs/moq-net/MIGRATE.md | 5 +++ rs/moq-net/src/model/group.rs | 38 +++++++------------- rs/moq-net/src/model/track.rs | 42 +++++++++++++++++++---- 35 files changed, 236 insertions(+), 148 deletions(-) delete mode 100644 js/crypto/src/timestamp.ts diff --git a/js/crypto/README.md b/js/crypto/README.md index c13915d51fb..3ef44662516 100644 --- a/js/crypto/README.md +++ b/js/crypto/README.md @@ -6,8 +6,9 @@ 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 refuse a -timestamp its track would refuse before signing or encrypting. +groups, datagrams, and track names so relays cannot read them. Both wrap `@moq/net` and check each +timestamp with its track's `Info.rescale` before signing or encrypting, so a frame either accepts is +one `@moq/net` accepts. ## Signing diff --git a/js/crypto/src/e2ee/e2ee.test.ts b/js/crypto/src/e2ee/e2ee.test.ts index a44039759e2..01db429f0cc 100644 --- a/js/crypto/src/e2ee/e2ee.test.ts +++ b/js/crypto/src/e2ee/e2ee.test.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/crypto/src/e2ee/generation-internal.ts b/js/crypto/src/e2ee/generation-internal.ts index aecbc2e8d5e..aad83278fc0 100644 --- a/js/crypto/src/e2ee/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/crypto/src/e2ee/group.ts b/js/crypto/src/e2ee/group.ts index 53947cea9b4..9e2e5543e44 100644 --- a/js/crypto/src/e2ee/group.ts +++ b/js/crypto/src/e2ee/group.ts @@ -4,7 +4,6 @@ * @module */ import type { Group as NetGroup, Time } from "@moq/net"; -import { onTrack } from "../timestamp.ts"; import { Failure } from "./failure.ts"; import type { Reader, Writer } from "./internal.ts"; import { MAX_GROUPED_PAYLOAD, TAG_LEN } from "./limits.ts"; @@ -62,7 +61,7 @@ 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"); - const at = onTrack(timestamp, this.#writer.timescale); + const at = this.#writer.track.rescale(timestamp); const owned = plaintext.slice(); return this.#writer.pump.run(() => this.#write(at, owned)); } diff --git a/js/crypto/src/e2ee/internal.ts b/js/crypto/src/e2ee/internal.ts index c75bb473fc5..ff2bd70d773 100644 --- a/js/crypto/src/e2ee/internal.ts +++ b/js/crypto/src/e2ee/internal.ts @@ -1,5 +1,5 @@ // Package-private state the public modules share without exporting it. -import 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 { Terminal } from "./terminal.ts"; @@ -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, whose `rescale` checks every timestamp before encryption. + track: NetTrack.Info; // Set by release or abort: no new writes, including on existing groups. closed: boolean; aborted?: Error; diff --git a/js/crypto/src/e2ee/track.ts b/js/crypto/src/e2ee/track.ts index 87c783bb0a2..36121d4cd6e 100644 --- a/js/crypto/src/e2ee/track.ts +++ b/js/crypto/src/e2ee/track.ts @@ -5,7 +5,6 @@ */ import type { Group as NetGroup, Track as NetTrack, Time } from "@moq/net"; import { Pump } from "../pump.ts"; -import { onTrack } from "../timestamp.ts"; import type { Event } from "./datagram.ts"; import { checkGroup } from "./derive.ts"; import { Failure } from "./failure.ts"; @@ -33,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. */ @@ -91,7 +90,7 @@ export class Producer { ): Promise { this.#writable(); this.#reserve(sequence); - const at = onTrack(timestamp, this.#writer.timescale); + const at = this.#writer.track.rescale(timestamp); const iv = this.#datagramKey.admitSeal(sequence, 0, plaintext.byteLength, MAX_DATAGRAM_PAYLOAD); this.#next = sequence + 1n; const owned = plaintext.slice(); diff --git a/js/crypto/src/sign/broadcast.ts b/js/crypto/src/sign/broadcast.ts index 0577e158dab..0e035cd7df9 100644 --- a/js/crypto/src/sign/broadcast.ts +++ b/js/crypto/src/sign/broadcast.ts @@ -6,7 +6,7 @@ * * @module */ -import { Instance, type Broadcast as NetBroadcast, type Track as NetTrack, type Path } from "@moq/net"; +import { Instance, type Broadcast as NetBroadcast, Track as NetTrack, type Path } from "@moq/net"; import { Failure } from "./failure.ts"; import type { PublicKey, SecretKey } from "./key.ts"; import { Scope } from "./scope.ts"; @@ -42,13 +42,18 @@ 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); } - return Track.Producer.make(inner, this.#key, new Scope(this.#path, this.instance, name), sequences, timescale); + return Track.Producer.make( + inner, + this.#key, + new Scope(this.#path, this.instance, name), + sequences, + NetTrack.infoDefaults(info), + ); } /** End the wrapped broadcast, as `@moq/net`'s `close` does. Idempotent. */ diff --git a/js/crypto/src/sign/group.ts b/js/crypto/src/sign/group.ts index 7aadc33aea7..3393429a4a2 100644 --- a/js/crypto/src/sign/group.ts +++ b/js/crypto/src/sign/group.ts @@ -3,9 +3,8 @@ * * @module */ -import type { Group as NetGroup, Time } from "@moq/net"; +import type { Group as NetGroup, Track as NetTrack, Time } from "@moq/net"; import type { Pump } from "../pump.ts"; -import { onTrack } from "../timestamp.ts"; import { Failure } from "./failure.ts"; import type { PublicKey, SecretKey } from "./key.ts"; import type { Scope } from "./scope.ts"; @@ -24,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, whose `rescale` gives the timestamp every frame is signed at. + track: NetTrack.Info; // Set by release or abort: no new writes, including on existing groups. closed: boolean; aborted?: Error; @@ -72,7 +71,7 @@ export class Producer { 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, and written that way so a local reader sees the signed value too. - const at = onTrack(timestamp, this.#writer.timescale); + const at = this.#writer.track.rescale(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/crypto/src/sign/sign.test.ts b/js/crypto/src/sign/sign.test.ts index 8aa85f2a506..3ab138ba4cc 100644 --- a/js/crypto/src/sign/sign.test.ts +++ b/js/crypto/src/sign/sign.test.ts @@ -1,7 +1,7 @@ // 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, Error as NetError, Origin, Path, Time } from "@moq/net"; +import { type Broadcast, Connection, Error as NetError, Track as NetTrack, 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 * as Signed from "./broadcast.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 }, NetTrack.infoDefaults()), raw }; }, async consume(expected: PublicKey): Promise { return new Signed.Consumer(await active(net.subscriber, path), expected, path); diff --git a/js/crypto/src/sign/track.ts b/js/crypto/src/sign/track.ts index 45be1a109d4..ac58e3d5f25 100644 --- a/js/crypto/src/sign/track.ts +++ b/js/crypto/src/sign/track.ts @@ -3,7 +3,7 @@ * * @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"; @@ -38,23 +38,23 @@ export class Producer { key: SecretKey, scope: Scope, sequences: Sequences, - timescale?: Time.Timescale, + info: NetTrack.Info, ) { 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: NetTrack.Info, ): 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/crypto/src/timestamp.ts b/js/crypto/src/timestamp.ts deleted file mode 100644 index 5e0d4907981..00000000000 --- a/js/crypto/src/timestamp.ts +++ /dev/null @@ -1,19 +0,0 @@ -// The timestamp check both halves share, so a frame either accepts is one `@moq/net` accepts. -import { Error as NetError, Time } from "@moq/net"; - -/** - * `timestamp` at the track's `timescale`, rounded as the wire rounds it. Mirrors Rust's - * `moq_net::group::on_track`, checked before a frame is signed or encrypted so a refused - * timestamp spends nothing. - * - * Throws `TimestampMismatch` when the frame's timedness disagrees with the track's, or a - * `RangeError` when the converted value leaves the safe range. - */ -export function onTrack( - timestamp: Time.Timestamp | undefined, - timescale: Time.Timescale | undefined, -): Time.Timestamp | undefined { - if ((timescale !== undefined) !== (timestamp !== undefined)) throw new NetError.TimestampMismatch(); - if (timestamp === undefined || timescale === undefined) return undefined; - return new Time.Timestamp(Math.round(timestamp.as(timescale)), timescale); -} diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 8dbad0d2958..bedb5489f66 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### `Track.Info` has `rescale` ([#7702](https://github.com/moq-dev/moq/pull/7702)) + +A resolved `Track.Info` has `rescale(timestamp)`, which returns the timestamp at the track's timescale, rounded as the wire rounds it, and throws `TimestampMismatch` for a timestamp the track refuses. It mirrors the Rust `track::Info::rescale`. +Build an `Info` with `Track.infoDefaults(fields)` rather than an object literal, which lacks the method. +A timestamp that leaves the safe range at the track's timescale is now refused at the write with `TimestampMismatch`, rather than with a `RangeError` when it is encoded. + ### 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..efe457ccfa9 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -638,6 +638,7 @@ export namespace Track { maxAge?: Milli; priority: number; refresh?: number; + rescale(timestamp: Time.Timestamp | undefined): Time.Timestamp | undefined; timescale?: Time.Timescale | null; } export type Order = "ascending" | "descending"; diff --git a/js/net/src/group.ts b/js/net/src/group.ts index f725378a3ed..ca89c848786 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -10,6 +10,7 @@ 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 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 +212,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, whose `rescale` every frame must pass: 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 +255,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 `rescale` refuses. +function checkTimed(track: TrackInfo | undefined, frame: Frame) { + track?.rescale(frame.timestamp); } function appendFrame(state: GroupState, frame: Frame) { @@ -393,13 +395,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 +606,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/internal.ts b/js/net/src/internal.ts index 0be942d71c1..a8ecf68f5f7 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 the track's `rescale` refuses + * 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/listing.ts b/js/net/src/listing.ts index 80e45d4a491..0055bb38996 100644 --- a/js/net/src/listing.ts +++ b/js/net/src/listing.ts @@ -15,7 +15,7 @@ import { type GetPromise, type Getter, Signal } from "@moq/signals"; import { StreamCode, StreamError } from "./error.ts"; import { hooks } from "./internal.ts"; -import type * as track from "./track.ts"; +import * as track from "./track.ts"; /** * What a {@link Tracks} listing reports, in order. @@ -445,9 +445,9 @@ export class Lister { return this.#listing.closed; } - /** List a track. Throws if this answer already lists it. */ - add(name: string, info: track.Info): void { - this.#listing.answerAdd(name, info); + /** List a track; unset `info` fields take their defaults. Throws if this answer already lists it. */ + add(name: string, info: Partial): void { + this.#listing.answerAdd(name, track.infoDefaults(info)); } /** Stop listing a track that left unfinished, reported as `removed`. Throws if this answer does not list it. */ diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 0b084e85f15..f492c7827ea 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -27,7 +27,7 @@ import { readSize, sendPayload } from "../payload.ts"; import { Priority, sendOrder } from "../priority.ts"; import { concat, encodeVarint, type Reader, type Stream, type StreamVersion, Writer } from "../stream.ts"; import { type Timescale, Timestamp } from "../time.ts"; -import type * as track from "../track.ts"; +import * as track from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { nextChange } from "../util/change.ts"; import { GivenUp } from "../util/given_up.ts"; @@ -100,21 +100,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?: track.Info; } -/** 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: track.Info): 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(timestamp); + return own ? own.value : Math.round(Timestamp.now().as(stamp.timescale)); } /** @@ -988,7 +992,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 +1167,7 @@ export class Publisher { return; } await this.#runFetchGroup(group, stream.writer, { - stamp: stamping(this.version, info.timescale), + stamp: stamping(this.version, track.infoDefaults({ timescale: info.timescale })), compress: info.compress, start: msg.startFrame, end: msg.endFrame, diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 02e38e65c11..3f58109a31a 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -30,7 +30,7 @@ import { sendOrder } from "../priority.ts"; import { type OpenOptions, type Reader, Stream, Writer } from "../stream.ts"; import { Tail } from "../tail.ts"; import * as Time from "../time.ts"; -import type * as track from "../track.ts"; +import * as track from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { closeUnwanted } from "../util/announce.ts"; import { Deadline, REQUEST_TIMEOUT_MS, requestOptions } from "../util/deadline.ts"; @@ -1477,7 +1477,7 @@ export class Subscriber { // Map the wire TRACK_INFO onto the model track.Info a producer/consumer holds. #toModelInfo(info: TrackInfo): track.Info { - return { + return track.infoDefaults({ timescale: info.timescale, // Publisher Max Age rides on the wire, so the local media-time budget // matches what the upstream advertises (relays re-serve with the same bound). @@ -1487,7 +1487,7 @@ export class Subscriber { compress: info.compress, // Lite-05/06 timestamps may be send times, so the copy's groups skip the rewind check. ...(hasMediaTime(this.version) ? {} : { unchecked: true }), - }; + }); } // Resolve a track's immutable model info via a TRACK stream (lite-05+), for the diff --git a/js/net/src/lite/tracks.test.ts b/js/net/src/lite/tracks.test.ts index ea5061fd47d..a8832fd6410 100644 --- a/js/net/src/lite/tracks.test.ts +++ b/js/net/src/lite/tracks.test.ts @@ -13,6 +13,7 @@ import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Reader, Stream, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; +import { infoDefaults } from "../track.ts"; import type { Limits } from "../util/limits.ts"; import { wireOf } from "../wire.ts"; import { Publisher } from "./publisher.ts"; @@ -478,7 +479,13 @@ test("a listing over a session carries each track's info, end to end", async () expect(await tracks.next()).toEqual({ kind: "added", name: "a", - info: { timescale: Timescale.MILLI, maxAge: Milli(3000), priority: 9, refresh: 4, compress: true }, + info: infoDefaults({ + timescale: Timescale.MILLI, + maxAge: Milli(3000), + priority: 9, + refresh: 4, + compress: true, + }), }); broadcast.createTrack("b"); expect(await next(tracks)).toBe("+b"); diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index 770361aa7f4..127fd3f6883 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -106,8 +106,8 @@ export function routeFailed(err: Error): boolean { return err instanceof SessionError || sessionClosed(err); } -// Every `track.Info` field but `unchecked`, so one added later fails to compile until it is -// listed here. `unchecked` says how a copy arrived, not what it holds, so copies over different +// Every `track.Info` field but `unchecked` and the `rescale` method, so one added later fails to +// compile until it is listed here. `unchecked` says how a copy arrived, not what it holds, so copies over different // lite versions still match. `ietf` is compared, like Rust's moq-transport `properties`. const INFO_FIELDS = Object.keys({ compress: true, @@ -116,7 +116,7 @@ const INFO_FIELDS = Object.keys({ priority: true, refresh: true, ietf: true, -} satisfies Record, true>) as (keyof track.Info)[]; +} satisfies Record, true>) as (keyof track.Info)[]; /** Two copies claiming the same content must agree on all of it, like Rust's `Info` equality. */ function compatible(a: track.Info, b: track.Info): boolean { diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 5eb5c49227f..f43a194e767 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -504,6 +504,20 @@ test("refresh must be a u32 ratio", () => { expect(infoDefaults({ refresh: 0 }).refresh).toBe(0); }); +test("rescale matches the track's timeline, rounded as the wire rounds it", () => { + const timed = infoDefaults({ timescale: Timescale.MILLI }); + const rescaled = timed.rescale(Timestamp.fromMicros(2_400)); + expect(rescaled?.value).toBe(2); + expect(rescaled?.scale).toBe(Timescale.MILLI); + expect(() => timed.rescale(undefined)).toThrow(TimestampMismatch); + const nano = infoDefaults({ timescale: Timescale.NANO }); + expect(() => nano.rescale(new Timestamp(Number.MAX_SAFE_INTEGER, Timescale.MILLI))).toThrow(TimestampMismatch); + + const untimed = infoDefaults(); + expect(untimed.rescale(undefined)).toBeUndefined(); + expect(() => untimed.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..e9f51c13968 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -42,7 +42,7 @@ import { type TrackRequestOptions, } from "./internal.ts"; import { CACHE_EXPIRY, grace, Ledger } from "./ledger.ts"; -import { Timescale, type Timestamp } from "./time.ts"; +import { Timescale, Timestamp } from "./time.ts"; import { checkSequence, max, min } from "./util/sequence.ts"; import { type Holdings, @@ -177,6 +177,28 @@ export interface Info { * @internal */ unchecked?: boolean; + /** + * `timestamp` at this track's {@link Info.timescale}, rounded as the wire rounds it. 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`. + */ + rescale(timestamp: Timestamp | undefined): Timestamp | undefined; +} + +// The one implementation of `Info.rescale`, shared by every resolved `Info`. +const INFO_METHODS: Pick = { rescale }; + +function rescale(this: Info, timestamp: Timestamp | undefined): Timestamp | undefined { + const timescale = this.timescale ?? undefined; + if ((timescale !== undefined) !== (timestamp !== undefined)) throw new TimestampMismatch(); + if (timestamp === undefined || timescale === undefined) return undefined; + try { + return new Timestamp(Math.round(timestamp.as(timescale)), timescale); + } catch (cause) { + throw new TimestampMismatch({ cause }); + } } // Normalize a duration for the wire, which carries it as an unsigned varint. @@ -208,7 +230,8 @@ export function infoDefaults(info: Partial = {}): Info { if (info.compress !== undefined && typeof info.compress !== "boolean") throw new TypeError("compress must be a boolean"); const timescale = info.timescale == null ? undefined : Timescale(info.timescale); - return { + // The method lives on the prototype, so the fields stay plain data to compare and copy. + return Object.assign(Object.create(INFO_METHODS) as Pick, { compress: info.compress ?? false, timescale, maxAge: info.maxAge === undefined ? undefined : wireMillis("maxAge", info.maxAge), @@ -216,7 +239,7 @@ export function infoDefaults(info: Partial = {}): Info { refresh: info.refresh == null ? undefined : refreshRatio(info.refresh), ...(info.ietf === undefined ? {} : { ietf: info.ietf }), ...(info.unchecked ? { unchecked: true } : {}), - }; + }); } function refreshRatio(value: number): number { @@ -1090,17 +1113,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(); + resolved.rescale(datagram.timestamp); } } } catch (err) { @@ -1546,15 +1568,14 @@ 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); } } // 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(); + this.#state.info.peek()?.rescale(timestamp); } // Refuse a write once the track is closed, or at or past its declared end. diff --git a/rs/moq-crypto/README.md b/rs/moq-crypto/README.md index 9fd4f540af5..416eaa3ffb7 100644 --- a/rs/moq-crypto/README.md +++ b/rs/moq-crypto/README.md @@ -7,7 +7,7 @@ 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 `group::on_track`, so a frame either half accepts is one `moq-net` accepts. +with its `track::Info::rescale`, so a frame either half accepts is one `moq-net` accepts. ## Signing diff --git a/rs/moq-crypto/src/e2ee/group.rs b/rs/moq-crypto/src/e2ee/group.rs index e95e89b1e50..f0b94d601ec 100644 --- a/rs/moq-crypto/src/e2ee/group.rs +++ b/rs/moq-crypto/src/e2ee/group.rs @@ -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, } @@ -70,7 +73,7 @@ impl Producer { return Err(Error::Identity); } // Checked before the frame identity is spent. - let timestamp = moq_net::group::on_track(timestamp.into(), inner.timescale())?; + 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-crypto/src/e2ee/track.rs b/rs/moq-crypto/src/e2ee/track.rs index 9999b6194fc..60994a7ef3d 100644 --- a/rs/moq-crypto/src/e2ee/track.rs +++ b/rs/moq-crypto/src/e2ee/track.rs @@ -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. @@ -125,7 +129,7 @@ impl Producer { plaintext: &[u8], ) -> Result { // Checked before the sequence is spent. - let timestamp = moq_net::group::on_track(timestamp, self.inner.info().timescale)?; + 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"); diff --git a/rs/moq-crypto/src/lib.rs b/rs/moq-crypto/src/lib.rs index 641d4c4cf11..e33db807d36 100644 --- a/rs/moq-crypto/src/lib.rs +++ b/rs/moq-crypto/src/lib.rs @@ -3,7 +3,7 @@ //! [`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::group::on_track`], so neither accepts a frame the net track would refuse. +//! [`moq_net::track::Info::rescale`], so neither accepts a frame the net track would refuse. #![warn(missing_docs)] diff --git a/rs/moq-crypto/src/sign/group.rs b/rs/moq-crypto/src/sign/group.rs index 238359ef9b5..faf09b1d72e 100644 --- a/rs/moq-crypto/src/sign/group.rs +++ b/rs/moq-crypto/src/sign/group.rs @@ -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,7 +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. - let timestamp = moq_net::group::on_track(timestamp.into(), self.inner.timescale())?; + let timestamp = self.track.rescale(timestamp.into())?; let frame = self.inner.frame_count() as u64; let body = self .scope diff --git a/rs/moq-crypto/src/sign/tests.rs b/rs/moq-crypto/src/sign/tests.rs index 0e6909c5363..3c366ef7d02 100644 --- a/rs/moq-crypto/src/sign/tests.rs +++ b/rs/moq-crypto/src/sign/tests.rs @@ -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(); diff --git a/rs/moq-crypto/src/sign/track.rs b/rs/moq-crypto/src/sign/track.rs index 24467dbc348..820344435cc 100644 --- a/rs/moq-crypto/src/sign/track.rs +++ b/rs/moq-crypto/src/sign/track.rs @@ -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. 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/track.rs b/rs/moq-net/src/model/track.rs index e7a598b0dba..be4907c71aa 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,22 @@ 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.scale(), Timescale::MILLI); + 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()); From 8ac4b0be2a9a955f6bb5e641b8edfacbe0c60aa8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 11:38:41 -0800 Subject: [PATCH 05/11] refactor(js)!: Track.rescale is a free function, keeping Info plain data Per the maintainer (2026-11-03), JS rescale is Track.rescale(info, ts) rather than a method on Info, so Info stays plain data and object literals work without infoDefaults. It lives in rescale.ts to keep group.ts out of an import cycle with track.ts. Co-Authored-By: Claude Opus 5.5 --- js/crypto/src/e2ee/group.ts | 4 ++-- js/crypto/src/e2ee/internal.ts | 4 ++-- js/crypto/src/e2ee/track.ts | 4 ++-- js/crypto/src/sign/broadcast.ts | 10 ++-------- js/crypto/src/sign/group.ts | 8 ++++---- js/crypto/src/sign/sign.test.ts | 4 ++-- js/crypto/src/sign/track.ts | 4 ++-- js/net/MIGRATE.md | 7 +++---- js/net/api/index.api.md | 2 +- js/net/src/group.ts | 7 ++++--- js/net/src/internal.ts | 2 +- js/net/src/listing.ts | 8 ++++---- js/net/src/lite/publisher.ts | 11 ++++++----- js/net/src/lite/subscriber.ts | 6 +++--- js/net/src/lite/tracks.test.ts | 9 +-------- js/net/src/rescale.ts | 23 ++++++++++++++++++++++ js/net/src/resume.ts | 6 +++--- js/net/src/track.test.ts | 18 ++++++++--------- js/net/src/track.ts | 35 ++++++++------------------------- 19 files changed, 82 insertions(+), 90 deletions(-) create mode 100644 js/net/src/rescale.ts diff --git a/js/crypto/src/e2ee/group.ts b/js/crypto/src/e2ee/group.ts index 9e2e5543e44..f88b4f61150 100644 --- a/js/crypto/src/e2ee/group.ts +++ b/js/crypto/src/e2ee/group.ts @@ -3,7 +3,7 @@ * * @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 type { Reader, Writer } from "./internal.ts"; import { MAX_GROUPED_PAYLOAD, TAG_LEN } from "./limits.ts"; @@ -61,7 +61,7 @@ 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"); - const at = this.#writer.track.rescale(timestamp); + const at = NetTrack.rescale(this.#writer.track, timestamp); const owned = plaintext.slice(); return this.#writer.pump.run(() => this.#write(at, owned)); } diff --git a/js/crypto/src/e2ee/internal.ts b/js/crypto/src/e2ee/internal.ts index ff2bd70d773..18104a494cd 100644 --- a/js/crypto/src/e2ee/internal.ts +++ b/js/crypto/src/e2ee/internal.ts @@ -14,8 +14,8 @@ export interface Keys { export interface Writer { pump: Pump; key: TrackKey; - // The net track's committed info, whose `rescale` checks every timestamp before encryption. - track: NetTrack.Info; + // 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; diff --git a/js/crypto/src/e2ee/track.ts b/js/crypto/src/e2ee/track.ts index 36121d4cd6e..4823b804e0a 100644 --- a/js/crypto/src/e2ee/track.ts +++ b/js/crypto/src/e2ee/track.ts @@ -3,7 +3,7 @@ * * @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"; @@ -90,7 +90,7 @@ export class Producer { ): Promise { this.#writable(); this.#reserve(sequence); - const at = this.#writer.track.rescale(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(); diff --git a/js/crypto/src/sign/broadcast.ts b/js/crypto/src/sign/broadcast.ts index 0e035cd7df9..128df9326dc 100644 --- a/js/crypto/src/sign/broadcast.ts +++ b/js/crypto/src/sign/broadcast.ts @@ -6,7 +6,7 @@ * * @module */ -import { Instance, type Broadcast as NetBroadcast, Track as NetTrack, type Path } from "@moq/net"; +import { Instance, type Broadcast as NetBroadcast, type Track as NetTrack, type Path } from "@moq/net"; import { Failure } from "./failure.ts"; import type { PublicKey, SecretKey } from "./key.ts"; import { Scope } from "./scope.ts"; @@ -47,13 +47,7 @@ export class Producer { sequences = { next: 0n }; this.#sequences.set(name, sequences); } - return Track.Producer.make( - inner, - this.#key, - new Scope(this.#path, this.instance, name), - sequences, - NetTrack.infoDefaults(info), - ); + return Track.Producer.make(inner, this.#key, new Scope(this.#path, this.instance, name), sequences, info); } /** End the wrapped broadcast, as `@moq/net`'s `close` does. Idempotent. */ diff --git a/js/crypto/src/sign/group.ts b/js/crypto/src/sign/group.ts index 3393429a4a2..8f35ea70ab5 100644 --- a/js/crypto/src/sign/group.ts +++ b/js/crypto/src/sign/group.ts @@ -3,7 +3,7 @@ * * @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 type { Pump } from "../pump.ts"; import { Failure } from "./failure.ts"; import type { PublicKey, SecretKey } from "./key.ts"; @@ -23,8 +23,8 @@ export interface Writer { pump: Pump; key: SecretKey; scope: Scope; - // The track's info, whose `rescale` gives the timestamp every frame is signed at. - track: NetTrack.Info; + // 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; @@ -71,7 +71,7 @@ export class Producer { 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, and written that way so a local reader sees the signed value too. - const at = this.#writer.track.rescale(timestamp); + 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/crypto/src/sign/sign.test.ts b/js/crypto/src/sign/sign.test.ts index 3ab138ba4cc..4f1178f0b29 100644 --- a/js/crypto/src/sign/sign.test.ts +++ b/js/crypto/src/sign/sign.test.ts @@ -1,7 +1,7 @@ // 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, Error as NetError, Track as NetTrack, 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 * as Signed from "./broadcast.ts"; @@ -56,7 +56,7 @@ async function publish(key: SecretKey, path: Path.Valid) { track(name: string) { const raw = publication.broadcast.createTrack(name); const scope = new Scope(path, signed.instance, name); - return { signed: Track.Producer.make(raw, key, scope, { next: 0n }, NetTrack.infoDefaults()), raw }; + 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); diff --git a/js/crypto/src/sign/track.ts b/js/crypto/src/sign/track.ts index ac58e3d5f25..f469d0c5b0a 100644 --- a/js/crypto/src/sign/track.ts +++ b/js/crypto/src/sign/track.ts @@ -38,7 +38,7 @@ export class Producer { key: SecretKey, scope: Scope, sequences: Sequences, - info: NetTrack.Info, + info: Pick, ) { this.#inner = inner; this.name = inner.name; @@ -52,7 +52,7 @@ export class Producer { key: SecretKey, scope: Scope, sequences: Sequences, - info: NetTrack.Info, + info: Pick, ): Producer { return new Producer(inner, key, scope, sequences, info); } diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index bedb5489f66..8d423921a20 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -4,11 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased -### `Track.Info` has `rescale` ([#7702](https://github.com/moq-dev/moq/pull/7702)) +### A timestamp out of range at the track's timescale is a `TimestampMismatch` ([#7702](https://github.com/moq-dev/moq/pull/7702)) -A resolved `Track.Info` has `rescale(timestamp)`, which returns the timestamp at the track's timescale, rounded as the wire rounds it, and throws `TimestampMismatch` for a timestamp the track refuses. It mirrors the Rust `track::Info::rescale`. -Build an `Info` with `Track.infoDefaults(fields)` rather than an object literal, which lacks the method. -A timestamp that leaves the safe range at the track's timescale is now refused at the write with `TimestampMismatch`, rather than with a `RangeError` when it is encoded. +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`. ### Group sequences are `bigint` ([#7681](https://github.com/moq-dev/moq/pull/7681)) diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index efe457ccfa9..b4cbf30c9c5 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -638,7 +638,6 @@ export namespace Track { maxAge?: Milli; priority: number; refresh?: number; - rescale(timestamp: Time.Timestamp | undefined): Time.Timestamp | undefined; timescale?: Time.Timescale | null; } export type Order = "ascending" | "descending"; @@ -725,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 ca89c848786..7bf33c7b158 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -9,6 +9,7 @@ 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"; @@ -212,7 +213,7 @@ class GroupState { cacheBytes = 0; compressed?: boolean; flate?: Compression; - // The owning track's info, whose `rescale` every frame must pass: a timed track's frames + // 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; @@ -255,9 +256,9 @@ class Landed implements Frame { } } -// Refuse a frame whose timestamp the track's `rescale` refuses. +// Refuse a frame whose timestamp the track's timeline refuses. function checkTimed(track: TrackInfo | undefined, frame: Frame) { - track?.rescale(frame.timestamp); + if (track) rescale(track, frame.timestamp); } function appendFrame(state: GroupState, frame: Frame) { diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index a8ecf68f5f7..c99f3aac334 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -617,7 +617,7 @@ 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 info, so a frame whose timestamp the track's `rescale` refuses + * 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, track: Info) => void; diff --git a/js/net/src/listing.ts b/js/net/src/listing.ts index 0055bb38996..80e45d4a491 100644 --- a/js/net/src/listing.ts +++ b/js/net/src/listing.ts @@ -15,7 +15,7 @@ import { type GetPromise, type Getter, Signal } from "@moq/signals"; import { StreamCode, StreamError } from "./error.ts"; import { hooks } from "./internal.ts"; -import * as track from "./track.ts"; +import type * as track from "./track.ts"; /** * What a {@link Tracks} listing reports, in order. @@ -445,9 +445,9 @@ export class Lister { return this.#listing.closed; } - /** List a track; unset `info` fields take their defaults. Throws if this answer already lists it. */ - add(name: string, info: Partial): void { - this.#listing.answerAdd(name, track.infoDefaults(info)); + /** List a track. Throws if this answer already lists it. */ + add(name: string, info: track.Info): void { + this.#listing.answerAdd(name, info); } /** Stop listing a track that left unfinished, reported as `removed`. Throws if this answer does not list it. */ diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index f492c7827ea..9af1866a7e8 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -25,9 +25,10 @@ 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 * as track from "../track.ts"; +import type * as track from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { nextChange } from "../util/change.ts"; import { GivenUp } from "../util/given_up.ts"; @@ -104,11 +105,11 @@ interface Stamp { * equals. Lite-05/06 cannot encode an untimed track, so an untimed one carries its send time * instead. */ - timed?: track.Info; + timed?: Pick; } /** How `version` stamps a track with `info`, or undefined when it carries no timestamps. */ -function stamping(version: Version, info: track.Info): Stamp | undefined { +function stamping(version: Version, info: Pick): Stamp | undefined { const timescale = info.timescale ?? undefined; const wire = wireTimescale(version, timescale); if (wire === undefined) return undefined; @@ -117,7 +118,7 @@ function stamping(version: Version, info: track.Info): Stamp | undefined { /** 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 { - const own = stamp.timed?.rescale(timestamp); + const own = stamp.timed && rescale(stamp.timed, timestamp); return own ? own.value : Math.round(Timestamp.now().as(stamp.timescale)); } @@ -1167,7 +1168,7 @@ export class Publisher { return; } await this.#runFetchGroup(group, stream.writer, { - stamp: stamping(this.version, track.infoDefaults({ timescale: info.timescale })), + stamp: stamping(this.version, info), compress: info.compress, start: msg.startFrame, end: msg.endFrame, diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 3f58109a31a..02e38e65c11 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -30,7 +30,7 @@ import { sendOrder } from "../priority.ts"; import { type OpenOptions, type Reader, Stream, Writer } from "../stream.ts"; import { Tail } from "../tail.ts"; import * as Time from "../time.ts"; -import * as track from "../track.ts"; +import type * as track from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { closeUnwanted } from "../util/announce.ts"; import { Deadline, REQUEST_TIMEOUT_MS, requestOptions } from "../util/deadline.ts"; @@ -1477,7 +1477,7 @@ export class Subscriber { // Map the wire TRACK_INFO onto the model track.Info a producer/consumer holds. #toModelInfo(info: TrackInfo): track.Info { - return track.infoDefaults({ + return { timescale: info.timescale, // Publisher Max Age rides on the wire, so the local media-time budget // matches what the upstream advertises (relays re-serve with the same bound). @@ -1487,7 +1487,7 @@ export class Subscriber { compress: info.compress, // Lite-05/06 timestamps may be send times, so the copy's groups skip the rewind check. ...(hasMediaTime(this.version) ? {} : { unchecked: true }), - }); + }; } // Resolve a track's immutable model info via a TRACK stream (lite-05+), for the diff --git a/js/net/src/lite/tracks.test.ts b/js/net/src/lite/tracks.test.ts index a8832fd6410..ea5061fd47d 100644 --- a/js/net/src/lite/tracks.test.ts +++ b/js/net/src/lite/tracks.test.ts @@ -13,7 +13,6 @@ import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Reader, Stream, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; -import { infoDefaults } from "../track.ts"; import type { Limits } from "../util/limits.ts"; import { wireOf } from "../wire.ts"; import { Publisher } from "./publisher.ts"; @@ -479,13 +478,7 @@ test("a listing over a session carries each track's info, end to end", async () expect(await tracks.next()).toEqual({ kind: "added", name: "a", - info: infoDefaults({ - timescale: Timescale.MILLI, - maxAge: Milli(3000), - priority: 9, - refresh: 4, - compress: true, - }), + info: { timescale: Timescale.MILLI, maxAge: Milli(3000), priority: 9, refresh: 4, compress: true }, }); broadcast.createTrack("b"); expect(await next(tracks)).toBe("+b"); diff --git a/js/net/src/rescale.ts b/js/net/src/rescale.ts new file mode 100644 index 00000000000..cdf6a25b8e1 --- /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 { Timestamp } from "./time.ts"; +import type { Info } from "./track.ts"; + +/** + * `timestamp` at `info`'s {@link Info.timescale}, rounded as the wire rounds it. + * + * 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(Math.round(timestamp.as(timescale)), timescale); + } catch (cause) { + throw new TimestampMismatch({ cause }); + } +} diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index 127fd3f6883..770361aa7f4 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -106,8 +106,8 @@ export function routeFailed(err: Error): boolean { return err instanceof SessionError || sessionClosed(err); } -// Every `track.Info` field but `unchecked` and the `rescale` method, so one added later fails to -// compile until it is listed here. `unchecked` says how a copy arrived, not what it holds, so copies over different +// Every `track.Info` field but `unchecked`, so one added later fails to compile until it is +// listed here. `unchecked` says how a copy arrived, not what it holds, so copies over different // lite versions still match. `ietf` is compared, like Rust's moq-transport `properties`. const INFO_FIELDS = Object.keys({ compress: true, @@ -116,7 +116,7 @@ const INFO_FIELDS = Object.keys({ priority: true, refresh: true, ietf: true, -} satisfies Record, true>) as (keyof track.Info)[]; +} satisfies Record, true>) as (keyof track.Info)[]; /** Two copies claiming the same content must agree on all of it, like Rust's `Info` equality. */ function compatible(a: track.Info, b: track.Info): boolean { diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index f43a194e767..99be98bf8c0 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(); @@ -505,17 +505,17 @@ test("refresh must be a u32 ratio", () => { }); test("rescale matches the track's timeline, rounded as the wire rounds it", () => { - const timed = infoDefaults({ timescale: Timescale.MILLI }); - const rescaled = timed.rescale(Timestamp.fromMicros(2_400)); + const timed = { timescale: Timescale.MILLI }; + const rescaled = rescale(timed, Timestamp.fromMicros(2_400)); expect(rescaled?.value).toBe(2); expect(rescaled?.scale).toBe(Timescale.MILLI); - expect(() => timed.rescale(undefined)).toThrow(TimestampMismatch); - const nano = infoDefaults({ timescale: Timescale.NANO }); - expect(() => nano.rescale(new Timestamp(Number.MAX_SAFE_INTEGER, Timescale.MILLI))).toThrow(TimestampMismatch); + expect(() => rescale(timed, undefined)).toThrow(TimestampMismatch); + const huge = new Timestamp(Number.MAX_SAFE_INTEGER, Timescale.MILLI); + expect(() => rescale({ timescale: Timescale.NANO }, huge)).toThrow(TimestampMismatch); - const untimed = infoDefaults(); - expect(untimed.rescale(undefined)).toBeUndefined(); - expect(() => untimed.rescale(Timestamp.fromMillis(1))).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", () => { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index e9f51c13968..cac4583b0f0 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -42,7 +42,8 @@ import { type TrackRequestOptions, } from "./internal.ts"; import { CACHE_EXPIRY, grace, Ledger } from "./ledger.ts"; -import { Timescale, Timestamp } from "./time.ts"; +import { rescale } from "./rescale.ts"; +import { Timescale, type Timestamp } from "./time.ts"; import { checkSequence, max, min } from "./util/sequence.ts"; import { type Holdings, @@ -177,29 +178,9 @@ export interface Info { * @internal */ unchecked?: boolean; - /** - * `timestamp` at this track's {@link Info.timescale}, rounded as the wire rounds it. 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`. - */ - rescale(timestamp: Timestamp | undefined): Timestamp | undefined; } -// The one implementation of `Info.rescale`, shared by every resolved `Info`. -const INFO_METHODS: Pick = { rescale }; - -function rescale(this: Info, timestamp: Timestamp | undefined): Timestamp | undefined { - const timescale = this.timescale ?? undefined; - if ((timescale !== undefined) !== (timestamp !== undefined)) throw new TimestampMismatch(); - if (timestamp === undefined || timescale === undefined) return undefined; - try { - return new Timestamp(Math.round(timestamp.as(timescale)), timescale); - } catch (cause) { - throw new TimestampMismatch({ cause }); - } -} +export { rescale }; // Normalize a duration for the wire, which carries it as an unsigned varint. // @@ -230,8 +211,7 @@ export function infoDefaults(info: Partial = {}): Info { if (info.compress !== undefined && typeof info.compress !== "boolean") throw new TypeError("compress must be a boolean"); const timescale = info.timescale == null ? undefined : Timescale(info.timescale); - // The method lives on the prototype, so the fields stay plain data to compare and copy. - return Object.assign(Object.create(INFO_METHODS) as Pick, { + return { compress: info.compress ?? false, timescale, maxAge: info.maxAge === undefined ? undefined : wireMillis("maxAge", info.maxAge), @@ -239,7 +219,7 @@ export function infoDefaults(info: Partial = {}): Info { refresh: info.refresh == null ? undefined : refreshRatio(info.refresh), ...(info.ietf === undefined ? {} : { ietf: info.ietf }), ...(info.unchecked ? { unchecked: true } : {}), - }); + }; } function refreshRatio(value: number): number { @@ -1122,7 +1102,7 @@ export class Producer { } for (const sink of this.#sinks) { for (const datagram of sink.datagrams.peek()) { - resolved.rescale(datagram.timestamp); + rescale(resolved, datagram.timestamp); } } } catch (err) { @@ -1575,7 +1555,8 @@ export class Producer { // Refuse a datagram whose timedness disagrees with this track's. #checkDatagram(timestamp: Timestamp | undefined): void { - this.#state.info.peek()?.rescale(timestamp); + const info = this.#state.info.peek(); + if (info) rescale(info, timestamp); } // Refuse a write once the track is closed, or at or past its declared end. From 14c453b307ea7ce7ec32e21ed6fd3759d30d573f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 11:51:48 -0800 Subject: [PATCH 06/11] fix(crypto): sign at the timescale the track committed, not the caller's options Co-Authored-By: Claude Opus 5.5 --- js/crypto/src/sign/broadcast.ts | 5 ++++- js/crypto/src/sign/sign.test.ts | 5 ++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/js/crypto/src/sign/broadcast.ts b/js/crypto/src/sign/broadcast.ts index 128df9326dc..07ff923b78b 100644 --- a/js/crypto/src/sign/broadcast.ts +++ b/js/crypto/src/sign/broadcast.ts @@ -47,7 +47,10 @@ export class Producer { sequences = { next: 0n }; this.#sequences.set(name, sequences); } - return Track.Producer.make(inner, this.#key, new Scope(this.#path, this.instance, name), sequences, info); + // 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); } /** End the wrapped broadcast, as `@moq/net`'s `close` does. Idempotent. */ diff --git a/js/crypto/src/sign/sign.test.ts b/js/crypto/src/sign/sign.test.ts index 4f1178f0b29..fe6d4432b08 100644 --- a/js/crypto/src/sign/sign.test.ts +++ b/js/crypto/src/sign/sign.test.ts @@ -73,7 +73,10 @@ 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")); From 371c37a859e4fe7045768e2ed3490b85bf1506df Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 12:11:21 -0800 Subject: [PATCH 07/11] fix(net)!: round a timestamp down to the track's scale, as Rust does JS rounded to the nearest unit (rescale, the IETF object encoder, the lite send-time stamp) while Rust's Timestamp::convert truncates, so 1500us on a millisecond track was 2 in JS and 1 in Rust. JS now floors everywhere it converts a timestamp to a track or wire scale, and the sign interop test checks JS against Rust's rescale for fractional values. Co-Authored-By: Claude Opus 5.5 --- js/crypto/README.md | 2 +- js/crypto/src/sign/sign.test.ts | 2 +- js/net/MIGRATE.md | 5 +++++ js/net/src/ietf/object.test.ts | 3 ++- js/net/src/ietf/object.ts | 6 +++--- js/net/src/lite/publisher.ts | 2 +- js/net/src/rescale.ts | 4 ++-- js/net/src/time.ts | 4 ++-- js/net/src/track.test.ts | 5 ++++- rs/moq-crypto/src/sign/tests.rs | 17 ++++++++++++++--- rs/moq-net/src/model/track.rs | 5 ++++- 11 files changed, 39 insertions(+), 16 deletions(-) diff --git a/js/crypto/README.md b/js/crypto/README.md index 3ef44662516..dfcf6b3ea32 100644 --- a/js/crypto/README.md +++ b/js/crypto/README.md @@ -25,7 +25,7 @@ An endpoint's `SecretKey` signs; its `PublicKey` is the endpoint ID, displayed a 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 +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 diff --git a/js/crypto/src/sign/sign.test.ts b/js/crypto/src/sign/sign.test.ts index fe6d4432b08..d2f1d01da46 100644 --- a/js/crypto/src/sign/sign.test.ts +++ b/js/crypto/src/sign/sign.test.ts @@ -80,7 +80,7 @@ test("frames roundtrip signed, timestamps included", async () => { 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); diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 8d423921a20..b13274940bd 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -9,6 +9,11 @@ How to update your code for each breaking change, newest first. 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/src/ietf/object.test.ts b/js/net/src/ietf/object.test.ts index 22ee0d368f5..34186f7ecb6 100644 --- a/js/net/src/ietf/object.test.ts +++ b/js/net/src/ietf/object.test.ts @@ -22,7 +22,8 @@ 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); }); 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..ddda0f9f06a 100644 --- a/js/net/src/ietf/object.ts +++ b/js/net/src/ietf/object.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 + // on the wire matches what the track declared, rounded down as Rust does. 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)); + const value = Math.floor(timestamp.as(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/lite/publisher.ts b/js/net/src/lite/publisher.ts index 9af1866a7e8..0eed1203008 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -119,7 +119,7 @@ function stamping(version: Version, info: Pick): Stamp /** 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 { const own = stamp.timed && rescale(stamp.timed, timestamp); - return own ? own.value : Math.round(Timestamp.now().as(stamp.timescale)); + return own ? own.value : Math.floor(Timestamp.now().as(stamp.timescale)); } /** diff --git a/js/net/src/rescale.ts b/js/net/src/rescale.ts index cdf6a25b8e1..e0f9e60eb6c 100644 --- a/js/net/src/rescale.ts +++ b/js/net/src/rescale.ts @@ -4,7 +4,7 @@ import { Timestamp } from "./time.ts"; import type { Info } from "./track.ts"; /** - * `timestamp` at `info`'s {@link Info.timescale}, rounded as the wire rounds it. + * `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 @@ -16,7 +16,7 @@ export function rescale(info: Pick, timestamp: Timestamp | un if ((timescale !== undefined) !== (timestamp !== undefined)) throw new TimestampMismatch(); if (timestamp === undefined || timescale === undefined) return undefined; try { - return new Timestamp(Math.round(timestamp.as(timescale)), timescale); + return new Timestamp(Math.floor(timestamp.as(timescale)), timescale); } catch (cause) { throw new TimestampMismatch({ cause }); } diff --git a/js/net/src/time.ts b/js/net/src/time.ts index febc6eac4c8..aadfb02cc51 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. diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 99be98bf8c0..ba01c939839 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -504,11 +504,14 @@ test("refresh must be a u32 ratio", () => { expect(infoDefaults({ refresh: 0 }).refresh).toBe(0); }); -test("rescale matches the track's timeline, rounded as the wire rounds it", () => { +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, undefined)).toThrow(TimestampMismatch); const huge = new Timestamp(Number.MAX_SAFE_INTEGER, Timescale.MILLI); expect(() => rescale({ timescale: Timescale.NANO }, huge)).toThrow(TimestampMismatch); diff --git a/rs/moq-crypto/src/sign/tests.rs b/rs/moq-crypto/src/sign/tests.rs index 3c366ef7d02..3400c5ba22c 100644 --- a/rs/moq-crypto/src/sign/tests.rs +++ b/rs/moq-crypto/src/sign/tests.rs @@ -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-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index be4907c71aa..53923575a2f 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -17172,7 +17172,10 @@ mod test { let timed = Info::timed(); let ms = Timestamp::from_micros(2_400).unwrap(); let rescaled = timed.rescale(Some(ms)).unwrap().unwrap(); - assert_eq!(rescaled.scale(), Timescale::MILLI); + 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(); From 91a8f843e1065148593b851c98887fdccecd1b8b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 12:21:12 -0800 Subject: [PATCH 08/11] fix(net): convert a timestamp's scale exactly before rounding it down Float division gave 4611686020.999999 for 4611686021000000 ns at milliseconds, which then floored a unit short. floorAt converts the whole part in integer math, as Rust's Timestamp::convert does, for rescale, the IETF object encoder, and the lite send-time stamp. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/object.test.ts | 2 ++ js/net/src/ietf/object.ts | 9 +++++---- js/net/src/lite/publisher.ts | 4 ++-- js/net/src/rescale.ts | 25 +++++++++++++++++++++++-- js/net/src/track.test.ts | 3 +++ 5 files changed, 35 insertions(+), 8 deletions(-) diff --git a/js/net/src/ietf/object.test.ts b/js/net/src/ietf/object.test.ts index 34186f7ecb6..a68ee90ec24 100644 --- a/js/net/src/ietf/object.test.ts +++ b/js/net/src/ietf/object.test.ts @@ -24,6 +24,8 @@ test("a timestamp is converted to the track's scale", () => { expect(roundtrip(Timestamp.fromMillis(1234), Timescale.NANO)?.value).toBe(1_234_000_000); // 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); }); 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 ddda0f9f06a..305306de0df 100644 --- a/js/net/src/ietf/object.ts +++ b/js/net/src/ietf/object.ts @@ -1,5 +1,6 @@ import { ProtocolViolation, StreamCode, Stream as StreamError } from "../error.ts"; import { decodePayload } from "../payload.ts"; +import { floorAt } from "../rescale.ts"; import type { Cursor, Reader } from "../stream.ts"; import { concat, encodeVarint, Writer } from "../stream.ts"; import { type Timescale, Timestamp } from "../time.ts"; @@ -41,10 +42,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, rounded down as Rust does. 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.floor(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/lite/publisher.ts b/js/net/src/lite/publisher.ts index 0eed1203008..8574a18dd2e 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -25,7 +25,7 @@ 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 { floorAt, 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 type * as track from "../track.ts"; @@ -119,7 +119,7 @@ function stamping(version: Version, info: Pick): Stamp /** 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 { const own = stamp.timed && rescale(stamp.timed, timestamp); - return own ? own.value : Math.floor(Timestamp.now().as(stamp.timescale)); + return own ? own.value : floorAt(Timestamp.now(), stamp.timescale); } /** diff --git a/js/net/src/rescale.ts b/js/net/src/rescale.ts index e0f9e60eb6c..134e247c7e7 100644 --- a/js/net/src/rescale.ts +++ b/js/net/src/rescale.ts @@ -1,6 +1,6 @@ // 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 { Timestamp } from "./time.ts"; +import { type Timescale, Timestamp } from "./time.ts"; import type { Info } from "./track.ts"; /** @@ -16,8 +16,29 @@ export function rescale(info: Pick, timestamp: Timestamp | un if ((timescale !== undefined) !== (timestamp !== undefined)) throw new TimestampMismatch(); if (timestamp === undefined || timescale === undefined) return undefined; try { - return new Timestamp(Math.floor(timestamp.as(timescale)), timescale); + return new Timestamp(floorAt(timestamp, timescale), timescale); } catch (cause) { throw new TimestampMismatch({ cause }); } } + +/** + * `timestamp`'s value at `scale`, rounded down exactly as Rust's integer `Timestamp::convert`. + * + * The whole part converts in integer math, so a value already aligned to `scale` keeps it + * instead of losing a unit to floating-point division (4611686021000000 ns is 4611686021 ms, + * where `as` gives 4611686020.999999). Throws a `RangeError` past the safe integer range. + */ +export function floorAt(timestamp: Timestamp, scale: Timescale): number { + const { value, scale: from } = timestamp; + const whole = Math.floor(value); + if (from === scale) return whole; + const product = BigInt(whole) * BigInt(scale); + const quotient = product / BigInt(from); + // The remainder and the fraction stay below one unit at `scale` each, well inside float precision. + const rest = Number(product % BigInt(from)) + (value - whole) * scale; + const result = Number(quotient) + Math.floor(rest / from); + if (!Number.isSafeInteger(result)) + throw new RangeError(`timestamp ${value} at ${from} exceeds the safe range at ${scale}`); + return result; +} diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index ba01c939839..276284c82a6 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -512,6 +512,9 @@ test("rescale matches the track's timeline, rounded down as Rust's convert does" // 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); expect(() => rescale(timed, undefined)).toThrow(TimestampMismatch); const huge = new Timestamp(Number.MAX_SAFE_INTEGER, Timescale.MILLI); expect(() => rescale({ timescale: Timescale.NANO }, huge)).toThrow(TimestampMismatch); From 2b453bc7c9117030cb70a15afb34f6cc77f12643 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 12:27:23 -0800 Subject: [PATCH 09/11] fix(net): floor a timestamp's scale conversion in exact rational math A fractional value still went through float arithmetic, so one instant could floor differently depending on its source scale. floorAt now decomposes the double into mantissa * 2^exponent and divides in BigInt, the decomposition isBefore already uses, and lives in time.ts (internal). Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/object.ts | 3 +-- js/net/src/lite/publisher.ts | 4 ++-- js/net/src/rescale.ts | 23 +---------------------- js/net/src/time.ts | 20 ++++++++++++++++++++ js/net/src/track.test.ts | 5 +++++ 5 files changed, 29 insertions(+), 26 deletions(-) diff --git a/js/net/src/ietf/object.ts b/js/net/src/ietf/object.ts index 305306de0df..9630317c62f 100644 --- a/js/net/src/ietf/object.ts +++ b/js/net/src/ietf/object.ts @@ -1,9 +1,8 @@ import { ProtocolViolation, StreamCode, Stream as StreamError } from "../error.ts"; import { decodePayload } from "../payload.ts"; -import { floorAt } from "../rescale.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"; diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 8574a18dd2e..80394a11a91 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -25,9 +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 { floorAt, rescale } from "../rescale.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"; diff --git a/js/net/src/rescale.ts b/js/net/src/rescale.ts index 134e247c7e7..216eb487733 100644 --- a/js/net/src/rescale.ts +++ b/js/net/src/rescale.ts @@ -1,6 +1,6 @@ // 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 { type Timescale, Timestamp } from "./time.ts"; +import { floorAt, Timestamp } from "./time.ts"; import type { Info } from "./track.ts"; /** @@ -21,24 +21,3 @@ export function rescale(info: Pick, timestamp: Timestamp | un throw new TimestampMismatch({ cause }); } } - -/** - * `timestamp`'s value at `scale`, rounded down exactly as Rust's integer `Timestamp::convert`. - * - * The whole part converts in integer math, so a value already aligned to `scale` keeps it - * instead of losing a unit to floating-point division (4611686021000000 ns is 4611686021 ms, - * where `as` gives 4611686020.999999). Throws a `RangeError` past the safe integer range. - */ -export function floorAt(timestamp: Timestamp, scale: Timescale): number { - const { value, scale: from } = timestamp; - const whole = Math.floor(value); - if (from === scale) return whole; - const product = BigInt(whole) * BigInt(scale); - const quotient = product / BigInt(from); - // The remainder and the fraction stay below one unit at `scale` each, well inside float precision. - const rest = Number(product % BigInt(from)) + (value - whole) * scale; - const result = Number(quotient) + Math.floor(rest / from); - if (!Number.isSafeInteger(result)) - throw new RangeError(`timestamp ${value} at ${from} exceeds the safe range at ${scale}`); - return result; -} diff --git a/js/net/src/time.ts b/js/net/src/time.ts index aadfb02cc51..0cdb6596e7a 100644 --- a/js/net/src/time.ts +++ b/js/net/src/time.ts @@ -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 276284c82a6..6d6be3f88f9 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -515,6 +515,11 @@ test("rescale matches the track's timeline, rounded down as Rust's convert does" 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); expect(() => rescale(timed, undefined)).toThrow(TimestampMismatch); const huge = new Timestamp(Number.MAX_SAFE_INTEGER, Timescale.MILLI); expect(() => rescale({ timescale: Timescale.NANO }, huge)).toThrow(TimestampMismatch); From 455186d0366c0e5451cbeb12f49f3702db4f36ae Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 12:34:51 -0800 Subject: [PATCH 10/11] test(net): pin one binary value at two scales flooring alike Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/object.test.ts | 3 +++ js/net/src/track.test.ts | 3 +++ 2 files changed, 6 insertions(+) diff --git a/js/net/src/ietf/object.test.ts b/js/net/src/ietf/object.test.ts index a68ee90ec24..9150c5fe905 100644 --- a/js/net/src/ietf/object.test.ts +++ b/js/net/src/ietf/object.test.ts @@ -26,6 +26,9 @@ test("a timestamp is converted to the track's scale", () => { 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/track.test.ts b/js/net/src/track.test.ts index 6d6be3f88f9..abad37e2ff9 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -520,6 +520,9 @@ test("rescale matches the track's timeline, rounded down as Rust's convert does" 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); From 084d901baef55233c5a2a746a0fd5b462d67323e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 12:36:15 -0800 Subject: [PATCH 11/11] docs(crypto): name Track.rescale, migrate to moq_crypto paths, fix the e2ee example Co-Authored-By: Claude Opus 5.5 --- js/crypto/README.md | 2 +- rs/moq-crypto/MIGRATE.md | 8 ++++---- rs/moq-crypto/README.md | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/js/crypto/README.md b/js/crypto/README.md index dfcf6b3ea32..29316633daf 100644 --- a/js/crypto/README.md +++ b/js/crypto/README.md @@ -7,7 +7,7 @@ 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 its track's `Info.rescale` before signing or encrypting, so a frame either accepts is +timestamp with `@moq/net`'s `Track.rescale(info, timestamp)` before signing or encrypting, so a frame either accepts is one `@moq/net` accepts. ## Signing diff --git a/rs/moq-crypto/MIGRATE.md b/rs/moq-crypto/MIGRATE.md index 706229d793e..3cd3abc1cc7 100644 --- a/rs/moq-crypto/MIGRATE.md +++ b/rs/moq-crypto/MIGRATE.md @@ -15,7 +15,7 @@ Depend on `moq-crypto` and rename the imports: | `moq_e2ee::…` | `moq_crypto::e2ee::…` | | `moq_sign::…` | `moq_crypto::sign::…` | -`moq_e2ee`'s entries below predate the merge and apply to `moq_crypto::e2ee`. +`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) @@ -30,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?; ``` @@ -42,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 index 416eaa3ffb7..4281ab09a79 100644 --- a/rs/moq-crypto/README.md +++ b/rs/moq-crypto/README.md @@ -75,10 +75,10 @@ learns only its length rounded up to 16 bytes. A track served on demand is reser ```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 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)?; -broadcast.announce(Route::default().with_instance(generation.epoch().instance(), 0))?; +publication.announce(Route::default().with_instance(generation.epoch().instance(), 0))?; ``` A subscriber follows `credential.path(semantic)` with `origin.follow(path, None)`. It takes