domma-cms 0.22.5 → 0.23.0

package/server/routes/api/forms.js

@@ -1,746 +1,765 @@
-/**
- * Core Forms API Routes
- * REST endpoints for form CRUD, public rendering, and submission handling.
- * Submissions are stored exclusively in Collections (no dual-storage).
- *
- * Endpoints (prefix: /api):
- *   GET    /forms                          — admin: list all forms
- *   POST   /forms                          — admin: create new form
- *   GET    /forms/:slug                    — admin: get form definition
- *   GET    /forms/:slug/public             — public: get form (no actions block)
- *   PUT    /forms/:slug                    — admin: update form definition
- *   DELETE /forms/:slug                    — admin: delete form
- *   GET    /forms/:slug/submissions        — admin: list submissions from collection
- *   GET    /forms/:slug/submissions/export — admin: CSV export from collection
- *   DELETE /forms/:slug/submissions        — admin: clear all submissions
- *   DELETE /forms/:slug/submissions/:id    — admin: delete one submission
- *   POST   /forms/submit/:slug             — public: accept submission
- *   POST   /forms/test-email               — admin: send test email
- */
-import {createRequire} from 'module';
-import {fileURLToPath} from 'url';
-import path from 'path';
-import {deleteForm, ensureFormsDir, listForms, readForm, slugify, writeForm} from '../../services/forms.js';
-import {executeAction} from '../../services/actions.js';
-import {createTransport, sendFormEmail} from '../../services/email.js';
-import {
-    clearEntries,
-    createCollection,
-    createEntry,
-    deleteEntry,
-    getCollection,
-    listEntries
-} from '../../services/collections.js';
-import {getConfig} from '../../config.js';
-import {authenticate, requireAdmin, requirePermission} from '../../middleware/auth.js';
-import {hooks} from '../../services/hooks.js';
-import {saveMedia} from '../../services/content.js';
-import {v4 as uuidv4} from 'uuid';
-
-/**
- * Detect form↔collection mismatches at save time so admins know BEFORE
- * users hit silent rejection. Returns an array of human-readable warning
- * strings — empty when the form lines up cleanly with its target collection.
- *
- * Checks performed:
- *   - Target collection exists (otherwise every submission goes nowhere)
- *   - Every required collection field has a matching form field
- *   - Every form field references a known collection field (typos)
- *
- * @param {object} form - The just-saved form definition
- * @returns {Promise<string[]>}
- */
-async function detectFormCollectionMismatch(form) {
-    const warnings = [];
-    const colAction = form?.actions?.collection;
-    const targetSlug = (colAction?.enabled && colAction.slug) ? colAction.slug : form?.slug;
-    if (!targetSlug) return warnings;
-
-    let collection;
-    try {
-        collection = await getCollection(targetSlug);
-    } catch {
-        return warnings;
-    }
-    if (!collection) {
-        warnings.push(`Target collection "${targetSlug}" does not exist — submissions will fail. Either create the collection or change the form's target.`);
-        return warnings;
-    }
-
-    const formFieldNames = new Set((form.fields || []).map(f => f.name).filter(Boolean));
-    const colFieldNames  = new Set((collection.fields || []).map(f => f.name));
-
-    // Missing-required: collection requires X but form doesn't collect X
-    const missingRequired = (collection.fields || [])
-        .filter(f => f.required)
-        .filter(f => !formFieldNames.has(f.name))
-        .map(f => f.label || f.name);
-    if (missingRequired.length) {
-        warnings.push(`The "${targetSlug}" collection requires fields the form does not collect: ${missingRequired.join(', ')}. Submissions will be rejected with "X is required". Either mark these fields as not required on the collection, add them to the form, or set them via an action's createInCollection step.`);
-    }
-
-    // Unknown fields: form sends X but collection has no such field (typo / drift)
-    const unknown = [...formFieldNames].filter(n => !colFieldNames.has(n));
-    if (unknown.length) {
-        warnings.push(`The form has fields the "${targetSlug}" collection doesn't define: ${unknown.join(', ')}. These values will be stored but won't be validated, indexed, or displayed in [collection] blocks unless you add matching fields to the collection.`);
-    }
-
-    return warnings;
-}
-
-/**
- * Sanitise a user-supplied filename:
- *   - strip path separators and traversal markers
- *   - keep only `[a-z0-9._-]`, lower-case
- *   - prepend an 8-char uuid prefix so concurrent uploads of the same name
- *     don't overwrite each other
- *
- * @param {string} raw
- * @returns {string}
- */
-function safeFilename(raw) {
-    const cleaned = String(raw || 'upload')
-        .toLowerCase()
-        .replace(/[^\w.-]+/g, '-')
-        .replace(/-+/g, '-')
-        .replace(/^[-.]+|[-.]+$/g, '')
-        .slice(0, 200) || 'upload';
-    const prefix = uuidv4().slice(0, 8);
-    return `${prefix}-${cleaned}`;
-}
-
-/**
- * Check a multipart file part against a form's `type: file` field config.
- *
- * @param {object} fieldCfg    - The form-field definition
- * @param {object} part        - Multipart part (mimetype, filename)
- * @param {number} size        - Buffer length in bytes
- * @returns {string|null}      - Error message, or null if OK
- */
-function validateUpload(fieldCfg, part, size) {
-    const cfg = fieldCfg?.file || {};
-    const max = Number(cfg.maxSize) || 5 * 1024 * 1024;     // 5 MB default
-    if (size > max) {
-        return `"${fieldCfg.label || fieldCfg.name}" file is too large (max ${Math.round(max / 1024)} KB).`;
-    }
-    const accept = String(cfg.accept || '').trim();
-    if (accept) {
-        // Comma-separated list of mime types, allowing wildcards like image/*
-        const patterns = accept.split(',').map(s => s.trim()).filter(Boolean);
-        const mime     = part.mimetype || '';
-        const ok = patterns.some(p => {
-            if (p.endsWith('/*')) return mime.startsWith(p.slice(0, -1));
-            return p === mime;
-        });
-        if (!ok) {
-            return `"${fieldCfg.label || fieldCfg.name}" file type "${mime}" not allowed (expected: ${accept}).`;
-        }
-    }
-    return null;
-}
-
-/**
- * Drain a multipart request into a JSON-shaped body. Text parts become string
- * values; file parts are validated against the matching form field, saved to
- * `content/media/`, and replaced by a `{ url, name, size, mime }` reference.
- *
- * Throws on validation failure (caller handles HTTP 400). Files are streamed
- * into memory up to fastify-multipart's configured limit — fine for the
- * resume-pdf / portrait-photo scale; large uploads should still use the admin
- * media flow.
- *
- * @param {import('fastify').FastifyRequest} request
- * @param {object} form
- * @returns {Promise<object>}
- */
-async function parseMultipartForm(request, form) {
-    const out = {};
-    const fileFields = new Map(
-        (form.fields || []).filter(f => f.type === 'file').map(f => [f.name, f])
-    );
-
-    for await (const part of request.parts()) {
-        if (part.type === 'file') {
-            const fieldCfg = fileFields.get(part.fieldname);
-            if (!fieldCfg) {
-                // Unknown file field — drain and skip rather than 400, so a
-                // form that gains a file input later doesn't reject older
-                // submissions in-flight from a stale page.
-                for await (const _ of part.file) { /* drain */ }
-                continue;
-            }
-            const chunks = [];
-            for await (const chunk of part.file) chunks.push(chunk);
-            const buffer = Buffer.concat(chunks);
-            const err    = validateUpload(fieldCfg, part, buffer.length);
-            if (err) throw new Error(err);
-            if (buffer.length === 0) continue;     // empty file input — skip
-            const saved = await saveMedia(safeFilename(part.filename), buffer);
-            out[part.fieldname] = {
-                url:  saved.url,
-                name: part.filename,
-                size: buffer.length,
-                mime: part.mimetype
-            };
-        } else {
-            // Text field — last value wins on duplicates (browser-standard).
-            out[part.fieldname] = part.value;
-        }
-    }
-    return out;
-}
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const ROOT = path.resolve(__dirname, '..', '..', '..');
-
-// Load shared logic engine (UMD/CJS) from core public assets
-const _require = createRequire(import.meta.url);
-const FormLogicEngine = _require('../../../public/js/form-logic-engine.js');
-
-// Per-slug rate limit store: slug → Map<ip, timestamp[]>
-const rateLimitMap = new Map();
-
-function isRateLimited(slug, ip, limitPerMinute) {
-    const now      = Date.now();
-    const windowMs = 60 * 1000;
-    if (!rateLimitMap.has(slug)) rateLimitMap.set(slug, new Map());
-    const slugMap    = rateLimitMap.get(slug);
-    const timestamps = (slugMap.get(ip) || []).filter(t => now - t < windowMs);
-    if (timestamps.length >= limitPerMinute) return true;
-    timestamps.push(now);
-    slugMap.set(ip, timestamps);
-    return false;
-}
-
-function submissionsToCSV(form, entries) {
-    const fields  = (form.fields || []).filter(f => f.type !== 'page-break' && f.type !== 'spacer');
-    const headers = [...fields.map(f => `"${f.label || f.name}"`), '"Date"'];
-    const rows    = entries.map(e => {
-        const cols = fields.map(f => {
-            const raw = e.data?.[f.name] ?? '';
-            const str = Array.isArray(raw) ? raw.join('; ') : String(raw);
-            const val = str.replace(/"/g, '""');
-            return `"${val}"`;
-        });
-        cols.push(`"${e.meta?.createdAt || ''}"`);
-        return cols.join(',');
-    });
-    return [headers.join(','), ...rows].join('\n');
-}
-
-export async function formsRoutes(fastify) {
-    await ensureFormsDir();
-
-    const canRead   = { preHandler: [authenticate, requirePermission('collections', 'read')]   };
-    const canCreate = { preHandler: [authenticate, requirePermission('collections', 'create')] };
-    const canUpdate = { preHandler: [authenticate, requirePermission('collections', 'update')] };
-    const canDelete = { preHandler: [authenticate, requirePermission('collections', 'delete')] };
-
-    // -----------------------------------------------------------------------
-    // GET /forms — list all form definitions with submission counts
-    // -----------------------------------------------------------------------
-    fastify.get('/forms', canRead, async (request) => {
-        const {canSeeArtefact} = await import('../../services/projects.js');
-        const forms = await listForms();
-        const result = await Promise.all(forms.map(async form => {
-            let submissionCount = 0;
-            try {
-                // listEntries returns { entries, total, page, limit } — total is the
-                // unpaginated count which is what we want for the badge here.
-                const r = await listEntries(form.slug, { limit: 0 });
-                submissionCount = r.total ?? (r.entries || []).length;
-            } catch {
-                // collection may not exist yet
-            }
-            // listForms returns metadata only; readForm returns full record with meta
-            let full = null;
-            try { full = await readForm(form.slug); } catch { /* skip */ }
-            return { form: { ...form, submissionCount }, full };
-        }));
-        return result
-            .filter(({ full }) => canSeeArtefact(request.user, full))
-            .map(({ form }) => form);
-    });
-
-    // -----------------------------------------------------------------------
-    // POST /forms — create new form
-    // -----------------------------------------------------------------------
-    fastify.post('/forms', canCreate, async (request, reply) => {
-        const { title, slug: rawSlug } = request.body || {};
-        if (!title?.trim()) {
-            return reply.status(400).send({ error: 'Title is required.' });
-        }
-        const slug = rawSlug ? slugify(rawSlug) : slugify(title);
-        if (!slug) {
-            return reply.status(400).send({ error: 'Could not generate a valid slug.' });
-        }
-
-        // Check for existing form with same slug
-        try {
-            await readForm(slug);
-            return reply.status(409).send({ error: `A form with slug "${slug}" already exists.` });
-        } catch {
-            // Does not exist — good
-        }
-
-        const now  = new Date().toISOString();
-        const body = request.body || {};
-        const form = {
-            slug,
-            title: title.trim(),
-            description: body.description || '',
-            fields: Array.isArray(body.fields) ? body.fields : [],
-            settings: {
-                submitText: 'Submit',
-                successMessage: 'Thank you for your submission.',
-                layout: 'stacked',
-                honeypot: true,
-                rateLimitPerMinute: 3,
-                ...(body.settings || {})
-            },
-            actions: {
-                email:      { enabled: false, recipients: '', subjectPrefix: `[${title.trim()}]` },
-                webhook:    { enabled: false, url: '', method: 'POST' },
-                collection: {enabled: true, slug},
-                ...(body.actions || {})
-            },
-            createdAt: now,
-            updatedAt: now
-        };
-
-        await writeForm(slug, form);
-
-        // Auto-create a matching collection for this form (skip if one already exists)
-        try {
-            await createCollection({
-                slug,
-                title: title.trim(),
-                description: `Submissions from the ${title.trim()} form.`,
-                fields: [],
-                api: {
-                    create: { enabled: false, access: 'admin' },
-                    read:   { enabled: true,  access: 'admin' },
-                    update: { enabled: false, access: 'admin' },
-                    delete: { enabled: false, access: 'admin' }
-                }
-            });
-        } catch (err) {
-            fastify.log.warn(`[forms] Could not auto-create collection "${slug}": ${err.message}`);
-        }
-
-        const warnings = await detectFormCollectionMismatch(form);
-        return reply.status(201).send(warnings.length ? { ...form, warnings } : form);
-    });
-
-    // -----------------------------------------------------------------------
-    // GET /forms/:slug — get single form (admin, includes actions)
-    // -----------------------------------------------------------------------
-    fastify.get('/forms/:slug', canRead, async (request, reply) => {
-        let form;
-        try {
-            form = await readForm(request.params.slug);
-        } catch {
-            return reply.status(404).send({ error: 'Form not found.' });
-        }
-        const {canSeeArtefact} = await import('../../services/projects.js');
-        if (!canSeeArtefact(request.user, form)) {
-            return reply.status(403).send({ error: 'Access denied for this project' });
-        }
-        return form;
-    });
-
-    // -----------------------------------------------------------------------
-    // GET /forms/:slug/public — get form for public rendering (no actions)
-    // -----------------------------------------------------------------------
-    fastify.get('/forms/:slug/public', async (request, reply) => {
-        try {
-            const form = await readForm(request.params.slug);
-            const { actions: _actions, ...safe } = form;
-            return safe;
-        } catch {
-            return reply.status(404).send({ error: 'Form not found.' });
-        }
-    });
-
-    // -----------------------------------------------------------------------
-    // PUT /forms/:slug — update form definition
-    // -----------------------------------------------------------------------
-    fastify.put('/forms/:slug', canUpdate, async (request, reply) => {
-        const { slug } = request.params;
-        let existing;
-        try {
-            existing = await readForm(slug);
-        } catch {
-            return reply.status(404).send({ error: 'Form not found.' });
-        }
-
-        const body    = request.body || {};
-        const updated = {
-            ...existing,
-            ...body,
-            slug,
-            createdAt: existing.createdAt,
-            updatedAt: new Date().toISOString()
-        };
-        await writeForm(slug, updated);
-
-        // Non-blocking warnings: check the form's fields against its target
-        // collection's required fields. Missing-required-on-form would cause
-        // every submission to fail server-side validation — admin gets a
-        // heads-up here so they can fix it BEFORE users hit silent rejection.
-        const warnings = await detectFormCollectionMismatch(updated);
-        return warnings.length ? { ...updated, warnings } : updated;
-    });
-
-    // -----------------------------------------------------------------------
-    // DELETE /forms/:slug — delete form
-    // -----------------------------------------------------------------------
-    fastify.delete('/forms/:slug', canDelete, async (request, reply) => {
-        const { slug } = request.params;
-        try {
-            await deleteForm(slug);
-        } catch {
-            return reply.status(404).send({ error: 'Form not found.' });
-        }
-        return { ok: true };
-    });
-
-    // -----------------------------------------------------------------------
-    // GET /forms/:slug/submissions — list submissions from collection
-    // -----------------------------------------------------------------------
-    fastify.get('/forms/:slug/submissions', canRead, async (request, reply) => {
-        const { slug } = request.params;
-        try {
-            // listEntries returns { entries, total, page, limit } — unwrap to
-            // the array. Newest-first is the conventional display order for
-            // submission lists.
-            const { entries } = await listEntries(slug, { limit: 0 });
-            return [...entries].reverse();
-        } catch {
-            return reply.status(404).send({ error: 'Collection not found for this form.' });
-        }
-    });
-
-    // -----------------------------------------------------------------------
-    // GET /forms/:slug/submissions/export — CSV download from collection
-    // -----------------------------------------------------------------------
-    fastify.get('/forms/:slug/submissions/export', canRead, async (request, reply) => {
-        const { slug } = request.params;
-        let form;
-        try {
-            form = await readForm(slug);
-        } catch {
-            return reply.status(404).send({ error: 'Form not found.' });
-        }
-        let entries = [];
-        try {
-            const r = await listEntries(slug, { limit: 0 });
-            entries = r.entries || [];
-        } catch {
-            // empty collection
-        }
-        const csv = submissionsToCSV(form, entries);
-        reply.header('Content-Type', 'text/csv');
-        reply.header('Content-Disposition', `attachment; filename="${slug}-submissions.csv"`);
-        return reply.send(csv);
-    });
-
-    // -----------------------------------------------------------------------
-    // GET /forms/:slug/submissions/export/json — JSON export from collection
-    // -----------------------------------------------------------------------
-    fastify.get('/forms/:slug/submissions/export/json', canRead, async (request, reply) => {
-        const { slug } = request.params;
-        let form;
-        try {
-            form = await readForm(slug);
-        } catch {
-            return reply.status(404).send({ error: 'Form not found.' });
-        }
-        let entries = [];
-        try {
-            const r = await listEntries(slug, { limit: 0 });
-            entries = r.entries || [];
-        } catch {
-            // empty
-        }
-        reply.header('Content-Type', 'application/json');
-        reply.header('Content-Disposition', `attachment; filename="${slug}-submissions.json"`);
-        return reply.send(JSON.stringify(entries, null, 2));
-    });
-
-    // -----------------------------------------------------------------------
-    // DELETE /forms/:slug/submissions — clear all submissions
-    // -----------------------------------------------------------------------
-    fastify.delete('/forms/:slug/submissions', canDelete, async (request, reply) => {
-        const { slug } = request.params;
-        try {
-            await clearEntries(slug);
-        } catch {
-            return reply.status(404).send({ error: 'Collection not found for this form.' });
-        }
-        return { ok: true };
-    });
-
-    // -----------------------------------------------------------------------
-    // DELETE /forms/:slug/submissions/:id — delete one submission
-    // -----------------------------------------------------------------------
-    fastify.delete('/forms/:slug/submissions/:id', canDelete, async (request, reply) => {
-        const { slug, id } = request.params;
-        try {
-            await deleteEntry(slug, id);
-        } catch {
-            return reply.status(404).send({ error: 'Submission not found.' });
-        }
-        return { ok: true };
-    });
-
-    /*
-     * POST /forms/submit/:slug — public form submission.
-     *
-     * Authentication is OPTIONAL: when a valid JWT is present the submitter
-     * is captured as the entry's `createdBy` and passed into any triggered
-     * action's template context (as `{{user.id}}`, `{{user.email}}`, etc.).
-     * Anonymous submissions still work — `createdBy` is null and actions
-     * receive an empty user. This is what makes the apply/bookmark patterns
-     * work without forcing every form to be auth-only:
-     *
-     *   - Anonymous contact form → submitted by guest, user=null
-     *   - "Apply for job" form    → submitted by candidate, action's
-     *     createInCollection step stamps the application with their id
-     */
-    fastify.post('/forms/submit/:slug', async (request, reply) => {
-        const { slug } = request.params;
-        let form;
-        try {
-            form = await readForm(slug);
-        } catch {
-            return reply.status(404).send({ error: 'Form not found.' });
-        }
-
-        // Multipart parsing — when the request is multipart (file uploads),
-        // we walk parts ourselves: text fields go into `body`, file parts are
-        // validated against the form's field config and saved to /content/media,
-        // then their { url, name, size, mime } reference object lands in `body`
-        // under the field name. Downstream code sees a uniform JSON-shaped body.
-        let body = request.body || {};
-        if (request.isMultipart && request.isMultipart()) {
-            try {
-                body = await parseMultipartForm(request, form);
-            } catch (err) {
-                return reply.status(400).send({ error: err.message });
-            }
-        }
-        const settings = form.settings || {};
-
-        // Best-effort auth — never reject, just enrich.
-        let submittingUser = null;
-        try {
-            const decoded = await request.jwtVerify();
-            if (decoded.type === 'access') {
-                submittingUser = {
-                    id:    decoded.id,
-                    name:  decoded.name,
-                    email: decoded.email,
-                    role:  decoded.role
-                };
-            }
-        } catch { /* anonymous submission */ }
-
-        // Honeypot check — silently accept if filled (bot detected)
-        if (settings.honeypot && body._hp) {
-            return { ok: true, message: settings.successMessage, redirect: settings.successRedirect || null };
-        }
-
-        // Timing check — silently accept if submitted too fast (< 2 s, likely a bot)
-        if (settings.honeypot && body._t) {
-            const elapsed = Date.now() - Number(body._t);
-            if (!Number.isNaN(elapsed) && elapsed < 2000) {
-                return {ok: true, message: settings.successMessage, redirect: settings.successRedirect || null};
-            }
-        }
-
-        // Build form values for engine evaluation
-        const formValues = {};
-        for (const field of form.fields || []) {
-            if (field.type === 'page-break' || field.type === 'spacer') continue;
-            const val = body[field.name];
-            formValues[field.name] = val !== undefined ? (typeof val === 'string' ? val.trim() : val) : '';
-        }
-
-        // Evaluate conditional logic
-        const missingFields    = [];
-        const validationErrors = [];
-        const visibleFieldNames = new Set();
-
-        for (const field of form.fields || []) {
-            if (field.type === 'page-break' || field.type === 'spacer') continue;
-            const vis = FormLogicEngine.evaluateFieldVisibility(field, formValues);
-            if (vis === 'hidden') continue;
-            visibleFieldNames.add(field.name);
-
-            const value   = formValues[field.name];
-            const isEmpty = !value?.toString().trim();
-            const required = FormLogicEngine.evaluateFieldRequirement(field, formValues);
-            if (required && isEmpty) {
-                missingFields.push(field.label || field.name);
-            }
-            if (!isEmpty) {
-                const errors = FormLogicEngine.validateField(field, value, formValues);
-                if (errors.length) validationErrors.push(errors[0].message);
-            }
-        }
-
-        if (missingFields.length || validationErrors.length) {
-            const parts = [];
-            if (missingFields.length) parts.push(`Required fields missing: ${missingFields.join(', ')}`);
-            if (validationErrors.length) parts.push(validationErrors.join('; '));
-            return reply.status(400).send({ error: `${parts.join('. ')}.` });
-        }
-
-        // Rate limit by IP
-        const ip    = request.ip || request.socket?.remoteAddress || 'unknown';
-        const limit = settings.rateLimitPerMinute || 3;
-        if (isRateLimited(slug, ip, limit)) {
-            return reply.status(429).send({ error: 'Too many submissions. Please try again later.' });
-        }
-
-        // Build submission data — only include visible fields
-        const data = {};
-        for (const field of form.fields || []) {
-            if (field.type === 'page-break' || field.type === 'spacer') continue;
-            if (!visibleFieldNames.has(field.name)) continue;
-            const val = body[field.name];
-            if (val !== undefined) {
-                data[field.name] = typeof val === 'string' ? val.trim() : val;
-            }
-        }
-
-        // Store in collection (sole submission store).
-        //
-        // CRITICAL: collection write failure is the difference between "your
-        // submission was saved" and "your submission disappeared into thin air".
-        // We MUST surface the error to the user rather than logging a warning
-        // and returning success — anything else is a silent-data-loss bug.
-        // (Email / webhook / action failures downstream are still treated as
-        // non-fatal — they fire AFTER the entry is persisted, so even a partial
-        // delivery has the original submission safely stored.)
-        const collectionAction = form.actions?.collection;
-        const targetSlug = (collectionAction?.enabled && collectionAction.slug) ? collectionAction.slug : slug;
-        let entry = null;
-        try {
-            const col = await getCollection(targetSlug);
-            if (col) {
-                entry = await createEntry(targetSlug, data, {
-                    source:    `form:${slug}`,
-                    createdBy: submittingUser?.id || null
-                });
-            } else {
-                // Target collection doesn't exist — admin misconfiguration.
-                // Better to fail loudly than silently lose submissions.
-                fastify.log.warn(`[forms] Submission for "${slug}" had no target collection "${targetSlug}"`);
-                return reply.status(500).send({
-                    error: `Submission not saved — target collection "${targetSlug}" does not exist. Please contact the site administrator.`
-                });
-            }
-        } catch (err) {
-            fastify.log.warn(`[forms] Collection write failed for "${slug}" → "${targetSlug}": ${err.message}`);
-            // Distinguish validation errors (user-actionable) from other
-            // failures (admin needs to look) so the message helps the right
-            // person. Validation errors typically start with "Validation failed:".
-            const msg = err.message.startsWith('Validation failed')
-                ? err.message.replace('Validation failed: ', '')
-                : `Submission could not be saved: ${err.message}`;
-            return reply.status(400).send({ error: msg });
-        }
-
-        // Email action
-        const emailAction = form.actions?.email;
-        if (emailAction?.enabled && emailAction.recipients) {
-            try {
-                const smtp      = getConfig('site').smtp || {};
-                const transport = await createTransport(smtp);
-                await sendFormEmail(transport, {
-                    from:      smtp.fromAddress,
-                    fromName:  smtp.fromName,
-                    to:        emailAction.recipients,
-                    subject:   `${emailAction.subjectPrefix || `[${form.title}]`} New submission`,
-                    formTitle: form.title,
-                    fields:    form.fields,
-                    data
-                });
-            } catch (err) {
-                fastify.log.warn(`[forms] Email send failed for "${slug}": ${err.message}`);
-            }
-        }
-
-        // Webhook action
-        const webhookAction = form.actions?.webhook;
-        if (webhookAction?.enabled && webhookAction.url) {
-            try {
-                await fetch(webhookAction.url, {
-                    method:  webhookAction.method || 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body:    JSON.stringify({ form: slug, data })
-                });
-            } catch (err) {
-                fastify.log.warn(`[forms] Webhook failed for "${slug}": ${err.message}`);
-            }
-        }
-
-        // CMS Action trigger — forwards the authenticated submitter so
-        // action steps can interpolate {{user.id}}, {{user.email}}, etc.
-        // (Anonymous submissions still trigger the action with user={}.)
-        const actionSlug = form.settings?.actionSlug;
-        if (actionSlug && entry) {
-            try {
-                await executeAction(actionSlug, entry.id, { user: submittingUser });
-            } catch (err) {
-                fastify.log.warn(`[forms] Action "${actionSlug}" failed for form "${slug}": ${err.message}`);
-            }
-        }
-
-        hooks.emit('form:submitted', {slug, entryId: entry?.id || null, data, formTitle: form.title});
-
-        // Template interpolation for successRedirect
-        let redirect = settings.successRedirect || null;
-        if (redirect && entry?.id) {
-            redirect = redirect.replace(/\{\{entryId\}\}/g, entry.id);
-        }
-
-        return {
-            ok:       true,
-            entryId:  entry?.id || null,
-            message:  settings.successMessage  || 'Thank you for your submission.',
-            redirect: redirect
-        };
-    });
-
-    // -----------------------------------------------------------------------
-    // POST /forms/test-email — send a test email
-    // -----------------------------------------------------------------------
-    fastify.post('/forms/test-email', { preHandler: [authenticate, requireAdmin] }, async (request, reply) => {
-        const smtp = getConfig('site').smtp || {};
-        const to   = (request.body?.to) || smtp.fromAddress || 'test@ethereal.email';
-        try {
-            const transport = await createTransport(smtp);
-            await sendFormEmail(transport, {
-                from:      smtp.fromAddress,
-                fromName:  smtp.fromName,
-                to,
-                subject:   '[Forms] Test Email',
-                formTitle: 'Test Form',
-                fields:    [
-                    { name: 'name',    label: 'Name' },
-                    { name: 'message', label: 'Message' }
-                ],
-                data: {
-                    name:    'Test Sender',
-                    message: 'This is a test email from your Domma CMS. If you received this, your SMTP settings are working correctly.'
-                }
-            });
-            return { ok: true, message: `Test email sent to ${to}` };
-        } catch (err) {
-            return reply.status(500).send({ error: `Failed to send test email: ${err.message}` });
-        }
-    });
-}
+/**
+ * Core Forms API Routes
+ * REST endpoints for form CRUD, public rendering, and submission handling.
+ * Submissions are stored exclusively in Collections (no dual-storage).
+ *
+ * Endpoints (prefix: /api):
+ *   GET    /forms                          — admin: list all forms
+ *   POST   /forms                          — admin: create new form
+ *   GET    /forms/:slug                    — admin: get form definition
+ *   GET    /forms/:slug/public             — public: get form (no actions block)
+ *   PUT    /forms/:slug                    — admin: update form definition
+ *   DELETE /forms/:slug                    — admin: delete form
+ *   GET    /forms/:slug/submissions        — admin: list submissions from collection
+ *   GET    /forms/:slug/submissions/export — admin: CSV export from collection
+ *   DELETE /forms/:slug/submissions        — admin: clear all submissions
+ *   DELETE /forms/:slug/submissions/:id    — admin: delete one submission
+ *   POST   /forms/submit/:slug             — public: accept submission
+ *   POST   /forms/test-email               — admin: send test email
+ */
+import {createRequire} from 'module';
+import {fileURLToPath} from 'url';
+import path from 'path';
+import {deleteForm, ensureCollectionForForm, ensureFormsDir, listForms, readForm, slugify, writeForm} from '../../services/forms.js';
+import {executeAction} from '../../services/actions.js';
+import {createTransport, sendFormEmail} from '../../services/email.js';
+import {
+    clearEntries,
+    createCollection,
+    createEntry,
+    deleteEntry,
+    getCollection,
+    listEntries
+} from '../../services/collections.js';
+import {getConfig} from '../../config.js';
+import {authenticate, requireAdmin, requirePermission} from '../../middleware/auth.js';
+import {hooks} from '../../services/hooks.js';
+import {saveMedia} from '../../services/content.js';
+import {v4 as uuidv4} from 'uuid';
+
+/**
+ * Detect form↔collection mismatches at save time so admins know BEFORE
+ * users hit silent rejection. Returns an array of human-readable warning
+ * strings — empty when the form lines up cleanly with its target collection.
+ *
+ * Checks performed:
+ *   - Target collection exists (otherwise every submission goes nowhere)
+ *   - Every required collection field has a matching form field
+ *   - Every form field references a known collection field (typos)
+ *
+ * @param {object} form - The just-saved form definition
+ * @returns {Promise<string[]>}
+ */
+async function detectFormCollectionMismatch(form) {
+    const warnings = [];
+    const colAction = form?.actions?.collection;
+    const targetSlug = (colAction?.enabled && colAction.slug) ? colAction.slug : form?.slug;
+    if (!targetSlug) return warnings;
+
+    let collection;
+    try {
+        collection = await getCollection(targetSlug);
+    } catch {
+        return warnings;
+    }
+    if (!collection) {
+        warnings.push(`Target collection "${targetSlug}" does not exist — submissions will fail. Either create the collection or change the form's target.`);
+        return warnings;
+    }
+
+    const formFieldNames = new Set((form.fields || []).map(f => f.name).filter(Boolean));
+    const colFieldNames  = new Set((collection.fields || []).map(f => f.name));
+
+    // Missing-required: collection requires X but form doesn't collect X
+    const missingRequired = (collection.fields || [])
+        .filter(f => f.required)
+        .filter(f => !formFieldNames.has(f.name))
+        .map(f => f.label || f.name);
+    if (missingRequired.length) {
+        warnings.push(`The "${targetSlug}" collection requires fields the form does not collect: ${missingRequired.join(', ')}. Submissions will be rejected with "X is required". Either mark these fields as not required on the collection, add them to the form, or set them via an action's createInCollection step.`);
+    }
+
+    // Unknown fields: form sends X but collection has no such field (typo / drift)
+    const unknown = [...formFieldNames].filter(n => !colFieldNames.has(n));
+    if (unknown.length) {
+        warnings.push(`The form has fields the "${targetSlug}" collection doesn't define: ${unknown.join(', ')}. These values will be stored but won't be validated, indexed, or displayed in [collection] blocks unless you add matching fields to the collection.`);
+    }
+
+    return warnings;
+}
+
+/**
+ * Sanitise a user-supplied filename:
+ *   - strip path separators and traversal markers
+ *   - keep only `[a-z0-9._-]`, lower-case
+ *   - prepend an 8-char uuid prefix so concurrent uploads of the same name
+ *     don't overwrite each other
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function safeFilename(raw) {
+    const cleaned = String(raw || 'upload')
+        .toLowerCase()
+        .replace(/[^\w.-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '')
+        .slice(0, 200) || 'upload';
+    const prefix = uuidv4().slice(0, 8);
+    return `${prefix}-${cleaned}`;
+}
+
+/**
+ * Check a multipart file part against a form's `type: file` field config.
+ *
+ * @param {object} fieldCfg    - The form-field definition
+ * @param {object} part        - Multipart part (mimetype, filename)
+ * @param {number} size        - Buffer length in bytes
+ * @returns {string|null}      - Error message, or null if OK
+ */
+function validateUpload(fieldCfg, part, size) {
+    const cfg = fieldCfg?.file || {};
+    const max = Number(cfg.maxSize) || 5 * 1024 * 1024;     // 5 MB default
+    if (size > max) {
+        return `"${fieldCfg.label || fieldCfg.name}" file is too large (max ${Math.round(max / 1024)} KB).`;
+    }
+    const accept = String(cfg.accept || '').trim();
+    if (accept) {
+        // Comma-separated list of mime types, allowing wildcards like image/*
+        const patterns = accept.split(',').map(s => s.trim()).filter(Boolean);
+        const mime     = part.mimetype || '';
+        const ok = patterns.some(p => {
+            if (p.endsWith('/*')) return mime.startsWith(p.slice(0, -1));
+            return p === mime;
+        });
+        if (!ok) {
+            return `"${fieldCfg.label || fieldCfg.name}" file type "${mime}" not allowed (expected: ${accept}).`;
+        }
+    }
+    return null;
+}
+
+/**
+ * Drain a multipart request into a JSON-shaped body. Text parts become string
+ * values; file parts are validated against the matching form field, saved to
+ * `content/media/`, and replaced by a `{ url, name, size, mime }` reference.
+ *
+ * Throws on validation failure (caller handles HTTP 400). Files are streamed
+ * into memory up to fastify-multipart's configured limit — fine for the
+ * resume-pdf / portrait-photo scale; large uploads should still use the admin
+ * media flow.
+ *
+ * @param {import('fastify').FastifyRequest} request
+ * @param {object} form
+ * @returns {Promise<object>}
+ */
+async function parseMultipartForm(request, form) {
+    const out = {};
+    const fileFields = new Map(
+        (form.fields || []).filter(f => f.type === 'file').map(f => [f.name, f])
+    );
+
+    for await (const part of request.parts()) {
+        if (part.type === 'file') {
+            const fieldCfg = fileFields.get(part.fieldname);
+            if (!fieldCfg) {
+                // Unknown file field — drain and skip rather than 400, so a
+                // form that gains a file input later doesn't reject older
+                // submissions in-flight from a stale page.
+                for await (const _ of part.file) { /* drain */ }
+                continue;
+            }
+            const chunks = [];
+            for await (const chunk of part.file) chunks.push(chunk);
+            const buffer = Buffer.concat(chunks);
+            const err    = validateUpload(fieldCfg, part, buffer.length);
+            if (err) throw new Error(err);
+            if (buffer.length === 0) continue;     // empty file input — skip
+            const saved = await saveMedia(safeFilename(part.filename), buffer);
+            out[part.fieldname] = {
+                url:  saved.url,
+                name: part.filename,
+                size: buffer.length,
+                mime: part.mimetype
+            };
+        } else {
+            // Text field — last value wins on duplicates (browser-standard).
+            out[part.fieldname] = part.value;
+        }
+    }
+    return out;
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+
+// Load shared logic engine (UMD/CJS) from core public assets
+const _require = createRequire(import.meta.url);
+const FormLogicEngine = _require('../../../public/js/form-logic-engine.js');
+
+// Per-slug rate limit store: slug → Map<ip, timestamp[]>
+const rateLimitMap = new Map();
+
+function isRateLimited(slug, ip, limitPerMinute) {
+    const now      = Date.now();
+    const windowMs = 60 * 1000;
+    if (!rateLimitMap.has(slug)) rateLimitMap.set(slug, new Map());
+    const slugMap    = rateLimitMap.get(slug);
+    const timestamps = (slugMap.get(ip) || []).filter(t => now - t < windowMs);
+    if (timestamps.length >= limitPerMinute) return true;
+    timestamps.push(now);
+    slugMap.set(ip, timestamps);
+    return false;
+}
+
+function submissionsToCSV(form, entries) {
+    const fields  = (form.fields || []).filter(f => f.type !== 'page-break' && f.type !== 'spacer');
+    const headers = [...fields.map(f => `"${f.label || f.name}"`), '"Date"'];
+    const rows    = entries.map(e => {
+        const cols = fields.map(f => {
+            const raw = e.data?.[f.name] ?? '';
+            const str = Array.isArray(raw) ? raw.join('; ') : String(raw);
+            const val = str.replace(/"/g, '""');
+            return `"${val}"`;
+        });
+        cols.push(`"${e.meta?.createdAt || ''}"`);
+        return cols.join(',');
+    });
+    return [headers.join(','), ...rows].join('\n');
+}
+
+export async function formsRoutes(fastify) {
+    await ensureFormsDir();
+
+    const canRead   = { preHandler: [authenticate, requirePermission('collections', 'read')]   };
+    const canCreate = { preHandler: [authenticate, requirePermission('collections', 'create')] };
+    const canUpdate = { preHandler: [authenticate, requirePermission('collections', 'update')] };
+    const canDelete = { preHandler: [authenticate, requirePermission('collections', 'delete')] };
+
+    // -----------------------------------------------------------------------
+    // GET /forms — list all form definitions with submission counts
+    // -----------------------------------------------------------------------
+    fastify.get('/forms', canRead, async (request) => {
+        const {canSeeArtefact} = await import('../../services/projects.js');
+        const forms = await listForms();
+        const result = await Promise.all(forms.map(async form => {
+            let submissionCount = 0;
+            try {
+                // listEntries returns { entries, total, page, limit } — total is the
+                // unpaginated count which is what we want for the badge here.
+                const r = await listEntries(form.slug, { limit: 0 });
+                submissionCount = r.total ?? (r.entries || []).length;
+            } catch {
+                // collection may not exist yet
+            }
+            // listForms returns metadata only; readForm returns full record with meta
+            let full = null;
+            try { full = await readForm(form.slug); } catch { /* skip */ }
+            return { form: { ...form, submissionCount }, full };
+        }));
+        return result
+            .filter(({ full }) => canSeeArtefact(request.user, full))
+            .map(({ form }) => form);
+    });
+
+    // -----------------------------------------------------------------------
+    // POST /forms — create new form
+    // -----------------------------------------------------------------------
+    fastify.post('/forms', canCreate, async (request, reply) => {
+        const { title, slug: rawSlug } = request.body || {};
+        if (!title?.trim()) {
+            return reply.status(400).send({ error: 'Title is required.' });
+        }
+        const slug = rawSlug ? slugify(rawSlug) : slugify(title);
+        if (!slug) {
+            return reply.status(400).send({ error: 'Could not generate a valid slug.' });
+        }
+
+        // Check for existing form with same slug
+        try {
+            await readForm(slug);
+            return reply.status(409).send({ error: `A form with slug "${slug}" already exists.` });
+        } catch {
+            // Does not exist — good
+        }
+
+        const now  = new Date().toISOString();
+        const body = request.body || {};
+        const form = {
+            slug,
+            title: title.trim(),
+            description: body.description || '',
+            fields: Array.isArray(body.fields) ? body.fields : [],
+            settings: {
+                submitText: 'Submit',
+                successMessage: 'Thank you for your submission.',
+                layout: 'stacked',
+                honeypot: true,
+                rateLimitPerMinute: 3,
+                ...(body.settings || {})
+            },
+            actions: {
+                email:      { enabled: false, recipients: '', subjectPrefix: `[${title.trim()}]` },
+                webhook:    { enabled: false, url: '', method: 'POST' },
+                collection: {enabled: true, slug},
+                ...(body.actions || {})
+            },
+            createdAt: now,
+            updatedAt: now
+        };
+
+        await writeForm(slug, form);
+
+        // Auto-create a matching collection for this form (skip if one already exists)
+        try {
+            await createCollection({
+                slug,
+                title: title.trim(),
+                description: `Submissions from the ${title.trim()} form.`,
+                fields: [],
+                api: {
+                    create: { enabled: false, access: 'admin' },
+                    read:   { enabled: true,  access: 'admin' },
+                    update: { enabled: false, access: 'admin' },
+                    delete: { enabled: false, access: 'admin' }
+                }
+            });
+        } catch (err) {
+            fastify.log.warn(`[forms] Could not auto-create collection "${slug}": ${err.message}`);
+        }
+
+        const warnings = await detectFormCollectionMismatch(form);
+        return reply.status(201).send(warnings.length ? { ...form, warnings } : form);
+    });
+
+    // -----------------------------------------------------------------------
+    // GET /forms/:slug — get single form (admin, includes actions)
+    // -----------------------------------------------------------------------
+    fastify.get('/forms/:slug', canRead, async (request, reply) => {
+        let form;
+        try {
+            form = await readForm(request.params.slug);
+        } catch {
+            return reply.status(404).send({ error: 'Form not found.' });
+        }
+        const {canSeeArtefact} = await import('../../services/projects.js');
+        if (!canSeeArtefact(request.user, form)) {
+            return reply.status(403).send({ error: 'Access denied for this project' });
+        }
+        return form;
+    });
+
+    // -----------------------------------------------------------------------
+    // GET /forms/:slug/public — get form for public rendering (no actions)
+    // -----------------------------------------------------------------------
+    fastify.get('/forms/:slug/public', async (request, reply) => {
+        try {
+            const form = await readForm(request.params.slug);
+            const { actions: _actions, ...safe } = form;
+            return safe;
+        } catch {
+            return reply.status(404).send({ error: 'Form not found.' });
+        }
+    });
+
+    // -----------------------------------------------------------------------
+    // PUT /forms/:slug — update form definition
+    // -----------------------------------------------------------------------
+    fastify.put('/forms/:slug', canUpdate, async (request, reply) => {
+        const { slug } = request.params;
+        let existing;
+        try {
+            existing = await readForm(slug);
+        } catch {
+            return reply.status(404).send({ error: 'Form not found.' });
+        }
+
+        const body    = request.body || {};
+        const updated = {
+            ...existing,
+            ...body,
+            slug,
+            createdAt: existing.createdAt,
+            updatedAt: new Date().toISOString()
+        };
+        await writeForm(slug, updated);
+
+        // Non-blocking warnings: check the form's fields against its target
+        // collection's required fields. Missing-required-on-form would cause
+        // every submission to fail server-side validation — admin gets a
+        // heads-up here so they can fix it BEFORE users hit silent rejection.
+        const warnings = await detectFormCollectionMismatch(updated);
+        return warnings.length ? { ...updated, warnings } : updated;
+    });
+
+    // -----------------------------------------------------------------------
+    // DELETE /forms/:slug — delete form
+    // -----------------------------------------------------------------------
+    fastify.delete('/forms/:slug', canDelete, async (request, reply) => {
+        const { slug } = request.params;
+        try {
+            await deleteForm(slug);
+        } catch {
+            return reply.status(404).send({ error: 'Form not found.' });
+        }
+        return { ok: true };
+    });
+
+    // -----------------------------------------------------------------------
+    // GET /forms/:slug/submissions — list submissions from collection
+    // -----------------------------------------------------------------------
+    fastify.get('/forms/:slug/submissions', canRead, async (request, reply) => {
+        const { slug } = request.params;
+        let form;
+        try {
+            form = await readForm(slug);
+        } catch {
+            return reply.status(404).send({ error: 'Form not found.' });
+        }
+        const collectionAction = form.actions?.collection;
+        const targetSlug = (collectionAction?.enabled && collectionAction.slug) ? collectionAction.slug : slug;
+
+        // A form whose backing collection has not been provisioned yet simply
+        // has no submissions — return an empty list rather than a 404 so the
+        // admin view loads cleanly instead of erroring.
+        const collection = await getCollection(targetSlug);
+        if (!collection) return [];
+
+        // listEntries returns { entries, total, page, limit } — unwrap to the
+        // array. Newest-first is the conventional display order.
+        const { entries } = await listEntries(targetSlug, { limit: 0 });
+        return [...entries].reverse();
+    });
+
+    // -----------------------------------------------------------------------
+    // GET /forms/:slug/submissions/export — CSV download from collection
+    // -----------------------------------------------------------------------
+    fastify.get('/forms/:slug/submissions/export', canRead, async (request, reply) => {
+        const { slug } = request.params;
+        let form;
+        try {
+            form = await readForm(slug);
+        } catch {
+            return reply.status(404).send({ error: 'Form not found.' });
+        }
+        let entries = [];
+        try {
+            const r = await listEntries(slug, { limit: 0 });
+            entries = r.entries || [];
+        } catch {
+            // empty collection
+        }
+        const csv = submissionsToCSV(form, entries);
+        reply.header('Content-Type', 'text/csv');
+        reply.header('Content-Disposition', `attachment; filename="${slug}-submissions.csv"`);
+        return reply.send(csv);
+    });
+
+    // -----------------------------------------------------------------------
+    // GET /forms/:slug/submissions/export/json — JSON export from collection
+    // -----------------------------------------------------------------------
+    fastify.get('/forms/:slug/submissions/export/json', canRead, async (request, reply) => {
+        const { slug } = request.params;
+        let form;
+        try {
+            form = await readForm(slug);
+        } catch {
+            return reply.status(404).send({ error: 'Form not found.' });
+        }
+        let entries = [];
+        try {
+            const r = await listEntries(slug, { limit: 0 });
+            entries = r.entries || [];
+        } catch {
+            // empty
+        }
+        reply.header('Content-Type', 'application/json');
+        reply.header('Content-Disposition', `attachment; filename="${slug}-submissions.json"`);
+        return reply.send(JSON.stringify(entries, null, 2));
+    });
+
+    // -----------------------------------------------------------------------
+    // DELETE /forms/:slug/submissions — clear all submissions
+    // -----------------------------------------------------------------------
+    fastify.delete('/forms/:slug/submissions', canDelete, async (request, reply) => {
+        const { slug } = request.params;
+        try {
+            await clearEntries(slug);
+        } catch {
+            return reply.status(404).send({ error: 'Collection not found for this form.' });
+        }
+        return { ok: true };
+    });
+
+    // -----------------------------------------------------------------------
+    // DELETE /forms/:slug/submissions/:id — delete one submission
+    // -----------------------------------------------------------------------
+    fastify.delete('/forms/:slug/submissions/:id', canDelete, async (request, reply) => {
+        const { slug, id } = request.params;
+        try {
+            await deleteEntry(slug, id);
+        } catch {
+            return reply.status(404).send({ error: 'Submission not found.' });
+        }
+        return { ok: true };
+    });
+
+    /*
+     * POST /forms/submit/:slug — public form submission.
+     *
+     * Authentication is OPTIONAL: when a valid JWT is present the submitter
+     * is captured as the entry's `createdBy` and passed into any triggered
+     * action's template context (as `{{user.id}}`, `{{user.email}}`, etc.).
+     * Anonymous submissions still work — `createdBy` is null and actions
+     * receive an empty user. This is what makes the apply/bookmark patterns
+     * work without forcing every form to be auth-only:
+     *
+     *   - Anonymous contact form → submitted by guest, user=null
+     *   - "Apply for job" form    → submitted by candidate, action's
+     *     createInCollection step stamps the application with their id
+     */
+    fastify.post('/forms/submit/:slug', async (request, reply) => {
+        const { slug } = request.params;
+        let form;
+        try {
+            form = await readForm(slug);
+        } catch {
+            return reply.status(404).send({ error: 'Form not found.' });
+        }
+
+        // Multipart parsing — when the request is multipart (file uploads),
+        // we walk parts ourselves: text fields go into `body`, file parts are
+        // validated against the form's field config and saved to /content/media,
+        // then their { url, name, size, mime } reference object lands in `body`
+        // under the field name. Downstream code sees a uniform JSON-shaped body.
+        let body = request.body || {};
+        if (request.isMultipart && request.isMultipart()) {
+            try {
+                body = await parseMultipartForm(request, form);
+            } catch (err) {
+                return reply.status(400).send({ error: err.message });
+            }
+        }
+        const settings = form.settings || {};
+
+        // Best-effort auth — never reject, just enrich.
+        let submittingUser = null;
+        try {
+            const decoded = await request.jwtVerify();
+            if (decoded.type === 'access') {
+                submittingUser = {
+                    id:    decoded.id,
+                    name:  decoded.name,
+                    email: decoded.email,
+                    role:  decoded.role
+                };
+            }
+        } catch { /* anonymous submission */ }
+
+        // Honeypot check — silently accept if filled (bot detected)
+        if (settings.honeypot && body._hp) {
+            return { ok: true, message: settings.successMessage, redirect: settings.successRedirect || null };
+        }
+
+        // Timing check — silently accept if submitted too fast (< 2 s, likely a bot)
+        if (settings.honeypot && body._t) {
+            const elapsed = Date.now() - Number(body._t);
+            if (!Number.isNaN(elapsed) && elapsed < 2000) {
+                return {ok: true, message: settings.successMessage, redirect: settings.successRedirect || null};
+            }
+        }
+
+        // Build form values for engine evaluation
+        const formValues = {};
+        for (const field of form.fields || []) {
+            if (field.type === 'page-break' || field.type === 'spacer') continue;
+            const val = body[field.name];
+            formValues[field.name] = val !== undefined ? (typeof val === 'string' ? val.trim() : val) : '';
+        }
+
+        // Evaluate conditional logic
+        const missingFields    = [];
+        const validationErrors = [];
+        const visibleFieldNames = new Set();
+
+        for (const field of form.fields || []) {
+            if (field.type === 'page-break' || field.type === 'spacer') continue;
+            const vis = FormLogicEngine.evaluateFieldVisibility(field, formValues);
+            if (vis === 'hidden') continue;
+            visibleFieldNames.add(field.name);
+
+            const value   = formValues[field.name];
+            const isEmpty = !value?.toString().trim();
+            const required = FormLogicEngine.evaluateFieldRequirement(field, formValues);
+            if (required && isEmpty) {
+                missingFields.push(field.label || field.name);
+            }
+            if (!isEmpty) {
+                const errors = FormLogicEngine.validateField(field, value, formValues);
+                if (errors.length) validationErrors.push(errors[0].message);
+            }
+        }
+
+        if (missingFields.length || validationErrors.length) {
+            const parts = [];
+            if (missingFields.length) parts.push(`Required fields missing: ${missingFields.join(', ')}`);
+            if (validationErrors.length) parts.push(validationErrors.join('; '));
+            return reply.status(400).send({ error: `${parts.join('. ')}.` });
+        }
+
+        // Rate limit by IP
+        const ip    = request.ip || request.socket?.remoteAddress || 'unknown';
+        const limit = settings.rateLimitPerMinute || 3;
+        if (isRateLimited(slug, ip, limit)) {
+            return reply.status(429).send({ error: 'Too many submissions. Please try again later.' });
+        }
+
+        // Build submission data — only include visible fields
+        const data = {};
+        for (const field of form.fields || []) {
+            if (field.type === 'page-break' || field.type === 'spacer') continue;
+            if (!visibleFieldNames.has(field.name)) continue;
+            const val = body[field.name];
+            if (val !== undefined) {
+                data[field.name] = typeof val === 'string' ? val.trim() : val;
+            }
+        }
+
+        // Store in collection (sole submission store).
+        //
+        // CRITICAL: collection write failure is the difference between "your
+        // submission was saved" and "your submission disappeared into thin air".
+        // We MUST surface the error to the user rather than logging a warning
+        // and returning success — anything else is a silent-data-loss bug.
+        // (Email / webhook / action failures downstream are still treated as
+        // non-fatal — they fire AFTER the entry is persisted, so even a partial
+        // delivery has the original submission safely stored.)
+        const collectionAction = form.actions?.collection;
+        const targetSlug = (collectionAction?.enabled && collectionAction.slug) ? collectionAction.slug : slug;
+        let entry = null;
+        try {
+            let col = await getCollection(targetSlug);
+            if (!col) {
+                // The backing collection was never created (a form pointing at a
+                // non-existent collection). Failing here would lose the visitor's
+                // submission outright, so self-heal by provisioning the collection
+                // from the form's own fields, then persist into it.
+                fastify.log.warn(`[forms] Auto-provisioning missing collection "${targetSlug}" for form "${slug}"`);
+                col = await ensureCollectionForForm(form);
+            }
+            if (col) {
+                entry = await createEntry(targetSlug, data, {
+                    source:    `form:${slug}`,
+                    createdBy: submittingUser?.id || null
+                });
+            } else {
+                // Could not resolve or provision a target — e.g. collection
+                // storage is explicitly disabled with no slug. Fail loudly
+                // rather than silently lose submissions.
+                fastify.log.warn(`[forms] Submission for "${slug}" had no target collection "${targetSlug}"`);
+                return reply.status(500).send({
+                    error: `Submission not saved — target collection "${targetSlug}" does not exist. Please contact the site administrator.`
+                });
+            }
+        } catch (err) {
+            fastify.log.warn(`[forms] Collection write failed for "${slug}" → "${targetSlug}": ${err.message}`);
+            // Distinguish validation errors (user-actionable) from other
+            // failures (admin needs to look) so the message helps the right
+            // person. Validation errors typically start with "Validation failed:".
+            const msg = err.message.startsWith('Validation failed')
+                ? err.message.replace('Validation failed: ', '')
+                : `Submission could not be saved: ${err.message}`;
+            return reply.status(400).send({ error: msg });
+        }
+
+        // Email action
+        const emailAction = form.actions?.email;
+        if (emailAction?.enabled && emailAction.recipients) {
+            try {
+                const smtp      = getConfig('site').smtp || {};
+                const transport = await createTransport(smtp);
+                await sendFormEmail(transport, {
+                    from:      smtp.fromAddress,
+                    fromName:  smtp.fromName,
+                    to:        emailAction.recipients,
+                    subject:   `${emailAction.subjectPrefix || `[${form.title}]`} New submission`,
+                    formTitle: form.title,
+                    fields:    form.fields,
+                    data
+                });
+            } catch (err) {
+                fastify.log.warn(`[forms] Email send failed for "${slug}": ${err.message}`);
+            }
+        }
+
+        // Webhook action
+        const webhookAction = form.actions?.webhook;
+        if (webhookAction?.enabled && webhookAction.url) {
+            try {
+                await fetch(webhookAction.url, {
+                    method:  webhookAction.method || 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body:    JSON.stringify({ form: slug, data })
+                });
+            } catch (err) {
+                fastify.log.warn(`[forms] Webhook failed for "${slug}": ${err.message}`);
+            }
+        }
+
+        // CMS Action trigger — forwards the authenticated submitter so
+        // action steps can interpolate {{user.id}}, {{user.email}}, etc.
+        // (Anonymous submissions still trigger the action with user={}.)
+        const actionSlug = form.settings?.actionSlug;
+        if (actionSlug && entry) {
+            try {
+                await executeAction(actionSlug, entry.id, { user: submittingUser });
+            } catch (err) {
+                fastify.log.warn(`[forms] Action "${actionSlug}" failed for form "${slug}": ${err.message}`);
+            }
+        }
+
+        hooks.emit('form:submitted', {slug, entryId: entry?.id || null, data, formTitle: form.title});
+
+        // Template interpolation for successRedirect
+        let redirect = settings.successRedirect || null;
+        if (redirect && entry?.id) {
+            redirect = redirect.replace(/\{\{entryId\}\}/g, entry.id);
+        }
+
+        return {
+            ok:       true,
+            entryId:  entry?.id || null,
+            message:  settings.successMessage  || 'Thank you for your submission.',
+            redirect: redirect
+        };
+    });
+
+    // -----------------------------------------------------------------------
+    // POST /forms/test-email — send a test email
+    // -----------------------------------------------------------------------
+    fastify.post('/forms/test-email', { preHandler: [authenticate, requireAdmin] }, async (request, reply) => {
+        const smtp = getConfig('site').smtp || {};
+        const to   = (request.body?.to) || smtp.fromAddress || 'test@ethereal.email';
+        try {
+            const transport = await createTransport(smtp);
+            await sendFormEmail(transport, {
+                from:      smtp.fromAddress,
+                fromName:  smtp.fromName,
+                to,
+                subject:   '[Forms] Test Email',
+                formTitle: 'Test Form',
+                fields:    [
+                    { name: 'name',    label: 'Name' },
+                    { name: 'message', label: 'Message' }
+                ],
+                data: {
+                    name:    'Test Sender',
+                    message: 'This is a test email from your Domma CMS. If you received this, your SMTP settings are working correctly.'
+                }
+            });
+            return { ok: true, message: `Test email sent to ${to}` };
+        } catch (err) {
+            return reply.status(500).send({ error: `Failed to send test email: ${err.message}` });
+        }
+    });
+}