caracms 0.5.1 → 0.7.0

package/skills/caracms-adopt/SKILL.md

@@ -331,7 +331,9 @@ editor's uploads are) and prints one JSON array on stdout:
 ```
 
 - It reads `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID` and
-  `S3_SECRET_ACCESS_KEY` from the environment, else the site's `.env`.
+  `S3_SECRET_ACCESS_KEY` from the environment, else the site's `.env`. On CaraCMS Cloud it
+  reads `CARACMS_CLOUD_KEY` instead (the same places) and uploads to the site's cloud
+  folder, with the same output; with both set it refuses.
 - The same image again writes nothing and prints its key with `"existed": true`. It never
   deletes anything.
 - JPEG, PNG, WebP, AVIF, HEIC/HEIF, GIF and SVG, up to 40 MB and 50 megapixels. If any file

package/src/cloud-middleware.ts

@@ -0,0 +1,85 @@
+/**
+ * The settings fetch for a cloud site's media (caracms-cloud M3 Decision 20). The package
+ * has no boot hook in the built server, so **the first request that reaches the server, of
+ * any kind,** fetches `GET /v1/settings` (live/cloud.ts → `loadCloudSettings`) and every
+ * request waits on that one shared fetch before anything renders. The live runtime reads the
+ * same held answer, so it's one fetch per process. Prerendered pages are files and never wait.
+ *
+ * - Registered first (`addMiddleware({ order: 'pre' })` in index.ts), before the editor's.
+ * - Only for a cloud site's media: `CARACMS_CLOUD_KEY` set, `CARACMS_MEDIA` not `memory`,
+ *   and none of the site's own media variables (that's `readMediaConfig`'s problem sentence).
+ * - A fetch that fails leaves the media unset (v3's handling: the editor's media routes 503
+ *   with the cloud's sentence) and is tried again by a request after `RETRY_MS`, so a cloud
+ *   that's away doesn't hold every request for its timeout.
+ *
+ * `cloudSettingsForBuild()` is the build's start (`astro:build:start`): the same fetch, and
+ * a refusal or an unreachable cloud **fails the build** with the cloud's sentence or the
+ * package's own. The build ignores `github.repo`: a site with no repo linked still builds.
+ * The key beside the site's own forms and email variables fails it too (caracms-cloud M4
+ * Decision 22), whether or not the media is the cloud's.
+ */
+import type { MiddlewareHandler } from 'astro';
+import { CLOUD_NO_MEDIA, CLOUD_UNREACHABLE_BUILD, isCloudRefusal, heldCloudSettings, loadCloudSettings } from './live/cloud.ts';
+import { cloudFormsConflict } from './live/mode.ts';
+import { cloudMedia } from './media.ts';
+
+type Env = Record<string, string | undefined>;
+
+/** After a failed fetch, requests in the next half minute don't wait on another. */
+export const RETRY_MS = 30_000;
+
+const NEXT_TRY = Symbol.for('caracms.cloudSettingsNextTry');
+const LOGGED = Symbol.for('caracms.cloudSettingsLogged');
+type Shared = { [NEXT_TRY]?: number; [LOGGED]?: string };
+
+/** Fetch the settings if this process doesn't hold them yet (and isn't waiting out a failure). */
+export async function ensureCloudSettings(env: Env = process.env, now = Date.now(), log: (line: string) => void = (line) => console.error(line)): Promise<void> {
+	const cloud = cloudMedia(env);
+	if (!cloud || cloud.problems.length) return;
+	if (heldCloudSettings(cloud.connection)?.kind === 'ready') return;
+	const g = globalThis as Shared;
+	if ((g[NEXT_TRY] ?? 0) > now) return;
+	try {
+		await loadCloudSettings(cloud.connection);
+		delete g[NEXT_TRY];
+		delete g[LOGGED];
+	} catch (error) {
+		g[NEXT_TRY] = now + RETRY_MS;
+		const line = isCloudRefusal(error) ? `CaraCMS Cloud (${error.error}): ${error.message}` : 'CaraCMS Cloud: the settings could not be read';
+		if (g[LOGGED] !== line) log(`[caracms] the media settings could not be fetched: ${line}`);
+		g[LOGGED] = line;
+	}
+}
+
+/** Forget the retry clock (tests). */
+export function resetCloudSettingsRetry(): void {
+	const g = globalThis as Shared;
+	delete g[NEXT_TRY];
+	delete g[LOGGED];
+}
+
+export const onRequest: MiddlewareHandler = async (_context, next) => {
+	await ensureCloudSettings();
+	return next();
+};
+
+/** The build's start: the settings, or an Error with the sentence that fails the build. Nothing for a site off the cloud. */
+export async function cloudSettingsForBuild(env: Env = process.env): Promise<void> {
+	// caracms-cloud M4 Decision 22: the key with the site's own forms and email variables fails the build too.
+	const conflict = cloudFormsConflict(env);
+	const forms = conflict ? [conflict] : [];
+	const cloud = cloudMedia(env);
+	if (!cloud) {
+		if (forms.length) throw new Error(`caracms: ${forms.join(' ')}`);
+		return;
+	}
+	if (cloud.problems.length || forms.length) throw new Error(`caracms: ${[...cloud.problems, ...forms].join(' ')}`);
+	let settings;
+	try {
+		settings = await loadCloudSettings(cloud.connection);
+	} catch (error) {
+		const message = isCloudRefusal(error) && error.error !== 'unreachable' ? error.message : CLOUD_UNREACHABLE_BUILD;
+		throw new Error(`caracms: ${message}`);
+	}
+	if (!settings.media) throw new Error(`caracms: ${CLOUD_NO_MEDIA}`);
+}

package/src/editor/README.md

@@ -29,7 +29,8 @@ and an alt already used), `GET thumbnail?key=&width=` (a 302 to the signed URL),
 `POST video-upload`, `GET video-upload/<id>`, `GET clips`, `GET clips/<id>`, `GET playback/<id>`.
 Every shape is in `types.ts` → `MEDIA_ENDPOINTS`. `server/media/`: `sniff.ts` (the type and size
 from the bytes), `upload.ts` (the 40 MB cap, the key rule, no overwrite), `bucket.ts` (S3 through
-aws4fetch, and the in-memory bucket), `library.ts` (the 60 s listing, metadata per key,
+aws4fetch, and the in-memory bucket), `cloud-bucket.ts` (the same seam on CaraCMS Cloud's media
+API, `CARACMS_CLOUD_KEY`), `library.ts` (the 60 s listing, metadata per key,
 where-used), `mux.ts` (the template's Mux rules), `alt.ts` (`WaitingView.missingAlt`),
 `config.ts` (503s, images and clips apart) and `memory.ts` (`CARACMS_MEDIA=memory`: `memoryMedia()`
 to seed the bucket and the fake Mux in tests).

package/src/editor/server/media/cloud-bucket.ts

@@ -0,0 +1,144 @@
+/**
+ * The media bucket on CaraCMS Cloud (caracms-cloud M3 Decision 21), behind bucket.ts's
+ * seam, so the upload route (checks, key, dedupe, metadata) and the files route don't
+ * change. The site's server never holds R2 credentials: it asks the API (live/cloud.ts,
+ * the site key) and the API answers for the site's own folder. Keys stay `uploads/…`:
+ * the cloud adds `sites/<folder>/` and strips it again.
+ *
+ * - `list` and `first`: `GET /v1/media/list`, following its `next` tokens (`list`) or one page (`first`).
+ * - `head`: `GET /v1/media/object`; `404 not_found` is "no such object".
+ * - `get`: `POST /v1/media/download-url`, then the presigned GET, streamed (the files route).
+ * - `put`: `POST /v1/media/upload-url`, then the presigned PUT with exactly the headers it names.
+ *
+ * **The cloud's refusals are shown as sent** (`CloudRefusal`: `upload_limit`'s sentence,
+ * `storage_unavailable`'s); the media handler puts the message in its 502. A cloud that
+ * can't be reached, and the storage's own answers to the presigned URLs, are BucketErrors
+ * (the handler's own sentences). Presigned URLs go nowhere but the fetch here: never in
+ * a log line, an error or an answer to the browser.
+ */
+import { isCloudRefusal, cloudCall, type CloudConnection } from '../../../live/cloud.ts';
+import { BucketError, type Bucket, type BucketObject, type ObjectMeta } from './bucket.ts';
+
+const STORAGE_TIMEOUT_MS = 20_000;
+/** A runaway-token guard, as s3Bucket's: 1000 pages of 1000 is far past one site's library. */
+const MAX_PAGES = 1000;
+
+const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.round(v) : null);
+const text = (v: unknown) => (typeof v === 'string' && v ? v : null);
+const iso = (v: unknown) => (typeof v === 'string' && !Number.isNaN(Date.parse(v)) ? new Date(v).toISOString() : null);
+
+export function cloudBucket(connection: Pick<CloudConnection, 'key' | 'url'>, fetchImpl: typeof fetch = (...args) => globalThis.fetch(...args)): Bucket {
+	const conn: CloudConnection = { ...connection, fetch: fetchImpl };
+
+	/** One API call; a cloud that can't be reached is a BucketError, any other refusal goes up as sent. */
+	async function api(method: 'GET' | 'POST', path: string, body?: unknown): Promise<Record<string, unknown>> {
+		try {
+			return await cloudCall(conn, method, path, body);
+		} catch (error) {
+			if (isCloudRefusal(error) && error.error === 'unreachable') throw new BucketError(`${method} ${path.split('?')[0]}: CaraCMS Cloud unreachable`);
+			throw error;
+		}
+	}
+
+	/** A presigned URL's request. The timeout covers the wait for the storage's headers (a `get` streams after). */
+	async function storage(what: string, url: string, init: RequestInit): Promise<Response> {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(new Error(`no answer in ${STORAGE_TIMEOUT_MS / 1000} s`)), STORAGE_TIMEOUT_MS);
+		try {
+			return await fetchImpl(url, { ...init, signal: controller.signal });
+		} catch (error) {
+			throw new BucketError(`${what}: storage unreachable (${error instanceof Error ? error.message : String(error)})`);
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+
+	async function page(prefix: string, after: string | null): Promise<{ objects: BucketObject[]; next: string | null }> {
+		const query = new URLSearchParams({ prefix });
+		if (after) query.set('after', after);
+		const answer = await api('GET', `/v1/media/list?${query}`);
+		if (!Array.isArray(answer.objects)) throw new BucketError(`list ${prefix}: the answer has no objects`);
+		const objects: BucketObject[] = [];
+		for (const o of answer.objects as Record<string, unknown>[]) {
+			const key = o && typeof o === 'object' ? text(o.key) : null;
+			if (!key) continue;
+			objects.push({ key, lastModified: iso(o.lastModified), size: typeof o.size === 'number' && Number.isFinite(o.size) ? o.size : null });
+		}
+		return { objects, next: text(answer.next) };
+	}
+
+	return {
+		async list(prefix) {
+			const out: BucketObject[] = [];
+			const seen = new Set<string>();
+			let after: string | null = null;
+			for (let n = 0; n < MAX_PAGES; n++) {
+				const { objects, next } = await page(prefix, after);
+				out.push(...objects);
+				if (!next || seen.has(next)) break;
+				seen.add(next);
+				after = next;
+			}
+			return out;
+		},
+		async first(prefix) {
+			const { objects } = await page(prefix, null);
+			return objects[0]?.key ?? null;
+		},
+		async head(key): Promise<ObjectMeta | null> {
+			let answer: Record<string, unknown>;
+			try {
+				answer = await api('GET', `/v1/media/object?${new URLSearchParams({ key })}`);
+			} catch (error) {
+				if (isCloudRefusal(error) && error.error === 'not_found') return null;
+				throw error;
+			}
+			return {
+				w: num(answer.w),
+				h: num(answer.h),
+				name: text(answer.name),
+				by: text(answer.by),
+				contentType: text(answer.contentType),
+				lastModified: iso(answer.lastModified),
+				size: typeof answer.size === 'number' && Number.isFinite(answer.size) ? answer.size : null,
+			};
+		},
+		async get(key) {
+			const { url } = await api('POST', '/v1/media/download-url', { key });
+			if (typeof url !== 'string' || !/^https?:\/\//.test(url)) throw new BucketError(`get ${key}: the answer has no URL`);
+			const res = await storage(`get ${key}`, url, { method: 'GET' });
+			if (res.status === 404) {
+				await res.body?.cancel().catch(() => {});
+				return null;
+			}
+			if (!res.ok || !res.body) {
+				await res.body?.cancel().catch(() => {});
+				throw new BucketError(`get ${key}: ${res.status}`, res.status);
+			}
+			const size = Number(res.headers.get('content-length'));
+			return { body: res.body, size: res.headers.has('content-length') && Number.isFinite(size) ? size : null };
+		},
+		async put({ key, body, contentType, sha256, meta }) {
+			const answer = await api('POST', '/v1/media/upload-url', {
+				key,
+				size: body.byteLength,
+				contentType,
+				sha256,
+				meta: { ...(meta.w !== undefined ? { w: meta.w } : {}), ...(meta.h !== undefined ? { h: meta.h } : {}), name: meta.name, by: meta.by },
+			});
+			const { url, method, headers } = answer;
+			if (typeof url !== 'string' || !/^https?:\/\//.test(url) || (method !== undefined && method !== 'PUT') || !headers || typeof headers !== 'object') {
+				throw new BucketError(`put ${key}: the upload answer isn't one`);
+			}
+			// The headers as the cloud named them, verbatim (the URL signs each one). Content-Length and Host
+			// are fetch's own to send: the body is exactly the declared size, and the URL's host is the signed one.
+			const sent = Object.fromEntries(
+				Object.entries(headers as Record<string, unknown>).filter(([name, v]) => typeof v === 'string' && !/^(content-length|host)$/i.test(name)),
+			) as Record<string, string>;
+			const res = await storage(`put ${key}`, url, { method: 'PUT', headers: sent, body: body as BodyInit });
+			await res.body?.cancel().catch(() => {});
+			// 412: R2 refused the signed If-None-Match: * because the key is there, and the key carries the bytes' hash: already stored.
+			if (!res.ok && res.status !== 412) throw new BucketError(`put ${key}: ${res.status}`, res.status);
+		},
+	};
+}

package/src/editor/server/media/cloud-mux.ts

@@ -0,0 +1,110 @@
+/**
+ * Mux on CaraCMS Cloud (caracms-cloud M4.5 Decision 16), behind mux.ts's seam, so the clip
+ * routes, where-used (`withUses`) and the editor don't change. The site's server holds no
+ * Mux token: it asks the API (live/cloud.ts, the site key), which asks the cloud's own
+ * Mux environment and answers from the site's own clips only. One route per method:
+ *
+ * - `createUpload`: `POST /v1/video/upload` `{ origin, title }` → `{ id, url }`.
+ * - `upload`: `GET /v1/video/upload?id=` → `VideoUploadStatus`.
+ * - `clip`: `GET /v1/video/clip?id=` → `Clip`; `clipOfPlayback`: `GET /v1/video/playback?id=`.
+ * - `clips`: `GET /v1/video/clips` → `{ clips }`, newest first (the cloud keeps the order).
+ *
+ * **The cloud's refusals become `MuxRouteError`s**, so the media handler's own catch answers
+ * them: `not_found` is the routes' documented 404 ('Not found.'); `video_limit` is a 403
+ * with the cloud's sentence as sent; any other refusal (`video_unavailable`, the key's own
+ * refusals…) is a 502 with the cloud's sentence as sent. A cloud that can't be reached, or
+ * an answer that isn't the shape, is a 502 with the package's own sentence. Each 502 is
+ * logged with the refusal's code. The key is never logged nor put in an error.
+ */
+import type { VideoUploadStatus } from '../../types.ts';
+import { cloudCall, isCloudRefusal, type CloudConnection } from '../../../live/cloud.ts';
+import { MuxRouteError, MUX_ID, type Clip, type MuxClient } from './mux.ts';
+
+export const CLOUD_VIDEO_UNREACHABLE = "CaraCMS Cloud couldn't be reached just now. Try again in a minute.";
+export const CLOUD_VIDEO_UNREADABLE = 'CaraCMS Cloud sent an unreadable reply.';
+
+const str = (v: unknown) => (typeof v === 'string' && v ? v : null);
+const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const px = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : null);
+
+export function cloudMux(
+	connection: Pick<CloudConnection, 'key' | 'url'>,
+	options: { fetch?: typeof fetch; log?: (line: string) => void } = {},
+): MuxClient {
+	const conn: CloudConnection = { ...connection, fetch: options.fetch ?? ((...args) => globalThis.fetch(...args)) };
+	const log = options.log ?? ((line: string) => console.error(line));
+
+	async function api(method: 'GET' | 'POST', path: string, body?: unknown): Promise<Record<string, unknown>> {
+		const where = `${method} ${path.split('?')[0]}`;
+		try {
+			return await cloudCall(conn, method, path, body);
+		} catch (error) {
+			if (!isCloudRefusal(error)) throw error;
+			if (error.error === 'not_found') throw new MuxRouteError(404, 'Not found.');
+			if (error.error === 'video_limit') throw new MuxRouteError(403, error.message);
+			log(`[caracms] video ${where}: CaraCMS Cloud (${error.error}): ${error.message}`);
+			throw new MuxRouteError(502, error.error === 'unreachable' ? CLOUD_VIDEO_UNREACHABLE : error.message);
+		}
+	}
+
+	const unreadable = (where: string): never => {
+		log(`[caracms] video ${where}: CaraCMS Cloud sent an unreadable reply`);
+		throw new MuxRouteError(502, CLOUD_VIDEO_UNREADABLE);
+	};
+
+	/** The cloud's `Clip`, checked field by field (it passes `toClip`'s shape through). */
+	const clipOf = (raw: unknown, where: string): Clip => {
+		const c = raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : null;
+		const id = str(c?.id);
+		if (!c || !id) return unreadable(where);
+		const playbackId = str(c.playbackId);
+		const errored = c.errored === true;
+		return {
+			id,
+			playbackId: playbackId && MUX_ID.test(playbackId) ? playbackId : null,
+			status: str(c.status) ?? 'unknown',
+			ready: c.ready === true,
+			errored,
+			error: errored ? (str(c.error) ?? 'Mux could not process this file.') : null,
+			title: str(c.title),
+			duration: num(c.duration),
+			aspectRatio: str(c.aspectRatio),
+			w: px(c.w),
+			h: px(c.h),
+			createdAt: str(c.createdAt),
+		};
+	};
+
+	const query = (id: string) => new URLSearchParams({ id }).toString();
+
+	return {
+		async createUpload(origin, title) {
+			const answer = await api('POST', '/v1/video/upload', { origin, title });
+			const id = str(answer.id);
+			const url = str(answer.url);
+			if (!id || !url || !/^https:\/\//.test(url)) return unreadable('POST /v1/video/upload');
+			return { id, url };
+		},
+		async upload(id): Promise<VideoUploadStatus> {
+			const answer = await api('GET', `/v1/video/upload?${query(id)}`);
+			const assetId = str(answer.assetId);
+			return {
+				id: str(answer.id) ?? id,
+				status: str(answer.status) ?? 'unknown',
+				assetId: assetId && MUX_ID.test(assetId) ? assetId : null,
+				error: str(answer.error),
+			};
+		},
+		async clip(assetId) {
+			return clipOf(await api('GET', `/v1/video/clip?${query(assetId)}`), 'GET /v1/video/clip');
+		},
+		async clipOfPlayback(playbackId) {
+			return clipOf(await api('GET', `/v1/video/playback?${query(playbackId)}`), 'GET /v1/video/playback');
+		},
+		async clips() {
+			const answer = await api('GET', '/v1/video/clips');
+			if (!Array.isArray(answer.clips)) return unreadable('GET /v1/video/clips');
+			return answer.clips.map((c) => clipOf(c, 'GET /v1/video/clips'));
+		},
+	};
+}

package/src/editor/server/media/config.ts

@@ -10,8 +10,16 @@
  * - Images need imgproxy's (`CARACMS_MEDIA_URL`, `IMGPROXY_KEY`, `IMGPROXY_SALT`, which
  *   sign the thumbnails) and the bucket's (`S3_BUCKET`, `S3_ENDPOINT`, `S3_REGION`,
  *   `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`). Clips need `MUX_TOKEN_ID` and `MUX_TOKEN_SECRET`.
+ * - **On CaraCMS Cloud** (caracms-cloud M3 Decision 19) `CARACMS_CLOUD_KEY` is the images'
+ *   one credential: the bucket is the cloud's (cloud-bucket.ts), the signing from the
+ *   settings the process holds (../../../media.ts).
+ * - **And the clips' (caracms-cloud M4.5 Decision 15)**: with the key, clips go through the
+ *   cloud's Mux (cloud-mux.ts), and the site's own `MUX_TOKEN_ID` / `MUX_TOKEN_SECRET`
+ *   beside it is a problem sentence naming them (one credential, not two).
  */
-import { isProductionBuild, readMediaConfig, type MediaSettings } from '../../../media.ts';
+import type { CloudConnection } from '../../../live/cloud.ts';
+import { CLOUD_AND_MUX_PROBLEM, OWN_MUX_VARIABLES, readCloudUrl } from '../../../live/mode.ts';
+import { cloudMedia, isProductionBuild, readMediaConfig, type MediaSettings } from '../../../media.ts';
 
 type Env = Record<string, string | undefined>;
 
@@ -26,9 +34,14 @@ export interface BucketSettings {
 export type ImagesConfig =
 	| { kind: 'memory'; signing: MediaSettings }
 	| { kind: 's3'; signing: MediaSettings; bucket: BucketSettings }
+	| { kind: 'cloud'; signing: MediaSettings; connection: Pick<CloudConnection, 'key' | 'url'> }
 	| { kind: 'unset'; message: string; missing: string[] };
 
-export type MuxConfig = { kind: 'memory' } | { kind: 'mux'; tokenId: string; tokenSecret: string } | { kind: 'unset'; message: string; missing: string[] };
+export type MuxConfig =
+	| { kind: 'memory' }
+	| { kind: 'mux'; tokenId: string; tokenSecret: string }
+	| { kind: 'cloud'; connection: Pick<CloudConnection, 'key' | 'url'> }
+	| { kind: 'unset'; message: string; missing: string[] };
 
 export const MEMORY_IN_PRODUCTION = 'CARACMS_MEDIA=memory is for tests and local runs; a production server never uses the in-memory media.';
 
@@ -48,6 +61,11 @@ export function readImagesConfig(env: Env = process.env, production = isProducti
 		return { kind: 'memory', signing: signing.settings };
 	}
 	const signing = readMediaConfig(env, production);
+	const cloud = cloudMedia(env);
+	if (cloud) {
+		if (signing.kind === 'ready') return { kind: 'cloud', signing: signing.settings, connection: cloud.connection };
+		return { kind: 'unset', message: signing.problems.join(' '), missing: [] };
+	}
 	const missing = signing.kind === 'unset' ? [...signing.missing] : [];
 	const problems = signing.kind === 'unset' ? [...signing.problems] : [];
 	const need = (name: string) => {
@@ -67,9 +85,18 @@ export function readImagesConfig(env: Env = process.env, production = isProducti
 	return { kind: 's3', signing: signing.settings, bucket: { endpoint, region, bucket: signing.settings.bucket, accessKeyId, secretAccessKey } };
 }
 
-/** The clip routes' settings: the site's Mux environment's token. */
+/** The clip routes' settings: the cloud's Mux (the site key), or the site's Mux environment's token. */
 export function readMuxConfig(env: Env = process.env, production = isProductionBuild()): MuxConfig {
 	if (memory(env)) return production ? { kind: 'unset', message: MEMORY_IN_PRODUCTION, missing: [] } : { kind: 'memory' };
+	const key = get(env, 'CARACMS_CLOUD_KEY');
+	if (key) {
+		const problems: string[] = [];
+		const both = OWN_MUX_VARIABLES.filter((name) => get(env, name));
+		if (both.length) problems.push(CLOUD_AND_MUX_PROBLEM(both));
+		const url = readCloudUrl(get(env, 'CARACMS_CLOUD_URL'), problems);
+		if (problems.length) return { kind: 'unset', message: problems.join(' '), missing: [] };
+		return { kind: 'cloud', connection: { key, url } };
+	}
 	const tokenId = get(env, 'MUX_TOKEN_ID');
 	const tokenSecret = get(env, 'MUX_TOKEN_SECRET');
 	const missing = [...(tokenId ? [] : ['MUX_TOKEN_ID']), ...(tokenSecret ? [] : ['MUX_TOKEN_SECRET'])];

package/src/editor/server/media/handler.ts

@@ -10,7 +10,8 @@
  * - **No lock** (Decision 7): an upload, or reading the library, changes no document.
  * - **Every reply is `Cache-Control: private, no-store`.**
  * - **Unconfigured: 503 with a sentence naming what's missing**, images (the bucket and
- *   imgproxy) and clips (Mux) apart: one missing never disables the other.
+ *   imgproxy) and clips (Mux, or CaraCMS Cloud's: cloud-mux.ts) apart: one missing never
+ *   disables the other.
  * - **The Mux token never reaches the browser, nor do Mux's error bodies** (server log
  *   only). Ids are checked against `^[A-Za-z0-9]{1,128}$` before they reach a URL.
  * - **The upload has its own body cap** (40 MB, upload.ts), not the write route's 2 MB or
@@ -41,6 +42,9 @@ import type { DraftsStore } from '../drafts-store.ts';
 import { parseReplaceBody } from '../replace.ts';
 import { checkOrigin, seqOf, tabOf, WriteRefused } from '../write.ts';
 import { BucketError, s3Bucket, type Bucket } from './bucket.ts';
+import { cloudBucket } from './cloud-bucket.ts';
+import { cloudMux } from './cloud-mux.ts';
+import { isCloudRefusal } from '../../../live/cloud.ts';
 import { readImagesConfig, readMuxConfig } from './config.ts';
 import { isFileKey } from '../../../files.ts';
 import { entryOf, fileEntryOf, libraryFor, mediaUses, UPLOADS, type Library, type MediaUses } from './library.ts';
@@ -76,6 +80,7 @@ function images(ctx: MediaContext): { library: Library; signing: MediaSettings }
 	const config = readImagesConfig(ctx.env ?? process.env, ctx.production);
 	if (config.kind === 'unset') return json(503, { error: config.message, code: 'media-unset', missing: config.missing } satisfies MediaUnset);
 	if (config.kind === 'memory') return { library: libraryFor('memory', () => memoryMedia().bucket), signing: config.signing };
+	if (config.kind === 'cloud') return { library: libraryFor(`cloud:${config.connection.url}:${config.signing.prefix}`, (): Bucket => cloudBucket(config.connection, ctx.fetch)), signing: config.signing };
 	const b = config.bucket;
 	return { library: libraryFor(`s3:${b.endpoint}:${b.bucket}:${b.accessKeyId}`, (): Bucket => s3Bucket(b, ctx.fetch)), signing: config.signing };
 }
@@ -85,6 +90,8 @@ function mux(ctx: MediaContext): MuxClient | Response {
 	if (config.kind === 'unset') return json(503, { error: config.message, code: 'mux-unset', missing: config.missing } satisfies MediaUnset);
 	const log = ctx.log ?? ((line: string) => console.error(line));
 	if (config.kind === 'memory') return muxClient({ tokenId: 'memory', tokenSecret: 'memory', fetch: memoryMedia().mux.fetch, log });
+	// caracms-cloud M4.5: the cloud's Mux, through the site key; its refusals arrive as MuxRouteErrors.
+	if (config.kind === 'cloud') return cloudMux(config.connection, { fetch: ctx.fetch, log });
 	return muxClient({ tokenId: config.tokenId, tokenSecret: config.tokenSecret, fetch: ctx.fetch, log });
 }
 
@@ -210,6 +217,11 @@ export async function handleMedia(request: Request, ctx: MediaContext): Promise<
 		if (error instanceof UploadRefused) return json(error.status, { error: error.message, code: error.code } satisfies MediaRefusal);
 		if (error instanceof MuxRouteError) return json(error.status, { error: error.message } satisfies ApiError);
 		if (error instanceof WriteRefused) return json(error.status, { error: error.message, ...error.body });
+		if (isCloudRefusal(error)) {
+			// caracms-cloud M3: the cloud's own sentence, as sent (a full site, its storage away).
+			log(`[caracms] media bucket: CaraCMS Cloud (${error.error}): ${error.message}`);
+			return json(502, { error: error.message } satisfies ApiError);
+		}
 		if (error instanceof BucketError) {
 			log(`[caracms] media bucket: ${error.message}`);
 			const said = error.status !== null && error.status >= 400 && error.status < 500;

package/src/files-route.ts

@@ -32,6 +32,7 @@ import type { APIRoute } from 'astro';
 import { clientIp, NO_GATE_MESSAGE } from './live/auth/request.ts';
 import { fileAddress, fileKeyOf, fileTypeOf } from './files.ts';
 import { s3Bucket, type Bucket } from './editor/server/media/bucket.ts';
+import { cloudBucket } from './editor/server/media/cloud-bucket.ts';
 import { readImagesConfig } from './editor/server/media/config.ts';
 import { memoryMedia } from './editor/server/media/memory.ts';
 import { isProductionBuild } from './media.ts';
@@ -168,7 +169,7 @@ export async function handleFileRequest(request: Request, ctx: FileRouteContext
 	}
 
 	// 6. The one key the allow-list passed.
-	const bucket: Bucket = config.kind === 'memory' ? memoryMedia().bucket : s3Bucket(config.bucket, ctx.fetch);
+	const bucket: Bucket = config.kind === 'memory' ? memoryMedia().bucket : config.kind === 'cloud' ? cloudBucket(config.connection, ctx.fetch) : s3Bucket(config.bucket, ctx.fetch);
 	let object;
 	try {
 		object = await bucket.get(file.key);