caracms 0.6.0 → 0.7.0

package/README.md

@@ -129,7 +129,7 @@ These go on the site's server. `caracms init` prints the same list.
 
 | Name | Needed | What it's for |
 |---|---|---|
-| `CARACMS_CLOUD_KEY` | instead of the GitHub and image variables | The site's key from CaraCMS Cloud (`cck_…`). It replaces the token or App, `GITHUB_REPO` and the image variables: see [CaraCMS Cloud](#caracms-cloud). |
+| `CARACMS_CLOUD_KEY` | instead of the GitHub, image, form and email variables | The site's key from CaraCMS Cloud (`cck_…`). It replaces the token or App, `GITHUB_REPO`, the image variables, and the form and email ones: see [CaraCMS Cloud](#caracms-cloud). |
 | `GITHUB_REPO` | required, but not with the cloud key | The site's repository, as owner/name. |
 | `CARACMS_GITHUB_TOKEN` | required, or the App, or the cloud key | A fine-grained token (`github_pat_…`) on that one repo: Contents read and write, Metadata read (Deployments read is optional). Never `GITHUB_TOKEN`. |
 | `GITHUB_APP_ID` | instead of the token | The GitHub App's ID, for anyone setting up many sites. Set the token or the App, not both. |
@@ -139,8 +139,8 @@ These go on the site's server. `caracms init` prints the same list.
 | `CARACMS_SECRET` | required | Signs the editors' sessions. A long random string. |
 | `CARACMS_CLIENT_IP_HEADER` | required off Railway, Fly and Render | Where the visitor's IP comes from: `x-real-ip` for nginx with `proxy_set_header X-Real-IP $remote_addr`, `x-forwarded-for` for Caddy, or `socket` if nothing sits in front of this server. `caracms start` won't start without it. |
 | `CARACMS_ALLOW` | for email sign-in | Who may sign in, comma-separated: addresses (`aoife@fernhill.ie`) or whole domains (`@fernhill.ie`). The client adds their own people in Site Settings. |
-| `RESEND_API_KEY` | for email sign-in | Sends the sign-in links (and form notifications) through Resend. |
-| `FORMS_FROM` | for email sign-in | The address those emails come from, on a domain verified in Resend. |
+| `RESEND_API_KEY` | for email sign-in, but not with the cloud key | Sends the sign-in links (and form notifications) through Resend. |
+| `FORMS_FROM` | for email sign-in, but not with the cloud key | The address those emails come from, on a domain verified in Resend. |
 | `CARACMS_BACKUP_USER` | for the backup sign-in | The backup sign-in, for when email sign-in links can't arrive. Both or neither. |
 | `CARACMS_BACKUP_PASSWORD` | for the backup sign-in | The backup sign-in's password. |
 | `CARACMS_RUNNING_COMMIT` | optional | The commit this server runs, where the host doesn't say (Railway and Render do). |
@@ -155,9 +155,9 @@ A site that uses images, video or forms needs these as well. The image variables
 | Feature | Variables |
 |---|---|
 | Images (the media bucket and imgproxy) | `CARACMS_MEDIA_URL` (imgproxy's address), `IMGPROXY_KEY`, `IMGPROXY_SALT`, `S3_BUCKET`, `S3_ENDPOINT`, `S3_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`; on CaraCMS Cloud, none of them: `CARACMS_CLOUD_KEY` alone |
-| Video | `MUX_TOKEN_ID`, `MUX_TOKEN_SECRET` |
-| Form submissions (a second bucket, at the media bucket's endpoint and region) | `SUBMISSIONS_S3_BUCKET`, `SUBMISSIONS_S3_ACCESS_KEY_ID`, `SUBMISSIONS_S3_SECRET_ACCESS_KEY` |
-| Form emails | `RESEND_API_KEY`, `FORMS_FROM` (as above) |
+| Video | `MUX_TOKEN_ID`, `MUX_TOKEN_SECRET`; on CaraCMS Cloud, none of them: `CARACMS_CLOUD_KEY` alone |
+| Form submissions (a second bucket, at the media bucket's endpoint and region) | `SUBMISSIONS_S3_BUCKET`, `SUBMISSIONS_S3_ACCESS_KEY_ID`, `SUBMISSIONS_S3_SECRET_ACCESS_KEY`; on CaraCMS Cloud, none of them: `CARACMS_CLOUD_KEY` alone |
+| Form emails | `RESEND_API_KEY`, `FORMS_FROM` (as above); on CaraCMS Cloud, none of them |
 | Spam checks on forms | `TURNSTILE_SITE_KEY`, `TURNSTILE_SECRET_KEY` |
 | A password on the whole site before launch | `CARACMS_PRELAUNCH` |
 | Try again through Railway's API | `CARACMS_RAILWAY_TOKEN` (Railway sets the rest) |
@@ -331,9 +331,11 @@ repo, and only that repo, about once an hour.
 The key replaces `CARACMS_GITHUB_TOKEN` (or `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`)
 and `GITHUB_REPO`: the repo comes from the cloud when the server starts, so setting
 `GITHUB_REPO` beside the key is refused, and so is setting a token or an App as well. It
-also replaces the image variables ([Images](#images-on-caracms-cloud), below).
+also replaces the image variables ([Images](#images-on-caracms-cloud), below), the
+video ones ([Video](#video-on-caracms-cloud)), and the form and email ones
+([Forms and email](#forms-and-email-on-caracms-cloud)).
 Everything else in [the variables](#the-variables) is still the site's own: `SITE_URL`,
-`REDIS_URL`, `CARACMS_SECRET`, the sign-in variables, and the video and form variables.
+`REDIS_URL`, `CARACMS_SECRET`, `CARACMS_ALLOW`, the backup sign-in, and Turnstile.
 There's no webhook: a check once a minute keeps the editor's Publish status up to date.
 
 If the cloud says no when the server starts (the App isn't installed on the repo, the
@@ -368,6 +370,38 @@ builds. A running site keeps serving whatever the cloud does.
 `caracms media import <files…>` works with the key too (from the environment or the
 site's `.env`), with the same rules and output, and its uploads count like any other.
 
+#### Forms and email on CaraCMS Cloud
+
+With the key, the site needs no submissions bucket and no Resend account. Set none of
+`SUBMISSIONS_S3_BUCKET`, `SUBMISSIONS_S3_ACCESS_KEY_ID`, `SUBMISSIONS_S3_SECRET_ACCESS_KEY`,
+`RESEND_API_KEY` or `FORMS_FROM`: setting any of them beside the key is refused, at build
+and when the server starts, with
+
+> Set CARACMS_CLOUD_KEY or the site's own forms and email variables, not both: remove RESEND_API_KEY and FORMS_FROM.
+
+The site's server still makes every check on a submission (the fields, the honeypot, the
+rate limit, Turnstile) and writes its email, as before. The cloud stores the submission
+and its attachments, and sends the email once it's stored. The editor's inbox reads them
+from the cloud, unchanged.
+
+- **Form emails** come from `forms@notify.caracms.com`, named "<brand name> – <form label>"
+  (for example "Urban Return – Contact"), with Reply-To the visitor. They go to the form's
+  recipients in Site Settings, at most the first ten (the server log says when some were
+  left off).
+- **Each site sends at most 50 form emails a day** (UTC) unless CaraCMS raises it. Past
+  that, a submission is still stored, and the inbox shows it as "Not emailed: this site
+  reached its daily email limit in CaraCMS Cloud (50). Ask CaraCMS to raise it." It isn't
+  sent later.
+- **Sign-in links** come from `no-reply@accounts.caracms.com`, in the same words as before.
+
+**On a laptop**, or anywhere that isn't a production server (`NODE_ENV=production`),
+nothing goes to the cloud, even with the key: submissions are kept in
+`.caracms/submissions/` and both emails are written to the server log, so a test enquiry
+never reaches a client's inbox.
+
+A site on an older caracms keeps its own bucket and Resend until it updates and removes
+them.
+
 #### Moving a site's images in
 
 `caracms media push` copies everything under `uploads/` in the site's own bucket into its
@@ -385,6 +419,30 @@ uploader, and never changes the source bucket. It prints `{ copied, skipped, fai
 A site bigger than its storage limit stops at the limit with the cloud's sentence: ask
 CaraCMS to raise it, then run it again.
 
+#### Video on CaraCMS Cloud
+
+With the key, the site's clips are uploaded to CaraCMS Cloud's Mux and listed from the
+site's own clips there; the editor works exactly as it does with a Mux account of your
+own. Set neither `MUX_TOKEN_ID` nor `MUX_TOKEN_SECRET`: setting either beside the key is
+refused with
+
+> Set CARACMS_CLOUD_KEY or the site's own Mux variables, not both: remove MUX_TOKEN_ID.
+
+Clips play on the site straight from Mux (`stream.mux.com`, `image.mux.com`), as before:
+the public pages never call the cloud. The minutes a site stores count towards its video
+limit (60 minutes unless CaraCMS has set another), and once it's reached, a new upload is
+refused with the cloud's sentence: "This site has reached its video limit in CaraCMS
+Cloud (60 minutes). Ask CaraCMS to raise it." A clip counts once Mux has finished with
+it, so one upload can take a site past its limit; the next is refused.
+
+**Moving a site's video in** means uploading its clips again in the editor and placing
+them where the old ones were. There's no copy command. Until a clip is replaced, the old
+one keeps playing on the site from the site's old Mux account: the page only needs its
+playback ID. In the editor it shows its poster and "A clip" (it isn't in the cloud's
+library), and saving other changes on the page leaves it as it is. Remove `MUX_TOKEN_ID`
+and `MUX_TOKEN_SECRET` when you set the key; keep the old Mux account until every clip
+has been replaced.
+
 #### Working locally
 
 **Anyone working on a real site, wherever they are, uses that site's CaraCMS Cloud**: your

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caracms",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A visual CMS for Astro sites, with content in git.",
   "license": "MIT",
   "type": "module",

package/src/cloud-middleware.ts

@@ -15,9 +15,12 @@
  * `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>;
@@ -62,9 +65,15 @@ export const onRequest: MiddlewareHandler = async (_context, 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) return;
-	if (cloud.problems.length) throw new Error(`caracms: ${cloud.problems.join(' ')}`);
+	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);

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,13 @@
  *   `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).
  */
 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>;
@@ -33,7 +37,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.';
 
@@ -77,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
@@ -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/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/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/mode.ts

@@ -101,6 +101,36 @@ export const CLOUD_AND_GITHUB_PROBLEM = (other: string) =>
 export const OWN_MEDIA_VARIABLES = ['S3_ENDPOINT', 'S3_REGION', 'S3_BUCKET', 'S3_ACCESS_KEY_ID', 'S3_SECRET_ACCESS_KEY', 'IMGPROXY_KEY', 'IMGPROXY_SALT', 'CARACMS_MEDIA_URL'] as const;
 const listed = (names: readonly string[]) => (names.length <= 1 ? names.join('') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`);
 export const CLOUD_AND_MEDIA_PROBLEM = (names: readonly string[]) => `Set CARACMS_CLOUD_KEY or the site's own media variables, not both: remove ${listed(names)}.`;
+/** The site's own Mux token, which `CARACMS_CLOUD_KEY` replaces (caracms-cloud M4.5 Decision 15). */
+export const OWN_MUX_VARIABLES = ['MUX_TOKEN_ID', 'MUX_TOKEN_SECRET'] as const;
+export const CLOUD_AND_MUX_PROBLEM = (names: readonly string[]) => `Set CARACMS_CLOUD_KEY or the site's own Mux variables, not both: remove ${listed(names)}.`;
+/** The site's own forms and email variables, which `CARACMS_CLOUD_KEY` replaces (caracms-cloud M4 Decision 22). */
+export const OWN_FORMS_VARIABLES = ['SUBMISSIONS_S3_BUCKET', 'SUBMISSIONS_S3_ACCESS_KEY_ID', 'SUBMISSIONS_S3_SECRET_ACCESS_KEY', 'RESEND_API_KEY', 'FORMS_FROM'] as const;
+export const CLOUD_AND_FORMS_PROBLEM = (names: readonly string[]) => `Set CARACMS_CLOUD_KEY or the site's own forms and email variables, not both: remove ${listed(names)}.`;
+
+/** The key beside any of the site's own forms and email variables: Decision 22's sentence, or null. */
+export function cloudFormsConflict(env: Env): string | null {
+	if (!env.CARACMS_CLOUD_KEY?.trim()) return null;
+	const both = OWN_FORMS_VARIABLES.filter((name) => env[name]?.trim());
+	return both.length ? CLOUD_AND_FORMS_PROBLEM(both) : null;
+}
+
+/**
+ * The cloud as the forms and email credential (caracms-cloud M4 Decision 22): the
+ * connection when `CARACMS_CLOUD_KEY` is set, with any problems (the site's own forms and
+ * email variables beside it, a bad `CARACMS_CLOUD_URL`). Null: not a cloud site. Whether
+ * the cloud is *used* is the caller's (only on a production server; the Core framing).
+ */
+export function cloudForms(env: Env): { connection: { key: string; url: string }; problems: string[] } | null {
+	const get = (name: string) => env[name]?.trim() || null;
+	const key = get('CARACMS_CLOUD_KEY');
+	if (!key) return null;
+	const conflict = cloudFormsConflict(env);
+	const problems: string[] = conflict ? [conflict] : [];
+	const url = readCloudUrl(get('CARACMS_CLOUD_URL'), problems);
+	return { connection: { key, url }, problems };
+}
+
 export const CLOUD_REPO_PROBLEM = 'CARACMS_CLOUD_KEY is set, so the repo comes from CaraCMS Cloud; remove GITHUB_REPO.';
 export const CLOUD_URL_PROBLEM = (url: string) =>
 	`CARACMS_CLOUD_URL must be the cloud's https:// address (http:// works for localhost only; got "${url}"). Leave it unset for CaraCMS Cloud itself.`;
@@ -194,6 +224,12 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 		// M3 Decision 19: the key is the media credential too (unless the tests' in-memory media is on).
 		const ownMedia = OWN_MEDIA_VARIABLES.filter((name) => get(name));
 		if (ownMedia.length && get('CARACMS_MEDIA') !== 'memory') problems.push(CLOUD_AND_MEDIA_PROBLEM(ownMedia));
+		// M4.5 Decision 15: and the video credential.
+		const ownMux = OWN_MUX_VARIABLES.filter((name) => get(name));
+		if (ownMux.length && get('CARACMS_MEDIA') !== 'memory') problems.push(CLOUD_AND_MUX_PROBLEM(ownMux));
+		// M4 Decision 22: and the forms and email credential.
+		const formsConflict = cloudFormsConflict(env);
+		if (formsConflict) problems.push(formsConflict);
 		github = { kind: 'cloud', key: cloudKey, url: readCloudUrl(get('CARACMS_CLOUD_URL'), problems) };
 	} else if (!memory || production) {
 		const appId = get('GITHUB_APP_ID');