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

package/src/loc.ts

@@ -0,0 +1,181 @@
+/**
+ * @mmt/container - LOC FEC Extensions
+ *
+ * FEC Source Info per draft-ramadan-moq-fec §7.1:
+ *   SBN (32 bits) + ESI (32 bits) = 8 bytes minimum.
+ *   Optional Original Object Length (QUIC varint) when Length > 8.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * LOC Header Extension IDs
+ */
+export enum LOCHeaderExtensionId {
+  CaptureTimestamp = 2,
+  VideoFrameMarking = 4,
+  AudioLevel = 6,
+  /** FEC Source Info: SBN(32) + ESI(32) [+ Original Object Length (varint)] */
+  FecSourceInfo = 0x10,
+  VideoConfig = 13,
+  /** Content authentication tag */
+  AuthTag = 14,
+}
+
+/** Maximum value for SBN and ESI (32 bits each) */
+export const FEC_SBN_MAX = 0xffffffff
+export const FEC_ESI_MAX = 0xffffffff
+
+/**
+ * Encode FEC Source Info value bytes: SBN(4B BE) + ESI(4B BE).
+ * Returns 8-byte Uint8Array.
+ */
+export function encodeFecSourceInfo(sbn: number, esi: number): Uint8Array {
+  const buf = new Uint8Array(8)
+  const view = new DataView(buf.buffer)
+  view.setUint32(0, sbn >>> 0, false)
+  view.setUint32(4, esi >>> 0, false)
+  return buf
+}
+
+/**
+ * Decode FEC Source Info value bytes: reads SBN(4B BE) + ESI(4B BE).
+ * Returns [sbn, esi].
+ */
+export function decodeFecSourceInfo(buf: Uint8Array, offset = 0): [sbn: number, esi: number] {
+  const view = new DataView(buf.buffer, buf.byteOffset + offset, 8)
+  return [view.getUint32(0, false), view.getUint32(4, false)]
+}
+
+/**
+ * FEC Source Info for LOC/CMAF extension headers.
+ * Per draft-ramadan-moq-fec §7.1: SBN(32) + ESI(32), fixed 8-byte minimum.
+ */
+export class FecSourceInfo {
+  static readonly TYPE = LOCHeaderExtensionId.FecSourceInfo
+
+  constructor(
+    /** Source Block Number (32 bits) */
+    public readonly sbn: number,
+    /** Encoding Symbol ID (32 bits) */
+    public readonly esi: number,
+    /** Original object length (optional, for zero-pad stripping) */
+    public readonly objectLength?: number,
+  ) {}
+
+  /** Encode as extension value bytes */
+  encode(): Uint8Array {
+    const base = encodeFecSourceInfo(this.sbn, this.esi)
+    if (this.objectLength == null) return base
+    // Append QUIC varint for object length
+    const lenBytes = encodeQuicVarint(this.objectLength)
+    const result = new Uint8Array(8 + lenBytes.length)
+    result.set(base, 0)
+    result.set(lenBytes, 8)
+    return result
+  }
+
+  /** Decode from extension value bytes */
+  static decode(buf: Uint8Array): FecSourceInfo {
+    const [sbn, esi] = decodeFecSourceInfo(buf)
+    let objectLength: number | undefined
+    if (buf.length > 8) {
+      const [val] = decodeQuicVarint(buf, 8)
+      objectLength = val
+    }
+    return new FecSourceInfo(sbn, esi, objectLength)
+  }
+}
+
+/**
+ * AuthTag for end-to-end content authentication.
+ */
+export class AuthTag {
+  static readonly TYPE = LOCHeaderExtensionId.AuthTag
+
+  constructor(public readonly tag: Uint8Array) {
+    if (tag.length === 0) throw new Error('AuthTag must not be empty')
+  }
+}
+
+// QUIC varint helpers
+function encodeQuicVarint(value: number): Uint8Array {
+  if (value < 64) return new Uint8Array([value])
+  if (value < 16384) {
+    const buf = new Uint8Array(2)
+    new DataView(buf.buffer).setUint16(0, value | 0x4000)
+    return buf
+  }
+  if (value < 1073741824) {
+    const buf = new Uint8Array(4)
+    new DataView(buf.buffer).setUint32(0, value | 0x80000000)
+    return buf
+  }
+  const buf = new Uint8Array(8)
+  new DataView(buf.buffer).setBigUint64(0, BigInt(value) | 0xc000000000000000n)
+  return buf
+}
+
+function decodeQuicVarint(buf: Uint8Array, offset: number): [number, number] {
+  if (offset >= buf.length) return [0, 0]
+  const first = buf[offset]!
+  const prefix = first >> 6
+  const len = 1 << prefix
+  if (offset + len > buf.length) return [0, 0]
+  const view = new DataView(buf.buffer, buf.byteOffset + offset, len)
+  switch (len) {
+    case 1: return [first & 0x3f, 1]
+    case 2: return [view.getUint16(0) & 0x3fff, 2]
+    case 4: return [view.getUint32(0) & 0x3fffffff, 4]
+    case 8: return [Number(view.getBigUint64(0) & 0x3fffffffffffffffn), 8]
+    default: return [0, 0]
+  }
+}
+
+// =============================================================================
+// Inline Tests (vitest)
+// =============================================================================
+
+if (import.meta.vitest) {
+  const { describe, test, expect } = import.meta.vitest
+
+  describe('FEC Source Info (32+32 bit)', () => {
+    test('encode/decode roundtrip', () => {
+      const [sbn, esi] = [1234, 5678]
+      const encoded = encodeFecSourceInfo(sbn, esi)
+      expect(encoded.length).toBe(8)
+      const [s, e] = decodeFecSourceInfo(encoded)
+      expect(s).toBe(1234)
+      expect(e).toBe(5678)
+    })
+
+    test('max 32-bit values', () => {
+      const [sbn, esi] = [0xffffffff, 0xffffffff]
+      const encoded = encodeFecSourceInfo(sbn, esi)
+      const [s, e] = decodeFecSourceInfo(encoded)
+      expect(s).toBe(0xffffffff)
+      expect(e).toBe(0xffffffff)
+    })
+
+    test('FecSourceInfo with object length', () => {
+      const info = new FecSourceInfo(100, 5, 9999)
+      const encoded = info.encode()
+      expect(encoded.length).toBeGreaterThan(8) // 8 + varint
+      const decoded = FecSourceInfo.decode(encoded)
+      expect(decoded.sbn).toBe(100)
+      expect(decoded.esi).toBe(5)
+      expect(decoded.objectLength).toBe(9999)
+    })
+
+    test('FecSourceInfo without object length', () => {
+      const info = new FecSourceInfo(7, 3)
+      const encoded = info.encode()
+      expect(encoded.length).toBe(8)
+      const decoded = FecSourceInfo.decode(encoded)
+      expect(decoded.sbn).toBe(7)
+      expect(decoded.esi).toBe(3)
+      expect(decoded.objectLength).toBeUndefined()
+    })
+
+  })
+}

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()
+    },
+  }
+}