@blockcast/mmt-alta-parse 0.1.0

package/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/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/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"}

package/dist/index.js

@@ -0,0 +1,115 @@
+/**
+ * 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).
+ */
+// --- Private MMTP/MPU/MFU constants (ISO/IEC 23008-1 §9.2.2–9.2.3) ---
+// Duplicated here as immutable spec values so this package stays a leaf with
+// zero `@blockcast/*` dependencies. Re-deriving from `mmt-container` would
+// reintroduce the package cycle this split exists to avoid.
+const MMTP_HEADER_SIZE = 12;
+const MPU_HEADER_SIZE = 8;
+const MPU_LENGTH_FIELD_SIZE = 2;
+const MPU_HEADER_REMAINDER_SIZE = MPU_HEADER_SIZE - MPU_LENGTH_FIELD_SIZE;
+const TIMED_MFU_DU_HEADER_SIZE = 14;
+const NONTIMED_MFU_DU_HEADER_SIZE = 4;
+const PACKET_TYPE_MPU = 0x00;
+// --- Public ALTA trailer constants ---
+/**
+ * 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 const MMTP_EXT_TYPE_ALTA_AUTH = 0xf0a1;
+/** Fixed size of the trailer's `[ext_type][ext_length]` prefix (2 + 2 BE). */
+export const MMTP_EXT_TRAILER_HEADER_SIZE = 4;
+/**
+ * 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 function extractAltaTrailer(mmtpPacket, options) {
+    if (mmtpPacket.length < MMTP_HEADER_SIZE + MPU_HEADER_SIZE)
+        return null;
+    // ISO/IEC 23008-1:2023 Figure 8 places V=0 packet_type in the low six bits.
+    const packetType = mmtpPacket[1] & 0x3f;
+    if (packetType !== PACKET_TYPE_MPU)
+        return null;
+    const fecType = (mmtpPacket[0] >> 3) & 0x03;
+    let headerLength = MMTP_HEADER_SIZE;
+    if (fecType < 2 && (mmtpPacket[0] & 0x20) !== 0)
+        headerLength += 4;
+    if (fecType < 2 && (mmtpPacket[0] & 0x02) !== 0) {
+        if (headerLength + 4 > mmtpPacket.length)
+            return null;
+        const extensionLength = new DataView(mmtpPacket.buffer, mmtpPacket.byteOffset + headerLength + 2, 2).getUint16(0, false);
+        headerLength += 4 + extensionLength;
+    }
+    if (headerLength + MPU_HEADER_SIZE > mmtpPacket.length)
+        return null;
+    const payload = mmtpPacket.subarray(headerLength);
+    // Inline a minimal MPU-header read — only the fields extractAltaTrailer needs.
+    // payloadLength: 16 BE at bytes 0-1.
+    // Byte 2 packs FT(4) | T(1) | FI(2) | A(1).
+    const payloadLength = (payload[0] << 8) | payload[1];
+    const flagsByte = payload[2];
+    const fragmentType = (flagsByte >> 4) & 0x0f;
+    const timed = ((flagsByte >> 3) & 0x01) === 1;
+    const fragmentationIndicator = (flagsByte >> 1) & 0x03;
+    // Only MFU packets (FT=2) carry the detached trailer.
+    if (fragmentType !== 2)
+        return null;
+    // FI=0/1 structurally carries a DU header; FI=2/3 does not. Require at
+    // least one media byte after that deterministic layout so the bytes at the
+    // declared boundary cannot impersonate ALTA for a header-only fragment.
+    const dataUnitHeaderSize = fragmentationIndicator <= 1
+        ? (timed ? TIMED_MFU_DU_HEADER_SIZE : NONTIMED_MFU_DU_HEADER_SIZE)
+        : 0;
+    if (payloadLength <= MPU_HEADER_REMAINDER_SIZE + dataUnitHeaderSize)
+        return null;
+    if (fecType > 1)
+        return null;
+    const hasFecId = !options?.skipFecId && fecType === 1;
+    const payloadEnd = hasFecId ? payload.length - 4 : payload.length;
+    const declaredEnd = MPU_LENGTH_FIELD_SIZE + payloadLength;
+    if (declaredEnd > payloadEnd)
+        return null;
+    if (declaredEnd + MMTP_EXT_TRAILER_HEADER_SIZE > payloadEnd)
+        return null;
+    const extType = (payload[declaredEnd] << 8) | payload[declaredEnd + 1];
+    if (extType !== MMTP_EXT_TYPE_ALTA_AUTH)
+        return null;
+    const extLen = (payload[declaredEnd + 2] << 8) | payload[declaredEnd + 3];
+    const authStart = declaredEnd + MMTP_EXT_TRAILER_HEADER_SIZE;
+    if (authStart + extLen !== payloadEnd)
+        return null;
+    return {
+        auth: payload.subarray(authStart, payloadEnd),
+        signedEnd: headerLength + declaredEnd,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@blockcast/mmt-alta-parse",
+  "version": "0.1.0",
+  "description": "Zero-dependency leaf: extract the detached ALTA authenticator trailer from an MMTP source packet",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "mmt",
+    "mmtp",
+    "alta",
+    "authenticator",
+    "trailer",
+    "iso23008-1"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Blockcast/libmmt.git",
+    "directory": "packages/mmt-alta-parse"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from 'vitest'
+import {
+  MMTP_EXT_TRAILER_HEADER_SIZE,
+  MMTP_EXT_TYPE_ALTA_AUTH,
+  extractAltaTrailer,
+} from './index.js'
+
+const MMTP_HEADER_SIZE = 12
+const MPU_HEADER_SIZE = 8
+const TIMED_MFU_DU_HEADER_SIZE = 14
+
+function buildPacket(options?: {
+  auth?: Uint8Array
+  appendFecId?: boolean
+  fecType?: number
+  fi?: number
+  media?: Uint8Array
+  payloadLength?: number
+  packetType?: number
+  timed?: boolean
+  trailing?: Uint8Array
+  wireDuSize?: number
+}): Uint8Array {
+  const auth = options?.auth
+  const appendFecId = options?.appendFecId ?? false
+  const fecType = options?.fecType ?? (appendFecId ? 1 : 0)
+  const fi = options?.fi ?? 0
+  const media = options?.media ?? new Uint8Array([0xaa, 0xbb, 0xcc])
+  const timed = options?.timed ?? true
+  const structuralDuSize = fi <= 1 ? (timed ? TIMED_MFU_DU_HEADER_SIZE : 4) : 0
+  const duSize = options?.wireDuSize ?? structuralDuSize
+  const payloadLength = options?.payloadLength ?? (MPU_HEADER_SIZE - 2 + duSize + media.length)
+  const bytes: number[] = []
+
+  bytes.push((fecType & 0x03) << 3)
+  bytes.push(options?.packetType ?? 0)
+  bytes.push(0, 1)
+  bytes.push(0, 0, 0, 1)
+  bytes.push(0, 0, 0, 2)
+
+  bytes.push((payloadLength >> 8) & 0xff, payloadLength & 0xff)
+  bytes.push((2 << 4) | (timed ? 1 << 3 : 0) | (fi << 1))
+  bytes.push(0)
+  bytes.push(0, 0, 0, 3)
+
+  for (let i = 0; i < duSize; i++) bytes.push(0)
+  for (const value of media) bytes.push(value)
+
+  if (auth) {
+    bytes.push((MMTP_EXT_TYPE_ALTA_AUTH >> 8) & 0xff, MMTP_EXT_TYPE_ALTA_AUTH & 0xff)
+    bytes.push((auth.length >> 8) & 0xff, auth.length & 0xff)
+    for (const value of auth) bytes.push(value)
+  }
+  if (options?.trailing) {
+    for (const value of options.trailing) bytes.push(value)
+  }
+  if (appendFecId) bytes.push(0, 0, 0, 9)
+
+  return new Uint8Array(bytes)
+}
+
+describe('extractAltaTrailer', () => {
+  it('locates ALTA after the canonical ISO-declared span and before Source FEC ID', () => {
+    const media = new Uint8Array([0x10, 0x20, 0x30, 0x40])
+    const auth = new Uint8Array([0xde, 0xad, 0xbe, 0xef])
+    const packet = buildPacket({ media, auth, appendFecId: true })
+
+    expect(extractAltaTrailer(packet)).toEqual({
+      auth,
+      signedEnd: MMTP_HEADER_SIZE + MPU_HEADER_SIZE + TIMED_MFU_DU_HEADER_SIZE + media.length,
+    })
+  })
+
+  it('locates ALTA in a recovered source symbol with the FEC ID already stripped', () => {
+    const auth = new Uint8Array([1, 2, 3, 4, 5])
+    const packet = buildPacket({ auth, fecType: 1 })
+    expect(extractAltaTrailer(packet, { skipFecId: true })?.auth).toEqual(auth)
+    expect(extractAltaTrailer(packet)).toBeNull()
+  })
+
+  it.each([
+    { fi: 0, duSize: TIMED_MFU_DU_HEADER_SIZE },
+    { fi: 1, duSize: TIMED_MFU_DU_HEADER_SIZE },
+    { fi: 2, duSize: 0 },
+    { fi: 3, duSize: 0 },
+  ])('uses the same declared coordinate for FI=$fi', ({ fi, duSize }) => {
+    const media = new Uint8Array([0x55, 0x66])
+    const auth = new Uint8Array([0x77])
+    const result = extractAltaTrailer(buildPacket({ fi, media, auth }))
+    expect(result?.signedEnd).toBe(MMTP_HEADER_SIZE + MPU_HEADER_SIZE + duSize + media.length)
+    expect(result?.auth).toEqual(auth)
+  })
+
+  it.each([0, 5])('rejects payload_length=%i because it cannot contain the MPU header remainder', (payloadLength) => {
+    expect(extractAltaTrailer(buildPacket({ auth: new Uint8Array([1]), payloadLength }))).toBeNull()
+  })
+
+  it.each([
+    { fi: 0, timed: true, payloadLength: 6, wireDuSize: 0 },
+    { fi: 0, timed: true, payloadLength: 20, wireDuSize: TIMED_MFU_DU_HEADER_SIZE },
+    { fi: 0, timed: false, payloadLength: 10, wireDuSize: 4 },
+    { fi: 2, timed: true, payloadLength: 6, wireDuSize: 0 },
+  ])('rejects an FT=2/FI=$fi declaration with no media after its structural DU header', (options) => {
+    expect(extractAltaTrailer(buildPacket({
+      ...options,
+      auth: new Uint8Array([1]),
+      media: new Uint8Array(),
+    }))).toBeNull()
+  })
+
+  it('rejects a declaration that overruns the packet', () => {
+    expect(extractAltaTrailer(buildPacket({
+      auth: new Uint8Array([1]),
+      payloadLength: 0xffff,
+    }))).toBeNull()
+  })
+
+  it('rejects the obsolete media-only declaration without scanning for ALTA', () => {
+    const media = new Uint8Array([0xf0, 0xa1, 0, 1, 0x99])
+    const packet = buildPacket({
+      media,
+      auth: new Uint8Array([0xaa]),
+      payloadLength: media.length,
+    })
+    expect(extractAltaTrailer(packet)).toBeNull()
+  })
+
+  it('returns null when the exact declared end has no ALTA trailer', () => {
+    expect(extractAltaTrailer(buildPacket({ appendFecId: true }))).toBeNull()
+  })
+
+  it('rejects bytes after the authenticator instead of accepting a partial suffix', () => {
+    const packet = buildPacket({
+      auth: new Uint8Array([0xaa, 0xbb]),
+      appendFecId: true,
+      trailing: new Uint8Array([0xcc]),
+    })
+    expect(extractAltaTrailer(packet)).toBeNull()
+  })
+
+  it('exports the four-byte ALTA trailer header size', () => {
+    expect(MMTP_EXT_TRAILER_HEADER_SIZE).toBe(4)
+  })
+})

package/src/index.ts

@@ -0,0 +1,136 @@
+/**
+ * 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).
+ */
+
+// --- Private MMTP/MPU/MFU constants (ISO/IEC 23008-1 §9.2.2–9.2.3) ---
+// Duplicated here as immutable spec values so this package stays a leaf with
+// zero `@blockcast/*` dependencies. Re-deriving from `mmt-container` would
+// reintroduce the package cycle this split exists to avoid.
+
+const MMTP_HEADER_SIZE = 12
+const MPU_HEADER_SIZE = 8
+const MPU_LENGTH_FIELD_SIZE = 2
+const MPU_HEADER_REMAINDER_SIZE = MPU_HEADER_SIZE - MPU_LENGTH_FIELD_SIZE
+const TIMED_MFU_DU_HEADER_SIZE = 14
+const NONTIMED_MFU_DU_HEADER_SIZE = 4
+const PACKET_TYPE_MPU = 0x00
+
+// --- Public ALTA trailer constants ---
+
+/**
+ * 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 const MMTP_EXT_TYPE_ALTA_AUTH = 0xf0a1
+
+/** Fixed size of the trailer's `[ext_type][ext_length]` prefix (2 + 2 BE). */
+export 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 function extractAltaTrailer(
+  mmtpPacket: Uint8Array,
+  options?: { skipFecId?: boolean },
+): AltaTrailer | null {
+  if (mmtpPacket.length < MMTP_HEADER_SIZE + MPU_HEADER_SIZE) return null
+  // ISO/IEC 23008-1:2023 Figure 8 places V=0 packet_type in the low six bits.
+  const packetType = mmtpPacket[1]! & 0x3f
+  if (packetType !== PACKET_TYPE_MPU) return null
+
+  const fecType = (mmtpPacket[0]! >> 3) & 0x03
+  let headerLength = MMTP_HEADER_SIZE
+  if (fecType < 2 && (mmtpPacket[0]! & 0x20) !== 0) headerLength += 4
+  if (fecType < 2 && (mmtpPacket[0]! & 0x02) !== 0) {
+    if (headerLength + 4 > mmtpPacket.length) return null
+    const extensionLength = new DataView(
+      mmtpPacket.buffer,
+      mmtpPacket.byteOffset + headerLength + 2,
+      2,
+    ).getUint16(0, false)
+    headerLength += 4 + extensionLength
+  }
+  if (headerLength + MPU_HEADER_SIZE > mmtpPacket.length) return null
+
+  const payload = mmtpPacket.subarray(headerLength)
+
+  // Inline a minimal MPU-header read — only the fields extractAltaTrailer needs.
+  // payloadLength: 16 BE at bytes 0-1.
+  // Byte 2 packs FT(4) | T(1) | FI(2) | A(1).
+  const payloadLength = (payload[0]! << 8) | payload[1]!
+  const flagsByte = payload[2]!
+  const fragmentType = (flagsByte >> 4) & 0x0f
+  const timed = ((flagsByte >> 3) & 0x01) === 1
+  const fragmentationIndicator = (flagsByte >> 1) & 0x03
+
+  // Only MFU packets (FT=2) carry the detached trailer.
+  if (fragmentType !== 2) return null
+
+  // FI=0/1 structurally carries a DU header; FI=2/3 does not. Require at
+  // least one media byte after that deterministic layout so the bytes at the
+  // declared boundary cannot impersonate ALTA for a header-only fragment.
+  const dataUnitHeaderSize = fragmentationIndicator <= 1
+    ? (timed ? TIMED_MFU_DU_HEADER_SIZE : NONTIMED_MFU_DU_HEADER_SIZE)
+    : 0
+  if (payloadLength <= MPU_HEADER_REMAINDER_SIZE + dataUnitHeaderSize) return null
+
+  if (fecType > 1) return null
+  const hasFecId = !options?.skipFecId && fecType === 1
+  const payloadEnd = hasFecId ? payload.length - 4 : payload.length
+  const declaredEnd = MPU_LENGTH_FIELD_SIZE + payloadLength
+  if (declaredEnd > payloadEnd) return null
+
+  if (declaredEnd + MMTP_EXT_TRAILER_HEADER_SIZE > payloadEnd) return null
+  const extType = (payload[declaredEnd]! << 8) | payload[declaredEnd + 1]!
+  if (extType !== MMTP_EXT_TYPE_ALTA_AUTH) return null
+  const extLen = (payload[declaredEnd + 2]! << 8) | payload[declaredEnd + 3]!
+
+  const authStart = declaredEnd + MMTP_EXT_TRAILER_HEADER_SIZE
+  if (authStart + extLen !== payloadEnd) return null
+
+  return {
+    auth: payload.subarray(authStart, payloadEnd),
+    signedEnd: headerLength + declaredEnd,
+  }
+}