@technomoron/mail-magic 1.0.16 → 1.0.23

package/dist/index.js

@@ -4,6 +4,7 @@ import { FormAPI } from './api/forms.js';
 import { MailerAPI } from './api/mailer.js';
 import { mailApiServer } from './server.js';
 import { mailStore } from './store/store.js';
+const DOMAIN_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
 function normalizeRoute(value, fallback = '') {
     if (!value) {
         return fallback;
@@ -18,12 +19,20 @@ function normalizeRoute(value, fallback = '') {
     }
     return withLeading.replace(/\/+$/, '');
 }
+function mergeStaticDirs(base, override) {
+    const merged = { ...base, ...(override ?? {}) };
+    if (Object.keys(merged).length === 0) {
+        return undefined;
+    }
+    return merged;
+}
 function buildServerConfig(store, overrides) {
     const env = store.env;
     return {
         apiHost: env.API_HOST,
         apiPort: env.API_PORT,
         uploadPath: store.getUploadStagingPath(),
+        uploadMax: env.UPLOAD_MAX,
         debug: env.DEBUG,
         apiBasePath: normalizeRoute(env.API_BASE_PATH, '/api'),
         swaggerEnabled: env.SWAGGER_ENABLED,
@@ -36,11 +45,40 @@ export async function createMailMagicServer(overrides = {}) {
     if (typeof overrides.apiBasePath === 'string') {
         store.env.API_BASE_PATH = overrides.apiBasePath;
     }
-    const config = buildServerConfig(store, overrides);
+    const baseStaticDirs = {};
+    let adminUiPath = null;
+    if (store.env.ADMIN_ENABLED) {
+        adminUiPath = await resolveAdminUiPath(store);
+        if (adminUiPath) {
+            baseStaticDirs['/'] = adminUiPath;
+        }
+    }
+    const mergedOverrides = {
+        ...overrides,
+        staticDirs: mergeStaticDirs(baseStaticDirs, overrides.staticDirs)
+    };
+    const config = buildServerConfig(store, mergedOverrides);
     const server = new mailApiServer(config, store).api(new MailerAPI()).api(new FormAPI()).api(new AssetAPI());
-    mountAssetRoute(server, store);
+    // Serve domain assets from a public route with traversal protection and caching.
+    const assetRoute = normalizeRoute(store.env.ASSET_ROUTE, '/asset');
+    const assetPrefix = assetRoute === '/' ? '' : assetRoute;
+    const apiBasePath = normalizeRoute(store.env.API_BASE_PATH, '/api');
+    const apiBasePrefix = apiBasePath === '/' ? '' : apiBasePath;
+    const assetHandler = createAssetHandler(server);
+    const assetMounts = new Set();
+    assetMounts.add(assetPrefix);
+    // Integration tests (and API_URL defaults) expect assets to also be reachable under the API base path.
+    if (apiBasePrefix && assetPrefix && !assetPrefix.startsWith(`${apiBasePrefix}/`)) {
+        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);
+    }
     if (store.env.ADMIN_ENABLED) {
-        await enableAdminFeatures(server, store);
+        await enableAdminFeatures(server, store, adminUiPath);
     }
     else {
         store.print_debug('Admin UI/API disabled via ADMIN_ENABLED');
@@ -76,15 +114,28 @@ const isDirectExecution = (() => {
 if (isDirectExecution) {
     void bootMailMagic();
 }
-async function enableAdminFeatures(server, store) {
+async function resolveAdminUiPath(store) {
+    try {
+        const mod = (await import('@technomoron/mail-magic-admin'));
+        if (typeof mod?.resolveAdminDist === 'function') {
+            return mod.resolveAdminDist(store.env.ADMIN_APP_PATH, (message) => store.print_debug(message));
+        }
+    }
+    catch (err) {
+        store.print_debug(`Unable to resolve admin UI path: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return null;
+}
+async function enableAdminFeatures(server, store, adminUiPath) {
     try {
         const mod = (await import('@technomoron/mail-magic-admin'));
         if (typeof mod?.registerAdmin === 'function') {
             await mod.registerAdmin(server, {
                 apiBasePath: normalizeRoute(store.env.API_BASE_PATH, '/api'),
                 assetRoute: normalizeRoute(store.env.ASSET_ROUTE, '/asset'),
-                appPath: store.env.ADMIN_APP_PATH,
-                logger: (message) => store.print_debug(message)
+                appPath: adminUiPath ?? store.env.ADMIN_APP_PATH,
+                logger: (message) => store.print_debug(message),
+                staticFallback: Boolean(adminUiPath)
             });
         }
         else if (mod?.AdminAPI) {
@@ -98,22 +149,3 @@ async function enableAdminFeatures(server, store) {
         store.print_debug(`Unable to load admin module: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-function mountAssetRoute(server, store) {
-    const normalizedRoute = normalizeRoute(store.env.ASSET_ROUTE, '/asset');
-    server.app.get(`${normalizedRoute}/:domain/*`, createAssetHandler(server));
-    ensureApiNotFoundLast(server);
-}
-function ensureApiNotFoundLast(server) {
-    const anyServer = server;
-    const handler = anyServer.apiNotFoundHandler;
-    const stack = anyServer.app?._router?.stack;
-    if (!handler || !Array.isArray(stack)) {
-        return;
-    }
-    const index = stack.findIndex((layer) => layer?.handle === handler);
-    if (index === -1 || index === stack.length - 1) {
-        return;
-    }
-    const [layer] = stack.splice(index, 1);
-    stack.push(layer);
-}

package/dist/models/db.js

@@ -2,13 +2,15 @@ import { Sequelize } from 'sequelize';
 import { init_api_domain, api_domain } from './domain.js';
 import { init_api_form, api_form } from './form.js';
 import { importData } from './init.js';
+import { init_api_recipient, api_recipient } from './recipient.js';
 import { init_api_txmail, api_txmail } from './txmail.js';
-import { init_api_user, api_user } from './user.js';
+import { init_api_user, api_user, migrateLegacyApiTokens } from './user.js';
 export async function init_api_db(db, store) {
     await init_api_user(db);
     await init_api_domain(db);
     await init_api_txmail(db);
     await init_api_form(db);
+    await init_api_recipient(db);
     // User ↔ Domain
     api_user.hasMany(api_domain, {
         foreignKey: 'user_id',
@@ -60,11 +62,29 @@ export async function init_api_db(db, store) {
         foreignKey: 'domain_id',
         as: 'domain'
     });
+    // Domain ↔ Recipient (form recipient allowlist)
+    api_domain.hasMany(api_recipient, {
+        foreignKey: 'domain_id',
+        as: 'recipients'
+    });
+    api_recipient.belongsTo(api_domain, {
+        foreignKey: 'domain_id',
+        as: 'domain'
+    });
     await db.query('PRAGMA foreign_keys = OFF');
     store.print_debug(`Force alter tables: ${store.env.DB_FORCE_SYNC}`);
     await db.sync({ alter: true, force: store.env.DB_FORCE_SYNC });
     await db.query('PRAGMA foreign_keys = ON');
     await importData(store);
+    try {
+        const { migrated, cleared } = await migrateLegacyApiTokens(store.env.API_TOKEN_PEPPER);
+        if (migrated || cleared) {
+            store.print_debug(`Migrated ${migrated} legacy API token(s) and cleared ${cleared} plaintext token(s).`);
+        }
+    }
+    catch (err) {
+        store.print_debug(`Failed to migrate legacy API tokens: ${err instanceof Error ? err.message : String(err)}`);
+    }
     store.print_debug('API Database Initialized...');
 }
 export async function connect_api_db(store) {
@@ -90,7 +110,14 @@ export async function connect_api_db(store) {
         dbparams.username = env.DB_USER;
         dbparams.password = env.DB_PASS;
     }
-    store.print_debug(`Database params are:\n${JSON.stringify(dbparams, undefined, 2)}`);
+    const debugDbParams = { ...dbparams };
+    if (typeof debugDbParams.password === 'string' && debugDbParams.password) {
+        debugDbParams.password = '<redacted>';
+    }
+    if (typeof debugDbParams.username === 'string' && debugDbParams.username) {
+        debugDbParams.username = '<redacted>';
+    }
+    store.print_debug(`Database params are:\n${JSON.stringify(debugDbParams, undefined, 2)}`);
     const db = new Sequelize(dbparams);
     await db.authenticate();
     store.print_debug('API Database Connected');

package/dist/models/form.js

@@ -1,9 +1,11 @@
 import path from 'path';
+import { nanoid } from 'nanoid';
 import { Model, DataTypes } from 'sequelize';
 import { z } from 'zod';
 import { user_and_domain, normalizeSlug } from '../util.js';
 export const api_form_schema = z.object({
     form_id: z.number().int().nonnegative(),
+    form_key: z.string().min(1).nullable().optional(),
     user_id: z.number().int().nonnegative(),
     domain_id: z.number().int().nonnegative(),
     locale: z.string().default(''),
@@ -15,6 +17,7 @@ export const api_form_schema = z.object({
     filename: z.string().default(''),
     slug: z.string().default(''),
     secret: z.string().default(''),
+    captcha_required: z.boolean().default(false),
     files: z
         .array(z.object({
         filename: z.string(),
@@ -33,6 +36,11 @@ export async function init_api_form(api_db) {
             allowNull: false,
             primaryKey: true
         },
+        form_key: {
+            type: DataTypes.STRING,
+            allowNull: true,
+            defaultValue: null
+        },
         user_id: {
             type: DataTypes.INTEGER,
             allowNull: false,
@@ -102,6 +110,11 @@ export async function init_api_form(api_db) {
             allowNull: false,
             defaultValue: ''
         },
+        captcha_required: {
+            type: DataTypes.BOOLEAN,
+            allowNull: false,
+            defaultValue: false
+        },
         files: {
             type: DataTypes.TEXT,
             allowNull: false,
@@ -120,6 +133,10 @@ export async function init_api_form(api_db) {
         charset: 'utf8mb4',
         collate: 'utf8mb4_unicode_ci',
         indexes: [
+            {
+                unique: true,
+                fields: ['form_key']
+            },
             {
                 unique: true,
                 fields: ['user_id', 'domain_id', 'locale', 'idname']
@@ -164,12 +181,16 @@ export async function upsert_form(record) {
     let instance = null;
     instance = await api_form.findByPk(record.form_id);
     if (instance) {
+        if (!instance.form_key && !record.form_key) {
+            record.form_key = nanoid();
+        }
         await instance.update(record);
     }
     else {
-        console.log('CREATE', JSON.stringify(record, undefined, 2));
+        if (!record.form_key) {
+            record.form_key = nanoid();
+        }
         instance = await api_form.create(record);
-        console.log(`INSTANCE IS ${instance}`);
     }
     if (!instance) {
         throw new Error(`Unable to update/create form ${record.form_id}`);

package/dist/models/init.js

@@ -6,7 +6,7 @@ import { user_and_domain } from '../util.js';
 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 { api_user, api_user_schema } from './user.js';
+import { apiTokenToHmac, api_user, api_user_schema } from './user.js';
 const init_data_schema = z.object({
     user: z.array(api_user_schema).default([]),
     domain: z.array(api_domain_schema).default([]),
@@ -143,8 +143,18 @@ export async function importData(store) {
         if (records.user) {
             store.print_debug('Creating user records');
             for (const record of records.user) {
-                const { domain, ...userWithoutDomain } = record;
-                await api_user.upsert({ ...userWithoutDomain, domain: null });
+                const { domain, token, token_hmac, ...userWithoutDomain } = record;
+                let resolvedTokenHmac;
+                if (typeof token_hmac === 'string' && token_hmac) {
+                    resolvedTokenHmac = token_hmac;
+                }
+                else if (typeof token === 'string' && token) {
+                    resolvedTokenHmac = apiTokenToHmac(token, store.env.API_TOKEN_PEPPER);
+                }
+                else {
+                    throw new Error(`User ${record.user_id} is missing token or token_hmac`);
+                }
+                await api_user.upsert({ ...userWithoutDomain, token: '', token_hmac: resolvedTokenHmac, domain: null });
                 if (typeof domain === 'number') {
                     pendingUserDomains.push({ user_id: record.user_id, domain });
                 }

package/dist/models/recipient.js

@@ -0,0 +1,65 @@
+import { Model, DataTypes } from 'sequelize';
+import { z } from 'zod';
+export const api_recipient_schema = z.object({
+    recipient_id: z.number().int().nonnegative(),
+    domain_id: z.number().int().nonnegative(),
+    // Empty string means "domain-wide"; otherwise scope to a specific form_key.
+    form_key: z.string().default(''),
+    idname: z.string().min(1),
+    email: z.string().min(1),
+    name: z.string().default('')
+});
+export class api_recipient extends Model {
+}
+export async function init_api_recipient(api_db) {
+    api_recipient.init({
+        recipient_id: {
+            type: DataTypes.INTEGER,
+            autoIncrement: true,
+            allowNull: false,
+            primaryKey: true
+        },
+        domain_id: {
+            type: DataTypes.INTEGER,
+            allowNull: false,
+            references: {
+                model: 'domain',
+                key: 'domain_id'
+            },
+            onDelete: 'CASCADE',
+            onUpdate: 'CASCADE'
+        },
+        form_key: {
+            type: DataTypes.STRING,
+            allowNull: false,
+            defaultValue: ''
+        },
+        idname: {
+            type: DataTypes.STRING,
+            allowNull: false,
+            defaultValue: ''
+        },
+        email: {
+            type: DataTypes.STRING,
+            allowNull: false,
+            defaultValue: ''
+        },
+        name: {
+            type: DataTypes.STRING,
+            allowNull: false,
+            defaultValue: ''
+        }
+    }, {
+        sequelize: api_db,
+        tableName: 'recipient',
+        charset: 'utf8mb4',
+        collate: 'utf8mb4_unicode_ci',
+        indexes: [
+            {
+                unique: true,
+                fields: ['domain_id', 'form_key', 'idname']
+            }
+        ]
+    });
+    return api_recipient;
+}

package/dist/models/user.js

@@ -1,9 +1,11 @@
-import { Model, DataTypes } from 'sequelize';
+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),
+    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(),
@@ -11,6 +13,30 @@ export const api_user_schema = z.object({
 });
 export class api_user extends Model {
 }
+export function apiTokenToHmac(token, pepper) {
+    return createHmac('sha256', pepper).update(token).digest('hex');
+}
+export async function migrateLegacyApiTokens(pepper) {
+    const users = await api_user.findAll({
+        where: {
+            token: {
+                [Op.ne]: ''
+            }
+        }
+    });
+    let migrated = 0;
+    let cleared = 0;
+    for (const user of users) {
+        const updates = { token: '' };
+        if (!user.token_hmac && user.token) {
+            updates.token_hmac = apiTokenToHmac(user.token, pepper);
+            migrated += 1;
+        }
+        cleared += 1;
+        await user.update(updates);
+    }
+    return { migrated, cleared };
+}
 export async function init_api_user(api_db) {
     await api_user.init({
         user_id: {
@@ -29,6 +55,11 @@ export async function init_api_user(api_db) {
             allowNull: false,
             defaultValue: ''
         },
+        token_hmac: {
+            type: DataTypes.STRING,
+            allowNull: true,
+            defaultValue: null
+        },
         name: {
             type: DataTypes.STRING,
             allowNull: false,
@@ -59,7 +90,13 @@ export async function init_api_user(api_db) {
         sequelize: api_db,
         tableName: 'user',
         charset: 'utf8mb4',
-        collate: 'utf8mb4_unicode_ci'
+        collate: 'utf8mb4_unicode_ci',
+        indexes: [
+            {
+                unique: true,
+                fields: ['token_hmac']
+            }
+        ]
     });
     return api_user;
 }

package/dist/server.js

@@ -1,5 +1,5 @@
 import { ApiServer } from '@technomoron/api-server-base';
-import { api_user } from './models/user.js';
+import { apiTokenToHmac, api_user } from './models/user.js';
 export class mailApiServer extends ApiServer {
     store;
     storage;
@@ -9,14 +9,26 @@ export class mailApiServer extends ApiServer {
         this.storage = store;
     }
     async getApiKey(token) {
-        this.storage.print_debug(`Looking up api key ${token}`);
-        const user = await api_user.findOne({ where: { token: token } });
-        if (!user) {
-            this.storage.print_debug(`Unable to find user for token ${token}`);
+        this.storage.print_debug('Looking up api key');
+        const pepper = this.storage.env.API_TOKEN_PEPPER;
+        const token_hmac = apiTokenToHmac(token, pepper);
+        const user = await api_user.findOne({ where: { token_hmac } });
+        if (user) {
+            return { uid: user.user_id };
+        }
+        // Backwards-compatible fallback for legacy databases that still store plaintext tokens.
+        const legacy = await api_user.findOne({ where: { token } });
+        if (!legacy) {
+            this.storage.print_debug('Unable to find user for api key');
             return null;
         }
-        else {
-            return { uid: user.user_id };
+        try {
+            await legacy.update({ token_hmac, token: '' });
+        }
+        catch (err) {
+            // Don't leak token data; just surface the update failure for debugging.
+            this.storage.print_debug(`Unable to migrate legacy api token: ${err instanceof Error ? err.message : String(err)}`);
         }
+        return { uid: legacy.user_id };
     }
 }

package/dist/store/envloader.js

@@ -91,6 +91,11 @@ export const envOptions = defineEnvOptions({
         default: false,
         type: 'boolean'
     },
+    AUTOESCAPE_HTML: {
+        description: 'Enable Nunjucks HTML autoescape when rendering templates',
+        default: true,
+        type: 'boolean'
+    },
     SMTP_HOST: {
         description: 'Hostname of SMTP sending host',
         default: 'localhost'
@@ -121,5 +126,55 @@ export const envOptions = defineEnvOptions({
     UPLOAD_PATH: {
         description: 'Path for attached files. Use {domain} to scope per domain.',
         default: './{domain}/uploads'
+    },
+    UPLOAD_MAX: {
+        description: 'Maximum upload size per file (bytes) when uploads are enabled',
+        default: 30 * 1024 * 1024,
+        type: 'number'
+    },
+    FORM_RATE_LIMIT_WINDOW_SEC: {
+        description: 'Rate limit window for unauthenticated form submissions (seconds)',
+        default: 0,
+        type: 'number'
+    },
+    FORM_RATE_LIMIT_MAX: {
+        description: 'Max unauthenticated form submissions per client IP per window (0 disables rate limiting)',
+        default: 0,
+        type: 'number'
+    },
+    FORM_MAX_ATTACHMENTS: {
+        description: 'Max number of uploaded files accepted by /v1/form/message (-1 unlimited, 0 disables attachments)',
+        default: -1,
+        type: 'number'
+    },
+    FORM_KEEP_UPLOADS: {
+        description: 'Keep uploaded form files on disk after processing (success or failure)',
+        default: true,
+        type: 'boolean'
+    },
+    FORM_CAPTCHA_PROVIDER: {
+        description: 'CAPTCHA provider used to verify tokens for /v1/form/message',
+        options: ['turnstile', 'hcaptcha', 'recaptcha'],
+        default: 'turnstile'
+    },
+    FORM_CAPTCHA_SECRET: {
+        description: 'CAPTCHA secret used by the server to verify tokens (enables captcha checks when set)',
+        default: ''
+    },
+    FORM_CAPTCHA_REQUIRED: {
+        description: 'Require a CAPTCHA token for /v1/form/message when captcha is enabled',
+        default: false,
+        type: 'boolean'
+    },
+    API_TOKEN_PEPPER: {
+        description: 'Server-side pepper used to HMAC API tokens before DB lookup. Keep it stable to preserve existing API keys.',
+        required: true,
+        transform: (raw) => {
+            const value = String(raw ?? '').trim();
+            if (value.length < 16) {
+                throw new Error('API_TOKEN_PEPPER must be at least 16 characters');
+            }
+            return value;
+        }
     }
 });

package/dist/store/store.js

@@ -113,7 +113,16 @@ export class mailStore {
         return {};
     }
     async init() {
-        const env = (this.env = await EnvLoader.createConfigProxy(envOptions, { debug: true }));
+        // 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 });
+        }
+        this.env = env;
+        if (this.env.FORM_CAPTCHA_REQUIRED && !String(this.env.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;
         this.configpath = path.isAbsolute(p) ? p : path.resolve(process.cwd(), p);

package/dist/util.js

@@ -96,22 +96,32 @@ export function decodeComponent(value) {
     if (!value) {
         return '';
     }
+    const decoded = Array.isArray(value) ? (value[0] ?? '') : value;
+    if (!decoded) {
+        return '';
+    }
     try {
-        return decodeURIComponent(value);
+        return decodeURIComponent(decoded);
     }
     catch {
-        return value;
+        return decoded;
     }
 }
-export function sendFileAsync(res, file) {
+export function sendFileAsync(res, file, options) {
     return new Promise((resolve, reject) => {
-        res.sendFile(file, (err) => {
+        const cb = (err) => {
             if (err) {
-                reject(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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@technomoron/mail-magic",
-	"version": "1.0.16",
+	"version": "1.0.23",
 	"main": "dist/index.js",
 	"type": "module",
 	"bin": {
@@ -42,13 +42,14 @@
 		"url": "https://github.com/technomoron/mail-magic/issues"
 	},
 	"dependencies": {
-		"@technomoron/api-server-base": "2.0.0-beta.15",
+		"@technomoron/api-server-base": "2.0.0-beta.18",
 		"@technomoron/env-loader": "^1.0.8",
 		"@technomoron/unyuck": "^1.0.4",
 		"bcryptjs": "^3.0.2",
 		"dotenv": "^16.4.5",
 		"email-addresses": "^5.0.0",
 		"html-to-text": "^9.0.5",
+		"nanoid": "^5.1.6",
 		"nodemailer": "^6.10.1",
 		"nunjucks": "^3.2.4",
 		"sequelize": "^6.37.7",
@@ -58,7 +59,7 @@
 		"zod": "^4.1.5"
 	},
 	"devDependencies": {
-		"@types/express": "^4.17.21",
+		"@types/express": "^5.0.6",
 		"@types/html-to-text": "^9.0.4",
 		"@types/nodemailer": "^6.4.19",
 		"@types/nunjucks": "^3.2.6",