feat(provenance): badge what a media file declares about how it was made (#83)

Adds @tronbrowser/provenance. Reads C2PA manifests, the IPTC
DigitalSourceType field and generator hints out of images and video, and
badges the findings on the page.

Local by default, because the alternative is telemetry. The only network
traffic a scan causes is a re-request for an image the page already
loaded, to the origin that already served it, normally answered from
cache — Range-limited, force-cache, same-origin credentials. No third
party learns anything. Asking one is a separate function that is off by
default and throws RemoteLookupDisabledError rather than silently
proceeding; there is no configuration that makes it quietly on, and the
opt-in check runs before the URL is touched so a misconfigured caller
cannot leak on the way to discovering it was disabled.

What the badge refuses to say matters more than what it says:

- There is no "authentic" or "verified real" state, because nothing here
  can establish that. The strongest positive claim available is "the file
  says it was captured by a camera", and that is what it says.
- Absence is never rendered as reassurance. Most sites strip metadata, so
  a bare file is equally common for real photographs and AI output.
- A generator name is a hint, never a verdict, and never shows unprompted.
  Editors write their own name into the same fields, so surfacing it would
  train people to read "opened in Firefly" as "fake".
- signatureVerified is typed as the literal false, so presence can never
  drift into implying validity.
- SynthID is never checked and every report says so.

Only findings that say something are drawn without being asked. Badging
every image on a page produces noise people learn to ignore, which is
worse than no badge, so the quiet ones are available via showAll.

Scans are bounded (40 elements, 96px floor) so a thumbnail gallery does
not become hundreds of range requests. Badges are inserted as siblings —
img and video cannot hold children, and appending to them silently does
nothing — and carry the caveat in aria-label rather than a hover-only
title.

59 tests, including assertions on what is fetched, not just what renders.
Full workspace suite green.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ralyodio

packages/provenance/README.md

@@ -0,0 +1,62 @@
+# @tronbrowser/provenance
+
+Reads what a media file declares about how it was made, and badges it on the page.
+
+## What it does
+
+Reads three things out of the bytes of an image or video:
+
+- **C2PA manifests** — JPEG APP11/JUMBF, PNG `caBX`, WebP `C2PA`, ISO-BMFF
+- **IPTC `DigitalSourceType`** — the standard vocabulary (`trainedAlgorithmicMedia`, `digitalCapture`, …)
+- **Generator names** left in XMP by Midjourney, DALL·E, Firefly, Imagen, Veo and others
+
+## Local by default
+
+The only network traffic a scan causes is a re-request for an image the page **already loaded**, to the origin that **already served it**, normally answered from cache. No third party learns anything.
+
+That is not incidental — it is why this is a browser feature rather than a call to somebody's API. Badging every image on every page by asking a remote service would be telemetry on the user's entire browsing session.
+
+Asking a third party is available, but it is a separate function, off by default, and it throws rather than silently proceeding if the user has not opted in:
+
+```ts
+import { lookupRemote, RemoteLookupDisabledError } from '@tronbrowser/provenance';
+
+// Throws RemoteLookupDisabledError — there is no config that makes this silently on
+await lookupRemote(url, { enabled: false, apiKey: '' });
+```
+
+## What it will not claim
+
+There is deliberately **no "authentic" or "verified real" badge.** Nothing here can establish that. The strongest positive statement available is *"the file says it was captured by a camera"*, and that is exactly what the badge says.
+
+Three rules the tests enforce:
+
+1. **Absence proves nothing.** Most sites strip metadata on upload, so a bare file is equally common for real photographs and AI output. "No provenance" is never rendered as "probably real".
+2. **Self-declaration is not proof.** Only C2PA is signed, and even then this reports its *presence* — validating the certificate chain needs a trust list and is a separate job. `signatureVerified` is typed as the literal `false` so it cannot drift.
+3. **A generator name is a hint, not a verdict.** Image editors write their own name into the same fields, so "opened in Firefly" and "made by Firefly" are indistinguishable there. It never triggers an AI badge, and never shows unprompted.
+
+**SynthID is never checked**, and every report says so rather than staying quiet about it — Google's watermarks are verified by its own service, not from a file's bytes.
+
+## Usage
+
+```ts
+import { scanMedia } from '@tronbrowser/provenance';
+
+const result = await scanMedia();
+// { examined: 12, badged: 2, skipped: 1 }
+```
+
+Only findings that actually say something are drawn unprompted. Most images on most pages have no provenance at all, and badging all of them is noise people learn to ignore — which is worse than no badge. Pass `showAll: true` for the on-demand view.
+
+Scans are bounded (`maxElements`, default 40) and skip anything under `minSize` (default 96px), so a gallery of thumbnails does not turn into hundreds of range requests.
+
+## Reading one file directly
+
+```ts
+import { readProvenance, toBadge } from '@tronbrowser/provenance';
+
+const report = readProvenance(bytes);
+const badge = toBadge(report);
+```
+
+`readProvenance` is pure and has no DOM or Node dependencies — it runs in a content script, a worker, or a test.

packages/provenance/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@tronbrowser/provenance",
+  "version": "3.8.8",
+  "private": true,
+  "description": "Reads what a media file declares about how it was made, locally, and badges it on the page",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src"
+  },
+  "devDependencies": {
+    "happy-dom": "^20.10.6",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  }
+}

packages/provenance/src/badge.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest';
+
+import { shouldDisplay, toBadge } from './badge.js';
+import { readProvenance } from './read.js';
+
+/**
+ * The badge is the only part of this package a user ever sees, so the wording
+ * is the part that can mislead. These tests are mostly about what it refuses
+ * to say: there is no "authentic" state, absence never reads as real, and a
+ * tool name never becomes an accusation.
+ */
+
+/** Builds bytes from literal bytes and ASCII strings. */
+function bytes(...parts: (number[] | string)[]): Uint8Array {
+  const out: number[] = [];
+  for (const part of parts) {
+    if (typeof part === 'string') {
+      for (let i = 0; i < part.length; i += 1) out.push(part.charCodeAt(i));
+    } else {
+      out.push(...part);
+    }
+  }
+  return new Uint8Array(out);
+}
+
+const JPEG = [0xff, 0xd8, 0xff, 0xe0];
+const PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+function xmp(inner: string): string {
+  return `<x:xmpmeta xmlns:x="adobe:ns:meta/">${inner}</x:xmpmeta>`;
+}
+
+function sourceType(term: string): string {
+  return xmp(
+    `<rdf:Description Iptc4xmpExt:DigitalSourceType="http://cv.iptc.org/newscodes/digitalsourcetype/${term}"/>`,
+  );
+}
+
+describe('what the badge says', () => {
+  it('calls a declared generative file AI-generated, and shows it unprompted', () => {
+    const badge = toBadge(readProvenance(bytes(JPEG, sourceType('trainedAlgorithmicMedia'))));
+
+    expect(badge.kind).toBe('ai');
+    expect(badge.label).toBe('AI-generated');
+    expect(badge.prominent).toBe(true);
+  });
+
+  it('reports a camera claim as a claim, not as authenticity', () => {
+    const badge = toBadge(readProvenance(bytes(JPEG, sourceType('digitalCapture'))));
+
+    expect(badge.kind).toBe('camera');
+    expect(badge.label).toBe('Camera capture');
+    // Nothing here can establish a photo is genuine, so nothing says so.
+    expect(badge.label).not.toMatch(/authentic|verified|genuine|real/i);
+    expect(badge.detail).toMatch(/not a signature/i);
+  });
+
+  it('does not interrupt the page for an unsigned camera claim', () => {
+    const unsigned = toBadge(readProvenance(bytes(JPEG, sourceType('digitalCapture'))));
+    const signed = toBadge(readProvenance(bytes(PNG, 'caBX', sourceType('digitalCapture'))));
+
+    expect(unsigned.prominent).toBe(false);
+    expect(signed.prominent).toBe(true);
+  });
+
+  it('reports a manifest that declares nothing as exactly that', () => {
+    const badge = toBadge(readProvenance(bytes(PNG, 'caBX', 'manifest')));
+
+    expect(badge.kind).toBe('signed');
+    expect(badge.detail).toMatch(/does not declare how it was made/i);
+    expect(badge.prominent).toBe(true);
+  });
+
+  it('treats a generator name as a hint and keeps it off the page', () => {
+    const badge = toBadge(readProvenance(bytes(JPEG, xmp('<xmp:CreatorTool>Midjourney</xmp:CreatorTool>'))));
+
+    expect(badge.kind).toBe('hint');
+    expect(badge.label).toBe('Possible AI tool');
+    // "Opened in Firefly" must not train people to read the badge as "fake".
+    expect(badge.prominent).toBe(false);
+  });
+
+  it('never turns a bare file into a claim about it', () => {
+    const badge = toBadge(readProvenance(bytes(JPEG, 'ordinary pixels')));
+
+    expect(badge.kind).toBe('unknown');
+    expect(badge.prominent).toBe(false);
+    expect(badge.detail).toMatch(/not evidence either way/i);
+  });
+
+  it('attaches the report caveats to every badge', () => {
+    const samples = [
+      bytes(JPEG, sourceType('trainedAlgorithmicMedia')),
+      bytes(JPEG, sourceType('digitalCapture')),
+      bytes(PNG, 'caBX'),
+      bytes(JPEG, xmp('<xmp:CreatorTool>Midjourney</xmp:CreatorTool>')),
+      bytes(JPEG, 'nothing'),
+    ];
+
+    for (const sample of samples) {
+      const report = readProvenance(sample);
+      const badge = toBadge(report);
+      // The caveat is what stops the badge overclaiming, so it is never optional.
+      for (const note of report.notes) expect(badge.detail).toContain(note);
+    }
+  });
+
+  it('never labels anything as verified', () => {
+    const samples = [
+      bytes(PNG, 'caBX', sourceType('digitalCapture')),
+      bytes(PNG, 'caBX'),
+      bytes(JPEG, sourceType('digitalCapture')),
+    ];
+
+    for (const sample of samples) {
+      expect(toBadge(readProvenance(sample)).label).not.toMatch(/verified|authentic/i);
+    }
+  });
+});
+
+describe('shouldDisplay', () => {
+  it('draws findings that say something and holds back the rest', () => {
+    const ai = toBadge(readProvenance(bytes(JPEG, sourceType('trainedAlgorithmicMedia'))));
+    const nothing = toBadge(readProvenance(bytes(JPEG, 'plain')));
+    const hint = toBadge(readProvenance(bytes(JPEG, xmp('<x>Midjourney</x>'))));
+
+    expect(shouldDisplay(ai)).toBe(true);
+    expect(shouldDisplay(nothing)).toBe(false);
+    expect(shouldDisplay(hint)).toBe(false);
+  });
+});

packages/provenance/src/badge.ts

@@ -0,0 +1,130 @@
+/**
+ * Turning a provenance report into what the user actually sees.
+ *
+ * Pure: report in, presentation out. Kept separate from the DOM work so the
+ * wording — the part that can mislead someone — is testable on its own.
+ *
+ * The hard rule is that the badge never asserts more than the file does. There
+ * is deliberately no "authentic" or "real photo" state, because nothing here
+ * can establish that. The strongest positive claim available is "the file says
+ * it was captured by a camera", and the badge says exactly that.
+ */
+
+import type { ProvenanceReport } from './read.js';
+
+/**
+ * What the badge is telling the user.
+ *
+ * `ai` — the file declares generative origin.
+ * `camera` — the file declares camera capture.
+ * `signed` — a manifest is present but says neither.
+ * `hint` — a generator name, too weak to call.
+ * `unknown` — nothing found. Shown only on request, never volunteered.
+ */
+export type BadgeKind = 'ai' | 'camera' | 'signed' | 'hint' | 'unknown';
+
+export interface Badge {
+  readonly kind: BadgeKind;
+  /** Short text on the badge itself. */
+  readonly label: string;
+  /** The longer explanation, shown on hover or focus. */
+  readonly detail: string;
+  /** True when the badge should appear without the user asking. */
+  readonly prominent: boolean;
+}
+
+/** Wording for each state, in one place so it can be reviewed as a set. */
+const LABELS: Readonly<Record<BadgeKind, string>> = {
+  ai: 'AI-generated',
+  camera: 'Camera capture',
+  signed: 'Signed provenance',
+  hint: 'Possible AI tool',
+  unknown: 'No provenance',
+};
+
+/**
+ * Maps a report onto a badge.
+ *
+ * @param report - What the file declared
+ * @returns The badge to show
+ */
+export function toBadge(report: ProvenanceReport): Badge {
+  if (report.declaredAiGenerated === true) {
+    return {
+      kind: 'ai',
+      label: LABELS.ai,
+      detail: qualify(report, report.digitalSourceTypeLabel ?? 'The file declares generative origin.'),
+      prominent: true,
+    };
+  }
+
+  if (report.declaredAiGenerated === false) {
+    return {
+      kind: 'camera',
+      label: LABELS.camera,
+      detail: qualify(report, report.digitalSourceTypeLabel ?? 'The file declares camera capture.'),
+      // A capture claim is worth showing when signed, and not worth
+      // interrupting the page for when it is a bare editable field.
+      prominent: report.strength === 'signed',
+    };
+  }
+
+  if (report.c2pa.present) {
+    return {
+      kind: 'signed',
+      label: LABELS.signed,
+      detail: qualify(
+        report,
+        'This file carries a C2PA manifest but does not declare how it was made.',
+      ),
+      prominent: true,
+    };
+  }
+
+  if (report.generators.length > 0) {
+    return {
+      kind: 'hint',
+      label: LABELS.hint,
+      detail: qualify(report, `Metadata mentions ${report.generators.join(', ')}.`),
+      // A tool name is not a finding. Surfacing it unprompted would train
+      // people to read "opened in Firefly" as "fake".
+      prominent: false,
+    };
+  }
+
+  return {
+    kind: 'unknown',
+    label: LABELS.unknown,
+    detail: qualify(report, 'This file carries no provenance metadata.'),
+    prominent: false,
+  };
+}
+
+/**
+ * Appends the report's own caveats to a summary.
+ *
+ * The caveat is not optional garnish — it is the part that stops a badge from
+ * overclaiming — so it is attached here rather than left to each caller.
+ *
+ * @param report - The report the badge came from
+ * @param summary - The one-line summary
+ * @returns Summary plus caveats
+ */
+function qualify(report: ProvenanceReport, summary: string): string {
+  return [summary, ...report.notes].join(' ');
+}
+
+/**
+ * Whether a badge should be drawn on the page without being asked for.
+ *
+ * Most images on most pages have no provenance at all. Badging every one of
+ * them would be noise that people learn to ignore, which is worse than no
+ * badge — so only findings that say something get drawn, and the rest are
+ * available on demand.
+ *
+ * @param badge - The badge in question
+ * @returns True when it should be shown unprompted
+ */
+export function shouldDisplay(badge: Badge): boolean {
+  return badge.prominent;
+}

packages/provenance/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * `@tronbrowser/provenance` — what a file declares about how it was made.
+ *
+ * Local by default: everything the badge shows is read from bytes the browser
+ * already has. Asking a third party is a separate, opt-in feature.
+ */
+
+export {
+  readProvenance,
+  detectC2pa,
+  detectContainer,
+  extractXmp,
+  readDigitalSourceType,
+  readGenerators,
+  indexOfAscii,
+  DIGITAL_SOURCE_TYPES,
+  SCAN_BYTES,
+  type C2paFinding,
+  type MediaContainer,
+  type ProvenanceReport,
+  type ProvenanceSignal,
+  type ProvenanceStrength,
+} from './read.js';
+
+export { toBadge, shouldDisplay, type Badge, type BadgeKind } from './badge.js';
+
+export {
+  scanMedia,
+  inspect,
+  fetchHead,
+  mediaUrl,
+  attachBadge,
+  SCANNED_ATTRIBUTE,
+  type ScanOptions,
+  type ScanResult,
+} from './scan.js';
+
+export {
+  lookupRemote,
+  RemoteLookupDisabledError,
+  REMOTE_LOOKUP_DISCLOSURE,
+  type RemoteLookupConfig,
+  type RemoteVerdict,
+} from './remote.js';