caracms 0.5.0 → 0.6.0

package/src/live/cloud.ts

@@ -3,8 +3,14 @@
  *
  * - `CARACMS_CLOUD_KEY` (the site key, `cck_…`) is sent as `Authorization: Bearer` and
  *   nowhere else; `CARACMS_CLOUD_URL` overrides the production address below.
- * - `cloudSettings()`: `GET /v1/settings` at start, for the site's repo (`github.repo`;
- *   null is `no_repo`, with the cloud's own sentence).
+ * - `fetchCloudSettings()`: `GET /v1/settings`, the whole answer the package uses: the
+ *   site's repo, its folder and its media (bucket, image host, imgproxy pair; M3).
+ *   `loadCloudSettings()` is the one fetch per process (M3 Decision 20): the build's start,
+ *   or the first request a server gets, and the live runtime, all share it, held on
+ *   `globalThis` (the build renders pages through another module instance than its hooks);
+ *   `heldCloudSettings()` reads that copy synchronously (`readMediaConfig`).
+ * - `cloudSettings()`: the site's repo from those settings (`github.repo`; null is
+ *   `no_repo`, with the cloud's own sentence). Only the editor needs a repo.
  * - `cloudToken()`: `POST /v1/github/token`, a fresh installation token on the site's repo,
  *   about an hour long. `GitHubClient` calls it and refreshes five minutes early.
  * - **A refusal** (any answer that isn't 2xx, carrying `{ error, message }`) throws a
@@ -15,7 +21,7 @@
  * - `cloudUnavailable()`: the sign-in guard's 503 for a refusal at start (Decision 14),
  *   the sentence escaped and the install link a link.
  *
- * The key and the tokens are never logged and never put in an error.
+ * The key, the tokens and the imgproxy pair are never logged and never put in an error.
  */
 
 /** The production API's address (caracms-cloud M0 → Contracts). The one place it's written. */
@@ -25,6 +31,8 @@ export const DEFAULT_CLOUD_URL = 'https://glad-bird-412.ap-southeast-2.convex.si
 export const CLOUD_KEY_SHAPE = /^cck_[A-Za-z0-9_-]{43}$/;
 
 export const CLOUD_UNREACHABLE = "CaraCMS Cloud couldn't be reached, so the editor can't start. Try again in a minute.";
+/** M3 Decision 20: the build's own sentence for a cloud it can't reach. */
+export const CLOUD_UNREACHABLE_BUILD = "CaraCMS Cloud couldn't be reached, so the site can't be built. Try again in a minute.";
 /** The cloud's own `no_repo` sentence (Contracts), for `github.repo: null` in the settings. */
 export const CLOUD_NO_REPO = 'This site has no GitHub repo in CaraCMS Cloud yet. Ask CaraCMS to set one.';
 /** Decision 13: a token answer named another repo than the one the server started with. */
@@ -41,8 +49,23 @@ export interface CloudConnection {
 	timeoutMs?: number;
 }
 
+/**
+ * Marks a `CloudRefusal`. `Symbol.for` is shared across module instances, so a refusal
+ * thrown by a second copy of this file (Vite's dev SSR graph can hold two) is still known.
+ */
+const REFUSAL_BRAND = Symbol.for('caracms.CloudRefusal');
+
+/**
+ * Is this a `CloudRefusal`, from any instance of this module? Use this, never
+ * `instanceof CloudRefusal`: that fails when the refusal came from the other copy.
+ */
+export function isCloudRefusal(value: unknown): value is CloudRefusal {
+	return typeof value === 'object' && value !== null && (value as Record<symbol, unknown>)[REFUSAL_BRAND] === true;
+}
+
 /** The cloud said no (or couldn't be reached). `message` is safe to show and to log. */
 export class CloudRefusal extends Error {
+	readonly [REFUSAL_BRAND] = true;
 	/** The cloud's `error` (`no_repo`, `app_not_installed`, `unknown_key`…), or the package's `unreachable` / `repo_changed`. */
 	readonly error: string;
 	/** An `https://` link the message names (the App's install page), or null. */
@@ -57,45 +80,155 @@ export class CloudRefusal extends Error {
 
 const unreachable = () => new CloudRefusal('unreachable', CLOUD_UNREACHABLE);
 
-async function call(connection: CloudConnection, method: 'GET' | 'POST', path: string): Promise<Record<string, unknown>> {
+/**
+ * One call to the API: `path` with its query, a JSON `body` for a POST. The answer's JSON
+ * object, or a `CloudRefusal` (the cloud's own, or `unreachable`). The media bucket
+ * (editor/server/media/cloud-bucket.ts) calls it too.
+ */
+export async function cloudCall(connection: CloudConnection, method: 'GET' | 'POST', path: string, body?: unknown): Promise<Record<string, unknown>> {
 	let res: Response;
-	let body: unknown;
+	let answer: unknown;
 	try {
 		res = await (connection.fetch ?? fetch)(`${connection.url}${path}`, {
 			method,
-			headers: { authorization: `Bearer ${connection.key}`, accept: 'application/json', 'user-agent': 'caracms' },
+			headers: {
+				authorization: `Bearer ${connection.key}`,
+				accept: 'application/json',
+				'user-agent': 'caracms',
+				...(body === undefined ? {} : { 'content-type': 'application/json' }),
+			},
+			...(body === undefined ? {} : { body: JSON.stringify(body) }),
 			signal: AbortSignal.timeout(connection.timeoutMs ?? CLOUD_TIMEOUT_MS),
 		});
-		body = await res.json();
+		answer = await res.json();
 	} catch {
 		throw unreachable();
 	}
-	const answer = body && typeof body === 'object' && !Array.isArray(body) ? (body as Record<string, unknown>) : null;
-	if (!answer) throw unreachable();
+	const object = answer && typeof answer === 'object' && !Array.isArray(answer) ? (answer as Record<string, unknown>) : null;
+	if (!object) throw unreachable();
 	if (!res.ok) {
-		const { error, message, installUrl } = answer;
+		const { error, message, installUrl } = object;
 		if (typeof error !== 'string' || typeof message !== 'string' || !message.trim()) throw unreachable();
 		throw new CloudRefusal(error, message, typeof installUrl === 'string' && /^https:\/\//i.test(installUrl) ? installUrl : null);
 	}
-	return answer;
+	return object;
 }
 
 const REPO = /^([A-Za-z0-9-]+)\/([A-Za-z0-9._-]+)$/;
 
-/** The site's repo, from `GET /v1/settings`. */
-export async function cloudSettings(connection: CloudConnection): Promise<{ owner: string; repo: string }> {
-	const answer = await call(connection, 'GET', '/v1/settings');
+/** What the package uses of `GET /v1/settings` (caracms-cloud M1's shape; M3 adds nothing it needs). */
+export interface CloudSettings {
+	/** The linked repo, or null (`no_repo`, which only the editor minds: a build ignores it). */
+	repo: { owner: string; repo: string } | null;
+	/** The site's media, or null when the answer lacks any of it (the editor can still start; images can't be built). */
+	media: {
+		/** The site's folder in the media bucket, `sites/<folder>/`: the prefix the cloud adds to every key. */
+		folder: string;
+		bucket: string;
+		/** Bare, `img.caracms.cloud`. */
+		imageHost: string;
+		/** imgproxy's pair for this site, hex. Never logged, never sent to a browser. */
+		key: string;
+		salt: string;
+	} | null;
+}
+
+/** The package's sentence for settings with no usable media (a cloud set up without its bucket or image host). */
+export const CLOUD_NO_MEDIA = "CaraCMS Cloud's settings for this site have no media yet, so images can't be built. Ask CaraCMS to check the site.";
+
+const FOLDER = /^sites\/[a-z0-9][a-z0-9-]*\/$/;
+const HOST = /^[A-Za-z0-9.-]+(?::\d+)?$/;
+const HEX = /^(?:[0-9a-fA-F]{2})+$/;
+const str = (v: unknown) => (typeof v === 'string' && v ? v : null);
+
+/** `GET /v1/settings`, checked. No `github` or a malformed repo counts as unreachable; incomplete media is `media: null`. */
+export async function fetchCloudSettings(connection: CloudConnection): Promise<CloudSettings> {
+	const answer = await cloudCall(connection, 'GET', '/v1/settings');
 	const github = answer.github as { repo?: unknown } | undefined;
+	const media = answer.media as { bucket?: unknown; imageHost?: unknown } | undefined;
+	const pair = answer.imgproxy as { key?: unknown; salt?: unknown } | undefined;
 	if (!github || typeof github !== 'object') throw unreachable();
-	if (github.repo === null) throw new CloudRefusal('no_repo', CLOUD_NO_REPO);
 	const m = typeof github.repo === 'string' ? REPO.exec(github.repo) : null;
-	if (!m) throw unreachable();
-	return { owner: m[1]!, repo: m[2]! };
+	if (github.repo !== null && !m) throw unreachable();
+	const folder = str(answer.folder);
+	const bucket = str(media && typeof media === 'object' ? media.bucket : null);
+	const imageHost = str(media && typeof media === 'object' ? media.imageHost : null);
+	const key = str(pair && typeof pair === 'object' ? pair.key : null);
+	const salt = str(pair && typeof pair === 'object' ? pair.salt : null);
+	const ok = folder && FOLDER.test(folder) && bucket && imageHost && HOST.test(imageHost) && key && HEX.test(key) && salt && HEX.test(salt);
+	return { repo: m ? { owner: m[1]!, repo: m[2]! } : null, media: ok ? { folder, bucket, imageHost, key, salt } : null };
+}
+
+/** The site's repo (the editor's start): `no_repo` when none is linked. */
+export async function cloudSettings(connection: CloudConnection): Promise<{ owner: string; repo: string }> {
+	return repoOf(await fetchCloudSettings(connection));
+}
+
+export function repoOf(settings: CloudSettings): { owner: string; repo: string } {
+	if (!settings.repo) throw new CloudRefusal('no_repo', CLOUD_NO_REPO);
+	return settings.repo;
+}
+
+// ── The one fetch per process (M3 Decision 20) ─────────────────────────────────
+
+const HELD = Symbol.for('caracms.cloudSettings');
+interface Held {
+	key: string;
+	url: string;
+	pending: Promise<CloudSettings> | null;
+	value: CloudSettings | null;
+	/** The last fetch's refusal, while no fetch has succeeded: the media-unset sentence. */
+	failure: CloudRefusal | null;
+}
+const held = () => globalThis as { [HELD]?: Held };
+
+/**
+ * The settings, fetched once per process and shared: the build's start, a server's first
+ * request and the live runtime all come here, so there's one `GET /v1/settings`. A fetch
+ * that fails is forgotten (its refusal kept for `heldCloudSettings`), so the next caller
+ * tries again. Another key or address than the held one fetches afresh (tests).
+ */
+export function loadCloudSettings(connection: CloudConnection): Promise<CloudSettings> {
+	const g = held();
+	const h = g[HELD];
+	if (h && h.key === connection.key && h.url === connection.url) {
+		if (h.value) return Promise.resolve(h.value);
+		if (h.pending) return h.pending;
+	}
+	const next: Held = { key: connection.key, url: connection.url, pending: null, value: null, failure: h?.key === connection.key && h.url === connection.url ? h.failure : null };
+	next.pending = fetchCloudSettings(connection).then(
+		(value) => {
+			next.value = value;
+			next.failure = null;
+			next.pending = null;
+			return value;
+		},
+		(error: unknown) => {
+			next.pending = null;
+			next.failure = isCloudRefusal(error) ? error : unreachable();
+			throw next.failure;
+		},
+	);
+	g[HELD] = next;
+	return next.pending;
+}
+
+/** The held copy for this key and address: ready, the last fetch's refusal, or null (not fetched yet, or fetching). */
+export function heldCloudSettings(connection: Pick<CloudConnection, 'key' | 'url'>): { kind: 'ready'; settings: CloudSettings } | { kind: 'failed'; refusal: CloudRefusal } | null {
+	const h = held()[HELD];
+	if (!h || h.key !== connection.key || h.url !== connection.url) return null;
+	if (h.value) return { kind: 'ready', settings: h.value };
+	return h.failure ? { kind: 'failed', refusal: h.failure } : null;
+}
+
+/** Forget the held settings (tests). */
+export function resetCloudSettings(): void {
+	delete held()[HELD];
 }
 
 /** A fresh installation token on the site's repo, from `POST /v1/github/token`. */
 export async function cloudToken(connection: CloudConnection): Promise<{ token: string; expiresAt: number; repo: string }> {
-	const answer = await call(connection, 'POST', '/v1/github/token');
+	const answer = await cloudCall(connection, 'POST', '/v1/github/token');
 	const { token, expiresAt, repo } = answer;
 	const at = typeof expiresAt === 'string' ? Date.parse(expiresAt) : Number.NaN;
 	if (typeof token !== 'string' || !token || Number.isNaN(at) || typeof repo !== 'string') throw unreachable();

package/src/live/github.ts

@@ -31,7 +31,7 @@
  * The private key, the site key and the tokens are never logged.
  */
 import { createSign } from 'node:crypto';
-import { CLOUD_REPO_CHANGED, CloudRefusal, cloudToken } from './cloud.ts';
+import { CLOUD_REPO_CHANGED, CloudRefusal, isCloudRefusal, cloudToken } from './cloud.ts';
 
 const API = 'https://api.github.com';
 
@@ -341,7 +341,7 @@ export class GitHubClient {
 		try {
 			answer = await cloudToken({ ...cloud, fetch: this.fetcher, timeoutMs: this.timeoutMs });
 		} catch (error) {
-			if (error instanceof CloudRefusal && error.error !== 'unreachable') this.cloudProblem = { message: error.message, installUrl: error.installUrl };
+			if (isCloudRefusal(error) && error.error !== 'unreachable') this.cloudProblem = { message: error.message, installUrl: error.installUrl };
 			throw error;
 		}
 		if (answer.repo.toLowerCase() !== this.nameWithOwner.toLowerCase()) {

package/src/live/mode.ts

@@ -97,6 +97,10 @@ export const CLOUD_KEY_PROBLEM =
 	"CARACMS_CLOUD_KEY isn't a CaraCMS Cloud site key: a key is cck_ followed by 43 letters, digits, - and _. Copy it again from app.caracms.com.";
 export const CLOUD_AND_GITHUB_PROBLEM = (other: string) =>
 	`Both CARACMS_CLOUD_KEY and ${other} are set: a site uses one GitHub credential, so remove ${other}.`;
+/** The site's own media variables, which `CARACMS_CLOUD_KEY` replaces (caracms-cloud M3 Decision 19). */
+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)}.`;
 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.`;
@@ -187,6 +191,9 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 		if (ghToken) problems.push(CLOUD_AND_GITHUB_PROBLEM('CARACMS_GITHUB_TOKEN'));
 		if (get('GITHUB_APP_ID')) problems.push(CLOUD_AND_GITHUB_PROBLEM('GITHUB_APP_ID'));
 		if (get('GITHUB_REPO')) problems.push(CLOUD_REPO_PROBLEM);
+		// 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));
 		github = { kind: 'cloud', key: cloudKey, url: readCloudUrl(get('CARACMS_CLOUD_URL'), problems) };
 	} else if (!memory || production) {
 		const appId = get('GITHUB_APP_ID');
@@ -298,7 +305,7 @@ function isBranchName(name: string): boolean {
 }
 
 /** CARACMS_CLOUD_URL, without a trailing slash: https://, or http:// on localhost. Unset, the production address. */
-function readCloudUrl(raw: string | null, problems: string[]): string {
+export function readCloudUrl(raw: string | null, problems: string[]): string {
 	if (!raw) return DEFAULT_CLOUD_URL;
 	let url: URL | null = null;
 	try {

package/src/live/runtime.ts

@@ -20,7 +20,7 @@ import { join, relative, sep } from 'node:path';
 import { repoPrefix, type ResolvedSite } from '../config.ts';
 import { GitHubBackend, MemoryBackend, type FileWrite, type GitBackend } from './backend.ts';
 import { DEFAULT_BRANCHES } from './branches.ts';
-import { cloudSettings } from './cloud.ts';
+import { fetchCloudSettings, heldCloudSettings, loadCloudSettings, repoOf, type CloudConnection } from './cloud.ts';
 import { GitHubClient, Tracker } from './github.ts';
 import { LiveGit, SITE_SETTINGS_FILE } from './git.ts';
 import type { LiveSettings } from './mode.ts';
@@ -57,6 +57,19 @@ export interface RuntimeOptions {
 	fetch?: typeof fetch;
 }
 
+/**
+ * The repo for the editor's start. M3 Decision 20: the settings the process already holds (the
+ * first request fetched them for the media), so one GET /v1/settings, not two; a test's own fetch
+ * asks afresh. A held copy with no repo isn't reused: the repo may have been linked since, so
+ * this start asks again (one more GET, only while the repo is missing). The held copy is left
+ * as it is, so the media keep working off it.
+ */
+export async function cloudRepoForStart(connection: CloudConnection): Promise<{ owner: string; repo: string }> {
+	const held = heldCloudSettings(connection);
+	const stale = held?.kind === 'ready' && !held.settings.repo;
+	return repoOf(await (connection.fetch || stale ? fetchCloudSettings(connection) : loadCloudSettings(connection)));
+}
+
 /** Build and start a runtime (not shared: tests make their own). */
 export async function createLiveRuntime(options: RuntimeOptions): Promise<LiveRuntime> {
 	const { site, settings } = options;
@@ -80,7 +93,7 @@ export async function createLiveRuntime(options: RuntimeOptions): Promise<LiveRu
 			if (gh.kind === 'cloud') {
 				// caracms-cloud M2 Decision 13: the repo from the cloud's settings, then the first
 				// token, so a refusal of either stops the start (the sign-in guard shows its sentence).
-				const { owner, repo } = await cloudSettings({ key: gh.key, url: gh.url, fetch });
+				const { owner, repo } = await cloudRepoForStart({ key: gh.key, url: gh.url, fetch });
 				client = new GitHubClient({ cloudKey: gh.key, cloudUrl: gh.url, owner, repo, now, fetch }, tracker);
 				await client.ready();
 				log(`live mode on ${owner}/${repo} through CaraCMS Cloud`);

package/src/media.ts

@@ -22,9 +22,19 @@
  * `IMGPROXY_KEY` and `IMGPROXY_SALT` (hex, the values imgproxy has), `S3_BUCKET` (the
  * bucket in the `s3://` source). `CARACMS_MEDIA=memory` supplies `https://img.test`, a
  * fixed test key and salt and a test bucket, and is refused on a production server.
+ *
+ * **On CaraCMS Cloud** (caracms-cloud M3 Decisions 19–20) `CARACMS_CLOUD_KEY` replaces all
+ * of them: the origin (`https://<media.imageHost>`), the pair, the bucket and the site's
+ * folder come from the cloud's settings, fetched once per process (live/cloud.ts →
+ * `loadCloudSettings`, at the build's start and by a server's first request) and read here
+ * from that held copy. The folder goes before the key in the source,
+ * `s3://<bucket>/sites/<folder>/<key>`; content keeps `uploads/…`. The key with any of the
+ * site's own media variables is a problem sentence (one credential, not two).
  */
 import { createHmac } from 'node:crypto';
 import type { ImageFormat } from './fields.ts';
+import { CLOUD_NO_MEDIA, heldCloudSettings, type CloudConnection } from './live/cloud.ts';
+import { CLOUD_AND_MEDIA_PROBLEM, OWN_MEDIA_VARIABLES, readCloudUrl } from './live/mode.ts';
 import { renderMedia, type RenderImage } from './media-value.ts';
 
 /** The srcset width ladder every fluid image draws from (Decision 2). 1920 at the top: imgproxy doesn't upscale. */
@@ -52,6 +62,8 @@ export interface MediaSettings {
 	key: string;
 	salt: string;
 	bucket: string;
+	/** Before every key in the source: the site's folder on CaraCMS Cloud (`sites/<folder>/`), else none. */
+	prefix?: string;
 	memory: boolean;
 }
 
@@ -70,6 +82,40 @@ export function isProductionBuild(): boolean {
 type Env = Record<string, string | undefined>;
 const HEX = /^(?:[0-9a-fA-F]{2})+$/;
 
+export { CLOUD_AND_MEDIA_PROBLEM, OWN_MEDIA_VARIABLES };
+/** No settings held yet: nothing has fetched them in this process (the middleware and the build's start do). */
+export const CLOUD_MEDIA_NOT_FETCHED = "The site's media settings haven't come from CaraCMS Cloud yet.";
+/** A held fetch that couldn't reach the cloud, in the media's words (the cloud's own refusals are shown as sent). */
+export const CLOUD_MEDIA_UNREACHABLE = "CaraCMS Cloud couldn't be reached, so images can't be shown. Try again in a minute.";
+
+/**
+ * The cloud as the media credential: the connection when `CARACMS_CLOUD_KEY` is set and
+ * `CARACMS_MEDIA` isn't `memory` (which wins over everything), with any problems (the
+ * site's own media variables beside it, a bad `CARACMS_CLOUD_URL`). Null: not a cloud site's media.
+ */
+export function cloudMedia(env: Env = process.env): { connection: Pick<CloudConnection, 'key' | 'url'>; problems: string[] } | null {
+	const get = (name: string) => env[name]?.trim() || null;
+	const key = get('CARACMS_CLOUD_KEY');
+	if (!key || get('CARACMS_MEDIA') === 'memory') return null;
+	const problems: string[] = [];
+	const both = OWN_MEDIA_VARIABLES.filter((name) => get(name));
+	if (both.length) problems.push(CLOUD_AND_MEDIA_PROBLEM(both));
+	const url = readCloudUrl(get('CARACMS_CLOUD_URL'), problems);
+	return { connection: { key, url }, problems };
+}
+
+/** The media settings from the held cloud settings (or why there are none). */
+function cloudMediaConfig(cloud: NonNullable<ReturnType<typeof cloudMedia>>, problems: string[]): MediaConfig {
+	problems.push(...cloud.problems);
+	if (problems.length) return { kind: 'unset', missing: [], problems };
+	const held = heldCloudSettings(cloud.connection);
+	if (!held) return { kind: 'unset', missing: [], problems: [CLOUD_MEDIA_NOT_FETCHED] };
+	if (held.kind === 'failed') return { kind: 'unset', missing: [], problems: [held.refusal.error === 'unreachable' ? CLOUD_MEDIA_UNREACHABLE : held.refusal.message] };
+	const media = held.settings.media;
+	if (!media) return { kind: 'unset', missing: [], problems: [CLOUD_NO_MEDIA] };
+	return { kind: 'ready', settings: { origin: `https://${media.imageHost}`, key: media.key, salt: media.salt, bucket: media.bucket, prefix: media.folder, memory: false } };
+}
+
 /** The media variables (Decision 5). Read on each call (cheap), so tests can change them. */
 export function readMediaConfig(env: Env = process.env, production = isProductionBuild()): MediaConfig {
 	const get = (name: string) => {
@@ -83,6 +129,8 @@ export function readMediaConfig(env: Env = process.env, production = isProductio
 		return { kind: 'ready', settings: { ...MEMORY_MEDIA, memory: true } };
 	}
 	if (mode) problems.push(`CARACMS_MEDIA must be "memory" or unset (got "${mode}").`);
+	const cloud = cloudMedia(env);
+	if (cloud) return cloudMediaConfig(cloud, problems);
 	const missing: string[] = [];
 	const need = (name: string) => {
 		const v = get(name);
@@ -131,8 +179,8 @@ function side(value: number | undefined): number {
 	return Math.min(Math.round(value), IMAGE_MAX_DIMENSION);
 }
 
-/** A key as imgproxy's `plain` source takes it: each part percent-encoded, slashes kept. */
-const sourceOf = (settings: MediaSettings, key: string) => `s3://${settings.bucket}/${key.split('/').map(encodeURIComponent).join('/')}`;
+/** A key as imgproxy's `plain` source takes it, after the cloud folder when there is one: each part percent-encoded, slashes kept. */
+const sourceOf = (settings: MediaSettings, key: string) => `s3://${settings.bucket}/${`${settings.prefix ?? ''}${key}`.split('/').map(encodeURIComponent).join('/')}`;
 
 const signed = (settings: MediaSettings, path: string) => `${settings.origin}/${signPath(path, settings.key, settings.salt)}${path}`;