@technomoron/mail-magic 1.0.33 → 1.0.35

package/CHANGES

@@ -1,8 +1,27 @@
+Version 1.0.35 (2026-02-17)
+
+- Enforce deterministic locale resolution for transactional template sends:
+  requested locale first, then root fallback (`locale=''`) only.
+- Enforce the same deterministic locale resolution for template-scoped asset uploads
+  (`POST /api/v1/assets`) for both `tx` and `form` template types.
+- Remove non-deterministic fallback to arbitrary locale records when requested/root
+  locales are missing.
+- Add regression tests covering deterministic locale fallback and missing-locale
+  behavior for both transactional sends and template asset upload resolution.
+
+Version 1.0.34 (2026-02-10)
+
+- Ensure inline form template assets (CID) are actually attached when delivering public form submissions.
+- Use safe, stable inline Content-IDs (no path separators) and keep stored `files[].cid` consistent with rendered HTML.
+- Expand tests to validate inline assets, linked assets, and uploaded attachments end-to-end.
+- Ensure record slugs and generated paths are domain-rooted only (no user segment).
+
 Version 1.0.33 (2026-02-09)
 
 - Route all env-derived config through `mailStore.vars` with explicit overrides for tests/examples.
 - Move shared helpers into `util/` modules (rate limiting, email parsing, path safety, uploads).
 - Switch template preprocessing to Unyuck’s asset collection while preserving existing URL and CID behavior.
+- Split form submission logic into focused util helpers and slim the API handler.
 
 Version 1.0.32 (2026-02-08)
 

package/dist/api/assets.js

@@ -22,11 +22,9 @@ export class AssetAPI extends ApiModule {
         }
         const templateType = templateTypeRaw.toLowerCase();
         const domainId = apireq.domain.domain_id;
-        const deflocale = this.server.storage.deflocale || '';
         if (templateType === 'tx') {
             const template = (await api_txmail.findOne({ where: { name: templateName, domain_id: domainId, locale } })) ||
-                (await api_txmail.findOne({ where: { name: templateName, domain_id: domainId, locale: deflocale } })) ||
-                (await api_txmail.findOne({ where: { name: templateName, domain_id: domainId } }));
+                (await api_txmail.findOne({ where: { name: templateName, domain_id: domainId, locale: '' } }));
             if (!template) {
                 throw new ApiError({
                     code: 404,
@@ -43,8 +41,7 @@ export class AssetAPI extends ApiModule {
         }
         if (templateType === 'form') {
             const form = (await api_form.findOne({ where: { idname: templateName, domain_id: domainId, locale } })) ||
-                (await api_form.findOne({ where: { idname: templateName, domain_id: domainId, locale: deflocale } })) ||
-                (await api_form.findOne({ where: { idname: templateName, domain_id: domainId } }));
+                (await api_form.findOne({ where: { idname: templateName, domain_id: domainId, locale: '' } }));
             if (!form) {
                 throw new ApiError({
                     code: 404,

package/dist/api/forms.js

@@ -1,4 +1,3 @@
-import path from 'path';
 import { ApiModule, ApiError } from '@technomoron/api-server-base';
 import { nanoid } from 'nanoid';
 import nunjucks from 'nunjucks';
@@ -6,209 +5,36 @@ import { UniqueConstraintError } from 'sequelize';
 import { api_domain } from '../models/domain.js';
 import { api_form } from '../models/form.js';
 import { api_recipient } from '../models/recipient.js';
-import { verifyCaptcha } from '../util/captcha.js';
-import { parseMailbox } from '../util/email.js';
+import { buildFormTemplateRecord, buildFormTemplatePaths, buildRecipientTo, buildReplyToValue, buildSubmissionContext, enforceAttachmentPolicy, enforceCaptchaPolicy, filterSubmissionFields, getPrimaryRecipientInfo, normalizeRecipientEmail, normalizeRecipientIdname, normalizeRecipientName, parseIdnameList, parseFormTemplatePayload, parseRecipientPayload, parsePublicSubmissionOrThrow, resolveFormKeyForTemplate, resolveFormKeyForRecipient, resolveRecipients, validateFormTemplatePayload } from '../util/forms.js';
 import { FixedWindowRateLimiter, enforceFormRateLimit } from '../util/ratelimit.js';
 import { buildAttachments, cleanupUploadedFiles } from '../util/uploads.js';
-import { buildRequestMeta, getBodyValue, normalizeBoolean, normalizeSlug } from '../util.js';
+import { buildRequestMeta, getBodyValue } from '../util.js';
 import { assert_domain_and_user } from './auth.js';
-import { extractReplyToFromSubmission } from './form-replyto.js';
-import { parseFormSubmissionInput } from './form-submission.js';
-function parsePublicSubmissionOrThrow(apireq) {
-    try {
-        return parseFormSubmissionInput(apireq.req.body);
-    }
-    catch {
-        // Treat malformed input as a bad request (Zod schema failures, non-object bodies, etc).
-        throw new ApiError({ code: 400, message: 'Invalid form submission payload' });
-    }
-}
-function enforceAttachmentPolicy(env, rawFiles) {
-    if (env.FORM_MAX_ATTACHMENTS === 0 && rawFiles.length > 0) {
-        throw new ApiError({ code: 413, message: 'This endpoint does not accept file attachments' });
-    }
-    for (const file of rawFiles) {
-        if (!file?.fieldname) {
-            continue;
-        }
-        if (!file.fieldname.startsWith('_mm_file')) {
-            throw new ApiError({
-                code: 400,
-                message: 'Invalid upload field name. Use _mm_file* for attachments.'
-            });
-        }
-    }
-    if (env.FORM_MAX_ATTACHMENTS > 0 && rawFiles.length > env.FORM_MAX_ATTACHMENTS) {
-        throw new ApiError({
-            code: 413,
-            message: `Too many attachments: ${rawFiles.length} > ${env.FORM_MAX_ATTACHMENTS}`
-        });
-    }
-}
-function filterSubmissionFields(rawFields, allowedFields) {
-    const allowed = Array.isArray(allowedFields) ? allowedFields : [];
-    if (!allowed.length) {
-        return rawFields;
-    }
-    const filtered = {};
-    // Always allow Reply-To derivation fields even when allowed_fields is configured.
-    const alwaysAllow = ['email', 'name', 'first_name', 'last_name'];
-    for (const key of alwaysAllow) {
-        if (Object.prototype.hasOwnProperty.call(rawFields, key)) {
-            filtered[key] = rawFields[key];
-        }
-    }
-    for (const key of allowed) {
-        const k = typeof key === 'string' ? key : String(key ?? '').trim();
-        if (!k) {
-            continue;
-        }
-        if (Object.prototype.hasOwnProperty.call(rawFields, k)) {
-            filtered[k] = rawFields[k];
-        }
-    }
-    return filtered;
-}
-async function enforceCaptchaPolicy(params) {
-    const captchaRequired = Boolean(params.vars.FORM_CAPTCHA_REQUIRED || params.form.captcha_required);
-    const captchaSecret = String(params.vars.FORM_CAPTCHA_SECRET ?? '').trim();
-    if (!captchaSecret) {
-        if (captchaRequired) {
-            throw new ApiError({ code: 500, message: 'Captcha is required but not configured on the server' });
-        }
-        return;
-    }
-    if (!params.captchaToken) {
-        if (captchaRequired) {
-            throw new ApiError({ code: 403, message: 'Captcha token required' });
-        }
-        return;
-    }
-    const provider = params.vars.FORM_CAPTCHA_PROVIDER;
-    const ok = await verifyCaptcha({
-        provider,
-        secret: captchaSecret,
-        token: params.captchaToken,
-        remoteip: params.clientIp || null
-    });
-    if (!ok) {
-        throw new ApiError({ code: 403, message: 'Captcha verification failed' });
-    }
-}
-function buildReplyToValue(form, fields) {
-    const forced = typeof form.replyto_email === 'string' ? form.replyto_email.trim() : '';
-    const forcedValue = forced ? forced : '';
-    if (form.replyto_from_fields) {
-        const extracted = extractReplyToFromSubmission(fields);
-        if (extracted) {
-            return extracted;
-        }
-        return forcedValue || undefined;
-    }
-    return forcedValue || undefined;
-}
 export class FormAPI extends ApiModule {
     rateLimiter = new FixedWindowRateLimiter();
-    parseIdnameList(value, field) {
-        if (value === undefined || value === null || value === '') {
-            return [];
-        }
-        const raw = Array.isArray(value) ? value : [value];
-        const out = [];
-        for (const entry of raw) {
-            const str = String(entry ?? '').trim();
-            if (!str) {
-                continue;
-            }
-            // Allow comma-separated convenience in form-encoded inputs while keeping the field name canonical.
-            const parts = str.split(',').map((p) => p.trim());
-            for (const part of parts) {
-                if (!part) {
-                    continue;
-                }
-                const normalized = normalizeSlug(part);
-                if (!normalized) {
-                    throw new ApiError({ code: 400, message: `Invalid ${field} identifier "${part}"` });
-                }
-                out.push(normalized);
-            }
-        }
-        return Array.from(new Set(out));
-    }
-    parseMailbox(value) {
-        return parseMailbox(value);
-    }
     async postFormRecipient(apireq) {
         await assert_domain_and_user(apireq);
         const body = (apireq.req.body ?? {});
-        const idnameRaw = getBodyValue(body, 'idname');
-        const emailRaw = getBodyValue(body, 'email');
-        const nameRaw = getBodyValue(body, 'name');
-        const formKeyRaw = getBodyValue(body, 'form_key');
-        const formid = getBodyValue(body, 'formid');
-        const localeRaw = getBodyValue(body, 'locale');
-        if (!idnameRaw) {
-            throw new ApiError({ code: 400, message: 'Missing recipient identifier (idname)' });
-        }
-        const idname = normalizeSlug(idnameRaw);
-        if (!idname) {
-            throw new ApiError({ code: 400, message: 'Invalid recipient identifier (idname)' });
-        }
-        if (!emailRaw) {
-            throw new ApiError({ code: 400, message: 'Missing recipient email address' });
-        }
-        const mailbox = this.parseMailbox(emailRaw);
-        if (!mailbox) {
-            throw new ApiError({ code: 400, message: 'Invalid recipient email address' });
-        }
-        const email = mailbox.address;
-        if (/[\r\n]/.test(email)) {
-            throw new ApiError({ code: 400, message: 'Invalid recipient email address' });
-        }
-        const name = String(nameRaw || mailbox.name || '')
-            .trim()
-            .slice(0, 200);
-        if (/[\r\n]/.test(name)) {
-            throw new ApiError({ code: 400, message: 'Invalid recipient name' });
-        }
+        const payload = parseRecipientPayload({
+            idname: getBodyValue(body, 'idname'),
+            email: getBodyValue(body, 'email'),
+            name: getBodyValue(body, 'name'),
+            form_key: getBodyValue(body, 'form_key'),
+            formid: getBodyValue(body, 'formid'),
+            locale: getBodyValue(body, 'locale')
+        });
+        const idname = normalizeRecipientIdname(payload.idnameRaw);
+        const { email, mailbox } = normalizeRecipientEmail(payload.emailRaw);
+        const name = normalizeRecipientName(payload.nameRaw, mailbox.name);
         const user = apireq.user;
         const domain = apireq.domain;
-        let form_key = '';
-        if (formKeyRaw) {
-            const form = await api_form.findOne({ where: { form_key: formKeyRaw } });
-            if (!form || form.domain_id !== domain.domain_id || form.user_id !== user.user_id) {
-                throw new ApiError({ code: 404, message: 'No such form_key for this domain' });
-            }
-            form_key = form.form_key ?? '';
-        }
-        else if (formid) {
-            const locale = localeRaw ? normalizeSlug(localeRaw) : '';
-            if (locale) {
-                const form = await api_form.findOne({
-                    where: { user_id: user.user_id, domain_id: domain.domain_id, locale, idname: formid }
-                });
-                if (!form) {
-                    throw new ApiError({ code: 404, message: 'No such form for this domain/locale' });
-                }
-                form_key = form.form_key ?? '';
-            }
-            else {
-                const matches = await api_form.findAll({
-                    where: { user_id: user.user_id, domain_id: domain.domain_id, idname: formid },
-                    limit: 2
-                });
-                if (matches.length === 0) {
-                    throw new ApiError({ code: 404, message: 'No such form for this domain' });
-                }
-                if (matches.length > 1) {
-                    throw new ApiError({
-                        code: 409,
-                        message: 'Form identifier is ambiguous; provide locale or form_key'
-                    });
-                }
-                form_key = matches[0].form_key ?? '';
-            }
-        }
+        const form_key = await resolveFormKeyForRecipient({
+            formKeyRaw: payload.formKeyRaw,
+            formid: payload.formid,
+            localeRaw: payload.localeRaw,
+            user,
+            domain
+        });
         const record = {
             domain_id: domain.domain_id,
             form_key,
@@ -234,121 +60,32 @@ export class FormAPI extends ApiModule {
     }
     async postFormTemplate(apireq) {
         await assert_domain_and_user(apireq);
-        const { template, sender = '', recipient = '', idname, subject = '', locale = '', secret = '', replyto_email: replytoEmailRaw = '', replyto_from_fields: replytoFromFieldsRaw = false, allowed_fields: allowedFieldsRaw, captcha_required: captchaRequiredRaw } = apireq.req.body;
-        const captcha_required = normalizeBoolean(captchaRequiredRaw);
-        const replyto_from_fields = normalizeBoolean(replytoFromFieldsRaw);
-        const replyto_email = String(replytoEmailRaw ?? '').trim();
-        const allowed_fields = (() => {
-            if (allowedFieldsRaw === undefined || allowedFieldsRaw === null || allowedFieldsRaw === '') {
-                return [];
-            }
-            const raw = Array.isArray(allowedFieldsRaw) ? allowedFieldsRaw : [allowedFieldsRaw];
-            const out = [];
-            for (const entry of raw) {
-                if (typeof entry === 'string') {
-                    // Accept JSON arrays and comma-separated convenience.
-                    const trimmed = entry.trim();
-                    if (trimmed.startsWith('[')) {
-                        try {
-                            const parsed = JSON.parse(trimmed);
-                            if (Array.isArray(parsed)) {
-                                for (const item of parsed) {
-                                    const key = String(item ?? '').trim();
-                                    if (key) {
-                                        out.push(key);
-                                    }
-                                }
-                                continue;
-                            }
-                        }
-                        catch {
-                            // fall back to comma-splitting below
-                        }
-                    }
-                    for (const part of trimmed.split(',').map((p) => p.trim())) {
-                        if (part) {
-                            out.push(part);
-                        }
-                    }
-                }
-                else {
-                    const key = String(entry ?? '').trim();
-                    if (key) {
-                        out.push(key);
-                    }
-                }
-            }
-            return Array.from(new Set(out));
-        })();
-        if (!template) {
-            throw new ApiError({ code: 400, message: 'Missing template data' });
-        }
-        if (!idname) {
-            throw new ApiError({ code: 400, message: 'Missing form identifier' });
-        }
-        if (!sender) {
-            throw new ApiError({ code: 400, message: 'Missing sender address' });
-        }
-        if (!recipient) {
-            throw new ApiError({ code: 400, message: 'Missing recipient address' });
-        }
-        if (replyto_email) {
-            const mailbox = this.parseMailbox(replyto_email);
-            if (!mailbox) {
-                throw new ApiError({ code: 400, message: 'Invalid replyto_email address' });
-            }
-        }
+        const payload = parseFormTemplatePayload(apireq.req.body ?? {});
+        validateFormTemplatePayload(payload);
         const user = apireq.user;
         const domain = apireq.domain;
-        const resolvedLocale = locale || apireq.locale || '';
-        const userSlug = normalizeSlug(user.idname);
-        const domainSlug = normalizeSlug(domain.name);
-        const formSlug = normalizeSlug(idname);
-        const localeSlug = normalizeSlug(resolvedLocale || domain.locale || user.locale || '');
-        const slug = `${userSlug}-${domainSlug}${localeSlug ? '-' + localeSlug : ''}-${formSlug}`;
-        const filenameParts = [domainSlug, 'form-template'];
-        if (localeSlug) {
-            filenameParts.push(localeSlug);
-        }
-        filenameParts.push(formSlug);
-        let filename = path.join(...filenameParts);
-        if (!filename.endsWith('.njk')) {
-            filename += '.njk';
-        }
-        let form_key = '';
-        try {
-            const existing = await api_form.findOne({
-                where: {
-                    user_id: user.user_id,
-                    domain_id: domain.domain_id,
-                    locale: localeSlug,
-                    idname
-                }
-            });
-            form_key = existing?.form_key || nanoid();
-        }
-        catch {
-            form_key = nanoid();
-        }
-        const record = {
+        const resolvedLocale = payload.locale || apireq.locale || '';
+        const { localeSlug, slug, filename } = buildFormTemplatePaths({
+            user,
+            domain,
+            idname: payload.idname,
+            locale: resolvedLocale
+        });
+        let form_key = (await resolveFormKeyForTemplate({
+            user_id: user.user_id,
+            domain_id: domain.domain_id,
+            locale: localeSlug,
+            idname: payload.idname
+        })) || nanoid();
+        const record = buildFormTemplateRecord({
             form_key,
             user_id: user.user_id,
             domain_id: domain.domain_id,
             locale: localeSlug,
-            idname,
-            sender,
-            recipient,
-            subject,
-            template,
             slug,
             filename,
-            secret,
-            replyto_email,
-            replyto_from_fields,
-            allowed_fields,
-            captcha_required,
-            files: []
-        };
+            payload
+        });
         let created = false;
         for (let attempt = 0; attempt < 10; attempt++) {
             try {
@@ -400,80 +137,39 @@ export class FormAPI extends ApiModule {
             const fields = filterSubmissionFields(parsedInput.fields, form.allowed_fields);
             const clientIp = apireq.getClientIp() ?? '';
             await enforceCaptchaPolicy({ vars: env, form, captchaToken, clientIp });
-            const scopeFormKey = String(form.form_key ?? '').trim();
-            if (!scopeFormKey) {
-                throw new ApiError({ code: 500, message: 'Form is missing a form_key' });
-            }
-            const resolveRecipient = async (idname) => {
-                const scoped = await api_recipient.findOne({
-                    where: { domain_id: form.domain_id, form_key: scopeFormKey, idname }
-                });
-                if (scoped) {
-                    return scoped;
-                }
-                return api_recipient.findOne({ where: { domain_id: form.domain_id, form_key: '', idname } });
-            };
-            const recipients = this.parseIdnameList(recipientsRaw, 'recipients');
-            if (recipients.length > 25) {
-                throw new ApiError({ code: 400, message: 'Too many recipients requested' });
-            }
-            const resolvedRecipients = [];
-            for (const idname of recipients) {
-                const record = await resolveRecipient(idname);
-                if (!record) {
-                    throw new ApiError({ code: 404, message: `Unknown recipient identifier "${idname}"` });
-                }
-                resolvedRecipients.push(record);
-            }
-            const thevars = {};
-            /*
-        console.log('Headers:', apireq.req.headers);
-        console.log('Body:', JSON.stringify(apireq.req.body, null, 2));
-        console.log('Files:', JSON.stringify(apireq.req.files, null, 2));
-        */
+            const resolvedRecipients = await resolveRecipients(form, recipientsRaw);
+            const recipients = parseIdnameList(recipientsRaw, 'recipients');
+            const { rcptEmail, rcptName, rcptIdname, rcptIdnames } = getPrimaryRecipientInfo(form, resolvedRecipients);
             const domainRecord = await api_domain.findOne({ where: { domain_id: form.domain_id } });
             await this.server.storage.relocateUploads(domainRecord?.name ?? null, rawFiles);
             const { attachments, attachmentMap } = buildAttachments(rawFiles);
+            // Attach inline template assets (cid:...) so clients can render embedded images reliably.
+            // Linked assets (asset('...') without inline flag) are kept as URLs and are not attached here.
+            const templateFiles = Array.isArray(form.files) ? form.files : [];
+            const inlineTemplateAttachments = templateFiles
+                .filter((file) => Boolean(file && file.cid))
+                .map((file) => ({
+                filename: file.filename,
+                path: file.path,
+                cid: file.cid
+            }));
+            const allAttachments = [...inlineTemplateAttachments, ...attachments];
             const meta = buildRequestMeta(apireq.req);
-            const to = (() => {
-                if (resolvedRecipients.length === 0) {
-                    return form.recipient;
-                }
-                return resolvedRecipients.map((entry) => {
-                    const mailbox = this.parseMailbox(entry.email);
-                    if (!mailbox) {
-                        throw new ApiError({ code: 500, message: 'Recipient mapping has an invalid email address' });
-                    }
-                    const mappedName = entry.name ? String(entry.name).trim().slice(0, 200) : '';
-                    if (mappedName && /[\r\n]/.test(mappedName)) {
-                        throw new ApiError({ code: 500, message: 'Recipient mapping has an invalid name' });
-                    }
-                    return mappedName ? { name: mappedName, address: mailbox.address } : mailbox.address;
-                });
-            })();
-            const rcptEmailForTemplate = (() => {
-                if (resolvedRecipients.length > 0) {
-                    const mailbox = this.parseMailbox(resolvedRecipients[0].email);
-                    return mailbox?.address ?? resolvedRecipients[0].email;
-                }
-                const mailbox = this.parseMailbox(String(form.recipient ?? ''));
-                return mailbox?.address ?? String(form.recipient ?? '');
-            })();
+            const to = buildRecipientTo(form, resolvedRecipients);
             const replyToValue = buildReplyToValue(form, fields);
-            const context = {
-                _mm_form_key: form_key,
-                _mm_recipients: recipients,
-                _mm_locale: localeRaw,
-                _rcpt_email_: rcptEmailForTemplate,
-                _rcpt_name_: resolvedRecipients[0]?.name ? String(resolvedRecipients[0].name).trim().slice(0, 200) : '',
-                _rcpt_idname_: resolvedRecipients[0]?.idname ?? '',
-                _rcpt_idnames_: resolvedRecipients.map((entry) => entry.idname),
-                _attachments_: attachmentMap,
-                _vars_: thevars,
-                _fields_: fields,
-                _files_: rawFiles,
-                _meta_: meta
-            };
+            const context = buildSubmissionContext({
+                form_key,
+                localeRaw,
+                recipients,
+                rcptEmail,
+                rcptName,
+                rcptIdname,
+                rcptIdnames,
+                attachmentMap,
+                fields,
+                files: rawFiles,
+                meta
+            });
             nunjucks.configure({ autoescape: this.server.storage.vars.AUTOESCAPE_HTML });
             const html = nunjucks.renderString(form.template, context);
             const mailOptions = {
@@ -481,7 +177,7 @@ export class FormAPI extends ApiModule {
                 to,
                 subject: form.subject,
                 html,
-                attachments,
+                attachments: allAttachments,
                 ...(replyToValue ? { replyTo: replyToValue } : {})
             };
             try {

package/dist/api/mailer.js

@@ -100,13 +100,11 @@ export class MailerAPI extends ApiModule {
             throw new ApiError({ code: 400, message: 'Invalid email address(es): ' + invalid.join(',') });
         }
         let template = null;
-        const deflocale = this.server.storage.deflocale || '';
         const domain_id = apireq.domain.domain_id;
         try {
             template =
                 (await api_txmail.findOne({ where: { name, domain_id, locale } })) ||
-                    (await api_txmail.findOne({ where: { name, domain_id, locale: deflocale } })) ||
-                    (await api_txmail.findOne({ where: { name, domain_id } }));
+                    (await api_txmail.findOne({ where: { name, domain_id, locale: '' } }));
         }
         catch (error) {
             throw new ApiError({

package/dist/bin/mail-magic.js

@@ -7,13 +7,15 @@ import { startMailMagicServer } from '../index.js';
 const args = process.argv.slice(2);
 function usage(exitCode = 0) {
     const out = exitCode === 0 ? process.stdout : process.stderr;
-    out.write(`Usage: mail-magic [--env PATH]\n\n` +
+    out.write(`Usage: mail-magic [--env PATH] [--config DIR]\n\n` +
         `Options:\n` +
         `  -e, --env PATH   Path to .env (defaults to ./.env)\n` +
+        `  -c, --config DIR Config directory (overrides CONFIG_PATH)\n` +
         `  -h, --help       Show this help\n`);
     process.exit(exitCode);
 }
 let envPath;
+let configPath;
 for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (arg === '-h' || arg === '--help') {
@@ -29,10 +31,24 @@ for (let i = 0; i < args.length; i += 1) {
         i += 1;
         continue;
     }
+    if (arg === '-c' || arg === '--config') {
+        const next = args[i + 1];
+        if (!next) {
+            console.error('Error: --config requires a directory');
+            usage(1);
+        }
+        configPath = next;
+        i += 1;
+        continue;
+    }
     if (arg.startsWith('--env=')) {
         envPath = arg.slice('--env='.length);
         continue;
     }
+    if (arg.startsWith('--config=')) {
+        configPath = arg.slice('--config='.length);
+        continue;
+    }
     console.error(`Error: unknown option ${arg}`);
     usage(1);
 }
@@ -41,6 +57,19 @@ if (!fs.existsSync(resolvedEnvPath)) {
     console.error(`Error: env file not found at ${resolvedEnvPath}`);
     process.exit(1);
 }
+let resolvedConfigPath;
+if (configPath) {
+    // Resolve the config dir relative to the .env directory (we chdir there next).
+    resolvedConfigPath = path.resolve(path.dirname(resolvedEnvPath), configPath);
+    if (!fs.existsSync(resolvedConfigPath)) {
+        console.error(`Error: config dir not found at ${resolvedConfigPath}`);
+        process.exit(1);
+    }
+    if (!fs.statSync(resolvedConfigPath).isDirectory()) {
+        console.error(`Error: config path is not a directory: ${resolvedConfigPath}`);
+        process.exit(1);
+    }
+}
 process.chdir(path.dirname(resolvedEnvPath));
 const result = dotenv.config({ path: resolvedEnvPath });
 if (result.error) {
@@ -50,7 +79,8 @@ if (result.error) {
 }
 async function main() {
     try {
-        const { store, vars } = await startMailMagicServer();
+        const envOverrides = resolvedConfigPath ? { CONFIG_PATH: resolvedConfigPath } : {};
+        const { store, vars } = await startMailMagicServer({}, envOverrides);
         console.log(`Using config path: ${store.configpath}`);
         console.log(`mail-magic server listening on ${vars.API_HOST}:${vars.API_PORT}`);
     }

package/dist/models/form.js

@@ -41,7 +41,7 @@ export const api_form_schema = z
         .string()
         .default('')
         .describe('Relative path (within the config tree) of the source .njk template file for this form.'),
-    slug: z.string().default('').describe('Generated slug used to build stable filenames/paths for this form.'),
+    slug: z.string().default('').describe('Generated slug for this form record (domain + locale + idname).'),
     secret: z
         .string()
         .default('')
@@ -214,12 +214,11 @@ export async function init_api_form(api_db) {
 }
 export async function upsert_form(record) {
     const { user, domain } = await user_and_domain(record.domain_id);
-    const idname = normalizeSlug(user.idname);
     const dname = normalizeSlug(domain.name);
     const name = normalizeSlug(record.idname);
     const locale = normalizeSlug(record.locale || domain.locale || user.locale || '');
     if (!record.slug) {
-        record.slug = `${idname}-${dname}${locale ? '-' + locale : ''}-${name}`;
+        record.slug = `${dname}${locale ? '-' + locale : ''}-${name}`;
     }
     if (!record.filename) {
         const parts = [dname, 'form-template'];

package/dist/models/init.js

@@ -8,6 +8,15 @@ import { api_domain, api_domain_schema } from './domain.js';
 import { api_form_schema, upsert_form } from './form.js';
 import { api_txmail_schema, upsert_txmail } from './txmail.js';
 import { apiTokenToHmac, api_user, api_user_schema } from './user.js';
+function buildInlineAssetCid(urlPath) {
+    // Many mail clients are picky about Content-ID values. Keep it stable and avoid path separators.
+    // Use a sanitized urlPath so nested assets remain unique without embedding `/` in the CID.
+    const normalized = String(urlPath || '')
+        .trim()
+        .replace(/\\/g, '/');
+    const safe = normalized.replace(/[^A-Za-z0-9._-]/g, '_').replace(/_+/g, '_');
+    return (safe || 'asset').slice(0, 200);
+}
 const init_data_schema = z.object({
     user: z.array(api_user_schema).default([]),
     domain: z.array(api_domain_schema).default([]),
@@ -57,7 +66,7 @@ async function _load_template(store, filename, pathname, user, domain, locale, t
             return {
                 filename: urlPath,
                 path: asset.path,
-                cid: asset.cid ? urlPath : undefined
+                cid: asset.cid ? buildInlineAssetCid(urlPath) : undefined
             };
         });
         for (const asset of assets) {
@@ -66,8 +75,9 @@ async function _load_template(store, filename, pathname, user, domain, locale, t
             }
             const rel = asset.filename.replace(/\\/g, '/');
             const urlPath = rel.startsWith('assets/') ? rel.slice('assets/'.length) : rel;
-            if (asset.cid !== urlPath) {
-                html = html.replaceAll(`cid:${asset.cid}`, `cid:${urlPath}`);
+            const desiredCid = buildInlineAssetCid(urlPath);
+            if (asset.cid !== desiredCid) {
+                html = html.replaceAll(`cid:${asset.cid}`, `cid:${desiredCid}`);
             }
         }
         return { html, assets: mappedAssets };

package/dist/models/txmail.js

@@ -14,7 +14,7 @@ export const api_txmail_schema = z
     filename: z.string().default('').describe('Relative path of the source .njk template file.'),
     sender: z.string().min(1).describe('Email From header used when delivering this template.'),
     subject: z.string().describe('Email subject used when delivering this template.'),
-    slug: z.string().default('').describe('Generated slug used to build stable filenames/paths.'),
+    slug: z.string().default('').describe('Generated slug for this template record (domain + locale + name).'),
     part: z.boolean().default(false).describe('If true, template is a partial (not a standalone send).'),
     files: z
         .array(z.object({
@@ -32,12 +32,11 @@ export class api_txmail extends Model {
 }
 export async function upsert_txmail(record) {
     const { user, domain } = await user_and_domain(record.domain_id);
-    const idname = normalizeSlug(user.idname);
     const dname = normalizeSlug(domain.name);
     const name = normalizeSlug(record.name);
     const locale = normalizeSlug(record.locale || domain.locale || user.locale || '');
     if (!record.slug) {
-        record.slug = `${idname}-${dname}${locale ? '-' + locale : ''}-${name}`;
+        record.slug = `${dname}${locale ? '-' + locale : ''}-${name}`;
     }
     if (!record.filename) {
         const parts = [dname, 'tx-template'];
@@ -155,7 +154,7 @@ export async function init_api_txmail(api_db) {
         const dname = normalizeSlug(domain.name);
         const name = normalizeSlug(template.name);
         const locale = normalizeSlug(template.locale || domain.locale || user.locale || '');
-        template.slug ||= `${normalizeSlug(user.idname)}-${dname}${locale ? '-' + locale : ''}-${name}`;
+        template.slug ||= `${dname}${locale ? '-' + locale : ''}-${name}`;
         if (!template.filename) {
             const parts = [dname, 'tx-template'];
             if (locale)

package/dist/{api → util}/form-submission.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { getBodyValue } from '../util.js';
+import { getBodyValue } from './utils.js';
 const ALLOWED_MM_KEYS = new Set(['_mm_form_key', '_mm_locale', '_mm_recipients']);
 function asRecord(input) {
     if (!input || typeof input !== 'object' || Array.isArray(input)) {

package/dist/util/forms.js

@@ -0,0 +1,431 @@
+import path from 'path';
+import { ApiError } from '@technomoron/api-server-base';
+import { api_form } from '../models/form.js';
+import { api_recipient } from '../models/recipient.js';
+import { verifyCaptcha } from './captcha.js';
+import { parseMailbox } from './email.js';
+import { extractReplyToFromSubmission } from './form-replyto.js';
+import { parseFormSubmissionInput } from './form-submission.js';
+import { normalizeBoolean, normalizeSlug } from './utils.js';
+export function parsePublicSubmissionOrThrow(apireq) {
+    try {
+        return parseFormSubmissionInput(apireq.req.body);
+    }
+    catch {
+        // Treat malformed input as a bad request (Zod schema failures, non-object bodies, etc).
+        throw new ApiError({ code: 400, message: 'Invalid form submission payload' });
+    }
+}
+export function enforceAttachmentPolicy(env, rawFiles) {
+    if (env.FORM_MAX_ATTACHMENTS === 0 && rawFiles.length > 0) {
+        throw new ApiError({ code: 413, message: 'This endpoint does not accept file attachments' });
+    }
+    for (const file of rawFiles) {
+        if (!file?.fieldname) {
+            continue;
+        }
+        if (!file.fieldname.startsWith('_mm_file')) {
+            throw new ApiError({
+                code: 400,
+                message: 'Invalid upload field name. Use _mm_file* for attachments.'
+            });
+        }
+    }
+    if (env.FORM_MAX_ATTACHMENTS > 0 && rawFiles.length > env.FORM_MAX_ATTACHMENTS) {
+        throw new ApiError({
+            code: 413,
+            message: `Too many attachments: ${rawFiles.length} > ${env.FORM_MAX_ATTACHMENTS}`
+        });
+    }
+}
+export function filterSubmissionFields(rawFields, allowedFields) {
+    const allowed = Array.isArray(allowedFields) ? allowedFields : [];
+    if (!allowed.length) {
+        return rawFields;
+    }
+    const filtered = {};
+    // Always allow Reply-To derivation fields even when allowed_fields is configured.
+    const alwaysAllow = ['email', 'name', 'first_name', 'last_name'];
+    for (const key of alwaysAllow) {
+        if (Object.prototype.hasOwnProperty.call(rawFields, key)) {
+            filtered[key] = rawFields[key];
+        }
+    }
+    for (const key of allowed) {
+        const k = typeof key === 'string' ? key : String(key ?? '').trim();
+        if (!k) {
+            continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(rawFields, k)) {
+            filtered[k] = rawFields[k];
+        }
+    }
+    return filtered;
+}
+export async function enforceCaptchaPolicy(params) {
+    const captchaRequired = Boolean(params.vars.FORM_CAPTCHA_REQUIRED || params.form.captcha_required);
+    const captchaSecret = String(params.vars.FORM_CAPTCHA_SECRET ?? '').trim();
+    if (!captchaSecret) {
+        if (captchaRequired) {
+            throw new ApiError({ code: 500, message: 'Captcha is required but not configured on the server' });
+        }
+        return;
+    }
+    if (!params.captchaToken) {
+        if (captchaRequired) {
+            throw new ApiError({ code: 403, message: 'Captcha token required' });
+        }
+        return;
+    }
+    const provider = params.vars.FORM_CAPTCHA_PROVIDER;
+    const ok = await verifyCaptcha({
+        provider,
+        secret: captchaSecret,
+        token: params.captchaToken,
+        remoteip: params.clientIp || null
+    });
+    if (!ok) {
+        throw new ApiError({ code: 403, message: 'Captcha verification failed' });
+    }
+}
+export function buildReplyToValue(form, fields) {
+    const forced = typeof form.replyto_email === 'string' ? form.replyto_email.trim() : '';
+    const forcedValue = forced ? forced : '';
+    if (form.replyto_from_fields) {
+        const extracted = extractReplyToFromSubmission(fields);
+        if (extracted) {
+            return extracted;
+        }
+        return forcedValue || undefined;
+    }
+    return forcedValue || undefined;
+}
+export function parseIdnameList(value, field) {
+    if (value === undefined || value === null || value === '') {
+        return [];
+    }
+    const raw = Array.isArray(value) ? value : [value];
+    const out = [];
+    for (const entry of raw) {
+        const str = String(entry ?? '').trim();
+        if (!str) {
+            continue;
+        }
+        // Allow comma-separated convenience in form-encoded inputs while keeping the field name canonical.
+        const parts = str.split(',').map((p) => p.trim());
+        for (const part of parts) {
+            if (!part) {
+                continue;
+            }
+            const normalized = normalizeSlug(part);
+            if (!normalized) {
+                throw new ApiError({ code: 400, message: `Invalid ${field} identifier "${part}"` });
+            }
+            out.push(normalized);
+        }
+    }
+    return Array.from(new Set(out));
+}
+export function parseRecipientPayload(body) {
+    return {
+        idnameRaw: String(body.idname ?? ''),
+        emailRaw: String(body.email ?? ''),
+        nameRaw: String(body.name ?? ''),
+        formKeyRaw: String(body.form_key ?? ''),
+        formid: String(body.formid ?? ''),
+        localeRaw: String(body.locale ?? '')
+    };
+}
+export function normalizeRecipientIdname(raw) {
+    if (!raw) {
+        throw new ApiError({ code: 400, message: 'Missing recipient identifier (idname)' });
+    }
+    const idname = normalizeSlug(raw);
+    if (!idname) {
+        throw new ApiError({ code: 400, message: 'Invalid recipient identifier (idname)' });
+    }
+    return idname;
+}
+export function normalizeRecipientEmail(raw) {
+    if (!raw) {
+        throw new ApiError({ code: 400, message: 'Missing recipient email address' });
+    }
+    const mailbox = parseMailbox(raw);
+    if (!mailbox) {
+        throw new ApiError({ code: 400, message: 'Invalid recipient email address' });
+    }
+    const email = mailbox.address;
+    if (/[\r\n]/.test(email)) {
+        throw new ApiError({ code: 400, message: 'Invalid recipient email address' });
+    }
+    return { email, mailbox };
+}
+export function normalizeRecipientName(raw, mailboxName) {
+    const name = String(raw || mailboxName || '')
+        .trim()
+        .slice(0, 200);
+    if (/[\r\n]/.test(name)) {
+        throw new ApiError({ code: 400, message: 'Invalid recipient name' });
+    }
+    return name;
+}
+export async function resolveFormKeyForRecipient(params) {
+    if (params.formKeyRaw) {
+        const form = await api_form.findOne({ where: { form_key: params.formKeyRaw } });
+        if (!form || form.domain_id !== params.domain.domain_id || form.user_id !== params.user.user_id) {
+            throw new ApiError({ code: 404, message: 'No such form_key for this domain' });
+        }
+        return form.form_key ?? '';
+    }
+    if (params.formid) {
+        const locale = params.localeRaw ? normalizeSlug(params.localeRaw) : '';
+        if (locale) {
+            const form = await api_form.findOne({
+                where: {
+                    user_id: params.user.user_id,
+                    domain_id: params.domain.domain_id,
+                    locale,
+                    idname: params.formid
+                }
+            });
+            if (!form) {
+                throw new ApiError({ code: 404, message: 'No such form for this domain/locale' });
+            }
+            return form.form_key ?? '';
+        }
+        const matches = await api_form.findAll({
+            where: { user_id: params.user.user_id, domain_id: params.domain.domain_id, idname: params.formid },
+            limit: 2
+        });
+        if (matches.length === 0) {
+            throw new ApiError({ code: 404, message: 'No such form for this domain' });
+        }
+        if (matches.length > 1) {
+            throw new ApiError({
+                code: 409,
+                message: 'Form identifier is ambiguous; provide locale or form_key'
+            });
+        }
+        return matches[0].form_key ?? '';
+    }
+    return '';
+}
+export function parseAllowedFields(raw) {
+    if (raw === undefined || raw === null || raw === '') {
+        return [];
+    }
+    const items = Array.isArray(raw) ? raw : [raw];
+    const out = [];
+    for (const entry of items) {
+        if (typeof entry === 'string') {
+            // Accept JSON arrays and comma-separated convenience.
+            const trimmed = entry.trim();
+            if (trimmed.startsWith('[')) {
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    if (Array.isArray(parsed)) {
+                        for (const item of parsed) {
+                            const key = String(item ?? '').trim();
+                            if (key) {
+                                out.push(key);
+                            }
+                        }
+                        continue;
+                    }
+                }
+                catch {
+                    // fall back to comma-splitting below
+                }
+            }
+            for (const part of trimmed.split(',').map((p) => p.trim())) {
+                if (part) {
+                    out.push(part);
+                }
+            }
+        }
+        else {
+            const key = String(entry ?? '').trim();
+            if (key) {
+                out.push(key);
+            }
+        }
+    }
+    return Array.from(new Set(out));
+}
+export function parseFormTemplatePayload(body) {
+    const template = body.template ? String(body.template) : '';
+    const sender = body.sender ? String(body.sender) : '';
+    const recipient = body.recipient ? String(body.recipient) : '';
+    const idname = body.idname ? String(body.idname) : '';
+    const subject = body.subject ? String(body.subject) : '';
+    const locale = body.locale ? String(body.locale) : '';
+    const secret = body.secret ? String(body.secret) : '';
+    const replyto_email = String(body.replyto_email ?? '').trim();
+    const replyto_from_fields = normalizeBoolean(body.replyto_from_fields);
+    const captcha_required = normalizeBoolean(body.captcha_required);
+    const allowed_fields = parseAllowedFields(body.allowed_fields);
+    return {
+        template,
+        sender,
+        recipient,
+        idname,
+        subject,
+        locale,
+        secret,
+        replyto_email,
+        replyto_from_fields,
+        allowed_fields,
+        captcha_required
+    };
+}
+export function validateFormTemplatePayload(payload) {
+    if (!payload.template) {
+        throw new ApiError({ code: 400, message: 'Missing template data' });
+    }
+    if (!payload.idname) {
+        throw new ApiError({ code: 400, message: 'Missing form identifier' });
+    }
+    if (!payload.sender) {
+        throw new ApiError({ code: 400, message: 'Missing sender address' });
+    }
+    if (!payload.recipient) {
+        throw new ApiError({ code: 400, message: 'Missing recipient address' });
+    }
+    if (payload.replyto_email) {
+        const mailbox = parseMailbox(payload.replyto_email);
+        if (!mailbox) {
+            throw new ApiError({ code: 400, message: 'Invalid replyto_email address' });
+        }
+    }
+}
+export function buildFormTemplatePaths(params) {
+    const domainSlug = normalizeSlug(params.domain.name);
+    const formSlug = normalizeSlug(params.idname);
+    const localeSlug = normalizeSlug(params.locale || params.domain.locale || params.user.locale || '');
+    const slug = `${domainSlug}${localeSlug ? '-' + localeSlug : ''}-${formSlug}`;
+    const filenameParts = [domainSlug, 'form-template'];
+    if (localeSlug) {
+        filenameParts.push(localeSlug);
+    }
+    filenameParts.push(formSlug);
+    let filename = path.join(...filenameParts);
+    if (!filename.endsWith('.njk')) {
+        filename += '.njk';
+    }
+    return { localeSlug, slug, filename };
+}
+export async function resolveFormKeyForTemplate(params) {
+    try {
+        const existing = await api_form.findOne({
+            where: {
+                user_id: params.user_id,
+                domain_id: params.domain_id,
+                locale: params.locale,
+                idname: params.idname
+            }
+        });
+        return existing?.form_key || '';
+    }
+    catch {
+        return '';
+    }
+}
+export function buildFormTemplateRecord(params) {
+    return {
+        form_key: params.form_key,
+        user_id: params.user_id,
+        domain_id: params.domain_id,
+        locale: params.locale,
+        idname: params.payload.idname,
+        sender: params.payload.sender,
+        recipient: params.payload.recipient,
+        subject: params.payload.subject,
+        template: params.payload.template,
+        slug: params.slug,
+        filename: params.filename,
+        secret: params.payload.secret,
+        replyto_email: params.payload.replyto_email,
+        replyto_from_fields: params.payload.replyto_from_fields,
+        allowed_fields: params.payload.allowed_fields,
+        captcha_required: params.payload.captcha_required,
+        files: []
+    };
+}
+export async function resolveRecipients(form, recipientsRaw) {
+    const scopeFormKey = String(form.form_key ?? '').trim();
+    if (!scopeFormKey) {
+        throw new ApiError({ code: 500, message: 'Form is missing a form_key' });
+    }
+    const resolveRecipient = async (idname) => {
+        const scoped = await api_recipient.findOne({
+            where: { domain_id: form.domain_id, form_key: scopeFormKey, idname }
+        });
+        if (scoped) {
+            return scoped;
+        }
+        return api_recipient.findOne({ where: { domain_id: form.domain_id, form_key: '', idname } });
+    };
+    const recipients = parseIdnameList(recipientsRaw, 'recipients');
+    if (recipients.length > 25) {
+        throw new ApiError({ code: 400, message: 'Too many recipients requested' });
+    }
+    const resolvedRecipients = [];
+    for (const idname of recipients) {
+        const record = await resolveRecipient(idname);
+        if (!record) {
+            throw new ApiError({ code: 404, message: `Unknown recipient identifier "${idname}"` });
+        }
+        resolvedRecipients.push(record);
+    }
+    return resolvedRecipients;
+}
+export function buildRecipientTo(form, recipients) {
+    if (recipients.length === 0) {
+        return form.recipient;
+    }
+    return recipients.map((entry) => {
+        const mailbox = parseMailbox(entry.email);
+        if (!mailbox) {
+            throw new ApiError({ code: 500, message: 'Recipient mapping has an invalid email address' });
+        }
+        const mappedName = entry.name ? String(entry.name).trim().slice(0, 200) : '';
+        if (mappedName && /[\r\n]/.test(mappedName)) {
+            throw new ApiError({ code: 500, message: 'Recipient mapping has an invalid name' });
+        }
+        return mappedName ? { name: mappedName, address: mailbox.address } : mailbox.address;
+    });
+}
+export function getPrimaryRecipientInfo(form, recipients) {
+    if (recipients.length > 0) {
+        const mailbox = parseMailbox(recipients[0].email);
+        return {
+            rcptEmail: mailbox?.address ?? recipients[0].email,
+            rcptName: recipients[0].name ? String(recipients[0].name).trim().slice(0, 200) : '',
+            rcptIdname: recipients[0].idname ?? '',
+            rcptIdnames: recipients.map((entry) => entry.idname)
+        };
+    }
+    const mailbox = parseMailbox(String(form.recipient ?? ''));
+    return {
+        rcptEmail: mailbox?.address ?? String(form.recipient ?? ''),
+        rcptName: '',
+        rcptIdname: '',
+        rcptIdnames: []
+    };
+}
+export function buildSubmissionContext(params) {
+    return {
+        _mm_form_key: params.form_key,
+        _mm_recipients: params.recipients,
+        _mm_locale: params.localeRaw,
+        _rcpt_email_: params.rcptEmail,
+        _rcpt_name_: params.rcptName,
+        _rcpt_idname_: params.rcptIdname,
+        _rcpt_idnames_: params.rcptIdnames,
+        _attachments_: params.attachmentMap,
+        _vars_: {},
+        _fields_: params.fields,
+        _files_: params.files,
+        _meta_: params.meta
+    };
+}

package/dist/util.js

@@ -2,3 +2,6 @@ export * from './util/utils.js';
 export * from './util/email.js';
 export * from './util/paths.js';
 export * from './util/uploads.js';
+export * from './util/form-replyto.js';
+export * from './util/form-submission.js';
+export * from './util/forms.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@technomoron/mail-magic",
-	"version": "1.0.33",
+	"version": "1.0.35",
 	"main": "dist/index.js",
 	"type": "module",
 	"bin": {