@glw907/cairn-cms 0.56.1 → 0.57.0

package/dist/sveltekit/media-route.d.ts

@@ -0,0 +1,12 @@
+import type { RequestHandler } from '@sveltejs/kit';
+import type { ResolvedAssetConfig } from '../media/config.js';
+/**
+ * Build the media delivery `RequestHandler` for a site's resolved media config.
+ *
+ * The handler validates the hash and extension before any R2 call, derives the object key from the
+ * validated values only (never trusting the URL's fan-out), guards the Cloudflare Images self-loop,
+ * and sets the security headers on every served response.
+ *
+ * @param resolved the adapter's resolved media config; when media is off the handler always 404s.
+ */
+export declare function createMediaRoute(resolved: ResolvedAssetConfig): RequestHandler;

package/dist/sveltekit/media-route.js

@@ -0,0 +1,137 @@
+import { requireBucket } from '../env.js';
+import { CairnError } from '../diagnostics/index.js';
+import { r2Key } from '../media/naming.js';
+import { log } from '../log/index.js';
+/** A 16-character lowercase hex content-hash prefix, validated before any R2 lookup. */
+const HASH_RE = /^[0-9a-f]{16}$/;
+/** The closed delivery extension allow-list. A filename ext outside this set is a 404 with no R2
+ *  read, so the route can never serve a type it cannot vouch for. */
+const DELIVERY_EXTS = new Set(['jpg', 'jpeg', 'png', 'gif', 'webp', 'avif']);
+/** The load-bearing XSS control: set on every non-404 response, so a served object can never run as
+ *  active content. `Content-Type` comes from the stored, server-validated metadata via
+ *  `writeHttpMetadata`; these override or add to it. */
+function applySecurityHeaders(headers, etag) {
+    headers.set('X-Content-Type-Options', 'nosniff');
+    headers.set('Content-Disposition', 'inline');
+    headers.set('Content-Security-Policy', "default-src 'none'; sandbox");
+    headers.set('Cache-Control', 'public, max-age=31536000, immutable');
+    headers.set('ETag', etag);
+    // An object stored outside the upload pipeline (a manual put, a future import) may carry no
+    // content type, so writeHttpMetadata would set none. Pair `nosniff` with an explicit safe
+    // default rather than serving a typeless response.
+    if (!headers.has('Content-Type'))
+        headers.set('Content-Type', 'application/octet-stream');
+}
+/** True when the returned object carries a body (a full or ranged read), narrowing it to the body
+ *  variant. R2 returns a body-less object on an `If-None-Match` hit. */
+function hasBody(obj) {
+    return 'body' in obj && obj.body != null;
+}
+/**
+ * Build the media delivery `RequestHandler` for a site's resolved media config.
+ *
+ * The handler validates the hash and extension before any R2 call, derives the object key from the
+ * validated values only (never trusting the URL's fan-out), guards the Cloudflare Images self-loop,
+ * and sets the security headers on every served response.
+ *
+ * @param resolved the adapter's resolved media config; when media is off the handler always 404s.
+ */
+export function createMediaRoute(resolved) {
+    return async (event) => {
+        // Media off: the route is mounted but serves nothing.
+        if (!resolved.enabled)
+            return new Response(null, { status: 404 });
+        // The catch-all param is conventionally `path` (route `/media/[...path]`). Decode each segment
+        // on its own and reject a traversal or an embedded slash, so no undecoded or `..` path reaches
+        // R2. params.path is `string | undefined` (kit's fallback ambient types), so guard the absence.
+        const raw = event.params.path;
+        if (typeof raw !== 'string' || raw === '')
+            return new Response(null, { status: 404 });
+        const segments = [];
+        for (const part of raw.split('/')) {
+            let decoded;
+            try {
+                decoded = decodeURIComponent(part);
+            }
+            catch {
+                return new Response(null, { status: 404 });
+            }
+            if (decoded === '' || decoded.includes('/') || decoded === '..') {
+                return new Response(null, { status: 404 });
+            }
+            segments.push(decoded);
+        }
+        // The filename is the last segment; its dot fields end with `<hash>.<ext>`. The slug, if any, is
+        // attacker-controlled and ignored. parseMediaToken does not run here.
+        const filename = segments[segments.length - 1];
+        const fields = filename.split('.');
+        if (fields.length < 2)
+            return new Response(null, { status: 404 });
+        const ext = fields[fields.length - 1].toLowerCase();
+        const hash = fields[fields.length - 2];
+        // Validate before any R2 call: a bad hash or ext is a 404 with no read.
+        if (!HASH_RE.test(hash) || !DELIVERY_EXTS.has(ext)) {
+            return new Response(null, { status: 404 });
+        }
+        // Derive the key from the validated values only; r2Key recomputes the fan-out from the hash.
+        const key = r2Key(hash, ext);
+        // Resolve the bucket. A missing binding is a drained 503 with a log, never a thrown 500.
+        let bucket;
+        try {
+            // `event.platform` is `App.Platform`, which the engine does not declare (a site does, with an
+            // `env`), so read it through a structural cast rather than naming the site's ambient type.
+            const platform = event.platform;
+            bucket = requireBucket(platform?.env ?? {}, resolved.bucketBinding);
+        }
+        catch (err) {
+            if (err instanceof CairnError && err.conditionId === 'config.bindings-missing') {
+                log.warn('media.delivery_failed', {
+                    reason: 'binding-missing',
+                    binding: resolved.bucketBinding,
+                });
+                return new Response(null, { status: 503 });
+            }
+            throw err;
+        }
+        // Self-loop guard: the Cloudflare Images origin subrequest carries `Via: image-resizing`. Serve
+        // it a clean full-body 200 with no conditional or range handling, so a transform cannot loop.
+        const via = event.request.headers.get('Via') ?? '';
+        const isImageResizing = via.includes('image-resizing');
+        // Only forward `range` when the request actually carried a `Range` header. R2 populates the
+        // returned object's `.range` whenever a `range` option is passed (even a header-less one), so
+        // passing it unconditionally would turn every full GET into a 206.
+        const hasRangeRequest = !isImageResizing && event.request.headers.has('Range');
+        const getOpts = isImageResizing
+            ? undefined
+            : {
+                onlyIf: event.request.headers,
+                ...(hasRangeRequest ? { range: event.request.headers } : {}),
+            };
+        const obj = await bucket.get(key, getOpts);
+        if (obj === null)
+            return new Response(null, { status: 404 });
+        // A body-less object is R2's `If-None-Match` hit: 304, no body. Skipped for the self-loop path,
+        // which always requested the full body.
+        if (!isImageResizing && !hasBody(obj)) {
+            const headers = new Headers();
+            obj.writeHttpMetadata(headers);
+            applySecurityHeaders(headers, obj.httpEtag);
+            return new Response(null, { status: 304, headers });
+        }
+        const headers = new Headers();
+        obj.writeHttpMetadata(headers);
+        applySecurityHeaders(headers, obj.httpEtag);
+        // A ranged read carries `obj.range`: respond 206 with a Content-Range. R2 fills the served
+        // window; derive the bounds defensively against the full size.
+        if (hasRangeRequest && obj.range) {
+            const start = obj.range.offset ?? 0;
+            const length = obj.range.length ?? obj.size - start;
+            const end = start + length - 1;
+            headers.set('Content-Range', `bytes ${start}-${end}/${obj.size}`);
+            const body = hasBody(obj) ? obj.body : null;
+            return new Response(body, { status: 206, headers });
+        }
+        const body = hasBody(obj) ? obj.body : null;
+        return new Response(body, { status: 200, headers });
+    };
+}

package/dist/vite/index.d.ts

@@ -40,6 +40,9 @@ export interface AdapterFacts {
     repo?: string;
     /** `cairn.sender.from`. */
     from?: string;
+    /** `cairn.assets.bucketBinding`, the media R2 binding name; undefined when the adapter declares no
+     *  assets. The doctor's conditional media-bucket check reads it. */
+    mediaBucketBinding?: string;
 }
 /** Read `{ owner, repo, from }` off the consumer's adapter by evaluating a tiny virtual module
  *  through the consumer's own Vite resolution, the same machinery the cairn-manifest bin uses.

package/dist/vite/index.js

@@ -181,17 +181,20 @@ function cairnVirtualOnly(source) {
     };
 }
 /** Build the virtual module that reads only the adapter facts the doctor derives. It imports the
- *  configured config module and exports the string-typed `owner`, `repo`, and `from` as JSON, so
- *  nothing else of the adapter (least of all a secret) crosses the boundary. */
+ *  configured config module and exports the string-typed `owner`, `repo`, `from`, and the media
+ *  `bucketBinding` as JSON, so nothing else of the adapter (least of all a secret) crosses the
+ *  boundary. */
 function adapterFactsSource(opts) {
     return `
 import { cairn } from ${JSON.stringify(opts.configModule)};
 const backend = cairn?.backend ?? {};
 const sender = cairn?.sender ?? {};
+const assets = cairn?.assets ?? {};
 const facts = {};
 if (typeof backend.owner === 'string') facts.owner = backend.owner;
 if (typeof backend.repo === 'string') facts.repo = backend.repo;
 if (typeof sender.from === 'string') facts.from = sender.from;
+if (typeof assets.bucketBinding === 'string') facts.mediaBucketBinding = assets.bucketBinding;
 export const result = JSON.stringify(facts);
 `;
 }
@@ -218,6 +221,8 @@ export async function readAdapterFacts(cwd = process.cwd()) {
             facts.repo = parsed.repo;
         if (typeof parsed.from === 'string')
             facts.from = parsed.from;
+        if (typeof parsed.mediaBucketBinding === 'string')
+            facts.mediaBucketBinding = parsed.mediaBucketBinding;
         return facts;
     }
     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.56.1",
+  "version": "0.57.0",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "sideEffects": [
@@ -32,6 +32,7 @@
     "check:reference:signatures": "npm run package && node scripts/check-reference-signatures.mjs",
     "check:readiness": "npm run package && node scripts/check-readiness.mjs",
     "check:docs": "node scripts/docs-links.mjs",
+    "check:version": "node scripts/check-version.mjs",
     "check:prose": "node scripts/check-admin-prose.mjs",
     "prepare": "npm run package",
     "check": "svelte-check --tsconfig ./tsconfig.json",
@@ -77,6 +78,11 @@
       "svelte": "./dist/delivery/data.js",
       "default": "./dist/delivery/data.js"
     },
+    "./media": {
+      "types": "./dist/media/index.d.ts",
+      "svelte": "./dist/media/index.js",
+      "default": "./dist/media/index.js"
+    },
     "./vite": {
       "types": "./dist/vite/index.d.ts",
       "default": "./dist/vite/index.js"
@@ -116,6 +122,7 @@
     "gray-matter": "^4",
     "hast-util-sanitize": "^5.0.2",
     "hastscript": "^9.0.1",
+    "heic-to": "^1.5.2",
     "mdast-util-directive": "^3.1.0",
     "rehype-raw": "^7.0.0",
     "rehype-sanitize": "^6.0.0",

package/src/lib/components/AdminLayout.svelte

@@ -20,6 +20,7 @@ identical on every host regardless of the site's own theme.
   import SignpostIcon from '@lucide/svelte/icons/signpost';
   import SettingsIcon from '@lucide/svelte/icons/settings';
   import UsersIcon from '@lucide/svelte/icons/users';
+  import ImageIcon from '@lucide/svelte/icons/image';
   import BlocksIcon from '@lucide/svelte/icons/blocks';
   import ExternalLinkIcon from '@lucide/svelte/icons/external-link';
   import './cairn-admin.css';
@@ -56,6 +57,8 @@ identical on every host regardless of the site's own theme.
   // the owner-only Editors.
   const coreItems: NavItem[] = $derived([
     ...data.concepts.map((c) => ({ label: c.label, icon: FileTextIcon, href: `/admin/${c.id}` })),
+    // Media is a content peer, immediately after the concepts.
+    { label: 'Media', icon: ImageIcon, href: '/admin/media' },
     ...(data.navLabel ? [{ label: data.navLabel, icon: SignpostIcon, href: '/admin/nav' }] : []),
     { label: 'Settings', icon: SettingsIcon, href: '/admin/settings' },
     ...(data.canManageEditors ? [{ label: 'Editors', icon: UsersIcon, href: '/admin/editors' }] : []),

package/src/lib/components/CairnAdmin.svelte

@@ -13,11 +13,13 @@ mount inside `AdminLayout`. No styling or wrapper elements of its own.
   import EditPage from './EditPage.svelte';
   import ManageEditors from './ManageEditors.svelte';
   import NavTree from './NavTree.svelte';
+  import CairnMediaLibrary from './CairnMediaLibrary.svelte';
   import type { AdminData } from '../sveltekit/cairn-admin.js';
   import type { ContentFormFailure } from '../sveltekit/content-routes.js';
   import type { ComponentRegistry } from '../render/registry.js';
   import type { IconSet } from '../render/glyph.js';
   import type { LinkResolve } from '../content/links.js';
+  import type { MediaResolve } from '../render/resolve-media.js';
 
   interface Props {
     /** The discriminated view data from `createCairnAdmin`'s load. */
@@ -33,7 +35,10 @@ mount inside `AdminLayout`. No styling or wrapper elements of its own.
         })
       | null;
     /** The site's design-accurate render pipeline, for the edit view's preview pane. */
-    render?: (md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }) => string | Promise<string>;
+    render?: (
+      md: string,
+      opts?: { stagger?: boolean; resolve?: LinkResolve; resolveMedia?: MediaResolve },
+    ) => string | Promise<string>;
     /** The site's component registry, for the edit view's insert palette. */
     registry?: ComponentRegistry;
     /** The site's icon set, for the edit view's guided form fields. */
@@ -62,6 +67,8 @@ mount inside `AdminLayout`. No styling or wrapper elements of its own.
       <ManageEditors data={data.page} {form} />
     {:else if data.view === 'nav'}
       <NavTree data={data.page} />
+    {:else if data.view === 'media'}
+      <CairnMediaLibrary data={data.page} {form} />
     {/if}
   </AdminLayout>
 {/if}