@glw907/cairn-cms 0.56.2 → 0.57.1

package/dist/sveltekit/content-routes.js

@@ -17,8 +17,15 @@ import { cachedInstallationToken } from '../github/signing.js';
 import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest, upsertEntry, removeEntry, inboundLinks } 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 { mediaLibraryEntry } from '../media/library-entry.js';
+import { buildUsageIndex } from '../media/usage.js';
 /** 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.
  *  Stylesheets are always shared, and the `byConcept` map never reaches the client. */
@@ -47,6 +54,19 @@ export function createContentRoutes(runtime, deps = {}) {
         const raw = await readRaw(runtime.backend, runtime.manifestPath, token);
         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) {
+        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
@@ -191,6 +211,78 @@ export function createContentRoutes(runtime, deps = {}) {
             return { ...base, entries: [], error: 'Could not load this content type from GitHub.' };
         }
     }
+    /** 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) {
+        requireSession(event);
+        // Read the flash flags a redirected action carried back, mirroring listLoad's `?error`/
+        // `?publishedAll` grammar: a deleted/updated success flag and a commit-conflict error. The
+        // conflict error rides its own slot so it never collides with the degraded-load `error` below.
+        let flash = null;
+        if (event.url.searchParams.get('deleted') === '1')
+            flash = 'deleted';
+        else if (event.url.searchParams.get('updated') === '1')
+            flash = 'updated';
+        const flashError = event.url.searchParams.get('error');
+        let token;
+        try {
+            token = await mintToken(event.platform?.env ?? {});
+        }
+        catch {
+            return { assets: [], usage: {}, error: 'Could not authenticate with GitHub.', flash, flashError };
+        }
+        // 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();
+        let branchNames = [];
+        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(() => ({}))));
+            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.', flash, flashError };
+        }
+        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 = {};
+        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, flash, flashError };
+    }
     /** Create a new entry: validate the slug, compose a dated id when the concept is dated, refuse to clobber. */
     async function createAction(event) {
         requireSession(event);
@@ -233,6 +325,10 @@ export function createContentRoutes(runtime, deps = {}) {
                 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);
         }
@@ -256,10 +352,16 @@ export function createContentRoutes(runtime, deps = {}) {
         // 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;
@@ -282,6 +384,15 @@ export function createContentRoutes(runtime, deps = {}) {
             }));
             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 = {};
+        const 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,
@@ -296,6 +407,8 @@ export function createContentRoutes(runtime, deps = {}) {
             error: event.url.searchParams.get('error'),
             slug: slugFromId(id, datePrefix),
             linkTargets,
+            mediaTargets,
+            mediaLibrary,
             inboundLinks: inbound,
             pending,
             published,
@@ -343,6 +456,24 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         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;
+        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);
@@ -388,13 +519,13 @@ export function createContentRoutes(runtime, deps = {}) {
         const commitFields = { concept: concept.id, id, editor: editor.email, branch };
         let branchSha;
         try {
-            branchSha = await commitFiles({ ...runtime.backend, branch }, [{ path, content: markdown }], { message: `Update ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } }, token);
+            branchSha = await commitFiles({ ...runtime.backend, branch }, mediaChange ? [{ path, content: markdown }, mediaChange] : [{ path, content: markdown }], { message: `Update ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } }, token);
             log.info('commit.succeeded', commitFields);
         }
         catch (err) {
             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
      *  as author. Main and its manifest stay untouched until publish. Fails safe on 409. */
@@ -429,13 +560,19 @@ export function createContentRoutes(runtime, deps = {}) {
         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 = [
+            { 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) },
-            ], { message: `Publish ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } }, token);
+            await commitFiles(runtime.backend, changes, { message: `Publish ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } }, token);
             log.info('entry.published', { ...commitFields, batch: false });
         }
         catch (err) {
@@ -698,5 +835,328 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         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) {
+        // 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, reason) => {
+            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?.env ?? {};
+        const rawBucket = platformEnv[resolved.bucketBinding];
+        if (!rawBucket)
+            return refuse(503, 'binding-missing');
+        const store = r2Store(rawBucket);
+        const key = r2Key(hash, ext);
+        const existing = await store.head(key);
+        let reused;
+        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 = {
+            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) {
+        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,
+            });
+        }
+        // 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;
+        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,
+            });
+        }
+        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,
+                });
+            }
+        }
+        // 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 });
+        }
+        const platformEnv = event.platform?.env ?? {};
+        const rawBucket = platformEnv[resolved.bucketBinding];
+        if (!rawBucket) {
+            return fail(503, { error: 'The media bucket is not bound.', hash, usage: [], foundIn });
+        }
+        const store = r2Store(rawBucket);
+        // 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) {
+        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.' });
+        }
+        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.' });
+        }
+        const edited = { ...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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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, max) {
+    // 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) {
+    if (value === null)
+        return null;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > MAX_DIMENSION)
+        return null;
+    return n;
 }

package/dist/sveltekit/csrf.d.ts

@@ -14,5 +14,21 @@ export declare function issueCsrfToken(event: {
     url: URL;
     cookies: CookieJar;
 }): string;
+/**
+ * Validate the double-submit token on a raw-body upload POST, reading the submitted token from the
+ * `X-Cairn-CSRF` request header rather than a form field. The upload's file bytes are the request
+ * body and are read once, so the form-field path (which clones the body to read `formData`) does not
+ * apply; the action carries the CSRF authority for uploads instead. Compares the header against the
+ * csrf cookie the loads issue, constant-time.
+ *
+ * Security rests on a custom request header being unsettable cross-origin without a CORS preflight:
+ * never add a permissive `Access-Control-Allow-Headers: x-cairn-csrf` (or an allow-origin) for
+ * `/admin` or `/media`, or this header witness collapses.
+ */
+export declare function validateCsrfHeader(event: {
+    url: URL;
+    request: Request;
+    cookies: CookieJar;
+}): boolean;
 /** Validate the double-submit token on an admin form POST, reading the field from a body clone. */
 export declare function validateCsrfToken(event: RequestContext): Promise<boolean>;

package/dist/sveltekit/csrf.js

@@ -43,6 +43,24 @@ export function issueCsrfToken(event) {
     event.cookies.set(name, token, { path: '/', httpOnly: true, secure, sameSite: 'strict' });
     return token;
 }
+/**
+ * Validate the double-submit token on a raw-body upload POST, reading the submitted token from the
+ * `X-Cairn-CSRF` request header rather than a form field. The upload's file bytes are the request
+ * body and are read once, so the form-field path (which clones the body to read `formData`) does not
+ * apply; the action carries the CSRF authority for uploads instead. Compares the header against the
+ * csrf cookie the loads issue, constant-time.
+ *
+ * Security rests on a custom request header being unsettable cross-origin without a CORS preflight:
+ * never add a permissive `Access-Control-Allow-Headers: x-cairn-csrf` (or an allow-origin) for
+ * `/admin` or `/media`, or this header witness collapses.
+ */
+export function validateCsrfHeader(event) {
+    const cookie = event.cookies.get(csrfCookieName(event.url.protocol === 'https:'));
+    if (!cookie)
+        return false;
+    const submitted = event.request.headers.get('x-cairn-csrf') ?? '';
+    return tokensMatch(submitted, cookie);
+}
 /** Validate the double-submit token on an admin form POST, reading the field from a body clone. */
 export async function validateCsrfToken(event) {
     const cookie = event.cookies.get(csrfCookieName(event.url.protocol === 'https:'));

package/dist/sveltekit/guard.js

@@ -4,7 +4,7 @@
 import { redirect, error } from '@sveltejs/kit';
 import { resolveSession } from '../auth/store.js';
 import { sessionCookieName } from '../auth/crypto.js';
-import { isUnsafeFormRequest, originMatches, validateCsrfToken } from './csrf.js';
+import { isUnsafeFormRequest, originMatches, validateCsrfToken, validateCsrfHeader } from './csrf.js';
 import { applySecurityHeaders } from './admin-response.js';
 import { renderConditionResponse, REASON_CONDITION } from './condition-response.js';
 import { log } from '../log/index.js';
@@ -63,8 +63,15 @@ export function createAuthGuard() {
             return renderConditionResponse(REASON_CONDITION.bindings);
         }
         // Rule 1 - admin: every unsafe form POST carries a valid double-submit token, else the branded
-        // 403 before resolve() runs. This covers the public login/auth posts too.
-        if (isUnsafeFormRequest(event.request) && !(await validateCsrfToken(event))) {
+        // 403 before resolve() runs. This covers the public login/auth posts too. The header witness is
+        // tried first: a valid X-Cairn-CSRF header clears the request without cloning the body, which is
+        // how the raw-body media upload (a text/plain POST) passes CSRF. A custom header cannot be set
+        // cross-origin without a CORS preflight, so it is as strong a token witness as the form field.
+        // Only with no valid header does the form-field path run and clone the body to read the token,
+        // the unchanged path for every ordinary admin form post.
+        if (isUnsafeFormRequest(event.request) &&
+            !validateCsrfHeader(event) &&
+            !(await validateCsrfToken(event))) {
             log.warn('guard.rejected', { reason: 'csrf', path: pathname });
             return renderConditionResponse('auth.csrf-token-invalid');
         }

package/dist/sveltekit/index.d.ts

@@ -2,7 +2,8 @@ export { createAuthGuard, requireSession, requireOwner } from './guard.js';
 export { createAuthRoutes, type AuthRoutesConfig, type RequestResult } from './auth-routes.js';
 export { createEditorRoutes } from './editors-routes.js';
 export { createContentRoutes } from './content-routes.js';
-export type { NavConcept, LayoutData, EntrySummary, ListData, EditData, ContentEvent, ContentRoutesDeps, SaveFailure, DeleteRefusal, RenameFailure, ContentFormFailure, } from './content-routes.js';
+export { createMediaRoute } from './media-route.js';
+export type { NavConcept, LayoutData, EntrySummary, ListData, EditData, MediaUsageInfo, MediaLibraryData, ContentEvent, ContentRoutesDeps, SaveFailure, DeleteRefusal, RenameFailure, MediaDeleteRefusal, MediaUpdateFailure, ContentFormFailure, UploadResult, } from './content-routes.js';
 export { createNavRoutes } from './nav-routes.js';
 export type { NavLoadData, NavPageOption, NavRoutesDeps } from './nav-routes.js';
 export { parseAdminPath, type AdminView } from './admin-dispatch.js';