caracms 0.6.0 → 0.8.0

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

@@ -12,9 +12,16 @@
  *   `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). Mux is unchanged.
+ *   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).
+ * - **With the config's `services`** (caracms-cloud M5 Decision 2) the other mode's variables
+ *   are never read (live/services.ts), and a cloud site without its key has neither.
  */
 import type { CloudConnection } from '../../../live/cloud.ts';
+import { CLOUD_AND_MUX_PROBLEM, OWN_MUX_VARIABLES, readCloudUrl } from '../../../live/mode.ts';
+import { bakedServices, CLOUD_KEY_MISSING_PROBLEM, servicesEnv, type Services } from '../../../live/services.ts';
 import { cloudMedia, isProductionBuild, readMediaConfig, type MediaSettings } from '../../../media.ts';
 
 type Env = Record<string, string | undefined>;
@@ -33,7 +40,11 @@ export type ImagesConfig =
 	| { 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.';
 
@@ -45,15 +56,17 @@ const get = (env: Env, name: string) => {
 const memory = (env: Env) => get(env, 'CARACMS_MEDIA') === 'memory';
 
 /** The image routes' settings: the bucket, and imgproxy's for the thumbnails. */
-export function readImagesConfig(env: Env = process.env, production = isProductionBuild()): ImagesConfig {
+export function readImagesConfig(env: Env = process.env, production = isProductionBuild(), services: Services | null = bakedServices()): ImagesConfig {
+	env = servicesEnv(env, services);
 	if (memory(env)) {
 		if (production) return { kind: 'unset', message: MEMORY_IN_PRODUCTION, missing: [] };
-		const signing = readMediaConfig(env, production);
+		const signing = readMediaConfig(env, production, services);
 		if (signing.kind !== 'ready') return { kind: 'unset', message: MEMORY_IN_PRODUCTION, missing: [] };
 		return { kind: 'memory', signing: signing.settings };
 	}
-	const signing = readMediaConfig(env, production);
-	const cloud = cloudMedia(env);
+	if (services === 'cloud' && !get(env, 'CARACMS_CLOUD_KEY')) return { kind: 'unset', message: CLOUD_KEY_MISSING_PROBLEM, missing: [] };
+	const signing = readMediaConfig(env, production, services);
+	const cloud = cloudMedia(env, services);
 	if (cloud) {
 		if (signing.kind === 'ready') return { kind: 'cloud', signing: signing.settings, connection: cloud.connection };
 		return { kind: 'unset', message: signing.problems.join(' '), missing: [] };
@@ -77,9 +90,20 @@ 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. */
-export function readMuxConfig(env: Env = process.env, production = isProductionBuild()): MuxConfig {
+/** 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(), services: Services | null = bakedServices()): MuxConfig {
+	env = servicesEnv(env, services);
 	if (memory(env)) return production ? { kind: 'unset', message: MEMORY_IN_PRODUCTION, missing: [] } : { kind: 'memory' };
+	const key = get(env, 'CARACMS_CLOUD_KEY');
+	if (services === 'cloud' && !key) return { kind: 'unset', message: CLOUD_KEY_MISSING_PROBLEM, missing: [] };
+	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
@@ -42,6 +43,7 @@ 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';
@@ -88,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 });
 }
 

package/src/editor/server/mode.ts

@@ -15,6 +15,7 @@
 import type { ResolvedSite } from '../../config.ts';
 import { liveEditor, type LiveEditor } from '../../live/editor.ts';
 import { readMode, unconfiguredMessage, type Baked, type Mode } from '../../live/mode.ts';
+import { bakedServices } from '../../live/services.ts';
 import { localDraftsStore, type DraftsStore } from './drafts-store.ts';
 
 declare const __CARACMS_PRODUCTION__: boolean | undefined;
@@ -26,11 +27,12 @@ export function isProductionServer(): boolean {
 	return typeof __CARACMS_PRODUCTION__ === 'boolean' ? __CARACMS_PRODUCTION__ : false;
 }
 
-/** The site's address and the commit the build baked in (runs-anywhere Decisions 7 and 9); empty in plain Node (tests). */
+/** The site's address, the commit and the config's `services` the build baked in (runs-anywhere Decisions 7 and 9, caracms-cloud M5 Decision 1); empty in plain Node (tests). */
 export function bakedAtBuild(): Baked {
 	return {
 		site: typeof __CARACMS_SITE__ === 'string' ? __CARACMS_SITE__ : null,
 		commit: typeof __CARACMS_BUILD_COMMIT__ === 'string' ? __CARACMS_BUILD_COMMIT__ : null,
+		services: bakedServices(),
 	};
 }
 

package/src/email.ts

@@ -10,6 +10,8 @@
  * reaches anyone's inbox. It never throws: an unset key or sender, Resend's refusal
  * or a timeout all come back as a result with a sentence.
  */
+import { bakedServices, servicesEnv } from './live/services.ts';
+
 export const RESEND_URL = 'https://api.resend.com/emails';
 export const SEND_TIMEOUT_MS = 10_000;
 
@@ -30,7 +32,8 @@ export async function sendEmail(
 	email: Email,
 	options: { env?: Record<string, string | undefined>; fetch?: typeof fetch; timeoutMs?: number } = {},
 ): Promise<SendResult> {
-	const env = options.env ?? process.env;
+	// caracms-cloud M5 Decision 2: on a cloud site RESEND_API_KEY and FORMS_FROM are never read (the cloud sends).
+	const env = servicesEnv(options.env ?? process.env, bakedServices());
 	const timeoutMs = options.timeoutMs ?? SEND_TIMEOUT_MS;
 	const apiKey = (env['RESEND_API_KEY'] ?? '').trim();
 	const from = (env['FORMS_FROM'] ?? '').trim();

package/src/forms/cloud-store.ts

@@ -0,0 +1,212 @@
+/**
+ * The submissions store on CaraCMS Cloud (caracms-cloud M4 Decisions 5–9 and 23), behind
+ * store.ts's `SubmissionStore`, so the endpoint's checks and the inbox don't change. The
+ * site's server never holds R2 or Resend credentials: it asks the API (live/cloud.ts, the
+ * site key), which answers for the site's own folder.
+ *
+ * - `create`: mints the id (`newSubmissionId`, the package's own shape), builds the
+ *   `StoredSubmission`, asks the `email` callback to write the email for it, and sends both
+ *   (`POST /v1/submissions`). On `409 exists` it mints a new id, writes the email again (its
+ *   link names the id) and tries once more. With files, the answer is **pending** with one
+ *   presigned PUT per file: each is uploaded with exactly the headers named, then
+ *   `POST /v1/submissions/confirm`, tried once more on a timeout or an unreachable cloud.
+ *   An upload that fails, or a confirm answered `409 incomplete`, removes the row
+ *   (`POST /v1/submissions/delete`); a confirm that never got through is left to the
+ *   cloud's hourly clean-up. Either way `create` throws: the visitor gets the endpoint's 502.
+ * - `get`, `list`, `update` (`readAt` only), `delete` and `getFile` (a 5-minute download
+ *   URL, then the bytes): one route each.
+ * - **The unread count comes back with every answer**; `unreadCount()` gives the last one
+ *   this store saw, or asks (`GET /v1/submissions/unread`). store.ts makes a store per
+ *   request, so the count is never older than the request.
+ *
+ * Refusals are `CloudRefusal`s with the cloud's own sentence (the endpoint logs it, the
+ * inbox shows it). Presigned URLs go nowhere but the fetch here: never in a log line or an error.
+ */
+import { createHash } from 'node:crypto';
+import { cloudCall, CloudRefusal, isCloudRefusal, type CloudConnection } from '../live/cloud.ts';
+import { isSubmissionId } from './rules.ts';
+import { fileKey, isFileKey, newSubmissionId, PAGE_SIZE, type StoredFile, type StoredSubmission, type SubmissionStore } from './store.ts';
+
+const STORAGE_TIMEOUT_MS = 20_000;
+
+const malformed = (what: string) => new CloudRefusal('unreachable', `CaraCMS Cloud's answer to ${what} isn't one the package knows.`);
+
+const count = (v: unknown): number | null => (typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : null);
+
+/** A submission as the cloud answered it: the package's own shape, checked enough to be read by the inbox. */
+function submissionOf(value: unknown, what: string): StoredSubmission {
+	const s = value as StoredSubmission | null;
+	if (!s || typeof s !== 'object' || !isSubmissionId(s.id) || typeof s.form !== 'string' || typeof s.receivedAt !== 'string' || !s.fields || typeof s.fields !== 'object') {
+		throw malformed(what);
+	}
+	return { ...s, v: 1, readAt: typeof s.readAt === 'string' ? s.readAt : null };
+}
+
+export function cloudStore(connection: CloudConnection): SubmissionStore {
+	const fetchImpl = connection.fetch ?? ((...args: Parameters<typeof fetch>) => globalThis.fetch(...args));
+	/** The unread count from the last answer that carried one. */
+	let unread: number | null = null;
+	const seen = (answer: Record<string, unknown>) => {
+		const n = count(answer.unread);
+		if (n !== null) unread = n;
+	};
+	const api = (method: 'GET' | 'POST', path: string, body?: unknown) => cloudCall(connection, method, path, body);
+	/** Null for the cloud's `404 not_found`; any other refusal goes up as sent. */
+	async function orNull(method: 'GET' | 'POST', path: string, body?: unknown): Promise<Record<string, unknown> | null> {
+		try {
+			return await api(method, path, body);
+		} catch (error) {
+			if (isCloudRefusal(error) && error.error === 'not_found') return null;
+			throw error;
+		}
+	}
+
+	/** A presigned URL's request, with its own timeout. */
+	async function storage(what: string, url: string, init: RequestInit): Promise<Response> {
+		try {
+			return await fetchImpl(url, { ...init, signal: AbortSignal.timeout(STORAGE_TIMEOUT_MS) });
+		} catch (error) {
+			throw new Error(`submissions: ${what}: storage unreachable (${error instanceof Error ? error.message : String(error)})`);
+		}
+	}
+
+	/** The confirm, tried once more when the cloud didn't answer (Decision 6). */
+	async function confirm(id: string): Promise<void> {
+		for (let attempt = 1; ; attempt++) {
+			try {
+				await api('POST', '/v1/submissions/confirm', { id });
+				return;
+			} catch (error) {
+				if (attempt < 2 && isCloudRefusal(error) && error.error === 'unreachable') continue;
+				throw error;
+			}
+		}
+	}
+
+	/** The row goes, best effort: the cloud's hourly clean-up takes it otherwise. */
+	const discard = (id: string) => api('POST', '/v1/submissions/delete', { id }).catch(() => {});
+
+	async function get(id: string): Promise<StoredSubmission | null> {
+		if (!isSubmissionId(id)) return null;
+		const answer = await orNull('GET', `/v1/submissions/get?${new URLSearchParams({ id })}`);
+		if (!answer) return null;
+		seen(answer);
+		const submission = submissionOf(answer.submission, 'get');
+		return submission.id === id ? submission : null;
+	}
+
+	return {
+		sendsEmail: true,
+		async create({ form, receivedAt, fields, files, email }) {
+			const hashes = (files ?? []).map((f) => createHash('sha256').update(f.data).digest('hex'));
+			for (let attempt = 1; ; attempt++) {
+				const id = newSubmissionId(receivedAt);
+				const stored: StoredFile[] = (files ?? []).map((f, i) => ({ name: f.name, size: f.data.byteLength, type: f.type, key: fileKey(id, i + 1, f.name) }));
+				const record: StoredSubmission = { v: 1, id, form, receivedAt, fields, ...(stored.length ? { files: stored } : {}), readAt: null };
+				const written = email?.(record) ?? { emailSkipped: 'No email was written for this submission.' };
+				let answer: Record<string, unknown>;
+				try {
+					answer = await api('POST', '/v1/submissions', {
+						id,
+						form,
+						receivedAt,
+						fields,
+						...(stored.length ? { files: stored.map((f, i) => ({ name: f.name, type: f.type, size: f.size, key: f.key, sha256: hashes[i] })) } : {}),
+						...written,
+					});
+				} catch (error) {
+					// The id was already the site's (Decision 5): a new one, and the email written again for it.
+					if (attempt < 2 && isCloudRefusal(error) && error.error === 'exists') continue;
+					throw error;
+				}
+				if (answer.state === 'complete') return record;
+				if (answer.state !== 'pending' || !Array.isArray(answer.uploads)) throw malformed('a new submission');
+				try {
+					for (const file of stored) {
+						const upload = (answer.uploads as Record<string, unknown>[]).find((u) => u && typeof u === 'object' && u.key === file.key);
+						const { url, method, headers } = upload ?? {};
+						if (typeof url !== 'string' || !/^https?:\/\//.test(url) || (method !== undefined && method !== 'PUT') || !headers || typeof headers !== 'object') {
+							throw malformed('a new submission');
+						}
+						// The headers as the cloud named them (the URL signs each); Content-Length and Host are fetch's own.
+						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 n = stored.indexOf(file);
+						const res = await storage(`upload ${n + 1}`, url, { method: 'PUT', headers: sent, body: files![n]!.data as BodyInit });
+						await res.body?.cancel().catch(() => {});
+						// 412: the signed If-None-Match: * found the key already there, so an earlier try put it.
+						if (!res.ok && res.status !== 412) throw new Error(`submissions: upload ${n + 1} of ${stored.length}: the storage answered ${res.status}`);
+					}
+				} catch (error) {
+					await discard(id);
+					throw error;
+				}
+				try {
+					await confirm(id);
+				} catch (error) {
+					// `409 incomplete`: a file isn't there at its size, so the row goes. Unreachable: the cloud's clean-up takes it.
+					if (isCloudRefusal(error) && error.error !== 'unreachable') await discard(id);
+					throw error;
+				}
+				return record;
+			}
+		},
+		get,
+		async getFile(id, n) {
+			if (!isSubmissionId(id) || !Number.isInteger(n) || n < 1) return null;
+			const answer = await orNull('POST', '/v1/submissions/file-url', { id, n });
+			if (!answer) return null;
+			const file = answer.file as StoredFile | undefined;
+			// Checked against the id asked for: a key that isn't this submission's is never read.
+			if (typeof answer.url !== 'string' || !file || typeof file !== 'object' || !isFileKey(id, file.key)) throw malformed('a file');
+			const res = await storage(`download ${n}`, answer.url, { method: 'GET' });
+			if (res.status === 404) {
+				await res.body?.cancel().catch(() => {});
+				return null;
+			}
+			if (!res.ok) {
+				await res.body?.cancel().catch(() => {});
+				throw new Error(`submissions: download ${n}: the storage answered ${res.status}`);
+			}
+			return { file: { name: String(file.name ?? ''), size: Number(file.size) || 0, type: String(file.type ?? ''), key: file.key }, body: new Uint8Array(await res.arrayBuffer()) };
+		},
+		async list(opts = {}) {
+			const limit = Math.max(1, Math.min(500, opts.limit ?? PAGE_SIZE));
+			const query = new URLSearchParams({ limit: String(limit) });
+			if (opts.before) {
+				// The cloud refuses a cursor not of the id's shape; v3's stores treat it as "after everything".
+				if (!isSubmissionId(opts.before)) return { items: [], older: null };
+				query.set('before', opts.before);
+			}
+			const answer = await api('GET', `/v1/submissions?${query}`);
+			if (!Array.isArray(answer.items)) throw malformed('the list');
+			seen(answer);
+			const older = answer.older;
+			return { items: answer.items.map((s) => submissionOf(s, 'the list')), older: typeof older === 'string' && isSubmissionId(older) ? older : null };
+		},
+		async update(id, patch) {
+			// The cloud records the email's outcome itself; only `readAt` is the inbox's to change.
+			if (!('readAt' in patch)) return get(id);
+			if (!isSubmissionId(id)) return null;
+			const answer = await orNull('POST', '/v1/submissions/update', { id, readAt: patch.readAt ?? null });
+			if (!answer) return null;
+			seen(answer);
+			return submissionOf(answer.submission, 'an update');
+		},
+		async delete(id) {
+			if (!isSubmissionId(id)) return false;
+			const answer = await api('POST', '/v1/submissions/delete', { id });
+			seen(answer);
+			return answer.deleted === true;
+		},
+		async unreadCount() {
+			if (unread !== null) return unread;
+			const answer = await api('GET', '/v1/submissions/unread');
+			const n = count(answer.unread);
+			if (n === null) throw malformed('the unread count');
+			unread = n;
+			return n;
+		},
+	};
+}

package/src/forms/email.ts

@@ -15,13 +15,16 @@
  *   dropped, one that doesn't look like an address skipped. An empty list is `skipped`.
  * - **Only a production server sends.** Elsewhere the email is written to the log and
  *   recorded `skipped`, saying so.
+ * - **On CaraCMS Cloud** (caracms-cloud M4 Decision 24) the site writes the email the same
+ *   way (`writeNotification`), from "<brand> – <form label>", to at most ten addresses,
+ *   and the cloud store hands it over with the submission; the cloud sends it.
  */
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { SITE_SETTINGS_FILE } from '../reserved.ts';
 import { sendEmail, sendsEmail } from '../email.ts';
 import { formatBytes, looksLikeEmail, shownFileName, submissionAddress, type ResolvedForm } from './rules.ts';
-import type { EmailOutcome, StoredSubmission } from './store.ts';
+import type { EmailOutcome, StoredSubmission, WrittenEmail } from './store.ts';
 
 type Env = Record<string, string | undefined>;
 
@@ -116,6 +119,53 @@ export function buildNotification(input: { submission: StoredSubmission; form: R
 	};
 }
 
+/** The most addresses one form email goes to on CaraCMS Cloud (caracms-cloud M4 Decision 4). */
+export const MAX_RECIPIENTS = 10;
+
+/** The sender's display name on CaraCMS Cloud (M4 Decision 11): `<brand name> – <form label>`, "Urban Return – Contact". The cloud cleans it further. */
+export function fromName(brandName: string, formLabel: string): string {
+	return [brandName.trim(), formLabel.trim()].filter(Boolean).join(' – ');
+}
+
+/** The sentence for a form with no one set to get its emails. */
+const noRecipients = (label: string) => `No one is set to get the ${label} form's emails (Site Settings → Form emails).`;
+
+/**
+ * The email a cloud site's server hands the cloud with a submission (M4 Decisions 11 and 24):
+ * written as `sendNotification` writes it, the recipients capped at the first ten (the rest
+ * logged), or the reason there is none. `settings` is the Site Settings read, or the error
+ * reading them threw. Never throws.
+ */
+export function writeNotification(input: {
+	submission: StoredSubmission;
+	form: ResolvedForm | null;
+	settings: FormSettings | { error: unknown };
+	siteUrl: string | null;
+	timeZone: string;
+	log?: (line: string) => void;
+}): WrittenEmail {
+	const log = input.log ?? ((line: string) => console.log(line));
+	if ('error' in input.settings) {
+		const { error } = input.settings;
+		return { emailFailed: `Could not read Site Settings: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	const settings = input.settings;
+	const label = input.form?.label ?? input.submission.form;
+	const all = sendableAddresses(settings.recipients[input.submission.form] ?? []);
+	if (all.length === 0) return { emailSkipped: noRecipients(label) };
+	const to = all.slice(0, MAX_RECIPIENTS);
+	if (all.length > to.length) {
+		const left = all.length - to.length;
+		log(`[caracms] forms: the ${label} form has ${all.length} recipients; its email goes to the first ${MAX_RECIPIENTS}, and ${left} ${left === 1 ? 'was' : 'were'} left off (Site Settings → Form emails).`);
+	}
+	try {
+		const built = buildNotification({ submission: input.submission, form: input.form, brandName: settings.brandName, siteUrl: input.siteUrl, timeZone: input.timeZone });
+		return { email: { to, subject: built.subject, text: built.text, ...(built.replyTo ? { replyTo: built.replyTo } : {}), fromName: fromName(settings.brandName, label) } };
+	} catch (error) {
+		return { emailFailed: `Could not write the email: ${error instanceof Error ? error.message : String(error)}` };
+	}
+}
+
 /** Send a submission's email and say what happened (the outcome recorded on it). Never throws. */
 export async function sendNotification(input: {
 	submission: StoredSubmission;
@@ -133,7 +183,7 @@ export async function sendNotification(input: {
 	const log = input.log ?? ((line: string) => console.log(line));
 	const to = sendableAddresses(input.settings.recipients[input.submission.form] ?? []);
 	const label = input.form?.label ?? input.submission.form;
-	if (to.length === 0) return { status: 'skipped', at, to, error: `No one is set to get the ${label} form's emails (Site Settings → Form emails).` };
+	if (to.length === 0) return { status: 'skipped', at, to, error: noRecipients(label) };
 	let built: ReturnType<typeof buildNotification>;
 	try {
 		built = buildNotification({ submission: input.submission, form: input.form, brandName: input.settings.brandName, siteUrl: input.siteUrl, timeZone: input.timeZone });

package/src/forms/endpoint.ts

@@ -29,7 +29,9 @@
  *    403; Cloudflare unreachable fails open, logged. Unset: accepted, with a warning.
  * 8. **Store** (store.ts), then **email** (email.ts), then **record** the email's outcome
  *    on the submission, then reply. A storage failure is a 502; an email failure never
- *    fails the visitor.
+ *    fails the visitor. **On CaraCMS Cloud** (caracms-cloud M4 Decision 24) the store
+ *    takes the written email with the submission and the cloud sends and records it, so
+ *    nothing is sent or recorded here; a cloud refusal is the same 502, its sentence logged.
  *
  * Replies: `Accept: application/json` gets `{ ok: true }` or `{ error }`; a no-JS post
  * gets a 303 to `<return>?sent=1`, or the error as plain text. Nothing about the visitor
@@ -40,7 +42,7 @@ import { publicOrigin } from '../live/auth/index.ts';
 import { clientIp, NO_GATE_MESSAGE } from '../live/auth/request.ts';
 import { readCapped } from '../editor/server/media/upload.ts';
 import { isProductionBuild } from '../media.ts';
-import { readFormSettings, sendNotification, type FormSettings } from './email.ts';
+import { readFormSettings, sendNotification, writeNotification, type FormSettings } from './email.ts';
 import { formLimiter, type FormRateLimiter } from './rate-limit.ts';
 import { cleanReturn, FILE_KINDS, FILE_TYPES, formsAcceptFiles, HONEYPOT, looksLikeEmail, MAX_FILE_BYTES, MAX_FILES, type ResolvedForm } from './rules.ts';
 import { cleanFileName, fileExtension, readSubmissionsConfig, submissionStore, type NewFile, type SubmissionStore } from './store.ts';
@@ -313,21 +315,31 @@ export async function handleForm(request: Request, ctx: FormContext): Promise<Re
 		}
 		store = chosen;
 	}
+	const siteUrl = publicOrigin(ctx.astroSite, env);
+	const readSettings = ctx.readSettings ?? (() => readFormSettings(ctx.site.root));
+	// On CaraCMS Cloud (caracms-cloud M4 Decision 24) the email goes with the submission: written here, sent by the cloud.
+	const settingsRead = store.sendsEmail ? await readSettings().catch((error: unknown) => ({ error })) : null;
 	let submission;
 	try {
 		const files: NewFile[] = await Promise.all(vetted.files.map(async (f) => ({ name: f.name, type: f.type, data: new Uint8Array(await f.blob.arrayBuffer()) })));
-		submission = await store.create({ form: form.id, receivedAt: now().toISOString(), fields: vetted.fields, ...(files.length ? { files } : {}) });
+		submission = await store.create({
+			form: form.id,
+			receivedAt: now().toISOString(),
+			fields: vetted.fields,
+			...(files.length ? { files } : {}),
+			...(settingsRead ? { email: (stored) => writeNotification({ submission: stored, form, settings: settingsRead, siteUrl, timeZone: ctx.site.timeZone, log }) } : {}),
+		});
 	} catch (error) {
 		log(`[caracms] forms: couldn't store a ${form.id} submission: ${error instanceof Error ? error.message : String(error)}`);
 		return reply(502, { error: STORE_FAILED_MESSAGE });
 	}
 	await limiter.hit(ip);
+	if (store.sendsEmail) return reply(200, { ok: true });
 
 	// EMAIL, then RECORD its outcome. Neither changes the visitor's reply.
 	let email;
 	try {
-		const settings = await (ctx.readSettings ?? (() => readFormSettings(ctx.site.root)))();
-		const siteUrl = publicOrigin(ctx.astroSite, env);
+		const settings = await readSettings();
 		email = await sendNotification({ submission, form, settings, siteUrl, timeZone: ctx.site.timeZone, env, fetch: ctx.fetch, now, log });
 	} catch (error) {
 		email = { status: 'failed' as const, at: now().toISOString(), to: [], error: `Could not read Site Settings: ${error instanceof Error ? error.message : String(error)}` };