@technomoron/mail-magic 1.0.32 → 1.0.34

package/dist/util/utils.js

@@ -0,0 +1,151 @@
+import { api_domain } from '../models/domain.js';
+import { api_user } from '../models/user.js';
+/**
+ * Normalize a string into a safe identifier for slugs, filenames, etc.
+ *
+ * - Lowercases all characters
+ * - Replaces any character that is not `a-z`, `0-9`, `-`, '.' or `_` with `-`
+ * - Collapses multiple consecutive dashes into one
+ * - Trims leading and trailing dashes
+ *
+ * Examples:
+ *   normalizeSlug("Hello World!")    -> "hello-world"
+ *   normalizeSlug("  Áccêntš  ")     -> "cc-nt"
+ *   normalizeSlug("My--Slug__Test")  -> "my-slug__test"
+ */
+export function normalizeSlug(input) {
+    if (!input) {
+        return '';
+    }
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-_\.]/g, '-')
+        .replace(/--+/g, '-') // collapse multiple dashes
+        .replace(/^-+|-+$/g, ''); // trim leading/trailing dashes
+}
+export async function user_and_domain(domain_id) {
+    const domain = await api_domain.findByPk(domain_id);
+    if (!domain) {
+        throw new Error(`Unable to look up domain ${domain_id}`);
+    }
+    const user = await api_user.findByPk(domain.user_id);
+    if (!user) {
+        throw new Error(`Unable to look up user ${domain.user_id}`);
+    }
+    return { user, domain };
+}
+function collectHeaderIps(header) {
+    if (!header) {
+        return [];
+    }
+    if (Array.isArray(header)) {
+        return header
+            .join(',')
+            .split(',')
+            .map((ip) => ip.trim())
+            .filter(Boolean);
+    }
+    return header
+        .split(',')
+        .map((ip) => ip.trim())
+        .filter(Boolean);
+}
+function resolveHeader(headers, key) {
+    const direct = headers[key];
+    const alt = headers[key.toLowerCase()];
+    const value = direct ?? alt;
+    if (typeof value === 'string' || Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+export function buildRequestMeta(rawReq) {
+    const req = (rawReq ?? {});
+    const headers = req.headers ?? {};
+    const ips = [];
+    ips.push(...collectHeaderIps(resolveHeader(headers, 'x-forwarded-for')));
+    const realIp = resolveHeader(headers, 'x-real-ip');
+    if (typeof realIp === 'string' && realIp.trim()) {
+        ips.push(realIp.trim());
+    }
+    const cfIp = resolveHeader(headers, 'cf-connecting-ip');
+    if (typeof cfIp === 'string' && cfIp.trim()) {
+        ips.push(cfIp.trim());
+    }
+    const fastlyIp = resolveHeader(headers, 'fastly-client-ip');
+    if (typeof fastlyIp === 'string' && fastlyIp.trim()) {
+        ips.push(fastlyIp.trim());
+    }
+    if (req.ip && req.ip.trim()) {
+        ips.push(req.ip.trim());
+    }
+    const remoteAddress = req.socket?.remoteAddress;
+    if (remoteAddress) {
+        ips.push(remoteAddress);
+    }
+    const uniqueIps = ips.filter((ip, index) => ips.indexOf(ip) === index);
+    const clientIp = uniqueIps[0] || '';
+    return {
+        client_ip: clientIp,
+        received_at: new Date().toISOString(),
+        ip_chain: uniqueIps
+    };
+}
+export function decodeComponent(value) {
+    if (!value) {
+        return '';
+    }
+    const decoded = Array.isArray(value) ? (value[0] ?? '') : value;
+    if (!decoded) {
+        return '';
+    }
+    try {
+        return decodeURIComponent(decoded);
+    }
+    catch {
+        return decoded;
+    }
+}
+export function getBodyValue(body, ...keys) {
+    for (const key of keys) {
+        const value = body[key];
+        if (Array.isArray(value) && value.length > 0) {
+            return String(value[0]);
+        }
+        if (value !== undefined && value !== null) {
+            return String(value);
+        }
+    }
+    return '';
+}
+export function normalizeBoolean(value) {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        return value !== 0;
+    }
+    const normalized = String(value ?? '')
+        .trim()
+        .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/dist/util.js

@@ -1,127 +1,7 @@
-import { api_domain } from './models/domain.js';
-import { api_user } from './models/user.js';
-/**
- * Normalize a string into a safe identifier for slugs, filenames, etc.
- *
- * - Lowercases all characters
- * - Replaces any character that is not `a-z`, `0-9`, `-`, '.' or `_` with `-`
- * - Collapses multiple consecutive dashes into one
- * - Trims leading and trailing dashes
- *
- * Examples:
- *   normalizeSlug("Hello World!")    -> "hello-world"
- *   normalizeSlug("  Áccêntš  ")     -> "cc-nt"
- *   normalizeSlug("My--Slug__Test")  -> "my-slug__test"
- */
-export function normalizeSlug(input) {
-    if (!input) {
-        return '';
-    }
-    return input
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9-_\.]/g, '-')
-        .replace(/--+/g, '-') // collapse multiple dashes
-        .replace(/^-+|-+$/g, ''); // trim leading/trailing dashes
-}
-export async function user_and_domain(domain_id) {
-    const domain = await api_domain.findByPk(domain_id);
-    if (!domain) {
-        throw new Error(`Unable to look up domain ${domain_id}`);
-    }
-    const user = await api_user.findByPk(domain.user_id);
-    if (!user) {
-        throw new Error(`Unable to look up user ${domain.user_id}`);
-    }
-    return { user, domain };
-}
-function collectHeaderIps(header) {
-    if (!header) {
-        return [];
-    }
-    if (Array.isArray(header)) {
-        return header
-            .join(',')
-            .split(',')
-            .map((ip) => ip.trim())
-            .filter(Boolean);
-    }
-    return header
-        .split(',')
-        .map((ip) => ip.trim())
-        .filter(Boolean);
-}
-function resolveHeader(headers, key) {
-    const direct = headers[key];
-    const alt = headers[key.toLowerCase()];
-    const value = direct ?? alt;
-    if (typeof value === 'string' || Array.isArray(value)) {
-        return value;
-    }
-    return undefined;
-}
-export function buildRequestMeta(rawReq) {
-    const req = (rawReq ?? {});
-    const headers = req.headers ?? {};
-    const ips = [];
-    ips.push(...collectHeaderIps(resolveHeader(headers, 'x-forwarded-for')));
-    const realIp = resolveHeader(headers, 'x-real-ip');
-    if (typeof realIp === 'string' && realIp.trim()) {
-        ips.push(realIp.trim());
-    }
-    const cfIp = resolveHeader(headers, 'cf-connecting-ip');
-    if (typeof cfIp === 'string' && cfIp.trim()) {
-        ips.push(cfIp.trim());
-    }
-    const fastlyIp = resolveHeader(headers, 'fastly-client-ip');
-    if (typeof fastlyIp === 'string' && fastlyIp.trim()) {
-        ips.push(fastlyIp.trim());
-    }
-    if (req.ip && req.ip.trim()) {
-        ips.push(req.ip.trim());
-    }
-    const remoteAddress = req.socket?.remoteAddress;
-    if (remoteAddress) {
-        ips.push(remoteAddress);
-    }
-    const uniqueIps = ips.filter((ip, index) => ips.indexOf(ip) === index);
-    const clientIp = uniqueIps[0] || '';
-    return {
-        client_ip: clientIp,
-        received_at: new Date().toISOString(),
-        ip_chain: uniqueIps
-    };
-}
-export function decodeComponent(value) {
-    if (!value) {
-        return '';
-    }
-    const decoded = Array.isArray(value) ? (value[0] ?? '') : value;
-    if (!decoded) {
-        return '';
-    }
-    try {
-        return decodeURIComponent(decoded);
-    }
-    catch {
-        return decoded;
-    }
-}
-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);
-    });
-}
+export * from './util/utils.js';
+export * from './util/email.js';
+export * from './util/paths.js';
+export * from './util/uploads.js';
+export * from './util/form-replyto.js';
+export * from './util/form-submission.js';
+export * from './util/forms.js';

package/docs/config-example/example.test/assets/files/banner.png

@@ -0,0 +1 @@
+example-banner-bytes

package/docs/config-example/example.test/assets/images/logo.png

@@ -0,0 +1 @@
+example-logo-bytes

package/docs/config-example/example.test/form-template/base.njk

@@ -0,0 +1,6 @@
+<!doctype html>
+<html>
+  <body>
+    {% block body %}{% endblock %}
+  </body>
+</html>

package/docs/config-example/example.test/form-template/contact.njk

@@ -0,0 +1,9 @@
+{% extends "base.njk" %}
+
+{% block body %}
+{% include "partials/fields.njk" %}
+
+<p>From IP: {{ _meta_.client_ip }}</p>
+
+<img src="asset('images/logo.png', true)" alt="Logo" />
+{% endblock %}

package/docs/config-example/example.test/form-template/partials/fields.njk

@@ -0,0 +1,3 @@
+<p>Name: {{ _fields_.name }}</p>
+<p>Email: {{ _fields_.email }}</p>
+<p>Message: {{ _fields_.message }}</p>

package/docs/config-example/example.test/tx-template/base.njk

@@ -0,0 +1,10 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>{{ _vars_.title or 'Mail Magic' }}</title>
+  </head>
+  <body>
+    {% block body %}{% endblock %}
+  </body>
+</html>

package/docs/config-example/example.test/tx-template/partials/header.njk

@@ -0,0 +1 @@
+<h1>{{ _vars_.heading or 'Hello from Mail Magic' }}</h1>

package/docs/config-example/example.test/tx-template/welcome.njk

@@ -0,0 +1,10 @@
+{% extends "base.njk" %}
+
+{% block body %}
+{% include "partials/header.njk" %}
+
+<p>Hello {{ _vars_.first_name or _rcpt_email_ }}!</p>
+
+<img src="asset('images/logo.png', true)" alt="Logo" />
+<img src="asset('files/banner.png')" alt="Banner" />
+{% endblock %}

package/docs/config-example/init-data.json

@@ -0,0 +1,57 @@
+{
+	"user": [
+		{
+			"user_id": 1,
+			"idname": "example",
+			"token": "example-token",
+			"name": "Example User",
+			"email": "noreply@example.test",
+			"domain": 1,
+			"locale": ""
+		}
+	],
+	"domain": [
+		{
+			"domain_id": 1,
+			"user_id": 1,
+			"name": "example.test",
+			"sender": "Example <noreply@example.test>",
+			"locale": "",
+			"is_default": true
+		}
+	],
+	"template": [
+		{
+			"template_id": 1,
+			"user_id": 1,
+			"domain_id": 1,
+			"name": "welcome",
+			"locale": "",
+			"template": "",
+			"filename": "",
+			"sender": "Example <noreply@example.test>",
+			"subject": "Welcome from Mail Magic",
+			"slug": "",
+			"files": []
+		}
+	],
+	"form": [
+		{
+			"form_id": 1,
+			"form_key": "example-contact-form",
+			"user_id": 1,
+			"domain_id": 1,
+			"locale": "",
+			"idname": "contact",
+			"sender": "Example Forms <forms@example.test>",
+			"recipient": "owner@example.test",
+			"subject": "New contact form submission",
+			"template": "",
+			"filename": "",
+			"slug": "",
+			"secret": "s3cret",
+			"captcha_required": false,
+			"files": []
+		}
+	]
+}

package/docs/form-security.md

@@ -0,0 +1,194 @@
+# Form Security (Spam + Abuse Mitigation)
+
+This document describes how to operate the public form submission endpoint safely.
+
+## Public Endpoint Contract
+
+Endpoint:
+
+- `POST /api/v1/form/message` (no auth)
+
+Required fields:
+
+- `_mm_form_key` (string)
+
+Optional routing fields:
+
+- `_mm_recipients` (array of recipient `idname`s, or a comma-separated string)
+
+Optional anti-abuse field:
+
+- CAPTCHA token field (provider-native):
+    - `cf-turnstile-response` (Turnstile)
+    - `h-captcha-response` (hCaptcha)
+    - `g-recaptcha-response` (reCAPTCHA)
+    - `captcha` (generic/legacy)
+
+Other fields:
+
+- Any other fields are allowed and are exposed to templates as `_fields_`.
+
+Non-system fields:
+
+- Any other non-`_mm_*` fields are accepted as user fields and exposed to templates as `_fields_` verbatim.
+- If the form template has `allowed_fields` configured, `_fields_` is filtered to that allowlist, plus these
+  always-allowed fields: `email`, `name`, `first_name`, `last_name` (so Reply-To extraction still works).
+
+Ignored legacy inputs:
+
+- The server does not use `domain`, `formid`, `secret`, `recipient`, `recipient_idname`, `replyto` (or casing variants)
+  for routing/auth. If they are submitted, they are treated as normal user fields (unless filtered by `allowed_fields`).
+
+CAPTCHA token fields are accepted exactly as the providers submit them (no wrapper/rename).
+
+Security goal:
+
+- Treat `form_key` as the only public identifier needed to locate the form.
+- Prevent “open relay” style abuse by allowing only recipient `idname`s (resolved server-side) instead of raw email
+  addresses.
+- Prevent client-controlled secrets and legacy fields from widening the attack surface.
+
+## Recipient Allowlist and Reply-To
+
+Mail Magic supports a recipient allowlist stored server-side via the authenticated endpoint:
+
+- `POST /api/v1/form/recipient` (auth required)
+
+Each recipient mapping has an `idname` and an email address. Mappings can be:
+
+- Form-scoped (provide `form_key` when upserting the mapping)
+- Domain-wide fallback (omit `form_key`)
+
+Public submissions can then request routing by specifying:
+
+- `_mm_recipients: ["alice", "desk"]`
+
+If `_mm_recipients` is omitted, the form’s stored default recipient is used.
+
+Reply-To:
+
+- Reply-To behavior is configured per form (stored with the form template).
+
+Fields on the form template:
+
+- `replyto_from_fields` (boolean): when enabled, derive Reply-To from the submitted fields:
+    - `email`
+    - optional `name` or `first_name` + `last_name`
+- `replyto_email` (string): forced reply-to mailbox used when extraction is disabled, or as a fallback when extraction
+  fails.
+- `allowed_fields` (string[]): optional allowlist of field names exposed to templates as `_fields_`. When set, any
+  submitted fields not listed are ignored for template rendering (and for reply-to extraction).
+
+Precedence:
+
+- If `replyto_from_fields=true`: use extracted Reply-To if possible, otherwise fall back to `replyto_email` (if set).
+- If `replyto_from_fields=false`: use `replyto_email` (if set).
+- Otherwise: omit Reply-To.
+
+## CAPTCHA
+
+CAPTCHA is verified server-side.
+
+Configuration (server environment):
+
+- `FORM_CAPTCHA_PROVIDER`: `turnstile` | `hcaptcha` | `recaptcha`
+- `FORM_CAPTCHA_SECRET`: provider secret key (enables verification when set)
+- `FORM_CAPTCHA_REQUIRED`: when `true`, require CAPTCHA tokens for all form submissions
+
+Per-form configuration (authenticated template upsert):
+
+- `captcha_required=true` on `POST /api/v1/form/template` to require CAPTCHA for that form.
+
+Client integration contract:
+
+- CAPTCHA token fields are accepted exactly as the providers submit them. Do not wrap or rename them.
+
+Examples:
+
+```json
+{ "_mm_form_key": "abc", "cf-turnstile-response": "<turnstile token>", "name": "Ada" }
+```
+
+```json
+{ "_mm_form_key": "abc", "h-captcha-response": "<hcaptcha token>", "name": "Ada" }
+```
+
+```json
+{ "_mm_form_key": "abc", "g-recaptcha-response": "<recaptcha token>", "name": "Ada" }
+```
+
+Operational notes:
+
+- If CAPTCHA is required but `FORM_CAPTCHA_SECRET` is missing, the server returns `500`.
+- If CAPTCHA is required and the provider token field is missing, the server returns `403`.
+- If verification fails, the server returns `403`.
+
+## Rate Limiting
+
+Mail Magic has an optional in-memory fixed-window limiter on the public form endpoint:
+
+- `FORM_RATE_LIMIT_WINDOW_SEC`: window size in seconds
+- `FORM_RATE_LIMIT_MAX`: max requests per client IP per window (`0` disables rate limiting)
+
+Important limitations:
+
+- It is per-process memory. If you run multiple instances, limits do not aggregate.
+- Client IP is derived from request metadata; if you are not behind a trusted reverse proxy that normalizes headers,
+  clients can spoof IP-related headers.
+
+Recommendation:
+
+- Keep the built-in limiter as a “last line of defense”.
+- Enforce a real limiter at the edge (CDN/WAF/reverse proxy) for stronger protection.
+
+## Attachments and Upload Limits
+
+Attachments are a common abuse vector.
+
+Controls:
+
+- `UPLOAD_MAX` (bytes): max size per uploaded file (enforced by the server’s multipart handling)
+- `FORM_MAX_ATTACHMENTS`: max number of uploaded files (`-1` unlimited, `0` disables attachments)
+- `FORM_KEEP_UPLOADS`: when `false`, uploaded files are deleted after processing (best-effort), even on failures
+
+Recommendations:
+
+- If you do not need attachments, set `FORM_MAX_ATTACHMENTS=0`.
+- Set a conservative `UPLOAD_MAX` (and enforce matching limits at your reverse proxy).
+- Monitor disk usage for your upload staging directory.
+
+## Reverse Proxy / Edge Hardening
+
+You should run the server behind a reverse proxy (or CDN) and apply:
+
+- Request body size limits.
+- Rate limits per IP.
+- Bot protection / WAF rules on `POST /api/v1/form/message`.
+- Header normalization: strip client-provided `X-Forwarded-For` and set it yourself.
+
+Example Nginx ideas (sketch, not drop-in):
+
+```nginx
+# Limit body size (align with UPLOAD_MAX and your attachment policy).
+client_max_body_size 2m;
+
+# Basic rate limiting.
+limit_req_zone $binary_remote_addr zone=form_rate:10m rate=10r/m;
+
+location /api/v1/form/message {
+  limit_req zone=form_rate burst=20 nodelay;
+  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+  proxy_set_header X-Real-IP $remote_addr;
+  proxy_pass http://127.0.0.1:3776;
+}
+```
+
+## Treat `form_key` as Sensitive
+
+`form_key` is the public identifier for a form. If it is leaked, attackers can submit spam to that form.
+
+Recommendations:
+
+- Use long, random `form_key`s (Mail Magic generates them automatically when creating/upserting a form template).
+- Rotate `form_key` if you suspect it has leaked.
+- Don’t publish `form_key` in places you cannot control (logs, public repos, client-side error reporting).