@technomoron/mail-magic 1.0.42 → 1.0.44

package/CHANGES

@@ -1,12 +1,33 @@
 CHANGES
 =======
 
-Unreleased (2026-02-27)
-
-- chore(release): prepare release metadata for server package.
+Version 1.0.44 (2026-03-05)
+
+- fix(autoreload): catch unhandled promise rejections from async `reload()` in `enableInitDataAutoReload` `onChange` callback.
+- fix(mailer): validate that parsed `vars` is a non-null, non-array object after `JSON.parse`; return 400 for invalid types.
+- docs(utils): add doc comment to `buildRequestMeta` clarifying it is informational and requires a trusted reverse proxy for reliable IP data.
+- (Changes generated/assisted by Claude Code (profile: anthropic-claude-opus-4-6/high).)
+
+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)
 

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.js

@@ -47,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,
@@ -65,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,

package/dist/esm/api/auth.js

@@ -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

@@ -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);
             }

package/dist/esm/api/mailer.js

@@ -89,6 +89,9 @@ export class MailerAPI extends ApiModule {
                 throw new ApiError({ code: 400, message: 'Invalid JSON provided in "vars"' });
             }
         }
+        if (!parsedVars || typeof parsedVars !== 'object' || Array.isArray(parsedVars)) {
+            throw new ApiError({ code: 400, message: '"vars" must be a JSON object' });
+        }
         const thevars = parsedVars;
         const { valid, invalid } = this.validateEmails(rcpt);
         if (invalid.length > 0) {
@@ -96,10 +99,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({
@@ -145,6 +156,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)) {
@@ -155,6 +179,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;
             }
         }
@@ -181,14 +208,20 @@ export class MailerAPI extends ApiModule {
                     ...(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'
             });
         }
     }

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

@@ -18,7 +18,7 @@ type AutoReloadContext = {
     config_filename: (name: string) => string;
     print_debug: (msg: string) => void;
 };
-export declare function enableInitDataAutoReload(ctx: AutoReloadContext, reload: () => void): AutoReloadHandle | null;
+export declare function enableInitDataAutoReload(ctx: AutoReloadContext, reload: () => void | Promise<void>): AutoReloadHandle | null;
 export declare class mailStore {
     private env;
     vars: MailStoreVars;

package/dist/esm/store/store.js

@@ -30,14 +30,25 @@ 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...');
+            // reload() may be sync or async — try/catch handles a synchronous
+            // throw, while Promise.resolve().catch() handles an async rejection.
+            try {
+                Promise.resolve(reload()).catch((err) => {
+                    ctx.print_debug(`Failed to reload config: ${err}`);
+                });
+            }
+            catch (err) {
+                ctx.print_debug(`Failed to reload config: ${err}`);
+            }
+        }, 300);
     };
     try {
         const watcher = fs.watch(initDataPath, { persistent: false }, onChange);

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/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

@@ -301,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
     });

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/utils.d.ts

@@ -19,6 +19,13 @@ export declare function user_and_domain(domain_id: number): Promise<{
     user: api_user;
     domain: api_domain;
 }>;
+/**
+ * Collect informational request metadata (client IP, IP chain, timestamp) for
+ * use in template rendering context.  The values are **not** used for security
+ * decisions such as rate limiting — those rely on `getClientIp()` which is
+ * trust-proxy aware.  For the IP chain to be meaningful the server must sit
+ * behind a trusted reverse proxy that sets the forwarded headers.
+ */
 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;

package/dist/esm/util/utils.js

@@ -60,6 +60,13 @@ function resolveHeader(headers, key) {
     }
     return undefined;
 }
+/**
+ * Collect informational request metadata (client IP, IP chain, timestamp) for
+ * use in template rendering context.  The values are **not** used for security
+ * decisions such as rate limiting — those rely on `getClientIp()` which is
+ * trust-proxy aware.  For the IP chain to be meaningful the server must sit
+ * behind a trusted reverse proxy that sets the forwarded headers.
+ */
 export function buildRequestMeta(rawReq) {
     const req = (rawReq ?? {});
     const headers = req.headers ?? {};

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@technomoron/mail-magic",
-  "version": "1.0.42",
+  "version": "1.0.44",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "type": "module",