caracms 0.5.1 → 0.7.0

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)}` };

package/src/forms/store.ts

@@ -9,8 +9,12 @@
  *   gets these. **The production server never falls back to disk**: with any of them
  *   unset, the store is `unset` (the endpoint's 502, the inbox's sentence).
  * - **Everywhere else**: `.caracms/submissions/` under the site's root (gitignored),
- *   **even with the bucket variables set**, so a laptop never lands a test enquiry in
+ *   **even with the bucket variables or the cloud key set**, so a laptop never lands a test enquiry in
  *   the client's inbox, nor copies their visitors' data down.
+ * - **CaraCMS Cloud** (caracms-cloud M4 Decision 23): a production server with
+ *   `CARACMS_CLOUD_KEY` stores through the cloud's API (cloud-store.ts), and the cloud sends
+ *   the email. The key with any of the site's own forms and email variables is `unset`
+ *   with Decision 22's sentence.
  * - **`CARACMS_SUBMISSIONS=memory`**: in memory, one per process, for tests. Refused in
  *   production, as `CARACMS_MEDIA=memory` is.
  *
@@ -31,6 +35,8 @@ import { createHash, randomInt } from 'node:crypto';
 import { mkdir, readdir, readFile, rmdir, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve, sep } from 'node:path';
 import { AwsClient } from 'aws4fetch';
+import { cloudForms } from '../live/mode.ts';
+import { cloudStore } from './cloud-store.ts';
 import { isSubmissionId, shownFileName } from './rules.ts';
 
 type Env = Record<string, string | undefined>;
@@ -77,8 +83,24 @@ export interface NewFile {
 	data: Uint8Array;
 }
 
+/**
+ * What a cloud site's server sends with a submission (caracms-cloud M4 Decision 11): the
+ * email, written, or the reason there is none. The cloud sends it once the row is stored.
+ */
+export type WrittenEmail =
+	| { email: { to: string[]; subject: string; text: string; replyTo?: string; fromName: string } }
+	| { emailSkipped: string }
+	| { emailFailed: string };
+
 export interface SubmissionStore {
-	create(input: { form: string; receivedAt: string; fields: Record<string, string>; files?: NewFile[] }): Promise<StoredSubmission>;
+	/**
+	 * `email` writes the email for the submission as stored (its id, files and time), and only
+	 * the cloud store calls it (M4 Decision 23): it may call it twice, when the cloud already
+	 * had the first id. The other stores ignore it; the endpoint sends their email itself.
+	 */
+	create(input: { form: string; receivedAt: string; fields: Record<string, string>; files?: NewFile[]; email?: (submission: StoredSubmission) => WrittenEmail }): Promise<StoredSubmission>;
+	/** True for the cloud store: the email goes with `create`, and the cloud sends it and records the outcome. */
+	readonly sendsEmail?: boolean;
 	get(id: string): Promise<StoredSubmission | null>;
 	getFile(id: string, n: number): Promise<{ file: StoredFile; body: Uint8Array } | null>;
 	/** Newest first, `limit` (default 50) after `before`; `older` is the cursor for the next page, or null. */
@@ -426,6 +448,8 @@ export type SubmissionsConfig =
 	| { kind: 'memory' }
 	| { kind: 'folder'; dir: string }
 	| { kind: 'bucket'; bucket: SubmissionsBucket }
+	/** CaraCMS Cloud (caracms-cloud M4 Decision 23): a production server with `CARACMS_CLOUD_KEY`. */
+	| { kind: 'cloud'; connection: { key: string; url: string } }
 	/** The production server without its bucket: `message` names what's missing (the endpoint's log, the inbox's sentence). */
 	| { kind: 'unset'; message: string; missing: string[] };
 
@@ -440,10 +464,19 @@ export function readSubmissionsConfig(root: string, env: Env = process.env, prod
 	const mode = get('CARACMS_SUBMISSIONS');
 	if (mode === 'memory') return production ? { kind: 'unset', message: SUBMISSIONS_MEMORY_IN_PRODUCTION, missing: [] } : { kind: 'memory' };
 	if (mode) return { kind: 'unset', message: `CARACMS_SUBMISSIONS must be "memory" or unset (got "${mode}").`, missing: [] };
+	// The key with the site's own variables is a mistake everywhere (M4 Decision 22), as the media's is.
+	const cloud = cloudForms(env);
+	if (cloud?.problems.length) return { kind: 'unset', message: cloud.problems.join(' '), missing: [] };
+	// Outside production: the folder, even with the cloud key (M4's Core framing).
 	if (!production) return { kind: 'folder', dir: join(root, LOCAL_SUBMISSIONS_FOLDER) };
+	if (cloud) return { kind: 'cloud', connection: cloud.connection };
 	const missing = [...SUBMISSIONS_ENV, ...SHARED_ENV].filter((name) => !get(name));
 	if (missing.length) {
-		return { kind: 'unset', message: `Form submissions aren't set up on this server: set ${list(missing)} to the site's submissions bucket.`, missing };
+		return {
+			kind: 'unset',
+			message: `Form submissions aren't set up on this server: set CARACMS_CLOUD_KEY to the site's CaraCMS Cloud key, or set ${list(missing)} to the site's submissions bucket.`,
+			missing,
+		};
 	}
 	return {
 		kind: 'bucket',
@@ -474,6 +507,8 @@ export function resetSubmissions(): void {
 /** The store for this config, one per process per backend (so the unread count is kept), or the `unset` config itself. */
 export function submissionStore(config: SubmissionsConfig, fetchImpl?: typeof fetch): SubmissionStore | Extract<SubmissionsConfig, { kind: 'unset' }> {
 	if (config.kind === 'unset') return config;
+	// One per call (a request): the cloud keeps the unread count, and the store holds only the count its own last answer gave.
+	if (config.kind === 'cloud') return cloudStore({ ...config.connection, ...(fetchImpl ? { fetch: fetchImpl } : {}) });
 	const s = shared();
 	const id = config.kind === 'memory' ? 'memory' : config.kind === 'folder' ? `folder:${config.dir}` : `bucket:${config.bucket.endpoint}:${config.bucket.bucket}:${config.bucket.accessKeyId}`;
 	let store = s.stores.get(id);

package/src/index.ts

@@ -46,6 +46,7 @@
  * (Decision 5) and has Vite pre-bundle the editor's browser deps. The public pages
  * have no script, no React and no editor markers in either.
  */
+import { cloudSettingsForBuild } from './cloud-middleware.ts';
 import type { AstroIntegration } from 'astro';
 import { fontProviders } from 'astro/config';
 import { execFileSync } from 'node:child_process';
@@ -198,6 +199,8 @@ export const REDIRECT_MIDDLEWARE = 'redirect-middleware.ts';
 
 /** M4 Phase 2: the unconfigured server's 503, registered before Phase 3's guard. */
 export const EDITOR_MIDDLEWARE = 'editor/middleware.ts';
+/** caracms-cloud M3 Decision 20: a cloud site's settings, fetched by the first request (cloud-middleware.ts). */
+export const CLOUD_MIDDLEWARE = 'cloud-middleware.ts';
 
 /**
  * Content files out of Vite's watch (Decision 5): a write never reloads `/admin`
@@ -410,6 +413,8 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 					if (address.url) injectRoute({ pattern: SITEMAP_ROUTE.pattern, entrypoint: new URL(`./${SITEMAP_ROUTE.entrypoint}`, import.meta.url), prerender: true });
 					// M4 Phase 3: the sign-in pages (live/auth/routes.ts).
 					for (const route of LOGIN_ROUTES) injectRoute({ pattern: route.pattern, entrypoint: new URL(`./${route.entrypoint}`, import.meta.url), prerender: false });
+					// caracms-cloud M3 Decision 20: a cloud site's settings, awaited before anything renders. First of all.
+					addMiddleware({ order: 'pre', entrypoint: new URL(`./${CLOUD_MIDDLEWARE}`, import.meta.url) });
 					// M4 Phase 2: an unconfigured production server's 503 on /admin and /_caracms/*. First, so it runs before the guard.
 					addMiddleware({ order: 'pre', entrypoint: new URL(`./${EDITOR_MIDDLEWARE}`, import.meta.url) });
 					// M4 Phase 3: the sign-in guard on /admin and /_caracms/ (live mode only). Must stay after the 503 middleware.
@@ -510,7 +515,11 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 				server.httpServer?.once('close', stop);
 			},
 			// Posts and tags, Decision 15: a production build reads each document once (read.ts). Never in dev.
-			'astro:build:start': () => shareBuildReads(true),
+			// caracms-cloud M3 Decision 20: a cloud site's settings, fetched once before any page renders; a refusal fails the build.
+			'astro:build:start': async () => {
+				shareBuildReads(true);
+				await cloudSettingsForBuild();
+			},
 			'astro:build:done': () => {
 				shareBuildReads(false);
 				if (buildInfo && serverDir && existsSync(serverDir)) writeFileSync(new URL(BUILD_INFO_FILE, serverDir), `${JSON.stringify(buildInfo)}\n`);

package/src/live/README.md

@@ -19,7 +19,7 @@ live drafts store, sweep, locks and status route, and Phase 3's sign-in, sit on
 | `backend.ts` | `GitBackend`; `GitHubBackend`, `MemoryBackend` (test helpers: `seed`, `push`, `file`, `deployments`, `beforeRequest`); `StaleHeadError` |
 | `branches.ts` | `Branch` (a role: `main` or `drafts`), `BranchNames` (the refs behind them), `DEFAULT_BRANCHES`. `CARACMS_MAIN_BRANCH` and `CARACMS_DRAFTS_BRANCH` (read by `mode.ts`, M9 Decision 6) name the branch Publish commits to and the one autosaves land on; unset, `main` and `drafts`. They're set together or not at all: one alone is a problem, so the mode is unconfigured (`/admin` answers 503 saying both must be set; the public site still serves). Only the backends turn a role into a ref name, so with both set a branch called `main` is never read or moved. `MemoryBackend.refs` is keyed by name |
 | `github.ts` | The App's JWT, the installation token (one repo, refreshed early), `Tracker` (request counts). A third credential, `cloud`: the token from CaraCMS Cloud, refreshed the same way; its refusals are an access problem of kind `cloud` |
-| `cloud.ts` | CaraCMS Cloud (`CARACMS_CLOUD_KEY`; caracms-cloud M2): `DEFAULT_CLOUD_URL`, `cloudSettings()` (the repo, at start), `cloudToken()`, `CloudRefusal` (the cloud's `error`, `message`, `installUrl`), and `cloudUnavailable()`, the sign-in guard's 503 for a refusal at start |
+| `cloud.ts` | CaraCMS Cloud (`CARACMS_CLOUD_KEY`; caracms-cloud M2): `DEFAULT_CLOUD_URL`, `fetchCloudSettings()` (the repo and the media; M3), `loadCloudSettings()` / `heldCloudSettings()` (one fetch per process, shared by the media and the runtime), `cloudSettings()` (the repo, at start), `cloudCall()` (one call, for the cloud bucket too), `cloudToken()`, `CloudRefusal` (the cloud's `error`, `message`, `installUrl`), and `cloudUnavailable()`, the sign-in guard's 503 for a refusal at start |
 | `webhook.ts` | `handleGithubWebhook()`, behind `POST /_caracms/github` (`../editor/routes/github.ts`) |
 | `autosaves.ts` | Phase 2. Autosaves in Redis (`caracms:autosave:<file>`, a week; stored compare-and-set, ordered per tab by `X-Caracms-Seq`), the session's last commit (the merge's ancestor) and who last changed a document (Decision 11; no expiry, and `known: false` when neither Redis nor git can say). M5a: a new document's autosave carries `created: { over }` (its ancestor until committed), a deletion is a "gone" autosave (`text` and `document` null, `gone: { title }`) |
 | `locks.ts` | Phase 2. `Locks`: taken by the first write, heartbeat on the poll (Redis diet: only when `needsBeat`), lapse only once committed, releasing, Edit here; presence, each record holding for twice its tab's poll interval plus 3 s |

package/src/live/auth/email.ts

@@ -7,10 +7,18 @@
  * server log and nothing is sent, so no test from a laptop reaches anyone's inbox.
  * The email names the site by its brand name. The link carries only the token.
  *
+ * **On CaraCMS Cloud** (caracms-cloud M4 Decision 25), a production server with
+ * `CARACMS_CLOUD_KEY` asks the cloud instead (`POST /v1/email/sign-in`), which writes the
+ * email from its own copy of this template and sends it from `accounts.caracms.com`. The
+ * key beside `RESEND_API_KEY` or `FORMS_FROM` (Decision 22) sends nothing and logs why.
+ * Outside production the link is logged, key or not.
+ *
  * The HTML part is one table layout with inline styles (mail clients strip `<style>`),
  * the system font stack, no images; the plain-text part says the same.
  */
 import { sendEmail, sendsEmail } from '../../email.ts';
+import { cloudCall, isCloudRefusal } from '../cloud.ts';
+import { cloudForms } from '../mode.ts';
 
 export { RESEND_URL } from '../../email.ts';
 const FONT = "ui-sans-serif,system-ui,-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif";
@@ -76,6 +84,20 @@ export async function deliverLink(input: {
 		log(`sign-in link for ${to} (not emailed outside production): ${link}`);
 		return 'logged';
 	}
+	const cloud = cloudForms(env);
+	if (cloud) {
+		if (cloud.problems.length) {
+			log(`could not email a sign-in link: ${cloud.problems.join(' ')}`);
+			return 'failed';
+		}
+		try {
+			await cloudCall({ ...cloud.connection, ...(input.fetch ? { fetch: input.fetch } : {}) }, 'POST', '/v1/email/sign-in', { to, link, siteName });
+			return 'sent';
+		} catch (error) {
+			log(`could not email a sign-in link: CaraCMS Cloud${isCloudRefusal(error) ? ` (${error.error}): ${error.message}` : `: ${error instanceof Error ? error.message : String(error)}`}`);
+			return 'failed';
+		}
+	}
 	const { subject, text, html } = buildLinkEmail({ siteName, link, email: to });
 	const result = await sendEmail({ to: [to], subject, text, html }, { env, fetch: input.fetch });
 	if (result.status === 'sent') return 'sent';

package/src/live/auth/middleware.ts

@@ -25,7 +25,7 @@
 import type { MiddlewareHandler } from 'astro';
 import { site } from 'virtual:caracms/config';
 import { editorMode } from '../../editor/server/mode.ts';
-import { CloudRefusal, cloudUnavailable } from '../cloud.ts';
+import { isCloudRefusal, cloudUnavailable } from '../cloud.ts';
 import { setPerson } from '../locals.ts';
 import { guard, isFormEndpoint, isGuardedPath } from './guard.ts';
 import { authFor } from './index.ts';
@@ -42,7 +42,7 @@ export const onRequest: MiddlewareHandler = async (context, next) => {
 	try {
 		auth = await authFor(site, mode.settings, context.site);
 	} catch (error) {
-		if (error instanceof CloudRefusal) {
+		if (isCloudRefusal(error)) {
 			console.error(`[caracms] sign-in: the live runtime could not start: CaraCMS Cloud (${error.error}): ${error.message}`);
 			return cloudUnavailable(error, context.url.pathname.startsWith('/_caracms/'));
 		}