@blockcast/mmt-manifest-verify 0.1.0

package/src/source-auth.ts

@@ -0,0 +1,230 @@
+import { blake3 } from '@noble/hashes/blake3'
+
+export const SOURCE_AUTH_MANIFEST_VERSION = 1
+export const SOURCE_AUTH_OBJECT_ENTRY_FRAME = 1
+export const SOURCE_AUTH_GROUP_CLOSE_FRAME = 2
+export const SOURCE_AUTH_OBJECT_ENTRY_LENGTH = 52
+export const SOURCE_AUTH_GROUP_CLOSE_LENGTH = 112
+export const SOURCE_AUTH_MAX_OBJECTS_PER_GROUP = 4096
+export const SOURCE_AUTH_MAX_TRUE_LENGTH = 16 * 1024 * 1024
+export const SOURCE_AUTH_SCOPE_LENGTH = 32
+
+const SIGNATURE_DOMAIN = new TextEncoder().encode('blockcast-mmt-root-v1\0\0\0')
+
+export interface SourceAuthObjectEntry {
+  kind: 'object'
+  groupId: bigint
+  objectId: number
+  trueLength: number
+  digest: Uint8Array
+}
+
+export interface SourceAuthGroupClose {
+  kind: 'close'
+  groupId: bigint
+  objectCount: number
+  root: Uint8Array
+  signature: Uint8Array
+}
+
+export type SourceAuthManifestFrame = SourceAuthObjectEntry | SourceAuthGroupClose
+
+function requireBytes(name: string, value: Uint8Array, length: number): void {
+  if (value.byteLength !== length) {
+    throw new Error(`${name} must be ${length} bytes, got ${value.byteLength}`)
+  }
+}
+
+function requireU32(name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 0 || value > 0xffff_ffff) {
+    throw new Error(`${name} must be an unsigned 32-bit integer`)
+  }
+}
+
+function requireU64(name: string, value: bigint): void {
+  if (value < 0n || value > 0xffff_ffff_ffff_ffffn) {
+    throw new Error(`${name} must be an unsigned 64-bit integer`)
+  }
+}
+
+function requireTrueLength(value: number): void {
+  requireU32('trueLength', value)
+  if (value > SOURCE_AUTH_MAX_TRUE_LENGTH) {
+    throw new Error(`trueLength exceeds the ${SOURCE_AUTH_MAX_TRUE_LENGTH}-byte profile maximum`)
+  }
+}
+
+export function sourceAuthObjectDigest(object: Uint8Array): Uint8Array {
+  return blake3(object)
+}
+
+export function sourceAuthLeafHash(
+  groupId: bigint,
+  objectId: number,
+  digest: Uint8Array,
+  trueLength: number,
+): Uint8Array {
+  requireU64('groupId', groupId)
+  requireU32('objectId', objectId)
+  requireBytes('digest', digest, 32)
+  requireTrueLength(trueLength)
+  const preimage = new Uint8Array(49)
+  const view = new DataView(preimage.buffer)
+  view.setBigUint64(1, groupId)
+  view.setUint32(9, objectId)
+  preimage.set(digest, 13)
+  view.setUint32(45, trueLength)
+  return blake3(preimage)
+}
+
+export function sourceAuthMerkleRoot(
+  entries: readonly {
+    groupId: bigint
+    objectId: number
+    digest: Uint8Array
+    trueLength: number
+  }[],
+): Uint8Array {
+  if (entries.length === 0) throw new Error('Merkle tree requires at least one object')
+  if (entries.length > SOURCE_AUTH_MAX_OBJECTS_PER_GROUP) {
+    throw new Error(`group exceeds ${SOURCE_AUTH_MAX_OBJECTS_PER_GROUP} objects`)
+  }
+  const groupId = entries[0]!.groupId
+  const objectIds = new Set<number>()
+  const ordered = [...entries].sort((left, right) => left.objectId - right.objectId)
+  let level = ordered.map((entry) => {
+    if (entry.groupId !== groupId) throw new Error('Merkle entries must belong to one group')
+    if (objectIds.has(entry.objectId)) throw new Error(`duplicate objectId ${entry.objectId}`)
+    objectIds.add(entry.objectId)
+    return sourceAuthLeafHash(entry.groupId, entry.objectId, entry.digest, entry.trueLength)
+  })
+  while (level.length > 1) {
+    const parents: Uint8Array[] = []
+    for (let index = 0; index < level.length; index += 2) {
+      const left = level[index]!
+      const right = level[index + 1] ?? left
+      const preimage = new Uint8Array(65)
+      preimage[0] = 1
+      preimage.set(left, 1)
+      preimage.set(right, 33)
+      parents.push(blake3(preimage))
+    }
+    level = parents
+  }
+  return level[0]!
+}
+
+export function trimRecoveredSourceAuthObject(
+  recoveredSymbol: Uint8Array,
+  trueLength: number,
+): Uint8Array {
+  requireTrueLength(trueLength)
+  if (trueLength > recoveredSymbol.byteLength) {
+    throw new Error(`true length ${trueLength} exceeds recovered object size ${recoveredSymbol.byteLength}`)
+  }
+  return recoveredSymbol.subarray(0, trueLength)
+}
+
+export function encodeSourceAuthObjectEntry(
+  entry: Omit<SourceAuthObjectEntry, 'kind'>,
+): Uint8Array {
+  requireU32('objectId', entry.objectId)
+  requireTrueLength(entry.trueLength)
+  requireU64('groupId', entry.groupId)
+  requireBytes('digest', entry.digest, 32)
+  const frame = new Uint8Array(SOURCE_AUTH_OBJECT_ENTRY_LENGTH)
+  const view = new DataView(frame.buffer)
+  frame[0] = SOURCE_AUTH_OBJECT_ENTRY_FRAME
+  frame[1] = SOURCE_AUTH_MANIFEST_VERSION
+  view.setBigUint64(4, entry.groupId)
+  view.setUint32(12, entry.objectId)
+  view.setUint32(16, entry.trueLength)
+  frame.set(entry.digest, 20)
+  return frame
+}
+
+export function encodeSourceAuthGroupClose(
+  close: Omit<SourceAuthGroupClose, 'kind'>,
+): Uint8Array {
+  requireU32('objectCount', close.objectCount)
+  if (close.objectCount === 0 || close.objectCount > SOURCE_AUTH_MAX_OBJECTS_PER_GROUP) {
+    throw new Error(`objectCount must be between 1 and ${SOURCE_AUTH_MAX_OBJECTS_PER_GROUP}`)
+  }
+  requireU64('groupId', close.groupId)
+  requireBytes('root', close.root, 32)
+  requireBytes('signature', close.signature, 64)
+  const frame = new Uint8Array(SOURCE_AUTH_GROUP_CLOSE_LENGTH)
+  const view = new DataView(frame.buffer)
+  frame[0] = SOURCE_AUTH_GROUP_CLOSE_FRAME
+  frame[1] = SOURCE_AUTH_MANIFEST_VERSION
+  view.setBigUint64(4, close.groupId)
+  view.setUint32(12, close.objectCount)
+  frame.set(close.root, 16)
+  frame.set(close.signature, 48)
+  return frame
+}
+
+export function sourceAuthSignaturePreimage(
+  authScope: Uint8Array,
+  groupId: bigint,
+  objectCount: number,
+  root: Uint8Array,
+): Uint8Array {
+  requireU32('objectCount', objectCount)
+  if (objectCount === 0 || objectCount > SOURCE_AUTH_MAX_OBJECTS_PER_GROUP) {
+    throw new Error(`objectCount must be between 1 and ${SOURCE_AUTH_MAX_OBJECTS_PER_GROUP}`)
+  }
+  requireU64('groupId', groupId)
+  requireBytes('authScope', authScope, SOURCE_AUTH_SCOPE_LENGTH)
+  requireBytes('root', root, 32)
+  const preimage = new Uint8Array(100)
+  const view = new DataView(preimage.buffer)
+  preimage.set(SIGNATURE_DOMAIN)
+  preimage.set(authScope, 24)
+  view.setBigUint64(56, groupId)
+  view.setUint32(64, objectCount)
+  preimage.set(root, 68)
+  return preimage
+}
+
+export function decodeSourceAuthManifestFrame(frame: Uint8Array): SourceAuthManifestFrame {
+  const frameType = frame[0]
+  const expectedLength = frameType === SOURCE_AUTH_OBJECT_ENTRY_FRAME
+    ? SOURCE_AUTH_OBJECT_ENTRY_LENGTH
+    : frameType === SOURCE_AUTH_GROUP_CLOSE_FRAME
+      ? SOURCE_AUTH_GROUP_CLOSE_LENGTH
+      : 0
+  if (expectedLength === 0) throw new Error(`unsupported manifest frame type ${frameType}`)
+  if (frame.byteLength !== expectedLength) {
+    throw new Error(`manifest frame has invalid length ${frame.byteLength} for type ${frameType}`)
+  }
+  if (frame[1] !== SOURCE_AUTH_MANIFEST_VERSION) {
+    throw new Error(`unsupported manifest version ${frame[1]}`)
+  }
+  if (frame[2] !== 0 || frame[3] !== 0) throw new Error('manifest reserved bits must be zero')
+
+  const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength)
+  const groupId = view.getBigUint64(4)
+  if (frameType === SOURCE_AUTH_OBJECT_ENTRY_FRAME) {
+    const entry: SourceAuthObjectEntry = {
+      kind: 'object',
+      groupId,
+      objectId: view.getUint32(12),
+      trueLength: view.getUint32(16),
+      digest: frame.slice(20, 52),
+    }
+    requireTrueLength(entry.trueLength)
+    return entry
+  }
+  const close: SourceAuthGroupClose = {
+    kind: 'close',
+    groupId,
+    objectCount: view.getUint32(12),
+    root: frame.slice(16, 48),
+    signature: frame.slice(48, 112),
+  }
+  if (close.objectCount === 0 || close.objectCount > SOURCE_AUTH_MAX_OBJECTS_PER_GROUP) {
+    throw new Error(`objectCount must be between 1 and ${SOURCE_AUTH_MAX_OBJECTS_PER_GROUP}`)
+  }
+  return close
+}

package/src/verifier.test.ts

@@ -0,0 +1,307 @@
+import { describe, expect, test, vi } from 'vitest'
+import { FecBlockMapper } from '@blockcast/mmt-fec'
+import {
+  encodeSourceAuthGroupClose,
+  encodeSourceAuthObjectEntry,
+  ManifestVerifier,
+  sourceAuthMerkleRoot,
+  sourceAuthObjectDigest,
+} from './index.js'
+
+const mapper = new FecBlockMapper({ interleaveDepthMs: 1000, gopDurationMs: 1000, k: 4 })
+
+function createVerifier(options?: {
+  mode?: 'off' | 'shadow' | 'enforce'
+  onMissingManifest?: 'stall' | 'fallback-shadow'
+  signatureValid?: boolean
+  bitrate?: number
+  authenticated?: boolean
+}) {
+  const failures = vi.fn()
+  const verifier = new ManifestVerifier({
+    manifestAuth: {
+      mode: options?.mode ?? 'enforce',
+      onMissingManifest: options?.onMissingManifest ?? 'stall',
+    },
+    verifySignature: () => options?.signatureValid ?? true,
+    onFailure: failures,
+  })
+  verifier.registerTrack({
+    broadcastNamespaceId: 'broadcast-1',
+    trackName: 'video',
+    keyEpoch: 7,
+    codec: 'avc1.640033',
+    timing: '30/1',
+    fecGeometry: 'K=4,T=1200,D=1',
+    manifestFormatVersion: 1,
+    authScope: new Uint8Array(32).fill(1),
+    publicKey: new Uint8Array(32).fill(2),
+    bitrate: options?.bitrate ?? 80_000,
+    groupDurationMs: 1000,
+    mapper,
+    manifestChannelAuthenticated: options?.authenticated ?? true,
+  })
+  return { verifier, failures }
+}
+
+function entry(groupId: number, objectId: number, data: Uint8Array) {
+  return {
+    groupId: BigInt(groupId),
+    objectId,
+    trueLength: data.byteLength,
+    digest: sourceAuthObjectDigest(data),
+  }
+}
+
+function ingestEntry(verifier: ManifestVerifier, value: ReturnType<typeof entry>): void {
+  verifier.ingestManifestFrame('video', encodeSourceAuthObjectEntry(value))
+}
+
+function closeGroup(
+  verifier: ManifestVerifier,
+  groupId: number,
+  entries: ReturnType<typeof entry>[],
+): void {
+  verifier.ingestManifestFrame('video', encodeSourceAuthGroupClose({
+    groupId: BigInt(groupId),
+    objectCount: entries.length,
+    root: sourceAuthMerkleRoot(entries),
+    signature: new Uint8Array(64).fill(3),
+  }))
+}
+
+describe('ManifestVerifier', () => {
+  test('supports off, shadow, and enforce modes', () => {
+    const data = new Uint8Array([1, 2, 3])
+    const identity = { trackName: 'video', groupId: 1, objectId: 0, ssId: 4 }
+
+    const off = createVerifier({ mode: 'off' }).verifier
+    const offRelease = vi.fn()
+    expect(off.admitObject(identity, data, offRelease)).toMatchObject({ action: 'play' })
+    expect(offRelease).toHaveBeenCalledOnce()
+
+    const shadow = createVerifier({ mode: 'shadow' }).verifier
+    const shadowRelease = vi.fn()
+    expect(shadow.admitObject(identity, data, shadowRelease)).toMatchObject({
+      action: 'play',
+      reason: 'manifestAbsent',
+    })
+    expect(shadowRelease).toHaveBeenCalledOnce()
+
+    const enforce = createVerifier().verifier
+    const enforceRelease = vi.fn()
+    expect(enforce.admitObject(identity, data, enforceRelease)).toMatchObject({ action: 'stall' })
+    expect(enforceRelease).not.toHaveBeenCalled()
+  })
+
+  test('releases a late matching entry and drops only a digest mismatch', () => {
+    const { verifier, failures } = createVerifier()
+    const data = new Uint8Array([4, 5, 6])
+    const release = vi.fn()
+    verifier.admitObject({ trackName: 'video', groupId: 2, objectId: 1, ssId: 9 }, data, release)
+    ingestEntry(verifier, entry(2, 1, data))
+    expect(release).toHaveBeenCalledOnce()
+    expect(verifier.stats.verified).toBe(1)
+    expect(failures).toHaveBeenCalledWith(expect.objectContaining({ reason: 'manifestLate' }))
+
+    const badRelease = vi.fn()
+    ingestEntry(verifier, entry(2, 2, new Uint8Array([9])))
+    expect(verifier.admitObject(
+      { trackName: 'video', groupId: 2, objectId: 2, ssId: 10 },
+      new Uint8Array([8]),
+      badRelease,
+    )).toMatchObject({ action: 'drop', reason: 'digestMismatch' })
+    expect(badRelease).not.toHaveBeenCalled()
+  })
+
+  test('verifies one close per group and rejects quarantined media on a bad signature', () => {
+    const { verifier } = createVerifier({ authenticated: false, signatureValid: false })
+    const data = new Uint8Array([7, 8])
+    const manifestEntry = entry(3, 0, data)
+    ingestEntry(verifier, manifestEntry)
+    const release = vi.fn()
+    expect(verifier.admitObject(
+      { trackName: 'video', groupId: 3, objectId: 0, ssId: 12 },
+      data,
+      release,
+    ).action).toBe('stall')
+    closeGroup(verifier, 3, [manifestEntry])
+    expect(release).not.toHaveBeenCalled()
+    expect(verifier.stats.failures.sigInvalid).toBe(1)
+  })
+
+  test('fails open on quarantine cap eviction and verifier exceptions', () => {
+    const capped = createVerifier({ bitrate: 8 }).verifier
+    const capRelease = vi.fn()
+    capped.admitObject(
+      { trackName: 'video', groupId: 4, objectId: 0, ssId: 16 },
+      new Uint8Array(2),
+      capRelease,
+    )
+    expect(capRelease).toHaveBeenCalledOnce()
+    expect(capped.stats.failures.verifierError).toBe(1)
+
+    const release = vi.fn()
+    const verifier = new ManifestVerifier({
+      manifestAuth: { mode: 'enforce', onMissingManifest: 'stall' },
+      verifySignature: () => { throw new Error('WASM unavailable') },
+    })
+    verifier.registerTrack({
+      broadcastNamespaceId: 'broadcast-1', trackName: 'video', keyEpoch: 1,
+      codec: 'avc1', timing: '30/1', fecGeometry: 'K=4', manifestFormatVersion: 1,
+      authScope: new Uint8Array(32), publicKey: new Uint8Array(32), bitrate: 80_000,
+      groupDurationMs: 1000, mapper, manifestChannelAuthenticated: false,
+    })
+    const data = new Uint8Array([1])
+    const manifestEntry = entry(5, 0, data)
+    ingestEntry(verifier, manifestEntry)
+    verifier.admitObject({ trackName: 'video', groupId: 5, objectId: 0, ssId: 20 }, data, release)
+    closeGroup(verifier, 5, [manifestEntry])
+    expect(release).toHaveBeenCalledOnce()
+    expect(verifier.stats.failures.verifierError).toBe(1)
+  })
+
+  test('switches enforce to shadow live and releases quarantine', () => {
+    const { verifier } = createVerifier()
+    const release = vi.fn()
+    verifier.admitObject(
+      { trackName: 'video', groupId: 6, objectId: 0, ssId: 24 },
+      new Uint8Array([1]),
+      release,
+    )
+    verifier.setMode('shadow')
+    expect(release).toHaveBeenCalledOnce()
+    expect(verifier.config.mode).toBe('shadow')
+  })
+
+  test('does not release quarantine for malformed or incomplete manifest frames', () => {
+    const { verifier } = createVerifier()
+    const release = vi.fn()
+    verifier.admitObject(
+      { trackName: 'video', groupId: 7, objectId: 0, ssId: 28 },
+      new Uint8Array([1]),
+      release,
+    )
+    verifier.ingestManifestFrame('video', new Uint8Array([0xff]))
+    verifier.ingestManifestFrame('video', encodeSourceAuthGroupClose({
+      groupId: 7n,
+      objectCount: 1,
+      root: new Uint8Array(32),
+      signature: new Uint8Array(64),
+    }))
+    expect(release).not.toHaveBeenCalled()
+    expect(verifier.stats.failures.verifierError).toBe(1)
+    expect(verifier.stats.failures.manifestAbsent).toBe(1)
+  })
+
+  test('rejects entries appended after a verified close', () => {
+    const { verifier } = createVerifier({ authenticated: false })
+    const first = entry(8, 0, new Uint8Array([1]))
+    ingestEntry(verifier, first)
+    closeGroup(verifier, 8, [first])
+
+    ingestEntry(verifier, entry(8, 1, new Uint8Array([2])))
+    const release = vi.fn()
+    expect(verifier.admitObject(
+      { trackName: 'video', groupId: 8, objectId: 1, ssId: 33 },
+      new Uint8Array([2]),
+      release,
+    ).action).toBe('stall')
+    expect(release).not.toHaveBeenCalled()
+    expect(verifier.stats.failures.verifierError).toBe(1)
+  })
+
+  test('requires exact authenticated object length', () => {
+    const { verifier } = createVerifier()
+    ingestEntry(verifier, entry(9, 0, new Uint8Array([1])))
+    const release = vi.fn()
+    expect(verifier.admitObject(
+      { trackName: 'video', groupId: 9, objectId: 0, ssId: 36 },
+      new Uint8Array([1, 2]),
+      release,
+    )).toMatchObject({ action: 'drop', reason: 'digestMismatch' })
+    expect(release).not.toHaveBeenCalled()
+  })
+
+  test('keeps first arrival on duplicate pending object identity', () => {
+    const { verifier } = createVerifier()
+    const firstRelease = vi.fn()
+    const duplicateRelease = vi.fn()
+    const identity = { trackName: 'video', groupId: 10, objectId: 0, ssId: 40 }
+    verifier.admitObject(identity, new Uint8Array([1]), firstRelease)
+    verifier.admitObject(identity, new Uint8Array([1]), duplicateRelease)
+    expect(verifier.stats.quarantinedBytes).toBe(1)
+    ingestEntry(verifier, entry(10, 0, new Uint8Array([1])))
+    expect(firstRelease).toHaveBeenCalledOnce()
+    expect(duplicateRelease).not.toHaveBeenCalled()
+  })
+
+  test('re-attempts group close when entries complete after a reordered close frame', () => {
+    const { verifier } = createVerifier({ authenticated: false })
+    const dataA = new Uint8Array([1, 2])
+    const dataB = new Uint8Array([3])
+    const entryA = entry(11, 0, dataA)
+    const entryB = entry(11, 1, dataB)
+
+    // Manifest-channel reorder: the close frame beats every object entry.
+    closeGroup(verifier, 11, [entryA, entryB])
+    expect(verifier.stats.failures.manifestAbsent).toBe(1)
+
+    const release = vi.fn()
+    expect(verifier.admitObject(
+      { trackName: 'video', groupId: 11, objectId: 0, ssId: 44 },
+      dataA,
+      release,
+    ).action).toBe('stall')
+
+    // Before the last entry arrives the object stays quarantined, not played.
+    ingestEntry(verifier, entryA)
+    expect(release).not.toHaveBeenCalled()
+    expect(verifier.stats.verified).toBe(0)
+
+    // Final entry completes the group: the stashed close is re-attempted and
+    // the quarantined object is released verified.
+    ingestEntry(verifier, entryB)
+    expect(release).toHaveBeenCalledOnce()
+    expect(verifier.stats.verified).toBe(1)
+
+    const directRelease = vi.fn()
+    expect(verifier.admitObject(
+      { trackName: 'video', groupId: 11, objectId: 1, ssId: 45 },
+      dataB,
+      directRelease,
+    )).toMatchObject({ action: 'play', verified: true })
+    expect(directRelease).toHaveBeenCalledOnce()
+  })
+
+  test('verifies a group whose id exceeds Number.MAX_SAFE_INTEGER (u62 group ids)', () => {
+    const { verifier, failures } = createVerifier()
+    const groupId = 72623859790382856n
+    expect(Number.isSafeInteger(Number(groupId))).toBe(false)
+
+    const data = new Uint8Array([9, 8, 7])
+    const bigEntry = {
+      groupId,
+      objectId: 0,
+      trueLength: data.byteLength,
+      digest: sourceAuthObjectDigest(data),
+    }
+    verifier.ingestManifestFrame('video', encodeSourceAuthObjectEntry(bigEntry))
+    verifier.ingestManifestFrame('video', encodeSourceAuthGroupClose({
+      groupId,
+      objectCount: 1,
+      root: sourceAuthMerkleRoot([bigEntry]),
+      signature: new Uint8Array(64).fill(3),
+    }))
+
+    const release = vi.fn()
+    expect(verifier.admitObject(
+      { trackName: 'video', groupId, objectId: 0 },
+      data,
+      release,
+    )).toMatchObject({ action: 'play', verified: true })
+    expect(release).toHaveBeenCalledOnce()
+    expect(verifier.stats.verified).toBe(1)
+    expect(failures).not.toHaveBeenCalled()
+  })
+})