@glw907/cairn-cms 0.56.2 → 0.57.0

package/src/lib/sveltekit/content-routes.ts

@@ -17,11 +17,24 @@ import { cachedInstallationToken } from '../github/signing.js';
 import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest, upsertEntry, removeEntry, inboundLinks, type Manifest, type LinkTarget, type InboundLink } from '../content/manifest.js';
 import { isConflict } from '../github/types.js';
 import { log } from '../log/index.js';
-import { issueCsrfToken } from './csrf.js';
+import { issueCsrfToken, validateCsrfHeader } from './csrf.js';
 import { requireSession } from './guard.js';
+import { sniffMediaType, isDeniedUpload, extForMediaType } from '../media/sniff.js';
+import { hashBytes, shortHash, slugifyFilename, r2Key } from '../media/naming.js';
+import { mediaToken } from '../media/reference.js';
+import { r2Store } from '../media/store.js';
+import { parseMediaEntries, parseMediaManifest, upsertMediaEntry, removeMediaEntry, serializeMediaManifest } from '../media/manifest.js';
+import type { MediaEntry } from '../media/manifest.js';
+import { mediaLibraryEntry } from '../media/library-entry.js';
+import type { MediaLibrary, MediaLibraryEntry } from '../media/library-entry.js';
+import { buildUsageIndex } from '../media/usage.js';
+import type { UsageEntry } from '../media/usage.js';
 import type { CookieJar, EventBase } from './types.js';
 import type { CairnRuntime, ConceptDescriptor, FrontmatterField, PreviewConfig, ResolvedPreview } from '../content/types.js';
 import type { Editor, Role } from '../auth/types.js';
+// R2Bucket is named only inside uploadAction to cast the raw binding for r2Store. It is a type-only
+// import that never appears in an exported signature, so it does not reach the public `.d.ts`.
+import type { R2Bucket } from '@cloudflare/workers-types';
 
 /** A sidebar concept entry: just enough to render the nav without shipping validators to the client. */
 export interface NavConcept {
@@ -99,6 +112,14 @@ export interface EditData {
   slug: string;
   /** The site's link targets, for the preview resolver and the link picker; from the committed manifest. */
   linkTargets: LinkTarget[];
+  /** The minimal media-resolver input the edit page builds its preview `resolveMedia` from, keyed by
+   *  the 16-hex content hash and parallel to `linkTargets`. Empty when media is off or the read fails. */
+  mediaTargets: Record<string, { slug: string; ext: string; contentType: string }>;
+  /** The picker's human layer for each stored asset, keyed by the 16-hex content hash and projected
+   *  from the same committed media manifest read that populates `mediaTargets`. The `hash` field
+   *  duplicates the key, so the picker can iterate `Object.values`. Empty when media is off or the
+   *  read fails (the same degradation path as `mediaTargets`). */
+  mediaLibrary: MediaLibrary;
   /** The entries that link to this one, for the delete guard. Empty when nothing links here. */
   inboundLinks: InboundLink[];
   /** True when the entry has a pending branch, so the body above came from that branch. */
@@ -115,6 +136,25 @@ export interface EditData {
   preview: ResolvedPreview | null;
 }
 
+/** One asset's where-used overlay, kept separate from MediaLibraryEntry so the picker's shared
+ *  projection stays decoupled from the Library-only usage facts. */
+export interface MediaUsageInfo {
+  /** Distinct content entries that reference the asset (count by distinct concept+id). */
+  count: number;
+  /** Every where-used row (published and edit-branch origins), for the detail's grouped list. */
+  entries: UsageEntry[];
+}
+
+/** The Media Library screen's data: the unioned assets, the per-hash usage overlay, and the
+ *  degraded-load error. The usage overlay is keyed by content hash; an asset with no references
+ *  simply has no key, which the screen renders as "no references found". */
+export interface MediaLibraryData {
+  assets: MediaLibraryEntry[];
+  /** Per-hash usage overlay, kept separate from MediaLibraryEntry so the popover stays decoupled. */
+  usage: Record<string, MediaUsageInfo>;
+  error: string | null;
+}
+
 /** The structural event the content routes read; a real SvelteKit RequestEvent satisfies it. */
 export interface ContentEvent extends EventBase<GithubKeyEnv> {
   params: Record<string, string>;
@@ -156,10 +196,45 @@ export interface RenameFailure {
   error: string;
 }
 
+/** A refused media delete: `fail(404)` for an asset not committed on the default branch, or
+ *  `fail(409)` when a fresh usage read finds the asset still in use and the typed-slug override
+ *  was not given. `fail(503)` covers media-off or a missing bucket binding. */
+export interface MediaDeleteRefusal {
+  /** The one-line human summary every action failure carries. */
+  error: string;
+  /** The refused asset's content hash, so the dialog marks the right asset. */
+  hash: string;
+  /** The where-used rows (published first, then by branch) the in-use face lists; empty otherwise. */
+  usage: UsageEntry[];
+  /** The distinct-entry count behind the refusal; zero when the asset is uncommitted. */
+  foundIn: number;
+}
+
+/** A refused media metadata edit: `fail(404)` for an asset not committed on the default branch, or
+ *  `fail(400)` for an invalid slug. */
+export interface MediaUpdateFailure {
+  /** The one-line human summary every action failure carries. */
+  error: string;
+}
+
 /** What a route's single `form` export presents to a view component: whichever content action
  *  last failed, merged with every field optional. `error` is always set on a failure; the richer
- *  keys identify which guard refused. */
-export type ContentFormFailure = Partial<SaveFailure & DeleteRefusal & RenameFailure>;
+ *  keys identify which guard refused. The media refusals ride here too, so the Media Library's one
+ *  `form` prop carries a `?/mediaDelete` or `?/mediaUpdate` refusal without a second type. */
+export type ContentFormFailure = Partial<
+  SaveFailure & DeleteRefusal & RenameFailure & MediaDeleteRefusal & MediaUpdateFailure
+>;
+
+/** The successful upload's response (`uploadAction`). The server-owned `record` rides the editor's
+ *  optimistic client state and commits with the entry at Save (the upload itself commits nothing).
+ *  `reused` is true when identical bytes were already stored, so the second upload did no second put;
+ *  `mismatch` flags an existing object whose stored content type differs from this sniff. */
+export interface UploadResult {
+  reference: string;
+  record: MediaEntry;
+  reused: boolean;
+  mismatch: boolean;
+}
 
 /** Resolve the effective preview for one concept: its `byConcept` override wins per key, with
  *  nullish coalescing so an override key that is present but undefined keeps the top-level value.
@@ -192,6 +267,18 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     return raw === null ? emptyManifest() : parseManifest(raw);
   }
 
+  /** Parse a committed media.json body to a plain value for parseMediaManifest, degrading a missing
+   *  or corrupt file to null (an empty manifest). The committed file is always our own serialization,
+   *  so the catch only guards a hand-edited or truncated file rather than a normal path. */
+  function parseMediaJson(raw: string | null): unknown {
+    if (raw === null) return null;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+
   /** The pending entry a `cairn/` ref names, or null for a ref the engine must ignore: a
    *  malformed name, an id that fails the slug rule (entry paths are built from it, so this is
    *  the path confinement), or a concept this site does not configure. Every ref consumer
@@ -353,6 +440,73 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     }
   }
 
+  /** The admin Media Library load: union the media manifest across main and every open cairn/*
+   *  branch (so a not-yet-published asset shows), project each row through the shared
+   *  mediaLibraryEntry helper, and attach the cross-branch where-used overlay keyed by content
+   *  hash. The assets union and the usage overlay degrade independently: a usage-build failure
+   *  still lists the assets with an empty overlay, and a wholesale read failure degrades to the
+   *  assets gathered so far rather than a thrown 500, mirroring listLoad's posture. */
+  async function mediaLibraryLoad(event: ContentEvent): Promise<MediaLibraryData> {
+    requireSession(event);
+    let token: string;
+    try {
+      token = await mintToken(event.platform?.env ?? {});
+    } catch {
+      return { assets: [], usage: {}, error: 'Could not authenticate with GitHub.' };
+    }
+
+    // Union the media manifest by hash: main's rows first, then any branch hash not already present.
+    // Identical bytes share one row, so a hash on both branches prefers main's row. A failed or
+    // absent branch read degrades to no rows for that branch (the tolerant parse yields {} on null).
+    // The branch list is taken ONCE here and handed to buildUsageIndex below, so the load path does
+    // not enumerate the open branches twice (the per-page subrequest budget is tight at ~25+ branches).
+    const union = new Map<string, MediaEntry>();
+    let branchNames: string[] = [];
+    try {
+      const mediaRaw = await readRaw(runtime.backend, runtime.mediaManifestPath, token);
+      for (const [hash, e] of Object.entries(parseMediaManifest(parseMediaJson(mediaRaw)))) {
+        union.set(hash, e);
+      }
+      const names = await listBranches(runtime.backend, PENDING_PREFIX, token);
+      branchNames = names;
+      const branchManifests = await Promise.all(
+        names.map((name) =>
+          readRaw({ ...runtime.backend, branch: name }, runtime.mediaManifestPath, token)
+            .then((raw) => parseMediaManifest(parseMediaJson(raw)))
+            .catch(() => ({}) as Record<string, MediaEntry>),
+        ),
+      );
+      for (const manifest of branchManifests) {
+        for (const [hash, e] of Object.entries(manifest)) {
+          if (!union.has(hash)) union.set(hash, e);
+        }
+      }
+    } catch {
+      // A wholesale read failure leaves whatever rows were already unioned; the screen lists them
+      // with no usage overlay rather than failing.
+      return { assets: [...union.values()].map(mediaLibraryEntry), usage: {}, error: 'Could not load media.' };
+    }
+    const assets = [...union.values()].map(mediaLibraryEntry);
+
+    // Build the where-used overlay from main's content manifest plus the open branches. A failure
+    // here keeps the asset list intact with an empty overlay, since the screen still lists assets.
+    let usage: Record<string, MediaUsageInfo> = {};
+    try {
+      const manifestRaw = await readRaw(runtime.backend, runtime.manifestPath, token);
+      const manifest = manifestRaw === null ? emptyManifest() : parseManifest(manifestRaw);
+      // Reuse the branch list from the media-union above; the Library DISPLAY keeps the default
+      // best-effort behavior (a failed branch read degrades that one branch, not the screen).
+      const index = await buildUsageIndex(runtime.backend, token, runtime.concepts, manifest, { branches: branchNames });
+      for (const [hash, entries] of index) {
+        usage[hash] = { count: distinctEntryCount(entries), entries };
+      }
+    } catch {
+      usage = {};
+    }
+
+    return { assets, usage, error: null };
+  }
+
   /** Create a new entry: validate the slug, compose a dated id when the concept is dated, refuse to clobber. */
   async function createAction(event: ContentEvent): Promise<never> {
     requireSession(event);
@@ -393,6 +547,9 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
       if (field.type === 'date') out[field.name] = dateInputValue(value);
       else if (field.type === 'boolean') out[field.name] = value === true;
       else if (field.type === 'tags' || field.type === 'freetags') out[field.name] = Array.isArray(value) ? value.map(String) : [];
+      // A hero is a nested object; the default String() arm would corrupt it to '[object Object]'.
+      // Hand the stored object back as-is so the editor reads .src/.alt/.caption on open.
+      else if (field.type === 'image') out[field.name] = value !== null && typeof value === 'object' ? value : undefined;
       else out[field.name] = typeof value === 'string' ? value : value == null ? '' : String(value);
     }
     return out;
@@ -415,10 +572,16 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     // only when the probe found a branch, with the stage-1 main read serving as the published
     // signal either way.
     const branch = pendingBranch(concept.id, id);
-    const [headSha, mainRaw, manifestRaw] = await Promise.all([
+    // The media manifest joins the concurrent batch only when media is on, read from the default
+    // branch (pending branches carry no copy). A rejected media read degrades to null so the edit
+    // never throws on a missing or unreadable media.json; the projection below treats null as empty.
+    const [headSha, mainRaw, manifestRaw, mediaRaw] = await Promise.all([
       branchHeadSha(runtime.backend, branch, token),
       readRaw(runtime.backend, path, token),
       readRaw(runtime.backend, runtime.manifestPath, token),
+      runtime.resolvedAssets.enabled
+        ? readRaw(runtime.backend, runtime.mediaManifestPath, token).catch(() => null)
+        : Promise.resolve(null),
     ]);
     const pending = headSha !== null;
     const raw = pending ? await readRaw({ ...runtime.backend, branch }, path, token) : mainRaw;
@@ -443,6 +606,16 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
       inbound = inboundLinks(manifest, concept.id, id);
     }
 
+    // Project the one committed media manifest read two ways: the minimal resolver triple the preview
+    // needs (`mediaTargets`) and the picker's full human layer (`mediaLibrary`), both keyed by hash.
+    // A corrupt committed file degrades both to empty, not a throw.
+    const mediaTargets: EditData['mediaTargets'] = {};
+    const mediaLibrary: EditData['mediaLibrary'] = {};
+    for (const [hash, e] of Object.entries(parseMediaManifest(parseMediaJson(mediaRaw)))) {
+      mediaTargets[hash] = { slug: e.slug, ext: e.ext, contentType: e.contentType };
+      mediaLibrary[hash] = mediaLibraryEntry(e);
+    }
+
     return {
       conceptId: concept.id,
       id,
@@ -457,6 +630,8 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
       error: event.url.searchParams.get('error'),
       slug: slugFromId(id, datePrefix),
       linkTargets,
+      mediaTargets,
+      mediaLibrary,
       inboundLinks: inbound,
       pending,
       published,
@@ -512,6 +687,11 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     /** The draft-target tokens the body links to, for save's warning query. */
     draftLinks: string[];
     token: string;
+    /** The merged media.json change this save committed to the branch, when media is on and the
+     *  post carried records. Publish reuses it verbatim so the main commit promotes the exact same
+     *  merged content (decision 1: the default-branch base is read once, here, not re-merged at
+     *  publish). Absent when media is off or no records were posted. */
+    mediaChange?: FileChange;
   }
 
   /** The shared core of save and publish: parse the posted form, validate the frontmatter,
@@ -540,6 +720,25 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     const markdown = serializeMarkdown(result.data, body);
     const token = await mintToken(event.platform?.env ?? {});
 
+    // Merge the editor's optimistic media records into the media manifest, gated on media being on
+    // and at least one valid record posted. The base is read from the default branch (never the
+    // pending branch), so each save's union starts from main's committed rows, and decision 1's
+    // last-writer-wins-by-hash race is the accepted trade. The merged file rides the branch commit
+    // below and, carried on SaveHold, the publish commit, so both reuse the same content with no
+    // second read. When media is off or no records arrive, nothing touches media.json.
+    let mediaChange: FileChange | undefined;
+    if (runtime.resolvedAssets.enabled) {
+      const records = parseMediaEntries(form.get('media'));
+      if (records.length > 0) {
+        const baseRaw = await readRaw(runtime.backend, runtime.mediaManifestPath, token);
+        let mediaManifest = parseMediaManifest(parseMediaJson(baseRaw));
+        for (const record of records) {
+          mediaManifest = upsertMediaEntry(mediaManifest, record);
+        }
+        mediaChange = { path: runtime.mediaManifestPath, content: serializeMediaManifest(mediaManifest) };
+      }
+    }
+
     // Upsert this entry's row into main's manifest in memory, for the link guard here and for
     // the publish commit. The save commits no manifest change; publish lands the upsert on main.
     const manifest = await readManifest(token);
@@ -586,7 +785,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     try {
       branchSha = await commitFiles(
         { ...runtime.backend, branch },
-        [{ path, content: markdown }],
+        mediaChange ? [{ path, content: markdown }, mediaChange] : [{ path, content: markdown }],
         { message: `Update ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } },
         token,
       );
@@ -595,7 +794,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
       commitFailure(commitFields, err, `/admin/${concept.id}/${id}`,
         'This file changed since you opened it. Reload and reapply your edits.', { query: suffix });
     }
-    return { path, markdown, branch, branchSha, manifest: upserted, draftLinks, token };
+    return { path, markdown, branch, branchSha, manifest: upserted, draftLinks, token, mediaChange };
   }
 
   /** Save an edit: validate, then commit to the entry's pending branch with the session editor
@@ -628,16 +827,22 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     if (!isValidId(id)) throw error(400, 'Invalid entry id');
     const held = await saveToBranch(event, editor, concept, id);
     if (!('branchSha' in held)) return held;
-    const { path, markdown, branch, branchSha, manifest, token } = held;
+    const { path, markdown, branch, branchSha, manifest, token, mediaChange } = held;
+
+    // The publish commit reuses the exact merged media.json saveToBranch already built (decision 1:
+    // no re-read or re-merge here). Promote it to main alongside the body and the content manifest
+    // in one atomic commit, or commit those two alone when the save touched no media.
+    const changes: FileChange[] = [
+      { path, content: markdown },
+      { path: runtime.manifestPath, content: serializeManifest(manifest) },
+    ];
+    if (mediaChange) changes.push(mediaChange);
 
     const commitFields = { concept: concept.id, id, editor: editor.email };
     try {
       await commitFiles(
         runtime.backend,
-        [
-          { path, content: markdown },
-          { path: runtime.manifestPath, content: serializeManifest(manifest) },
-        ],
+        changes,
         { message: `Publish ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } },
         token,
       );
@@ -937,5 +1142,361 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     throw redirect(303, `/admin/${concept.id}/${newId}?renamed=1`);
   }
 
-  return { layoutLoad, indexRedirect, listLoad, createAction, editLoad, saveAction, publishAction, publishAllAction, discardAction, deleteAction, listDeleteAction, renameAction, mintToken };
+  /**
+   * Ingest an uploaded image: the JSON/fetch endpoint with the untrusted-input contract (spec piece
+   * 2, decisions 1 to 3). The body is the raw file bytes, read once; the human metadata travels in
+   * percent-encoded `X-Cairn-*` request headers. The server owns every committed field and trusts no
+   * client value: it sniffs the real type, screens the engine deny-list, re-hashes, re-derives the
+   * ext and slug, caps and sanitizes the human fields, and clamps the advisory dimensions. It stores
+   * put-first to R2 with content-addressed dedup (no second put for identical bytes, no
+   * compensating delete) and commits nothing to git.
+   *
+   * Wire contract: this is a SvelteKit form action, so for a JSON request SvelteKit serializes the
+   * result into a 200 JSON envelope `{ type, status, data }`. A `fail(status, ...)` rides the
+   * envelope's `status` field, NOT the HTTP response status (the HTTP status stays 200); a client
+   * parses `type`/`status` from the body, never `Response.status`. Success returns a plain
+   * `UploadResult` (also a 200 envelope). The action logs `media.upload_failed` on a refusal and
+   * `media.uploaded` on success.
+   *
+   * Session authority: behind `createAuthGuard` the guard is the production session gate. An
+   * unauthenticated admin POST is redirected 303 by the guard before this action runs (an opaque,
+   * status-0 response under the client's `redirect: 'manual'`), so the `fail(401, 'session-expired')`
+   * below is a belt-and-suspenders for a direct or un-guarded call, not the primary path.
+   */
+  async function uploadAction(event: ContentEvent): Promise<ReturnType<typeof fail> | UploadResult> {
+    // Read the editor up front for log attribution; the gate at step 4 enforces its presence. The
+    // pre-session gates (1 to 3) may log with an undefined editor email, which is fine.
+    const editor = event.locals.editor ?? null;
+    const refuse = (status: number, reason: string): ReturnType<typeof fail> => {
+      log.warn('media.upload_failed', { editor: editor?.email, reason });
+      return fail(status, { error: reason });
+    };
+
+    // 1. Media on.
+    const resolved = runtime.resolvedAssets;
+    if (!resolved.enabled) return refuse(503, 'media-disabled');
+
+    // 2. Content-Length before the body is read: an absent or non-positive-integer length is a 411,
+    //    an oversize length is a 413. Both refuse before the bytes are buffered. The header is
+    //    client-advisory, so the real DoS bound is the Worker request-size limit, not maxUploadBytes:
+    //    a lying client still buffers up to the platform ceiling before the post-read recheck (step 5).
+    const lengthHeader = event.request.headers.get('content-length');
+    const length = lengthHeader === null ? NaN : Number(lengthHeader);
+    if (!Number.isInteger(length) || length <= 0) return refuse(411, 'length-required');
+    if (length > resolved.maxUploadBytes) return refuse(413, 'too-large');
+
+    // 3. CSRF from the X-Cairn-CSRF header (no body clone): the action is the CSRF authority for the
+    //    raw-body upload, since the guard runs its form-CSRF only on form content types.
+    if (!event.cookies || !validateCsrfHeader({ url: event.url, request: event.request, cookies: event.cookies })) {
+      return refuse(403, 'csrf');
+    }
+
+    // 4. JSON-aware session (belt-and-suspenders; see the docstring): behind the guard an
+    //    unauthenticated POST is already 303'd before this runs. For a direct or un-guarded call,
+    //    read the resolved editor directly and refuse with a 401 envelope rather than a 303 redirect.
+    if (!editor) return refuse(401, 'session-expired');
+
+    // 5. Read the body once. Content-Length is client-advisory, so a lying client could send more
+    //    than it declared; recheck the real size against the cap after the read.
+    const bytes = new Uint8Array(await event.request.arrayBuffer());
+    if (bytes.length > resolved.maxUploadBytes) return refuse(413, 'too-large');
+
+    // 6. Server re-derivation: trust nothing the client declared.
+    const declaredType = event.request.headers.get('content-type') ?? undefined;
+    const sniffed = sniffMediaType(bytes);
+    if (isDeniedUpload(bytes, declaredType) || sniffed === null || !resolved.allowedTypes.includes(sniffed)) {
+      return refuse(415, 'unsupported-type');
+    }
+    const ext = extForMediaType(sniffed);
+    if (ext === null) return refuse(415, 'unsupported-type');
+
+    const full = await hashBytes(bytes);
+    const hash = shortHash(full);
+
+    const decodedFilename = safeDecode(event.request.headers.get('x-cairn-filename'));
+    const slug = slugifyFilename(decodedFilename);
+    const originalFilename = sanitizeField(basename(decodedFilename), MAX_ORIGINAL_FILENAME);
+    const alt = sanitizeField(safeDecode(event.request.headers.get('x-cairn-alt')), MAX_ALT);
+    const displayNameRaw = sanitizeField(safeDecode(event.request.headers.get('x-cairn-display-name')), MAX_DISPLAY_NAME);
+    const displayName = displayNameRaw || slug;
+    const width = clampDimension(event.request.headers.get('x-cairn-width'));
+    const height = clampDimension(event.request.headers.get('x-cairn-height'));
+
+    // 7. Store put-first with R2-head dedup, commit nothing. The raw bucket binding lives on
+    //    platform.env, which the engine reads through a structural cast (the engine does not declare
+    //    App.Platform). r2Store wraps it as the narrow MediaStore seam; R2Bucket is named only for
+    //    this cast and never in an exported signature.
+    const platformEnv = (event.platform as { env?: Record<string, unknown> } | undefined)?.env ?? {};
+    const rawBucket = platformEnv[resolved.bucketBinding];
+    if (!rawBucket) return refuse(503, 'binding-missing');
+    const store = r2Store(rawBucket as R2Bucket);
+
+    const key = r2Key(hash, ext);
+    const existing = await store.head(key);
+    let reused: boolean;
+    let mismatch = false;
+    if (existing !== null) {
+      // The key derives from the 16-hex short hash (64 bits), so a distinct file could in principle
+      // collide on it. The put stores the full sha256 as custom metadata; verify it here. A stored
+      // sha256 that differs from this upload's full hash is a genuine short-hash collision: refuse,
+      // never serve the first file's bytes under the second's reference. A stored object with no
+      // sha256 (a legacy or manually-put object we cannot verify) proceeds as a dedup hit, best effort.
+      const storedSha = existing.customMetadata?.sha256;
+      if (storedSha !== undefined && storedSha !== full) return refuse(409, 'hash-collision');
+      // Identical bytes are already stored: skip the put. A second upload does no second put, so a
+      // concurrent dedup-reuse is never clobbered. Flag a stored type that disagrees with this sniff.
+      reused = true;
+      mismatch = existing.httpMetadata?.contentType !== undefined && existing.httpMetadata.contentType !== sniffed;
+    } else {
+      await store.put(
+        key,
+        bytes,
+        { contentType: sniffed, cacheControl: 'public, max-age=31536000, immutable' },
+        { sha256: full },
+      );
+      reused = false;
+    }
+
+    const record: MediaEntry = {
+      hash,
+      sha256: full,
+      slug,
+      displayName,
+      originalFilename,
+      alt,
+      ext,
+      contentType: sniffed,
+      bytes: bytes.length,
+      width,
+      height,
+      createdAt: new Date().toISOString(),
+    };
+    const reference = mediaToken({ slug, hash });
+
+    log.info('media.uploaded', { editor: editor.email, hash, bytes: bytes.length, contentType: sniffed, reused });
+    return { reference, record, reused, mismatch };
+  }
+
+  /** A media slug is the same lowercase-alphanumeric-with-hyphens grammar the reference token uses. */
+  const MEDIA_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+  /** A 16-hex content-hash prefix, the immutable asset key. */
+  const MEDIA_HASH_RE = /^[0-9a-f]{16}$/;
+
+  /** Safe-delete a committed media asset. The gate rechecks usage server-side against a FRESH index
+   *  read at delete time (never a client-passed count), mirroring deleteEntry's authoritative inbound
+   *  recheck. An in-use asset refuses unless the form carries the typed-slug override (the in-use
+   *  alertdialog's type-to-confirm). When confirmed, the order is load-bearing: commit the manifest
+   *  row removal FIRST, then delete the R2 object, so a failure after the commit leaves bytes with no
+   *  row (a benign orphan) rather than a row pointing at deleted bytes (a broken delivery). Scope:
+   *  3c deletes assets committed on the default branch; a branch-only upload is removed by discarding
+   *  its draft, not here.
+   *
+   *  The published-usage side of the gate trusts the content manifest's mediaRefs (kept fresh by
+   *  save/publish via manifestEntryFromFile), the same manifest-trust model the entry-delete gate
+   *  uses; a raw git edit that adds a media reference without a save/publish or a manifest regenerate
+   *  is not seen, matching the documented "regenerate after a raw edit" contract. The recheck reads
+   *  in STRICT mode, so a transient branch-read failure fails the delete closed rather than mistaking
+   *  a referenced asset for an orphan. There is an inherent stale-read window between the recheck and
+   *  the commit (no sha-guard ties them); it is bounded because the resolver and the route key on the
+   *  hash, so a reference added in that window still resolves to bytes that may be gone, the same
+   *  delete-races-an-edit window every safe delete carries. */
+  async function mediaDeleteAction(event: ContentEvent): Promise<ReturnType<typeof fail> | never> {
+    const editor = requireSession(event);
+    const token = await mintToken(event.platform?.env ?? {});
+
+    const form = await event.request.formData();
+    const hash = String(form.get('hash') ?? '');
+    if (!MEDIA_HASH_RE.test(hash)) throw error(400, 'Invalid media hash');
+
+    // The asset must be committed on the default branch to be deletable here. A branch-only upload
+    // (the common 2b case before publish) has no main row; removing it is a discard of the draft.
+    const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+    const row = manifest[hash];
+    if (!row) {
+      return fail(404, {
+        error: 'That asset is not committed. Discard its draft to remove an unpublished upload.',
+        hash,
+        usage: [],
+        foundIn: 0,
+      } satisfies MediaDeleteRefusal);
+    }
+
+    // The authoritative gate: a fresh usage read, never a client count. The index spans main's
+    // content manifest and every open cairn/* branch. STRICT mode rethrows a branch-read failure
+    // (rather than the display path's degrade-and-skip), so a transient branch read failing does not
+    // make a still-referenced asset look orphaned and skip the typed-slug confirm.
+    let index: Awaited<ReturnType<typeof buildUsageIndex>>;
+    try {
+      index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+    } catch {
+      // Fail closed: we could not verify every place the asset is used, so refuse rather than risk
+      // deleting bytes a branch still references.
+      return fail(503, {
+        error: 'Could not verify where this asset is used. Try again.',
+        hash,
+        usage: [],
+        foundIn: 0,
+      } satisfies MediaDeleteRefusal);
+    }
+    const rows = index.get(hash) ?? [];
+    const foundIn = distinctEntryCount(rows);
+
+    if (rows.length > 0) {
+      // In use: refuse unless the editor typed the slug to force it (the in-use face's confirmation).
+      // An empty stored slug must never be satisfiable by the empty default, so a blank row.slug is
+      // treated as never-confirmed: the typed confirm cannot be bypassed.
+      const confirmSlug = String(form.get('confirmSlug') ?? '');
+      if (row.slug === '' || confirmSlug !== row.slug) {
+        log.warn('media.delete_blocked', { editor: editor.email, hash, foundIn });
+        // Group published-first, then branch entries by branch name, so the list reads stably.
+        const usage = [...rows].sort((a, b) => originRank(a) - originRank(b) || branchKey(a).localeCompare(branchKey(b)));
+        return fail(409, {
+          error: `Cannot delete ${row.slug}: found in ${foundIn} ${foundIn === 1 ? 'entry' : 'entries'}.`,
+          hash,
+          usage,
+          foundIn,
+        } satisfies MediaDeleteRefusal);
+      }
+    }
+
+    // Resolve the R2 bucket before the commit, so a missing binding refuses before any write.
+    const resolved = runtime.resolvedAssets;
+    if (!resolved.enabled) {
+      return fail(503, { error: 'Media is not enabled for this site.', hash, usage: [], foundIn } satisfies MediaDeleteRefusal);
+    }
+    const platformEnv = (event.platform as { env?: Record<string, unknown> } | undefined)?.env ?? {};
+    const rawBucket = platformEnv[resolved.bucketBinding];
+    if (!rawBucket) {
+      return fail(503, { error: 'The media bucket is not bound.', hash, usage: [], foundIn } satisfies MediaDeleteRefusal);
+    }
+    const store = r2Store(rawBucket as R2Bucket);
+    // Derive the R2 key BEFORE the commit. A corrupt ext throws here, so a bad key refuses before
+    // any write rather than after the row is already removed (which would orphan the bytes).
+    const objectKey = r2Key(hash, row.ext);
+
+    // Commit the manifest row removal FIRST. The order is load-bearing (see the docstring).
+    const commitFields = { concept: 'media', id: hash, editor: editor.email };
+    try {
+      await commitFiles(
+        runtime.backend,
+        [{ path: runtime.mediaManifestPath, content: serializeMediaManifest(removeMediaEntry(manifest, hash)) }],
+        { message: `Delete media: ${row.slug}`, author: { name: editor.displayName, email: editor.email } },
+        token,
+      );
+      log.info('commit.succeeded', commitFields);
+    } catch (err) {
+      commitFailure(commitFields, err, '/admin/media',
+        'The media manifest changed since you opened it. Reload and try again.');
+    }
+    // THEN delete the object. An absent object is a no-op (the R2 contract), so a dead row clears.
+    await store.delete(objectKey);
+    log.info('media.deleted', { editor: editor.email, hash });
+    throw redirect(303, '/admin/media?deleted=1');
+  }
+
+  /** Edit a committed asset's metadata: its display name, slug, and default alt. A single media.json
+   *  row commit, with NO reference rewrite: the resolver and the delivery route key on the hash, so a
+   *  rename never breaks an existing `media:` reference. The default alt is the asset's value for the
+   *  next placement, never a propagating edit of the alt already committed in existing placements. */
+  async function mediaUpdateAction(event: ContentEvent): Promise<ReturnType<typeof fail> | never> {
+    const editor = requireSession(event);
+    const token = await mintToken(event.platform?.env ?? {});
+
+    const form = await event.request.formData();
+    const hash = String(form.get('hash') ?? '');
+    if (!MEDIA_HASH_RE.test(hash)) throw error(400, 'Invalid media hash');
+
+    const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+    const row = manifest[hash];
+    if (!row) {
+      return fail(404, { error: 'That asset is not committed.' } satisfies MediaUpdateFailure);
+    }
+
+    const displayName = sanitizeField(String(form.get('displayName') ?? ''), MAX_DISPLAY_NAME);
+    const slug = String(form.get('slug') ?? '').trim();
+    const alt = sanitizeField(String(form.get('alt') ?? ''), MAX_ALT);
+    if (!MEDIA_SLUG_RE.test(slug)) {
+      return fail(400, { error: 'Enter a valid slug: lowercase letters, numbers, and hyphens.' } satisfies MediaUpdateFailure);
+    }
+
+    const edited: MediaEntry = { ...row, displayName: displayName || slug, slug, alt };
+    const commitFields = { concept: 'media', id: hash, editor: editor.email };
+    try {
+      await commitFiles(
+        runtime.backend,
+        [{ path: runtime.mediaManifestPath, content: serializeMediaManifest(upsertMediaEntry(manifest, edited)) }],
+        { message: `Update media: ${edited.slug}`, author: { name: editor.displayName, email: editor.email } },
+        token,
+      );
+      log.info('commit.succeeded', commitFields);
+    } catch (err) {
+      commitFailure(commitFields, err, '/admin/media',
+        'The media manifest changed since you opened it. Reload and try again.');
+    }
+    throw redirect(303, '/admin/media?updated=1');
+  }
+
+  return { layoutLoad, indexRedirect, listLoad, mediaLibraryLoad, createAction, editLoad, saveAction, publishAction, publishAllAction, discardAction, deleteAction, listDeleteAction, renameAction, uploadAction, mediaDeleteAction, mediaUpdateAction, mintToken };
+}
+
+/** The cap, in characters, on the stored alt text. The human fields are display copy, not content,
+ *  so a generous cap rejects only abuse-scale input. */
+const MAX_ALT = 160;
+/** The cap, in characters, on the stored display name. */
+const MAX_DISPLAY_NAME = 120;
+/** The cap, in characters, on the stored original filename. */
+const MAX_ORIGINAL_FILENAME = 120;
+/** The largest pixel dimension kept; anything larger is treated as bogus and clamped to null. */
+const MAX_DIMENSION = 60000;
+
+/** Decode a percent-encoded header value, yielding `''` on a malformed sequence or an absent header,
+ *  so a hostile `X-Cairn-*` value cannot throw past the gate. */
+function safeDecode(value: string | null): string {
+  if (value === null) return '';
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return '';
+  }
+}
+
+/** The basename of a decoded filename: the final path segment after any `/` or `\`. A client value
+ *  of `../../evil.png` yields `evil.png`, so no path component reaches the stored record. */
+function basename(name: string): string {
+  const parts = name.split(/[/\\]/);
+  return parts[parts.length - 1];
+}
+
+/** Sort key for a where-used row's origin: published rows rank before branch rows, so the in-use
+ *  refusal lists "Published on the site" first, then the edit-branch references. */
+function originRank(entry: UsageEntry): number {
+  return entry.origin.kind === 'published' ? 0 : 1;
+}
+
+/** A where-used row's branch name for the secondary sort (the empty string for a published row,
+ *  which sorts ahead of any branch by `originRank` already). */
+function branchKey(entry: UsageEntry): string {
+  return entry.origin.kind === 'branch' ? entry.origin.branch : '';
+}
+
+/** The distinct-entry count behind a where-used set: a published use and an edit-branch edit of the
+ *  same entry are two rows but one distinct entry, so count by concept/id. */
+function distinctEntryCount(rows: UsageEntry[]): number {
+  return new Set(rows.map((e) => `${e.concept}/${e.id}`)).size;
+}
+
+/** Strip control characters from a human field and cap it at `max` characters. Control characters
+ *  (C0 and DEL) never belong in display copy and could corrupt a log line or a committed JSON. */
+function sanitizeField(value: string, max: number): string {
+  // eslint-disable-next-line no-control-regex
+  return value.replace(/[\u0000-\u001f\u007f]/g, '').slice(0, max);
+}
+
+/** Parse an advisory pixel dimension header. A valid integer in `[1, MAX_DIMENSION]` is kept; an
+ *  absent, non-numeric, or out-of-range value becomes null (MediaEntry dimensions are `number | null`). */
+function clampDimension(value: string | null): number | null {
+  if (value === null) return null;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > MAX_DIMENSION) return null;
+  return n;
 }