@blockcast/mmt-container 0.1.0 → 0.3.0

package/src/loc.ts

@@ -1,129 +1,130 @@
 /**
  * @mmt/container - LOC FEC Extensions
  *
- * FEC Payload ID helpers for LOC (Low Overhead Container) format
- * Per draft-ramadan-moq-mmt Section 7.3
+ * FEC Source Info travels as a MoQT object extension header.
  *
- * The FEC Payload ID encodes Source Block Number (SBN) and
- * Encoding Symbol ID (ESI) as a 48-bit value: (SBN << 24) | ESI
+ * MoQT's key-value parity rule makes an **even** type varint-valued and an
+ * **odd** type length-prefixed-byte-valued. FEC Source Info is byte-valued, so
+ * its type MUST be odd. It used to be `0x10`, which is even: moqtail-ts had to
+ * special-case it ahead of the parity rule and upstream `js/net` reads every
+ * even type as a single varint, so a conformant parser or a re-encoding relay
+ * desynced on the first FEC-tagged object. The codepoint is now `0x11` and
+ * `0x10` is not accepted — there is no compatibility shim (BLO-40702).
+ *
+ * Value layout, exactly 4 bytes:
+ *
+ *     SS_ID (32 bits, big endian)
+ *
+ * SS_ID is the source symbol's sequence number — the same value and the same
+ * definition the Source FEC Payload ID trailer carries on the MMTP path, so one
+ * identifier covers both paths. It is a fixed 32-bit field, never a varint: MoQT
+ * permits non-minimal varint encodings, so a varint here would vary the
+ * extension's own length without varying its meaning, and the varint encoding is
+ * a property of the session, which MoQT redefined at draft-17 (#1016). Any value
+ * length other than 4 is an error.
+ *
+ * The value carries no block coordinate. A receiver places the symbol in a block
+ * by SS_ID and learns the block's extent from a repair object's
+ * (SS_Start, SSB_length) — it must not infer one from this extension. An earlier
+ * revision carried SBN + ESI + an optional Original Object Length; all three are
+ * gone (BLO-40702). SBN/ESI contradicted the draft's own block model (Z=1, so
+ * SBN is always 0, and blocks are delimited only by repair objects), and the
+ * object length travelled inside the object it described, so it was absent in
+ * the recovery case it existed for — the recoverable length is the `Length`
+ * field inside the FEC-protected source symbol.
  *
  * @packageDocumentation
  */
 
 /**
- * LOC Header Extension IDs
+ * LOC Header Extension IDs.
+ *
+ * NOTE: `AuthTag` is byte-valued on an even type, the same parity violation
+ * `FecSourceInfo` just left. It has no encoder, no wire path and no draft text
+ * here, so it is not renumbered as part of this change — see BLO-40702.
  */
 export enum LOCHeaderExtensionId {
   CaptureTimestamp = 2,
   VideoFrameMarking = 4,
   AudioLevel = 6,
   VideoConfig = 13,
-  /** FEC Payload ID extension (draft-ramadan-moq-mmt Section 7.3) */
-  FecPayloadId = 0x10,
+  /** FEC Source Info: SS_ID(32) */
+  FecSourceInfo = 0x11,
+  /** Content authentication tag */
+  AuthTag = 14,
 }
 
-/** Maximum value for SBN and ESI (24 bits each) */
-export const FEC_PAYLOAD_ID_MAX = 0xffffff
+/** Maximum value for SS_ID (32 bits) */
+export const FEC_SS_ID_MAX = 0xffffffff
+
+/** FEC Source Info value length — fixed. */
+export const FEC_SOURCE_INFO_LEN = 4
+
+/** Returns `value` if it is an integer in [0, max]; throws otherwise. */
+function checkField(field: string, value: number, max: number): number {
+  if (!Number.isInteger(value) || value < 0 || value > max) {
+    throw new Error(`FecSourceInfo ${field} out of range: ${value}`)
+  }
+  return value
+}
 
 /**
- * Pack Source Block Number (SBN) and Encoding Symbol ID (ESI) into a 48-bit value.
- *
- * Per draft-ramadan-moq-mmt Section 7.3, the FEC Payload ID is encoded as:
- * `(SBN << 24) | ESI` where both SBN and ESI are 24 bits.
- *
- * @param sbn - Source Block Number (24 bits, 0-16777215)
- * @param esi - Encoding Symbol ID (24 bits, 0-16777215)
- * @returns Packed 48-bit value as bigint
- *
- * @example
- * ```ts
- * import { fecPack } from '@mmt/container/loc'
- * const packed = fecPack(100, 5) // 419430405n
- * ```
+ * Encode FEC Source Info value bytes: SS_ID(4B BE).
+ * Returns 4-byte Uint8Array. Throws if SS_ID is out of range.
  */
-export function fecPack(sbn: number, esi: number): bigint {
-  return (BigInt(sbn & 0xffffff) << 24n) | BigInt(esi & 0xffffff)
+export function encodeFecSourceInfo(ssId: number): Uint8Array {
+  const buf = new Uint8Array(FEC_SOURCE_INFO_LEN)
+  new DataView(buf.buffer).setUint32(0, checkField('ssId', ssId, FEC_SS_ID_MAX), false)
+  return buf
 }
 
 /**
- * Unpack a 48-bit FEC Payload ID into Source Block Number and Encoding Symbol ID.
+ * Decode FEC Source Info value bytes: reads SS_ID(4B BE).
  *
- * Per draft-ramadan-moq-mmt Section 7.3, extracts:
- * - SBN from upper 24 bits
- * - ESI from lower 24 bits
- *
- * @param packed - Packed 48-bit FEC Payload ID value
- * @returns Tuple of [sbn, esi] both as numbers
- *
- * @example
- * ```ts
- * import { fecPack, fecUnpack } from '@mmt/container/loc'
- * const packed = fecPack(100, 5)
- * const [sbn, esi] = fecUnpack(packed) // [100, 5]
- * ```
+ * Bounds are checked against `buf`'s own length, not its backing buffer: on a
+ * subarray of a larger ArrayBuffer a short value would otherwise read past the
+ * logical end of `buf` and return a well-formed SS_ID built from foreign bytes.
  */
-export function fecUnpack(packed: bigint): [sbn: number, esi: number] {
-  const sbn = Number((packed >> 24n) & 0xffffffn)
-  const esi = Number(packed & 0xffffffn)
-  return [sbn, esi]
+export function decodeFecSourceInfo(buf: Uint8Array, offset = 0): number {
+  if (offset < 0 || offset + FEC_SOURCE_INFO_LEN > buf.length) {
+    throw new Error(`FEC Source Info must be ${FEC_SOURCE_INFO_LEN} bytes, got ${buf.length - offset}`)
+  }
+  return new DataView(buf.buffer, buf.byteOffset + offset, FEC_SOURCE_INFO_LEN).getUint32(0, false)
 }
 
 /**
- * FEC Payload ID for LOC extension headers
- *
- * Encodes Source Block Number (SBN) and Encoding Symbol ID (ESI)
- * for FEC recovery with LOC container format.
- *
- * @example
- * ```ts
- * import { FecPayloadId } from '@mmt/container/loc'
- *
- * // Create from SBN/ESI
- * const fecId = new FecPayloadId(100, 5)
- *
- * // Get packed value for extension header
- * const packed = fecId.packed // 419430405n
- *
- * // Create from packed value
- * const fecId2 = FecPayloadId.fromPacked(packed)
- * ```
+ * FEC Source Info for LOC/CMAF extension headers: SS_ID(32).
  */
-export class FecPayloadId {
-  static readonly TYPE = LOCHeaderExtensionId.FecPayloadId
+export class FecSourceInfo {
+  static readonly TYPE = LOCHeaderExtensionId.FecSourceInfo
 
   constructor(
-    /** Source Block Number (24 bits, 0-16777215) */
-    public readonly sbn: number,
-    /** Encoding Symbol ID (24 bits, 0-16777215) */
-    public readonly esi: number,
-  ) {
-    if (sbn < 0 || sbn > 0xffffff) {
-      throw new Error('SBN must be 0-16777215 (24 bits)')
-    }
-    if (esi < 0 || esi > 0xffffff) {
-      throw new Error('ESI must be 0-16777215 (24 bits)')
-    }
-  }
+    /** Source symbol sequence number (32 bits) */
+    public readonly ssId: number,
+  ) {}
 
-  /** Get packed 48-bit value */
-  get packed(): bigint {
-    return fecPack(this.sbn, this.esi)
+  /** Encode as extension value bytes */
+  encode(): Uint8Array {
+    return encodeFecSourceInfo(this.ssId)
   }
 
-  /** Create from packed 48-bit value */
-  static fromPacked(packed: bigint): FecPayloadId {
-    const [sbn, esi] = fecUnpack(packed)
-    return new FecPayloadId(sbn, esi)
+  /** Decode from extension value bytes. Fails closed on any other length. */
+  static decode(buf: Uint8Array): FecSourceInfo {
+    if (buf.length !== FEC_SOURCE_INFO_LEN) {
+      throw new Error(`FEC Source Info must be ${FEC_SOURCE_INFO_LEN} bytes, got ${buf.length}`)
+    }
+    return new FecSourceInfo(decodeFecSourceInfo(buf))
   }
+}
 
-  /** Check if value is within valid 24-bit range */
-  static isValidSbn(sbn: number): boolean {
-    return sbn >= 0 && sbn <= 0xffffff
-  }
+/**
+ * AuthTag for end-to-end content authentication.
+ */
+export class AuthTag {
+  static readonly TYPE = LOCHeaderExtensionId.AuthTag
 
-  /** Check if value is within valid 24-bit range */
-  static isValidEsi(esi: number): boolean {
-    return esi >= 0 && esi <= 0xffffff
+  constructor(public readonly tag: Uint8Array) {
+    if (tag.length === 0) throw new Error('AuthTag must not be empty')
   }
 }
 
@@ -134,85 +135,58 @@ export class FecPayloadId {
 if (import.meta.vitest) {
   const { describe, test, expect } = import.meta.vitest
 
-  describe('FEC Helpers', () => {
-    test('fecPack/fecUnpack roundtrip', () => {
-      const sbn = 12345
-      const esi = 67890
-      const packed = fecPack(sbn, esi)
-      const [unpackedSbn, unpackedEsi] = fecUnpack(packed)
-      expect(unpackedSbn).toBe(sbn)
-      expect(unpackedEsi).toBe(esi)
+  describe('FEC Source Info (SS_ID(32))', () => {
+    test('the codepoint is odd, so MoQT parity makes it length-prefixed bytes', () => {
+      expect(FecSourceInfo.TYPE % 2).toBe(1)
+      expect(FecSourceInfo.TYPE).toBe(0x11)
+      // 0x10 is retired with no dual-accept.
+      expect(FecSourceInfo.TYPE).not.toBe(0x10)
     })
 
-    test('fecPack/fecUnpack max values', () => {
-      const sbn = FEC_PAYLOAD_ID_MAX
-      const esi = FEC_PAYLOAD_ID_MAX
-      const packed = fecPack(sbn, esi)
-      const [unpackedSbn, unpackedEsi] = fecUnpack(packed)
-      expect(unpackedSbn).toBe(sbn)
-      expect(unpackedEsi).toBe(esi)
+    test('encode/decode roundtrip', () => {
+      const encoded = encodeFecSourceInfo(1234)
+      expect(encoded.length).toBe(4)
+      expect(decodeFecSourceInfo(encoded)).toBe(1234)
     })
 
-    test('fecPack/fecUnpack zero', () => {
-      const packed = fecPack(0, 0)
-      expect(packed).toBe(0n)
-      const [sbn, esi] = fecUnpack(0n)
-      expect(sbn).toBe(0)
-      expect(esi).toBe(0)
+    test('max 32-bit value', () => {
+      expect(decodeFecSourceInfo(encodeFecSourceInfo(0xffffffff))).toBe(0xffffffff)
     })
 
-    test('fecPack truncates overflow', () => {
-      const sbn = 0x1ffffff // 25 bits
-      const esi = 0x1ffffff // 25 bits
-      const packed = fecPack(sbn, esi)
-      const [unpackedSbn, unpackedEsi] = fecUnpack(packed)
-      expect(unpackedSbn).toBe(FEC_PAYLOAD_ID_MAX)
-      expect(unpackedEsi).toBe(FEC_PAYLOAD_ID_MAX)
-    })
-  })
-
-  describe('FecPayloadId', () => {
-    test('should create and roundtrip', () => {
-      const sbn = 12345
-      const esi = 67890
-      const fecId = new FecPayloadId(sbn, esi)
-      expect(fecId.sbn).toBe(sbn)
-      expect(fecId.esi).toBe(esi)
-
-      const fecId2 = FecPayloadId.fromPacked(fecId.packed)
-      expect(fecId2.sbn).toBe(sbn)
-      expect(fecId2.esi).toBe(esi)
+    test('FecSourceInfo is a fixed 4 bytes', () => {
+      const encoded = new FecSourceInfo(100).encode()
+      expect(encoded.length).toBe(4)
+      expect(FecSourceInfo.decode(encoded).ssId).toBe(100)
     })
 
-    test('should handle max 24-bit values', () => {
-      const sbn = 0xffffff
-      const esi = 0xffffff
-      const fecId = new FecPayloadId(sbn, esi)
-      const fecId2 = FecPayloadId.fromPacked(fecId.packed)
-      expect(fecId2.sbn).toBe(sbn)
-      expect(fecId2.esi).toBe(esi)
+    test('SS_ID is fixed width, not a varint: small values still take 4 bytes', () => {
+      // A QUIC varint would have spent 1 byte on 1 and 8 bytes on 2^32-1.
+      expect(new FecSourceInfo(1).encode().length).toBe(4)
+      expect(new FecSourceInfo(0xffffffff).encode().length).toBe(4)
+      expect(FecSourceInfo.decode(new FecSourceInfo(0xffffffff).encode()).ssId).toBe(0xffffffff)
+      expect(FecSourceInfo.decode(new FecSourceInfo(0).encode()).ssId).toBe(0)
     })
 
-    test('should reject invalid SBN', () => {
-      expect(() => new FecPayloadId(-1, 0)).toThrow()
-      expect(() => new FecPayloadId(0x1000000, 0)).toThrow()
+    test('decode fails closed on any other value length', () => {
+      // 8 and 12 were the previous SBN/ESI[/objectLength] widths: they must not decode.
+      for (const len of [0, 3, 5, 7, 8, 12, 16]) {
+        expect(() => FecSourceInfo.decode(new Uint8Array(len))).toThrow(/must be 4 bytes/)
+      }
     })
 
-    test('should reject invalid ESI', () => {
-      expect(() => new FecPayloadId(0, -1)).toThrow()
-      expect(() => new FecPayloadId(0, 0x1000000)).toThrow()
+    test('decodeFecSourceInfo does not read past the end of a subarray', () => {
+      // 3 readable bytes inside an 8-byte buffer: the 4th would be foreign.
+      const backing = new Uint8Array([0, 0, 0, 1, 0xde, 0xad, 0xbe, 0xef])
+      expect(() => decodeFecSourceInfo(backing.subarray(0, 3))).toThrow(/must be 4 bytes/)
+      expect(() => decodeFecSourceInfo(backing, 5)).toThrow(/must be 4 bytes/)
+      expect(decodeFecSourceInfo(backing.subarray(0, 4))).toBe(1)
     })
 
-    test('isValidSbn/isValidEsi', () => {
-      expect(FecPayloadId.isValidSbn(0)).toBe(true)
-      expect(FecPayloadId.isValidSbn(0xffffff)).toBe(true)
-      expect(FecPayloadId.isValidSbn(-1)).toBe(false)
-      expect(FecPayloadId.isValidSbn(0x1000000)).toBe(false)
-
-      expect(FecPayloadId.isValidEsi(0)).toBe(true)
-      expect(FecPayloadId.isValidEsi(0xffffff)).toBe(true)
-      expect(FecPayloadId.isValidEsi(-1)).toBe(false)
-      expect(FecPayloadId.isValidEsi(0x1000000)).toBe(false)
+    test('encode rejects an out-of-range ss_id', () => {
+      // Not wrapped mod 2^32: -1 must not encode as 0xffffffff, nor 2^32 as 0.
+      expect(() => new FecSourceInfo(0x1_0000_0000).encode()).toThrow(/ssId out of range/)
+      expect(() => new FecSourceInfo(-1).encode()).toThrow(/ssId out of range/)
+      expect(() => encodeFecSourceInfo(1.5)).toThrow(/ssId out of range/)
     })
   })
 }

package/src/manifest-auth-plan.ts

@@ -0,0 +1,107 @@
+import {
+  ManifestVerifier,
+  manifestBindingId,
+  type ManifestAuthConfig,
+  type ManifestTrackContext,
+  type SignatureVerifier,
+} from '@blockcast/mmt-manifest-verify'
+import {
+  resolveMulticastAuthCatalog,
+  type MulticastAuthMode,
+  type ResolvedMulticastAuthConfig,
+} from './multicast-auth-catalog.js'
+
+export interface ManifestAuthBinding {
+  bindingId: string
+  mediaTrack: string
+  manifestTrack: string
+  sourceSymbolFormat: string
+}
+
+export interface ManifestAuthPlan {
+  verifier: ManifestVerifier
+  mode: MulticastAuthMode
+  bindings: readonly ManifestAuthBinding[]
+  manifestTracks: readonly string[]
+  bindingIdFor(mediaTrack: string, sourceSymbolFormat: string): string | undefined
+  ingestManifestPayload(manifestTrack: string, payload: Uint8Array): void
+  dispose(): void
+}
+
+type ContextFields = Omit<
+  ManifestTrackContext,
+  'bindingId' | 'trackName' | 'sourceSymbolFormat' | 'authScope' | 'publicKey' | 'acceptedPublicKeys'
+>
+
+/** Build the one canonical verifier plan shared by browser players. Transport
+ * implementations subscribe the exact returned manifestTracks and feed each
+ * bare source-auth frame to ingestManifestPayload without name inference. */
+export function createManifestAuthPlan(
+  catalog: unknown,
+  options: {
+    playerMode?: MulticastAuthMode
+    onMissingManifest?: ManifestAuthConfig['onMissingManifest']
+    verifySignature: SignatureVerifier
+    contextFor(
+      binding: ResolvedMulticastAuthConfig['tracks'][number],
+      resolved: ResolvedMulticastAuthConfig,
+    ): ContextFields
+    onFailure?: ConstructorParameters<typeof ManifestVerifier>[0]['onFailure']
+  },
+): ManifestAuthPlan | undefined {
+  const resolved = resolveMulticastAuthCatalog(catalog, options.playerMode)
+  if (!resolved || resolved.mode === 'off') return undefined
+
+  const verifier = new ManifestVerifier({
+    manifestAuth: {
+      mode: resolved.mode,
+      onMissingManifest: options.onMissingManifest ??
+        (resolved.mode === 'enforce' ? 'stall' : 'fallback-shadow'),
+    },
+    verifySignature: options.verifySignature,
+    ...(options.onFailure === undefined ? {} : { onFailure: options.onFailure }),
+  })
+  const byManifestTrack = new Map<string, ManifestAuthBinding>()
+  const bindings = resolved.tracks.map((binding): ManifestAuthBinding => {
+    const bindingId = manifestBindingId(binding.mediaTrack, binding.sourceSymbolFormat)
+    const planned = {
+      bindingId,
+      mediaTrack: binding.mediaTrack,
+      manifestTrack: binding.manifestTrack,
+      sourceSymbolFormat: binding.sourceSymbolFormat,
+    }
+    verifier.registerTrack({
+      ...options.contextFor(binding, resolved),
+      bindingId,
+      trackName: binding.mediaTrack,
+      sourceSymbolFormat: binding.sourceSymbolFormat,
+      authScope: binding.authScope,
+      publicKey: resolved.acceptedPublicKeys[0]!,
+      acceptedPublicKeys: resolved.acceptedPublicKeys,
+    })
+    byManifestTrack.set(binding.manifestTrack, planned)
+    return planned
+  })
+  let disposed = false
+
+  return {
+    verifier,
+    mode: resolved.mode,
+    bindings,
+    manifestTracks: [...byManifestTrack.keys()],
+    bindingIdFor(mediaTrack, sourceSymbolFormat) {
+      const bindingId = manifestBindingId(mediaTrack, sourceSymbolFormat)
+      return bindings.some((binding) => binding.bindingId === bindingId) ? bindingId : undefined
+    },
+    ingestManifestPayload(manifestTrack, payload) {
+      const binding = byManifestTrack.get(manifestTrack)
+      if (!binding) throw new Error(`unknown manifest subscription track ${manifestTrack}`)
+      verifier.ingestManifestFrame(binding.bindingId, payload)
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      verifier.dispose()
+    },
+  }
+}