@blockcast/mmt-base 0.1.0

package/src/mmtp.test.ts

@@ -0,0 +1,769 @@
+/**
+ * Tests for parseMoqRepairFrame and extractMFUPayload.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+	extractAltaTrailer,
+	extractMFUPayload,
+	extractRepairFecPayloadId,
+	MMTP_HEADER_SIZE,
+	MPU_HEADER_SIZE,
+	MFU_DU_HEADER_SIZE_TIMED,
+	MMTP_EXT_TYPE_ALTA_AUTH,
+	MMTP_EXT_TRAILER_HEADER_SIZE,
+	PACKET_TYPE_SIGNALING,
+	parseMMTPHeader,
+	parseMoqRepairFrame,
+	parseMPUHeader,
+	hasSourceFecPayloadId,
+	parseAlFecMessage,
+	unwrapMMTP,
+} from "./mmtp.js";
+
+const REPAIR_FEC_PID = 13; // SS_Start(4) + RSB_length(3) + RS_ID(3) + SSB_length(3)
+const REPAIR_HDR = MMTP_HEADER_SIZE + REPAIR_FEC_PID; // 25
+
+function buildMoqRepairFrame(opts: {
+	packetId?: number;
+	ssStart?: number;
+	rsbLength?: number;
+	rsId?: number;
+	ssbLength?: number;
+	symbolData?: Uint8Array;
+}): Uint8Array {
+	const {
+		packetId = 1,
+		ssStart = 64,
+		rsbLength = 8,
+		rsId = 2,
+		ssbLength = 32,
+		symbolData = new Uint8Array(100),
+	} = opts;
+
+	const frame = new Uint8Array(REPAIR_HDR + symbolData.length);
+	const view = new DataView(frame.buffer);
+
+	// MMTP header
+	frame[0] = 0x10; // FEC_type=2 (mode-0 repair)
+	frame[1] = 0x03; // packetType=repair
+	view.setUint16(2, packetId, false);
+
+	// FEC Payload ID: SS_Start(4) + RSB_length(3) + RS_ID(3) + SSB_length(3) at offset 12
+	view.setUint32(12, ssStart, false); // 4 bytes
+	frame[16] = (rsbLength >> 16) & 0xff;
+	frame[17] = (rsbLength >> 8) & 0xff;
+	frame[18] = rsbLength & 0xff;
+	frame[19] = (rsId >> 16) & 0xff;
+	frame[20] = (rsId >> 8) & 0xff;
+	frame[21] = rsId & 0xff;
+	frame[22] = (ssbLength >> 16) & 0xff;
+	frame[23] = (ssbLength >> 8) & 0xff;
+	frame[24] = ssbLength & 0xff;
+
+	// Repair symbol data
+	frame.set(symbolData, REPAIR_HDR);
+
+	return frame;
+}
+
+describe("parseMoqRepairFrame", () => {
+	it("uses the same ISO V=0 low-bits identity as the raw-multicast parser", () => {
+		const frame = buildMoqRepairFrame({ ssStart: 64, ssbLength: 32 });
+		expect(frame[1]).toBe(0x03);
+		expect(extractRepairFecPayloadId(frame)).toEqual({
+			ssStart: 64,
+			rsbLength: 8,
+			rsId: 2,
+			ssbLength: 32,
+		});
+		expect(parseMoqRepairFrame(frame)).not.toBeNull();
+	});
+	it("rejects pre-migration FFmpeg high-bits repair in the raw-multicast parser", () => {
+		const frame = buildMoqRepairFrame({ ssStart: 64, ssbLength: 32 });
+		frame[1] = 0x0c;
+		expect(extractRepairFecPayloadId(frame)).toBeNull();
+	});
+	it("returns the authoritative Annex C coordinates without inventing SBN/ESI", () => {
+		const frame = buildMoqRepairFrame({ ssStart: 65, ssbLength: 32, rsId: 3 });
+		const result = parseMoqRepairFrame(frame);
+		expect(result).not.toBeNull();
+		expect(result!.ssStart).toBe(65);
+		expect(result!.ssbLength).toBe(32);
+		expect(result!.rsId).toBe(3);
+		expect(result).not.toHaveProperty("sbn");
+		expect(result).not.toHaveProperty("esi");
+	});
+
+	it("should extract SSB_length (K) from repair frame", () => {
+		const frame = buildMoqRepairFrame({ ssbLength: 32 });
+		const result = parseMoqRepairFrame(frame);
+		expect(result!.ssbLength).toBe(32);
+	});
+
+	it("should extract repair symbol data after header", () => {
+		const symbolData = new Uint8Array([0xde, 0xad, 0xbe, 0xef]);
+		const frame = buildMoqRepairFrame({ symbolData });
+		const result = parseMoqRepairFrame(frame);
+		expect(result!.symbolData.length).toBe(4);
+		expect(Array.from(result!.symbolData)).toEqual([0xde, 0xad, 0xbe, 0xef]);
+	});
+
+	it("starts the repair payload ID after the ISO C/X optional fields", () => {
+		const symbolData = new Uint8Array([0xde, 0xad, 0xbe, 0xef]);
+		const frame = addOptionalHeaderFields(buildMoqRepairFrame({
+			ssStart: 64,
+			ssbLength: 32,
+			symbolData,
+		}));
+
+		expect(extractRepairFecPayloadId(frame)).toEqual({
+			ssStart: 64,
+			rsbLength: 8,
+			rsId: 2,
+			ssbLength: 32,
+		});
+		expect(parseMoqRepairFrame(frame)?.symbolData).toEqual(symbolData);
+	});
+
+	it("should extract packetId for audio/video routing", () => {
+		const frame = buildMoqRepairFrame({ packetId: 2 });
+		const result = parseMoqRepairFrame(frame);
+		expect(result!.packetId).toBe(2);
+	});
+
+	it("should return null for frames smaller than repair header", () => {
+		const result = parseMoqRepairFrame(new Uint8Array(20));
+		expect(result).toBeNull();
+	});
+
+	it("should return null for non-repair packets", () => {
+		const frame = buildMoqRepairFrame({});
+		frame[1] = 0x00; // packetType=MPU
+		const result = parseMoqRepairFrame(frame);
+		expect(result).toBeNull();
+	});
+
+	it("accepts an authored audio SSB_length without a caller-supplied fallback", () => {
+		const frame = buildMoqRepairFrame({ ssStart: 8, ssbLength: 4, rsId: 1 });
+		const result = parseMoqRepairFrame(frame);
+		expect(result!.ssStart).toBe(8);
+		expect(result!.ssbLength).toBe(4);
+		expect(result!.rsId).toBe(1);
+	});
+
+	it("rejects non-mode-0 and structurally invalid repair packets", () => {
+		const wrongFecType = buildMoqRepairFrame({});
+		wrongFecType[0] = 0;
+		expect(parseMoqRepairFrame(wrongFecType)).toBeNull();
+
+		expect(parseMoqRepairFrame(buildMoqRepairFrame({ rsbLength: 0 }))).toBeNull();
+		expect(parseMoqRepairFrame(buildMoqRepairFrame({ ssbLength: 0 }))).toBeNull();
+		expect(parseMoqRepairFrame(buildMoqRepairFrame({ rsbLength: 2, rsId: 2 }))).toBeNull();
+		expect(parseMoqRepairFrame(buildMoqRepairFrame({ symbolData: new Uint8Array() }))).toBeNull();
+	});
+});
+
+describe("parseMPUHeader", () => {
+	it("parses byte 3 as an 8-bit fragment counter", () => {
+		const payload = new Uint8Array(8);
+		const view = new DataView(payload.buffer);
+		view.setUint16(0, 1234, false);
+		payload[2] = (2 << 4) | (1 << 3) | (1 << 1); // FT=2, T=1, FI=1
+		payload[3] = 0x83;
+		view.setUint32(4, 42, false);
+
+		const header = parseMPUHeader(payload);
+
+		expect(header.fragmentCounter).toBe(0x83);
+		expect(header.fragmentationIndicator).toBe(1);
+		expect(header.timedFlag).toBe(1);
+		expect(header.aggregationFlag).toBe(false);
+		expect(header.payloadLength).toBe(1234);
+		expect(header.mpuSequenceNumber).toBe(42);
+	});
+});
+
+describe("MMTP V/C/X header fields", () => {
+	it("parses packet_counter and extension before the payload", () => {
+		const packet = new Uint8Array(12 + 4 + 4 + 3 + 2);
+		const view = new DataView(packet.buffer);
+		packet[0] = 0x22; // C=1, X=1, fecType=0
+		view.setUint16(2, 7, false);
+		view.setUint32(4, 1000, false);
+		view.setUint32(8, 9, false);
+		view.setUint32(12, 0x01020304, false);
+		view.setUint16(16, 0x1234, false);
+		view.setUint16(18, 3, false);
+		packet.set([0xaa, 0xbb, 0xcc], 20);
+		packet.set([0xde, 0xad], 23);
+
+		const { header, payload } = unwrapMMTP(packet);
+		expect(header.packetCounterFlag).toBe(true);
+		expect(header.packetCounter).toBe(0x01020304);
+		expect(header.extensionFlag).toBe(true);
+		expect(header.extension?.type).toBe(0x1234);
+		expect(header.extension?.data).toEqual(new Uint8Array([0xaa, 0xbb, 0xcc]));
+		expect(header.headerLength).toBe(23);
+		expect(payload).toEqual(new Uint8Array([0xde, 0xad]));
+	});
+
+	it("parses optional fields on repair packets before their payload", () => {
+		const packet = addOptionalHeaderFields(buildMoqRepairFrame({ ssStart: 64 }));
+		packet[0] = (packet[0]! & ~0x18) | 0x10; // repair FEC_type=2, C=1, X=1
+		const header = parseMMTPHeader(packet);
+		expect(header.headerLength).toBe(22);
+		expect(header.packetCounter).toBe(0x01020304);
+		expect(header.extension?.data).toEqual(new Uint8Array([0xaa, 0xbb]));
+	});
+
+	it("rejects unsupported MMTP versions instead of decoding a V=1 layout as V=0", () => {
+		const packet = new Uint8Array(MMTP_HEADER_SIZE);
+		packet[0] = 0x40;
+		expect(() => parseMMTPHeader(packet)).toThrow("Unsupported MMTP version: 1");
+	});
+
+	it("nullable network helpers fail closed for malformed dynamic headers", () => {
+		const malformed = [
+			new Uint8Array(15),
+			new Uint8Array(15),
+			new Uint8Array(19),
+			new Uint8Array(24),
+		];
+		malformed[0]![0] = 0x20; // truncated C-only packet_counter
+		malformed[1]![0] = 0x02; // truncated X-only extension header
+		malformed[2]![0] = 0x22; // C+X, truncated extension header
+		malformed[3]![0] = 0x02; // oversized extension value
+		for (const packet of malformed) packet[1] = 0x02;
+		new DataView(malformed[3]!.buffer).setUint16(14, 0xffff, false);
+
+		for (const packet of malformed) {
+			expect(() => extractMFUPayload(packet)).not.toThrow();
+			expect(extractMFUPayload(packet)).toBeNull();
+			expect(() => hasSourceFecPayloadId(packet)).not.toThrow();
+			expect(hasSourceFecPayloadId(packet)).toBe(false);
+			expect(() => parseAlFecMessage(packet)).not.toThrow();
+			expect(parseAlFecMessage(packet)).toBeNull();
+		}
+	});
+});
+
+// ── extractMFUPayload tests ──────────────────────────────────────
+// Reproduces moqtail AVCC corruption: MMTP source packets (fecType=1)
+// with various payloadLength values going through extractMFUPayload.
+
+/** Build a complete MMTP+MPU+MFU packet for testing extractMFUPayload. */
+function buildMFUPacket(opts: {
+	fecType?: number;
+	fi?: number;
+	payloadLength?: number;
+	videoData?: Uint8Array;
+	appendFecId?: boolean;
+	rapFlag?: boolean;
+	packetId?: number;
+	fragmentCounter?: number;
+	movieFragmentSequenceNumber?: number;
+	sampleNumber?: number;
+	sampleOffset?: number;
+	includeMfuDuHeader?: boolean;
+	fragmentType?: number;
+	timedFlag?: number;
+	aggregationFlag?: boolean;
+	itemId?: number;
+}): Uint8Array {
+	const fi = opts.fi ?? 0;
+	const fragmentType = opts.fragmentType ?? 2;
+	const timedFlag = opts.timedFlag ?? 1;
+	const fecType = opts.fecType ?? (opts.appendFecId ? 1 : 0);
+	const rapFlag = opts.rapFlag ?? false;
+	const videoData = opts.videoData ?? new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF]);
+	const hasMfuDu = opts.includeMfuDuHeader ?? (fragmentType === 2 && fi <= 1);
+	const mfuDuSize = hasMfuDu ? (timedFlag === 1 ? MFU_DU_HEADER_SIZE_TIMED : 4) : 0;
+	const payloadLength = opts.payloadLength ?? (MPU_HEADER_SIZE - 2 + mfuDuSize + videoData.length);
+	const movieFragmentSequenceNumber = opts.movieFragmentSequenceNumber ?? 7;
+	const sampleNumber = opts.sampleNumber ?? 11;
+	const sampleOffset = opts.sampleOffset ?? 0;
+	const parts: number[] = [];
+	// MMTP header (12 bytes)
+	parts.push((fecType << 3) | (rapFlag ? 1 : 0));
+	parts.push(0x00); // packet_type=MPU
+	parts.push(0, opts.packetId ?? 1);
+	parts.push(0, 0, 0x03, 0xE8); // timestamp
+	parts.push(0, 0, 0, 1); // sequence number
+	// MPU header (8 bytes)
+	parts.push((payloadLength >> 8) & 0xff, payloadLength & 0xff);
+	parts.push((fragmentType << 4) | (timedFlag << 3) | (fi << 1) |
+		(opts.aggregationFlag ? 1 : 0));
+	parts.push((opts.fragmentCounter ?? 0) & 0xff); // fragment_counter
+	parts.push(0, 0, 0, 42); // mpuSequenceNumber
+	// MFU DU header is present only on complete/first MFU fragments.
+	if (hasMfuDu) {
+		if (timedFlag === 1) {
+			parts.push(
+				(movieFragmentSequenceNumber >> 24) & 0xff,
+				(movieFragmentSequenceNumber >> 16) & 0xff,
+				(movieFragmentSequenceNumber >> 8) & 0xff,
+				movieFragmentSequenceNumber & 0xff,
+				(sampleNumber >> 24) & 0xff,
+				(sampleNumber >> 16) & 0xff,
+				(sampleNumber >> 8) & 0xff,
+				sampleNumber & 0xff,
+				(sampleOffset >> 24) & 0xff,
+				(sampleOffset >> 16) & 0xff,
+				(sampleOffset >> 8) & 0xff,
+				sampleOffset & 0xff,
+				0x80,
+				0,
+			);
+		} else {
+			const itemId = opts.itemId ?? 0x01020304;
+			parts.push(
+				(itemId >> 24) & 0xff,
+				(itemId >> 16) & 0xff,
+				(itemId >> 8) & 0xff,
+				itemId & 0xff,
+			);
+		}
+	}
+	// Video data
+	for (const b of videoData) parts.push(b);
+	// Source FEC Payload ID: SS_ID (4 bytes)
+	if (opts.appendFecId) {
+		parts.push(0, 0, 0, 163); // SS_ID=163
+	}
+	return new Uint8Array(parts);
+}
+
+function addOptionalHeaderFields(packet: Uint8Array): Uint8Array {
+	const expanded = new Uint8Array(packet.length + 4 + 4 + 2);
+	expanded.set(packet.subarray(0, MMTP_HEADER_SIZE), 0);
+	expanded[0] = expanded[0]! | 0x22;
+	const view = new DataView(expanded.buffer);
+	view.setUint32(12, 0x01020304, false);
+	view.setUint16(16, 0x2001, false);
+	view.setUint16(18, 2, false);
+	expanded.set([0xaa, 0xbb], 20);
+	expanded.set(packet.subarray(MMTP_HEADER_SIZE), 22);
+	return expanded;
+}
+
+describe("extractMFUPayload — FEC PID boundary", () => {
+	it("rejects aggregated MPU payloads in the strict one-data-unit profile", () => {
+		expect(extractMFUPayload(buildMFUPacket({ aggregationFlag: true }))).toBeNull();
+	});
+
+	it("uses the ISO length-after-field declaration for complete, continuation, and init payloads", () => {
+		const media = new Uint8Array([0xaa, 0xbb, 0xcc]);
+		const complete = extractMFUPayload(buildMFUPacket({ videoData: media }))!;
+		expect(complete.mpu.payloadLength).toBe(6 + MFU_DU_HEADER_SIZE_TIMED + media.length);
+		expect(complete.data).toEqual(media);
+
+		for (const fi of [2, 3]) {
+			const continuation = extractMFUPayload(buildMFUPacket({ fi, videoData: media }))!;
+			expect(continuation.mpu.payloadLength).toBe(6 + media.length);
+			expect(continuation.mfuDuHeader).toBeNull();
+			expect(continuation.data).toEqual(media);
+		}
+
+		const init = extractMFUPayload(buildMFUPacket({
+			fragmentType: 0,
+			includeMfuDuHeader: false,
+			videoData: media,
+		}))!;
+		expect(init.mpu.payloadLength).toBe(6 + media.length);
+		expect(init.data).toEqual(media);
+	});
+
+	it("parses a non-timed complete MFU within the declared span", () => {
+		const media = new Uint8Array([0x10, 0x20]);
+		const result = extractMFUPayload(buildMFUPacket({
+			timedFlag: 0,
+			itemId: 0x10203040,
+			videoData: media,
+		}))!;
+		expect(result.itemId).toBe(0x10203040);
+		expect(result.data).toEqual(media);
+	});
+
+	it("starts the MPU payload after packet_counter and header extension", () => {
+		const video = new Uint8Array([0xde, 0xad, 0xbe, 0xef]);
+		const pkt = addOptionalHeaderFields(buildMFUPacket({ videoData: video, fecType: 0 }));
+		const r = extractMFUPayload(pkt)!;
+		expect(r.header.packetCounter).toBe(0x01020304);
+		expect(r.header.extension?.data).toEqual(new Uint8Array([0xaa, 0xbb]));
+		expect(r.data).toEqual(video);
+	});
+
+	it("rejects a truncated non-timed MFU before reading Item_ID", () => {
+		const pkt = new Uint8Array(MMTP_HEADER_SIZE + MPU_HEADER_SIZE);
+		const view = new DataView(pkt.buffer);
+		view.setUint16(MMTP_HEADER_SIZE, 1, false);
+		pkt[MMTP_HEADER_SIZE + 2] = 0x20; // FT=2, T=0, FI=0
+
+		expect(extractMFUPayload(pkt)).toBeNull();
+	});
+
+	it("rejects declarations shorter than the MPU-header remainder", () => {
+		for (const payloadLength of [0, 5]) {
+			expect(extractMFUPayload(buildMFUPacket({ payloadLength, fecType: 0 }))).toBeNull();
+		}
+	});
+
+	it("rejects a declaration that overruns the packet", () => {
+		expect(extractMFUPayload(buildMFUPacket({ payloadLength: 0xffff, fecType: 0 }))).toBeNull();
+	});
+
+	it("rejects the obsolete media-only declaration", () => {
+		const video = new Uint8Array(40).fill(0xab);
+		video.set([0, 0, 0, 5, 0x65], 0);
+		expect(extractMFUPayload(buildMFUPacket({
+			videoData: video,
+			payloadLength: video.length,
+			fecType: 0,
+		}))).toBeNull();
+	});
+
+	it("fecType=1 + FEC PID present: strips PID, extracts clean video data", () => {
+		const video = new Uint8Array(100).fill(0x42);
+		const pkt = buildMFUPacket({ videoData: video, appendFecId: true });
+		const r = extractMFUPayload(pkt)!;
+		expect(r).not.toBeNull();
+		expect(r.data.length).toBe(100);
+		expect(r.data).toEqual(video);
+		expect(r.fecPayloadId).toEqual({ ssId: 163 });
+	});
+
+	it("fecType=0 + no FEC PID: uses full payload", () => {
+		const video = new Uint8Array(50).fill(0xAA);
+		const pkt = buildMFUPacket({ videoData: video, fecType: 0 });
+		const r = extractMFUPayload(pkt)!;
+		expect(r.data.length).toBe(50);
+		expect(r.data).toEqual(video);
+		expect(r.fecPayloadId).toBeNull();
+	});
+
+	it("rejects an unmarked trailing Source FEC Payload ID", () => {
+		const video = new Uint8Array(50).fill(0xAB);
+		const pkt = buildMFUPacket({ videoData: video, fecType: 0, appendFecId: true });
+		expect(extractMFUPayload(pkt)).toBeNull();
+	});
+
+	it("rejects payloadLength=0 with a Source FEC Payload ID", () => {
+		const video = new Uint8Array(100).fill(0x42);
+		const pkt = buildMFUPacket({ videoData: video, payloadLength: 0, appendFecId: true });
+		expect(extractMFUPayload(pkt)).toBeNull();
+	});
+
+	it("rejects payloadLength=0 without FEC", () => {
+		const video = new Uint8Array(50).fill(0xBB);
+		const pkt = buildMFUPacket({ videoData: video, payloadLength: 0, fecType: 0 });
+		expect(extractMFUPayload(pkt)).toBeNull();
+	});
+
+	it("accepts the canonical ISO declaration with a Source FEC Payload ID", () => {
+		const video = new Uint8Array(80).fill(0xCC);
+		const pkt = buildMFUPacket({ videoData: video, payloadLength: 6 + MFU_DU_HEADER_SIZE_TIMED + 80, appendFecId: true });
+		const r = extractMFUPayload(pkt)!;
+		expect(r.data.length).toBe(80);
+		expect(r.data).toEqual(video);
+	});
+
+	it("skipFecId prevents truncation on FEC-recovered symbol", () => {
+		// FEC-recovered symbol: fecType=1 but FEC PID already stripped
+		const video = new Uint8Array(100).fill(0xDD);
+		const pkt = buildMFUPacket({ videoData: video, fecType: 1 });
+		// Without skipFecId, fecType=1 requires the missing PID and fails closed.
+		expect(extractMFUPayload(pkt)).toBeNull();
+		// With skipFecId — full data preserved
+		const good = extractMFUPayload(pkt, { skipFecId: true })!;
+		expect(good.data.length).toBe(100);
+		expect(good.data).toEqual(video);
+	});
+
+	it("AVCC keyframe integrity: NALU length prefix survives extraction", () => {
+		// Build realistic AVCC: [4B len][SPS][4B len][IDR]
+		const sps = new Uint8Array([0x67, 0x42, 0xC0, 0x1E, 0xD9, 0x00, 0xA0, 0x47, 0xFE, 0x88]);
+		const idr = new Uint8Array(200).fill(0x65);
+		const avcc = new Uint8Array(4 + sps.length + 4 + idr.length);
+		const dv = new DataView(avcc.buffer);
+		dv.setUint32(0, sps.length, false);
+		avcc.set(sps, 4);
+		dv.setUint32(4 + sps.length, idr.length, false);
+		avcc.set(idr, 4 + sps.length + 4);
+
+		const pkt = buildMFUPacket({ videoData: avcc, appendFecId: true, rapFlag: true });
+		const r = extractMFUPayload(pkt)!;
+		expect(r.data.length).toBe(avcc.length);
+		// First 4 bytes must be SPS length, not garbage from FEC PID
+		const naluLen = new DataView(r.data.buffer, r.data.byteOffset, 4).getUint32(0, false);
+		expect(naluLen).toBe(sps.length);
+		expect(r.data).toEqual(avcc);
+	});
+
+	it("middle/last fragments without DU header preserve raw continuation bytes", () => {
+		for (const fi of [2, 3]) {
+			const video = new Uint8Array([0x00, 0x00, 0x04, 0x31, 0xaa, 0xbb]);
+			const pkt = buildMFUPacket({
+				fi,
+				videoData: video,
+				payloadLength: 6 + video.length,
+				appendFecId: true,
+				includeMfuDuHeader: false,
+			});
+			const r = extractMFUPayload(pkt)!;
+			expect(r.data).toEqual(video);
+			expect(r.mfuDuHeader).toBeNull();
+			expect(r.fecPayloadId).toEqual({ ssId: 163 });
+		}
+	});
+
+	it("does not treat sane-looking raw continuation bytes as a timed DU header", () => {
+		const video = new Uint8Array([
+			0x00, 0x10, 0x3d, 0xe2, // movie_fragment_sequence_number seen in failed continuation data
+			0x00, 0x00, 0x87, 0x50, // sample_number is within the sanity bound
+			0x00, 0x00, 0x05, 0x00, // plausible offset
+			0x80, 0x00,
+			0xaa, 0xbb,
+		]);
+		const pkt = buildMFUPacket({
+			fi: 2,
+			videoData: video,
+			payloadLength: 6 + video.length,
+			appendFecId: true,
+			includeMfuDuHeader: false,
+		});
+		const r = extractMFUPayload(pkt)!;
+		expect(r.data).toEqual(video);
+		expect(r.mfuDuHeader).toBeNull();
+		expect(r.fecPayloadId).toEqual({ ssId: 163 });
+	});
+
+	it("does not scan FI=2 media for a timed DU header", () => {
+		const video = new Uint8Array([0xAA, 0xBB, 0xCC, 0xDD, 0xEE]);
+		const pkt = buildMFUPacket({
+			fi: 2,
+			videoData: video,
+			payloadLength: 6 + MFU_DU_HEADER_SIZE_TIMED + video.length,
+			appendFecId: true,
+			includeMfuDuHeader: true,
+			movieFragmentSequenceNumber: 9,
+			sampleNumber: 17,
+			sampleOffset: 1280,
+		});
+		const r = extractMFUPayload(pkt)!;
+		expect(r.data.subarray(MFU_DU_HEADER_SIZE_TIMED)).toEqual(video);
+		expect(r.mfuDuHeader).toBeNull();
+	});
+});
+
+/**
+ * Build an MMTP source packet that optionally carries the ALTA authenticator
+ * trailer between the declared MFU payload and the Source FEC Payload ID.
+ * Wire layout when both trailer and FEC PID are present:
+ *   [MMTP 12][length 2][remaining MPU header 6][MFU DU][MFU data]
+ *   [ext_type(2) ext_length(2) auth_bytes][SS_ID 4]
+ * payload_length is the declared `6 + MFU DU + MFU data` span.
+ */
+function buildPacketWithAltaTrailer(opts: {
+	videoData?: Uint8Array;
+	auth?: Uint8Array;
+	fi?: number;
+	appendFecId?: boolean;
+	extType?: number; // override for negative tests
+	extLenOverride?: number; // override ext_length field (negative tests)
+	packetType?: number; // override MMTP packet_type (negative tests)
+	payloadLengthOverride?: number; // override MPU payload_length
+}): Uint8Array {
+	const fi = opts.fi ?? 0;
+	const appendFecId = opts.appendFecId ?? true;
+	const videoData = opts.videoData ?? new Uint8Array(40).fill(0x11);
+	const hasMfuDu = fi <= 1;
+	const mfuDuSize = hasMfuDu ? MFU_DU_HEADER_SIZE_TIMED : 0;
+	const payloadLength = opts.payloadLengthOverride ?? (6 + mfuDuSize + videoData.length);
+
+	const parts: number[] = [];
+	// MMTP header: fecType=1 (so extractFecPayloadId path is reached when appendFecId)
+	const fecType = appendFecId ? 1 : 0;
+	parts.push((fecType << 3) | 0);
+	// ISO V=0 multicast wire encoding: reserved(2)|packet_type(6).
+	parts.push((opts.packetType ?? 0x00) & 0x3f);
+	parts.push(0, 1); // packet_id
+	parts.push(0, 0, 0x03, 0xE8); // timestamp
+	parts.push(0, 0, 0, 1); // sequence_number
+	// MPU header
+	parts.push((payloadLength >> 8) & 0xff, payloadLength & 0xff);
+	parts.push((2 << 4) | (1 << 3) | (fi << 1)); // FT=2 (MFU), timed=1, FI
+	parts.push(0); // fragment_counter
+	parts.push(0, 0, 0, 42); // MPU_sequence_number
+	// MFU DU header (complete/first timed MFU fragments)
+	if (hasMfuDu) {
+		for (let i = 0; i < MFU_DU_HEADER_SIZE_TIMED; i++) parts.push(0);
+	}
+	// MFU data
+	for (const b of videoData) parts.push(b);
+	// ALTA trailer (if auth provided)
+	if (opts.auth) {
+		const extType = opts.extType ?? MMTP_EXT_TYPE_ALTA_AUTH;
+		const extLen = opts.extLenOverride ?? opts.auth.length;
+		parts.push((extType >> 8) & 0xff, extType & 0xff);
+		parts.push((extLen >> 8) & 0xff, extLen & 0xff);
+		for (const b of opts.auth) parts.push(b);
+	}
+	// Source FEC Payload ID
+	if (appendFecId) {
+		parts.push(0, 0, 0x04, 0x00); // SS_ID = 1024
+	}
+	return new Uint8Array(parts);
+}
+
+describe("extractAltaTrailer", () => {
+	it("keeps ALTA-only and ALTA+FEC suffixes outside extracted media", () => {
+		const videoData = new Uint8Array([0x11, 0x22, 0x33]);
+		const auth = new Uint8Array([0xaa, 0xbb]);
+
+		const altaOnly = extractMFUPayload(buildPacketWithAltaTrailer({
+			videoData,
+			auth,
+			appendFecId: false,
+		}))!;
+		expect(altaOnly.data).toEqual(videoData);
+		expect(altaOnly.fecPayloadId).toBeNull();
+
+		const combined = extractMFUPayload(buildPacketWithAltaTrailer({
+			videoData,
+			auth,
+			appendFecId: true,
+		}))!;
+		expect(combined.data).toEqual(videoData);
+		expect(combined.fecPayloadId).toEqual({ ssId: 1024 });
+	});
+
+	it("rejects an unknown suffix at the declared boundary", () => {
+		const packet = buildPacketWithAltaTrailer({
+			auth: new Uint8Array([0xaa]),
+			appendFecId: false,
+			extType: 0x1234,
+		});
+		expect(extractMFUPayload(packet)).toBeNull();
+	});
+
+	it("returns null when no trailer present (MFU + SS_ID only)", () => {
+		const pkt = buildPacketWithAltaTrailer({ appendFecId: true });
+		expect(extractAltaTrailer(pkt)).toBeNull();
+	});
+
+	it("returns {auth, signedEnd} when valid ALTA trailer is present", () => {
+		const auth = new Uint8Array([0xAA, 0xBB, 0xCC, 0xDD, 0xEE]);
+		const pkt = buildPacketWithAltaTrailer({ auth });
+		const r = extractAltaTrailer(pkt);
+		expect(r).not.toBeNull();
+		expect(r!.auth).toEqual(auth);
+		// signedEnd marks where the signed payload ends (= where the trailer begins)
+		// = MMTP_HEADER_SIZE + MPU_HEADER_SIZE + MFU_DU + videoData.length
+		const expectedSignedEnd =
+			MMTP_HEADER_SIZE + MPU_HEADER_SIZE + MFU_DU_HEADER_SIZE_TIMED + 40;
+		expect(r!.signedEnd).toBe(expectedSignedEnd);
+	});
+
+	it("accounts for packet_counter and MMTP header extension in signedEnd", () => {
+		const auth = new Uint8Array([0xaa, 0xbb]);
+		const packet = buildPacketWithAltaTrailer({ auth });
+		const expanded = new Uint8Array(packet.length + 10);
+		expanded.set(packet.subarray(0, MMTP_HEADER_SIZE), 0);
+		expanded[0] = expanded[0]! | 0x22;
+		const view = new DataView(expanded.buffer);
+		view.setUint32(12, 0x01020304, false);
+		view.setUint16(16, 0x1234, false);
+		view.setUint16(18, 2, false);
+		expanded.set([0x55, 0x66], 20);
+		expanded.set(packet.subarray(MMTP_HEADER_SIZE), 22);
+
+		const result = extractAltaTrailer(expanded);
+
+		expect(result?.auth).toEqual(auth);
+		expect(result?.signedEnd).toBe(MMTP_HEADER_SIZE + 10 + MPU_HEADER_SIZE + MFU_DU_HEADER_SIZE_TIMED + 40);
+	});
+
+	it("returns null for the obsolete payloadLength=0 convention", () => {
+		const auth = new Uint8Array([0xAA, 0xBB]);
+		const pkt = buildPacketWithAltaTrailer({ auth, payloadLengthOverride: 0 });
+		expect(extractAltaTrailer(pkt)).toBeNull();
+	});
+
+	it("returns null for non-MPU packet types (signaling / repair)", () => {
+		const auth = new Uint8Array([0xAA]);
+		const signalingPkt = buildPacketWithAltaTrailer({
+			auth,
+			packetType: PACKET_TYPE_SIGNALING,
+		});
+		expect(extractAltaTrailer(signalingPkt)).toBeNull();
+	});
+
+	it("returns null when ext_type does not match MMTP_EXT_TYPE_ALTA_AUTH", () => {
+		const auth = new Uint8Array([0xAA, 0xBB]);
+		// Use a different ext_type (0x1234) — not the ALTA authenticator sentinel.
+		const pkt = buildPacketWithAltaTrailer({ auth, extType: 0x1234 });
+		expect(extractAltaTrailer(pkt)).toBeNull();
+	});
+
+	it("returns null when ext_length would extend past the SS_ID boundary", () => {
+		const auth = new Uint8Array([0xAA, 0xBB, 0xCC]);
+		// Advertised length is 99 bytes but only 3 auth bytes exist in the packet.
+		const pkt = buildPacketWithAltaTrailer({ auth, extLenOverride: 99 });
+		expect(extractAltaTrailer(pkt)).toBeNull();
+	});
+
+	it("returns null when the packet is smaller than MMTP+MPU header", () => {
+		// Arbitrary truncated packet — below the minimum header budget.
+		const tiny = new Uint8Array(4);
+		expect(extractAltaTrailer(tiny)).toBeNull();
+	});
+
+	it("skipFecId=true: trailer extends to end-of-packet (no 4-byte SS_ID reserved)", () => {
+		// When the caller is an FEC-recovered symbol, the SS_ID has already been
+		// stripped upstream and the last 4 bytes belong to the trailer itself.
+		const auth = new Uint8Array([0x11, 0x22, 0x33, 0x44, 0x55, 0x66]);
+		const pkt = buildPacketWithAltaTrailer({ auth, appendFecId: false });
+		const r = extractAltaTrailer(pkt, { skipFecId: true });
+		expect(r).not.toBeNull();
+		expect(r!.auth).toEqual(auth);
+	});
+
+	it("exposes MMTP_EXT_TRAILER_HEADER_SIZE as 4 (2B ext_type + 2B ext_length)", () => {
+		expect(MMTP_EXT_TRAILER_HEADER_SIZE).toBe(4);
+	});
+
+	// Pins the contract between the two call shapes that fec-worker and
+	// mmtp-router use. Historically fec-worker had its own
+	// `extractAltaTrailerFromRecovered` duplicate to avoid a package cycle
+	// with @blockcast/mmt-container. After the dedup
+	// (@blockcast/mmt-alta-parse leaf), fec-worker now calls
+	// `extractAltaTrailer(recovered, { skipFecId: true })`. If that flag ever
+	// diverges from the default FEC-path behavior in subtle ways, recovered
+	// ALTA verification silently drops to 0 — this test would fail first.
+	it("equivalence: wire packet (default) and recovered bytes (skipFecId:true) yield identical auth + signedEnd", () => {
+		const videoData = new Uint8Array(40).fill(0x11);
+		const auth = new Uint8Array([0xde, 0xad, 0xbe, 0xef, 0x12, 0x34, 0x56, 0x78]);
+
+		// Wire packet: fecType=1 at byte 0, has trailing 4-byte SS_ID.
+		const wirePkt = buildPacketWithAltaTrailer({ videoData, auth, appendFecId: true });
+
+		// Real FEC-recovered bytes are the wire packet MINUS the trailing SS_ID.
+		// fecType=1 is preserved in byte 0 — the flag `skipFecId: true` tells the
+		// parser that those 4 SS_ID bytes aren't really present, not that the
+		// MMTP header has been rewritten.
+		const recoveredBytes = wirePkt.subarray(0, wirePkt.length - 4);
+
+		const viaWire = extractAltaTrailer(wirePkt);
+		const viaRecovered = extractAltaTrailer(recoveredBytes, { skipFecId: true });
+
+		expect(viaWire).not.toBeNull();
+		expect(viaRecovered).not.toBeNull();
+		// Byte-identical auth payload — this is what the ALTA verifier hashes.
+		expect(viaRecovered!.auth).toEqual(viaWire!.auth);
+		expect(viaRecovered!.auth).toEqual(auth);
+		// signedEnd is the offset the verifier slices to — must also match so
+		// both call shapes produce the same signed payload range.
+		expect(viaRecovered!.signedEnd).toBe(viaWire!.signedEnd);
+	});
+});