@technomoron/mail-magic 1.0.32 → 1.0.34

package/dist/models/user.js

@@ -1,16 +1,20 @@
 import { createHmac } from 'node:crypto';
 import { Model, DataTypes, Op } from 'sequelize';
 import { z } from 'zod';
-export const api_user_schema = z.object({
-    user_id: z.number().int().nonnegative(),
-    idname: z.string().min(1),
-    token: z.string().min(1).optional(),
-    token_hmac: z.string().min(1).optional(),
-    name: z.string().min(1),
-    email: z.string().email(),
-    domain: z.number().int().nonnegative().nullable().optional(),
-    locale: z.string().default('')
-});
+export const api_user_schema = z
+    .object({
+    user_id: z.number().int().nonnegative().describe('Database primary key for the user record.'),
+    idname: z.string().min(1).describe('User identifier (slug-like).'),
+    token: z.string().min(1).optional().describe('Legacy API token (may be blank after migration).'),
+    token_hmac: z.string().min(1).optional().describe('API token digest (HMAC).'),
+    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.')
+})
+    .describe('User account record and API credentials.');
+// Sequelize typing pattern: merge the Zod-inferred attribute type onto the model instance type.
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class api_user extends Model {
 }
 export function apiTokenToHmac(token, pepper) {

package/dist/server.js

@@ -10,7 +10,7 @@ export class mailApiServer extends ApiServer {
     }
     async getApiKey(token) {
         this.storage.print_debug('Looking up api key');
-        const pepper = this.storage.env.API_TOKEN_PEPPER;
+        const pepper = this.storage.vars.API_TOKEN_PEPPER;
         const token_hmac = apiTokenToHmac(token, pepper);
         const user = await api_user.findOne({ where: { token_hmac } });
         if (user) {

package/dist/store/store.js

@@ -5,20 +5,20 @@ import { createTransport } from 'nodemailer';
 import { connect_api_db } from '../models/db.js';
 import { importData } from '../models/init.js';
 import { envOptions } from './envloader.js';
-function create_mail_transport(env) {
+function create_mail_transport(vars) {
     const args = {
-        host: env.SMTP_HOST,
-        port: env.SMTP_PORT,
-        secure: env.SMTP_SECURE,
+        host: vars.SMTP_HOST,
+        port: vars.SMTP_PORT,
+        secure: vars.SMTP_SECURE,
         tls: {
-            rejectUnauthorized: env.SMTP_TLS_REJECT
+            rejectUnauthorized: vars.SMTP_TLS_REJECT
         },
         requireTLS: true,
-        logger: env.DEBUG,
-        debug: env.DEBUG
+        logger: vars.DEBUG,
+        debug: vars.DEBUG
     };
-    const user = env.SMTP_USER;
-    const pass = env.SMTP_PASSWORD;
+    const user = vars.SMTP_USER;
+    const pass = vars.SMTP_PASSWORD;
     if (user && pass) {
         args.auth = { user, pass };
     }
@@ -33,6 +33,7 @@ function create_mail_transport(env) {
 }
 export class mailStore {
     env;
+    vars;
     transport;
     api_db = null;
     keys = {};
@@ -41,7 +42,7 @@ export class mailStore {
     uploadTemplate;
     uploadStagingPath;
     print_debug(msg) {
-        if (this.env.DEBUG) {
+        if (this.vars.DEBUG) {
             console.log(msg);
         }
     }
@@ -49,7 +50,7 @@ export class mailStore {
         return path.resolve(path.join(this.configpath, name));
     }
     resolveUploadPath(domainName) {
-        const raw = this.env.UPLOAD_PATH ?? '';
+        const raw = this.vars.UPLOAD_PATH ?? '';
         const hasDomainToken = raw.includes('{domain}');
         const expanded = hasDomainToken && domainName ? raw.replaceAll('{domain}', domainName) : raw;
         if (!expanded) {
@@ -62,7 +63,7 @@ export class mailStore {
         return path.resolve(base, expanded);
     }
     getUploadStagingPath() {
-        if (!this.env.UPLOAD_PATH) {
+        if (!this.vars.UPLOAD_PATH) {
             return '';
         }
         if (this.uploadTemplate) {
@@ -112,23 +113,53 @@ export class mailStore {
         this.print_debug(`No api-keys.json file found: tried ${keyfile}`);
         return {};
     }
-    async init() {
+    async init(overrides = {}) {
         // Load env config only via EnvLoader + envOptions (avoid ad-hoc `process.env` parsing here).
         // If DEBUG is enabled, re-load with EnvLoader debug output enabled.
-        let env = await EnvLoader.createConfigProxy(envOptions, { debug: false });
-        if (env.DEBUG) {
-            env = await EnvLoader.createConfigProxy(envOptions, { debug: true });
+        const overrideEntries = Object.entries(overrides);
+        const envSnapshot = new Map();
+        if (overrideEntries.length > 0) {
+            for (const [key, value] of overrideEntries) {
+                envSnapshot.set(key, process.env[key]);
+                if (value === undefined || value === null) {
+                    delete process.env[key];
+                }
+                else {
+                    process.env[key] = String(value);
+                }
+            }
+        }
+        let env;
+        try {
+            env = await EnvLoader.createConfigProxy(envOptions, { debug: false });
+            const debugEnabled = overrides.DEBUG ?? env.DEBUG;
+            if (debugEnabled) {
+                env = await EnvLoader.createConfigProxy(envOptions, { debug: true });
+            }
+        }
+        finally {
+            if (envSnapshot.size > 0) {
+                for (const [key, value] of envSnapshot.entries()) {
+                    if (value === undefined) {
+                        delete process.env[key];
+                    }
+                    else {
+                        process.env[key] = value;
+                    }
+                }
+            }
         }
         this.env = env;
-        if (this.env.FORM_CAPTCHA_REQUIRED && !String(this.env.FORM_CAPTCHA_SECRET ?? '').trim()) {
+        this.vars = { ...env, ...overrides };
+        if (this.vars.FORM_CAPTCHA_REQUIRED && !String(this.vars.FORM_CAPTCHA_SECRET ?? '').trim()) {
             throw new Error('FORM_CAPTCHA_SECRET must be set when FORM_CAPTCHA_REQUIRED=true');
         }
         EnvLoader.genTemplate(envOptions, '.env-dist');
-        const p = env.CONFIG_PATH;
+        const p = this.vars.CONFIG_PATH;
         this.configpath = path.isAbsolute(p) ? p : path.resolve(process.cwd(), p);
         console.log(`Config path is ${this.configpath}`);
-        if (env.UPLOAD_PATH && env.UPLOAD_PATH.includes('{domain}')) {
-            this.uploadTemplate = env.UPLOAD_PATH;
+        if (this.vars.UPLOAD_PATH && this.vars.UPLOAD_PATH.includes('{domain}')) {
+            this.uploadTemplate = this.vars.UPLOAD_PATH;
             this.uploadStagingPath = path.resolve(this.configpath, '_uploads');
             try {
                 fs.mkdirSync(this.uploadStagingPath, { recursive: true });
@@ -138,9 +169,9 @@ export class mailStore {
             }
         }
         // this.keys = await this.load_api_keys(this.configpath);
-        this.transport = await create_mail_transport(env);
+        this.transport = await create_mail_transport(this.vars);
         this.api_db = await connect_api_db(this);
-        if (this.env.DB_AUTO_RELOAD) {
+        if (this.vars.DB_AUTO_RELOAD) {
             this.print_debug('Enabling auto reload of init-data.json');
             fs.watchFile(this.config_filename('init-data.json'), { interval: 2000 }, () => {
                 this.print_debug('Config file changed, reloading...');

package/dist/swagger.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function normalizeRoute(value, fallback = '') {
+    if (!value) {
+        return fallback;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return fallback;
+    }
+    const withLeading = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    if (withLeading === '/') {
+        return withLeading;
+    }
+    return withLeading.replace(/\/+$/, '');
+}
+function replacePrefix(input, from, to) {
+    if (input === from) {
+        return to;
+    }
+    if (input.startsWith(`${from}/`)) {
+        const suffix = input.slice(from.length);
+        if (to === '/') {
+            return suffix.replace(/^\/+/, '/') || '/';
+        }
+        return `${to}${suffix}`;
+    }
+    return input;
+}
+function rewriteSpecForRuntime(spec, opts) {
+    if (!spec || typeof spec !== 'object') {
+        return spec;
+    }
+    const base = normalizeRoute(opts.apiBasePath, '/api');
+    const asset = normalizeRoute(opts.assetRoute, '/asset');
+    const root = spec;
+    const out = { ...root };
+    // Keep the spec stable while still reflecting the configured public URL and base paths.
+    out.servers = [{ url: String(opts.apiUrl || ''), description: 'Configured API_URL' }];
+    const rawPaths = root.paths;
+    if (!rawPaths || typeof rawPaths !== 'object') {
+        return out;
+    }
+    const rewritten = {};
+    for (const [p, v] of Object.entries(rawPaths)) {
+        let next = String(p);
+        next = replacePrefix(next, '/api', base);
+        next = replacePrefix(next, '/asset', asset);
+        // Normalize double slashes after prefix replacement (path only, not URLs).
+        next = next.replace(/\/{2,}/g, '/');
+        rewritten[next] = v;
+    }
+    out.paths = rewritten;
+    return out;
+}
+let cachedSpec = null;
+let cachedSpecError = null;
+function loadPackagedOpenApiSpec() {
+    if (cachedSpec || cachedSpecError) {
+        return cachedSpec;
+    }
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const candidate = path.resolve(here, '../docs/swagger/openapi.json');
+        const raw = fs.readFileSync(candidate, 'utf8');
+        cachedSpec = JSON.parse(raw);
+        return cachedSpec;
+    }
+    catch (err) {
+        cachedSpecError = err instanceof Error ? err.message : String(err);
+        return null;
+    }
+}
+export function installMailMagicSwagger(server, opts) {
+    const rawPath = typeof opts.swaggerPath === 'string' ? opts.swaggerPath.trim() : '';
+    const enabled = Boolean(opts.swaggerEnabled) || rawPath.length > 0;
+    if (!enabled) {
+        return;
+    }
+    const base = normalizeRoute(opts.apiBasePath, '/api');
+    const resolved = rawPath.length > 0 ? rawPath : `${base}/swagger`;
+    const mount = normalizeRoute(resolved, `${base}/swagger`);
+    // Mount under the API router so it runs before the API 404 handler.
+    server.useExpress(mount, (req, res, next) => {
+        if (req.method && req.method !== 'GET' && req.method !== 'HEAD') {
+            next();
+            return;
+        }
+        const spec = loadPackagedOpenApiSpec();
+        if (!spec) {
+            res.status(500).json({
+                success: false,
+                code: 500,
+                message: `Swagger spec is unavailable${cachedSpecError ? `: ${cachedSpecError}` : ''}`,
+                data: null,
+                errors: {}
+            });
+            return;
+        }
+        res.status(200).json(rewriteSpecForRuntime(spec, {
+            apiBasePath: base,
+            assetRoute: opts.assetRoute,
+            apiUrl: opts.apiUrl
+        }));
+    });
+}

package/dist/util/captcha.js

@@ -0,0 +1,24 @@
+export async function verifyCaptcha(params) {
+    const endpoints = {
+        turnstile: 'https://challenges.cloudflare.com/turnstile/v0/siteverify',
+        hcaptcha: 'https://hcaptcha.com/siteverify',
+        recaptcha: 'https://www.google.com/recaptcha/api/siteverify'
+    };
+    const endpoint = endpoints[params.provider] ?? endpoints.turnstile;
+    const body = new URLSearchParams();
+    body.set('secret', params.secret);
+    body.set('response', params.token);
+    if (params.remoteip) {
+        body.set('remoteip', params.remoteip);
+    }
+    const res = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body
+    });
+    if (!res.ok) {
+        return false;
+    }
+    const data = (await res.json().catch(() => null));
+    return Boolean(data?.success);
+}

package/dist/util/email.js

@@ -0,0 +1,19 @@
+import emailAddresses from 'email-addresses';
+export function validateEmail(email) {
+    const parsed = emailAddresses.parseOneAddress(email);
+    if (parsed) {
+        return parsed.address;
+    }
+    return undefined;
+}
+export function parseMailbox(value) {
+    const parsed = emailAddresses.parseOneAddress(value);
+    if (!parsed) {
+        return undefined;
+    }
+    const mailbox = parsed;
+    if (!mailbox?.address) {
+        return undefined;
+    }
+    return mailbox;
+}

package/dist/util/form-replyto.js

@@ -0,0 +1,44 @@
+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 '';
+}
+function sanitizeHeaderValue(value, maxLen) {
+    const trimmed = String(value ?? '').trim();
+    if (!trimmed) {
+        return '';
+    }
+    // Prevent header injection.
+    if (/[\r\n]/.test(trimmed)) {
+        return '';
+    }
+    return trimmed.slice(0, maxLen);
+}
+export function extractReplyToFromSubmission(body) {
+    const emailRaw = sanitizeHeaderValue(getFirstStringField(body, 'email'), 320);
+    if (!emailRaw) {
+        return undefined;
+    }
+    const parsed = emailAddresses.parseOneAddress(emailRaw);
+    if (!parsed) {
+        return undefined;
+    }
+    const address = sanitizeHeaderValue(parsed?.address, 320);
+    if (!address) {
+        return undefined;
+    }
+    // Prefer a single "name" field, otherwise compose from first_name/last_name.
+    let name = sanitizeHeaderValue(getFirstStringField(body, 'name'), 200);
+    if (!name) {
+        const first = sanitizeHeaderValue(getFirstStringField(body, 'first_name'), 100);
+        const last = sanitizeHeaderValue(getFirstStringField(body, 'last_name'), 100);
+        name = sanitizeHeaderValue(`${first}${first && last ? ' ' : ''}${last}`, 200);
+    }
+    return name ? { name, address } : address;
+}

package/dist/util/form-submission.js

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+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)) {
+        return {};
+    }
+    return input;
+}
+function getCaptchaTokenFromBody(body) {
+    return getBodyValue(body, 'cf-turnstile-response', 'h-captcha-response', 'g-recaptcha-response', 'captcha');
+}
+const optionalStringish = z.union([z.string(), z.array(z.string())]).optional();
+// Public form submission payload schema.
+// - Validates/normalizes system fields under the `_mm_*` namespace.
+// - Allows arbitrary non-system fields through (exposed to templates as `_fields_`).
+// - Rejects unknown `_mm_*` keys (except `_mm_file*` attachment field names).
+export const form_submission_schema = z
+    .object({
+    _mm_form_key: z
+        .string()
+        .min(1)
+        .describe('Required. Public form key identifying which form configuration to use.'),
+    _mm_locale: z
+        .string()
+        .optional()
+        .default('')
+        .describe('Optional locale hint used when rendering and for recipient resolution.'),
+    _mm_recipients: z
+        .union([z.string(), z.array(z.string())])
+        .optional()
+        .describe('Optional list of recipient idnames (array) or comma-separated string. Recipients are resolved server-side.'),
+    // Common fields used to derive Reply-To (optional; no defaults).
+    email: optionalStringish.describe('Optional submitter email used to derive Reply-To.'),
+    name: optionalStringish.describe('Optional submitter name used to derive Reply-To.'),
+    first_name: optionalStringish.describe('Optional submitter first name used to derive Reply-To.'),
+    last_name: optionalStringish.describe('Optional submitter last name used to derive Reply-To.'),
+    // Provider-native CAPTCHA token field names (accepted as-is; not part of the `_mm_*` namespace).
+    'cf-turnstile-response': optionalStringish.describe('Cloudflare Turnstile token (accepted as-is).'),
+    'h-captcha-response': optionalStringish.describe('hCaptcha token (accepted as-is).'),
+    'g-recaptcha-response': optionalStringish.describe('Google reCAPTCHA token (accepted as-is).'),
+    captcha: optionalStringish.describe('Generic/legacy captcha token field (accepted as-is).')
+})
+    .passthrough()
+    .superRefine((obj, ctx) => {
+    for (const key of Object.keys(obj)) {
+        if (!key.startsWith('_mm_')) {
+            continue;
+        }
+        if (key.startsWith('_mm_file')) {
+            // Files arrive in req.files, but allow clients to pass harmless metadata fields.
+            continue;
+        }
+        if (!ALLOWED_MM_KEYS.has(key)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Unknown system field "${key}"`
+            });
+        }
+    }
+})
+    .describe('Public form submission payload. System fields must be `_mm_*`. All other fields are treated as user fields and exposed to templates as `_fields_`.');
+export function parseFormSubmissionInput(raw) {
+    const body = asRecord(raw);
+    // Enforce that system params are _mm_* only (except provider captcha fields).
+    // We intentionally do not accept non-_mm aliases for system params.
+    const mm_form_key = getBodyValue(body, '_mm_form_key');
+    const mm_locale = getBodyValue(body, '_mm_locale');
+    const mm_recipients = body._mm_recipients;
+    const mm_captcha_token = getCaptchaTokenFromBody(body);
+    const parsed = form_submission_schema.parse({
+        ...body,
+        _mm_form_key: mm_form_key,
+        _mm_locale: mm_locale,
+        _mm_recipients: mm_recipients
+    });
+    const { _mm_form_key, _mm_locale, _mm_recipients, ...rest } = parsed;
+    // Expose non-system fields to templates. Keep all non-`_mm_*` keys verbatim.
+    const fields = {};
+    for (const [key, value] of Object.entries(rest)) {
+        if (key.startsWith('_mm_')) {
+            continue;
+        }
+        fields[key] = value;
+    }
+    return {
+        mm: {
+            form_key: _mm_form_key,
+            locale: _mm_locale,
+            captcha_token: mm_captcha_token,
+            recipients_raw: _mm_recipients
+        },
+        fields
+    };
+}