@blockcast/mmt-base 0.3.0 → 0.4.0-main.2654dbc2ed6d

package/src/mmtp.ts

@@ -1,10 +1,3 @@
-import {
-  MMTP_EXT_TYPE_ALTA_AUTH as _LEAF_MMTP_EXT_TYPE_ALTA_AUTH,
-  MMTP_EXT_TRAILER_HEADER_SIZE as _LEAF_MMTP_EXT_TRAILER_HEADER_SIZE,
-  extractAltaTrailer as _leafExtractAltaTrailer,
-  type AltaTrailer as _LeafAltaTrailer,
-} from '@blockcast/mmt-alta-parse'
-
 /**
  * @mmt/container - MMTP Parser
  *
@@ -81,7 +74,7 @@ export const MFU_DU_HEADER_SIZE_NONTIMED = 4  // T=0: non-timed media (item_id o
 
 const MPU_LENGTH_FIELD_SIZE = 2
 const MPU_HEADER_REMAINDER_SIZE = MPU_HEADER_SIZE - MPU_LENGTH_FIELD_SIZE
-const SOURCE_FEC_PAYLOAD_ID_SIZE = 4
+export const SOURCE_FEC_PAYLOAD_ID_SIZE = 4
 
 // MMTP Packet Types (ISO/IEC 23008-1:2023 Section 9.2.2)
 export const PACKET_TYPE_MPU = 0x00
@@ -103,9 +96,10 @@ export const MMTP_SIGNALING_PACKET_ID = 0
 /** Largest value of the 16-bit MMTP `packet_id` header field. */
 export const MMTP_PACKET_ID_MAX = 0xffff
 
-// FEC Code IDs
-export const FEC_CODE_XOR = 1
-export const FEC_CODE_RAPTORQ = 2
+// fec_code_id_for_repair_flow code points (ISO/IEC 23008-10 Table 1;
+// draft-ramadan-moq-mmt-01 Section 8.3).
+export const FEC_CODE_REED_SOLOMON = 1
+export const FEC_CODE_RAPTORQ = 3
 
 /**
  * Parse MMTP header from buffer
@@ -353,9 +347,17 @@ function resolveMfuPayloadLayout(
   }
 }
 
-function isEmptyOrExactAltaTrailer(payload: Uint8Array, start: number, end: number): boolean {
+// Legacy detached per-packet authenticator suffix `[0xf0a1][len][auth]`. Its
+// producer was removed (BLO-16483) and nothing verifies it any more; provenance
+// is the signed per-group manifest. Receivers still skip an exact suffix so a
+// stale producer degrades to unauthenticated playback instead of dropped
+// packets. ponytail: hard-cut to reject once no deployed producer can emit it.
+const LEGACY_TRAILER_EXT_TYPE = 0xf0a1
+const LEGACY_TRAILER_HEADER_SIZE = 4
+
+function isEmptyOrExactLegacyTrailer(payload: Uint8Array, start: number, end: number): boolean {
   if (start === end) return true
-  if (start < 0 || end > payload.length || start + _LEAF_MMTP_EXT_TRAILER_HEADER_SIZE > end) {
+  if (start < 0 || end > payload.length || start + LEGACY_TRAILER_HEADER_SIZE > end) {
     return false
   }
 
@@ -364,46 +366,73 @@ function isEmptyOrExactAltaTrailer(payload: Uint8Array, start: number, end: numb
     payload.byteOffset + start,
     end - start,
   )
-  if (view.getUint16(0, false) !== _LEAF_MMTP_EXT_TYPE_ALTA_AUTH) return false
+  if (view.getUint16(0, false) !== LEGACY_TRAILER_EXT_TYPE) return false
 
   const authLength = view.getUint16(2, false)
-  return start + _LEAF_MMTP_EXT_TRAILER_HEADER_SIZE + authLength === end
+  return start + LEGACY_TRAILER_HEADER_SIZE + authLength === end
 }
 
 interface DeclaredTrailerLayout {
   hasFecId: boolean
+  hasOverlayFecId: boolean
+}
+
+/** Options for extractMFUPayload and explainMFURejection. */
+export interface MFUExtractOptions {
+  /**
+   * When true, do NOT subtract the Source FEC Payload ID from the payload
+   * boundary, even if fecType >= 1. For FEC-recovered symbols whose FEC PID
+   * was already stripped before WASM decoding.
+   */
+  skipFecId?: boolean
+  /**
+   * The catalog declares a keyframe overlay (`scope: "keyframe"` repair track)
+   * for this packet's source. A RAP packet then carries two Source FEC Payload
+   * IDs, base first and overlay last (BLO-32719 Clarification 7). This is a
+   * catalog fact, never inferred: the header has no overlay bit, and a payload
+   * four bytes shorter is byte-identical to a missing overlay. Mirrors
+   * mmt-core `split_payload_and_source_fec_trailers(overlay_declared)`.
+   */
+  overlayDeclared?: boolean
 }
 
 function resolveDeclaredTrailers(
   payload: Uint8Array,
   declaredEnd: number,
   fecType: number,
-  options?: { skipFecId?: boolean },
+  options?: MFUExtractOptions,
+  rapFlag = false,
 ): DeclaredTrailerLayout | null {
   if (declaredEnd > payload.length) return null
 
   if (options?.skipFecId) {
-    return isEmptyOrExactAltaTrailer(payload, declaredEnd, payload.length)
-      ? { hasFecId: false }
+    return isEmptyOrExactLegacyTrailer(payload, declaredEnd, payload.length)
+      ? { hasFecId: false, hasOverlayFecId: false }
       : null
   }
 
+  const overlay = options?.overlayDeclared === true && rapFlag
   if (fecType === 1) {
-    const fecStart = payload.length - SOURCE_FEC_PAYLOAD_ID_SIZE
-    if (fecStart < declaredEnd || !isEmptyOrExactAltaTrailer(payload, declaredEnd, fecStart)) {
+    const fecStart = payload.length - sourceFecTrailerSize(overlay)
+    if (fecStart < declaredEnd || !isEmptyOrExactLegacyTrailer(payload, declaredEnd, fecStart)) {
       return null
     }
-    return { hasFecId: true }
+    return { hasFecId: true, hasOverlayFecId: overlay }
   }
-  if (fecType !== 0) return null
+  // An overlay ID rides behind a base ID the header says is absent.
+  if (fecType !== 0 || overlay) return null
 
-  if (isEmptyOrExactAltaTrailer(payload, declaredEnd, payload.length)) {
-    return { hasFecId: false }
+  if (isEmptyOrExactLegacyTrailer(payload, declaredEnd, payload.length)) {
+    return { hasFecId: false, hasOverlayFecId: false }
   }
 
   return null
 }
 
+function sourceFecTrailerSize(overlay: boolean): number {
+  return overlay ? 2 * SOURCE_FEC_PAYLOAD_ID_SIZE : SOURCE_FEC_PAYLOAD_ID_SIZE
+}
+
 /**
  * Extract NAL unit payload from MMTP packet
  */
@@ -429,6 +458,8 @@ export interface MFUExtraction {
   itemId: number | null
   /** Source FEC Payload ID if present (`FEC_type == 1`), or null */
   fecPayloadId: { ssId: number } | null
+  /** Keyframe-overlay Source FEC Payload ID: RAP packets with `overlayDeclared` only. */
+  overlayFecPayloadId: { ssId: number } | null
 }
 
 /**
@@ -441,15 +472,17 @@ export interface MFUExtraction {
  * - Source FEC Payload ID (4 bytes at end, only when `FEC_type == 1`)
  *
  * `payloadLength` is the ISO length-after-field value: six remaining MPU-header
- * bytes, then the MFU DU header when present, then media. ALTA and Source FEC
- * trailers are outside that declared span and must consume the exact suffix.
+ * bytes, then the MFU DU header when present, then media. The legacy
+ * authenticator suffix and the Source FEC trailer are outside that declared span and must consume the exact suffix.
  *
  * @param mmtpPacket Raw MMTP packet (from multicast or MoQ)
  * @param options.skipFecId When true, do NOT subtract the 4-byte Source FEC Payload ID
  *   from the payload boundary, even if fecType >= 1 in the MMTP header.  Use this for
  *   FEC-recovered symbols where the FEC PID was already stripped before WASM decoding
  *   but the fecType bits in byte 0 still reflect the original packet (FEC Type=1 per
- *   draft-ramadan-moq-mmt-00 §3.1).
+ *   draft-ramadan-moq-mmt-01 §3.1).
+ * @param options.overlayDeclared The catalog declares a keyframe overlay for this
+ *   source, so a RAP packet carries an 8-byte trailer (see MFUExtractOptions).
  * @returns Extracted MFU data + metadata, or null if packet is too small
  */
 interface MfuPlan {
@@ -470,7 +503,7 @@ interface MfuPlan {
  */
 function planMfuExtraction(
   mmtpPacket: Uint8Array,
-  options?: { skipFecId?: boolean },
+  options?: MFUExtractOptions,
   parsedHeader?: MMTPHeader,
 ): { plan: MfuPlan } | { rejection: MFURejection } {
   if (mmtpPacket.length < MMTP_HEADER_SIZE + MPU_HEADER_SIZE) {
@@ -535,6 +568,7 @@ function planMfuExtraction(
     layout.dataEnd,
     header.fecType,
     options,
+    header.rapFlag,
   )
   if (!trailerLayout) {
     // The most common cause is a producer whose Source FEC Payload ID width
@@ -542,13 +576,14 @@ function planMfuExtraction(
     // leaving operators to infer it from a generic trailer error.
     if (!options?.skipFecId && header.fecType === 1) {
       const observed = payload.length - layout.dataEnd
-      if (observed !== SOURCE_FEC_PAYLOAD_ID_SIZE) {
+      const expected = sourceFecTrailerSize(options?.overlayDeclared === true && header.rapFlag)
+      if (observed !== expected) {
         return {
           rejection: {
             gate: 'source-fec-payload-id-width-mismatch',
             detail:
               `producer wrote a ${observed}-byte Source FEC Payload ID, ` +
-              `ISO/IEC 23008-1 §C.5.2 requires ${SOURCE_FEC_PAYLOAD_ID_SIZE} ` +
+              `ISO/IEC 23008-1 §C.5.2 requires ${expected} ` +
               `(payload=${payload.length}, declaredEnd=${layout.dataEnd})`,
           },
         }
@@ -559,7 +594,7 @@ function planMfuExtraction(
         gate: 'declared-trailers-unresolved',
         detail:
           `trailer bytes [${layout.dataEnd}, ${payload.length}) are neither empty ` +
-          `nor an exact ALTA trailer (fecType=${header.fecType})`,
+          `nor an exact legacy authenticator trailer (fecType=${header.fecType})`,
       },
     }
   }
@@ -579,7 +614,7 @@ function planMfuExtraction(
  */
 export function explainMFURejection(
   mmtpPacket: Uint8Array,
-  options?: { skipFecId?: boolean },
+  options?: MFUExtractOptions,
 ): MFURejection | null {
   const result = planMfuExtraction(mmtpPacket, options)
   return 'rejection' in result ? result.rejection : null
@@ -587,7 +622,7 @@ export function explainMFURejection(
 
 export function extractMFUPayload(
   mmtpPacket: Uint8Array,
-  options?: { skipFecId?: boolean },
+  options?: MFUExtractOptions,
 ): MFUExtraction | null {
   return extractPlannedMfu(mmtpPacket, planMfuExtraction(mmtpPacket, options))
 }
@@ -602,7 +637,7 @@ export function extractMFUPayload(
 export function extractMFUPayloadWithHeader(
   mmtpPacket: Uint8Array,
   header: MMTPHeader,
-  options?: { skipFecId?: boolean },
+  options?: MFUExtractOptions,
 ): MFUExtraction | null {
   return extractPlannedMfu(mmtpPacket, planMfuExtraction(mmtpPacket, options, header))
 }
@@ -629,17 +664,17 @@ function extractPlannedMfu(
 
   const data = payload.subarray(mfuOffset, dataEnd)
 
-  const fecPayloadId = trailerLayout.hasFecId
-    ? {
-        ssId: new DataView(
-          mmtpPacket.buffer,
-          mmtpPacket.byteOffset + mmtpPacket.length - SOURCE_FEC_PAYLOAD_ID_SIZE,
-          SOURCE_FEC_PAYLOAD_ID_SIZE,
-        ).getUint32(0, false),
-      }
+  const trailerStart =
+    mmtpPacket.length - sourceFecTrailerSize(trailerLayout.hasOverlayFecId)
+  const ssIdAt = (offset: number) => ({
+    ssId: new DataView(mmtpPacket.buffer, mmtpPacket.byteOffset + offset, 4).getUint32(0, false),
+  })
+  const fecPayloadId = trailerLayout.hasFecId ? ssIdAt(trailerStart) : null
+  const overlayFecPayloadId = trailerLayout.hasOverlayFecId
+    ? ssIdAt(trailerStart + SOURCE_FEC_PAYLOAD_ID_SIZE)
     : null
 
-  return { header, mpu, fragmentType, data, mfuDuHeader, itemId, fecPayloadId }
+  return { header, mpu, fragmentType, data, mfuDuHeader, itemId, fecPayloadId, overlayFecPayloadId }
 }
 
 /**
@@ -732,22 +767,6 @@ export function sourceFecPayloadIdOf(
   }
 }
 
-/**
- * MMTP header-extension ext_type assigned to the detached ALTA authenticator
- * trailer (Path 2 / 08-07). Carried in an `[ext_type][ext_length][auth]`
- * block appended after the MPU's declared payload bytes, before the 4-byte
- * Source FEC Payload ID. MMTP X-bit stays 0 — non-ALTA MMTP receivers treat
- * the trailer as bytes past `payload_length` and skip it (per ISO 23008-1
- * §9.2.2 "may be discarded without impacting correct processing").
- */
-// Re-export the ALTA trailer helper from the zero-dep leaf package. The leaf
-// owns the implementation so container and FEC consumers share one parser
-// without creating a package cycle.
-export const MMTP_EXT_TYPE_ALTA_AUTH = _LEAF_MMTP_EXT_TYPE_ALTA_AUTH
-export const MMTP_EXT_TRAILER_HEADER_SIZE = _LEAF_MMTP_EXT_TRAILER_HEADER_SIZE
-export type AltaTrailer = _LeafAltaTrailer
-export const extractAltaTrailer = _leafExtractAltaTrailer
-
 /** Size of Repair FEC Payload ID per ISO/IEC 23008-1 Section C.5.3 */
 export const REPAIR_FEC_PID_SIZE = 13
 

package/src/multicast-catalog.ts

@@ -0,0 +1,350 @@
+/**
+ * The draft-ramadan-moq-multicast-01 endpoint and `auth` rules, written once
+ * for both sides of the catalog: `validateCmsfMmtpCatalog` in
+ * `@blockcast/mmt-container` throws the first issue, and the receivers in
+ * `@blockcast/mmt-transport` ignore every endpoint an issue names (all of
+ * them when the issue is catalog-level). It lives here because mmt-base is
+ * the only package both depend on.
+ *
+ * Draft: Blockcast/moqcast-draft@fd962fd73d21ed281b60219c11ea61cc9e4e91c4
+ * (PR #2 head; normative text equal to 3162ef93), sections 4.1 and 7.2.6.
+ */
+
+export type MulticastJoinMode = "ssm" | "asm";
+
+/** An endpoint's join mode and `S` (4.1): `sourceAddress` on SSM,
+ * `auth.senderAddress` on protected ASM, absent on unprotected ASM. */
+export interface MulticastEndpointSource {
+	mode: MulticastJoinMode;
+	source?: string;
+}
+
+export type MulticastCatalogIssueCode =
+	| "multicast_auth"
+	| "multicast_endpoint"
+	| "multicast_endpoint_auth"
+	| "multicast_track";
+
+export interface MulticastCatalogIssue {
+	code: MulticastCatalogIssueCode;
+	/** JSONPath of the offending field. */
+	path: string;
+	message: string;
+	/** Endpoint the issue makes a receiver ignore; absent for a catalog-level
+	 * issue, which leaves the receiver no endpoint at all (7.2.6). */
+	endpointIndex?: number;
+}
+
+/** Canonical unpadded base64url of exactly 32 octets. */
+export const ED25519_PUBLIC_KEY_BASE64URL = /^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/;
+
+const UINT32_MAX = 0xffff_ffff;
+const AUTH_MEMBERS = new Set(["scheme", "version", "sig", "keys", "minEpoch"]);
+const KEY_MEMBERS = new Set(["kid", "publicKey", "firstEpoch"]);
+const ENDPOINT_AUTH_MEMBERS = new Set([
+	"manifestPort",
+	"streamId",
+	"senderAddress",
+	"maxAuthDelayMs",
+	"manifestTimerMs",
+	"manifestTrack",
+]);
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(value: unknown): value is JsonObject {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function isIntegerIn(value: unknown, min: number, max: number): value is number {
+	return Number.isSafeInteger(value) && (value as number) >= min && (value as number) <= max;
+}
+
+/**
+ * Join mode and `S` of one endpoint, or `undefined` when its fields disagree
+ * and a receiver must ignore it (4.1). `sourceAddress` alone selects the mode;
+ * `protocol` may only restate it, so "amt" and "atsc3" (draft -00) are
+ * inconsistent here: a bearer is a `networkSource`, never a protocol.
+ */
+export function multicastEndpointSource(endpoint: unknown): MulticastEndpointSource | undefined {
+	if (!isObject(endpoint)) return undefined;
+	const sourceAddress = endpoint["sourceAddress"];
+	if (sourceAddress !== undefined && !isNonEmptyString(sourceAddress)) return undefined;
+	const mode: MulticastJoinMode = sourceAddress === undefined ? "asm" : "ssm";
+	const protocol = endpoint["protocol"];
+	if (protocol !== undefined && protocol !== mode) return undefined;
+	const auth = endpoint["auth"];
+	const senderAddress = isObject(auth) ? auth["senderAddress"] : undefined;
+	if (mode === "ssm") return senderAddress === undefined ? { mode, source: sourceAddress as string } : undefined;
+	if (auth === undefined) return { mode };
+	return isNonEmptyString(senderAddress) ? { mode, source: senderAddress } : undefined;
+}
+
+function authIssues(auth: unknown): MulticastCatalogIssue[] {
+	const base = "$.multicast.auth";
+	const issue = (path: string, message: string): MulticastCatalogIssue[] => [
+		{ code: "multicast_auth", path: `${base}${path}`, message },
+	];
+	if (!isObject(auth)) return issue("", "auth must be an object");
+	const unknown = Object.keys(auth).filter(key => !AUTH_MEMBERS.has(key));
+	if (unknown.length > 0) {
+		return issue("", `auth has unknown member(s) ${unknown.join(", ")}; draft -01 7.2.6 defines scheme, version, sig, keys and minEpoch`);
+	}
+	if (auth["scheme"] !== "bc-provenance") return issue(".scheme", 'scheme must be "bc-provenance"');
+	if (auth["version"] !== 2) return issue(".version", "version must be 2 (bc-provenance version 2, draft -01 7.2)");
+	if (auth["sig"] !== "ed25519") return issue(".sig", 'sig must be "ed25519"');
+	const keys = auth["keys"];
+	if (!Array.isArray(keys) || keys.length < 1 || keys.length > 4) {
+		return issue(".keys", "keys must be an array of one to four {kid, publicKey, firstEpoch} objects");
+	}
+	const kids = new Set<number>();
+	const firstEpochs = new Set<number>();
+	for (let index = 0; index < keys.length; index++) {
+		const key = keys[index];
+		const at = `.keys[${index}]`;
+		if (!isObject(key) || Object.keys(key).some(member => !KEY_MEMBERS.has(member))) {
+			return issue(at, "a key is exactly {kid, publicKey, firstEpoch}");
+		}
+		if (!isIntegerIn(key["kid"], 0, UINT32_MAX)) return issue(`${at}.kid`, "kid must be an unsigned 32-bit integer");
+		if (typeof key["publicKey"] !== "string" || !ED25519_PUBLIC_KEY_BASE64URL.test(key["publicKey"])) {
+			return issue(`${at}.publicKey`, "publicKey must be a 32-octet Ed25519 key in canonical unpadded base64url");
+		}
+		if (!isIntegerIn(key["firstEpoch"], 0, UINT32_MAX)) {
+			return issue(`${at}.firstEpoch`, "firstEpoch must be an unsigned 32-bit integer");
+		}
+		// A repeated kid or firstEpoch leaves no key set (7.2.6): fail the whole
+		// block, never fall back to unauthenticated reception.
+		if (kids.has(key["kid"])) return issue(`${at}.kid`, `kid ${key["kid"]} is repeated; the catalog holds no key set`);
+		if (firstEpochs.has(key["firstEpoch"])) {
+			return issue(`${at}.firstEpoch`, `firstEpoch ${key["firstEpoch"]} is repeated; the catalog holds no key set`);
+		}
+		kids.add(key["kid"]);
+		firstEpochs.add(key["firstEpoch"]);
+	}
+	if (!isIntegerIn(auth["minEpoch"], 0, UINT32_MAX)) {
+		return issue(".minEpoch", "minEpoch must be an unsigned 32-bit integer");
+	}
+	return [];
+}
+
+function endpointAuthIssue(
+	endpoint: JsonObject,
+	mode: MulticastJoinMode,
+	at: string,
+): { path: string; message: string } | undefined {
+	const auth = endpoint["auth"];
+	if (!isObject(auth)) return { path: `${at}.auth`, message: "auth must be an object" };
+	const unknown = Object.keys(auth).filter(key => !ENDPOINT_AUTH_MEMBERS.has(key));
+	if (unknown.length > 0) return { path: `${at}.auth`, message: `auth has unknown member(s) ${unknown.join(", ")}` };
+	if (!isIntegerIn(auth["manifestPort"], 1, 65535)) {
+		return { path: `${at}.auth.manifestPort`, message: "manifestPort must be an integer from 1 to 65535" };
+	}
+	if (!isIntegerIn(auth["streamId"], 0, UINT32_MAX)) {
+		return { path: `${at}.auth.streamId`, message: "streamId must be an unsigned 32-bit integer" };
+	}
+	if (mode === "ssm" && auth["senderAddress"] !== undefined) {
+		return { path: `${at}.auth.senderAddress`, message: "senderAddress must not appear on an SSM endpoint; S is sourceAddress" };
+	}
+	if (mode === "asm" && !isNonEmptyString(auth["senderAddress"])) {
+		return { path: `${at}.auth.senderAddress`, message: "a protected ASM endpoint requires senderAddress" };
+	}
+	if (auth["maxAuthDelayMs"] !== undefined && !isIntegerIn(auth["maxAuthDelayMs"], 50, 1000)) {
+		return { path: `${at}.auth.maxAuthDelayMs`, message: "maxAuthDelayMs must be an integer from 50 to 1000" };
+	}
+	if (auth["manifestTimerMs"] !== undefined && !isIntegerIn(auth["manifestTimerMs"], 1, Number.MAX_SAFE_INTEGER)) {
+		return { path: `${at}.auth.manifestTimerMs`, message: "manifestTimerMs must be an integer of at least 1" };
+	}
+	if (auth["manifestTrack"] !== undefined && !isNonEmptyString(auth["manifestTrack"])) {
+		return { path: `${at}.auth.manifestTrack`, message: "manifestTrack must be a non-empty string" };
+	}
+	if (!isIntegerIn(endpoint["bandwidth"], 1, Number.MAX_SAFE_INTEGER)) {
+		return { path: `${at}.bandwidth`, message: "a protected endpoint requires bandwidth, which bounds the receiver's hold queues" };
+	}
+	return undefined;
+}
+
+/**
+ * Where a catalog object carries the namespace of the catalog track it was
+ * read from. A symbol, so it is never wire data and survives object spread;
+ * `Symbol.for`, so two bundled copies of this module agree on it.
+ */
+export const CATALOG_NAMESPACE: unique symbol = Symbol.for("@blockcast/mmt-base/catalogNamespace");
+
+/**
+ * `catalog` tagged with the namespace of its catalog track. Every receiver
+ * rule that takes the catalog (`multicastCatalogIssues`,
+ * `admittedMulticastEndpoints` and the transport selectors built on them)
+ * then judges the foreign-namespace rule against it, independent of track
+ * order. Tag once, where the catalog track is read.
+ */
+export function withCatalogNamespace<T extends object>(catalog: T, namespace: string): T {
+	return { ...catalog, [CATALOG_NAMESPACE]: namespace };
+}
+
+/**
+ * Every draft -01 4.1 / 7.2.6 violation in `catalog.multicast`, in document
+ * order. Packet-id, group-address and track-existence rules are not here; the
+ * container validator and the receivers already check those.
+ *
+ * `catalogNamespace` is the namespace of the catalog track, from `options` or else the
+ * catalog's `withCatalogNamespace` tag. Without it the
+ * foreign-namespace rule can only compare listed tracks with each other: the
+ * first listed track's namespace becomes the reference, so which side of a
+ * disagreement is dropped depends on order. It still fails closed; pass
+ * `catalogNamespace` wherever the catalog track is known.
+ */
+export function multicastCatalogIssues(
+	catalog: unknown,
+	options: { catalogNamespace?: string } = {},
+): MulticastCatalogIssue[] {
+	if (!isObject(catalog)) return [];
+	const issues: MulticastCatalogIssue[] = [];
+	if ("multicast.auth" in catalog) {
+		// Fail closed: a draft -00 publisher meant the flow to be protected, and
+		// the key it names verifies nothing in bc-provenance version 2.
+		issues.push({
+			code: "multicast_auth",
+			path: '$["multicast.auth"]',
+			message: 'the root "multicast.auth" key is retired; declare auth as multicast.auth (draft -01 7.2.6)',
+		});
+	}
+	const multicast = catalog["multicast"];
+	if (!isObject(multicast)) return issues;
+	const protectedCatalog = multicast["auth"] !== undefined;
+	if (protectedCatalog) issues.push(...authIssues(multicast["auth"]));
+	const endpoints = multicast["endpoints"];
+	if (!Array.isArray(endpoints)) return issues;
+
+	const tracks = Array.isArray(catalog["tracks"]) ? catalog["tracks"] : [];
+	const namespaceOf = new Map<string, unknown>();
+	for (const track of tracks) {
+		if (isObject(track) && typeof track["name"] === "string") namespaceOf.set(track["name"], track["namespace"]);
+	}
+	const tagged = (catalog as { [CATALOG_NAMESPACE]?: unknown })[CATALOG_NAMESPACE];
+	let referenceNamespace = options.catalogNamespace ?? (typeof tagged === "string" ? tagged : undefined);
+
+	const sources: Array<MulticastEndpointSource | undefined> = [];
+	for (let index = 0; index < endpoints.length; index++) {
+		const endpoint = endpoints[index];
+		const at = `$.multicast.endpoints[${index}]`;
+		const fail = (code: MulticastCatalogIssueCode, path: string, message: string) => {
+			issues.push({ code, path, message, endpointIndex: index });
+		};
+		sources.push(undefined);
+		if (!isObject(endpoint)) {
+			fail("multicast_endpoint", at, "endpoint must be an object");
+			continue;
+		}
+		const protocol = endpoint["protocol"];
+		if (protocol !== undefined && protocol !== "ssm" && protocol !== "asm") {
+			fail("multicast_endpoint", `${at}.protocol`, `protocol must be "ssm" or "asm"; a bearer such as ${JSON.stringify(protocol)} is a networkSource entry (draft -01 4.2)`);
+			continue;
+		}
+		const hasAuth = endpoint["auth"] !== undefined;
+		if (protectedCatalog !== hasAuth) {
+			fail(
+				"multicast_endpoint_auth",
+				`${at}.auth`,
+				protectedCatalog
+					? "every endpoint requires auth when multicast carries auth; a receiver ignores this endpoint"
+					: "auth names no key without multicast.auth; a receiver ignores this endpoint",
+			);
+			continue;
+		}
+		const sourceAddress = endpoint["sourceAddress"];
+		if (sourceAddress !== undefined && !isNonEmptyString(sourceAddress)) {
+			fail("multicast_endpoint", `${at}.sourceAddress`, "sourceAddress must be a non-empty string");
+			continue;
+		}
+		const mode: MulticastJoinMode = sourceAddress === undefined ? "asm" : "ssm";
+		if (protocol !== undefined && protocol !== mode) {
+			fail("multicast_endpoint", `${at}.protocol`, `protocol ${JSON.stringify(protocol)} disagrees with sourceAddress, which selects ${mode}`);
+			continue;
+		}
+		// The (S, G, port) rule below compares ports with ===, so only an
+		// integer may reach it: "5001" and 5001 would otherwise both pass.
+		if (!isIntegerIn(endpoint["port"], 1, 65535)) {
+			fail("multicast_endpoint", `${at}.port`, "port must be an integer from 1 to 65535");
+			continue;
+		}
+		if (hasAuth) {
+			const authIssue = endpointAuthIssue(endpoint, mode, at);
+			if (authIssue) {
+				fail("multicast_endpoint_auth", authIssue.path, authIssue.message);
+				continue;
+			}
+		}
+		sources[index] = multicastEndpointSource(endpoint);
+
+		const refs = Array.isArray(endpoint["tracks"]) ? endpoint["tracks"] : [];
+		for (let refIndex = 0; refIndex < refs.length; refIndex++) {
+			const ref = refs[refIndex];
+			const name = isObject(ref) ? ref["name"] : ref;
+			if (typeof name !== "string") continue;
+			const namespace = namespaceOf.get(name);
+			if (typeof namespace !== "string") continue;
+			referenceNamespace ??= namespace;
+			if (namespace !== referenceNamespace) {
+				fail("multicast_track", `${at}.tracks[${refIndex}].name`, `track ${JSON.stringify(name)} declares namespace ${JSON.stringify(namespace)}, not the catalog track's ${JSON.stringify(referenceNamespace)}`);
+			}
+		}
+	}
+
+	// One endpoint object per (S, G, port), and a manifestPort that is no port
+	// and no other manifestPort of its (S, G) (4.1, 7.2.6). The rule binds the
+	// endpoint whose manifestPort clashes; two equal tuples or two equal
+	// manifestPorts break it on both sides, so both are named.
+	const tupleOf = (index: number) => {
+		const endpoint = endpoints[index] as JsonObject;
+		const auth = endpoint["auth"];
+		return {
+			sg: JSON.stringify([sources[index]!.source ?? null, endpoint["groupAddress"]]),
+			port: endpoint["port"],
+			manifestPort: isObject(auth) ? auth["manifestPort"] : undefined,
+		};
+	};
+	for (let index = 0; index < endpoints.length; index++) {
+		if (!sources[index]) continue;
+		const own = tupleOf(index);
+		const at = `$.multicast.endpoints[${index}]`;
+		if (own.manifestPort !== undefined && own.manifestPort === own.port) {
+			issues.push({ code: "multicast_endpoint_auth", path: `${at}.auth.manifestPort`, message: "manifestPort must differ from the endpoint's own port", endpointIndex: index });
+			continue;
+		}
+		for (let other = 0; other < endpoints.length; other++) {
+			if (other === index || !sources[other]) continue;
+			const peer = tupleOf(other);
+			if (peer.sg !== own.sg) continue;
+			if (peer.port === own.port) {
+				issues.push({ code: "multicast_endpoint", path: `${at}.port`, message: `(S, G, port) is shared with endpoint ${other}; one endpoint object per multicast tuple`, endpointIndex: index });
+				break;
+			}
+			if (own.manifestPort !== undefined && (own.manifestPort === peer.port || own.manifestPort === peer.manifestPort)) {
+				issues.push({ code: "multicast_endpoint_auth", path: `${at}.auth.manifestPort`, message: `manifestPort is a port or manifestPort of endpoint ${other} on the same (S, G)`, endpointIndex: index });
+				break;
+			}
+		}
+	}
+	return issues;
+}
+
+/**
+ * Indices of the endpoints a receiver may use: none when a catalog-level
+ * issue leaves it no key set (7.2.6), otherwise every endpoint no issue
+ * names. Other receiver checks (group address, packet ids) still apply.
+ */
+export function admittedMulticastEndpoints(
+	catalog: unknown,
+	options: { catalogNamespace?: string } = {},
+): ReadonlySet<number> {
+	const multicast = isObject(catalog) ? catalog["multicast"] : undefined;
+	const endpoints = isObject(multicast) && Array.isArray(multicast["endpoints"]) ? multicast["endpoints"] : [];
+	const issues = multicastCatalogIssues(catalog, options);
+	if (issues.some(issue => issue.endpointIndex === undefined)) return new Set();
+	const ignored = new Set(issues.map(issue => issue.endpointIndex));
+	return new Set(endpoints.map((_, index) => index).filter(index => !ignored.has(index)));
+}