@blockcast/mmt-container 0.4.1 → 0.5.0-main.2c1f81817995

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +2 -2
  2. package/dist/browser-runtime.js +3458 -356
  3. package/dist/browser-runtime.js.map +4 -4
  4. package/dist/cmcd-producer.d.ts +5 -1
  5. package/dist/cmcd-producer.d.ts.map +1 -1
  6. package/dist/cmcd-producer.js.map +2 -2
  7. package/dist/delivery-catalog.js +18 -2
  8. package/dist/delivery-catalog.js.map +2 -2
  9. package/dist/fec-manager.d.ts +21 -16
  10. package/dist/fec-manager.d.ts.map +1 -1
  11. package/dist/fec-manager.js +177 -80
  12. package/dist/fec-manager.js.map +3 -3
  13. package/dist/held-layer-admission.d.ts +58 -0
  14. package/dist/held-layer-admission.d.ts.map +1 -0
  15. package/dist/held-layer-admission.js +105 -0
  16. package/dist/held-layer-admission.js.map +7 -0
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js.map +2 -2
  19. package/dist/mmtp-container-parser.no-modules.js +2682 -1023
  20. package/dist/mmtp-container-parser.no-modules.js.map +4 -4
  21. package/dist/mmtp-fec-session.d.ts +36 -3
  22. package/dist/mmtp-fec-session.d.ts.map +1 -1
  23. package/dist/mmtp-fec-session.js +114 -5
  24. package/dist/mmtp-fec-session.js.map +3 -3
  25. package/dist/mmtp-router.d.ts +72 -28
  26. package/dist/mmtp-router.d.ts.map +1 -1
  27. package/dist/mmtp-router.js +321 -203
  28. package/dist/mmtp-router.js.map +2 -2
  29. package/dist/multicast-auth-catalog.d.ts +10 -2
  30. package/dist/multicast-auth-catalog.d.ts.map +1 -1
  31. package/dist/multicast-auth-catalog.js +422 -22
  32. package/dist/multicast-auth-catalog.js.map +4 -4
  33. package/dist/multicast-manager.d.ts +48 -9
  34. package/dist/multicast-manager.d.ts.map +1 -1
  35. package/dist/multicast-manager.js +3406 -340
  36. package/dist/multicast-manager.js.map +4 -4
  37. package/dist/multicast-transport.d.ts +4 -1
  38. package/dist/multicast-transport.d.ts.map +1 -1
  39. package/dist/multicast-transport.js +20 -3
  40. package/dist/multicast-transport.js.map +2 -2
  41. package/dist/no-modules.d.ts +1 -2
  42. package/dist/no-modules.d.ts.map +1 -1
  43. package/dist/no-modules.js +2668 -1007
  44. package/dist/no-modules.js.map +4 -4
  45. package/dist/repair-fetch.d.ts +10 -1
  46. package/dist/repair-fetch.d.ts.map +1 -1
  47. package/dist/repair-fetch.js +5 -2
  48. package/dist/repair-fetch.js.map +2 -2
  49. package/package.json +5 -14
  50. package/src/cmcd-producer.ts +6 -1
  51. package/src/fec-manager.ts +121 -131
  52. package/src/held-layer-admission.ts +161 -0
  53. package/src/index.ts +5 -9
  54. package/src/mmtp-fec-session.ts +76 -3
  55. package/src/mmtp-router.ts +390 -272
  56. package/src/multicast-auth-catalog.ts +81 -8
  57. package/src/multicast-manager.ts +189 -48
  58. package/src/multicast-transport.ts +6 -2
  59. package/src/no-modules.ts +1 -6
  60. package/src/repair-fetch.ts +24 -4
  61. package/dist/manifest-auth-plan.d.ts +0 -31
  62. package/dist/manifest-auth-plan.d.ts.map +0 -1
  63. package/dist/manifest-auth-plan.js +0 -426
  64. package/dist/manifest-auth-plan.js.map +0 -7
  65. package/dist/source-auth.d.ts +0 -2
  66. package/dist/source-auth.d.ts.map +0 -1
  67. package/dist/source-auth.js +0 -3912
  68. package/dist/source-auth.js.map +0 -7
  69. package/src/manifest-auth-plan.ts +0 -55
  70. package/src/source-auth.ts +0 -1
  71. package/test-vectors/generate-source-auth-fixture.mjs +0 -114
  72. package/test-vectors/source-auth-v1.json +0 -61
@@ -16,7 +16,7 @@
16
16
  */
17
17
 
18
18
  import { multicastCatalogIssues } from "@blockcast/mmt-base";
19
- import { manifestKeyFor, type ManifestKey } from "@blockcast/mmt-manifest-verify";
19
+ import { bcProvenanceV2Ctx, type BcProvenanceV2Params, type BcpV2Key } from "@blockcast/mmt-manifest-verify";
20
20
 
21
21
  export type MulticastAuthScheme = "bc-provenance";
22
22
  export type MulticastAuthSig = "ed25519";
@@ -153,11 +153,13 @@ export interface ResolvedMulticastAuthFlow {
153
153
  manifestTimerMs: number;
154
154
  manifestTrack?: string;
155
155
  tracks: Array<{ name: string; packetId: number }>;
156
+ /** `ctx` recomputed from the catalog (7.2.4); present when `namespaceFields` was given. */
157
+ ctx?: Uint8Array;
156
158
  }
157
159
 
158
160
  export interface ResolvedMulticastAuthConfig {
159
161
  /** Decoded keys, ascending by `firstEpoch`. */
160
- keys: ManifestKey[];
162
+ keys: BcpV2Key[];
161
163
  minEpoch: number;
162
164
  flows: ResolvedMulticastAuthFlow[];
163
165
  }
@@ -171,10 +173,19 @@ export interface ResolvedMulticastAuthConfig {
171
173
  * `firstEpoch`, the retired root key) throws, so nothing is admitted and
172
174
  * nothing falls back to unauthenticated reception. An endpoint the rules make
173
175
  * a receiver ignore yields no flow; the others still bind.
176
+ *
177
+ * `namespaceFields` are the Track Namespace Fields of the catalog track, as
178
+ * MOQT carries them. With them every flow carries the recomputed `ctx`, which
179
+ * the receiver compares against each record; without them `ctx` is carried
180
+ * blind (7.2.4).
174
181
  */
175
182
  export function resolveMulticastAuthCatalog(
176
183
  catalog: unknown,
177
- options: { requireAuth?: boolean; catalogNamespace?: string } = {},
184
+ options: {
185
+ requireAuth?: boolean;
186
+ catalogNamespace?: string;
187
+ namespaceFields?: readonly (string | Uint8Array)[];
188
+ } = {},
178
189
  ): ResolvedMulticastAuthConfig | undefined {
179
190
  if (typeof catalog !== "object" || catalog === null || Array.isArray(catalog)) {
180
191
  throw new Error("[multicast-auth-catalog] catalog must be an object");
@@ -192,10 +203,22 @@ export function resolveMulticastAuthCatalog(
192
203
  }
193
204
  const ignored = new Set(issues.map((issue) => issue.endpointIndex));
194
205
  const endpoints = (multicast!["endpoints"] ?? []) as Array<Record<string, unknown>>;
206
+ const catalogTracks = ((catalog as Record<string, unknown>)["tracks"] ?? []) as Array<Record<string, unknown>>;
195
207
  const flows: ResolvedMulticastAuthFlow[] = [];
196
208
  endpoints.forEach((endpoint, endpointIndex) => {
197
209
  if (ignored.has(endpointIndex)) return;
198
210
  const flowAuth = endpoint["auth"] as EndpointAuthConfig;
211
+ const tracks = ((endpoint["tracks"] ?? []) as Array<{ name: string; packetId: number }>).map(({ name, packetId }) => ({
212
+ name,
213
+ packetId,
214
+ }));
215
+ let ctx: Uint8Array | undefined;
216
+ if (options.namespaceFields !== undefined) {
217
+ const params = ctxParams(catalogTracks, tracks);
218
+ // No catalog entry to hash: the endpoint is ignored, nothing is read unauthenticated.
219
+ if (params === undefined) return;
220
+ ctx = bcProvenanceV2Ctx(options.namespaceFields, tracks.map((track) => track.packetId), params);
221
+ }
199
222
  flows.push({
200
223
  endpointIndex,
201
224
  source: (endpoint["sourceAddress"] ?? flowAuth.senderAddress) as string,
@@ -207,10 +230,8 @@ export function resolveMulticastAuthCatalog(
207
230
  maxAuthDelayMs: flowAuth.maxAuthDelayMs ?? DEFAULT_MAX_AUTH_DELAY_MS,
208
231
  manifestTimerMs: flowAuth.manifestTimerMs ?? DEFAULT_MANIFEST_TIMER_MS,
209
232
  ...(flowAuth.manifestTrack === undefined ? {} : { manifestTrack: flowAuth.manifestTrack }),
210
- tracks: ((endpoint["tracks"] ?? []) as Array<{ name: string; packetId: number }>).map(({ name, packetId }) => ({
211
- name,
212
- packetId,
213
- })),
233
+ tracks,
234
+ ...(ctx === undefined ? {} : { ctx }),
214
235
  });
215
236
  });
216
237
  return {
@@ -222,6 +243,55 @@ export function resolveMulticastAuthCatalog(
222
243
  };
223
244
  }
224
245
 
246
+ /** A positive integer that fits the u32 it is hashed as (7.2.4), else `0`. */
247
+ function positiveInteger(value: unknown): number {
248
+ return typeof value === "number" && Number.isSafeInteger(value) && value > 0 && value <= 0xffffffff ? value : 0;
249
+ }
250
+
251
+ /**
252
+ * `params_hash` inputs (7.2.4): the catalog entry of the endpoint's
253
+ * lowest-`packetId` media track or, for a repair-only endpoint, of the source
254
+ * its lowest-`packetId` repair track repairs (`depends`, else the track whose
255
+ * `fec.repairTrack` names it). A timescale or group duration that does not
256
+ * resolve to an integer tick count is `0`.
257
+ */
258
+ function ctxParams(
259
+ catalogTracks: Array<Record<string, unknown>>,
260
+ listed: Array<{ name: string; packetId: number }>,
261
+ ): BcProvenanceV2Params | undefined {
262
+ const byName = new Map(catalogTracks.map((track) => [track["name"], track]));
263
+ const ordered = [...listed].sort((a, b) => a.packetId - b.packetId).map(({ name }) => byName.get(name));
264
+ let entry = ordered.find((track) => track !== undefined && track["packaging"] !== "fec-repair");
265
+ if (entry === undefined) {
266
+ const repair = ordered.find((track) => track !== undefined);
267
+ if (repair === undefined) return undefined;
268
+ const depends = repair["depends"];
269
+ entry = Array.isArray(depends) && depends.length === 1
270
+ ? byName.get(depends[0])
271
+ : catalogTracks.find((track) => (track["fec"] as Record<string, unknown> | undefined)?.["repairTrack"] === repair["name"]);
272
+ if (entry === undefined) return undefined;
273
+ }
274
+ const timescale = positiveInteger(entry["timescale"]);
275
+ const ms = positiveInteger(entry["groupDurationMs"]);
276
+ const groupDurationTicks = positiveInteger(entry["groupDurationTicks"]) ||
277
+ positiveInteger(timescale && (ms * timescale) % 1000 === 0 ? (ms * timescale) / 1000 : 0);
278
+ const fec = entry["fec"] as Record<string, unknown> | undefined;
279
+ return {
280
+ codec: typeof entry["codec"] === "string" ? entry["codec"] : "",
281
+ timescale,
282
+ groupDurationTicks,
283
+ ...(fec === undefined || fec === null ? {} : {
284
+ fec: {
285
+ algorithm: typeof fec["algorithm"] === "string" ? fec["algorithm"] : "",
286
+ sourceSymbols: positiveInteger(fec["sourceSymbols"]),
287
+ repairSymbols: positiveInteger(fec["repairSymbols"]),
288
+ symbolSize: positiveInteger(fec["symbolSize"]),
289
+ interleaveDepthMs: positiveInteger(fec["interleaveDepthMs"]),
290
+ },
291
+ }),
292
+ };
293
+ }
294
+
225
295
  /** The key that signs a record of `kid` at `epoch`, or `undefined` when that
226
296
  * `kid` does not sign it (7.2.7: such a record is dropped before verification). */
227
297
  export function multicastAuthKeyFor(
@@ -229,5 +299,8 @@ export function multicastAuthKeyFor(
229
299
  kid: number,
230
300
  epoch: number,
231
301
  ): Uint8Array | undefined {
232
- return manifestKeyFor(resolved.keys, epoch, kid);
302
+ // `keys` is ascending by firstEpoch with unique kid and firstEpoch (resolve throws otherwise).
303
+ const signers = resolved.keys.filter((key) => key.firstEpoch <= epoch);
304
+ const signer = signers[signers.length - 1];
305
+ return signer?.kid === kid ? signer.publicKey : undefined;
233
306
  }
@@ -43,7 +43,6 @@ import type {
43
43
  import {
44
44
  MmtpRouter,
45
45
  type FrameCallback,
46
- type ManifestIdentityResolver,
47
46
  type MmtpIngressContext,
48
47
  type MmtpStreamIdentity,
49
48
  type StagedStreamSwitch,
@@ -56,8 +55,11 @@ import {
56
55
  type MulticastFailbackReason,
57
56
  type MulticastJoinOutcome,
58
57
  type MulticastJoinStats,
58
+ type MulticastTransportConfig,
59
59
  } from "./multicast-transport.js";
60
60
  import { computeFecDeliveryWindowMs } from "./track-session.js";
61
+ import { BcProvenanceV2Receiver, type BcpV2ReceiverConfig } from "@blockcast/mmt-manifest-verify";
62
+ import type { ResolvedMulticastAuthConfig, ResolvedMulticastAuthFlow } from "./multicast-auth-catalog.js";
61
63
  import { DEFAULT_AMT_RELAY_PORT } from "./catalog-network-source.js";
62
64
  import { deriveFecInterleaveDepth, FecBlockMapper } from "@blockcast/mmt-fec";
63
65
  import type {
@@ -68,10 +70,6 @@ import type {
68
70
  } from "@blockcast/fec-worker";
69
71
  import type { MfuReassemblerBackend } from "./mfu-reassembler.js";
70
72
  import type { MfuReassemblyPolicy } from "./mfu-reassembly-policy.js";
71
- import type {
72
- ManifestObjectIdentity,
73
- ManifestVerifier,
74
- } from "@blockcast/mmt-manifest-verify";
75
73
  import type {
76
74
  BlockAssemblerConfig,
77
75
  CmafBlockSample,
@@ -104,6 +102,8 @@ export interface MulticastRepairEndpoint {
104
102
  repairOwners: ReadonlyArray<{ packetId: number; ownerPacketId: number }>;
105
103
  /** Ingress tracks: the owners' source tracks and the repair tracks. */
106
104
  tracks: MmtpIngressContext["tracks"];
105
+ /** The protected flow (`MmtpRouter.registerProvenanceFlow`) this group's datagrams belong to. */
106
+ flow?: string;
107
107
  }
108
108
 
109
109
  /**
@@ -116,8 +116,32 @@ export type MulticastRepairSubscribe = (
116
116
  onPacket: (packet: Uint8Array) => void,
117
117
  ) => (() => void) | Promise<() => void>;
118
118
 
119
+ /**
120
+ * A protected endpoint's join (draft -01 7.2.7): the keys and flow
121
+ * `resolveMulticastAuthCatalog` resolved for it. The join registers the flow
122
+ * with the router and subscribes `manifestPort` on the same `(S, G)` beside
123
+ * the media, so every media datagram is admitted by a record before it is read.
124
+ */
125
+ export interface MulticastProvenanceJoin {
126
+ auth: Pick<ResolvedMulticastAuthConfig, "keys" | "minEpoch">;
127
+ flow: ResolvedMulticastAuthFlow;
128
+ /** Receiver options beyond the catalog's (ctx, clock, freshness, W, lead). */
129
+ receiver?: Omit<Partial<BcpV2ReceiverConfig>, "endpoint" | "keys" | "minEpoch" | "bandwidth" | "maxAuthDelayMs" | "manifestTimerMs">;
130
+ }
131
+
119
132
  export interface MulticastEndpointConfig {
120
- sourceAddress: string;
133
+ /** SSM source; omitted on ASM. */
134
+ sourceAddress?: string;
135
+ /** ASM sender filter: `auth.senderAddress` of a protected ASM endpoint. Never beside `sourceAddress`. */
136
+ senderAddress?: string;
137
+ /**
138
+ * Present on a protected endpoint: the join admits through bc-provenance v2.
139
+ * From its first admission (`onProtected`) MoQ copies of the listed tracks
140
+ * are dropped until the media transport fails back (silence or a
141
+ * subscription error); the manager un-protects then whether or not a player
142
+ * registered `onFailback`.
143
+ */
144
+ provenance?: MulticastProvenanceJoin;
121
145
  groupAddress: string;
122
146
  port: number;
123
147
  /** Explicit gateway transport policy. Omitted means gateway-selected auto mode. */
@@ -190,15 +214,6 @@ export interface MulticastManagerOptions {
190
214
  reassemblyPolicy?: MfuReassemblyPolicy;
191
215
  reassembler?: MfuReassemblerBackend;
192
216
  maxBufferedMfus?: number;
193
- manifestVerifier?: ManifestVerifier;
194
- manifestVerifierOwnership?: "caller" | "router";
195
- resolveManifestIdentity?: (
196
- packetId: number,
197
- sbn: number,
198
- esi: number,
199
- catalogTrackName?: string,
200
- ) => ManifestObjectIdentity | null;
201
- resolveManifestIdentityForRoute?: ManifestIdentityResolver;
202
217
  /**
203
218
  * Also write every repair lifecycle event to the console as one
204
219
  * `REPAIR_LIFECYCLE_LOG_PREFIX` JSON line. Off unless asked for: the lines
@@ -296,11 +311,13 @@ interface ActiveRenditionSwitch {
296
311
  state: RenditionSwitchState;
297
312
  }
298
313
 
299
- function freezeIngress(tracks: Iterable<Readonly<{ name: string; packetId: number }>>): MmtpIngressContext {
314
+ /** `flow` is the live join's protected flow: every ingress a switch installs keeps it, or the router reads media unauthenticated. */
315
+ function freezeIngress(tracks: Iterable<Readonly<{ name: string; packetId: number }>>, flow: string | undefined): MmtpIngressContext {
300
316
  return Object.freeze({
301
317
  tracks: Object.freeze(
302
318
  [...tracks].map(({ name, packetId }) => Object.freeze({ name, packetId })),
303
319
  ),
320
+ ...(flow === undefined ? {} : { flow }),
304
321
  });
305
322
  }
306
323
 
@@ -488,6 +505,11 @@ export interface BlockPolicyStats {
488
505
  * §7.5 anchor (no epoch reference, or none it could be extended from).
489
506
  */
490
507
  repairsSkippedRangeNoAnchor: number;
508
+ /**
509
+ * `repairsSkipped` by reason: the block's repair group could not complete
510
+ * it (sources + RSB_length < K'), so no FETCH was sent.
511
+ */
512
+ repairsSkippedGroupCannotComplete: number;
491
513
  /**
492
514
  * The most recent skip: its reason, the measured RTT (null when
493
515
  * unmeasured), the time that was left to the deadline, and the request's
@@ -549,6 +571,7 @@ function newBlockPolicyStats(
549
571
  repairsSkippedRttExceedsBudget: 0,
550
572
  repairsSkippedPresentationDelayUnavailable: 0,
551
573
  repairsSkippedRangeNoAnchor: 0,
574
+ repairsSkippedGroupCannotComplete: 0,
552
575
  lastRepairSkip: null,
553
576
  keyframeRepairFetchesSent: 0,
554
577
  rangeRepairFetchesSent: 0,
@@ -701,6 +724,8 @@ const REPAIR_SKIP_REASONS: ReadonlySet<unknown> = new Set([
701
724
  "rtt-unmeasured",
702
725
  "rtt-exceeds-budget",
703
726
  "presentation-delay-unavailable",
727
+ "range-no-anchor",
728
+ "group-cannot-complete",
704
729
  ]);
705
730
  const REPAIR_DEADLINE_BOUNDS: ReadonlySet<unknown> = new Set(["wait", "presentation", "keyframe", "retention"]);
706
731
  const GAP_REASONS: Readonly<Record<string, "stall" | "conceal">> = {
@@ -1211,6 +1236,10 @@ export class MulticastManager {
1211
1236
  readonly #router: MmtpRouter;
1212
1237
  #hostMfuTimeoutMs: number | null;
1213
1238
  readonly #transport: MulticastTransport<MmtpIngressContext>;
1239
+ /** The protected flow of the current join and its manifestPort subscription. */
1240
+ #provenanceJoin: { flow: string; manifest: MulticastTransport } | null = null;
1241
+ #onFailback: ((reason: MulticastFailbackReason) => void) | null = null;
1242
+ #failbackHooked = false;
1214
1243
  /** Live joinRepairEndpoints() releases → the repair owners they registered,
1215
1244
  * re-applied after configureMultiTrack() clears catalog-derived owners. */
1216
1245
  readonly #repairReleases = new Map<() => void, MulticastRepairEndpoint["repairOwners"]>();
@@ -1276,10 +1305,6 @@ export class MulticastManager {
1276
1305
  reassemblyPolicy: options?.reassemblyPolicy,
1277
1306
  reassembler: options?.reassembler,
1278
1307
  maxBufferedMfus: options?.maxBufferedMfus,
1279
- manifestVerifier: options?.manifestVerifier,
1280
- manifestVerifierOwnership: options?.manifestVerifierOwnership,
1281
- resolveManifestIdentity: options?.resolveManifestIdentity,
1282
- resolveManifestIdentityForRoute: options?.resolveManifestIdentityForRoute,
1283
1308
  // The router has reset its own state for the stream; reset the rest.
1284
1309
  onPublisherRestart: (packetId, catalogTrackName) => {
1285
1310
  this.#resetStreamOutsideRouter(packetId, catalogTrackName);
@@ -1326,7 +1351,7 @@ export class MulticastManager {
1326
1351
  });
1327
1352
  this.#hostMfuTimeoutMs = this.#router.reassembler.timeoutMs;
1328
1353
  this.#transport = new MulticastTransport<MmtpIngressContext>((packet, ingress) => {
1329
- this.#router.feedPacket(packet, "multicast", undefined, ingress);
1354
+ this.#router.feedPacket(packet, "multicast", ingress);
1330
1355
  });
1331
1356
  // Each joined subscription declares how it delivers packets. An ordered
1332
1357
  // relay decides FEC block fate by stream order instead of the datagram
@@ -1343,17 +1368,9 @@ export class MulticastManager {
1343
1368
  const recovered = new Uint8Array(data);
1344
1369
  const catalogTrackName = recoveredTrackName
1345
1370
  ?? this.#fec.catalogTrackNameForBlock(sbn, packetId);
1346
- if (catalogTrackName === undefined) {
1347
- this.#router.routeRecoveredSymbol(sbn, recovered, packetId, meta.esi);
1348
- } else {
1349
- this.#router.routeRecoveredSymbol(
1350
- sbn,
1351
- recovered,
1352
- packetId,
1353
- meta.esi,
1354
- catalogTrackName,
1355
- );
1356
- }
1371
+ return catalogTrackName === undefined
1372
+ ? this.#router.routeRecoveredSymbol(sbn, recovered, packetId, meta.esi)
1373
+ : this.#router.routeRecoveredSymbol(sbn, recovered, packetId, meta.esi, catalogTrackName);
1357
1374
  };
1358
1375
 
1359
1376
  // D-28: release the in-flight repair slot when a repair-requested block
@@ -1438,6 +1455,11 @@ export class MulticastManager {
1438
1455
  get router(): MmtpRouter {
1439
1456
  return this.#router;
1440
1457
  }
1458
+ /** Repair FETCH wiring (wireRepairFetch): this manager can request unicast repair. */
1459
+ setUnicastRepair(enabled: boolean): void {
1460
+ this.#router.setUnicastRepair(enabled);
1461
+ }
1462
+
1441
1463
  get transport(): MulticastTransport<MmtpIngressContext> {
1442
1464
  return this.#transport;
1443
1465
  }
@@ -2028,8 +2050,36 @@ export class MulticastManager {
2028
2050
  onTakeover(cb: () => void) {
2029
2051
  this.#transport.onTakeover(cb);
2030
2052
  }
2053
+ /** Failback un-protects the join's flow (7.2.7 failover), so the fallback's MoQ packets are read. */
2031
2054
  onFailback(cb: (reason: MulticastFailbackReason) => void) {
2032
- this.#transport.onFailback(cb);
2055
+ this.#onFailback = cb;
2056
+ this.#hookFailback();
2057
+ }
2058
+
2059
+ /**
2060
+ * Install the manager's own failback listener on the media transport, which
2061
+ * arms its silence watchdog: a protected join un-protects on failover even
2062
+ * when no player listens, else its tracks' MoQ copies stay dropped.
2063
+ */
2064
+ #hookFailback(): void {
2065
+ if (this.#failbackHooked) return;
2066
+ this.#failbackHooked = true;
2067
+ this.#transport.onFailback((reason) => {
2068
+ const joined = this.#provenanceJoin;
2069
+ if (joined !== null) this.#router.unprotectProvenanceFlow(joined.flow);
2070
+ this.#onFailback?.(reason);
2071
+ });
2072
+ }
2073
+ /**
2074
+ * A protected join's handoff (draft -01 7.2.7), before `onTakeover`: its
2075
+ * first admitted datagram. MoQ copies of the flow's tracks the router still
2076
+ * held unadmitted are discarded, and later ones are dropped. Fires again
2077
+ * after a failback once multicast resumes.
2078
+ */
2079
+ onProtected(cb: (() => void) | null) {
2080
+ this.#router.onProvenanceFlowProtected(cb && ((flow) => {
2081
+ if (this.#provenanceJoin?.flow === flow) cb();
2082
+ }));
2033
2083
  }
2034
2084
  /** See MulticastTransport.onDataPlaneLive: the join's first accepted packet. */
2035
2085
  onDataPlaneLive(cb: () => void) {
@@ -2047,6 +2097,17 @@ export class MulticastManager {
2047
2097
  }
2048
2098
 
2049
2099
  async join(config: MulticastEndpointConfig): Promise<boolean> {
2100
+ const provenanceFlow = config.provenance?.flow;
2101
+ if (
2102
+ provenanceFlow !== undefined &&
2103
+ ((config.sourceAddress ?? config.senderAddress) !== provenanceFlow.source ||
2104
+ config.groupAddress !== provenanceFlow.groupAddress ||
2105
+ config.port !== provenanceFlow.port)
2106
+ ) {
2107
+ throw new RangeError(
2108
+ "[MulticastManager] join: provenance flow (S, G, port) must match sourceAddress ?? senderAddress, groupAddress and port",
2109
+ );
2110
+ }
2050
2111
  // A join replaces the admission a staged switch was built on. The new
2051
2112
  // join's config decides what is admitted, so nothing is restored or
2052
2113
  // retired here: the switch just ends.
@@ -2071,22 +2132,27 @@ export class MulticastManager {
2071
2132
  : selectedPacketIds === null
2072
2133
  ? undefined
2073
2134
  : [...selectedPacketIds].map((packetId) => ({ name: "", packetId }));
2074
- const ingress = ingressTracks === undefined
2135
+ this.#releaseProvenanceJoin();
2136
+ const provenance = config.provenance;
2137
+ const protectedTracks = ingressTracks ?? provenance?.flow.tracks;
2138
+ const ingress: MmtpIngressContext | undefined = protectedTracks === undefined
2075
2139
  ? undefined
2076
2140
  : {
2077
2141
  tracks: Object.freeze(
2078
- ingressTracks.map(({ name, packetId }) =>
2142
+ protectedTracks.map(({ name, packetId }) =>
2079
2143
  Object.freeze({ name, packetId }),
2080
2144
  ),
2081
2145
  ),
2146
+ ...(provenance === undefined ? {} : { flow: multicastProvenanceFlowKey(provenance.flow) }),
2082
2147
  };
2083
2148
  // The single relay inlet: the player/UI override, or the catalog's
2084
2149
  // `multicast.networkSource[{type:"amt"}]` relay, which
2085
2150
  // `endpointToMulticastConfig` (packages/transport
2086
2151
  // multicast-catalog-policy.ts) resolves into `amtRelay` via `findAmtRelay`.
2087
2152
  const amtRelay = config.amtRelay;
2088
- const transportConfig = {
2153
+ const transportConfig: MulticastTransportConfig = {
2089
2154
  sourceAddress: config.sourceAddress,
2155
+ senderAddress: config.senderAddress,
2090
2156
  groupAddress: config.groupAddress,
2091
2157
  port: config.port,
2092
2158
  mode: config.mode,
@@ -2116,9 +2182,70 @@ export class MulticastManager {
2116
2182
  packetIds: config.packetIds,
2117
2183
  tracks: catalogTracks?.map(({ name, packetId }) => ({ name, packetId })),
2118
2184
  };
2119
- return ingress === undefined
2185
+ if (provenance !== undefined) this.#joinProvenance(provenance, ingress as MmtpIngressContext & { flow: string }, transportConfig);
2186
+ const protectedJoin = this.#provenanceJoin;
2187
+ const joined = await (ingress === undefined
2120
2188
  ? this.#transport.join(transportConfig)
2121
- : this.#transport.join(transportConfig, ingress);
2189
+ : this.#transport.join(transportConfig, ingress));
2190
+ // No media: leave the manifest subscription and release the flow now, not at the next join.
2191
+ if (!joined && protectedJoin !== null && this.#provenanceJoin === protectedJoin) this.#releaseProvenanceJoin();
2192
+ return joined;
2193
+ }
2194
+
2195
+ /**
2196
+ * Register the protected flow and subscribe its `manifestPort` on the same
2197
+ * `(S, G)` with its own listener (draft -01 7.2.7), so records reach the
2198
+ * flow's receiver and media datagrams are held until one admits them. A
2199
+ * manifest subscription that fails to join admits nothing: the media is
2200
+ * held and expires, never read unauthenticated.
2201
+ */
2202
+ #joinProvenance(
2203
+ provenance: MulticastProvenanceJoin,
2204
+ ingress: MmtpIngressContext & { flow: string },
2205
+ media: MulticastTransportConfig,
2206
+ ): void {
2207
+ const { flow, auth } = provenance;
2208
+ const receiver = new BcProvenanceV2Receiver({
2209
+ ...provenance.receiver,
2210
+ // The caller's ctx when it passes one, else the catalog's: an explicit
2211
+ // `catalogCtx: undefined` must not switch off the 7.2.4 ctx check.
2212
+ catalogCtx: provenance.receiver?.catalogCtx ?? flow.ctx,
2213
+ endpoint: {
2214
+ sourceAddress: flow.source,
2215
+ groupAddress: flow.groupAddress,
2216
+ port: flow.port,
2217
+ manifestPort: flow.manifestPort,
2218
+ streamId: flow.streamId,
2219
+ },
2220
+ keys: auth.keys,
2221
+ minEpoch: auth.minEpoch,
2222
+ bandwidth: flow.bandwidth,
2223
+ maxAuthDelayMs: flow.maxAuthDelayMs,
2224
+ manifestTimerMs: flow.manifestTimerMs,
2225
+ });
2226
+ this.#router.registerProvenanceFlow(ingress, receiver);
2227
+ this.#hookFailback();
2228
+ const manifest = new MulticastTransport((record) => {
2229
+ if (this.#provenanceJoin?.manifest === manifest) {
2230
+ this.#router.feedProvenanceRecord(ingress.flow, record, "multicast");
2231
+ }
2232
+ });
2233
+ this.#provenanceJoin = { flow: ingress.flow, manifest };
2234
+ const { packetIds: _packetIds, tracks: _tracks, ...path } = media;
2235
+ void manifest.join({ ...path, port: flow.manifestPort }).then((joined) => {
2236
+ if (!joined && this.#provenanceJoin?.manifest === manifest) {
2237
+ console.warn(`[MulticastManager] manifestPort ${flow.groupAddress}:${flow.manifestPort} not joined`, manifest.lastJoinOutcome);
2238
+ }
2239
+ });
2240
+ }
2241
+
2242
+ /** Un-protect: drop the flow's hold queues (no expiry counted) and leave its manifestPort. */
2243
+ #releaseProvenanceJoin(): void {
2244
+ const joined = this.#provenanceJoin;
2245
+ if (joined === null) return;
2246
+ this.#provenanceJoin = null;
2247
+ joined.manifest.dispose();
2248
+ this.#router.releaseProvenanceFlow(joined.flow);
2122
2249
  }
2123
2250
 
2124
2251
  /**
@@ -2153,9 +2280,10 @@ export class MulticastManager {
2153
2280
  for (const endpoint of endpoints) {
2154
2281
  const ingress: MmtpIngressContext = {
2155
2282
  tracks: Object.freeze(endpoint.tracks.map(({ name, packetId }) => Object.freeze({ name, packetId }))),
2283
+ ...(endpoint.flow === undefined ? {} : { flow: endpoint.flow }),
2156
2284
  };
2157
2285
  const onPacket = (packet: Uint8Array) => {
2158
- if (!released) this.#router.feedPacket(packet, "multicast", undefined, ingress);
2286
+ if (!released) this.#router.feedPacket(packet, "multicast", ingress);
2159
2287
  };
2160
2288
  const fail = (error: unknown) =>
2161
2289
  console.warn(`[MulticastManager] repair group ${endpoint.group}:${endpoint.port} not joined`, error);
@@ -2323,7 +2451,7 @@ export class MulticastManager {
2323
2451
  for (const track of [...live.tracks, ...request.tracks]) {
2324
2452
  stagedTracks.set(`${track.packetId}\0${track.name}`, track);
2325
2453
  }
2326
- const stagedIngress = freezeIngress(stagedTracks.values());
2454
+ const stagedIngress = freezeIngress(stagedTracks.values(), live.flow);
2327
2455
  const stagedPacketIds =
2328
2456
  committedPacketIds === undefined || livePacketIds === null
2329
2457
  ? null
@@ -2338,7 +2466,7 @@ export class MulticastManager {
2338
2466
  liveIngress: live,
2339
2467
  livePacketIds,
2340
2468
  widened,
2341
- committedIngress: freezeIngress(request.tracks),
2469
+ committedIngress: freezeIngress(request.tracks, live.flow),
2342
2470
  committedPacketIds,
2343
2471
  router: null,
2344
2472
  state: "staged",
@@ -2352,7 +2480,7 @@ export class MulticastManager {
2352
2480
  let widening: Promise<void> | undefined;
2353
2481
  try {
2354
2482
  if (widened) widening = this.#transport.setPacketIds([...stagedPacketIds!]);
2355
- this.#transport.setContext(stagedIngress);
2483
+ this.#setSwitchIngress(stagedIngress);
2356
2484
  } catch (error) {
2357
2485
  active.router.cancel();
2358
2486
  throw error;
@@ -2374,6 +2502,12 @@ export class MulticastManager {
2374
2502
  };
2375
2503
  }
2376
2504
 
2505
+ /** Route a switch's ingress and keep a protected flow's registration in step (7.2.7). */
2506
+ #setSwitchIngress(ingress: MmtpIngressContext): void {
2507
+ this.#transport.setContext(ingress);
2508
+ if (ingress.flow !== undefined) this.#router.updateProvenanceFlowIngress({ ...ingress, flow: ingress.flow });
2509
+ }
2510
+
2377
2511
  /** The router committed the staged switch (it already retired `from`). */
2378
2512
  #commitRenditionSwitch(active: ActiveRenditionSwitch, commit: StreamSwitchCommit): void {
2379
2513
  if (this.#renditionSwitch !== active) return;
@@ -2381,7 +2515,7 @@ export class MulticastManager {
2381
2515
  active.state = "committed";
2382
2516
  active.router = null;
2383
2517
  if (this.#transport.joined) {
2384
- this.#transport.setContext(active.committedIngress);
2518
+ this.#setSwitchIngress(active.committedIngress);
2385
2519
  if (active.committedPacketIds !== undefined) {
2386
2520
  // The page-side filter narrows now; the provider may keep delivering
2387
2521
  // the retired IDs until it applies the narrower list, and the page
@@ -2429,7 +2563,7 @@ export class MulticastManager {
2429
2563
  active.router = null;
2430
2564
  if (restore) {
2431
2565
  if (this.#transport.joined) {
2432
- this.#transport.setContext(active.liveIngress);
2566
+ this.#setSwitchIngress(active.liveIngress);
2433
2567
  if (active.widened && active.livePacketIds !== null) {
2434
2568
  this.#transport.setPacketIds([...active.livePacketIds]).catch((error: unknown) => {
2435
2569
  console.warn(
@@ -2518,8 +2652,8 @@ export class MulticastManager {
2518
2652
  data: Uint8Array,
2519
2653
  packetId: number,
2520
2654
  catalogTrackName?: string,
2521
- ) {
2522
- this.#router.routeRecoveredBlock(blockId, data, packetId, catalogTrackName);
2655
+ ): boolean {
2656
+ return this.#router.routeRecoveredBlock(blockId, data, packetId, catalogTrackName);
2523
2657
  }
2524
2658
 
2525
2659
  /** Route one Worker-recovered source symbol through the MMTP parser + dedup pipeline. */
@@ -2529,8 +2663,8 @@ export class MulticastManager {
2529
2663
  packetId: number,
2530
2664
  esi = 0,
2531
2665
  catalogTrackName?: string,
2532
- ) {
2533
- this.#router.routeRecoveredSymbol(blockId, data, packetId, esi, catalogTrackName);
2666
+ ): boolean {
2667
+ return this.#router.routeRecoveredSymbol(blockId, data, packetId, esi, catalogTrackName);
2534
2668
  }
2535
2669
 
2536
2670
  // ---------------------------------------------------------------------------
@@ -2946,6 +3080,7 @@ export class MulticastManager {
2946
3080
  if (reason === "rtt-unmeasured") stats.repairsSkippedRttUnmeasured++;
2947
3081
  else if (reason === "rtt-exceeds-budget") stats.repairsSkippedRttExceedsBudget++;
2948
3082
  else if (reason === "range-no-anchor") stats.repairsSkippedRangeNoAnchor++;
3083
+ else if (reason === "group-cannot-complete") stats.repairsSkippedGroupCannotComplete++;
2949
3084
  else stats.repairsSkippedPresentationDelayUnavailable++;
2950
3085
  stats.lastRepairSkip = {
2951
3086
  reason,
@@ -3196,6 +3331,7 @@ export class MulticastManager {
3196
3331
  this.#trackResetObservers.clear();
3197
3332
  this.#repairLifecycleObservers.clear();
3198
3333
  this.#transport.dispose();
3334
+ this.#releaseProvenanceJoin();
3199
3335
  for (const release of [...this.#repairReleases.keys()]) release();
3200
3336
  this.#router.dispose();
3201
3337
  this.#fec.dispose();
@@ -3206,3 +3342,8 @@ export class MulticastManager {
3206
3342
  // (wireRepairFetch) drives.
3207
3343
  const repairFetchHost = (manager: MulticastManager): RepairFetchHost => manager;
3208
3344
  void repairFetchHost;
3345
+
3346
+ /** The router's key of a protected flow: its `(S, G, port)`. */
3347
+ export function multicastProvenanceFlowKey(flow: Pick<ResolvedMulticastAuthFlow, "source" | "groupAddress" | "port">): string {
3348
+ return JSON.stringify([flow.source, flow.groupAddress, flow.port]);
3349
+ }
@@ -19,7 +19,10 @@ import {
19
19
  } from '@blockcast/mmt-base'
20
20
 
21
21
  export interface MulticastTransportConfig {
22
- sourceAddress: string
22
+ /** SSM source; omitted on ASM. */
23
+ sourceAddress?: string
24
+ /** ASM sender filter (multicast-contract 1.1.0 `senderAddress`); never beside `sourceAddress`. */
25
+ senderAddress?: string
23
26
  groupAddress: string
24
27
  port: number
25
28
  mode?: 'auto' | 'native' | 'tunnel'
@@ -368,10 +371,11 @@ export class MulticastTransport<TPacketContext = never> {
368
371
  try {
369
372
  const packetIds = config.packetIds?.length ? new Set(config.packetIds) : null
370
373
  console.log(
371
- `[MulticastTransport] window.multicast.subscribe(${config.sourceAddress}, ${config.groupAddress}, ${config.port})`,
374
+ `[MulticastTransport] window.multicast.subscribe(${config.sourceAddress ?? config.senderAddress ?? '*'}, ${config.groupAddress}, ${config.port})`,
372
375
  )
373
376
  const subscribeConfig = toWindowMulticastSubscribeConfig({
374
377
  source: config.sourceAddress,
378
+ senderAddress: config.senderAddress,
375
379
  group: config.groupAddress,
376
380
  port: config.port,
377
381
  mode: config.mode,
package/src/no-modules.ts CHANGED
@@ -19,9 +19,4 @@ export { MmtpToCmaf } from './mmtp-to-cmaf.js'
19
19
  // reach only this classic-script surface, so it has to be exported here as
20
20
  // well as from the barrel (BLO-49943).
21
21
  export { isFmp4InitSegment } from './codec-utils.js'
22
- export { createManifestAuthPlan } from './manifest-auth-plan.js'
23
- export {
24
- ManifestVerifier,
25
- createWebCryptoEd25519Verifier,
26
- manifestBindingId,
27
- } from '@blockcast/mmt-manifest-verify'
22
+ export { BcProvenanceV2Receiver } from '@blockcast/mmt-manifest-verify'