@technomoron/mail-magic 1.0.15 → 1.0.23

package/CHANGES

@@ -1,3 +1,51 @@
+Version 1.0.23 (2026-02-07)
+
+- Added a form recipient allowlist table plus `POST /api/v1/form/recipient` to map a
+  public recipient `idname` to an email address (with optional display name),
+  scoped per domain and optionally per `form_key`.
+- `POST /api/v1/form/message` now supports `recipient_idname` so public forms can
+  select a configured recipient without exposing email addresses client-side.
+- Added integration tests covering recipient allowlist fallbacks, overrides, locale scoping,
+  validation, and ownership checks.
+
+Version 1.0.22 (2026-02-07)
+
+- Added opt-in anti-abuse controls for public form submissions, including:
+  `UPLOAD_MAX`, in-memory IP rate limiting, optional CAPTCHA verification
+  (Turnstile/hCaptcha/reCAPTCHA) with per-form `captcha_required`, optional
+  attachment count limits, and optional upload cleanup.
+
+Version 1.0.21 (2026-02-07)
+
+- Added `AUTOESCAPE_HTML` (default: true) to control Nunjucks HTML autoescaping
+  when rendering transactional and form templates.
+
+Version 1.0.20 (2026-02-07)
+
+- Centralized env parsing in `mailStore` (no direct `process.env` reads in core
+  server code).
+
+Version 1.0.19 (2026-02-07)
+
+- Store API tokens as HMAC-SHA256 (with required `API_TOKEN_PEPPER`) instead of
+  plaintext, and migrate legacy plaintext tokens on startup.
+
+Version 1.0.18 (2026-02-07)
+
+- Added a stable `form_key` (generated via nanoid) to uniquely identify forms and
+  return it from `POST /api/v1/form/template`.
+- Updated `POST /api/v1/form/message` form lookup to use `form_key` (preferred),
+  otherwise require `domain` + `formid` (+ optional `locale`) to avoid ambiguous
+  cross-domain/locale matches.
+
+Version 1.0.17 (2026-02-07)
+
+- Reduced sensitive logging by disabling env dumps unless `DEBUG` is enabled,
+  removing API tokens from debug output and API errors, and redacting DB
+  credentials in debug logs.
+- Fixed TypeScript build issues by aligning Express typings and updating
+  Express-related utility types.
+
 Version 1.0.15 (2026-02-01)
 
 - Made the optional admin UI/API opt-in via `ADMIN_ENABLED`, delegating admin

package/README.md

@@ -1,6 +1,8 @@
 # @technomoron/mail-magic
 
-Mail Magic is a TypeScript service for managing, templating, and delivering transactional emails. It exposes a small REST API built on `@technomoron/api-server-base`, persists data with Sequelize/SQLite, and renders outbound messages with Nunjucks templates.
+Mail Magic is a TypeScript service for managing, templating, and delivering transactional emails. It exposes a small
+REST API built on `@technomoron/api-server-base`, persists data with Sequelize/SQLite, and renders outbound messages
+with Nunjucks templates.
 
 ## Features
 
@@ -16,7 +18,8 @@ Mail Magic is a TypeScript service for managing, templating, and delivering tran
 1. Clone the repository: `git clone git@github.com:technomoron/mail-magic.git`
 2. Install dependencies: `npm install`
 3. Create your environment file: copy `.env-dist` to `.env` and adjust values
-4. Populate the config directory (defaults to `./data/`; see `config-example/` for a reference layout). You can point `CONFIG_PATH` at `./config` to use the bundled sample data.
+4. Populate the config directory (defaults to `./data/`; see `config-example/` for a reference layout). You can point
+   `CONFIG_PATH` at `./config` to use the bundled sample data.
 5. Build the project: `npm run build`
 6. Start the API server: `npm run start`
 
@@ -24,22 +27,38 @@ During development you can run `npm run dev` for a watch mode that recompiles on
 
 ## Configuration
 
-- **Environment variables** are defined in `src/store/envloader.ts`. Important settings include SMTP credentials, API host/port, the config directory path, database options, and `ADMIN_ENABLED`/`ADMIN_APP_PATH` to control the admin UI/API.
-- **Config directory** (`CONFIG_PATH`) contains JSON seed data (`init-data.json`), optional API key files, and template assets. Each domain now lives directly under the config root (for example `data/example.com/form-template/…`). Use an absolute path or a relative one like `../data` when you want the config outside the repo. Review `config-example/` for the recommended layout, in particular the `form-template/` and `tx-template/` folders used for compiled Nunjucks templates.
-- **Database** defaults to SQLite (`maildata.db`). You can switch dialects by updating the environment options if your deployment requires another database.
-- **Uploads** default to `<CONFIG_PATH>/<domain>/uploads` via `UPLOAD_PATH=./{domain}/uploads`. Set a fixed path if you prefer a shared upload directory.
-
-When `DB_AUTO_RELOAD` is enabled the service watches `init-data.json` and refreshes templates and forms without a restart.
+- **Environment variables** are defined in `src/store/envloader.ts`. Important settings include SMTP credentials, API
+  host/port, the config directory path, database options, and `ADMIN_ENABLED`/`ADMIN_APP_PATH` to control the admin
+  UI/API.
+- **Config directory** (`CONFIG_PATH`) contains JSON seed data (`init-data.json`), optional API key files, and template
+  assets. Each domain now lives directly under the config root (for example `data/example.com/form-template/…`). Use an
+  absolute path or a relative one like `../data` when you want the config outside the repo. Review `config-example/` for
+  the recommended layout, in particular the `form-template/` and `tx-template/` folders used for compiled Nunjucks
+  templates.
+- **Database** defaults to SQLite (`maildata.db`). You can switch dialects by updating the environment options if your
+  deployment requires another database.
+- **Uploads** default to `<CONFIG_PATH>/<domain>/uploads` via `UPLOAD_PATH=./{domain}/uploads`. Set a fixed path if you
+  prefer a shared upload directory.
+
+When `DB_AUTO_RELOAD` is enabled the service watches `init-data.json` and refreshes templates and forms without a
+restart.
 
 ### Admin UI
 
-The server mounts the admin UI at `/` only when `ADMIN_ENABLED` is true and the `@technomoron/mail-magic-admin` package is installed. You can point `ADMIN_APP_PATH` at a dist folder (or its parent) to override the package-provided build. The admin API module is loaded from the admin package as well. This is a placeholder Vue app today, but it is already wired so future admin features can live there without changing the server routing.
+The server mounts the admin UI at `/` only when `ADMIN_ENABLED` is true and the `@technomoron/mail-magic-admin` package
+is installed. You can point `ADMIN_APP_PATH` at a dist folder (or its parent) to override the package-provided build.
+The admin API module is loaded from the admin package as well. This is a placeholder Vue app today, but it is already
+wired so future admin features can live there without changing the server routing.
 
 ### Template assets and inline resources
 
-- Keep any non-inline files (images, attachments, etc.) under `<CONFIG_PATH>/<domain>/assets`. Mail Magic rewrites `asset('logo.png')` using `ASSET_ROUTE` (default `/asset`) and a base URL from `ASSET_PUBLIC_BASE` (or `API_URL` if unset). The default output looks like `http://localhost:3776/asset/<domain>/logo.png`.
-- Pass `true` as the second argument when you want to embed a file as an inline CID attachment: `asset('logo.png', true)` stores the file in Nodemailer and rewrites the HTML to reference `cid:logo.png`.
-- Avoid mixing template-type folders for assets; everything that should be linked externally belongs in the shared `<domain>/assets` tree so it can be served for both form and transactional templates.
+- Keep any non-inline files (images, attachments, etc.) under `<CONFIG_PATH>/<domain>/assets`. Mail Magic rewrites
+  `asset('logo.png')` using `ASSET_ROUTE` (default `/asset`) and a base URL from `ASSET_PUBLIC_BASE` (or `API_URL` if
+  unset). The default output looks like `http://localhost:3776/asset/<domain>/logo.png`.
+- Pass `true` as the second argument when you want to embed a file as an inline CID attachment:
+  `asset('logo.png', true)` stores the file in Nodemailer and rewrites the HTML to reference `cid:logo.png`.
+- Avoid mixing template-type folders for assets; everything that should be linked externally belongs in the shared
+  `<domain>/assets` tree so it can be served for both form and transactional templates.
 
 ## API Overview
 
@@ -52,7 +71,8 @@ The server mounts the admin UI at `/` only when `ADMIN_ENABLED` is true and the
 
 All routes are mounted under `API_BASE_PATH` (default `/api`), so the full path is typically `/api/v1/...`.
 
-All authenticated routes expect an API token associated with a configured user. Attachments can be uploaded alongside the `/v1/tx/message` request and are forwarded by Nodemailer.
+All authenticated routes expect an API token associated with a configured user. Attachments can be uploaded alongside
+the `/v1/tx/message` request and are forwarded by Nodemailer.
 
 ## Available Scripts
 

package/dist/api/assets.js

@@ -144,17 +144,27 @@ export class AssetAPI extends ApiModule {
     }
 }
 export function createAssetHandler(server) {
-    return async (req, res) => {
+    return async (req, res, next) => {
+        if (req.method && req.method !== 'GET' && req.method !== 'HEAD') {
+            if (next) {
+                next();
+                return;
+            }
+            res.status(405).end();
+            return;
+        }
         const domain = decodeComponent(req?.params?.domain);
         if (!domain || !DOMAIN_PATTERN.test(domain)) {
             res.status(404).end();
             return;
         }
-        const rawPath = typeof req?.params?.[0] === 'string' ? req.params[0] : '';
-        const segments = rawPath
-            .split('/')
-            .filter(Boolean)
-            .map((segment) => decodeComponent(segment));
+        const rawPathParam = req?.params?.path ?? req?.params?.[0];
+        const rawSegments = Array.isArray(rawPathParam)
+            ? rawPathParam
+            : typeof rawPathParam === 'string'
+                ? rawPathParam.split('/').filter(Boolean)
+                : [];
+        const segments = rawSegments.map((segment) => decodeComponent(typeof segment === 'string' ? segment : ''));
         if (!segments.length || segments.some((segment) => !SEGMENT_PATTERN.test(segment))) {
             res.status(404).end();
             return;
@@ -191,9 +201,10 @@ export function createAssetHandler(server) {
             return;
         }
         res.type(path.extname(realCandidate));
-        res.set('Cache-Control', 'public, max-age=300');
         try {
-            await sendFileAsync(res, realCandidate);
+            // 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 });
         }
         catch (err) {
             server.storage.print_debug(`Failed to serve asset ${domain}/${segments.join('/')}: ${err instanceof Error ? err.message : String(err)}`);

package/dist/api/auth.js

@@ -20,9 +20,14 @@ export async function assert_domain_and_user(apireq) {
     if (!domain) {
         throw new ApiError({ code: 401, message: 'Missing domain' });
     }
-    const user = await api_user.findOne({ where: { token: apireq.token } });
+    const rawUid = apireq.getRealUid();
+    const uid = rawUid === null ? null : Number(rawUid);
+    if (!uid || Number.isNaN(uid)) {
+        throw new ApiError({ code: 401, message: 'Invalid/Unknown API Key/Token' });
+    }
+    const user = await api_user.findByPk(uid);
     if (!user) {
-        throw new ApiError({ code: 401, message: `Invalid/Unknown API Key/Token '${apireq.token}'` });
+        throw new ApiError({ code: 401, message: 'Invalid/Unknown API Key/Token' });
     }
     const dbdomain = await api_domain.findOne({ where: { name: domain } });
     if (!dbdomain) {