@svta/cml-c2pa 1.0.0

package/NOTICE.md

@@ -0,0 +1,2 @@
+Streaming Video Technology Alliance Common Media Library Copyright (c) 2026
+Streaming Video Technology Alliance

package/README.md

@@ -0,0 +1,68 @@
+# @svta/cml-c2pa
+
+C2PA (Coalition for Content Provenance and Authenticity) live video validation for BMFF/MP4 containers.
+
+Supports both segment validation methods defined in the C2PA specification:
+
+- **§19.3 — Per-segment C2PA Manifest Box**: each segment embeds a full C2PA manifest with COSE signature
+- **§19.4 — Verifiable Segment Info (VSI/EMSG)**: the init segment carries the manifest and session keys; each media segment carries a lightweight signed EMSG box
+
+
+## Installation
+
+```bash
+npm i @svta/cml-c2pa
+```
+
+> **Note:** `@svta/cml-iso-bmff`, `@svta/cml-utils`, and `cbor-x` are peer dependencies. Most package managers install them automatically, but you may need to add them explicitly.
+
+> **Note:** This library uses the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) (`crypto.subtle`) for COSE signature verification and BMFF hash computation. In Node.js 20+ this is available globally. In browsers, `crypto.subtle` requires a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (HTTPS or `localhost`).
+
+## Usage
+
+### Manifest Box method (per-segment manifests)
+
+```typescript
+import { validateC2paManifestBoxSegment } from '@svta/cml-c2pa'
+import type { ManifestBoxValidationState } from '@svta/cml-c2pa'
+
+let lastManifestId: string | null = null
+let state: ManifestBoxValidationState | undefined
+
+for (const segmentUrl of segmentUrls) {
+  const bytes = new Uint8Array(await fetch(segmentUrl).then(r => r.arrayBuffer()))
+  const { result, nextManifestId, nextState } = await validateC2paManifestBoxSegment(
+    bytes,
+    lastManifestId,
+    state,
+  )
+  lastManifestId = nextManifestId
+  state = nextState
+
+  console.log(result.isValid, result.errorCodes)
+}
+```
+
+### VSI/EMSG method (init segment + media segments)
+
+```typescript
+import { validateC2paInitSegment, validateC2paSegment } from '@svta/cml-c2pa'
+
+const initBytes = new Uint8Array(await fetch(initUrl).then(r => r.arrayBuffer()))
+const init = await validateC2paInitSegment(initBytes)
+
+const segmentBytes = new Uint8Array(await fetch(segmentUrl).then(r => r.arrayBuffer()))
+const validated = await validateC2paSegment(segmentBytes, init.sessionKeys)
+```
+
+## Docs
+
+- [VSI/EMSG Validation](https://github.com/streaming-video-technology-alliance/common-media-library/blob/main/libs/c2pa/docs/vsi-validation.md) — Validate using Verifiable Segment Info (§19.4)
+- [Manifest Box Validation](https://github.com/streaming-video-technology-alliance/common-media-library/blob/main/libs/c2pa/docs/manifest-box-validation.md) — Validate using per-segment manifests (§19.3)
+- [Results and Error Codes](https://github.com/streaming-video-technology-alliance/common-media-library/blob/main/libs/c2pa/docs/results-and-error-codes.md) — Interpret results, error codes, and manifest data
+
+## References
+
+- [C2PA Specification v2.3](https://c2pa.org/specifications/specifications/2.3/specs/C2PA_Specification.html)
+- [JUMBF — ISO 19566-5](https://www.iso.org/standard/84635.html)
+- [COSE — RFC 9052](https://www.rfc-editor.org/rfc/rfc9052)

package/dist/index.d.ts

@@ -0,0 +1,339 @@
+import { ValueOf } from "@svta/cml-utils";
+
+//#region src/C2paAssertion.d.ts
+
+/**
+* A C2PA assertion within a manifest
+*
+* @public
+*/
+type C2paAssertion = {
+  readonly label: string;
+  readonly data: unknown;
+};
+//#endregion
+//#region src/C2paSignatureInfo.d.ts
+/**
+* Signature information extracted from a C2PA claim
+*
+* @public
+*/
+type C2paSignatureInfo = {
+  readonly issuer: string | null;
+  readonly certNotBefore: string | null;
+};
+//#endregion
+//#region src/C2paManifest.d.ts
+/**
+* A C2PA manifest (the active manifest within a manifest store)
+*
+* @public
+*/
+type C2paManifest = {
+  readonly label: string;
+  readonly instanceId: string | null;
+  readonly claimGenerator: string | null;
+  readonly signatureInfo: C2paSignatureInfo;
+  readonly assertions: readonly C2paAssertion[];
+};
+//#endregion
+//#region src/C2paStatusCode.d.ts
+/**
+* Standard C2PA validation status codes for manifest integrity checks,
+* as defined in the C2PA specification chapters 15 and 18.
+*
+* @see {@link https://c2pa.org/specifications/specifications/2.3/specs/C2PA_Specification.html#_claim_validation | C2PA Spec §15.10.3}
+*
+* @enum
+*
+* @public
+*/
+declare const C2paStatusCode: {
+  /** Assertion hash does not match the hashed URI in the claim (§15.10.3.1) */
+  readonly ASSERTION_HASHEDURI_MISMATCH: "assertion.hashedURI.mismatch";
+  /** An assertion referenced in the claim is missing from the assertion store (§15.10.3.1) */
+  readonly ASSERTION_MISSING: "assertion.missing";
+  /** An action requiring an ingredient reference does not have one (§18.15.4.7) */
+  readonly ASSERTION_ACTION_INGREDIENT_MISMATCH: "assertion.action.ingredientMismatch";
+  /** Claim signature verification failed (§15.7) */
+  readonly CLAIM_SIGNATURE_MISMATCH: "claim.signature.mismatch";
+};
+/**
+* Union type of all {@link (C2paStatusCode:variable)} values.
+*
+* @public
+*/
+type C2paStatusCode = ValueOf<typeof C2paStatusCode>;
+//#endregion
+//#region src/cose/CoseKeyJwk.d.ts
+/**
+* A JWK (JSON Web Key) representation of a COSE public key,
+* suitable for use with the WebCrypto `importKey` API.
+*
+* @public
+*/
+type CoseKeyJwk = {
+  readonly kty: string;
+  readonly crv: string;
+  readonly x: string;
+  readonly y?: string;
+};
+//#endregion
+//#region src/LiveVideoStatusCode.d.ts
+/**
+* Standard C2PA failure status codes for live video validation,
+* as defined in the C2PA specification section 19.7.
+*
+* @see {@link https://c2pa.org/specifications/specifications/2.3/specs/C2PA_Specification.html#_live_video_validation_process | C2PA Spec §19.7}
+*
+* @enum
+*
+* @public
+*/
+declare const LiveVideoStatusCode: {
+  /** Init segment contains an `mdat` box (§19.7.1) */
+  readonly INIT_INVALID: "livevideo.init.invalid";
+  /** C2PA Manifest Box failed standard validation (§19.7.1) */
+  readonly MANIFEST_INVALID: "livevideo.manifest.invalid";
+  /** Segment structure invalid: missing Manifest Box/emsg, signature/hash/key failure (§19.7) */
+  readonly SEGMENT_INVALID: "livevideo.segment.invalid";
+  /** Live video assertion field invalid: sequenceNumber or streamId mismatch (§19.7.2) */
+  readonly ASSERTION_INVALID: "livevideo.assertion.invalid";
+  /** continuityMethod absent, unsupported, or companion fields incorrect (§19.7.2) */
+  readonly CONTINUITY_METHOD_INVALID: "livevideo.continuityMethod.invalid";
+  /** Session key invalid: signerBinding failed or required fields absent (§19.7.3) */
+  readonly SESSIONKEY_INVALID: "livevideo.sessionkey.invalid";
+};
+/**
+* Union type of all {@link (LiveVideoStatusCode:variable)} values.
+*
+* @public
+*/
+type LiveVideoStatusCode = ValueOf<typeof LiveVideoStatusCode>;
+//#endregion
+//#region src/init/InitSegmentValidation.d.ts
+/**
+* A session key extracted and verified from a C2PA `c2pa.session-keys` assertion.
+*
+* Only keys whose signer binding is valid and whose validity period has not expired
+* are included in {@link InitSegmentValidation.sessionKeys}.
+*
+* @public
+*/
+type ValidatedSessionKey = {
+  readonly kid: string;
+  readonly jwk: CoseKeyJwk;
+  readonly minSequenceNumber: number;
+  readonly validityPeriod: number;
+  readonly createdAt: string;
+};
+/**
+* Result of validating a C2PA init segment.
+*
+* Returned by {@link validateC2paInitSegment}.
+*
+* @public
+*/
+type InitSegmentValidation = {
+  readonly manifest: C2paManifest | null;
+  readonly certificate: Uint8Array | null;
+  readonly manifestId: string | null;
+  readonly sessionKeys: readonly ValidatedSessionKey[];
+  readonly isValid: boolean;
+  readonly errorCodes: readonly (LiveVideoStatusCode | C2paStatusCode)[];
+};
+//#endregion
+//#region src/init/validateC2paInitSegment.d.ts
+/**
+* Validates a C2PA init segment: parses the manifest, extracts and verifies
+* the certificate, validates the BMFF hard binding hash, verifies all
+* session keys from the `c2pa.session-keys` assertion, and performs
+* manifest integrity checks (assertion hashes, missing assertions,
+* action ingredients, and claim signature verification).
+*
+* Only session keys with a valid signer binding and an unexpired validity period
+* are included in the result.
+*
+* @param bytes - Raw init segment bytes
+* @returns Structured validation result (with `INIT_INVALID` error code if `mdat` box is present)
+* @throws If no C2PA UUID box is found
+*
+* @example
+* {@includeCode ../../test/init/validateC2paInitSegment.test.ts#example}
+*
+* @public
+*/
+declare function validateC2paInitSegment(bytes: Uint8Array): Promise<InitSegmentValidation>;
+//#endregion
+//#region src/vsi/SequenceState.d.ts
+/**
+* State and result types for monotonic sequence number validation
+* per C2PA Live Streaming Specification §18.4.
+*
+* @public
+*/
+/**
+* Immutable state snapshot for a single stream's sequence number history.
+*
+* Pass to {@link validateC2paSegment} via the `sequenceState` parameter.
+*
+* @public
+*/
+type SequenceState = {
+  readonly lastSequenceNumber: number | null;
+  readonly seenSequences: ReadonlySet<number>;
+};
+/**
+* Reason codes for sequence number validation outcomes.
+*
+* @see {@link SequenceValidationResult}
+*
+* @enum
+*
+* @public
+*/
+declare const SequenceValidationReason: {
+  /** Sequence number is the next expected value */
+  readonly VALID: "valid";
+  /** Sequence number was already seen */
+  readonly DUPLICATE: "duplicate";
+  /** One or more sequence numbers were skipped */
+  readonly GAP_DETECTED: "gap_detected";
+  /** Sequence number is less than the last seen */
+  readonly OUT_OF_ORDER: "out_of_order";
+  /** Below the session key's minSequenceNumber */
+  readonly SEQUENCE_NUMBER_BELOW_MINIMUM: "sequence_number_below_minimum";
+};
+/**
+* Union type of all {@link (SequenceValidationReason:variable)} values.
+*
+* @public
+*/
+type SequenceValidationReason = ValueOf<typeof SequenceValidationReason>;
+/**
+* Result of validating a single sequence number against the current stream state.
+*
+* Discriminated on `reason` — narrow to `'gap_detected'` to access
+* `missingFrom` / `missingTo`.
+*
+* @public
+*/
+type SequenceValidationResult = {
+  readonly isValid: true;
+  readonly reason: typeof SequenceValidationReason.VALID;
+} | {
+  readonly isValid: false;
+  readonly reason: typeof SequenceValidationReason.SEQUENCE_NUMBER_BELOW_MINIMUM | typeof SequenceValidationReason.DUPLICATE | typeof SequenceValidationReason.OUT_OF_ORDER;
+} | {
+  readonly isValid: false;
+  readonly reason: typeof SequenceValidationReason.GAP_DETECTED;
+  readonly missingFrom: number;
+  readonly missingTo: number;
+};
+//#endregion
+//#region src/segment/SegmentValidation.d.ts
+/**
+* The result of validating a single C2PA live stream segment (VSI/EMSG method).
+*
+* Returned by {@link validateC2paSegment}.
+*
+* @public
+*/
+type SegmentValidationResult = {
+  readonly sequenceNumber: number;
+  readonly manifestId: string;
+  readonly bmffHashHex: string | null;
+  readonly kidHex: string | null;
+  readonly sequenceResult: SequenceValidationResult;
+  readonly isValid: boolean;
+  readonly errorCodes: readonly LiveVideoStatusCode[];
+};
+//#endregion
+//#region src/segment/validateC2paSegment.d.ts
+/**
+* Validates a C2PA live stream segment using the VSI/EMSG method (§19.7.3).
+*
+* Extracts the EMSG box, decodes the COSE_Sign1 and VSI map, matches the
+* session key by kid, then performs all cryptographic checks: signature
+* verification, BMFF content hash, sequence number floor, and key validity.
+*
+* Returns `null` if the segment does not contain a C2PA EMSG box.
+*
+* @param segmentBytes - Raw segment bytes
+* @param sessionKeys - Available session keys from the init segment
+* @param sequenceState - Current sequence state for this stream
+* @returns Validation result and updated sequence state, or `null` if no C2PA EMSG box
+*
+* @example
+* {@includeCode ../../test/segment/validateC2paSegment.test.ts#example}
+*
+* @public
+*/
+declare function validateC2paSegment(segmentBytes: Uint8Array, sessionKeys: readonly ValidatedSessionKey[], sequenceState?: SequenceState): Promise<{
+  readonly result: SegmentValidationResult;
+  readonly nextSequenceState: SequenceState;
+} | null>;
+//#endregion
+//#region src/manifestbox/ManifestBoxValidation.d.ts
+/**
+* The result of validating a single C2PA manifest-box live stream segment.
+*
+* Returned by {@link validateC2paManifestBoxSegment}.
+*
+* @public
+*/
+type ManifestBoxValidationResult = {
+  readonly manifest: C2paManifest | null;
+  readonly issuer: string | null;
+  readonly sequenceNumber: number | null;
+  readonly previousManifestId: string | null;
+  readonly streamId: string | null;
+  readonly continuityMethod: string | null;
+  readonly bmffHashHex: string | null;
+  readonly isValid: boolean;
+  readonly errorCodes: readonly (LiveVideoStatusCode | C2paStatusCode)[];
+};
+/**
+* State to carry between consecutive manifest-box segment validations.
+*
+* Pass the `nextState` returned by {@link validateC2paManifestBoxSegment}
+* into the next call to enable streamId, sequenceNumber, and continuity checks.
+*
+* @public
+*/
+type ManifestBoxValidationState = {
+  readonly lastStreamId?: string | null;
+  readonly lastSequenceNumber?: number | null;
+};
+//#endregion
+//#region src/manifestbox/validateC2paManifestBoxSegment.d.ts
+/**
+* Validates a C2PA manifest-box live stream segment.
+*
+* Parses the C2PA manifest embedded in the segment and validates per §19.7.1 and §19.7.2.
+* Recomputes the `c2pa.hash.bmff.v3` content hash from the raw segment bytes and compares
+* it against the expected hash in the manifest assertion. Checks live-video assertions
+* (sequenceNumber, streamId, continuityMethod) and manifest-ID chain continuity.
+*
+* This function is **pure** — it does not access any external state. The
+* caller is responsible for persisting `nextManifestId` and `nextState`
+* between calls.
+*
+* @param bytes - Raw segment bytes
+* @param lastManifestId - Manifest ID from the previous segment, or null for the first segment
+* @param state - Optional state from the previous segment for streamId/sequenceNumber checks
+* @returns Validation result, the manifest ID, and state to persist for the next call
+*
+* @example
+* {@includeCode ../../test/manifestbox/validateC2paManifestBoxSegment.test.ts#example}
+*
+* @public
+*/
+declare function validateC2paManifestBoxSegment(bytes: Uint8Array, lastManifestId: string | null, state?: ManifestBoxValidationState): Promise<{
+  readonly result: ManifestBoxValidationResult;
+  readonly nextManifestId: string | null;
+  readonly nextState: ManifestBoxValidationState;
+}>;
+//#endregion
+export { C2paAssertion, C2paManifest, C2paSignatureInfo, C2paStatusCode, CoseKeyJwk, InitSegmentValidation, LiveVideoStatusCode, ManifestBoxValidationResult, ManifestBoxValidationState, SegmentValidationResult, type SequenceState, SequenceValidationReason, type SequenceValidationResult, ValidatedSessionKey, validateC2paInitSegment, validateC2paManifestBoxSegment, validateC2paSegment };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/C2paAssertion.ts","../src/C2paSignatureInfo.ts","../src/C2paManifest.ts","../src/C2paStatusCode.ts","../src/cose/CoseKeyJwk.ts","../src/LiveVideoStatusCode.ts","../src/init/InitSegmentValidation.ts","../src/init/validateC2paInitSegment.ts","../src/vsi/SequenceState.ts","../src/segment/SegmentValidation.ts","../src/segment/validateC2paSegment.ts","../src/manifestbox/ManifestBoxValidation.ts","../src/manifestbox/validateC2paManifestBoxSegment.ts"],"sourcesContent":[],"mappings":"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"}