caracms 0.0.0-stage → 0.2.0

package/src/forms/rate-limit.ts

@@ -0,0 +1,130 @@
+/**
+ * The form endpoint's rate limit (M6 Decision 5): 5 hits per visitor IP per 10 minutes.
+ *
+ * - **In Redis** whenever the server has `REDIS_URL` (live mode always does in
+ *   production), as expiring counters, so the count survives a deploy. One window per
+ *   IP starts with its first hit (sign-in's limits do the same, live/auth/links.ts).
+ * - **In memory** without it (local mode, tests).
+ * - **Redis out fails open**, with a log line: the limit is spam control, and a
+ *   visitor's message matters more than a counter (the honeypot and Turnstile stand).
+ *
+ * `peek` only looks (the check before a large body is read); `hit` counts one and says
+ * whether that one is over the limit.
+ *
+ * **One limiter per use** (M6c Decision 6): each instance has its own key prefix, limit
+ * and window (`LimitSettings`), so the public file route's downloads (files-route.ts,
+ * `caracms:files:rl:`) never use up a visitor's contact-form allowance. The forms' own
+ * settings are `FORM_LIMIT`, unchanged.
+ */
+import { createHash } from 'node:crypto';
+import { connectRedis, type RedisClient } from '../live/redis.ts';
+
+export const RATE_LIMIT = { max: 5, windowMs: 10 * 60 * 1000 } as const;
+
+/** One limiter's settings: its Redis key prefix, its limit and window, and what its log line calls a hit. */
+export interface LimitSettings {
+	/** Ends in `:`; the hashed IP follows. */
+	prefix: string;
+	max: number;
+	windowMs: number;
+	/** The log line's words: `forms` / `submission`. */
+	area: string;
+	hitName: string;
+}
+
+/** The forms' limiter (M6 Decision 5). */
+export const FORM_LIMIT: LimitSettings = { prefix: 'caracms:forms:rl:', ...RATE_LIMIT, area: 'forms', hitName: 'submission' };
+
+export interface RateLimiter {
+	/** Already at the limit? Records nothing. */
+	peek(ip: string): Promise<boolean>;
+	/** Count a hit: true when this one is over the limit. */
+	hit(ip: string): Promise<boolean>;
+}
+
+/** The forms' name for it, kept. */
+export type FormRateLimiter = RateLimiter;
+
+export function memoryLimiter(options: { now?: () => number; max?: number; windowMs?: number } = {}): RateLimiter {
+	const now = options.now ?? Date.now;
+	const max = options.max ?? FORM_LIMIT.max;
+	const windowMs = options.windowMs ?? FORM_LIMIT.windowMs;
+	const hits = new Map<string, number[]>();
+	const recent = (ip: string) => (hits.get(ip) ?? []).filter((t) => t > now() - windowMs);
+	return {
+		async peek(ip) {
+			return recent(ip).length >= max;
+		},
+		async hit(ip) {
+			if (hits.size > 1000) for (const [k] of hits) if (recent(k).length === 0) hits.delete(k);
+			const times = recent(ip);
+			times.push(now());
+			hits.set(ip, times);
+			return times.length > max;
+		},
+	};
+}
+
+/** `options` defaults to the forms' settings. */
+export function redisLimiter(redis: RedisClient, log: (line: string) => void = (l) => console.error(l), options: Partial<LimitSettings> = {}): RateLimiter {
+	const { prefix, max, windowMs, area, hitName } = { ...FORM_LIMIT, ...options };
+	const key = (ip: string) => `${prefix}${createHash('sha256').update(ip).digest('hex')}`;
+	const failOpen = (error: unknown) => {
+		log(`[caracms] ${area}: couldn't reach Redis for the rate limit, so this ${hitName} wasn't counted: ${error instanceof Error ? error.message : String(error)}`);
+		return false;
+	};
+	return {
+		async peek(ip) {
+			try {
+				return Number((await redis.get(key(ip))) ?? 0) >= max;
+			} catch (error) {
+				return failOpen(error);
+			}
+		},
+		async hit(ip) {
+			try {
+				const k = key(ip);
+				const count = await redis.incr(k);
+				// The first hit starts the window; a key left with no expiry (a crash between the calls) gets one now.
+				if (count === 1 || (await redis.pttl(k)) === -1) await redis.pexpire(k, windowMs);
+				return count > max;
+			} catch (error) {
+				return failOpen(error);
+			}
+		},
+	};
+}
+
+type Shared = Record<symbol, { url: string | null; limiter: RateLimiter } | undefined>;
+
+/**
+ * The process's limiter for one use, kept on `globalThis` under `name` (a `Symbol.for`
+ * key, so Vite's module copies share it): Redis at `REDIS_URL` when it's set, else memory.
+ */
+export function processLimiter(name: string, settings: LimitSettings, env: Record<string, string | undefined> = process.env): RateLimiter {
+	const slot = Symbol.for(name);
+	const url = env['REDIS_URL']?.trim() || null;
+	const g = globalThis as Shared;
+	const held = g[slot];
+	if (held && held.url === url) return held.limiter;
+	const limiter = url ? redisLimiter(connectRedis(url), undefined, settings) : memoryLimiter({ max: settings.max, windowMs: settings.windowMs });
+	g[slot] = { url, limiter };
+	return limiter;
+}
+
+/** Forget one use's process limiter (tests). */
+export function resetProcessLimiter(name: string): void {
+	delete (globalThis as Shared)[Symbol.for(name)];
+}
+
+const FORMS = 'caracms.formLimiter';
+
+/** The forms' process limiter. */
+export function formLimiter(env: Record<string, string | undefined> = process.env): FormRateLimiter {
+	return processLimiter(FORMS, FORM_LIMIT, env);
+}
+
+/** Forget the forms' process limiter (tests). */
+export function resetFormLimiter(): void {
+	resetProcessLimiter(FORMS);
+}

package/src/forms/route.ts

@@ -0,0 +1,24 @@
+/**
+ * `POST /_caracms/form` (M6 Decision 5): the public forms' endpoint, on demand. Public in
+ * every mode: the guard lets it through and the unconfigured 503 exempts it. The rules
+ * are endpoint.ts's.
+ */
+import type { APIRoute } from 'astro';
+import { site } from 'virtual:caracms/config';
+import { handleForm } from './endpoint.ts';
+
+export const prerender = false;
+
+export const ALL: APIRoute = (context) =>
+	handleForm(context.request, {
+		site,
+		astroSite: context.site,
+		// Astro's getter throws where the adapter gives no address (tests' containers).
+		clientAddress: () => {
+			try {
+				return context.clientAddress;
+			} catch {
+				return undefined;
+			}
+		},
+	});

package/src/forms/rules.ts

@@ -0,0 +1,278 @@
+/**
+ * The forms config's rules (M6 Decision 4), and what the endpoint, the email, the
+ * inbox and the public form share about a form: the honeypot's name, the hidden
+ * fields, the upload limits, the sender's name and the snippet.
+ *
+ * The template is the rulebook (`tina-astro-template/docs/forms.md` → The forms
+ * config, Files: the wire contract); this is its `form-rules.mjs` and the shared parts
+ * of `form-field-types.mjs`, with caracms's shape: forms are `defineSite({ forms })`,
+ * keyed by id, their fields keyed by name in the form's order.
+ *
+ * Browser-safe (no imports): the editor's inbox reads `senderName`, `formatBytes` and
+ * the id pattern too.
+ */
+
+/** The six field types (Decision 4). The template's site-own types are deferred. */
+export const FORM_FIELD_TYPES = ['text', 'email', 'tel', 'textarea', 'select', 'files'] as const;
+export type FormFieldType = (typeof FORM_FIELD_TYPES)[number];
+
+/** One field of a form, as the site's config writes it (Contracts → The forms config). */
+export interface FormFieldConfig {
+	label: string;
+	/** Default `text`. */
+	type?: FormFieldType;
+	/** Required unless this is set: blank and absent are then both fine (stored as `''`). */
+	optional?: boolean;
+	/** A select's fixed choices; the endpoint accepts only their values. Select only. */
+	options?: { value: string; label: string }[];
+	/** A line under the field. */
+	help?: string;
+	/** The browser's hint, and the inbox's sender name (`name`, or `given-name` + `family-name`). */
+	autocomplete?: string;
+	/** The line under the field when it's blank or wrong; blank uses the type's own wording. */
+	error?: string;
+	/**
+	 * The input's hint text inside the box (`placeholder`): text, email, tel and textarea
+	 * only. It never replaces the label, which stays in the markup for screen readers even
+	 * when a site hides it. Plain text, trimmed; blank is the same as leaving it out.
+	 */
+	placeholder?: string;
+	/**
+	 * A short fixed text drawn before the input, like "$" on a price: text and tel only.
+	 * Only for show: it isn't part of what's sent, stored, emailed or shown in the inbox.
+	 * Plain text, trimmed; blank is the same as leaving it out.
+	 */
+	prefix?: string;
+	/** A textarea's height in lines (`rows`), a whole number from 1 to 50. Default 6. Textarea only. */
+	rows?: number;
+}
+
+/** One form (Contracts → The forms config). Its key is its id: stored on submissions, keys `formRecipients`; never renamed once live. */
+export interface FormConfig {
+	/** "Contact": the inbox, the email, Site Settings. */
+	label: string;
+	/** The email's subject starts with this: `<subject> — <brand name> website`. */
+	email: { subject: string };
+	/** The fields by name, in the form's order. */
+	fields: Record<string, FormFieldConfig>;
+}
+
+export interface ResolvedFormField {
+	name: string;
+	label: string;
+	type: FormFieldType;
+	optional: boolean;
+	options?: { value: string; label: string }[];
+	help?: string;
+	autocomplete?: string;
+	error?: string;
+	placeholder?: string;
+	prefix?: string;
+	rows?: number;
+}
+
+/** A form as the package uses it: its fields as a list, in order, each with its type. Plain JSON. */
+export interface ResolvedForm {
+	id: string;
+	label: string;
+	email: { subject: string };
+	fields: ResolvedFormField[];
+}
+
+/**
+ * The honeypot's name (Decision 5): a hidden field only a bot fills in. `fax`, not
+ * `company`: a real form can have a Company field (the template's lesson). The form
+ * component renders it from here and the endpoint reads it from here.
+ */
+export const HONEYPOT = 'fax';
+
+/** The form's hidden fields: its id, the no-JS return page, and Turnstile's token. */
+export const HIDDEN_FIELDS = ['form', 'return', 'cf-turnstile-response'] as const;
+
+/** Names a form's field can't take. */
+export const RESERVED_FIELD_NAMES: readonly string[] = [HONEYPOT, ...HIDDEN_FIELDS];
+
+/** At most this many files on one submission. */
+export const MAX_FILES = 5;
+/** At most this many bytes of files in all, on one submission: 25 MB. */
+export const MAX_FILE_BYTES = 25 * 1024 * 1024;
+
+/**
+ * The extensions a files field takes, each with the declared types it may come with.
+ * **The extension decides the type**: a declared type must be blank,
+ * `application/octet-stream` or one listed here. The first is the type a download is
+ * served as.
+ */
+export const FILE_TYPES: Readonly<Record<string, readonly string[]>> = {
+	jpg: ['image/jpeg', 'image/pjpeg'],
+	jpeg: ['image/jpeg', 'image/pjpeg'],
+	png: ['image/png'],
+	webp: ['image/webp'],
+	heic: ['image/heic', 'image/heif', 'image/heic-sequence', 'image/heif-sequence'],
+	pdf: ['application/pdf'],
+	doc: ['application/msword'],
+	docx: ['application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
+	xls: ['application/vnd.ms-excel'],
+	xlsx: ['application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
+};
+
+/** The allowed kinds, as a visitor reads them (the endpoint's refusal names them). */
+export const FILE_KINDS = 'JPEG, PNG, WebP, HEIC, PDF, Word or Excel';
+
+/** The file input's `accept`. */
+export const FILE_ACCEPT = Object.keys(FILE_TYPES)
+	.map((ext) => `.${ext}`)
+	.join(',');
+
+/** The types that take a placeholder: the ones a visitor types into. */
+export const PLACEHOLDER_TYPES: readonly FormFieldType[] = ['text', 'email', 'tel', 'textarea'];
+/** The types that take a prefix: a one-line box where a fixed lead-in reads naturally ("$", "+353"). */
+const PREFIX_TYPES: readonly FormFieldType[] = ['text', 'tel'];
+
+const FORM_ID = /^[a-z][a-z0-9-]*$/;
+/** A field's name goes into the form's markup and the stored JSON: letters, digits, `_` and `-`. */
+const FIELD_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+/**
+ * Check the site's forms (Decision 4: `forms.md` → The forms config's `checkForms()`
+ * list) and resolve them. `fail` throws the sentence, which names the form and the
+ * field. Refused: the honeypot's name or a hidden field's, a duplicate, no `email`
+ * field, more than one `files` field, a select without options, options on a field
+ * that isn't a select, and a type that isn't one of the six.
+ */
+export function checkForms(forms: unknown, fail: (message: string) => never): Record<string, ResolvedForm> {
+	if (forms === undefined) return {};
+	if (!forms || typeof forms !== 'object' || Array.isArray(forms)) fail('forms must be an object of forms by id, like { contact: { label, email, fields } }.');
+	const out: Record<string, ResolvedForm> = {};
+	for (const [id, raw] of Object.entries(forms as Record<string, unknown>)) {
+		const where = `form "${id}"`;
+		if (!FORM_ID.test(id)) fail(`${where}: its id must be lowercase letters, digits and hyphens (it's stored on every submission).`);
+		const form = (raw ?? {}) as Partial<FormConfig>;
+		if (typeof form !== 'object' || Array.isArray(form)) fail(`${where} must be an object: { label, email: { subject }, fields }.`);
+		if (typeof form.label !== 'string' || !form.label.trim()) fail(`${where} needs a label (the inbox, the email and Site Settings name it by it).`);
+		if (typeof form.email?.subject !== 'string' || !form.email.subject.trim()) fail(`${where} needs email.subject, like "New contact enquiry".`);
+		if (!form.fields || typeof form.fields !== 'object' || Array.isArray(form.fields)) fail(`${where} needs fields, an object of fields by name.`);
+		const fields: ResolvedFormField[] = [];
+		const seen = new Set<string>();
+		let filesField: string | null = null;
+		for (const [name, rawField] of Object.entries(form.fields!)) {
+			const at = `${where}, field "${name}"`;
+			if (RESERVED_FIELD_NAMES.includes(name)) {
+				fail(`${at}: "${name}" is taken (${name === HONEYPOT ? 'the honeypot, a field only a bot fills in' : "one of the form's hidden fields"}); name the field something else.`);
+			}
+			if (!FIELD_NAME.test(name)) fail(`${at}: a field's name must start with a letter and hold only letters, digits, "_" and "-".`);
+			// Object keys can't repeat, but two spellings of one name would post as one field.
+			if (seen.has(name.toLowerCase())) fail(`${at} is listed twice (field names are compared without case).`);
+			seen.add(name.toLowerCase());
+			const field = (rawField ?? {}) as Partial<FormFieldConfig>;
+			if (typeof field.label !== 'string' || !field.label.trim()) fail(`${at} needs a label (what the visitor sees).`);
+			const type = field.type ?? 'text';
+			if (!(FORM_FIELD_TYPES as readonly string[]).includes(type)) fail(`${at}: type must be one of ${FORM_FIELD_TYPES.join(', ')} (got ${JSON.stringify(field.type)}).`);
+			if (type === 'select') {
+				if (!Array.isArray(field.options) || field.options.length === 0) fail(`${at}: a select needs options, like [{ value: 'branding', label: 'Branding' }].`);
+				const values = new Set<string>();
+				for (const option of field.options!) {
+					if (typeof option?.value !== 'string' || !option.value || typeof option.label !== 'string' || !option.label) fail(`${at}: every option needs a value and a label.`);
+					if (values.has(option.value)) fail(`${at}: the option "${option.value}" is listed twice.`);
+					values.add(option.value);
+				}
+			} else if (field.options !== undefined) {
+				fail(`${at}: only a select takes options (this one is ${type}).`);
+			}
+			if (type === 'files') {
+				if (filesField) fail(`${at}: a form has at most one files field ("${filesField}" is the first).`);
+				filesField = name;
+			}
+			if (field.optional !== undefined && typeof field.optional !== 'boolean') fail(`${at}: optional must be true or left out.`);
+			for (const key of ['help', 'autocomplete', 'error', 'placeholder', 'prefix'] as const) {
+				if (field[key] !== undefined && typeof field[key] !== 'string') fail(`${at}: ${key} must be text.`);
+			}
+			const placeholder = field.placeholder?.trim() ?? '';
+			if (placeholder && !PLACEHOLDER_TYPES.includes(type)) fail(`${at}: a ${type} field has no box to type in, so it can't take a placeholder (only ${PLACEHOLDER_TYPES.join(', ')} can).`);
+			const prefix = field.prefix?.trim() ?? '';
+			if (prefix && !PREFIX_TYPES.includes(type)) fail(`${at}: only a text or tel field takes a prefix (this one is ${type}).`);
+			if (field.rows !== undefined) {
+				if (type !== 'textarea') fail(`${at}: only a textarea takes rows (this one is ${type}).`);
+				if (!Number.isInteger(field.rows) || field.rows < 1 || field.rows > 50) fail(`${at}: rows must be a whole number from 1 to 50 (got ${JSON.stringify(field.rows)}).`);
+			}
+			fields.push({
+				name,
+				label: field.label!.trim(),
+				type,
+				optional: field.optional === true,
+				...(type === 'select' ? { options: field.options!.map((o) => ({ value: o.value, label: o.label })) } : {}),
+				...(field.help ? { help: field.help } : {}),
+				...(field.autocomplete ? { autocomplete: field.autocomplete } : {}),
+				...(field.error ? { error: field.error } : {}),
+				...(placeholder ? { placeholder } : {}),
+				...(prefix ? { prefix } : {}),
+				...(field.rows !== undefined ? { rows: field.rows } : {}),
+			});
+		}
+		const email = fields.find((f) => f.name === 'email');
+		if (!email) fail(`${where} needs a field named "email", with type 'email': the visitor's address, which the email's Reply-To uses.`);
+		if (email!.type !== 'email') fail(`${where}, field "email": its type must be 'email' (it's the visitor's address, the email's Reply-To).`);
+		out[id] = { id, label: form.label!.trim(), email: { subject: form.email!.subject.trim() }, fields };
+	}
+	return out;
+}
+
+const RETURN_PATH = /^\/[a-z0-9/-]*$/;
+
+/** The no-JS return page (Decision 5): a path on this site matching `^/[a-z0-9/-]*$` and not `//…`, else `/`. */
+export function cleanReturn(value: string): string {
+	return RETURN_PATH.test(value) && !value.startsWith('//') ? value : '/';
+}
+
+/** Whether any form takes files: the endpoint's upload cap is there only then (Decision 5). */
+export const formsAcceptFiles = (forms: Readonly<Record<string, Pick<ResolvedForm, 'fields'>>>): boolean =>
+	Object.values(forms).some((form) => form.fields.some((field) => field.type === 'files'));
+
+// Deliberately loose: an over-strict pattern refuses real addresses. The real check is the reply.
+export const looksLikeEmail = (value: string): boolean => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+
+/** A size as people read it: "812 bytes", "240 KB", "2.4 MB" (1 KB = 1024 bytes). */
+export function formatBytes(bytes: number): string {
+	const n = Number.isFinite(bytes) && bytes > 0 ? bytes : 0;
+	if (n < 1024) return `${n} ${n === 1 ? 'byte' : 'bytes'}`;
+	if (Math.round(n / 1024) < 1024) return `${Math.round(n / 1024)} KB`;
+	const mb = n / 1024 / 1024;
+	return `${mb < 10 ? mb.toFixed(1) : Math.round(mb)} MB`;
+}
+
+/** The last part of a name, whatever slashes a browser or a bot sent: `../../x.pdf` → `x.pdf`. */
+export const shownFileName = (name: string): string => name.split(/[\\/]/).pop() ?? '';
+
+/**
+ * A submission's id: the receive time with `:` and `.` swapped for `-`, then six
+ * random base-36 characters (`2026-09-25T09-14-02-123Z_k3f9a2`), so ids sort in
+ * received order. Every id from a URL is checked against this before it becomes a
+ * key or a path (the path-traversal guard).
+ */
+export const SUBMISSION_ID = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z_[a-z0-9]{6}$/;
+export const isSubmissionId = (id: unknown): id is string => typeof id === 'string' && SUBMISSION_ID.test(id);
+
+/** A submission's address in the editor (the email's link). */
+export const submissionAddress = (id: string): string => `/admin/submissions/${encodeURIComponent(id)}`;
+
+/**
+ * Who sent it (Decision 9, `forms.md` → The forms config): the field marked
+ * `autocomplete: 'name'`, else the `given-name` and `family-name` fields together,
+ * else the email address. A form no longer in the config: the address.
+ */
+export function senderName(form: Pick<ResolvedForm, 'fields'> | null, fields: Readonly<Record<string, unknown>>): string {
+	const value = (name: string | undefined) => (name && typeof fields[name] === 'string' ? (fields[name] as string).trim() : '');
+	const by = (hint: string) => form?.fields.find((f) => f.autocomplete === hint)?.name;
+	const full = value(by('name'));
+	if (full) return full;
+	const both = [value(by('given-name')), value(by('family-name'))].filter(Boolean).join(' ');
+	if (both) return both;
+	return value('email');
+}
+
+/** A row's one-line snippet (Decision 9): the form's first `textarea`, its lines joined, cut at 140 characters. '' when there's none. */
+export function submissionSnippet(form: Pick<ResolvedForm, 'fields'> | null, fields: Readonly<Record<string, unknown>>): string {
+	const name = form?.fields.find((f) => f.type === 'textarea')?.name;
+	const text = name && typeof fields[name] === 'string' ? (fields[name] as string).replace(/\s+/g, ' ').trim() : '';
+	return text.length > 140 ? `${text.slice(0, 139).trimEnd()}…` : text;
+}