@sweberdev/witness 0.0.0-stage → 0.1.1

package/dist/types-WWHzrNlc.d.cts

@@ -0,0 +1,90 @@
+/**
+ * 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)).
+ */
+type DisclosureKind = "chatbot" | "generated" | "edited" | "deepfake" | "emotion-recognition" | "biometric-categorisation";
+declare const DISCLOSURE_KINDS: readonly DisclosureKind[];
+/** The kinds that describe a piece of content and can be written into a marking. */
+type ContentKind = "generated" | "edited" | "deepfake";
+/**
+ * IPTC Digital Source Type values relevant to AI. See
+ * https://cv.iptc.org/newscodes/digitalsourcetype/
+ */
+type SourceType = "trainedAlgorithmicMedia" | "compositeWithTrainedAlgorithmicMedia" | "algorithmicallyEnhanced" | "algorithmicMedia" | "compositeSynthetic";
+/** Wording for one disclosure kind in one language. */
+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. */
+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;
+}
+interface LocaleMessages {
+    kinds: Record<DisclosureKind, DisclosureText>;
+    ui: UiText;
+}
+/** A partial override of a locale, e.g. to switch German to the informal "du". */
+interface LocaleOverride {
+    kinds?: Partial<Record<DisclosureKind, Partial<DisclosureText>>>;
+    ui?: Partial<UiText>;
+}
+/** What a marking says about a piece of content. Input for {@link createMarking}. */
+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. */
+interface Marking {
+    kind: ContentKind;
+    sourceType: SourceType;
+    generator?: string;
+    generatorVersion?: string;
+    provider?: string;
+    createdAt: string;
+    disclosureUrl?: string;
+    humanReviewed: boolean;
+    description?: string;
+}
+
+export { type ContentKind as C, type DisclosureKind as D, type LocaleOverride as L, type Marking as M, type SourceType as S, type UiText as U, type MarkingInput as a, type DisclosureText as b, type LocaleMessages as c, DISCLOSURE_KINDS as d };

package/dist/types-WWHzrNlc.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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)).
+ */
+type DisclosureKind = "chatbot" | "generated" | "edited" | "deepfake" | "emotion-recognition" | "biometric-categorisation";
+declare const DISCLOSURE_KINDS: readonly DisclosureKind[];
+/** The kinds that describe a piece of content and can be written into a marking. */
+type ContentKind = "generated" | "edited" | "deepfake";
+/**
+ * IPTC Digital Source Type values relevant to AI. See
+ * https://cv.iptc.org/newscodes/digitalsourcetype/
+ */
+type SourceType = "trainedAlgorithmicMedia" | "compositeWithTrainedAlgorithmicMedia" | "algorithmicallyEnhanced" | "algorithmicMedia" | "compositeSynthetic";
+/** Wording for one disclosure kind in one language. */
+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. */
+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;
+}
+interface LocaleMessages {
+    kinds: Record<DisclosureKind, DisclosureText>;
+    ui: UiText;
+}
+/** A partial override of a locale, e.g. to switch German to the informal "du". */
+interface LocaleOverride {
+    kinds?: Partial<Record<DisclosureKind, Partial<DisclosureText>>>;
+    ui?: Partial<UiText>;
+}
+/** What a marking says about a piece of content. Input for {@link createMarking}. */
+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. */
+interface Marking {
+    kind: ContentKind;
+    sourceType: SourceType;
+    generator?: string;
+    generatorVersion?: string;
+    provider?: string;
+    createdAt: string;
+    disclosureUrl?: string;
+    humanReviewed: boolean;
+    description?: string;
+}
+
+export { type ContentKind as C, type DisclosureKind as D, type LocaleOverride as L, type Marking as M, type SourceType as S, type UiText as U, type MarkingInput as a, type DisclosureText as b, type LocaleMessages as c, DISCLOSURE_KINDS as d };

package/package.json

@@ -1,6 +1,126 @@
 {
   "name": "@sweberdev/witness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "AI transparency kit for Article 50 of the EU AI Act: chatbot notices, AI labels in DE/EN/FR/IT, IPTC/XMP marking for images, an invisible text watermark and Vercel AI SDK middleware.",
+  "license": "MIT",
+  "author": "Seya Weber (https://github.com/sxwxbxr)",
+  "homepage": "https://packages.sweber.dev/witness/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Weber-Development/witness.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/Weber-Development/witness/issues"
+  },
+  "type": "module",
+  "sideEffects": [
+    "./dist/elements-auto.js",
+    "./dist/elements-auto.cjs",
+    "./src/elements-auto.ts",
+    "./styles.css"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./elements": {
+      "import": {
+        "types": "./dist/elements-auto.d.ts",
+        "default": "./dist/elements-auto.js"
+      },
+      "require": {
+        "types": "./dist/elements-auto.d.cts",
+        "default": "./dist/elements-auto.cjs"
+      }
+    },
+    "./elements/define": {
+      "import": {
+        "types": "./dist/elements.d.ts",
+        "default": "./dist/elements.js"
+      },
+      "require": {
+        "types": "./dist/elements.d.cts",
+        "default": "./dist/elements.cjs"
+      }
+    },
+    "./ai-sdk": {
+      "import": {
+        "types": "./dist/ai-sdk.d.ts",
+        "default": "./dist/ai-sdk.js"
+      },
+      "require": {
+        "types": "./dist/ai-sdk.d.cts",
+        "default": "./dist/ai-sdk.cjs"
+      }
+    },
+    "./cli": {
+      "import": {
+        "types": "./dist/cli.d.ts",
+        "default": "./dist/cli.js"
+      },
+      "require": {
+        "types": "./dist/cli.d.cts",
+        "default": "./dist/cli.cjs"
+      }
+    },
+    "./styles.css": "./styles.css",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "witness": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "styles.css",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai-act",
+    "eu-ai-act",
+    "article-50",
+    "ai-transparency",
+    "ai-label",
+    "ai-disclosure",
+    "chatbot",
+    "watermark",
+    "xmp",
+    "iptc",
+    "digital-source-type",
+    "vercel-ai-sdk",
+    "web-component"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "ai": "^7.0.127",
+    "jsdom": "^27.0.0",
+    "sharp": "^0.35.5",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.0",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }

package/src/ai-sdk.ts

@@ -0,0 +1,252 @@
+/**
+ * Middleware for the Vercel AI SDK (`ai` 5, 6 and 7). It marks what a model produces:
+ *
+ * - `witnessMiddleware` appends the invisible text watermark to every text part, for
+ *   `generateText` and `streamText`, and adds `providerMetadata.witness`.
+ * - `witnessImageMiddleware` writes XMP with the IPTC Digital Source Type into every image
+ *   from `generateImage`.
+ *
+ * The types are structural, so this module has no dependency on `ai`.
+ */
+
+import { type MarkImageOptions, markImage } from "./image.js";
+import { createMarking, iptcSourceType } from "./marking.js";
+import type { ContentKind, Marking } from "./types.js";
+import { watermarkSuffix, watermarkText } from "./watermark.js";
+
+type SpecVersion = "v2" | "v3" | "v4";
+
+interface ModelInfo {
+  provider: string;
+  modelId: string;
+}
+
+export interface WitnessMarkedEvent {
+  type: "text" | "image";
+  marking: Marking;
+  /** For text: the id of the text part in a stream, if any. */
+  partId?: string;
+  /** For images: what happened to each image. */
+  status?: string;
+}
+
+export interface WitnessMiddlewareOptions {
+  /**
+   * The AI SDK middleware specification. `v4` for `ai` 7 (default), `v3` for `ai` 6, `v2`
+   * for `ai` 5.
+   */
+  specificationVersion?: SpecVersion;
+  /** Name written into the marking. Default: `provider/modelId` of the wrapped model. */
+  generator?: string | ((model: ModelInfo) => string);
+  /** Default `generated`. */
+  kind?: ContentKind;
+  /** Your company or product, written into the marking. */
+  provider?: string;
+  /** Append the invisible text watermark. Default `true`. */
+  watermark?: boolean;
+  /** A reference written into the watermark, e.g. a log id. */
+  id?: () => string;
+  /** Called once per marked text part or image, e.g. to write an audit log entry. */
+  onMarked?: (event: WitnessMarkedEvent) => void;
+}
+
+interface TextPart {
+  type: string;
+  text?: string;
+}
+
+interface GenerateResult {
+  content: TextPart[];
+  providerMetadata?: Record<string, unknown>;
+}
+
+interface StreamPart {
+  type: string;
+  id?: string;
+  delta?: string;
+  providerMetadata?: Record<string, unknown>;
+}
+
+interface StreamResult {
+  stream: ReadableStream<StreamPart>;
+}
+
+/** The `witness` entry added to `providerMetadata`. */
+export function witnessProviderMetadata(marking: Marking): Record<string, string | boolean> {
+  return {
+    aiGenerated: true,
+    kind: marking.kind,
+    sourceType: iptcSourceType(marking.sourceType),
+    createdAt: marking.createdAt,
+    ...(marking.generator ? { generator: marking.generator } : {}),
+    ...(marking.provider ? { provider: marking.provider } : {}),
+  };
+}
+
+/** Language model middleware. Pass it to `wrapLanguageModel`. */
+export function witnessMiddleware(options: WitnessMiddlewareOptions = {}) {
+  const watermark = options.watermark ?? true;
+
+  const markingFor = (model: ModelInfo): Marking =>
+    createMarking({
+      kind: options.kind ?? "generated",
+      generator: generatorFor(options.generator, model),
+      ...(options.provider ? { provider: options.provider } : {}),
+    });
+
+  const watermarkFor = (marking: Marking) => ({
+    ...(marking.generator ? { generator: marking.generator } : {}),
+    createdAt: marking.createdAt,
+    ...(options.id ? { id: options.id() } : {}),
+  });
+
+  return {
+    specificationVersion: options.specificationVersion ?? "v4",
+
+    async wrapGenerate<R extends GenerateResult>({
+      doGenerate,
+      model,
+    }: {
+      doGenerate: () => PromiseLike<R>;
+      model: ModelInfo;
+    }): Promise<R> {
+      const result = await doGenerate();
+      const marking = markingFor(model);
+      const content = result.content.map((part) => {
+        if (part.type !== "text" || typeof part.text !== "string" || part.text.length === 0) {
+          return part;
+        }
+        options.onMarked?.({ type: "text", marking });
+        return watermark
+          ? { ...part, text: watermarkText(part.text, watermarkFor(marking)) }
+          : part;
+      });
+      return {
+        ...result,
+        content,
+        providerMetadata: { ...result.providerMetadata, witness: witnessProviderMetadata(marking) },
+      };
+    },
+
+    async wrapStream<R extends StreamResult>({
+      doStream,
+      model,
+    }: {
+      doStream: () => PromiseLike<R>;
+      model: ModelInfo;
+    }): Promise<R> {
+      const result = await doStream();
+      const marking = markingFor(model);
+      const withText = new Set<string>();
+      const transform = new TransformStream<StreamPart, StreamPart>({
+        transform(part, controller) {
+          const id = part.id ?? "";
+          if (
+            part.type === "text-delta" &&
+            typeof part.delta === "string" &&
+            part.delta.length > 0
+          ) {
+            withText.add(id);
+          }
+          if (part.type === "text-end" && withText.has(id)) {
+            withText.delete(id);
+            options.onMarked?.({ type: "text", marking, partId: id });
+            if (watermark) {
+              controller.enqueue({
+                type: "text-delta",
+                id,
+                delta: watermarkSuffix(watermarkFor(marking)),
+              });
+            }
+          }
+          if (part.type === "finish") {
+            controller.enqueue({
+              ...part,
+              providerMetadata: {
+                ...part.providerMetadata,
+                witness: witnessProviderMetadata(marking),
+              },
+            });
+            return;
+          }
+          controller.enqueue(part);
+        },
+      });
+      return { ...result, stream: result.stream.pipeThrough(transform) };
+    },
+  };
+}
+
+export interface WitnessImageMiddlewareOptions
+  extends Pick<WitnessMiddlewareOptions, "generator" | "kind" | "provider" | "onMarked">,
+    MarkImageOptions {
+  /** `v4` for `ai` 7 (default), `v3` for `ai` 6. */
+  specificationVersion?: "v3" | "v4";
+}
+
+interface ImageResult {
+  images: string[] | Uint8Array[];
+  warnings: unknown[];
+}
+
+/** Image model middleware. Pass it to `wrapImageModel`. */
+export function witnessImageMiddleware(options: WitnessImageMiddlewareOptions = {}) {
+  return {
+    specificationVersion: options.specificationVersion ?? "v4",
+
+    async wrapGenerate<R extends ImageResult>({
+      doGenerate,
+      model,
+    }: {
+      doGenerate: () => PromiseLike<R>;
+      model: ModelInfo;
+    }): Promise<R> {
+      const result = await doGenerate();
+      const marking = createMarking({
+        kind: options.kind ?? "generated",
+        generator: generatorFor(options.generator, model),
+        ...(options.provider ? { provider: options.provider } : {}),
+      });
+      const warnings = [...result.warnings];
+      const markOne = (bytes: Uint8Array): Uint8Array => {
+        const marked = markImage(bytes, marking, options.c2pa ? { c2pa: options.c2pa } : {});
+        options.onMarked?.({ type: "image", marking, status: marked.status });
+        if (marked.status !== "marked") {
+          warnings.push({
+            type: "other",
+            message:
+              marked.status === "skipped-c2pa"
+                ? "Witness: image already carries a C2PA manifest and was left unchanged."
+                : "Witness: image format not supported (PNG, JPEG, WebP); image is not marked.",
+          });
+        }
+        return marked.bytes;
+      };
+      const images = result.images.map((image: string | Uint8Array) =>
+        typeof image === "string" ? toBase64(markOne(fromBase64(image))) : markOne(image),
+      ) as R["images"];
+      return { ...result, images, warnings };
+    },
+  };
+}
+
+function generatorFor(option: WitnessMiddlewareOptions["generator"], model: ModelInfo): string {
+  if (typeof option === "function") return option(model);
+  return option ?? `${model.provider}/${model.modelId}`;
+}
+
+function fromBase64(value: string): Uint8Array {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+function toBase64(bytes: Uint8Array): string {
+  let binary = "";
+  const step = 0x8000;
+  for (let i = 0; i < bytes.length; i += step) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + step));
+  }
+  return btoa(binary);
+}

package/src/bin.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+
+runCli(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+});