@technomoron/mail-magic 1.0.41 → 1.0.43

package/CHANGES

@@ -1,6 +1,42 @@
 CHANGES
 =======
 
+Version 1.0.43 (2026-03-04)
+
+- fix(security): add allowlist for custom email headers on `/v1/tx/message` to prevent header injection via arbitrary keys (e.g. `Bcc`, `From`, `Sender`).
+- fix(security): sanitize Swagger error response to avoid leaking internal filesystem paths.
+- fix(security): reject `..` and `.` path segments explicitly in `normalizeSubdir`.
+- fix(forms): return 500 error instead of silent success when all `form_key` generation attempts are exhausted.
+- fix(mailer): guard `transport` with null check instead of non-null assertion; return 503 when transport is unavailable.
+- fix(mailer): stop leaking internal error details (SMTP errors, file paths) in `/v1/tx/message` error responses.
+- fix(autoreload): debounce `fs.watch` callback (300ms) to prevent reload storms from rapid file change events.
+- refactor(form-replyto): replace duplicated `getFirstStringField` with shared `getBodyValue` from utils.
+- docs(readme): fix `rcpt` example from JSON array to comma-separated string to match actual API contract.
+- feat(locale): implement 3-step locale fallback for template lookup: request locale → domain default locale → empty locale.
+- fix(auth): resolve default locale from domain record instead of hardcoding `'en'` when request omits `locale`.
+- refactor(locale): remove `user.locale` from all locale resolution chains; domain locale is the sole default.
+- docs(tutorial): replace non-existent `now().iso8601()` Nunjucks call with `default('unknown')`.
+- test(autoreload): update store-autoreload tests to use fake timers for debounced reload.
+- perf(forms): batch recipient resolution for `_mm_recipients` into scoped + fallback `IN` queries while preserving precedence and requested order.
+- test(forms): add coverage for multi-recipient resolution order with scoped-over-domain recipient precedence.
+- (Changes generated/assisted by Codex (profile: openai-gpt-5-codex/medium).)
+- (Changes generated/assisted by Claude Code (profile: anthropic-claude-opus-4-6/high).)
+
+Version 1.0.42 (2026-02-27)
+
+- chore(deps): upgrade `@technomoron/api-server-base` from `2.0.0-beta.20` to `2.0.0-beta.24` (Express → Fastify migration).
+- feat(auth): enable API key authentication (`apiKeyEnabled: true`, `apiKeyPrefix: 'apikey-'`) in server config to restore API key auth broken by the beta.24 default change.
+- feat(ratelimit): replace local `FixedWindowRateLimiter` implementation with the one exported by `@technomoron/api-server-base`; re-export for consumers.
+- feat(validation): add Fastify JSON Schema validation (`schema`) to `/v1/tx/template`, `/v1/form/template`, and `/v1/form/recipient` routes; omit schema from multipart-capable routes where body is populated after Fastify's validation phase.
+- fix(assets): use a MIME type map to set correct `Content-Type` headers (e.g. `image/png`) instead of passing raw file extensions to `fastifyReply.type()`, which Fastify 5 does not convert automatically.
+- fix(assets): read asset files into a `Buffer` for `res.send()` since Fastify 5 stream piping through `fastify.routing()` does not flush to supertest-style clients.
+- fix(ratelimit): restore `Retry-After` response header on 429 rate-limit rejections by setting it on the underlying Fastify reply before throwing `ApiError`.
+- fix(uploads): update `UploadedFile` type to match `ApiUploadedFile` from beta.24 (`filepath?`/`buffer?` instead of `path`); update `store.ts`, `uploads.ts`, `mailer.ts`, `forms.ts` to handle both in-memory buffers and on-disk files.
+- fix(swagger): replace Express-typed handler signature with `ExtendedReq`/`ApiRequest['res']` from `@technomoron/api-server-base`.
+- fix(routes): change wildcard route from `/:domain/*path` to `/:domain/*` (find-my-way/Fastify does not support named wildcards).
+- docs(swagger): bump packaged OpenAPI spec version to 1.0.42.
+- (Changes generated/assisted by Claude Code (profile: anthropic-claude-sonnet-4-6/high).)
+
 Version 1.0.41 (2026-02-22)
 
 - chore(release): add package-level `release:check` script and wire `release` to shared publish script.

package/README.md

@@ -209,7 +209,7 @@ curl -X POST http://localhost:3776/api/v1/tx/message \
     "domain": "example.test",
     "name": "welcome",
     "locale": "en",
-    "rcpt": ["person@example.test"],
+    "rcpt": "person@example.test",
     "vars": { "first_name": "Ada" }
   }'
 ```

package/dist/esm/api/assets.d.ts

@@ -1,9 +1,11 @@
 import { ApiModule, ApiRoute } from '@technomoron/api-server-base';
 import { mailApiServer } from '../server.js';
-import type { NextFunction, Request, Response } from 'express';
+import type { ApiRequest, ExtendedReq } from '@technomoron/api-server-base';
+type ApiRes = ApiRequest['res'];
 export declare class AssetAPI extends ApiModule<mailApiServer> {
     private resolveTemplateDir;
     private postAssets;
     defineRoutes(): ApiRoute[];
 }
-export declare function createAssetHandler(server: mailApiServer): (req: Request, res: Response, next?: NextFunction) => Promise<void>;
+export declare function createAssetHandler(server: mailApiServer): (req: ExtendedReq, res: ApiRes, next?: (error?: unknown) => void) => Promise<void>;
+export {};

package/dist/esm/api/assets.js

@@ -6,12 +6,36 @@ import { api_txmail } from '../models/txmail.js';
 import { SEGMENT_PATTERN, normalizeSubdir } from '../util/paths.js';
 import { moveUploadedFiles } from '../util/uploads.js';
 import { getBodyValue } from '../util/utils.js';
-import { decodeComponent, sendFileAsync } from '../util.js';
+import { decodeComponent } from '../util.js';
 import { assert_domain_and_user } from './auth.js';
 const DOMAIN_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
+const MIME_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.css': 'text/css',
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.json': 'application/json',
+    '.txt': 'text/plain',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.pdf': 'application/pdf',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.eot': 'application/vnd.ms-fontobject'
+};
+function getMimeType(ext) {
+    return MIME_TYPES[ext.toLowerCase()] ?? 'application/octet-stream';
+}
 export class AssetAPI extends ApiModule {
     async resolveTemplateDir(apireq) {
-        const body = apireq.req.body ?? {};
+        const body = (apireq.req.body ?? {});
         const templateTypeRaw = getBodyValue(body, 'templateType', 'template_type', 'type');
         const templateName = getBodyValue(body, 'template', 'name', 'idname', 'formid');
         const locale = getBodyValue(body, 'locale');
@@ -23,9 +47,17 @@ export class AssetAPI extends ApiModule {
         }
         const templateType = templateTypeRaw.toLowerCase();
         const domainId = apireq.domain.domain_id;
+        const deflocale = apireq.domain.locale || '';
         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: '' } }));
+            let template = await api_txmail.findOne({ where: { name: templateName, domain_id: domainId, locale } });
+            if (!template && deflocale && deflocale !== locale) {
+                template = await api_txmail.findOne({
+                    where: { name: templateName, domain_id: domainId, locale: deflocale }
+                });
+            }
+            if (!template && locale !== '') {
+                template = await api_txmail.findOne({ where: { name: templateName, domain_id: domainId, locale: '' } });
+            }
             if (!template) {
                 throw new ApiError({
                     code: 404,
@@ -41,8 +73,15 @@ export class AssetAPI extends ApiModule {
             return path.dirname(candidate);
         }
         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: '' } }));
+            let form = await api_form.findOne({ where: { idname: templateName, domain_id: domainId, locale } });
+            if (!form && deflocale && deflocale !== locale) {
+                form = await api_form.findOne({
+                    where: { idname: templateName, domain_id: domainId, locale: deflocale }
+                });
+            }
+            if (!form && locale !== '') {
+                form = await api_form.findOne({ where: { idname: templateName, domain_id: domainId, locale: '' } });
+            }
             if (!form) {
                 throw new ApiError({
                     code: 404,
@@ -65,7 +104,7 @@ export class AssetAPI extends ApiModule {
         if (!rawFiles.length) {
             throw new ApiError({ code: 400, message: 'No files uploaded' });
         }
-        const body = apireq.req.body ?? {};
+        const body = (apireq.req.body ?? {});
         const subdir = normalizeSubdir(getBodyValue(body, 'path', 'dir'));
         const templateType = getBodyValue(body, 'templateType', 'template_type', 'type');
         let targetRoot;
@@ -101,15 +140,15 @@ export function createAssetHandler(server) {
                 next();
                 return;
             }
-            res.status(405).end();
+            res.status(405).send(null);
             return;
         }
-        const domain = decodeComponent(req?.params?.domain);
+        const domain = decodeComponent(req?.params?.['domain']);
         if (!domain || !DOMAIN_PATTERN.test(domain)) {
-            res.status(404).end();
+            res.status(404).send(null);
             return;
         }
-        const rawPathParam = req?.params?.path ?? req?.params?.[0];
+        const rawPathParam = req.params?.['path'] ?? req.params?.['*'];
         const rawSegments = Array.isArray(rawPathParam)
             ? rawPathParam
             : typeof rawPathParam === 'string'
@@ -117,12 +156,12 @@ export function createAssetHandler(server) {
                 : [];
         const segments = rawSegments.map((segment) => decodeComponent(typeof segment === 'string' ? segment : ''));
         if (!segments.length || segments.some((segment) => !SEGMENT_PATTERN.test(segment))) {
-            res.status(404).end();
+            res.status(404).send(null);
             return;
         }
         const assetsRoot = path.join(server.storage.configpath, domain, 'assets');
         if (!fs.existsSync(assetsRoot)) {
-            res.status(404).end();
+            res.status(404).send(null);
             return;
         }
         const resolvedRoot = fs.realpathSync(assetsRoot);
@@ -131,12 +170,12 @@ export function createAssetHandler(server) {
         try {
             const stats = await fs.promises.stat(candidate);
             if (!stats.isFile()) {
-                res.status(404).end();
+                res.status(404).send(null);
                 return;
             }
         }
         catch {
-            res.status(404).end();
+            res.status(404).send(null);
             return;
         }
         let realCandidate;
@@ -144,23 +183,29 @@ export function createAssetHandler(server) {
             realCandidate = await fs.promises.realpath(candidate);
         }
         catch {
-            res.status(404).end();
+            res.status(404).send(null);
             return;
         }
         if (!realCandidate.startsWith(normalizedRoot)) {
-            res.status(404).end();
+            res.status(404).send(null);
             return;
         }
-        res.type(path.extname(realCandidate));
+        const ext = path.extname(realCandidate);
+        // Access the underlying Fastify reply to set content-type and cache-control headers.
+        // ApiResponse does not expose arbitrary header-setting methods.
+        const fastifyReply = res.reply;
+        if (fastifyReply) {
+            fastifyReply.type(getMimeType(ext));
+            fastifyReply.header('cache-control', 'public, max-age=300');
+        }
         try {
-            // Express' `sendFile()` sets Cache-Control based on `maxAge` (in ms). Setting the header
-            // before calling `sendFile()` can be overwritten by Express defaults.
-            await sendFileAsync(res, realCandidate, { maxAge: 300_000 });
+            const content = await fs.promises.readFile(realCandidate);
+            res.send(content);
         }
         catch (err) {
             server.storage.print_debug(`Failed to serve asset ${domain}/${segments.join('/')}: ${err instanceof Error ? err.message : String(err)}`);
             if (!res.headersSent) {
-                res.status(500).end();
+                res.status(500).send(null);
             }
         }
     };

package/dist/esm/api/auth.js

@@ -3,7 +3,7 @@ import { api_domain } from '../models/domain.js';
 import { api_user } from '../models/user.js';
 import { getBodyValue } from '../util/utils.js';
 export async function assert_domain_and_user(apireq) {
-    const body = apireq.req.body ?? {};
+    const body = (apireq.req.body ?? {});
     const domainRaw = getBodyValue(body, 'domain');
     const locale = getBodyValue(body, 'locale');
     const rawUid = apireq.getRealUid();
@@ -36,5 +36,5 @@ export async function assert_domain_and_user(apireq) {
     }
     apireq.domain = dbdomain;
     apireq.user = user;
-    apireq.locale = locale || 'en';
+    apireq.locale = locale || dbdomain.locale || '';
 }

package/dist/esm/api/forms.js

@@ -62,7 +62,7 @@ export class FormAPI extends ApiModule {
     }
     async postFormTemplate(apireq) {
         await assert_domain_and_user(apireq);
-        const payload = parseFormTemplatePayload(apireq.req.body ?? {});
+        const payload = parseFormTemplatePayload((apireq.req.body ?? {}));
         validateFormTemplatePayload(payload);
         const user = apireq.user;
         const domain = apireq.domain;
@@ -89,6 +89,7 @@ export class FormAPI extends ApiModule {
             payload
         });
         let created = false;
+        let upserted = false;
         for (let attempt = 0; attempt < 10; attempt++) {
             try {
                 const [form, wasCreated] = await api_form.upsert(record, {
@@ -96,6 +97,7 @@ export class FormAPI extends ApiModule {
                     conflictFields: ['user_id', 'domain_id', 'locale', 'idname']
                 });
                 created = wasCreated ?? false;
+                upserted = true;
                 form_key = form.form_key || form_key;
                 this.server.storage.print_debug(`Form template upserted: ${form.idname} (created=${wasCreated})`);
                 break;
@@ -115,6 +117,9 @@ export class FormAPI extends ApiModule {
                 });
             }
         }
+        if (!upserted) {
+            throw new ApiError({ code: 500, message: 'Unable to generate a unique form_key after multiple attempts' });
+        }
         return [200, { Status: 'OK', created, form_key }];
     }
     async postSendForm(apireq) {
@@ -185,6 +190,9 @@ export class FormAPI extends ApiModule {
                 ...(replyToValue ? { replyTo: replyToValue } : {})
             };
             try {
+                if (!this.server.storage.transport) {
+                    throw new ApiError({ code: 503, message: 'Mail transport is not available' });
+                }
                 const info = await this.server.storage.transport.sendMail(mailOptions);
                 this.server.storage.print_debug('Email sent: ' + info.response);
             }
@@ -207,13 +215,45 @@ export class FormAPI extends ApiModule {
                 method: 'post',
                 path: '/v1/form/recipient',
                 handler: (req) => this.postFormRecipient(req),
-                auth: { type: 'yes', req: 'any' }
+                auth: { type: 'yes', req: 'any' },
+                schema: {
+                    body: {
+                        type: 'object',
+                        required: ['email', 'idname'],
+                        properties: {
+                            email: { type: 'string' },
+                            idname: { type: 'string' },
+                            name: { type: 'string' },
+                            form_key: { type: 'string' },
+                            formid: { type: 'string' },
+                            locale: { type: 'string' },
+                            domain: { type: 'string' }
+                        },
+                        additionalProperties: true
+                    }
+                }
             },
             {
                 method: 'post',
                 path: '/v1/form/template',
                 handler: (req) => this.postFormTemplate(req),
-                auth: { type: 'yes', req: 'any' }
+                auth: { type: 'yes', req: 'any' },
+                schema: {
+                    body: {
+                        type: 'object',
+                        required: ['idname', 'template', 'sender', 'recipient'],
+                        properties: {
+                            idname: { type: 'string' },
+                            template: { type: 'string' },
+                            sender: { type: 'string' },
+                            recipient: { type: 'string' },
+                            subject: { type: 'string' },
+                            locale: { type: 'string' },
+                            domain: { type: 'string' }
+                        },
+                        additionalProperties: true
+                    }
+                }
             },
             {
                 method: 'post',

package/dist/esm/api/mailer.js

@@ -31,7 +31,12 @@ export class MailerAPI extends ApiModule {
     // Store a template in the database
     async post_template(apireq) {
         await assert_domain_and_user(apireq);
-        const { template, sender = '', name, subject = '', locale = '' } = apireq.req.body;
+        const body = apireq.req.body;
+        const template = String(body.template ?? '');
+        const sender = String(body.sender ?? '');
+        const name = String(body.name ?? '');
+        const subject = String(body.subject ?? '');
+        const locale = String(body.locale ?? '');
         if (!template) {
             throw new ApiError({ code: 400, message: 'Missing template data' });
         }
@@ -63,7 +68,14 @@ export class MailerAPI extends ApiModule {
     }
     // Send a template using posted arguments.
     async post_send(apireq) {
-        const { name, rcpt, locale = '', vars = {}, replyTo, reply_to, headers } = apireq.req.body;
+        const body = apireq.req.body;
+        const name = String(body.name ?? '');
+        const rcpt = String(body.rcpt ?? '');
+        const locale = String(body.locale ?? '');
+        const vars = body.vars ?? {};
+        const replyTo = body.replyTo;
+        const reply_to = body.reply_to;
+        const headers = body.headers;
         await assert_domain_and_user(apireq);
         if (!name || !rcpt) {
             throw new ApiError({ code: 400, message: 'name/rcpt required' });
@@ -84,10 +96,18 @@ export class MailerAPI extends ApiModule {
         }
         let template = null;
         const domain_id = apireq.domain.domain_id;
+        const deflocale = apireq.domain.locale || '';
         try {
-            template =
-                (await api_txmail.findOne({ where: { name, domain_id, locale } })) ||
-                    (await api_txmail.findOne({ where: { name, domain_id, locale: '' } }));
+            // 1. Exact locale match
+            template = await api_txmail.findOne({ where: { name, domain_id, locale } });
+            // 2. Domain/user default locale (if different from request locale)
+            if (!template && deflocale && deflocale !== locale) {
+                template = await api_txmail.findOne({ where: { name, domain_id, locale: deflocale } });
+            }
+            // 3. Empty-locale fallback (if not already tried above)
+            if (!template && locale !== '') {
+                template = await api_txmail.findOne({ where: { name, domain_id, locale: '' } });
+            }
         }
         catch (error) {
             throw new ApiError({
@@ -116,7 +136,7 @@ export class MailerAPI extends ApiModule {
             })),
             ...rawFiles.map((file) => ({
                 filename: file.originalname,
-                path: file.path
+                ...(file.buffer ? { content: file.buffer } : { path: file.filepath })
             }))
         ];
         const attachmentMap = {};
@@ -133,6 +153,19 @@ export class MailerAPI extends ApiModule {
                 throw new ApiError({ code: 400, message: 'Invalid reply-to email address' });
             }
         }
+        const ALLOWED_CUSTOM_HEADERS = new Set([
+            'x-mailer',
+            'x-priority',
+            'x-entity-ref-id',
+            'list-unsubscribe',
+            'list-unsubscribe-post',
+            'list-id',
+            'precedence',
+            'references',
+            'in-reply-to',
+            'message-id',
+            'importance'
+        ]);
         let normalizedHeaders;
         if (headers !== undefined) {
             if (!headers || typeof headers !== 'object' || Array.isArray(headers)) {
@@ -143,6 +176,9 @@ export class MailerAPI extends ApiModule {
                 if (typeof value !== 'string') {
                     throw new ApiError({ code: 400, message: `headers.${key} must be a string` });
                 }
+                if (!ALLOWED_CUSTOM_HEADERS.has(key.toLowerCase())) {
+                    throw new ApiError({ code: 400, message: `Header "${key}" is not allowed` });
+                }
                 normalizedHeaders[key] = value;
             }
         }
@@ -162,21 +198,27 @@ export class MailerAPI extends ApiModule {
                 const sendargs = {
                     from: sender,
                     to: recipient,
-                    subject: template.subject || apireq.req.body.subject || '',
+                    subject: template.subject || body.subject || '',
                     html,
                     text,
                     attachments,
                     ...(normalizedReplyTo ? { replyTo: normalizedReplyTo } : {}),
                     ...(normalizedHeaders ? { headers: normalizedHeaders } : {})
                 };
+                if (!this.server.storage.transport) {
+                    throw new ApiError({ code: 503, message: 'Mail transport is not available' });
+                }
                 await this.server.storage.transport.sendMail(sendargs);
             }
             return [200, { Status: 'OK', Message: 'Emails sent successfully' }];
         }
         catch (error) {
+            if (error instanceof ApiError) {
+                throw error;
+            }
             throw new ApiError({
                 code: 500,
-                message: error instanceof Error ? error.message : String(error)
+                message: 'Failed to render or send email'
             });
         }
     }
@@ -186,13 +228,30 @@ export class MailerAPI extends ApiModule {
                 method: 'post',
                 path: '/v1/tx/message',
                 handler: this.post_send.bind(this),
+                // No schema: this route accepts multipart/form-data; Fastify validates request.body
+                // before the multipart parsing hook populates it, so schema required-fields would
+                // reject valid multipart requests. Validation is handled in the route handler.
                 auth: { type: 'yes', req: 'any' }
             },
             {
                 method: 'post',
                 path: '/v1/tx/template',
                 handler: this.post_template.bind(this),
-                auth: { type: 'yes', req: 'any' }
+                auth: { type: 'yes', req: 'any' },
+                schema: {
+                    body: {
+                        type: 'object',
+                        required: ['name', 'template'],
+                        properties: {
+                            name: { type: 'string' },
+                            template: { type: 'string' },
+                            sender: { type: 'string' },
+                            subject: { type: 'string' },
+                            locale: { type: 'string' }
+                        },
+                        additionalProperties: true
+                    }
+                }
             }
         ];
     }

package/dist/esm/index.js

@@ -25,6 +25,8 @@ function buildServerConfig(store, overrides) {
         apiBasePath: normalizeRoute(env.API_BASE_PATH, '/api'),
         swaggerEnabled: env.SWAGGER_ENABLED,
         swaggerPath: env.SWAGGER_PATH,
+        apiKeyEnabled: true,
+        apiKeyPrefix: 'apikey-',
         ...overrides
     };
 }
@@ -71,10 +73,9 @@ export async function createMailMagicServer(overrides = {}, envOverrides = {}) {
         assetMounts.add(`${apiBasePrefix}${assetPrefix}`);
     }
     for (const prefix of assetMounts) {
-        // Express 5 (path-to-regexp v8) requires wildcard params to be named.
-        // Use ApiServer.useExpress() so mounts under `apiBasePath` are installed on the API router
-        // (and remain reachable before the API 404 handler).
-        server.useExpress(`${prefix}/:domain/*path`, assetHandler);
+        // Use ApiServer.useExpress() so mounts under `apiBasePath` are installed before the API
+        // 404 handler. Fastify (find-my-way) requires the wildcard to be an unnamed `*`.
+        server.useExpress(`${prefix}/:domain/*`, assetHandler);
     }
     if (store.vars.ADMIN_ENABLED) {
         await enableAdminFeatures(server, store, adminUiPath);

package/dist/esm/models/form.js

@@ -231,12 +231,11 @@ export async function init_api_form(api_db) {
     return api_form;
 }
 export async function upsert_form(record) {
-    const { user, domain } = await user_and_domain(record.domain_id);
+    const { domain } = await user_and_domain(record.domain_id);
     const dname = normalizeSlug(domain.name);
     const { slug, filename: generatedFilename } = buildFormSlugAndFilename({
         domainName: domain.name,
         domainLocale: domain.locale,
-        userLocale: user.locale,
         idname: record.idname,
         locale: record.locale
     });

package/dist/esm/models/init.js

@@ -67,12 +67,12 @@ async function _load_template(store, filename, pathname, user, domain, locale, t
 }
 export async function loadFormTemplate(store, form) {
     const { user, domain } = await user_and_domain(form.domain_id);
-    const locale = form.locale || domain.locale || user.locale || null;
+    const locale = form.locale || domain.locale || null;
     return _load_template(store, form.filename, '', user, domain, locale, 'form-template');
 }
 export async function loadTxTemplate(store, template) {
     const { user, domain } = await user_and_domain(template.domain_id);
-    const locale = template.locale || domain.locale || user.locale || null;
+    const locale = template.locale || domain.locale || null;
     return _load_template(store, template.filename, '', user, domain, locale, 'tx-template');
 }
 export async function importData(store) {

package/dist/esm/models/txmail.js

@@ -29,10 +29,10 @@ export const api_txmail_schema = z
 export class api_txmail extends Model {
 }
 export async function upsert_txmail(record) {
-    const { user, domain } = await user_and_domain(record.domain_id);
+    const { domain } = await user_and_domain(record.domain_id);
     const dname = normalizeSlug(domain.name);
     const name = normalizeSlug(record.name);
-    const locale = normalizeSlug(record.locale || domain.locale || user.locale || '');
+    const locale = normalizeSlug(record.locale || domain.locale || '');
     if (!record.slug) {
         record.slug = `${dname}${locale ? '-' + locale : ''}-${name}`;
     }
@@ -157,10 +157,10 @@ export async function init_api_txmail(api_db) {
         ]
     });
     api_txmail.addHook('beforeValidate', async (template) => {
-        const { user, domain } = await user_and_domain(template.domain_id);
+        const { domain } = await user_and_domain(template.domain_id);
         const dname = normalizeSlug(domain.name);
         const name = normalizeSlug(template.name);
-        const locale = normalizeSlug(template.locale || domain.locale || user.locale || '');
+        const locale = normalizeSlug(template.locale || domain.locale || '');
         template.slug ||= `${dname}${locale ? '-' + locale : ''}-${name}`;
         if (!template.filename) {
             const parts = [dname, 'tx-template'];

package/dist/esm/models/user.js

@@ -10,7 +10,7 @@ export const api_user_schema = z
     name: z.string().min(1).describe('Display name for the user.'),
     email: z.string().email().describe('User email address.'),
     domain: z.number().int().nonnegative().nullable().optional().describe('Default domain ID for the user.'),
-    locale: z.string().default('').describe('Default locale for the user.')
+    locale: z.string().default('').describe('Reserved. Locale resolution uses the domain locale.')
 })
     .describe('User account record and API credentials.');
 export class api_user extends Model {

package/dist/esm/store/store.d.ts

@@ -4,9 +4,10 @@ import { Sequelize } from 'sequelize';
 import { envOptions } from './envloader.js';
 import type SMTPTransport from 'nodemailer/lib/smtp-transport';
 type UploadedFile = {
-    path: string;
-    filename?: string;
-    destination?: string;
+    fieldname?: string;
+    originalname?: string;
+    filepath?: string;
+    buffer?: Buffer;
 };
 export type MailStoreVars = envConfig<typeof envOptions>;
 type AutoReloadHandle = {

package/dist/esm/store/store.js

@@ -30,14 +30,21 @@ export function enableInitDataAutoReload(ctx, reload) {
     }
     const initDataPath = ctx.config_filename('init-data.json');
     ctx.print_debug('Enabling auto reload of init-data.json');
+    let debounceTimer = null;
     const onChange = () => {
-        ctx.print_debug('Config file changed, reloading...');
-        try {
-            reload();
-        }
-        catch (err) {
-            ctx.print_debug(`Failed to reload config: ${err}`);
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
         }
+        debounceTimer = setTimeout(() => {
+            debounceTimer = null;
+            ctx.print_debug('Config file changed, reloading...');
+            try {
+                reload();
+            }
+            catch (err) {
+                ctx.print_debug(`Failed to reload config: ${err}`);
+            }
+        }, 300);
     };
     try {
         const watcher = fs.watch(initDataPath, { persistent: false }, onChange);
@@ -102,24 +109,28 @@ export class mailStore {
         }
         await fs.promises.mkdir(targetDir, { recursive: true });
         await Promise.all(files.map(async (file) => {
-            if (!file?.path) {
+            const name = (file.originalname ?? file.filepath) ? path.basename(file.filepath ?? file.originalname ?? '') : '';
+            if (!name) {
                 return;
             }
-            const basename = path.basename(file.path);
-            const destination = path.join(targetDir, basename);
-            if (destination === file.path) {
-                return;
+            const destination = path.join(targetDir, name);
+            if (file.buffer) {
+                await fs.promises.writeFile(destination, file.buffer);
+                file.filepath = destination;
+                file.buffer = undefined;
             }
-            try {
-                await fs.promises.rename(file.path, destination);
-            }
-            catch {
-                await fs.promises.copyFile(file.path, destination);
-                await fs.promises.unlink(file.path);
-            }
-            file.path = destination;
-            if (file.destination !== undefined) {
-                file.destination = targetDir;
+            else if (file.filepath) {
+                if (destination === file.filepath) {
+                    return;
+                }
+                try {
+                    await fs.promises.rename(file.filepath, destination);
+                }
+                catch {
+                    await fs.promises.copyFile(file.filepath, destination);
+                    await fs.promises.unlink(file.filepath);
+                }
+                file.filepath = destination;
             }
         }));
     }

package/dist/esm/swagger.js

@@ -54,8 +54,8 @@ function loadPackagedOpenApiSpec() {
         cachedSpec = JSON.parse(raw);
         return cachedSpec;
     }
-    catch (err) {
-        cachedSpecError = err instanceof Error ? err.message : String(err);
+    catch {
+        cachedSpecError = 'Failed to load OpenAPI spec';
         return null;
     }
 }

package/dist/esm/types.d.ts

@@ -26,7 +26,11 @@ export interface RequestMeta {
     ip_chain: string[];
 }
 export interface UploadedFile {
-    originalname: string;
-    path: string;
     fieldname: string;
+    originalname: string;
+    encoding?: string;
+    mimetype?: string;
+    size?: number;
+    buffer?: Buffer;
+    filepath?: string;
 }

package/dist/esm/util/form-replyto.js

@@ -1,14 +1,5 @@
 import emailAddresses from 'email-addresses';
-function getFirstStringField(body, key) {
-    const value = body[key];
-    if (Array.isArray(value) && value.length > 0) {
-        return String(value[0] ?? '');
-    }
-    if (value !== undefined && value !== null) {
-        return String(value);
-    }
-    return '';
-}
+import { getBodyValue } from './utils.js';
 function sanitizeHeaderValue(value, maxLen) {
     const trimmed = String(value ?? '').trim();
     if (!trimmed) {
@@ -21,7 +12,7 @@ function sanitizeHeaderValue(value, maxLen) {
     return trimmed.slice(0, maxLen);
 }
 export function extractReplyToFromSubmission(body) {
-    const emailRaw = sanitizeHeaderValue(getFirstStringField(body, 'email'), 320);
+    const emailRaw = sanitizeHeaderValue(getBodyValue(body, 'email'), 320);
     if (!emailRaw) {
         return undefined;
     }
@@ -34,10 +25,10 @@ export function extractReplyToFromSubmission(body) {
         return undefined;
     }
     // Prefer a single "name" field, otherwise compose from first_name/last_name.
-    let name = sanitizeHeaderValue(getFirstStringField(body, 'name'), 200);
+    let name = sanitizeHeaderValue(getBodyValue(body, 'name'), 200);
     if (!name) {
-        const first = sanitizeHeaderValue(getFirstStringField(body, 'first_name'), 100);
-        const last = sanitizeHeaderValue(getFirstStringField(body, 'last_name'), 100);
+        const first = sanitizeHeaderValue(getBodyValue(body, 'first_name'), 100);
+        const last = sanitizeHeaderValue(getBodyValue(body, 'last_name'), 100);
         name = sanitizeHeaderValue(`${first}${first && last ? ' ' : ''}${last}`, 200);
     }
     return name ? { name, address } : address;

package/dist/esm/util/forms.js

@@ -1,4 +1,5 @@
 import { ApiError } from '@technomoron/api-server-base';
+import { Op } from 'sequelize';
 import { api_form } from '../models/form.js';
 import { api_recipient } from '../models/recipient.js';
 import { verifyCaptcha } from './captcha.js';
@@ -300,7 +301,6 @@ export function buildFormTemplatePaths(params) {
     return buildFormSlugAndFilename({
         domainName: params.domain.name,
         domainLocale: params.domain.locale,
-        userLocale: params.user.locale,
         idname: params.idname,
         locale: params.locale
     });
@@ -342,22 +342,36 @@ export async function resolveRecipients(form, recipientsRaw) {
     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' });
     }
+    if (recipients.length === 0) {
+        return [];
+    }
+    const scopedMatches = await api_recipient.findAll({
+        where: {
+            domain_id: form.domain_id,
+            form_key: scopeFormKey,
+            idname: { [Op.in]: recipients }
+        }
+    });
+    const scopedByIdname = new Map(scopedMatches.map((entry) => [entry.idname, entry]));
+    const unresolved = recipients.filter((idname) => !scopedByIdname.has(idname));
+    let fallbackByIdname = new Map();
+    if (unresolved.length > 0) {
+        const fallbackMatches = await api_recipient.findAll({
+            where: {
+                domain_id: form.domain_id,
+                form_key: '',
+                idname: { [Op.in]: unresolved }
+            }
+        });
+        fallbackByIdname = new Map(fallbackMatches.map((entry) => [entry.idname, entry]));
+    }
     const resolvedRecipients = [];
     for (const idname of recipients) {
-        const record = await resolveRecipient(idname);
+        const record = scopedByIdname.get(idname) ?? fallbackByIdname.get(idname) ?? null;
         if (!record) {
             throw new ApiError({ code: 404, message: `Unknown recipient identifier "${idname}"` });
         }

package/dist/esm/util/paths.d.ts

@@ -4,7 +4,6 @@ export declare function assertSafeRelativePath(filename: string, label: string):
 export declare function buildFormSlugAndFilename(params: {
     domainName: string;
     domainLocale: string;
-    userLocale: string;
     idname: string;
     locale: string;
 }): {

package/dist/esm/util/paths.js

@@ -12,6 +12,9 @@ export function normalizeSubdir(value) {
     }
     const segments = cleaned.split('/').filter(Boolean);
     for (const segment of segments) {
+        if (segment === '..' || segment === '.') {
+            throw new ApiError({ code: 400, message: `Invalid path segment "${segment}"` });
+        }
         if (!SEGMENT_PATTERN.test(segment)) {
             throw new ApiError({ code: 400, message: `Invalid path segment "${segment}"` });
         }
@@ -31,7 +34,7 @@ export function assertSafeRelativePath(filename, label) {
 export function buildFormSlugAndFilename(params) {
     const domainSlug = normalizeSlug(params.domainName);
     const formSlug = normalizeSlug(params.idname);
-    const localeSlug = normalizeSlug(params.locale || params.domainLocale || params.userLocale || '');
+    const localeSlug = normalizeSlug(params.locale || params.domainLocale || '');
     const slug = `${domainSlug}${localeSlug ? '-' + localeSlug : ''}-${formSlug}`;
     const filenameParts = [domainSlug, 'form-template'];
     if (localeSlug) {

package/dist/esm/util/ratelimit.d.ts

@@ -1,15 +1,6 @@
-import { ApiRequest } from '@technomoron/api-server-base';
-export type RateLimitDecision = {
-    allowed: boolean;
-    retryAfterSec: number;
-};
-export declare class FixedWindowRateLimiter {
-    private readonly maxKeys;
-    private readonly buckets;
-    constructor(maxKeys?: number);
-    check(key: string, max: number, windowMs: number): RateLimitDecision;
-    private prune;
-}
+import { ApiRequest, FixedWindowRateLimiter } from '@technomoron/api-server-base';
+export { FixedWindowRateLimiter };
+export type { RateLimitDecision } from '@technomoron/api-server-base';
 export declare function enforceFormRateLimit(limiter: FixedWindowRateLimiter, env: {
     FORM_RATE_LIMIT_WINDOW_SEC: number;
     FORM_RATE_LIMIT_MAX: number;

package/dist/esm/util/ratelimit.js

@@ -1,42 +1,5 @@
-import { ApiError } from '@technomoron/api-server-base';
-export class FixedWindowRateLimiter {
-    maxKeys;
-    buckets = new Map();
-    constructor(maxKeys = 10_000) {
-        this.maxKeys = maxKeys;
-    }
-    check(key, max, windowMs) {
-        if (!key || max <= 0 || windowMs <= 0) {
-            return { allowed: true, retryAfterSec: 0 };
-        }
-        const now = Date.now();
-        const bucket = this.buckets.get(key);
-        if (!bucket || now - bucket.windowStartMs >= windowMs) {
-            this.buckets.delete(key);
-            this.buckets.set(key, { windowStartMs: now, count: 1 });
-            this.prune();
-            return { allowed: true, retryAfterSec: 0 };
-        }
-        bucket.count += 1;
-        // Refresh insertion order to keep active entries at the end for pruning.
-        this.buckets.delete(key);
-        this.buckets.set(key, bucket);
-        if (bucket.count <= max) {
-            return { allowed: true, retryAfterSec: 0 };
-        }
-        const retryAfterSec = Math.max(1, Math.ceil((bucket.windowStartMs + windowMs - now) / 1000));
-        return { allowed: false, retryAfterSec };
-    }
-    prune() {
-        while (this.buckets.size > this.maxKeys) {
-            const oldest = this.buckets.keys().next().value;
-            if (!oldest) {
-                break;
-            }
-            this.buckets.delete(oldest);
-        }
-    }
-}
+import { ApiError, FixedWindowRateLimiter } from '@technomoron/api-server-base';
+export { FixedWindowRateLimiter };
 export function enforceFormRateLimit(limiter, env, apireq) {
     const clientIp = apireq.getClientIp() ?? '';
     if (!clientIp) {
@@ -47,7 +10,8 @@ export function enforceFormRateLimit(limiter, env, apireq) {
     const windowMs = Math.max(0, env.FORM_RATE_LIMIT_WINDOW_SEC) * 1000;
     const decision = limiter.check(`form-message:${clientIp}`, env.FORM_RATE_LIMIT_MAX, windowMs);
     if (!decision.allowed) {
-        apireq.res.set('Retry-After', String(decision.retryAfterSec));
+        const fastifyReply = apireq.res.reply;
+        fastifyReply?.header('retry-after', String(decision.retryAfterSec));
         throw new ApiError({ code: 429, message: 'Too many form submissions; try again later' });
     }
 }

package/dist/esm/util/uploads.d.ts

@@ -2,7 +2,8 @@ import type { UploadedFile } from '../types.js';
 export declare function buildAttachments(rawFiles: UploadedFile[]): {
     attachments: Array<{
         filename: string;
-        path: string;
+        path?: string;
+        content?: Buffer;
     }>;
     attachmentMap: Record<string, string>;
 };

package/dist/esm/util/uploads.js

@@ -5,7 +5,7 @@ import { SEGMENT_PATTERN } from './paths.js';
 export function buildAttachments(rawFiles) {
     const attachments = rawFiles.map((file) => ({
         filename: file.originalname,
-        path: file.path
+        ...(file.buffer ? { content: file.buffer } : { path: file.filepath })
     }));
     const attachmentMap = {};
     for (const file of rawFiles) {
@@ -15,11 +15,11 @@ export function buildAttachments(rawFiles) {
 }
 export async function cleanupUploadedFiles(files) {
     await Promise.all(files.map(async (file) => {
-        if (!file?.path) {
+        if (!file?.filepath) {
             return;
         }
         try {
-            await fs.promises.unlink(file.path);
+            await fs.promises.unlink(file.filepath);
         }
         catch {
             // best effort cleanup
@@ -34,15 +34,20 @@ export async function moveUploadedFiles(files, targetDir) {
             throw new ApiError({ code: 400, message: `Invalid filename "${file.originalname}"` });
         }
         const destination = path.join(targetDir, filename);
-        if (destination === file.path) {
-            continue;
+        if (file.buffer) {
+            await fs.promises.writeFile(destination, file.buffer);
         }
-        try {
-            await fs.promises.rename(file.path, destination);
-        }
-        catch {
-            await fs.promises.copyFile(file.path, destination);
-            await fs.promises.unlink(file.path);
+        else if (file.filepath) {
+            if (destination === file.filepath) {
+                continue;
+            }
+            try {
+                await fs.promises.rename(file.filepath, destination);
+            }
+            catch {
+                await fs.promises.copyFile(file.filepath, destination);
+                await fs.promises.unlink(file.filepath);
+            }
         }
     }
 }

package/dist/esm/util/utils.d.ts

@@ -1,7 +1,6 @@
 import { api_domain } from '../models/domain.js';
 import { api_user } from '../models/user.js';
 import type { RequestMeta } from '../types.js';
-import type { Response } from 'express';
 /**
  * Normalize a string into a safe identifier for slugs, filenames, etc.
  *
@@ -24,4 +23,3 @@ export declare function buildRequestMeta(rawReq: unknown): RequestMeta;
 export declare function decodeComponent(value: string | string[] | undefined): string;
 export declare function getBodyValue(body: Record<string, unknown>, ...keys: string[]): string;
 export declare function normalizeBoolean(value: unknown): boolean;
-export declare function sendFileAsync(res: Pick<Response, 'sendFile'>, file: string, options?: Parameters<Response['sendFile']>[1]): Promise<void>;

package/dist/esm/util/utils.js

@@ -131,21 +131,3 @@ export function normalizeBoolean(value) {
         .toLowerCase();
     return ['true', '1', 'yes', 'on'].includes(normalized);
 }
-export function sendFileAsync(res, file, options) {
-    return new Promise((resolve, reject) => {
-        const cb = (err) => {
-            if (err) {
-                reject(err instanceof Error ? err : new Error(String(err)));
-            }
-            else {
-                resolve();
-            }
-        };
-        if (options !== undefined) {
-            // Express will set Cache-Control based on `maxAge` etc; callers can still override.
-            res.sendFile(file, options, cb);
-            return;
-        }
-        res.sendFile(file, cb);
-    });
-}

package/docs/swagger/openapi.json

@@ -2,7 +2,7 @@
 	"openapi": "3.1.0",
 	"info": {
 		"title": "Mail Magic API",
-		"version": "1.0.41",
+		"version": "1.0.42",
 		"description": "OpenAPI definition for the Mail Magic server. Authenticated endpoints require an API key provided as `Authorization: Bearer apikey-<token>`."
 	},
 	"servers": [

package/docs/tutorial.md

@@ -264,7 +264,7 @@ Create `${CONFIG_ROOT}/init-data.json` so the service can bootstrap the MyOrg us
         <tr>
           <td style="padding:16px 24px;background:#f9fafb;color:#4b5563;font-size:12px;">
             <strong>Sender IP:</strong> {{ _meta_.client_ip | default('unknown') }} ·
-            <strong>Received at:</strong> {{ _meta_.received_at | default(now().iso8601()) }}
+            <strong>Received at:</strong> {{ _meta_.received_at | default('unknown') }}
           </td>
         </tr>
         {% endif %}

package/examples/README.md

@@ -1,7 +1,7 @@
 # Mail Magic Examples
 
-The canonical example setup for Mail Magic. Shipped inside the `@technomoron/mail-magic` package so it is
-accessible without a private repo clone:
+The canonical example setup for Mail Magic. Shipped inside the `@technomoron/mail-magic` package so it is accessible
+without a private repo clone:
 
 ```bash
 ls node_modules/@technomoron/mail-magic/examples/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@technomoron/mail-magic",
-  "version": "1.0.41",
+  "version": "1.0.43",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "type": "module",
@@ -34,7 +34,7 @@
     "url": "https://github.com/technomoron/mail-magic/issues"
   },
   "dependencies": {
-    "@technomoron/api-server-base": "2.0.0-beta.20",
+    "@technomoron/api-server-base": "2.0.0-beta.24",
     "@technomoron/env-loader": "^1.0.8",
     "@technomoron/unyuck": "^1.0.4",
     "bcryptjs": "^3.0.2",