@blockcast/mmt-container 0.1.0-main.0399efef1f07

package/src/multicast-auth-catalog.ts

@@ -0,0 +1,340 @@
+/**
+ * `multicast.auth` v2 — catalog representation for per-track source-auth
+ * scopes and manifest tracks (BLO-16700 decision).
+ *
+ * Reconciles two previously-accepted, mutually incompatible contracts:
+ *   - BLO-16481 (S0): every publisher session/track/source-symbol-format
+ *     needs its own fresh, unpredictable 32-byte `auth_scope`, bound into
+ *     the signed per-group Merkle root (see `sourceAuthSignaturePreimage`
+ *     in ./source-auth.ts).
+ *   - BLO-16485 (S3 draft): a singular `multicast.auth` block with one
+ *     `manifestTrack` string and no `authScope` field at all — unable to
+ *     describe two protected tracks (e.g. audio + video) in one session.
+ *
+ * `multicast.auth` v2 keeps one shared signing identity (scheme, hash,
+ * sig, publicKey, keyId, previousKey, compaction, enforcement) but moves
+ * `manifestTrack` into a `tracks[]` array, one entry per protected media
+ * track, each carrying its own `manifestTrack` name, `authScope`, and
+ * `sourceSymbolFormat`. This is additive over the S3 draft shape (every
+ * top-level field the draft specified still exists at the top level) —
+ * only `manifestTrack` moves from top-level into each track entry.
+ *
+ * `manifestTrack` is carried as an opaque string field, deliberately NOT
+ * run through `parseTrackRole`/`VALID_ROLE_SUFFIXES` in ./carp-catalog.ts.
+ * `carp-catalog.ts` only recognises `base`/`delta`/`repair` role suffixes
+ * and throws on anything else (including a hypothetical `manifest` role);
+ * resolving BLO-16485's "manifest-track name collision" MANDATORY item by
+ * adding a role would force every catalog consumer to learn a fourth role
+ * and would break `validateSwitchingSet`'s base/delta/repair completeness
+ * check. Carrying it as a typed field here avoids both.
+ */
+
+export type MulticastAuthScheme = "bc-provenance";
+export type MulticastAuthHash = "blake3";
+export type MulticastAuthSig = "ed25519";
+export type MulticastAuthCompaction = "merkle" | "none";
+export type MulticastAuthEnforcement = "shadow" | "enforce";
+export type MulticastAuthMode = "off" | MulticastAuthEnforcement;
+
+const RAW_ED25519_KEY_LENGTH = 32;
+const SOURCE_AUTH_SCOPE_LENGTH = 32;
+
+const BASE64URL_ALPHABET =
+	"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/** Encode raw bytes as unpadded base64url — the one accepted encoding for
+ * `authScope`/`publicKey`/`previousKey` (BLO-16483's operator quickstart). */
+export function encodeBase64Url(bytes: Uint8Array): string {
+	let output = "";
+	for (let i = 0; i < bytes.length; i += 3) {
+		const b0 = bytes[i]!;
+		const b1 = bytes[i + 1];
+		const b2 = bytes[i + 2];
+		output += BASE64URL_ALPHABET[b0 >> 2];
+		output += BASE64URL_ALPHABET[((b0 & 0x03) << 4) | (b1 === undefined ? 0 : b1 >> 4)];
+		if (b1 === undefined) break;
+		output += BASE64URL_ALPHABET[((b1 & 0x0f) << 2) | (b2 === undefined ? 0 : b2 >> 6)];
+		if (b2 === undefined) break;
+		output += BASE64URL_ALPHABET[b2 & 0x3f];
+	}
+	return output;
+}
+
+const BASE64URL_DECODE_TABLE = (() => {
+	const table = new Int8Array(128).fill(-1);
+	for (let i = 0; i < BASE64URL_ALPHABET.length; i++) {
+		table[BASE64URL_ALPHABET.charCodeAt(i)] = i;
+	}
+	return table;
+})();
+
+/** Decode unpadded base64url text to raw bytes. Throws on any padding
+ * (`=`), standard-alphabet (`+`/`/`), or otherwise invalid character. */
+export function decodeBase64Url(text: string): Uint8Array {
+	if (text.length % 4 === 1) {
+		throw new Error(`[multicast-auth-catalog] invalid unpadded base64url length for "${text}"`);
+	}
+	const bytes: number[] = [];
+	let buffer = 0;
+	let bits = 0;
+	for (let i = 0; i < text.length; i++) {
+		const code = text.charCodeAt(i);
+		const value = code < 128 ? BASE64URL_DECODE_TABLE[code] : -1;
+		if (value === undefined || value < 0) {
+			throw new Error(`[multicast-auth-catalog] invalid base64url character in "${text}"`);
+		}
+		buffer = (buffer << 6) | value;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			bytes.push((buffer >> bits) & 0xff);
+		}
+	}
+	const decoded = Uint8Array.from(bytes);
+	if (encodeBase64Url(decoded) !== text) {
+		throw new Error(`[multicast-auth-catalog] non-canonical base64url encoding "${text}"`);
+	}
+	return decoded;
+}
+
+/** Decode + length-validate an `authScope` field. Throws unless it decodes
+ * to exactly `SOURCE_AUTH_SCOPE_LENGTH` (32) raw bytes. */
+export function decodeAuthScope(authScope: string): Uint8Array {
+	const bytes = decodeBase64Url(authScope);
+	if (bytes.byteLength !== SOURCE_AUTH_SCOPE_LENGTH) {
+		throw new Error(
+			`[multicast-auth-catalog] authScope must decode to ${SOURCE_AUTH_SCOPE_LENGTH} raw bytes, got ${bytes.byteLength}`,
+		);
+	}
+	return bytes;
+}
+
+/** Decode a catalog key in the only accepted representation: exactly 32 raw
+ * ed25519 bytes encoded as canonical, unpadded base64url. */
+export function decodeEd25519PublicKey(publicKey: string): Uint8Array {
+	const bytes = decodeBase64Url(publicKey);
+	if (bytes.byteLength !== RAW_ED25519_KEY_LENGTH) {
+		throw new Error(
+			`[multicast-auth-catalog] public key must decode to ${RAW_ED25519_KEY_LENGTH} raw bytes, got ${bytes.byteLength}`,
+		);
+	}
+	return bytes;
+}
+
+/**
+ * One protected media track's manifest + scope binding.
+ *
+ * - `mediaTrack`: the actual media track name (e.g. `"video/base"`).
+ * - `manifestTrack`: the sibling track carrying this track's signed
+ *   manifest objects (see ./source-auth.ts `SourceAuthObjectEntry`/
+ *   `SourceAuthGroupClose`). Opaque string — not role-parsed.
+ * - `authScope`: this track's unique 32-byte scope, raw bytes as unpadded
+ *   base64url. BLO-16481 requires a scope fresh per (publisher session,
+ *   track, source-symbol format) — a track publishing under two source-
+ *   symbol formats in the same session MUST appear as two entries here,
+ *   each with its own scope.
+ * - `sourceSymbolFormat`: names the deployed source-symbol profile this
+ *   track's authenticated bytes are derived from (e.g.
+ *   `"full-mmtp-packet"` or `"fec-padded-recovery"`, the two formats
+ *   BLO-16481's S0 fixture covers).
+ */
+export interface MulticastAuthTrackConfig {
+	mediaTrack: string;
+	manifestTrack: string;
+	authScope: string;
+	sourceSymbolFormat: string;
+}
+
+/**
+ * `multicast.auth` v2 — supersedes the BLO-16485 draft's singular
+ * `manifestTrack`/no-`authScope` shape (BLO-16700 decision).
+ */
+export interface MulticastAuthConfig {
+	scheme: MulticastAuthScheme;
+	hash: MulticastAuthHash;
+	sig: MulticastAuthSig;
+	/** Raw 32-byte ed25519 public key, unpadded base64url. */
+	publicKey: string;
+	keyId: string;
+	/** Raw 32-byte ed25519 public key, unpadded base64url. Accepted
+	 * alongside `publicKey` during a key-rotation overlap window. */
+	previousKey?: string;
+	compaction: MulticastAuthCompaction;
+	/** Player-config-wins default; catalog value only selects the default
+	 * when the player hasn't pinned one (S3 enforcement precedence). */
+	enforcement?: MulticastAuthEnforcement;
+	tracks: MulticastAuthTrackConfig[];
+}
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+function isValidAuthScopeField(value: unknown): value is string {
+	if (!isNonEmptyString(value)) return false;
+	try {
+		decodeAuthScope(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function isValidPublicKeyField(value: unknown): value is string {
+	if (!isNonEmptyString(value)) return false;
+	try {
+		decodeEd25519PublicKey(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function hasOnlyKeys(object: Record<string, unknown>, allowed: readonly string[]): boolean {
+	const allowedKeys = new Set(allowed);
+	return Object.keys(object).every((key) => allowedKeys.has(key));
+}
+
+export function isMulticastAuthTrackConfig(obj: unknown): obj is MulticastAuthTrackConfig {
+	if (typeof obj !== "object" || obj === null) return false;
+	const o = obj as Record<string, unknown>;
+	return (
+		hasOnlyKeys(o, ["mediaTrack", "manifestTrack", "authScope", "sourceSymbolFormat"]) &&
+		isNonEmptyString(o["mediaTrack"]) &&
+		isNonEmptyString(o["manifestTrack"]) &&
+		o["mediaTrack"] !== o["manifestTrack"] &&
+		isValidAuthScopeField(o["authScope"]) &&
+		isNonEmptyString(o["sourceSymbolFormat"])
+	);
+}
+
+const VALID_COMPACTION = new Set<string>(["merkle", "none"]);
+const VALID_ENFORCEMENT = new Set<string>(["shadow", "enforce"]);
+
+/** Semantic uniqueness rule shared by runtime parsing and the published
+ * catalog schema's `uniqueMulticastAuthTrackBindings` keyword. */
+export function hasUniqueMulticastAuthTrackBindings(tracks: readonly unknown[]): boolean {
+	const bindings = tracks.flatMap((track) => {
+		if (typeof track !== "object" || track === null) return [];
+		const value = track as Record<string, unknown>;
+		if (typeof value["mediaTrack"] !== "string" || typeof value["sourceSymbolFormat"] !== "string") {
+			return [];
+		}
+		return [JSON.stringify([value["mediaTrack"], value["sourceSymbolFormat"]])];
+	});
+	return new Set(bindings).size === bindings.length;
+}
+
+export function isMulticastAuthConfig(obj: unknown): obj is MulticastAuthConfig {
+	if (typeof obj !== "object" || obj === null) return false;
+	const o = obj as Record<string, unknown>;
+
+	if (o["scheme"] !== "bc-provenance") return false;
+	if (o["hash"] !== "blake3") return false;
+	if (o["sig"] !== "ed25519") return false;
+	if (!hasOnlyKeys(o, ["scheme", "hash", "sig", "publicKey", "keyId", "previousKey", "compaction", "enforcement", "tracks"])) return false;
+	if (!isValidPublicKeyField(o["publicKey"])) return false;
+	if (!isNonEmptyString(o["keyId"])) return false;
+	if (o["previousKey"] !== undefined && !isValidPublicKeyField(o["previousKey"])) return false;
+	if (o["previousKey"] === o["publicKey"]) return false;
+	if (typeof o["compaction"] !== "string" || !VALID_COMPACTION.has(o["compaction"])) return false;
+	if (o["enforcement"] !== undefined) {
+		if (typeof o["enforcement"] !== "string" || !VALID_ENFORCEMENT.has(o["enforcement"])) return false;
+	}
+
+	if (!Array.isArray(o["tracks"]) || o["tracks"].length === 0) return false;
+	const tracks = o["tracks"] as unknown[];
+	if (!tracks.every((t) => isMulticastAuthTrackConfig(t))) return false;
+	const typedTracks = tracks as MulticastAuthTrackConfig[];
+
+	// BLO-16481: a fresh scope per track — catalog-declared scopes must be
+	// pairwise distinct within one auth block.
+	const scopes = typedTracks.map((t) => t.authScope);
+	if (new Set(scopes).size !== scopes.length) return false;
+	if (!hasUniqueMulticastAuthTrackBindings(typedTracks)) return false;
+
+	// Each entry must point at its own manifest track.
+	const manifestTracks = typedTracks.map((t) => t.manifestTrack);
+	if (new Set(manifestTracks).size !== manifestTracks.length) return false;
+
+	return true;
+}
+
+export interface ResolvedMulticastAuthConfig {
+	keyId: string;
+	/** Current key first, followed by the overlap key when advertised. */
+	acceptedPublicKeys: Uint8Array[];
+	mode: MulticastAuthMode;
+	compaction: MulticastAuthCompaction;
+	tracks: Array<Omit<MulticastAuthTrackConfig, "authScope"> & { authScope: Uint8Array }>;
+}
+
+/** Player configuration is authoritative, including an explicit `off`.
+ * Catalog enforcement is only a default; an auth block without it defaults
+ * to shadow, while a catalog without auth defaults to off. */
+export function resolveMulticastAuthMode(
+	playerMode: MulticastAuthMode | undefined,
+	auth: MulticastAuthConfig | undefined,
+): MulticastAuthMode {
+	if (playerMode !== undefined) return playerMode;
+	if (auth === undefined) return "off";
+	return auth.enforcement ?? "shadow";
+}
+
+/** Parse and resolve the catalog auth block into verifier-ready raw keys and
+ * scopes. Invalid blocks and dangling media/manifest track references fail
+ * closed instead of silently falling back to unauthenticated playback. */
+export function resolveMulticastAuthCatalog(
+	catalog: unknown,
+	playerMode?: MulticastAuthMode,
+): ResolvedMulticastAuthConfig | undefined {
+	if (typeof catalog !== "object" || catalog === null || Array.isArray(catalog)) {
+		throw new Error("[multicast-auth-catalog] catalog must be an object");
+	}
+	const root = catalog as Record<string, unknown>;
+	const rawAuth = root["multicast.auth"];
+	if (rawAuth === undefined) {
+		if (playerMode === "enforce") {
+			throw new Error("[multicast-auth-catalog] player enforce mode requires multicast.auth");
+		}
+		return undefined;
+	}
+	if (!isMulticastAuthConfig(rawAuth)) {
+		throw new Error("[multicast-auth-catalog] invalid multicast.auth v2 block");
+	}
+
+	const rawTracks = root["tracks"];
+	if (!Array.isArray(rawTracks)) {
+		throw new Error("[multicast-auth-catalog] catalog tracks must be an array");
+	}
+	const catalogTrackNames = new Set(
+		rawTracks.flatMap((track) =>
+			typeof track === "object" && track !== null &&
+			typeof (track as Record<string, unknown>)["name"] === "string"
+				? [(track as Record<string, unknown>)["name"] as string]
+				: []
+		),
+	);
+	for (const track of rawAuth.tracks) {
+		if (!catalogTrackNames.has(track.mediaTrack)) {
+			throw new Error(`[multicast-auth-catalog] unknown mediaTrack "${track.mediaTrack}"`);
+		}
+		if (!catalogTrackNames.has(track.manifestTrack)) {
+			throw new Error(`[multicast-auth-catalog] unknown manifestTrack "${track.manifestTrack}"`);
+		}
+	}
+
+	return {
+		keyId: rawAuth.keyId,
+		acceptedPublicKeys: [
+			decodeEd25519PublicKey(rawAuth.publicKey),
+			...(rawAuth.previousKey === undefined ? [] : [decodeEd25519PublicKey(rawAuth.previousKey)]),
+		],
+		mode: resolveMulticastAuthMode(playerMode, rawAuth),
+		compaction: rawAuth.compaction,
+		tracks: rawAuth.tracks.map((track) => ({
+			...track,
+			authScope: decodeAuthScope(track.authScope),
+		})),
+	};
+}