@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/node_modules/@blockcast/fec-worker/src/shred-worker-client.ts

@@ -0,0 +1,222 @@
+/**
+ * @blockcast/fec-worker — Shred Worker Main-Thread Client
+ *
+ * Thin wrapper over the shred (Reed-Solomon) worker, mirroring
+ * {@link FecWorkerClient}'s shape. Spawns one Worker, speaks the
+ * {@link ShredWorkerCommand}/{@link ShredWorkerEvent} protocol, and keeps the
+ * datagram read loop + wire parse + WASM FEC off the main thread.
+ *
+ * Typical wiring for a WebTransport datagram source (fully off-thread):
+ *
+ *   const client = new ShredWorkerClient(new URL("./shred-fec-worker.js", import.meta.url));
+ *   client.onRecovered((data, meta) => renderRecoveredSet(data, meta));
+ *   client.configure({ maxSlots: 5000, symbolSize: 512, wasmUrl: "/vendor/fec/mmt_wasm.js" });
+ *   client.attachStream(wt.datagrams.readable); // transferred; main does no read() per packet
+ *
+ * For sources that demux on the main thread (moqtail OBJECT_DATAGRAM callback,
+ * IWA multicast bridge), push each raw frame with {@link feedShred} instead.
+ *
+ * {@link feedShred} is a fire-and-forget `postMessage` with no native
+ * backpressure, so a consumer that decodes slower than the ingest rate (a
+ * backgrounded/throttled tab, WASM RS falling behind a ~4k shred/s feed) would
+ * grow the worker's inbound message queue without limit — the queue lives in the
+ * renderer process and has been observed to reach multiple GB, GC-thrashing the
+ * page into a wedge. The client bounds it with an in-flight window keyed off the
+ * worker's own periodic stats heartbeat (no per-frame ack round-trip); see
+ * {@link ShredWorkerClientOptions.maxInflight}.
+ */
+
+import type {
+	ShredWorkerCommand,
+	ShredWorkerConfig,
+	ShredWorkerEvent,
+	ShredWorkerStats,
+	ShredWorkerErrorCode,
+	RecoveredMeta,
+} from "./shred-worker-types.js";
+
+/** Construction-time options for {@link ShredWorkerClient}. */
+export interface ShredWorkerClientOptions {
+	/**
+	 * Cap on frames posted via {@link ShredWorkerClient.feedShred} but not yet
+	 * drained by the worker, before further frames are dropped ("skip-to-live" at
+	 * the worker boundary). Bounds the worker's inbound message queue — the sole
+	 * unbounded structure on the main-thread-demux (`feedShred`) path.
+	 *
+	 * The drain signal is the worker's periodic `stats` heartbeat: the monotonic
+	 * total of frames it has taken off the queue (`shredsRx + malformed +
+	 * versionMismatch`). No per-frame acknowledgement crosses the boundary, so the
+	 * bound is heartbeat-granular — size it above one heartbeat's worth of ingest
+	 * (default 250ms heartbeat × ~4k frames/s ≈ ~1k frames).
+	 *
+	 * Default {@link DEFAULT_MAX_INFLIGHT} (8192 frames ≈ ~10 MB at ~1.3 KB/frame).
+	 * Set to `0` (or any value `<= 0`) to disable the bound entirely — only do so
+	 * for a source with its own backpressure (e.g. a bounded {@link
+	 * ShredWorkerClient.attachStream} producer). Note the bound assumes `feedShred`
+	 * is the sole ingest path; mixing it with `attachStream` (whose frames also
+	 * advance the heartbeat total) makes the window under-count and benignly
+	 * disables the drop.
+	 */
+	maxInflight?: number;
+}
+
+/** Default {@link ShredWorkerClientOptions.maxInflight} (~10 MB of queued frames). */
+export const DEFAULT_MAX_INFLIGHT = 8192;
+
+export class ShredWorkerClient {
+	readonly #worker: Worker;
+	#onRecovered: ((data: ArrayBuffer, meta: RecoveredMeta) => void) | null = null;
+	#onStats: ((stats: ShredWorkerStats) => void) | null = null;
+	#onError: ((message: string, code?: ShredWorkerErrorCode) => void) | null = null;
+	#disposed = false;
+
+	/** feedShred in-flight backpressure accounting (see ShredWorkerClientOptions.maxInflight). */
+	readonly #maxInflight: number;
+	#sent = 0; // frames posted via feedShred (monotonic)
+	#processed = 0; // worker-consumed total from the last stats heartbeat (monotonic)
+	#droppedBackpressure = 0; // frames dropped by the in-flight guard (monotonic)
+
+	/**
+	 * @param workerOrUrl - A URL (a Worker is created internally, `type: module`)
+	 *   or a pre-created Worker (for testing via constructor injection).
+	 * @param opts - Optional {@link ShredWorkerClientOptions}.
+	 */
+	constructor(workerOrUrl: Worker | URL, opts: ShredWorkerClientOptions = {}) {
+		this.#maxInflight = opts.maxInflight ?? DEFAULT_MAX_INFLIGHT;
+		this.#worker =
+			workerOrUrl instanceof URL
+				? new Worker(workerOrUrl, { type: "module" })
+				: workerOrUrl;
+		this.#worker.onmessage = (e: MessageEvent<ShredWorkerEvent>) =>
+			this.#handleEvent(e.data);
+		this.#worker.onerror = (e) =>
+			this.#onError?.(formatWorkerError(e), "worker-runtime");
+		this.#worker.onmessageerror = () =>
+			this.#onError?.("failed to deserialize worker message", "worker-message");
+	}
+
+	/** Configure the decoder (WASM load + ShredFecBuffer construction happen in the worker). */
+	configure(config: ShredWorkerConfig): void {
+		if (this.#disposed) throw new Error("[ShredWorkerClient] disposed");
+		this.#post({ type: "configure", config });
+	}
+
+	/**
+	 * Hand the worker a stream of raw shred frames to batch-drain. The stream is
+	 * transferred — the caller must not use it afterward. One active stream at a
+	 * time; attaching a new one cancels the previous.
+	 */
+	attachStream(readable: ReadableStream<Uint8Array>): void {
+		if (this.#disposed) return;
+		this.#post({ type: "attachStream", readable }, [readable]);
+	}
+
+	/**
+	 * Feed one already-demuxed raw shred frame. `frame` is transferred zero-copy;
+	 * the caller must not access it afterward.
+	 *
+	 * Dropped (frame NOT transferred, so the caller's buffer stays intact) when the
+	 * in-flight window is full — i.e. the worker is more than `maxInflight` frames
+	 * behind. This is the memory bound: a slow/wedged consumer costs bounded
+	 * skip-to-live drops (see {@link droppedBackpressure}), never an unbounded
+	 * renderer-heap blow-up.
+	 */
+	feedShred(frame: ArrayBuffer): void {
+		if (this.#disposed) return;
+		if (this.#maxInflight > 0 && this.#sent - this.#processed >= this.#maxInflight) {
+			this.#droppedBackpressure++;
+			return;
+		}
+		this.#sent++;
+		this.#post({ type: "feedShred", frame }, [frame]);
+	}
+
+	/** Explicitly drive loss recovery (in addition to the worker's internal timer). */
+	recoverAll(nowMs: number = Date.now()): void {
+		if (this.#disposed) return;
+		this.#post({ type: "recoverAll", nowMs });
+	}
+
+	/** Register callback for recovered/completed FEC sets. `data` is a transferred buffer. */
+	onRecovered(cb: (data: ArrayBuffer, meta: RecoveredMeta) => void): void {
+		this.#onRecovered = cb;
+	}
+
+	/** Register callback for the coalesced stats heartbeat. */
+	onStats(cb: (stats: ShredWorkerStats) => void): void {
+		this.#onStats = cb;
+	}
+
+	/** Register callback for worker errors. */
+	onError(cb: (message: string, code?: ShredWorkerErrorCode) => void): void {
+		this.#onError = cb;
+	}
+
+	/**
+	 * Frames dropped by the in-flight backpressure guard since construction
+	 * (monotonic). Surface this in the UI so sustained loss is visible rather than
+	 * silent — a rising counter means the consumer can't keep pace with ingest.
+	 */
+	get droppedBackpressure(): number {
+		return this.#droppedBackpressure;
+	}
+
+	/**
+	 * Frames posted via {@link feedShred} but not yet reported drained by the
+	 * worker's last stats heartbeat (best-effort, heartbeat-granular; never < 0).
+	 */
+	get inflight(): number {
+		return Math.max(0, this.#sent - this.#processed);
+	}
+
+	/** Dispose the worker. Idempotent. */
+	dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		try {
+			this.#worker.postMessage({ type: "dispose" } satisfies ShredWorkerCommand);
+		} catch {
+			/* worker may already be gone */
+		}
+		this.#worker.terminate();
+	}
+
+	#post(cmd: ShredWorkerCommand, transfer: Transferable[] = []): void {
+		this.#worker.postMessage(cmd, transfer);
+	}
+
+	#handleEvent(event: ShredWorkerEvent): void {
+		switch (event.type) {
+			case "recovered":
+				this.#onRecovered?.(event.data, event.meta);
+				break;
+			case "stats":
+				// The worker's monotonic consumed-frame total is the drain signal for
+				// the feedShred in-flight guard. shredsRx counts only valid frames;
+				// malformed + versionMismatch are consumed off the queue too, so the
+				// sum is the true "frames taken off the queue" and keeps the window
+				// from inflating (and false-dropping) on a malformed/skewed source.
+				this.#processed =
+					event.stats.shredsRx + event.stats.malformed + event.stats.versionMismatch;
+				this.#onStats?.(event.stats);
+				break;
+			case "error":
+				if (event.code) this.#onError?.(event.message, event.code);
+				else this.#onError?.(event.message);
+				break;
+		}
+	}
+}
+
+function formatWorkerError(event: ErrorEvent): string {
+	const parts = ["Worker error"];
+	if (event.message) parts.push(event.message);
+	if (event.filename) {
+		const loc = [event.filename];
+		if (event.lineno) loc.push(String(event.lineno));
+		if (event.colno) loc.push(String(event.colno));
+		parts.push(`at ${loc.join(":")}`);
+	}
+	if (event.error instanceof Error && event.error.stack) parts.push(event.error.stack);
+	return parts.join(": ");
+}

package/node_modules/@blockcast/fec-worker/src/shred-worker-types.ts

@@ -0,0 +1,194 @@
+/**
+ * @blockcast/fec-worker — Shred (Reed-Solomon) Worker Protocol
+ *
+ * A sibling codec to the RaptorQ/MMTP worker (`fec-worker.ts`). Solana-style
+ * shred streams carry a different FEC payload identity than MMTP source/repair
+ * symbols — a shred is `(slot, fecSetIndex, localIndex, numData, numCoding,
+ * isCoding, lastInSet)`, not a flat `ssId` — so they need their own command
+ * shape. The transport harness (Worker spawn, onmessage plumbing, zero-copy
+ * `toOwnedArrayBuffer` transfers) is shared; the decoder WASM is not.
+ *
+ * The worker owns the batch-drain: the consumer transfers a WebTransport
+ * `datagrams.readable` (or any `ReadableStream<Uint8Array>` of raw shred
+ * frames) into the Worker via {@link ShredWorkerCommand} `attachStream`, and
+ * the read loop + wire parse + `ShredFecBuffer.add_shred` all run off the main
+ * thread. Only recovered FEC sets (and coalesced stats) cross back. A
+ * `feedShred` command covers sources that have already demuxed the shred bytes
+ * on the main thread (e.g. a moqtail OBJECT_DATAGRAM callback, or the IWA
+ * multicast bridge).
+ *
+ * Types here are importable from both main thread and Worker contexts.
+ */
+
+// --- Wire format ------------------------------------------------------------
+
+/**
+ * Wire header layout the worker parses. Mirrors the deployed shred player's
+ * `onShredBytes` exactly (libmmt shred-forwarder `emit_frame`) so the off-thread
+ * path is bit-identical to the proven on-thread path.
+ *
+ * v3 (28-byte header):
+ *   [0]      version       u8   (== 3; non-3 frames are dropped, not misframed)
+ *   [1-8]    slot          u64 LE
+ *   [9-12]   fecSetIndex   u32 LE
+ *   [13-16]  localIndex    u32 LE   (data: 0..numData; coding: numData+position)
+ *   [17]     flags         u8       (bit0 = DATA_COMPLETE, bit1 = IS_CODING_SHRED)
+ *   [18]     numData       u8       (coding shreds only; 0 on data — WASM infers)
+ *   [19]     numCoding     u8       (coding shreds only; 0 on data)
+ *   [20-27]  sendTsUs      u64 LE   (µs since epoch, 0 when unstamped)
+ *   [28+]    erasureShard           (equal length across the FEC set)
+ *
+ * DATA_COMPLETE (last data shred in the set) is passed to `add_shred` as its
+ * `lastInSet` argument — the WASM uses it to infer numData for a set that
+ * received only data shreds (no coding).
+ */
+export const SHRED_WIRE_VERSION = 3;
+export const SHRED_HEADER_LEN = 28;
+export const SHRED_FLAG_DATA_COMPLETE = 0x01;
+export const SHRED_FLAG_IS_CODING = 0x02;
+
+// --- Config -----------------------------------------------------------------
+
+/** Per-decoder configuration for the shred FEC worker. */
+export interface ShredWorkerConfig {
+	/** Ring capacity in slots (matches `new ShredFecBuffer(maxSlots, symbolSize)`). */
+	maxSlots: number;
+	/** Symbol size in bytes (Solana shred payloads are fixed-size within a set). */
+	symbolSize: number;
+	/**
+	 * Module URL for the shred WASM (wasm-bindgen ESM exporting `default` init +
+	 * `ShredFecBuffer`). The worker `import()`s it and calls `await default()`.
+	 * Ignored when `self.__SHRED_WASM_BINDINGS__` is pre-injected (tests / custom
+	 * loaders), mirroring the RaptorQ worker's `__MMT_WASM_BINDINGS__` contract.
+	 */
+	wasmUrl?: string;
+	/**
+	 * How often (ms) the worker coalesces and posts a `stats` event. The read
+	 * loop never posts per-shred; only recovered frames and this heartbeat cross
+	 * the boundary. Default 250ms.
+	 */
+	statsIntervalMs?: number;
+	/**
+	 * How often (ms) the worker runs `try_recover_all(now)` to drain timed-out
+	 * FEC sets that `add_shred` didn't complete (loss scenarios). Default 50ms,
+	 * matching the player's on-thread recovery timer. Set to 0 to disable (the
+	 * consumer may instead drive it explicitly with `recoverAll`).
+	 */
+	recoverIntervalMs?: number;
+}
+
+// --- Stats ------------------------------------------------------------------
+
+/**
+ * First-shred-per-slot sample, collected by the worker and drained into each
+ * coalesced `stats` heartbeat. Lets the main thread run app-specific,
+ * slot-derived stats (e.g. the turbine-leg latency estimator, per-slot latency
+ * percentiles) WITHOUT re-parsing the wire header — the worker stays the single
+ * source of truth for parsing, and these cross the boundary aggregated (a
+ * handful per heartbeat), never per-packet.
+ */
+export interface SlotSample {
+	/** Slot number (first shred of this slot the worker saw). */
+	slot: bigint;
+	/** Publisher send timestamp (µs since epoch) of that first shred, 0 when unstamped. */
+	sendTsUs: bigint;
+	/** Frame byte length of that first shred. */
+	bytes: number;
+}
+
+/** Aggregate shred-decode counters, emitted on the coalesced `stats` heartbeat. */
+export interface ShredWorkerStats {
+	/** Total shred frames parsed (data + coding). */
+	shredsRx: number;
+	/** Data (source) shreds observed. */
+	sourceShreds: number;
+	/** Coding (repair) shreds observed. */
+	repairShreds: number;
+	/** FEC sets completed (direct completion + FEC recovery). */
+	fecSetsCompleted: number;
+	/** Bytes handed back as recovered/completed sets. */
+	bytesReassembled: number;
+	/** Sets recovered specifically via `try_recover_all` (loss recovery). */
+	fecSetsRecovered: number;
+	/** Current `ShredFecBuffer.pending_fec_sets()`, or -1 when unavailable. */
+	pendingFecSets: number;
+	/** Frames dropped for being shorter than the v3 header. */
+	malformed: number;
+	/** Frames dropped for carrying a non-v3 version byte (forwarder/worker skew). */
+	versionMismatch: number;
+	/** Highest slot number observed (as a string — bigint isn't JSON-safe for UI). */
+	currentSlot: string;
+	/** First-shred-per-slot samples parsed since the previous heartbeat (drained each emit). */
+	slotSamples: SlotSample[];
+}
+
+/** Stable identities for worker failures whose message text carries live values. */
+export type ShredWorkerErrorCode =
+	| "wasm-load-failed"
+	| "wasm-bindings-missing"
+	| "not-configured"
+	| "stream-read-failed"
+	| "unknown-command"
+	| "worker-runtime"
+	| "worker-message";
+
+// --- Recovered frame metadata ----------------------------------------------
+
+/** Metadata attached to each recovered set the worker emits. */
+export interface RecoveredMeta {
+	/**
+	 * Slot the recovered set belongs to. Attributed on both the direct-completion
+	 * path and the identity-carrying recovery drain
+	 * (`try_recover_all_with_identity`); only 0n on the legacy `ShredReassembler`
+	 * fallback, which has no identity variant. Do NOT branch on `slot === 0n` as
+	 * "unattributed" — that would drop the majority of recovered sets.
+	 */
+	slot: bigint;
+	/** FEC set index within the slot (0 only on the legacy identity-less fallback). */
+	fecSetIndex: number;
+	/**
+	 * Publisher send timestamp (µs since epoch), 0 when unstamped/unknown. On
+	 * direct completion this is the completing shred's stamp; on the recovery
+	 * drain it is the set's first-seen shred stamp (shreds of a set are sent µs
+	 * apart, so the two are equivalent latency baselines).
+	 */
+	sendTsUs: bigint;
+	/** True when produced by loss recovery (`try_recover_all`) rather than direct completion. */
+	recovered: boolean;
+}
+
+// --- Commands (main -> worker) ----------------------------------------------
+
+/** Discriminated union of all commands sent from the main thread to the shred worker. */
+export type ShredWorkerCommand =
+	| { type: "configure"; config: ShredWorkerConfig }
+	| {
+			/**
+			 * Hand the worker a stream of raw shred frames to batch-drain. Each
+			 * chunk is one wire frame (one WebTransport datagram). The stream is
+			 * transferred (add to the postMessage transfer list) — the main thread
+			 * must not touch it afterward.
+			 */
+			type: "attachStream";
+			readable: ReadableStream<Uint8Array>;
+	  }
+	| {
+			/**
+			 * Feed one already-demuxed raw shred frame. `frame` is transferred
+			 * zero-copy — the caller must not access it after posting. Use this for
+			 * sources whose demux stays on the main thread (moqtail OBJECT_DATAGRAM
+			 * callback, IWA multicast bridge).
+			 */
+			type: "feedShred";
+			frame: ArrayBuffer;
+	  }
+	| { type: "recoverAll"; nowMs: number }
+	| { type: "dispose" };
+
+// --- Events (worker -> main) ------------------------------------------------
+
+/** Discriminated union of all events emitted from the shred worker to the main thread. */
+export type ShredWorkerEvent =
+	| { type: "recovered"; data: ArrayBuffer; meta: RecoveredMeta }
+	| { type: "stats"; stats: ShredWorkerStats }
+	| { type: "error"; message: string; code?: ShredWorkerErrorCode };

package/node_modules/@blockcast/fec-worker/src/transfer.ts

@@ -0,0 +1,12 @@
+/**
+ * Return a fresh ArrayBuffer containing exactly the bytes in `view`.
+ *
+ * Worker outputs must not transfer buffers that might be owned by a WASM
+ * binding or by a larger shared packet. A fresh JS-owned buffer gives
+ * postMessage() exclusive ownership without detaching unrelated memory.
+ */
+export function toOwnedArrayBuffer(view: Uint8Array): ArrayBuffer {
+	const copy = new Uint8Array(view.byteLength);
+	copy.set(view);
+	return copy.buffer;
+}

package/node_modules/@blockcast/mmt-alta-parse/README.md

@@ -0,0 +1,181 @@
+# @blockcast/mmt-alta-parse
+
+Zero-dependency leaf package that extracts the detached **ALTA authenticator trailer** from an MMTP source packet. ALTA (Authenticated Lightweight TESLA-like Algorithm) is Blockcast's sender-authentication scheme for multicast streams: each MMTP source packet carries a detached signature trailer that downstream consumers (the FEC worker, the FFI core) verify against a catalog-published public key. This package is **the parser only** — it locates the trailer, returns the raw authenticator bytes, and tells the caller where the signed payload ends. Signature verification (Ed25519 / P-256) lives in the consumer that has crypto and the public key in hand.
+
+It is split into a leaf package with zero `@blockcast/*` dependencies so both `@blockcast/mmt-container` (wire-path parsing) and `@blockcast/fec-worker` (FEC-recovered-source parsing) can share one implementation without creating a package cycle.
+
+## Install
+
+```bash
+pnpm add @blockcast/mmt-alta-parse
+```
+
+## Quick start
+
+```ts
+import { extractAltaTrailer } from "@blockcast/mmt-alta-parse"
+
+// `wirePacket` is a full MMTP packet as it came off the network (Uint8Array).
+const trailer = extractAltaTrailer(wirePacket)
+
+if (trailer === null) {
+  // Packet has no ALTA trailer. This is normal for:
+  //  - non-MPU packets (repair, signaling)
+  //  - unsigned streams
+  //  - malformed / truncated packets
+  return
+}
+
+// `trailer.auth`        — the authenticator bytes (no ext_type/ext_length prefix)
+// `trailer.signedEnd`   — byte offset where the signed payload ends inside wirePacket.
+//                         The signer signed wirePacket.subarray(0, signedEnd).
+
+const signedPayload = wirePacket.subarray(0, trailer.signedEnd)
+// Hand off to a verifier with the catalog-published public key:
+//   ed25519.verify_detached(trailer.auth, signedPayload, publicKey)
+```
+
+For FEC-recovered source symbols (where the upstream FEC pipeline has already stripped the 4-byte Source FEC Payload ID), pass `{ skipFecId: true }`:
+
+```ts
+const trailer = extractAltaTrailer(recoveredSymbol, { skipFecId: true })
+```
+
+## Exports
+
+Per `package.json` (single entry point, ESM only):
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `extractAltaTrailer(packet, options?)` | function | Parse a wire MMTP packet and return its `AltaTrailer` or `null`. |
+| `AltaTrailer` | type | `{ auth: Uint8Array; signedEnd: number }` |
+| `MMTP_EXT_TYPE_ALTA_AUTH` | const `0xf0a1` | The MMTP header-extension `ext_type` assigned to the detached ALTA trailer. |
+| `MMTP_EXT_TRAILER_HEADER_SIZE` | const `4` | Fixed size of the trailer's `[ext_type][ext_length]` prefix (2 + 2 bytes BE). |
+
+The package has no runtime dependencies — `package.json` lists `"dependencies": {}`.
+
+## ALTA wire format
+
+The detached ALTA authenticator is appended **after** the declared MPU payload bytes and **before** the optional 4-byte Source FEC Payload ID. ISO/IEC 23008-1 defines `payload_length` as a length-after-field value: it includes the six MPU-header bytes following the field, the MFU data-unit header when present, and the media bytes. The MMTP header-extension `X` bit stays `0` — non-ALTA receivers treat the trailing bytes as data past `payload_length` and discard them per ISO/IEC 23008-1 §9.2.2 ("may be discarded without impacting correct processing").
+
+Wire layout for a signed source packet:
+
+```
+| MMTP hdr | length (2) | remaining MPU hdr (6) | MFU hdr? | MFU data | TRAILER | SS_ID? (4) |
+             \_______________________________________________________/
+                    payload_length bytes start after the field
+                                                                    ^
+                                                                    |
+                                                               signedEnd
+```
+
+In MPU-payload coordinates, `signedEnd` is exactly `2 + payload_length`; the returned packet-relative offset also includes the complete, possibly extended MMTP header.
+
+The trailer itself is:
+
+```
+| ext_type (2 BE) | ext_length (2 BE) | auth (ext_length bytes) |
+       0xf0a1
+```
+
+- `ext_type = 0xf0a1` identifies the trailer as ALTA. Anything else is rejected (`null` return).
+- `ext_length` is the authenticator length in bytes — 64 for Ed25519, 64 for P-256 raw `(r,s)`, or whatever the signer minted.
+- The signed range is everything from byte 0 through `signedEnd-1` of the wire packet — i.e. the MMTP header, MPU header, MFU header, and MFU payload, but **not** the trailer itself or the optional FEC payload ID.
+
+This is the **detached trailer** form (a.k.a. "Path 2 / 08-07") from `draft-ramadan-moq-mmt` §12. It coexists with FEC: the signer signs the source-packet bytes **before** they enter the FEC encoder, so a receiver that recovers a missing source symbol from repair gets the same signed bytes the sender minted. This is the "sign-before-encode" rule — see the parent monorepo Phase 8 spec.
+
+### When `extractAltaTrailer` returns `null`
+
+The function returns `null` (rather than throwing) for every non-trailer outcome — see `src/index.ts:69-115`:
+
+| Condition | Why |
+|-----------|-----|
+| Packet shorter than `MMTP_HEADER_SIZE + MPU_HEADER_SIZE` (20 B) | Truncated/malformed |
+| Packet type ≠ MPU (`0x00`) | Repair and signaling packets aren't signed per-packet |
+| Fragment type ≠ 2 (MFU) | Only timed or non-timed MFU media packets carry trailers |
+| `payload_length` cannot contain the MPU-header remainder, structurally required DU header, and media | The declaration ends inside headers or describes a header-only MFU |
+| `2 + payload_length` exceeds the pre-FEC packet boundary | Truncated/malformed declaration |
+| No bytes between MFU data and SS_ID for the 4-byte trailer header | Unsigned stream |
+| `ext_type` ≠ `0xf0a1` | Some other header-extension lives in that slot |
+| Declared `ext_length` does not end exactly at the SS_ID boundary | Malformed or ambiguous trailer suffix |
+
+Callers should treat `null` as "no signature on this packet" and route based on stream policy (require-signed vs allow-unsigned).
+
+## Verification flow (where this package fits)
+
+```
+                    catalog (CMSF)
+                          │
+                  alta.publicKey (SPKI bytes)
+                          │
+                          ▼
+   ┌─────────────────────────────────────────────────────┐
+   │ @blockcast/mmt-container :: mmtp-router             │
+   │   wirePacket → extractAltaTrailer(packet) ──────────┼──► this package
+   │                ⇒ { auth, signedEnd }                │
+   │                                                     │
+   │   feedSourceSymbol(..., { auth, payloadEnd: signedEnd })
+   └────────────────────────┬────────────────────────────┘
+                            │
+                            ▼
+   ┌─────────────────────────────────────────────────────┐
+   │ @blockcast/fec-worker (configured with publicKey)│
+   │   ed25519.verify_detached(auth,                     │
+   │                           symbol[0..payloadEnd],    │
+   │                           publicKey)                │
+   │   → emits altaVerified per packet → FecTrackStats   │
+   └─────────────────────────────────────────────────────┘
+```
+
+Concretely, in `packages/container/src/mmtp-router.ts:798`, the router calls `extractAltaTrailer(packet)` for every signed source packet on the wire, packages the result as `{ auth, payloadEnd: signedEnd }`, and hands it to the FEC manager. The FEC worker (configured with `alta.publicKey` from the CMSF catalog at `configure()` time) does the actual Ed25519 / P-256 verification and increments per-track `altaVerified` / `altaFailed` counters in `FecTrackStats`. Those counters surface in CMCD as `x-bc-alta-verified` (see `packages/container/src/cmcd-producer.ts:93`).
+
+## Why not TESLA
+
+TESLA (RFC 4082) is the IETF reference for sender-authenticated multicast: it uses delayed-disclosure of MAC keys to amortize signing cost, but at the protocol level it carries 10–20% authentication overhead per stream (depending on key chain depth and disclosure interval). ALTA is Blockcast's lighter variant — same threat model (verify each packet was minted by the legitimate sender, not a rogue injector on the multicast group), measurably lower overhead (~6.91% in production multicast tests). The parent monorepo's `CLAUDE.md` calls this out at `packages/alta/`. ALTA replaces the v2 stub verifier in v3.0 / Phase 8.
+
+## Relation to DRM
+
+ALTA and DRM solve **different** problems and are orthogonal:
+
+| | ALTA | DRM (Widevine / PlayReady / FairPlay / ClearKey) |
+|---|---|---|
+| Authenticates | the **sender** | the **receiver** |
+| Question | "Did this packet come from the legitimate broadcaster?" | "Is this device authorized to play this content?" |
+| Wire layer | Per-MMTP-packet detached trailer | Sample-level CENC encryption + license server |
+| Catalog field | `alta.publicKey` | `contentProtection[]` (planned in v4 / M7) |
+
+A stream can use both — ALTA on the multicast wire (so receivers reject injected packets), CENC + DRM at the sample level (so unauthorized devices can't play). They don't interact.
+
+## Specifications
+
+- **ISO/IEC 23008-1:2023** §9.2.2 (MMTP packet header), §9.2.3 (MPU/MFU header) — the host packet structure
+- **draft-ramadan-moq-mmt** §12 — detached authenticator trailer ("Path 2 / 08-07") wire format
+- **RFC 8032** — Ed25519 signature algorithm (a typical inhabitant of the trailer)
+- **NIST FIPS 186-4** — ECDSA over P-256 (alternative inhabitant)
+- **RFC 4082** — TESLA (the heavier scheme ALTA replaces; included for context, not a dependency)
+- ATSC A/331 §A — referenced by libmmt for catalog-style key/signaling distribution patterns
+
+This package is agnostic to the signature algorithm — it only carries opaque bytes.
+
+## Related packages
+
+| Package | Role |
+|---------|------|
+| `@blockcast/mmt-container` | Consumes this parser via `mmtp-router.ts`; provides the CMSF catalog that distributes `alta.publicKey` to the FEC worker. |
+| `@blockcast/fec-worker` | Verifier — receives `{ auth, payloadEnd }` and the catalog public key at configure time, performs the actual Ed25519 / P-256 verification, increments `altaVerified` / `altaFailed` in `FecTrackStats`. |
+| `@blockcast/mmt-fec` | Surfaces verification counters to the application via FEC stats snapshots. |
+
+## Testing
+
+```bash
+pnpm test            # vitest run
+pnpm test:watch      # vitest in watch mode
+pnpm typecheck       # tsc --noEmit
+pnpm build           # tsc → dist/
+```
+
+Direct tests in `src/index.test.ts` cover canonical complete/fragmented declarations, ALTA-only and ALTA+FEC suffixes, malformed lengths, and rejection of obsolete boundary conventions. Coverage is also exercised through the re-exported parser in `@blockcast/mmt-container`.
+
+## License
+
+Apache-2.0 — see `LICENSE`.

package/node_modules/@blockcast/mmt-alta-parse/dist/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Zero-dependency helper for extracting the detached ALTA authenticator trailer
+ * from an MMTP source packet.
+ *
+ * Lives in its own leaf package so both `@blockcast/mmt-container` (wire-path
+ * parsing) and `@blockcast/fec-worker` (FEC-recovered-source parsing) can share
+ * one implementation without creating a package cycle between them.
+ *
+ * Spec: ISO/IEC 23008-1:2023 + draft-ramadan-moq-mmt §12 (detached trailer, Path 2).
+ */
+/**
+ * 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").
+ */
+export declare const MMTP_EXT_TYPE_ALTA_AUTH = 61601;
+/** Fixed size of the trailer's `[ext_type][ext_length]` prefix (2 + 2 BE). */
+export declare const MMTP_EXT_TRAILER_HEADER_SIZE = 4;
+/** Result of extracting the detached ALTA authenticator from an MMTP packet. */
+export interface AltaTrailer {
+    /** Authenticator bytes (no ext_type/ext_length prefix, no trailing padding). */
+    auth: Uint8Array;
+    /**
+     * Wire-packet byte offset where the signed payload ends, i.e. where the
+     * trailer begins. Caller uses this to produce
+     * `payload = wirePacket.subarray(0, signedEnd)` for verify_detached.
+     */
+    signedEnd: number;
+}
+/**
+ * Extract the detached ALTA authenticator trailer from an MMTP source packet.
+ *
+ * Wire layout:
+ *   `[MMTP hdr][length(2)][remaining MPU hdr(6)][DU?][media][TRAILER][SS_ID?]`
+ *   `payload_length = 6 + DU bytes + media bytes`
+ *
+ * Returns `null` when:
+ * - the packet is too small / malformed,
+ * - `payload_length` cannot contain the remaining six MPU-header bytes,
+ * - the declared payload overruns the packet,
+ * - no bytes remain between `payload_length` and the SS_ID,
+ * - the trailer's `ext_type` isn't {@link MMTP_EXT_TYPE_ALTA_AUTH},
+ * - the declared `ext_length` would extend past the SS_ID boundary.
+ *
+ * Non-MPU packets (repair, signaling) always return `null`.
+ *
+ * @param options.skipFecId When true, do NOT reserve 4 trailing bytes for the
+ *   Source FEC Payload ID. Use on FEC-recovered symbols where the PID has
+ *   already been stripped upstream.
+ */
+export declare function extractAltaTrailer(mmtpPacket: Uint8Array, options?: {
+    skipFecId?: boolean;
+}): AltaTrailer | null;
+//# sourceMappingURL=index.d.ts.map

package/node_modules/@blockcast/mmt-alta-parse/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiBH;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAA;AAE7C,8EAA8E;AAC9E,eAAO,MAAM,4BAA4B,IAAI,CAAA;AAE7C,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,IAAI,EAAE,UAAU,CAAA;IAChB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,UAAU,EACtB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAChC,WAAW,GAAG,IAAI,CA4DpB"}