@sweberdev/witness 0.0.0-stage → 0.1.0

package/src/inflate.ts

@@ -0,0 +1,189 @@
+/**
+ * A small synchronous zlib inflater (RFC 1950/1951), enough to read compressed XMP from PNG
+ * zTXt and iTXt chunks in any JavaScript runtime. Based on the structure of tinf by
+ * Jørgen Ibsen (zlib licence).
+ */
+
+interface Tree {
+  counts: Uint16Array;
+  symbols: Uint16Array;
+}
+
+const LENGTH_BASE = [
+  3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 19, 23, 27, 31, 35, 43, 51, 59, 67, 83, 99, 115, 131,
+  163, 195, 227, 258,
+];
+const LENGTH_EXTRA = [
+  0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0,
+];
+const DIST_BASE = [
+  1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193, 257, 385, 513, 769, 1025, 1537, 2049,
+  3073, 4097, 6145, 8193, 12289, 16385, 24577,
+];
+const DIST_EXTRA = [
+  0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13,
+];
+const CODE_LENGTH_ORDER = [16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15];
+
+function buildTree(lengths: ArrayLike<number>, offset: number, count: number): Tree {
+  const tree: Tree = { counts: new Uint16Array(16), symbols: new Uint16Array(count) };
+  for (let i = 0; i < count; i++) {
+    const length = lengths[offset + i] ?? 0;
+    tree.counts[length] = (tree.counts[length] ?? 0) + 1;
+  }
+  tree.counts[0] = 0;
+  const offsets = new Uint16Array(16);
+  let sum = 0;
+  for (let i = 0; i < 16; i++) {
+    offsets[i] = sum;
+    sum += tree.counts[i] ?? 0;
+  }
+  for (let i = 0; i < count; i++) {
+    const length = lengths[offset + i] ?? 0;
+    if (length) {
+      const at = offsets[length] ?? 0;
+      tree.symbols[at] = i;
+      offsets[length] = at + 1;
+    }
+  }
+  return tree;
+}
+
+let fixed: { lit: Tree; dist: Tree } | null = null;
+function fixedTrees(): { lit: Tree; dist: Tree } {
+  if (!fixed) {
+    const lengths = new Uint8Array(288);
+    lengths.fill(8, 0, 144);
+    lengths.fill(9, 144, 256);
+    lengths.fill(7, 256, 280);
+    lengths.fill(8, 280, 288);
+    fixed = { lit: buildTree(lengths, 0, 288), dist: buildTree(new Uint8Array(30).fill(5), 0, 30) };
+  }
+  return fixed;
+}
+
+class Reader {
+  pos = 0;
+  bit = 0;
+  bits = 0;
+  constructor(readonly data: Uint8Array) {}
+
+  getBit(): number {
+    if (this.bits === 0) {
+      if (this.pos >= this.data.length) throw new Error("inflate: unexpected end of data");
+      this.bit = this.data[this.pos++] ?? 0;
+      this.bits = 8;
+    }
+    const value = this.bit & 1;
+    this.bit >>>= 1;
+    this.bits--;
+    return value;
+  }
+
+  read(count: number, base = 0): number {
+    let value = 0;
+    for (let i = 0; i < count; i++) value |= this.getBit() << i;
+    return value + base;
+  }
+
+  decode(tree: Tree): number {
+    let sum = 0;
+    let cur = 0;
+    let len = 0;
+    do {
+      cur = 2 * cur + this.getBit();
+      len++;
+      if (len > 15) throw new Error("inflate: invalid code");
+      sum += tree.counts[len] ?? 0;
+      cur -= tree.counts[len] ?? 0;
+    } while (cur >= 0);
+    return tree.symbols[sum + cur] ?? 0;
+  }
+}
+
+function dynamicTrees(r: Reader): { lit: Tree; dist: Tree } {
+  const hlit = r.read(5, 257);
+  const hdist = r.read(5, 1);
+  const hclen = r.read(4, 4);
+  const codeLengths = new Uint8Array(19);
+  for (let i = 0; i < hclen; i++) codeLengths[CODE_LENGTH_ORDER[i] ?? 0] = r.read(3);
+  const codeTree = buildTree(codeLengths, 0, 19);
+  const lengths = new Uint8Array(hlit + hdist);
+  for (let n = 0; n < hlit + hdist; ) {
+    const sym = r.decode(codeTree);
+    if (sym < 16) {
+      lengths[n++] = sym;
+      continue;
+    }
+    let repeat: number;
+    let value = 0;
+    if (sym === 16) {
+      if (n === 0) throw new Error("inflate: invalid repeat");
+      value = lengths[n - 1] ?? 0;
+      repeat = r.read(2, 3);
+    } else if (sym === 17) {
+      repeat = r.read(3, 3);
+    } else {
+      repeat = r.read(7, 11);
+    }
+    while (repeat-- > 0) lengths[n++] = value;
+  }
+  return { lit: buildTree(lengths, 0, hlit), dist: buildTree(lengths, hlit, hdist) };
+}
+
+/** Inflates zlib-wrapped data. Throws on corrupt input or when `maxLength` is exceeded. */
+export function inflateZlib(data: Uint8Array, maxLength = 16 * 1024 * 1024): Uint8Array {
+  if (
+    data.length < 2 ||
+    ((data[0] ?? 0) & 0x0f) !== 8 ||
+    (((data[0] ?? 0) << 8) | (data[1] ?? 0)) % 31 !== 0
+  ) {
+    throw new Error("inflate: not a zlib stream");
+  }
+  const r = new Reader(data);
+  r.pos = 2;
+  let out = new Uint8Array(Math.max(1024, data.length * 4));
+  let length = 0;
+  const push = (byte: number) => {
+    if (length >= out.length) {
+      if (out.length >= maxLength) throw new Error("inflate: output too large");
+      const next = new Uint8Array(Math.min(maxLength, out.length * 2));
+      next.set(out);
+      out = next;
+    }
+    out[length++] = byte;
+  };
+
+  let final = 0;
+  do {
+    final = r.getBit();
+    const type = r.read(2);
+    if (type === 0) {
+      r.bits = 0;
+      if (r.pos + 4 > data.length) throw new Error("inflate: unexpected end of data");
+      const len = (data[r.pos] ?? 0) | ((data[r.pos + 1] ?? 0) << 8);
+      r.pos += 4;
+      if (r.pos + len > data.length) throw new Error("inflate: unexpected end of data");
+      for (let i = 0; i < len; i++) push(data[r.pos++] ?? 0);
+    } else if (type === 1 || type === 2) {
+      const { lit, dist } = type === 1 ? fixedTrees() : dynamicTrees(r);
+      for (;;) {
+        const sym = r.decode(lit);
+        if (sym === 256) break;
+        if (sym < 256) {
+          push(sym);
+          continue;
+        }
+        const index = sym - 257;
+        const len = r.read(LENGTH_EXTRA[index] ?? 0, LENGTH_BASE[index] ?? 0);
+        const distSym = r.decode(dist);
+        const offset = r.read(DIST_EXTRA[distSym] ?? 0, DIST_BASE[distSym] ?? 0);
+        if (offset > length) throw new Error("inflate: invalid distance");
+        for (let i = 0; i < len; i++) push(out[length - offset] ?? 0);
+      }
+    } else {
+      throw new Error("inflate: invalid block type");
+    }
+  } while (!final);
+  return out.subarray(0, length);
+}

package/src/marking.ts

@@ -0,0 +1,237 @@
+import { format, getMessages } from "./i18n.js";
+import type { ContentKind, LocaleOverride, Marking, MarkingInput, SourceType } from "./types.js";
+
+const IPTC_BASE = "http://cv.iptc.org/newscodes/digitalsourcetype/";
+
+const SCHEMA_ORG: Record<SourceType, string> = {
+  trainedAlgorithmicMedia: "https://schema.org/TrainedAlgorithmicMediaDigitalSource",
+  compositeWithTrainedAlgorithmicMedia:
+    "https://schema.org/CompositeWithTrainedAlgorithmicMediaDigitalSource",
+  algorithmicallyEnhanced: "https://schema.org/AlgorithmicallyEnhancedDigitalSource",
+  algorithmicMedia: "https://schema.org/AlgorithmicMediaDigitalSource",
+  compositeSynthetic: "https://schema.org/CompositeSyntheticDigitalSource",
+};
+
+const DEFAULT_SOURCE: Record<ContentKind, SourceType> = {
+  generated: "trainedAlgorithmicMedia",
+  edited: "compositeWithTrainedAlgorithmicMedia",
+  deepfake: "trainedAlgorithmicMedia",
+};
+
+/** The IPTC Digital Source Type URI, e.g. for XMP or `data-ai-source-type`. */
+export function iptcSourceType(type: SourceType): string {
+  return IPTC_BASE + type;
+}
+
+/** The schema.org `IPTCDigitalSourceEnumeration` member for JSON-LD. */
+export function schemaOrgSourceType(type: SourceType): string {
+  return SCHEMA_ORG[type];
+}
+
+/** Reads a source type from an IPTC or schema.org URI, or from the bare name. */
+export function parseSourceType(value: string | null | undefined): SourceType | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  const name = trimmed.startsWith(IPTC_BASE) ? trimmed.slice(IPTC_BASE.length) : trimmed;
+  if (name in SCHEMA_ORG) return name as SourceType;
+  for (const [type, uri] of Object.entries(SCHEMA_ORG)) {
+    if (uri === trimmed) return type as SourceType;
+  }
+  return undefined;
+}
+
+/** True for source types that mean "made or changed by a trained AI model". */
+export function isAiSourceType(type: SourceType | undefined): boolean {
+  return (
+    type === "trainedAlgorithmicMedia" ||
+    type === "compositeWithTrainedAlgorithmicMedia" ||
+    type === "algorithmicallyEnhanced"
+  );
+}
+
+/** Applies defaults to a marking. */
+export function createMarking(input: MarkingInput = {}): Marking {
+  const kind = input.kind ?? "generated";
+  const createdAt =
+    input.createdAt instanceof Date
+      ? input.createdAt.toISOString()
+      : (input.createdAt ?? new Date().toISOString());
+  const marking: Marking = {
+    kind,
+    sourceType: input.sourceType ?? DEFAULT_SOURCE[kind],
+    createdAt,
+    humanReviewed: input.humanReviewed ?? false,
+  };
+  if (input.generator) marking.generator = input.generator;
+  if (input.generatorVersion) marking.generatorVersion = input.generatorVersion;
+  if (input.provider) marking.provider = input.provider;
+  if (input.disclosureUrl) marking.disclosureUrl = input.disclosureUrl;
+  if (input.description) marking.description = input.description;
+  return marking;
+}
+
+/**
+ * `data-*` attributes that mark an element's content as AI-generated. Spread them on the
+ * element that wraps the content.
+ */
+export function markingAttributes(input: Marking | MarkingInput): Record<string, string> {
+  const m = normalise(input);
+  const attributes: Record<string, string> = {
+    "data-ai-generated": "true",
+    "data-ai-kind": m.kind,
+    "data-ai-source-type": iptcSourceType(m.sourceType),
+    "data-ai-created": m.createdAt,
+  };
+  if (m.generator) attributes["data-ai-generator"] = generatorName(m);
+  if (m.provider) attributes["data-ai-provider"] = m.provider;
+  if (m.humanReviewed) attributes["data-ai-reviewed"] = "true";
+  return attributes;
+}
+
+/**
+ * Page-level `<meta>` tags for a page whose main content is AI-generated. There is no
+ * standardised meta tag yet, so these are a convention; pair them with {@link markingJsonLd}.
+ */
+export function markingMetaTags(
+  input: Marking | MarkingInput,
+): Array<{ name: string; content: string }> {
+  const m = normalise(input);
+  const tags = [
+    { name: "ai-generated", content: m.kind },
+    { name: "ai-source-type", content: iptcSourceType(m.sourceType) },
+  ];
+  if (m.generator) tags.push({ name: "ai-generator", content: generatorName(m) });
+  if (m.humanReviewed) tags.push({ name: "ai-reviewed", content: "true" });
+  return tags;
+}
+
+/** The meta tags as an HTML string. */
+export function renderMetaTags(input: Marking | MarkingInput): string {
+  return markingMetaTags(input)
+    .map((tag) => `<meta name="${escapeHtml(tag.name)}" content="${escapeHtml(tag.content)}">`)
+    .join("\n");
+}
+
+/** The meta tags in the shape of Next.js `metadata.other`. */
+export function nextMetadata(input: Marking | MarkingInput): { other: Record<string, string> } {
+  return {
+    other: Object.fromEntries(markingMetaTags(input).map((tag) => [tag.name, tag.content])),
+  };
+}
+
+/**
+ * schema.org JSON-LD for a creative work, with `digitalSourceType` set. Merge `extra` to add
+ * your own properties such as `headline` or `@type: "NewsArticle"`.
+ */
+export function markingJsonLd(
+  input: Marking | MarkingInput,
+  extra: Record<string, unknown> = {},
+): Record<string, unknown> {
+  const m = normalise(input);
+  const data: Record<string, unknown> = {
+    "@context": "https://schema.org",
+    "@type": "CreativeWork",
+    digitalSourceType: schemaOrgSourceType(m.sourceType),
+    dateCreated: m.createdAt,
+  };
+  if (m.generator) {
+    data.creator = {
+      "@type": "SoftwareApplication",
+      name: m.generator,
+      ...(m.generatorVersion ? { softwareVersion: m.generatorVersion } : {}),
+    };
+  }
+  if (m.provider) data.publisher = { "@type": "Organization", name: m.provider };
+  if (m.description) data.description = m.description;
+  return { ...data, ...extra };
+}
+
+/** The JSON-LD as a `<script type="application/ld+json">` tag. */
+export function renderJsonLd(
+  input: Marking | MarkingInput,
+  extra: Record<string, unknown> = {},
+): string {
+  const json = JSON.stringify(markingJsonLd(input, extra)).replace(/</g, "\\u003c");
+  return `<script type="application/ld+json">${json}</script>`;
+}
+
+export interface LabelHtmlOptions {
+  locale?: string | readonly string[];
+  messages?: LocaleOverride;
+  /** Where the visible label goes. Text should be labelled at the top. Default `top`. */
+  position?: "top" | "bottom";
+  /** Element that wraps label and content. Default `div`. */
+  tag?: "div" | "section" | "article" | "figure" | "aside";
+}
+
+/**
+ * Wraps server-rendered HTML in an element that carries the marking attributes and a visible
+ * label. Works without JavaScript; style it with `@sweberdev/witness/styles.css` or your own
+ * CSS for `.witness-label`.
+ */
+export function labelHtml(
+  html: string,
+  input: Marking | MarkingInput,
+  options: LabelHtmlOptions = {},
+): string {
+  const m = normalise(input);
+  const tag = options.tag ?? "div";
+  const attributes = Object.entries(markingAttributes(m))
+    .map(([name, value]) => ` ${name}="${escapeHtml(value)}"`)
+    .join("");
+  const label = renderLabelLine(m, options);
+  const body = options.position === "bottom" ? `${html}${label}` : `${label}${html}`;
+  return `<${tag} class="witness-content"${attributes}>${body}</${tag}>`;
+}
+
+/** One line of visible label text, e.g. "KI-generiert · Erzeugt mit Claude". */
+export function labelText(
+  input: Marking | MarkingInput,
+  options: Pick<LabelHtmlOptions, "locale" | "messages"> = {},
+): string {
+  const m = normalise(input);
+  const messages = getMessages(options.locale, options.messages);
+  const parts = [messages.kinds[m.kind].label];
+  if (m.generator) {
+    parts.push(format(messages.ui.generatedWith, { generator: generatorName(m) }));
+  }
+  if (m.humanReviewed) parts.push(messages.ui.humanReviewed);
+  return parts.join(" · ");
+}
+
+function renderLabelLine(m: Marking, options: LabelHtmlOptions): string {
+  const messages = getMessages(options.locale, options.messages);
+  const text = escapeHtml(labelText(m, options));
+  const link = m.disclosureUrl
+    ? ` <a class="witness-label__link" href="${escapeHtml(m.disclosureUrl)}">${escapeHtml(messages.ui.moreInfo)}</a>`
+    : "";
+  return `<p class="witness-label" role="note"><span class="witness-label__icon" aria-hidden="true">AI</span> <span class="witness-label__text">${text}</span>${link}</p>`;
+}
+
+/** "Model 1.2" when a version is known. */
+export function generatorName(m: Pick<Marking, "generator" | "generatorVersion">): string {
+  if (!m.generator) return "";
+  return m.generatorVersion ? `${m.generator} ${m.generatorVersion}` : m.generator;
+}
+
+function normalise(input: Marking | MarkingInput): Marking {
+  return isMarking(input) ? input : createMarking(input);
+}
+
+function isMarking(input: Marking | MarkingInput): input is Marking {
+  return (
+    typeof input.kind === "string" &&
+    typeof input.sourceType === "string" &&
+    typeof input.createdAt === "string" &&
+    typeof input.humanReviewed === "boolean"
+  );
+}
+
+export function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}

package/src/types.ts

@@ -0,0 +1,115 @@
+/**
+ * The transparency situations Article 50 of the EU AI Act describes.
+ *
+ * - `chatbot`: a person interacts directly with an AI system (Art. 50(1)).
+ * - `generated`: image, audio, video or text produced by an AI system (Art. 50(2) and 50(4)).
+ * - `edited`: existing content altered with an AI system (Art. 50(2) and 50(4)).
+ * - `deepfake`: generated or manipulated content that resembles real people, objects,
+ *   places or events and could falsely appear authentic (Art. 50(4)).
+ * - `emotion-recognition` and `biometric-categorisation`: people are exposed to such a
+ *   system (Art. 50(3)).
+ */
+export type DisclosureKind =
+  | "chatbot"
+  | "generated"
+  | "edited"
+  | "deepfake"
+  | "emotion-recognition"
+  | "biometric-categorisation";
+
+export const DISCLOSURE_KINDS: readonly DisclosureKind[] = [
+  "chatbot",
+  "generated",
+  "edited",
+  "deepfake",
+  "emotion-recognition",
+  "biometric-categorisation",
+];
+
+/** The kinds that describe a piece of content and can be written into a marking. */
+export type ContentKind = "generated" | "edited" | "deepfake";
+
+/**
+ * IPTC Digital Source Type values relevant to AI. See
+ * https://cv.iptc.org/newscodes/digitalsourcetype/
+ */
+export type SourceType =
+  | "trainedAlgorithmicMedia"
+  | "compositeWithTrainedAlgorithmicMedia"
+  | "algorithmicallyEnhanced"
+  | "algorithmicMedia"
+  | "compositeSynthetic";
+
+/** Wording for one disclosure kind in one language. */
+export interface DisclosureText {
+  /** Two or three words for a badge, e.g. "AI-generated". */
+  label: string;
+  /** One line for the heading of a notice. */
+  title: string;
+  /** One or two plain sentences that explain the label. */
+  body: string;
+}
+
+/** Interface strings shared by the notice and label components. */
+export interface UiText {
+  /** Button that collapses the chatbot notice. */
+  acknowledge: string;
+  /** Accessible name of the button that opens label details. */
+  details: string;
+  /** "Generated with {generator}". `{generator}` is replaced. */
+  generatedWith: string;
+  /** "Created on {date}". `{date}` is replaced. */
+  createdOn: string;
+  /** Shown when a person reviewed the content and took editorial responsibility. */
+  humanReviewed: string;
+  /** Link text to a page with more information. */
+  moreInfo: string;
+  /** Closes the details popover. */
+  close: string;
+}
+
+export interface LocaleMessages {
+  kinds: Record<DisclosureKind, DisclosureText>;
+  ui: UiText;
+}
+
+/** A partial override of a locale, e.g. to switch German to the informal "du". */
+export interface LocaleOverride {
+  kinds?: Partial<Record<DisclosureKind, Partial<DisclosureText>>>;
+  ui?: Partial<UiText>;
+}
+
+/** What a marking says about a piece of content. Input for {@link createMarking}. */
+export interface MarkingInput {
+  /** Defaults to `generated`. */
+  kind?: ContentKind;
+  /** Defaults from `kind`: `trainedAlgorithmicMedia`, or the composite type for `edited`. */
+  sourceType?: SourceType;
+  /** Name of the AI system or model, e.g. "gpt-image-2" or "Claude". */
+  generator?: string;
+  /** Version of the AI system, if known. */
+  generatorVersion?: string;
+  /** Who provides or operates the AI system, e.g. your company. */
+  provider?: string;
+  /** ISO 8601 timestamp. Defaults to now. */
+  createdAt?: string | Date;
+  /** A page that explains how and why you use AI. */
+  disclosureUrl?: string;
+  /** A person reviewed the content and holds editorial responsibility (Art. 50(4), text). */
+  humanReviewed?: boolean;
+  /** Free text, e.g. "Image generated from the prompt by the newsroom". */
+  description?: string;
+}
+
+/** A normalised marking with all defaults applied. */
+export interface Marking {
+  kind: ContentKind;
+  sourceType: SourceType;
+  generator?: string;
+  generatorVersion?: string;
+  provider?: string;
+  createdAt: string;
+  disclosureUrl?: string;
+  humanReviewed: boolean;
+  description?: string;
+}