@blockcast/mmt-manifest-verify 0.1.0

package/src/verifier.ts

@@ -0,0 +1,520 @@
+import {
+  decodeSourceAuthManifestFrame,
+  sourceAuthMerkleRoot,
+  sourceAuthObjectDigest,
+  sourceAuthSignaturePreimage,
+  type SourceAuthGroupClose,
+  type SourceAuthObjectEntry,
+} from './source-auth.js'
+
+export type ManifestAuthMode = 'off' | 'shadow' | 'enforce'
+export type MissingManifestPolicy = 'stall' | 'fallback-shadow'
+export type ManifestFailureReason =
+  | 'sigInvalid'
+  | 'digestMismatch'
+  | 'manifestLate'
+  | 'manifestAbsent'
+  | 'verifierError'
+
+export interface ManifestAuthConfig {
+  mode: ManifestAuthMode
+  onMissingManifest: MissingManifestPolicy
+}
+
+export interface ManifestObjectIdentity {
+  trackName: string
+  /** MoQ group ids are u62; values above 2^53 must be passed as bigint. */
+  groupId: number | bigint
+  objectId: number
+  packetId?: number
+  ssId?: number
+}
+
+export interface ManifestFecBlockMapper {
+  readonly d: number
+  derive(groupId: number, objectId: number): { ssId: number }
+}
+
+export interface ManifestTrackContext {
+  broadcastNamespaceId: string
+  trackName: string
+  keyEpoch: number
+  codec: string
+  timing: string
+  fecGeometry: string
+  manifestFormatVersion: number
+  /** Authenticated-catalog binding for the namespace, track, epoch, codec,
+   * timing, FEC geometry, and manifest version fields above. */
+  authScope: Uint8Array
+  publicKey: Uint8Array
+  bitrate: number
+  groupDurationMs: number
+  mapper: ManifestFecBlockMapper
+  manifestChannelAuthenticated: boolean
+}
+
+export interface ManifestVerificationStats {
+  verified: number
+  failures: Record<ManifestFailureReason, number>
+  quarantinedBytes: number
+}
+
+export interface ManifestFailure {
+  trackName: string
+  groupId: number | bigint
+  objectId: number
+  reason: ManifestFailureReason
+}
+
+export interface ManifestAdmission {
+  action: 'play' | 'stall' | 'drop'
+  verified: boolean
+  reason?: ManifestFailureReason
+}
+
+type SignatureVerifier = (
+  publicKey: Uint8Array,
+  message: Uint8Array,
+  signature: Uint8Array,
+) => boolean
+
+interface PendingObject {
+  identity: ManifestObjectIdentity
+  data: Uint8Array
+  release: () => void
+  bytes: number
+}
+
+interface GroupState {
+  entries: Map<number, SourceAuthObjectEntry>
+  pending: Map<number, PendingObject>
+  close?: SourceAuthGroupClose
+  /** Close frame that arrived before all object entries (manifest-channel
+   * reordering); retried once the entry count matches. */
+  pendingClose?: SourceAuthGroupClose
+  rootVerified: boolean
+  failed?: ManifestFailureReason
+}
+
+interface TrackState {
+  context: ManifestTrackContext
+  groups: Map<bigint, GroupState>
+  quarantine: PendingObject[]
+  quarantinedBytes: number
+  capBytes: number
+  manifestEntries: number
+  maxManifestEntries: number
+  maxGroups: number
+}
+
+const FAILURE_REASONS: readonly ManifestFailureReason[] = [
+  'sigInvalid',
+  'digestMismatch',
+  'manifestLate',
+  'manifestAbsent',
+  'verifierError',
+]
+
+const equalBytes = (left: Uint8Array, right: Uint8Array): boolean => {
+  if (left.byteLength !== right.byteLength) return false
+  let diff = 0
+  for (let index = 0; index < left.byteLength; index++) diff |= left[index]! ^ right[index]!
+  return diff === 0
+}
+
+export class ManifestVerifier {
+  #config: ManifestAuthConfig
+  readonly #verifySignature: SignatureVerifier
+  readonly #onFailure?: (failure: ManifestFailure) => void
+  readonly #tracks = new Map<string, TrackState>()
+  readonly #stats: ManifestVerificationStats = {
+    verified: 0,
+    failures: Object.fromEntries(FAILURE_REASONS.map((reason) => [reason, 0])) as Record<ManifestFailureReason, number>,
+    quarantinedBytes: 0,
+  }
+
+  constructor(options: {
+    manifestAuth: ManifestAuthConfig
+    verifySignature: SignatureVerifier
+    onFailure?: (failure: ManifestFailure) => void
+  }) {
+    this.#config = { ...options.manifestAuth }
+    this.#verifySignature = options.verifySignature
+    this.#onFailure = options.onFailure
+  }
+
+  get config(): Readonly<ManifestAuthConfig> {
+    return this.#config
+  }
+
+  get stats(): ManifestVerificationStats {
+    return {
+      verified: this.#stats.verified,
+      failures: { ...this.#stats.failures },
+      quarantinedBytes: this.#stats.quarantinedBytes,
+    }
+  }
+
+  setMode(mode: ManifestAuthMode): void {
+    this.#config = { ...this.#config, mode }
+    if (mode !== 'enforce') this.#releaseAllQuarantine(false)
+  }
+
+  registerTrack(context: ManifestTrackContext): void {
+    if (this.#tracks.has(context.trackName)) {
+      throw new Error(`manifest track ${context.trackName} is already registered`)
+    }
+    if (!Number.isFinite(context.bitrate) || context.bitrate <= 0) {
+      throw new Error('manifest track bitrate must be > 0')
+    }
+    if (!Number.isFinite(context.groupDurationMs) || context.groupDurationMs <= 0) {
+      throw new Error('manifest track groupDurationMs must be > 0')
+    }
+    if (context.authScope.byteLength !== 32) throw new Error('manifest authScope must be 32 bytes')
+    if (context.publicKey.byteLength !== 32) throw new Error('manifest publicKey must be 32 bytes')
+    for (const [name, value] of Object.entries({
+      broadcastNamespaceId: context.broadcastNamespaceId,
+      trackName: context.trackName,
+      codec: context.codec,
+      timing: context.timing,
+      fecGeometry: context.fecGeometry,
+    })) {
+      if (value.length === 0) throw new Error(`manifest ${name} must not be empty`)
+    }
+    this.#tracks.set(context.trackName, {
+      context,
+      groups: new Map(),
+      quarantine: [],
+      quarantinedBytes: 0,
+      capBytes: Math.ceil((context.bitrate * context.groupDurationMs) / 8000),
+      manifestEntries: 0,
+      maxManifestEntries: Math.ceil((context.bitrate * context.groupDurationMs) / (8000 * 52)),
+      maxGroups: context.mapper.d + 1,
+    })
+  }
+
+  ingestManifestFrame(trackName: string, frameBytes: Uint8Array): void {
+    const track = this.#requireTrack(trackName)
+    try {
+      const frame = decodeSourceAuthManifestFrame(frameBytes)
+      const groupId = frame.groupId
+      const group = this.#group(track, groupId)
+      if (frame.kind === 'object') {
+        if (group.close || group.failed) {
+          this.#failure({ trackName, groupId, objectId: frame.objectId }, 'verifierError')
+          return
+        }
+        if (group.entries.has(frame.objectId)) {
+          this.#failure({ trackName, groupId, objectId: frame.objectId }, 'verifierError')
+          return
+        }
+        if (group.entries.size >= 4096 || track.manifestEntries >= track.maxManifestEntries) {
+          this.#failure({ trackName, groupId, objectId: frame.objectId }, 'verifierError')
+          return
+        }
+        group.entries.set(frame.objectId, frame)
+        track.manifestEntries++
+        const pending = group.pending.get(frame.objectId)
+        if (pending) {
+          this.#failure(pending.identity, 'manifestLate')
+          this.#resolvePending(track, group, pending, frame)
+        }
+        if (group.pendingClose && group.entries.size === group.pendingClose.objectCount) {
+          const close = group.pendingClose
+          group.pendingClose = undefined
+          this.#closeGroup(track, groupId, group, close)
+        }
+        return
+      }
+      this.#closeGroup(track, groupId, group, frame)
+    } catch {
+      this.#failure({ trackName, groupId: 0, objectId: 0 }, 'verifierError')
+    }
+  }
+
+  admitObject(
+    identity: ManifestObjectIdentity,
+    data: Uint8Array,
+    release: () => void,
+  ): ManifestAdmission {
+    if (this.#config.mode === 'off') {
+      release()
+      return { action: 'play', verified: false }
+    }
+    const track = this.#tracks.get(identity.trackName)
+    if (!track) {
+      release()
+      this.#failure(identity, 'verifierError')
+      return { action: 'play', verified: false, reason: 'verifierError' }
+    }
+    try {
+      if (!this.#validateIdentity(track, identity)) {
+        return this.#rejectOrShadow(identity, release, 'digestMismatch')
+      }
+      const group = this.#group(track, BigInt(identity.groupId))
+      if (group.failed === 'sigInvalid' || group.failed === 'digestMismatch') {
+        return this.#rejectOrShadow(identity, release, group.failed)
+      }
+      const entry = group.entries.get(identity.objectId)
+      if (entry) return this.#admitAgainstEntry(track, group, identity, data, release, entry)
+      if (this.#config.mode === 'shadow' || this.#config.onMissingManifest === 'fallback-shadow') {
+        release()
+        this.#failure(identity, 'manifestAbsent')
+        return { action: 'play', verified: false, reason: 'manifestAbsent' }
+      }
+      if (!this.#quarantine(track, group, { identity, data, release, bytes: data.byteLength })) {
+        return { action: 'drop', verified: false }
+      }
+      return { action: 'stall', verified: false }
+    } catch {
+      release()
+      this.#failure(identity, 'verifierError')
+      return { action: 'play', verified: false, reason: 'verifierError' }
+    }
+  }
+
+  dispose(): void {
+    this.#releaseAllQuarantine(false)
+    this.#tracks.clear()
+  }
+
+  #requireTrack(trackName: string): TrackState {
+    const track = this.#tracks.get(trackName)
+    if (!track) throw new Error(`unknown manifest track ${trackName}`)
+    return track
+  }
+
+  #group(track: TrackState, groupId: bigint): GroupState {
+    let group = track.groups.get(groupId)
+    if (!group) {
+      group = { entries: new Map(), pending: new Map(), rootVerified: false }
+      track.groups.set(groupId, group)
+      while (track.groups.size > track.maxGroups) {
+        const oldest = track.groups.entries().next().value as [bigint, GroupState] | undefined
+        if (!oldest) break
+        const [oldestId, oldestGroup] = oldest
+        for (const pending of [...oldestGroup.pending.values()]) {
+          this.#removePending(track, oldestGroup, pending)
+          pending.release()
+          this.#failure(pending.identity, 'verifierError')
+        }
+        track.manifestEntries -= oldestGroup.entries.size
+        track.groups.delete(oldestId)
+      }
+    }
+    return group
+  }
+
+  #validateIdentity(track: TrackState, identity: ManifestObjectIdentity): boolean {
+    const coordinates = track.context.mapper.derive(Number(identity.groupId), identity.objectId)
+    return identity.ssId === undefined || coordinates.ssId === identity.ssId
+  }
+
+  #admitAgainstEntry(
+    track: TrackState,
+    group: GroupState,
+    identity: ManifestObjectIdentity,
+    data: Uint8Array,
+    release: () => void,
+    entry: SourceAuthObjectEntry,
+  ): ManifestAdmission {
+    if (entry.trueLength !== data.byteLength) {
+      return this.#rejectOrShadow(identity, release, 'digestMismatch')
+    }
+    const digestMatches = equalBytes(sourceAuthObjectDigest(data.subarray(0, entry.trueLength)), entry.digest)
+    if (!digestMatches) return this.#rejectOrShadow(identity, release, 'digestMismatch')
+    if (!track.context.manifestChannelAuthenticated && !group.rootVerified) {
+      if (this.#config.mode === 'shadow') {
+        release()
+        return { action: 'play', verified: false }
+      }
+      if (!this.#quarantine(track, group, { identity, data, release, bytes: data.byteLength })) {
+        return { action: 'drop', verified: false }
+      }
+      return { action: 'stall', verified: false }
+    }
+    release()
+    this.#stats.verified++
+    return { action: 'play', verified: true }
+  }
+
+  #rejectOrShadow(
+    identity: ManifestObjectIdentity,
+    release: () => void,
+    reason: 'digestMismatch' | 'sigInvalid',
+  ): ManifestAdmission {
+    this.#failure(identity, reason)
+    if (this.#config.mode === 'enforce') {
+      console.warn(JSON.stringify({ event: 'manifest-enforce-drop', track: identity.trackName, group: String(identity.groupId), object: identity.objectId, reason }))
+      return { action: 'drop', verified: false, reason }
+    }
+    release()
+    return { action: 'play', verified: false, reason }
+  }
+
+  #resolvePending(
+    track: TrackState,
+    group: GroupState,
+    pending: PendingObject,
+    entry: SourceAuthObjectEntry,
+  ): void {
+    this.#removePending(track, group, pending)
+    this.#admitAgainstEntry(track, group, pending.identity, pending.data, pending.release, entry)
+  }
+
+  #closeGroup(
+    track: TrackState,
+    groupId: bigint,
+    group: GroupState,
+    close: SourceAuthGroupClose,
+  ): void {
+    if (group.close) return
+    const entries = [...group.entries.values()]
+    if (entries.length !== close.objectCount) {
+      // Manifest-channel reordering: the close frame beat some object entries.
+      // Stash it (latest-wins on duplicates) so the object-entry path can
+      // re-attempt the close once the count matches; quarantined objects stay
+      // quarantined, and manifestAbsent below is a signal, not an eviction.
+      group.pendingClose = close
+      const hadPending = group.pending.size > 0
+      if (this.#config.onMissingManifest === 'fallback-shadow' || this.#config.mode === 'shadow') {
+        for (const pending of [...group.pending.values()]) {
+          this.#removePending(track, group, pending)
+          pending.release()
+          this.#failure(pending.identity, 'manifestAbsent')
+        }
+      } else {
+        for (const pending of group.pending.values()) {
+          this.#failure(pending.identity, 'manifestAbsent')
+        }
+      }
+      if (!hadPending) {
+        this.#failure({ trackName: track.context.trackName, groupId, objectId: 0 }, 'manifestAbsent')
+      }
+      return
+    }
+    if (!equalBytes(sourceAuthMerkleRoot(entries), close.root)) {
+      group.failed = 'digestMismatch'
+      this.#failGroup(track, groupId, group, 'digestMismatch')
+      return
+    }
+    const preimage = sourceAuthSignaturePreimage(track.context.authScope, close.groupId, close.objectCount, close.root)
+    let signatureValid: boolean
+    try {
+      signatureValid = this.#verifySignature(track.context.publicKey, preimage, close.signature)
+    } catch {
+      this.#failOpenGroup(track, groupId, group)
+      return
+    }
+    if (!signatureValid) {
+      group.failed = 'sigInvalid'
+      this.#failGroup(track, groupId, group, 'sigInvalid')
+      return
+    }
+    group.failed = undefined
+    group.close = close
+    group.pendingClose = undefined
+    group.rootVerified = true
+    for (const pending of [...group.pending.values()]) {
+      const entry = group.entries.get(pending.identity.objectId)
+      if (entry) this.#resolvePending(track, group, pending, entry)
+      else if (this.#config.onMissingManifest === 'fallback-shadow') {
+        this.#removePending(track, group, pending)
+        pending.release()
+        this.#failure(pending.identity, 'manifestAbsent')
+      }
+    }
+  }
+
+  #failGroup(
+    track: TrackState,
+    groupId: bigint,
+    group: GroupState,
+    reason: 'digestMismatch' | 'sigInvalid',
+  ): void {
+    if (group.pending.size === 0) {
+      this.#failure({ trackName: track.context.trackName, groupId, objectId: 0 }, reason)
+      return
+    }
+    for (const pending of [...group.pending.values()]) {
+      this.#removePending(track, group, pending)
+      this.#rejectOrShadow(pending.identity, pending.release, reason)
+    }
+  }
+
+  #removePending(track: TrackState, group: GroupState, pending: PendingObject): void {
+    if (group.pending.get(pending.identity.objectId) === pending) {
+      group.pending.delete(pending.identity.objectId)
+    }
+    const index = track.quarantine.indexOf(pending)
+    if (index >= 0) track.quarantine.splice(index, 1)
+    track.quarantinedBytes -= pending.bytes
+    this.#stats.quarantinedBytes -= pending.bytes
+  }
+
+  #quarantine(track: TrackState, group: GroupState, pending: PendingObject): boolean {
+    if (group.pending.has(pending.identity.objectId)) return false
+    group.pending.set(pending.identity.objectId, pending)
+    track.quarantine.push(pending)
+    track.quarantinedBytes += pending.bytes
+    this.#stats.quarantinedBytes += pending.bytes
+    this.#enforceCap(track)
+    return true
+  }
+
+  #enforceCap(track: TrackState): void {
+    while (track.quarantinedBytes > track.capBytes && track.quarantine.length > 0) {
+      const pending = track.quarantine.shift()!
+      const group = track.groups.get(BigInt(pending.identity.groupId))
+      if (group) group.pending.delete(pending.identity.objectId)
+      track.quarantinedBytes -= pending.bytes
+      this.#stats.quarantinedBytes -= pending.bytes
+      pending.release()
+      this.#failure(pending.identity, 'verifierError')
+      console.warn(`[ManifestVerifier] quarantine cap eviction fail-open track=${pending.identity.trackName} group=${pending.identity.groupId} object=${pending.identity.objectId}`)
+    }
+  }
+
+  #failOpenTrack(track: TrackState, reason: 'verifierError'): void {
+    for (const pending of [...track.quarantine]) {
+      const group = track.groups.get(BigInt(pending.identity.groupId))
+      if (group) this.#removePending(track, group, pending)
+      pending.release()
+      this.#failure(pending.identity, reason)
+    }
+  }
+
+  #failOpenGroup(track: TrackState, groupId: bigint, group: GroupState): void {
+    const pending = [...group.pending.values()]
+    if (pending.length === 0) {
+      this.#failure({ trackName: track.context.trackName, groupId, objectId: 0 }, 'verifierError')
+      return
+    }
+    for (const object of pending) {
+      this.#removePending(track, group, object)
+      object.release()
+      this.#failure(object.identity, 'verifierError')
+    }
+  }
+
+  #releaseAllQuarantine(countFailure: boolean): void {
+    for (const track of this.#tracks.values()) {
+      for (const pending of [...track.quarantine]) {
+        const group = track.groups.get(BigInt(pending.identity.groupId))
+        if (group) this.#removePending(track, group, pending)
+        pending.release()
+        if (countFailure) this.#failure(pending.identity, 'verifierError')
+      }
+    }
+  }
+
+  #failure(identity: ManifestObjectIdentity, reason: ManifestFailureReason): void {
+    this.#stats.failures[reason]++
+    this.#onFailure?.({
+      trackName: identity.trackName,
+      groupId: identity.groupId,
+      objectId: identity.objectId,
+      reason,
+    })
+  }
+}