@postedin/cms-client 0.1.0

package/src/form-proxy/cms-errors.ts

@@ -0,0 +1,73 @@
+// Which of a form's own fields the CMS refused, read out of a Payload error
+// body.
+//
+// Since postedin/cms#279 a submission is validated before it is written:
+// required answers, email shape, manual option lists and an upload id that
+// must still name a live `pending` file of this form. A refusal is a `400`
+// carrying a Payload `ValidationError`, which names each failed field in
+// `errors[].path` as `data.<fieldName>` — the same name the browser posted.
+//
+// Only those names travel any further. The CMS's own wording does not: it is
+// resolved in the CMS request's language rather than the visitor's — Payload
+// takes `req.t` from the `payload-lng` cookie or the `Accept-Language` header,
+// never from the `?locale` this proxy sends, so a Spanish visitor would be
+// answered in English — and the rest of the body names internal fields. The
+// browser already knows every field name it posted, so handing the names back
+// discloses nothing, and the message the visitor reads is the site's own: form
+// chrome, like every other validation string.
+
+// A path this site can place against a field it rendered. `honeypot`, `form`
+// and `data` are refusals about the request rather than about an answer, and
+// are deliberately not matched: there is no field to hang them on.
+const FIELD_PATH = /^data\.([A-Za-z0-9_-]+)$/;
+
+// A form has tens of fields, not hundreds. The cap is for a body that is not
+// what we think it is rather than for one of ours.
+const MAX_FIELDS = 50;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// Payload nests a ValidationError's per-field errors under `data.errors`, and
+// wraps that in the top-level `errors` array every REST failure carries. Both
+// levels are read, so a plainer `{ errors: [{ path }] }` is understood too.
+function pathsOf(entry: unknown): string[] {
+	if (!isRecord(entry)) {
+		return [];
+	}
+
+	const paths: string[] = [];
+	if (typeof entry.path === 'string') {
+		paths.push(entry.path);
+	}
+
+	const data = entry.data;
+	if (isRecord(data) && Array.isArray(data.errors)) {
+		for (const nested of data.errors) {
+			if (isRecord(nested) && typeof nested.path === 'string') {
+				paths.push(nested.path);
+			}
+		}
+	}
+
+	return paths;
+}
+
+export function refusedFieldNames(body: unknown): string[] {
+	if (!isRecord(body) || !Array.isArray(body.errors)) {
+		return [];
+	}
+
+	const names = new Set<string>();
+	for (const entry of body.errors) {
+		for (const path of pathsOf(entry)) {
+			const match = FIELD_PATH.exec(path);
+			if (match) {
+				names.add(match[1]);
+			}
+		}
+	}
+
+	return [...names].slice(0, MAX_FIELDS);
+}

package/src/form-proxy/cms-write.ts

@@ -0,0 +1,44 @@
+import { jsonResponse } from './http';
+import type { CmsResult, FormOwnershipCheck } from './types';
+
+export interface WriteShape {
+	// Body the browser gets on success; only the new document id goes in.
+	success(id: string | undefined): unknown;
+	// CMS statuses the client branches on, each with a fixed message.
+	passThrough: Record<number, string>;
+	// Fixed message for every other failure, answered as 502.
+	failed: string;
+}
+
+// Runs a CMS write on behalf of a visitor and shapes the outcome. Never echoes
+// the CMS body: at depth > 0 it carries the populated project (deploy hooks,
+// tokens) and its errors name internal fields.
+export async function writeThroughCms(
+	cms: FormOwnershipCheck,
+	formId: string,
+	write: () => Promise<CmsResult>,
+	shape: WriteShape,
+): Promise<Response> {
+	let result: CmsResult;
+	try {
+		if (!(await cms.formBelongsToProject(formId))) {
+			return jsonResponse({ error: 'Invalid form id' }, 400);
+		}
+		result = await write();
+	} catch {
+		return jsonResponse({ error: shape.failed }, 502);
+	}
+
+	if (result.status >= 200 && result.status < 300) {
+		return jsonResponse(shape.success(result.id), 201);
+	}
+	const message = shape.passThrough[result.status];
+	if (message !== undefined) {
+		// Field *names* only, and only ones the CMS named: enough for the browser
+		// to put an error under the right input, while the message it shows stays
+		// the site's own. The CMS's wording never travels.
+		const fields = result.fields?.length ? { fields: result.fields } : {};
+		return jsonResponse({ error: message, ...fields }, result.status);
+	}
+	return jsonResponse({ error: shape.failed }, 502);
+}

package/src/form-proxy/http.ts

@@ -0,0 +1,96 @@
+export function jsonResponse(body: unknown, status: number) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { 'Content-Type': 'application/json' },
+	});
+}
+
+function declaredLength(request: Request): number | null {
+	const raw = request.headers.get('Content-Length');
+	if (raw === null) {
+		return null;
+	}
+	const n = Number(raw);
+	return Number.isFinite(n) ? n : null;
+}
+
+export function exceedsLimit(request: Request, maxBytes: number): boolean {
+	const declared = declaredLength(request);
+	return declared !== null && declared > maxBytes;
+}
+
+export type BodyRead<T> =
+	| { ok: true; value: T }
+	| { ok: false; response: Response };
+
+// Reads a body without trusting Content-Length: the declared size is a cheap
+// early exit, the actual byte count is what enforces the cap.
+export async function readBodyWithin(
+	request: Request,
+	maxBytes: number,
+	tooLarge: string,
+): Promise<BodyRead<ArrayBuffer>> {
+	if (exceedsLimit(request, maxBytes)) {
+		return { ok: false, response: jsonResponse({ error: tooLarge }, 413) };
+	}
+
+	const bytes = await request.arrayBuffer();
+	if (bytes.byteLength > maxBytes) {
+		return { ok: false, response: jsonResponse({ error: tooLarge }, 413) };
+	}
+	return { ok: true, value: bytes };
+}
+
+export async function readJsonBody(
+	request: Request,
+	maxBytes: number,
+): Promise<BodyRead<unknown>> {
+	const read = await readBodyWithin(request, maxBytes, 'Payload too large');
+	if (!read.ok) {
+		return read;
+	}
+
+	try {
+		return {
+			ok: true,
+			value: JSON.parse(new TextDecoder().decode(read.value)),
+		};
+	} catch {
+		return {
+			ok: false,
+			response: jsonResponse({ error: 'Invalid JSON' }, 400),
+		};
+	}
+}
+
+export async function readMultipartBody(
+	request: Request,
+	maxBytes: number,
+): Promise<BodyRead<FormData>> {
+	const contentType = request.headers.get('Content-Type') ?? '';
+	if (!contentType.includes('multipart/form-data')) {
+		return {
+			ok: false,
+			response: jsonResponse({ error: 'Expected multipart form data' }, 400),
+		};
+	}
+
+	const read = await readBodyWithin(request, maxBytes, 'File too large');
+	if (!read.ok) {
+		return read;
+	}
+
+	try {
+		// Re-wrapping the capped bytes keeps the multipart parser off the raw
+		// request stream, so it can never buffer more than we already allowed.
+		const value = await new Response(read.value, {
+			headers: { 'Content-Type': contentType },
+		}).formData();
+		return { ok: true, value };
+	} catch {
+		return {
+			ok: false,
+			response: jsonResponse({ error: 'Invalid multipart body' }, 400),
+		};
+	}
+}

package/src/form-proxy/index.ts

@@ -0,0 +1,73 @@
+import type { Project } from '../payload-types';
+import type { FormProxyCmsClient } from './cms-client';
+import { createRateLimiter, type RateLimiter } from './rate-limit';
+import { handleFormSubmission } from './submissions';
+import type { ProxyDeps } from './types';
+import { handleFormUpload } from './uploads';
+
+export type { FormProxyCmsClient } from './cms-client';
+export { createFormProxyCmsClient } from './cms-client';
+export { refusedFieldNames } from './cms-errors';
+export { createRateLimiter, type RateLimiter } from './rate-limit';
+export {
+	handleFormSubmission,
+	MAX_SUBMISSION_BYTES,
+	type SubmissionsCmsClient,
+} from './submissions';
+export type { CmsResult, FormOwnershipCheck, ProxyDeps } from './types';
+export { handleFormUpload, type UploadsCmsClient } from './uploads';
+
+/**
+ * The part of an Astro `APIContext` the proxy reads. `clientAddress` is a
+ * getter that throws on a prerendered route, which is why it is read guarded.
+ */
+export interface RequestContext {
+	readonly clientAddress: string;
+}
+
+function clientAddress(context: RequestContext): string {
+	try {
+		return context.clientAddress;
+	} catch {
+		return 'unknown';
+	}
+}
+
+export type FormProxy = ReturnType<typeof createFormProxy>;
+
+export function createFormProxy(
+	cms: FormProxyCmsClient,
+	project: () => Promise<Project>,
+	locales: readonly string[],
+) {
+	// One instance per function container; see rate-limit.ts for the caveat.
+	const submissionLimiter = createRateLimiter({
+		limit: 10,
+		windowMs: 60_000,
+	});
+	const uploadLimiter = createRateLimiter({ limit: 20, windowMs: 60_000 });
+
+	// Everything a handler needs from the running site: the tenant our key
+	// writes into, the CMS client, and who is asking.
+	async function buildProxyDeps(
+		context: RequestContext,
+		rateLimiter: RateLimiter,
+	): Promise<ProxyDeps<FormProxyCmsClient>> {
+		return {
+			projectId: (await project()).id,
+			cms,
+			clientAddress: clientAddress(context),
+			rateLimiter,
+			locales,
+		};
+	}
+
+	return {
+		cms,
+		submissionLimiter,
+		uploadLimiter,
+		buildProxyDeps,
+		handleFormSubmission,
+		handleFormUpload,
+	};
+}

package/src/form-proxy/rate-limit.ts

@@ -0,0 +1,46 @@
+export interface RateLimiter {
+	allow(key: string): boolean;
+}
+
+interface Options {
+	limit: number;
+	windowMs: number;
+	now?: () => number;
+}
+
+// Fixed-window counter held in memory. On Vercel each function instance keeps
+// its own table, so this is a best-effort brake on bursts from one client, not
+// a global quota — the Vercel Firewall rate-limit rule is the authoritative one.
+export function createRateLimiter({
+	limit,
+	windowMs,
+	now = Date.now,
+}: Options): RateLimiter {
+	const windows = new Map<string, { start: number; count: number }>();
+
+	function sweep(current: number) {
+		for (const [key, entry] of windows) {
+			if (current - entry.start > windowMs) {
+				windows.delete(key);
+			}
+		}
+	}
+
+	return {
+		allow(key) {
+			const current = now();
+			const entry = windows.get(key);
+
+			if (!entry || current - entry.start > windowMs) {
+				if (windows.size > 10_000) {
+					sweep(current);
+				}
+				windows.set(key, { start: current, count: 1 });
+				return true;
+			}
+
+			entry.count += 1;
+			return entry.count <= limit;
+		},
+	};
+}

package/src/form-proxy/submissions.ts

@@ -0,0 +1,88 @@
+import type { Locale } from '../locales';
+import { writeThroughCms } from './cms-write';
+import { jsonResponse, readJsonBody } from './http';
+import type { CmsResult, FormOwnershipCheck, ProxyDeps } from './types';
+
+export interface SubmissionsCmsClient extends FormOwnershipCheck {
+	createSubmission(
+		payload: {
+			form: string;
+			project: string;
+			data: Record<string, unknown>;
+			honeypot: string;
+		},
+		locale?: Locale,
+	): Promise<CmsResult>;
+}
+
+// Generous for a contact form, tiny for anything trying to hurt the CMS
+export const MAX_SUBMISSION_BYTES = 64 * 1024;
+
+// Every locale the CMS schema knows: the default when a site names none.
+const CMS_LOCALES: readonly Locale[] = ['es', 'en'];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// The field ships empty; a real visitor never touches it. Anything else in
+// there, whatever its type, was put there by a script.
+function honeypotFilled(value: unknown): boolean {
+	return value !== undefined && value !== null && value !== '';
+}
+
+export async function handleFormSubmission(
+	request: Request,
+	deps: ProxyDeps<SubmissionsCmsClient>,
+): Promise<Response> {
+	if (deps.rateLimiter && !deps.rateLimiter.allow(deps.clientAddress)) {
+		return jsonResponse({ error: 'Too many requests' }, 429);
+	}
+
+	const read = await readJsonBody(request, MAX_SUBMISSION_BYTES);
+	if (!read.ok) {
+		return read.response;
+	}
+	const body = read.value;
+
+	if (!isRecord(body)) {
+		return jsonResponse({ error: 'Invalid data' }, 400);
+	}
+	if (typeof body.form !== 'string' || !body.form) {
+		return jsonResponse({ error: 'Invalid form id' }, 400);
+	}
+	// The browser does not get to pick the tenant our API key writes into
+	if (body.project !== deps.projectId) {
+		return jsonResponse({ error: 'Invalid project id' }, 400);
+	}
+	if (!isRecord(body.data)) {
+		return jsonResponse({ error: 'Invalid data' }, 400);
+	}
+	// A filled honeypot is a bot; don't spend a CMS call on it
+	if (honeypotFilled(body.honeypot)) {
+		return jsonResponse({ error: 'Invalid submission' }, 400);
+	}
+
+	const form = body.form;
+	const data = body.data;
+	const locales = deps.locales ?? CMS_LOCALES;
+	const locale =
+		typeof body.locale === 'string' && locales.includes(body.locale)
+			? (body.locale as Locale)
+			: undefined;
+
+	return writeThroughCms(
+		deps.cms,
+		form,
+		() =>
+			deps.cms.createSubmission(
+				{ form, project: deps.projectId, data, honeypot: '' },
+				locale,
+			),
+		{
+			success: (id) => ({ ok: true, id }),
+			passThrough: { 400: 'Invalid submission' },
+			failed: 'Submission failed',
+		},
+	);
+}

package/src/form-proxy/types.ts

@@ -0,0 +1,23 @@
+import type { RateLimiter } from './rate-limit';
+
+// What a CMS write gives back to the handlers: the status to branch on, the
+// new document id, and — when the CMS refused the write field by field — the
+// names of the form's own fields it would not accept. Never the document
+// itself, and never the CMS's own wording; see cms-errors.ts.
+export type CmsResult = { status: number; id?: string; fields?: string[] };
+
+export interface FormOwnershipCheck {
+	formBelongsToProject(formId: string): Promise<boolean>;
+}
+
+export interface ProxyDeps<TClient extends FormOwnershipCheck> {
+	projectId: string;
+	cms: TClient;
+	clientAddress: string;
+	rateLimiter?: RateLimiter;
+	/**
+	 * The locales a submission may name. Defaults to every locale the CMS
+	 * schema knows.
+	 */
+	locales?: readonly string[];
+}

package/src/form-proxy/upload-policy.ts

@@ -0,0 +1,92 @@
+// What the CMS's `form-uploads` collection accepts, mirrored here so the
+// browser, the proxy route and the CMS agree about the same file.
+//
+// The CMS is the authority: `src/blocks/Form/uploadPolicy.ts` there declares
+// the size limit and the MIME map, and since postedin/cms#278 it enforces both
+// — a file over the limit is answered 413, a type outside the list 400. It also
+// *sniffs the bytes*, which nothing on this side can do, so a file whose
+// contents do not match its name passes every check here and is still refused.
+// Everything below is therefore an early, friendlier "no", never a guarantee of
+// a "yes".
+//
+// A leaf module with no imports: the React form islands read it in the browser
+// and the proxy handler reads it on the server.
+
+/** 10 MB, matching `MAX_UPLOAD_FILE_SIZE` in the CMS. */
+export const MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Room for the multipart envelope around a max-size file.
+ *
+ * Here rather than beside the handler that reads it so that every limit the
+ * upload path is held to is in one file, which is also the file the browser
+ * imports — importing it from the handler would pull the handler into the
+ * client bundle.
+ */
+export const MAX_REQUEST_BYTES = MAX_UPLOAD_BYTES + 64 * 1024;
+
+/**
+ * The MIME types behind each choice in a file field's `allowedFileTypes`, and
+ * — flattened — the whole of what the CMS accepts.
+ *
+ * `application/x-cfb` is what a legacy `.doc` or `.xls` sniffs as; the CMS
+ * carries it for that reason and it is kept here so the two lists can be
+ * compared line by line.
+ */
+export const FILE_TYPE_MIME_MAP: Record<string, string[]> = {
+	images: [
+		'image/jpeg',
+		'image/png',
+		'image/gif',
+		'image/webp',
+		'image/svg+xml',
+	],
+	documents: [
+		'application/pdf',
+		'application/msword',
+		'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+		'application/vnd.ms-excel',
+		'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+		'application/x-cfb',
+		'text/plain',
+	],
+	videos: ['video/mp4', 'video/webm', 'video/ogg', 'video/quicktime'],
+	audio: ['audio/mpeg', 'audio/ogg', 'audio/wav', 'audio/webm'],
+};
+
+export const ALLOWED_UPLOAD_MIME_TYPES: string[] = [
+	...new Set(Object.values(FILE_TYPE_MIME_MAP).flat()),
+];
+
+/** The `accept` attribute for a file field's declared `allowedFileTypes`. */
+export function acceptAttribute(types?: string[] | null): string {
+	if (!types || types.length === 0) {
+		return '';
+	}
+	return types.flatMap((type) => FILE_TYPE_MIME_MAP[type] ?? []).join(',');
+}
+
+/** Why the CMS would refuse this file, as far as the browser can tell. */
+export type UploadRefusal = 'size' | 'type';
+
+/**
+ * The refusal a file would earn before it is sent, or `null` to send it.
+ *
+ * A file the browser reports no type for is sent: an empty `type` is what
+ * Chrome gives an extension it does not recognise, and the CMS sniffs the bytes
+ * anyway, so guessing here would refuse files the CMS would have taken. The
+ * types a field does not ask for are left to the `accept` attribute and to the
+ * CMS; this only holds a file to what the collection accepts at all.
+ */
+export function uploadRefusal(file: {
+	size: number;
+	type: string;
+}): UploadRefusal | null {
+	if (file.size > MAX_UPLOAD_BYTES) {
+		return 'size';
+	}
+	if (file.type && !ALLOWED_UPLOAD_MIME_TYPES.includes(file.type)) {
+		return 'type';
+	}
+	return null;
+}

package/src/form-proxy/uploads.ts

@@ -0,0 +1,81 @@
+import { writeThroughCms } from './cms-write';
+import { jsonResponse, readMultipartBody } from './http';
+import { MAX_REQUEST_BYTES, MAX_UPLOAD_BYTES } from './upload-policy';
+import type { CmsResult, FormOwnershipCheck, ProxyDeps } from './types';
+
+export interface UploadsCmsClient extends FormOwnershipCheck {
+	createUpload(
+		file: File,
+		payload: { form: string; project: string },
+	): Promise<CmsResult>;
+}
+
+function parsePayload(
+	raw: FormDataEntryValue | null,
+): { form: string; project: unknown } | null {
+	if (typeof raw !== 'string') {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (
+			typeof parsed !== 'object' ||
+			parsed === null ||
+			typeof parsed.form !== 'string' ||
+			!parsed.form
+		) {
+			return null;
+		}
+		return { form: parsed.form, project: parsed.project };
+	} catch {
+		return null;
+	}
+}
+
+export async function handleFormUpload(
+	request: Request,
+	deps: ProxyDeps<UploadsCmsClient>,
+): Promise<Response> {
+	if (deps.rateLimiter && !deps.rateLimiter.allow(deps.clientAddress)) {
+		return jsonResponse({ error: 'Too many requests' }, 429);
+	}
+
+	const read = await readMultipartBody(request, MAX_REQUEST_BYTES);
+	if (!read.ok) {
+		return read.response;
+	}
+	const formData = read.value;
+
+	const file = formData.get('file');
+	if (!(file instanceof File)) {
+		return jsonResponse({ error: 'Missing file' }, 400);
+	}
+	if (file.size > MAX_UPLOAD_BYTES) {
+		return jsonResponse({ error: 'File too large' }, 413);
+	}
+
+	const payload = parsePayload(formData.get('_payload'));
+	if (!payload) {
+		return jsonResponse({ error: 'Invalid form id' }, 400);
+	}
+	// The browser does not get to pick the tenant our API key writes into
+	if (payload.project !== deps.projectId) {
+		return jsonResponse({ error: 'Invalid project id' }, 400);
+	}
+
+	// The client reads doc.id and branches on 400 (type) / 413 (size)
+	return writeThroughCms(
+		deps.cms,
+		payload.form,
+		() =>
+			deps.cms.createUpload(file, {
+				form: payload.form,
+				project: deps.projectId,
+			}),
+		{
+			success: (id) => ({ doc: { id } }),
+			passThrough: { 400: 'Invalid file', 413: 'File too large' },
+			failed: 'Upload failed',
+		},
+	);
+}