@michaelthielemann/kestrel 2.0.0 → 2.1.0

package/layers/media/app/components/MediaLibrary.vue

@@ -51,18 +51,20 @@ function onOpenItem(item: LibraryItem) {
   viewerError.value = ''
   viewerOpen.value = true
 }
-async function onSaveAlt(alt: string) {
+async function onSaveMeta(alt: string, ai?: { aiSourceType: string | null; aiNote: string | null }) {
   const f = viewerFile.value as LibraryFileRow | null
   if (!f) return
   viewerBusy.value = true
   viewerError.value = ''
   try {
     // Alt lives in the per-locale translations JSON; write the primary locale (the library resolves
-    // alt in that same locale, so this round-trips into the list). The precondition header lets the
-    // server 409 instead of silently losing a concurrent edit from another open viewer tab.
+    // alt in that same locale, so this round-trips into the list). The AI disclosure is NOT per-locale,
+    // so it rides alongside as top-level keys — and only when the viewer actually offered it, so a save
+    // from a consumer with the feature off never clears a recorded disclosure. The precondition header
+    // lets the server 409 instead of silently losing a concurrent edit from another open viewer tab.
     await $fetch(`/api/media/${f.id}`, {
       method: 'PATCH',
-      body: { translations: { [primary]: { alt } } },
+      body: { translations: { [primary]: { alt } }, ...(ai ?? {}) },
       ...(f.updatedAt ? { headers: { 'x-kestrel-if-unmodified-since': String(new Date(f.updatedAt).getTime()) } } : {}),
     })
   } catch (e) {
@@ -336,7 +338,7 @@ const localizedMenu = computed(() => menuItems.value.map((s) => ({
       @update:open="(v) => { if (!v) upload.resolveAll('skip') }"
     />
     <MediaNewFolderDialog v-model:open="newFolderOpen" @create="onCreateFolder" />
-    <MediaViewer :open="viewerOpen" :file="viewerFile" :busy="viewerBusy" :error="viewerError" @update:open="(v) => { viewerOpen = v }" @save="onSaveAlt" />
+    <MediaViewer :open="viewerOpen" :file="viewerFile" :busy="viewerBusy" :error="viewerError" @update:open="(v) => { viewerOpen = v }" @save="onSaveMeta" />
     <UiAlert v-if="opError && !deleteOpen && !renameOpen" variant="error">{{ opError }}</UiAlert>
     <MediaDeleteDialog
       :open="deleteOpen"

package/layers/media/app/components/MediaViewer.vue

@@ -3,9 +3,15 @@ import { ref, computed, watch } from 'vue'
 import { humanizeSize, type LibraryFile } from '../utils/library'
 
 // Fullscreen-ish preview + general info for a single file. Images additionally expose an editable alt
-// text (the only field worth maintaining from the library); everything else is read-only metadata.
+// text (the only field worth maintaining from the library) and — when the consumer switched the feature
+// on — the EU AI Act Art. 50 disclosure; everything else is read-only metadata.
 const props = defineProps<{ open: boolean; file: LibraryFile | null; busy?: boolean; error?: string | null }>()
-const emit = defineEmits<{ 'update:open': [boolean]; save: [string] }>()
+// The disclosure rides along as a SECOND positional argument rather than reshaping the first: an outside
+// consumer (`extensions/galleries-secure`) handles `save` as `(alt: string)` and simply ignores the extra.
+const emit = defineEmits<{
+  'update:open': [boolean]
+  save: [alt: string, ai?: { aiSourceType: string | null; aiNote: string | null }]
+}>()
 const { t, lang } = useT()
 
 const isImage = computed(() => props.file?.mime.startsWith('image/') ?? false)
@@ -18,12 +24,42 @@ const uploaded = computed(() => {
   return Number.isNaN(d.getTime()) ? '—' : d.toLocaleString(lang.value)
 })
 
+// Gates the disclosure controls only — the data is always resolved server-side, so a consumer who turns
+// the flag back off keeps whatever was recorded, it just stops being editable here.
+const aiEnabled = computed(() => useRuntimeConfig().public.aiDisclosureEnabled === true)
+const showAi = computed(() => isImage.value && aiEnabled.value)
+const AI_SOURCE_TYPES = ['trainedAlgorithmicMedia', 'compositeWithTrainedAlgorithmicMedia', 'algorithmicallyEnhanced'] as const
+// A leading empty option is what makes "no disclosure recorded" both representable and clearable
+// (mirrors how `field/Choice.vue` renders a non-required single choice).
+const aiSourceTypeOptions = computed(() => [
+  { label: '—', value: '' },
+  ...AI_SOURCE_TYPES.map((v) => ({ label: t(`mediaViewer.aiSourceType.${v}`), value: v })),
+])
+
 const alt = ref('')
-// Seed (and re-seed) the draft whenever the dialog opens — immediate so a viewer mounted already-open
-// (or re-opened on a different file) shows the current alt rather than a stale/empty value.
-watch(() => props.open, (o) => { if (o) alt.value = props.file?.alt ?? '' }, { immediate: true })
-const dirty = computed(() => isImage.value && alt.value !== (props.file?.alt ?? ''))
-function save() { if (dirty.value && !props.busy) emit('save', alt.value) }
+const aiSourceType = ref('')
+const aiNote = ref('')
+const fileAlt = computed(() => props.file?.alt ?? '')
+const fileAiSourceType = computed(() => props.file?.aiDisclosure?.sourceType ?? '')
+const fileAiNote = computed(() => props.file?.aiDisclosure?.note ?? '')
+// Seed (and re-seed) the drafts whenever the dialog opens — immediate so a viewer mounted already-open
+// (or re-opened on a different file) shows the current values rather than stale/empty ones.
+watch(() => props.open, (o) => {
+  if (!o) return
+  alt.value = fileAlt.value
+  aiSourceType.value = fileAiSourceType.value
+  aiNote.value = fileAiNote.value
+}, { immediate: true })
+
+const aiDirty = computed(() => showAi.value && (aiSourceType.value !== fileAiSourceType.value || aiNote.value !== fileAiNote.value))
+const dirty = computed(() => isImage.value && (alt.value !== fileAlt.value || aiDirty.value))
+function save() {
+  if (!dirty.value || props.busy) return
+  // With the feature off the payload is omitted entirely, so an alt-only save can never blank a
+  // disclosure the consumer recorded while it was on.
+  if (!showAi.value) { emit('save', alt.value); return }
+  emit('save', alt.value, { aiSourceType: aiSourceType.value || null, aiNote: aiNote.value.trim() || null })
+}
 </script>
 
 <template>
@@ -46,6 +82,18 @@ function save() { if (dirty.value && !props.busy) emit('save', alt.value) }
             <UiTextInput v-model="alt" v-bind="f" @keydown.enter="save" />
           </template>
         </UiField>
+        <div v-if="showAi" class="media-viewer__ai">
+          <UiField :label="t('mediaViewer.aiSourceTypeLabel')" :hint="t('mediaViewer.aiSourceTypeHint')">
+            <template #default="f">
+              <UiSelect v-model="aiSourceType" :options="aiSourceTypeOptions" v-bind="f" />
+            </template>
+          </UiField>
+          <UiField :label="t('mediaViewer.aiNote')" :hint="t('mediaViewer.aiNoteHint')">
+            <template #default="f">
+              <UiTextInput v-model="aiNote" v-bind="f" @keydown.enter="save" />
+            </template>
+          </UiField>
+        </div>
         <UiAlert v-if="error" variant="error">{{ error }}</UiAlert>
         <!-- Optional per-file extra panel (e.g. proofing comments). Empty by default. -->
         <slot name="extra" :file="file" />
@@ -81,6 +129,7 @@ function save() { if (dirty.value && !props.busy) emit('save', alt.value) }
 .media-viewer__preview img { max-width: 100%; max-height: 70svh; object-fit: contain; }
 .media-viewer__ext { padding: var(--space-7); font-size: var(--text-xl); font-weight: var(--weight-bold); color: var(--color-text-muted); }
 .media-viewer__details { display: flex; flex-direction: column; gap: var(--space-4); }
+.media-viewer__ai { display: flex; flex-direction: column; gap: var(--space-3); }
 .media-viewer__info { display: flex; flex-direction: column; gap: var(--space-2); margin: 0; }
 .media-viewer__info > div { display: flex; justify-content: space-between; gap: var(--space-3); font-size: var(--text-sm); }
 .media-viewer__info dt { color: var(--color-text-muted); }

package/layers/media/app/utils/ai-disclosure.ts

@@ -0,0 +1,19 @@
+import type { AiSourceType } from '../../server/utils/resolve'
+
+/**
+ * Default human-readable label for an EU AI Act source type — the badge text when no editor note was
+ * entered. English-only on purpose: it is a fallback, not a translation layer, and a consumer who wants
+ * their own wording (or locale) writes the `aiNote`, styles `.kestrel-img__ai-badge`, or reads
+ * `ResolvedMedia.aiDisclosure` and renders their own element. Kept pure so it stays unit-testable.
+ *
+ * An unrecognised value is returned VERBATIM rather than mapped to a generic label: the column is plain
+ * text at the DB level, and quietly relabelling an unknown value would state a disclosure nobody made.
+ */
+export function aiSourceTypeLabel(sourceType: AiSourceType | string): string {
+  switch (sourceType) {
+    case 'trainedAlgorithmicMedia': return 'AI-generated'
+    case 'compositeWithTrainedAlgorithmicMedia': return 'Contains AI-generated content'
+    case 'algorithmicallyEnhanced': return 'AI-edited'
+    default: return sourceType
+  }
+}

package/layers/media/app/utils/library.ts

@@ -7,6 +7,8 @@ export type { LibraryFolder }
 export interface LibraryFile {
   id: number; filename: string; mime: string; folder: string; size: number
   width?: number; height?: number; thumbhash?: string; src: string; srcset?: string; alt?: string
+  /** EU AI Act Art. 50 disclosure — always listed; `kestrel.config.ts`'s flag only gates the editor. */
+  aiDisclosure?: { sourceType: string; note: string | null } | null
   createdAt?: string
 }
 export type LibraryItem =

package/layers/media/server/api/media/[id].patch.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { eq, getTableColumns } from 'drizzle-orm'
+import { createError } from 'h3'
+import { createTestDb } from '../../../../../test/helpers/db'
+import { create } from '../../../../core/server/utils/crud'
+import builtMedia, { media } from '../../collections/media'
+
+interface FakeEvent { body: Record<string, unknown> }
+
+let db: ReturnType<typeof createTestDb>
+let id: number
+
+// The handler is a Nitro route: its auto-imported helpers are plain globals in a node test.
+Object.assign(globalThis, {
+  defineEventHandler: (handler: unknown) => handler,
+  requireAdmin: () => {},
+  createError,
+  requireId: () => id,
+  readIfUnmodifiedSince: () => undefined,
+  readBody: async (event: FakeEvent) => event.body,
+  useDb: () => db,
+  useRuntimeConfig: () => ({ kestrel: {} }),
+})
+
+const handler = (await import('./[id].patch')).default as unknown as (event: FakeEvent) => Promise<Record<string, unknown>>
+const patch = (body: Record<string, unknown>) => handler({ body })
+
+const cols = getTableColumns(media) as Record<string, never>
+const row = () => db.select().from(media).where(eq(cols.id, id)).get() as Record<string, unknown>
+
+beforeEach(() => {
+  db = createTestDb()
+  const created = create(db, builtMedia, { storageKey: 'a/one.png', folder: 'a', filename: 'one.png', mime: 'image/png', ext: 'png', size: 1 }) as { id: number }
+  id = created.id
+})
+
+describe('PATCH /api/media/:id — EU AI Act disclosure', () => {
+  it('persists both disclosure columns', async () => {
+    await patch({ aiSourceType: 'algorithmicallyEnhanced', aiNote: 'upscaled' })
+    expect(row()).toMatchObject({ aiSourceType: 'algorithmicallyEnhanced', aiNote: 'upscaled' })
+  })
+
+  it('clears the classification with an explicit null', async () => {
+    await patch({ aiSourceType: 'trainedAlgorithmicMedia', aiNote: 'Midjourney v7' })
+    await patch({ aiSourceType: null })
+    expect(row().aiSourceType).toBeNull()
+    expect(row().aiNote).toBe('Midjourney v7') // untouched — only the sent keys are written
+  })
+
+  it('rejects an unknown source type with a 400 instead of writing it', async () => {
+    await expect(patch({ aiSourceType: 'nonsense' })).rejects.toThrowError(expect.objectContaining({ statusCode: 400 }))
+    expect(row().aiSourceType).toBeNull()
+  })
+
+  it('stores a blanked note as null rather than an empty string a badge would render', async () => {
+    await patch({ aiSourceType: 'trainedAlgorithmicMedia', aiNote: 'Midjourney v7' })
+    await patch({ aiNote: '   ' })
+    expect(row().aiNote).toBeNull()
+  })
+
+  it('leaves the columns alone when the body does not mention them', async () => {
+    await patch({ aiSourceType: 'trainedAlgorithmicMedia', aiNote: 'note' })
+    await patch({ translations: { en: { alt: 'a kitten' } } })
+    expect(row()).toMatchObject({ aiSourceType: 'trainedAlgorithmicMedia', aiNote: 'note' })
+  })
+})

package/layers/media/server/api/media/[id].patch.ts

@@ -1,9 +1,32 @@
 import { eq, getTableColumns } from 'drizzle-orm'
-import { media } from '../../collections/media'
+import builtMedia, { media } from '../../collections/media'
 import { mergeTranslations, type Translations } from '../../utils/translations'
 import { emitMediaWrite } from '../../utils/media-write'
 import { requireMediaCollection } from '../../utils/media-enabled'
 
+const AI_KEYS = ['aiSourceType', 'aiNote'] as const
+
+/**
+ * The EU AI Act disclosure columns are top-level (not per-locale), so they are patched as plain siblings of
+ * `translations`. Only the keys the body actually sent are written — omitting one must not clear it. The
+ * allow-list of source types is NOT duplicated here: the collection's own update schema (built from the
+ * `choice` field's `choices`) is the single source of truth, so an unknown value 400s instead of storing.
+ */
+function readAiDisclosure(body: Record<string, unknown> | undefined | null): Record<string, unknown> {
+  const sent = AI_KEYS.filter((k) => Object.hasOwn(body ?? {}, k))
+  if (!sent.length) return {}
+  const parsed = builtMedia.update.safeParse(Object.fromEntries(sent.map((k) => [k, body![k]])))
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: `Invalid AI disclosure: ${parsed.error.issues[0]?.message ?? 'unknown value'}` })
+  }
+  const value = parsed.data as Record<string, unknown>
+  const patch: Record<string, unknown> = {}
+  for (const k of sent) patch[k] = value[k] ?? null
+  // A blanked note must round-trip as "no note", not as an empty string a badge would render as blank text.
+  if (patch.aiNote === '') patch.aiNote = null
+  return patch
+}
+
 export default defineEventHandler(async (event) => {
   requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
   requireMediaCollection()
@@ -34,6 +57,7 @@ export default defineEventHandler(async (event) => {
     // `en.alt` from the media viewer) keeps the other locales AND the locale's other fields intact.
     patch.translations = mergeTranslations(current?.translations, body.translations as Translations)
   }
+  Object.assign(patch, readAiDisclosure(body))
   const row = db.update(media).set(patch).where(eq(cols.id, id)).returning().get() as Record<string, unknown> | undefined
   if (!row) throw createError({ statusCode: 404, statusMessage: `media ${id} not found` })
   emitMediaWrite({ id }, row) // alt/title/description changed → re-render embedding pages (fresh alt text)

package/layers/media/server/api/media/index.post.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto'
 import { eq, inArray, getTableColumns, isNull } from 'drizzle-orm'
-import { media } from '../../collections/media'
+import builtMedia, { media } from '../../collections/media'
 import { useStorageDriver, mediaRuntimeConfig } from '../../../../core/server/utils/storage'
 import { sniffMime, extForMime, resolveAllowedMimes } from '../../utils/sniff'
 import { sanitizeFolder, buildKey, suggestFreeName, withExtension } from '../../utils/naming'
@@ -17,6 +17,8 @@ import { isUniqueViolation } from '../../../../core/server/utils/crud'
 import { withLock, mediaLockKey } from '../../../../core/server/utils/key-lock'
 import { requireMediaCollection } from '../../utils/media-enabled'
 import { emitMediaWrite } from '../../utils/media-write'
+import { detectAiSignal, aiSignalNote } from '../../utils/ai-signal-detect'
+import { aiDisclosureEnabled } from '../../utils/ai-disclosure-enabled'
 
 export default defineEventHandler(async (event) => {
   requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
@@ -83,12 +85,23 @@ export default defineEventHandler(async (event) => {
   const description = text('description')
   const translations = alt || title || description ? { [primaryLocale()]: { alt, title, description } } : {}
 
+  // EU AI Act Art. 50 disclosure. The classification is validated against the collection's own choice
+  // schema so the allow-list has a single source of truth (same as the PATCH route).
+  const aiSourceType = text('aiSourceType')?.trim() || undefined
+  if (aiSourceType && !builtMedia.update.safeParse({ aiSourceType }).success) {
+    throw createError({ statusCode: 400, statusMessage: `Invalid AI disclosure: unknown source type "${aiSourceType}"` })
+  }
+  const uploadedAiNote = text('aiNote')?.trim() || undefined
+  // Only parse when the feature is on: consumers who leave it off pay nothing for it. What the scan finds
+  // is EVIDENCE for the free-text note — it never asserts `aiSourceType`, which stays a human decision.
+  const signal = aiDisclosureEnabled() && !uploadedAiNote ? await detectAiSignal(bytes, mime).catch(() => null) : null
+
   // Serialize the collision-check → put → insert per storageKey: two concurrent uploads to the SAME key
   // (or a backfill re-deriving it) must not interleave, or last-writer-wins would leave the winning row
   // describing the loser's bytes. Different keys never share a lock, so throughput is unaffected.
   const { row, created } = await withLock(mediaLockKey(storageKey), async (): Promise<{ row: Record<string, unknown>; created: boolean }> => {
     const existing = db.select().from(media).where(eq(cols.storageKey, storageKey)).get() as
-      | { id: number; derivatives?: DerivativeManifest; translations?: Translations }
+      | { id: number; derivatives?: DerivativeManifest; translations?: Translations; aiNote?: string | null }
       | undefined
 
     // An object on disk with no media row (another media's derivative, or an orphan) must never be
@@ -131,7 +144,10 @@ export default defineEventHandler(async (event) => {
     }
 
     if (folder) ensureFolder(db, folder)
-    const values = buildMediaValues({ storageKey, folder, filename, mime, ext, size: bytes.length, checksum, derived, translations })
+    // The scan only ever fills a note that would otherwise be empty — it must not talk over an uploader's
+    // own text, nor over one an editor already curated on the row this upload is replacing.
+    const aiNote = uploadedAiNote ?? (existing?.aiNote ? undefined : signal && aiSignalNote(signal))
+    const values = buildMediaValues({ storageKey, folder, filename, mime, ext, size: bytes.length, checksum, derived, translations, aiSourceType, aiNote })
     try {
       // persistUpload writes the objects then the row; on a create-path failure it removes the freshly-written
       // blobs so a partial upload never strands orphans that permanently 409-block the filename.

package/layers/media/server/collections/media.ts

@@ -22,6 +22,20 @@ const built = buildCollection(defineCollection({
     thumbhash: { type: 'text' },
     derivatives: { type: 'json' },
     translations: { type: 'json' },
+    // EU AI Act Art. 50 disclosure. Top-level, NOT per-locale (`translations`): how an asset was produced
+    // does not change per translation. The vocabulary mirrors the disclosure-relevant subset of IPTC's
+    // Digital Source Type, so a later metadata-embedding slice can map 1:1.
+    aiSourceType: {
+      type: 'choice',
+      options: {
+        choices: [
+          { label: 'Fully AI-generated', value: 'trainedAlgorithmicMedia' },
+          { label: 'AI content composited into real media', value: 'compositeWithTrainedAlgorithmicMedia' },
+          { label: 'AI-enhanced / algorithmically edited', value: 'algorithmicallyEnhanced' },
+        ],
+      },
+    },
+    aiNote: { type: 'text' },
   },
 }))
 

package/layers/media/server/utils/ai-disclosure-enabled.ts

@@ -0,0 +1,16 @@
+import { resolveServerKestrel, serverRuntimeConfig } from '../../../core/server/utils/server-config'
+
+/**
+ * Whether the EU AI Act disclosure feature is switched on for this consumer (`aiDisclosure.enabled`).
+ *
+ * It gates the ADMIN UI and the upload-time signal scan — never the data: `ResolvedMedia.aiDisclosure` is
+ * always resolved from whatever the columns hold, so turning the flag off hides the editor without
+ * touching (or hiding) a disclosure already recorded. Same runtimeConfig-then-own-config fallback as
+ * `mediaCollectionEnabled`, so non-Nitro callers (scripts, build) resolve it too.
+ */
+export function aiDisclosureEnabled(): boolean {
+  const cfg = (serverRuntimeConfig()?.kestrel?.aiDisclosure ?? resolveServerKestrel().aiDisclosure) as
+    | { enabled?: boolean }
+    | undefined
+  return cfg?.enabled === true
+}

package/layers/media/server/utils/ai-signal-detect.ts

@@ -0,0 +1,155 @@
+/**
+ * Upload-time scan for signals that a file was AI-generated or -manipulated (EU AI Act Art. 50).
+ *
+ * **This produces EVIDENCE, never a classification.** Everything it finds is quoted into the free-text
+ * `aiNote`; the legal `aiSourceType` stays a deliberate human decision, because a signal is neither proof
+ * nor its absence a disproof: metadata survives no re-save, screenshot or re-encode, and an upstream file
+ * can be mislabeled or forged. In particular a C2PA manifest is reported as PRESENT only — verifying its
+ * signature needs the full C2PA SDK plus a trust list, which Kestrel deliberately does not ship.
+ *
+ * Pure (no DB, no Nitro) so it stays unit-testable, and never throws: an unreadable file is simply no
+ * evidence, which must not fail the upload it came with.
+ */
+
+/** Tools that name themselves in EXIF `Software`. Matched case-insensitively as whole phrases, so an
+ *  ordinary "Adobe Photoshop" is not caught by the "Adobe Firefly" entry. */
+const KNOWN_GENERATORS = [
+  'midjourney', 'dall-e', 'dall·e', 'adobe firefly', 'stable diffusion', 'leonardo.ai',
+  'nightcafe', 'bing image creator', 'google imagefx', 'imagen', 'flux.1', 'ideogram',
+]
+
+/** PNG text-chunk keywords the Stable-Diffusion / ComfyUI families write their generation graph under. */
+const GENERATION_KEYWORDS = ['parameters', 'prompt', 'workflow']
+
+export interface AiSignal {
+  /** One human-readable line per signal found, in a stable order. Never empty (the result is null instead). */
+  evidence: string[]
+}
+
+/** Walk PNG chunks after the 8-byte signature, yielding `[type, data]`. Bails out on any malformed length. */
+function* pngChunks(bytes: Buffer): Generator<[string, Buffer]> {
+  if (bytes.length < 8 || bytes.readUInt32BE(0) !== 0x89504E47) return
+  let at = 8
+  while (at + 8 <= bytes.length) {
+    const len = bytes.readUInt32BE(at)
+    const end = at + 8 + len
+    if (len > bytes.length || end + 4 > bytes.length) return
+    yield [bytes.toString('latin1', at + 4, at + 8), bytes.subarray(at + 8, end)]
+    at = end + 4 // skip the trailing CRC
+  }
+}
+
+/** Walk JPEG marker segments after SOI, yielding `[marker, payload]`. Stops at SOS (entropy-coded data). */
+function* jpegSegments(bytes: Buffer): Generator<[number, Buffer]> {
+  if (bytes.length < 4 || bytes[0] !== 0xFF || bytes[1] !== 0xD8) return
+  let at = 2
+  while (at + 4 <= bytes.length) {
+    if (bytes[at] !== 0xFF) return
+    const marker = bytes[at + 1]!
+    if (marker === 0xDA || marker === 0xD9) return
+    const len = bytes.readUInt16BE(at + 2)
+    if (len < 2 || at + 2 + len > bytes.length) return
+    yield [marker, bytes.subarray(at + 4, at + 2 + len)]
+    at += 2 + len
+  }
+}
+
+/** Walk RIFF/WebP chunks, yielding `[fourcc, data]`. Chunks are padded to an even length. */
+function* riffChunks(bytes: Buffer): Generator<[string, Buffer]> {
+  if (bytes.length < 12 || bytes.toString('latin1', 0, 4) !== 'RIFF') return
+  let at = 12
+  while (at + 8 <= bytes.length) {
+    const len = bytes.readUInt32LE(at + 4)
+    const end = at + 8 + len
+    if (len > bytes.length || end > bytes.length) return
+    yield [bytes.toString('latin1', at, at + 4), bytes.subarray(at + 8, end)]
+    at = end + (len % 2)
+  }
+}
+
+/**
+ * The IPTC Digital Source Type a generator self-declared, read straight out of the embedded XMP packet.
+ * Deliberately a byte-level scan rather than a metadata library: XMP is the same XML in every container,
+ * so this also covers the ones exifr cannot open (WebP), and it costs one `indexOf` when absent.
+ */
+function findDigitalSourceType(bytes: Buffer): string | null {
+  const at = bytes.indexOf('DigitalSourceType', 0, 'latin1')
+  if (at < 0) return null
+  const window = bytes.toString('latin1', at, Math.min(at + 512, bytes.length))
+  // Both XMP serializations: as an rdf:Description attribute, or as its own element.
+  const value = /^DigitalSourceType\s*=\s*"([^"]*)"/.exec(window)?.[1]
+    ?? /^DigitalSourceType[^>]*>([^<]*)</.exec(window)?.[1]
+  const trimmed = value?.trim()
+  return trimmed ? trimmed : null
+}
+
+/** True when the file structurally carries a C2PA/JUMBF manifest store. Presence only — never verified. */
+function hasC2paManifest(bytes: Buffer): boolean {
+  for (const [type] of pngChunks(bytes)) if (type === 'caBX') return true
+  // C2PA-in-JPEG lives in APP11 segments whose payload starts with the JUMBF "JP" identifier.
+  for (const [marker, payload] of jpegSegments(bytes)) {
+    if (marker === 0xEB && payload.length >= 2 && payload.toString('latin1', 0, 2) === 'JP') return true
+  }
+  for (const [fourcc] of riffChunks(bytes)) if (fourcc === 'C2PA') return true
+  return false
+}
+
+/** The generation-parameter keyword a PNG text chunk is stored under, or null. Covers tEXt/zTXt/iTXt —
+ *  in all three the keyword is the leading null-terminated string, so a compressed payload needs no
+ *  inflating to be recognised (exifr only decodes the uncompressed tEXt form). */
+function findPngGenerationChunk(bytes: Buffer): string | null {
+  for (const [type, data] of pngChunks(bytes)) {
+    if (type !== 'tEXt' && type !== 'zTXt' && type !== 'iTXt') continue
+    const nul = data.indexOf(0)
+    const keyword = data.toString('latin1', 0, nul < 0 ? data.length : nul).toLowerCase()
+    if (GENERATION_KEYWORDS.includes(keyword)) return keyword
+  }
+  return null
+}
+
+/** The EXIF `Software`/`ProcessingSoftware` value, when it names a tool on the known-generator list. */
+async function findGeneratorSoftware(bytes: Buffer): Promise<string | null> {
+  let tags: Record<string, unknown> | undefined
+  try {
+    // Loaded lazily: consumers who never turn the feature on never pay the module's parse cost.
+    const exifr = (await import('exifr')).default
+    tags = await exifr.parse(bytes, { tiff: true, exif: true, mergeOutput: true }) as Record<string, unknown> | undefined
+  } catch {
+    return null // an unsupported container or a corrupt header is simply no evidence
+  }
+  for (const key of ['Software', 'ProcessingSoftware']) {
+    const value = tags?.[key]
+    if (typeof value !== 'string' || !value.trim()) continue
+    const haystack = value.toLowerCase()
+    if (KNOWN_GENERATORS.some((g) => haystack.includes(g))) return value.trim()
+  }
+  return null
+}
+
+/**
+ * Scan an uploaded file for AI-origin signals. Returns null when nothing matched — which is NOT evidence
+ * of non-AI origin, only the absence of a declaration.
+ */
+export async function detectAiSignal(bytes: Buffer, _mime: string): Promise<AiSignal | null> {
+  const evidence: string[] = []
+
+  const sourceType = findDigitalSourceType(bytes)
+  if (sourceType) evidence.push(`IPTC/XMP Digital Source Type: ${sourceType}`)
+
+  const software = await findGeneratorSoftware(bytes)
+  if (software) evidence.push(`EXIF Software: ${software}`)
+
+  if (hasC2paManifest(bytes)) {
+    evidence.push('C2PA content-credentials manifest present (unverified — presence only, no signature check)')
+  }
+
+  const keyword = findPngGenerationChunk(bytes)
+  if (keyword) evidence.push(`PNG text chunk "${keyword}" present (Stable-Diffusion-style generation parameters)`)
+
+  return evidence.length ? { evidence } : null
+}
+
+/** How the scan's findings are worded into `aiNote`. Kept here so the wording has one home. */
+export function aiSignalNote(signal: AiSignal): string {
+  return `Detected at upload: ${signal.evidence.join('; ')}`
+}

package/layers/media/server/utils/library.ts

@@ -56,7 +56,8 @@ export function listLibrary(db: BetterSQLite3Database, q: LibraryQuery, publicUr
     return {
       id: m.id, filename: r.filename as string, mime: m.mime, folder: r.folder as string,
       size: r.size as number, width: m.width, height: m.height, thumbhash: m.thumbhash,
-      src: m.src, srcset, alt: m.alt, createdAt: r.createdAt as Date, updatedAt: r.updatedAt as Date,
+      src: m.src, srcset, alt: m.alt, aiDisclosure: m.aiDisclosure,
+      createdAt: r.createdAt as Date, updatedAt: r.updatedAt as Date,
     }
   })
 

package/layers/media/server/utils/record.ts

@@ -14,6 +14,10 @@ export interface MediaInput {
   checksum: string
   derived?: DerivedImage
   translations?: Record<string, { alt?: string; title?: string; description?: string }>
+  /** EU AI Act disclosure to write. Omitted/null ⇒ the column is left out of the values entirely, which is
+   *  what keeps an overwrite from wiping a disclosure the re-upload did not re-send. */
+  aiSourceType?: string | null
+  aiNote?: string | null
 }
 
 /**
@@ -46,6 +50,10 @@ export function buildMediaValues(input: MediaInput): Record<string, unknown> {
     thumbhash: input.derived?.thumbhash ?? null,
     derivatives: manifest,
     translations: input.translations ?? {},
+    // Written only when there is something to write: the overwrite path feeds these same values to an
+    // UPDATE, and a null here would silently clear a disclosure an editor set on the existing row.
+    ...(input.aiSourceType != null ? { aiSourceType: input.aiSourceType } : {}),
+    ...(input.aiNote != null ? { aiNote: input.aiNote } : {}),
   }
 }
 

package/layers/media/server/utils/resolve.ts

@@ -7,6 +7,9 @@ import type { DerivativeManifest } from './record'
 /** One derivative, tagged with its parsed name + format so `<picture>` rendering can group by format. */
 export interface MediaVariant { name: string; format: string; url: string; width: number; height: number }
 
+/** The disclosure-relevant subset of the IPTC Digital Source Type vocabulary (EU AI Act Art. 50). */
+export type AiSourceType = 'trainedAlgorithmicMedia' | 'compositeWithTrainedAlgorithmicMedia' | 'algorithmicallyEnhanced'
+
 export interface ResolvedMedia {
   id: number
   /** The media's storage folder ('' at the media root) — lets the field open the picker there. */
@@ -23,6 +26,10 @@ export interface ResolvedMedia {
   srcset: { url: string; width: number }[]
   /** Every derivative, name+format-tagged — the source `KestrelImg`/`useMediaVariant` build `<picture>` from. */
   variants: MediaVariant[]
+  /** EU AI Act Art. 50 disclosure, set by an editor — null when unset. Always resolved regardless of
+   *  `kestrel.config.ts`'s `aiDisclosure.enabled` (that flag only gates the admin UI). Kestrel never
+   *  renders this automatically; read it directly or opt into `KestrelImg`'s `aiBadge` prop. */
+  aiDisclosure: { sourceType: AiSourceType; note: string | null } | null
 }
 
 interface MediaRow {
@@ -35,6 +42,8 @@ interface MediaRow {
   thumbhash: string | null
   derivatives: DerivativeManifest | null
   translations: Record<string, { alt?: string; title?: string; description?: string }> | null
+  aiSourceType: string | null
+  aiNote: string | null
 }
 
 export function resolveMedia(row: MediaRow, locale: string, publicUrl: (key: string) => string): ResolvedMedia {
@@ -69,6 +78,9 @@ export function resolveMedia(row: MediaRow, locale: string, publicUrl: (key: str
     src: publicUrl(row.storageKey),
     srcset,
     variants,
+    // A note without a source type is only evidence (e.g. the upload scan's pre-fill), not a disclosure —
+    // never emit a half-filled object a consumer might render as one.
+    aiDisclosure: row.aiSourceType ? { sourceType: row.aiSourceType as AiSourceType, note: row.aiNote ?? null } : null,
   }
 }