@glw907/cairn-cms 0.56.2 → 0.57.0

package/src/lib/sveltekit/csrf.ts

@@ -46,6 +46,24 @@ export function issueCsrfToken(event: { url: URL; cookies: CookieJar }): string
   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: { url: URL; request: Request; cookies: CookieJar }): boolean {
+  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: RequestContext): Promise<boolean> {
   const cookie = event.cookies.get(csrfCookieName(event.url.protocol === 'https:'));

package/src/lib/sveltekit/guard.ts

@@ -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';
@@ -75,8 +75,17 @@ export function createAuthGuard() {
     }
 
     // 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/src/lib/sveltekit/index.ts

@@ -4,18 +4,24 @@ 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 { 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';

package/src/lib/sveltekit/media-route.ts

@@ -0,0 +1,158 @@
+// The media delivery route: an engine-provided SvelteKit RequestHandler a site mounts at
+// `/media/[...path]`. It streams content-addressed bytes from R2 with the security headers that are
+// the load-bearing XSS control for served media. The route sits outside `/admin`, so the admin
+// security headers never run on it; it owns its own.
+//
+// It lives on the `/sveltekit` barrel, not the node-safe `/media` subpath, because it reads
+// `platform.env`, which pulls `@sveltejs/kit` into its graph. Its public signature names only kit
+// (a peer dependency) and web globals, never an `@cloudflare/workers-types` type (decision 5).
+import type { RequestHandler } from '@sveltejs/kit';
+import { requireBucket } from '../env.js';
+import { CairnError } from '../diagnostics/index.js';
+import { r2Key } from '../media/naming.js';
+import { log } from '../log/index.js';
+import type { DeliveryObject, DeliveryObjectBody } from '../media/delivery-bucket.js';
+import type { ResolvedAssetConfig } from '../media/config.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: ReadonlySet<string> = 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: Headers, etag: string): void {
+  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: DeliveryObject | DeliveryObjectBody): obj is DeliveryObjectBody {
+  return 'body' in obj && (obj as DeliveryObjectBody).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: ResolvedAssetConfig): RequestHandler {
+  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: string[] = [];
+    for (const part of raw.split('/')) {
+      let decoded: string;
+      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 as { env?: Record<string, unknown> } | undefined;
+      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/src/lib/vite/index.ts

@@ -220,20 +220,26 @@ 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;
 }
 
 /** 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: CairnManifestOptions): string {
   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);
 `;
 }
@@ -264,6 +270,7 @@ export async function readAdapterFacts(cwd: string = process.cwd()): Promise<Ada
     if (typeof parsed.owner === 'string') facts.owner = parsed.owner;
     if (typeof parsed.repo === 'string') 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 {
     return null;