@technomoron/mail-magic 1.0.40 → 1.0.41

package/dist/esm/store/envloader.d.ts

@@ -0,0 +1,188 @@
+export declare const envOptions: {
+    NODE_ENV: {
+        description: string;
+        options: string[];
+        default: string;
+    };
+    API_PORT: {
+        description: string;
+        default: string;
+        type: "number";
+    };
+    API_HOST: {
+        description: string;
+        default: string;
+    };
+    DB_AUTO_RELOAD: {
+        description: string;
+        type: "boolean";
+        default: false;
+    };
+    DB_FORCE_SYNC: {
+        description: string;
+        type: "boolean";
+        default: false;
+    };
+    DB_SYNC_ALTER: {
+        description: string;
+        type: "boolean";
+        default: false;
+    };
+    API_URL: {
+        description: string;
+        default: string;
+    };
+    API_BASE_PATH: {
+        description: string;
+        default: string;
+    };
+    ASSET_PUBLIC_BASE: {
+        description: string;
+        default: string;
+    };
+    SWAGGER_ENABLED: {
+        description: string;
+        type: "boolean";
+        default: false;
+    };
+    SWAGGER_PATH: {
+        description: string;
+        default: string;
+    };
+    ADMIN_ENABLED: {
+        description: string;
+        default: false;
+        type: "boolean";
+    };
+    ADMIN_APP_PATH: {
+        description: string;
+        default: string;
+    };
+    ASSET_ROUTE: {
+        description: string;
+        default: string;
+    };
+    CONFIG_PATH: {
+        description: string;
+        default: string;
+    };
+    GEN_ENV_TEMPLATE: {
+        description: string;
+        default: false;
+        type: "boolean";
+    };
+    DB_USER: {
+        description: string;
+    };
+    DB_PASS: {
+        description: string;
+    };
+    DB_NAME: {
+        description: string;
+        default: string;
+    };
+    DB_HOST: {
+        description: string;
+        default: string;
+    };
+    DB_TYPE: {
+        description: string;
+        options: string[];
+        default: string;
+    };
+    DB_LOG: {
+        description: string;
+        default: string;
+        type: "boolean";
+    };
+    DEBUG: {
+        description: string;
+        default: false;
+        type: "boolean";
+    };
+    AUTOESCAPE_HTML: {
+        description: string;
+        default: true;
+        type: "boolean";
+    };
+    SMTP_HOST: {
+        description: string;
+        default: string;
+    };
+    SMTP_PORT: {
+        description: string;
+        default: number;
+        type: "number";
+    };
+    SMTP_SECURE: {
+        description: string;
+        default: false;
+        type: "boolean";
+    };
+    SMTP_TLS_REJECT: {
+        description: string;
+        default: true;
+        type: "boolean";
+    };
+    SMTP_REQUIRE_TLS: {
+        description: string;
+        default: true;
+        type: "boolean";
+    };
+    SMTP_USER: {
+        description: string;
+        default: string;
+    };
+    SMTP_PASSWORD: {
+        description: string;
+        default: string;
+    };
+    UPLOAD_PATH: {
+        description: string;
+        default: string;
+    };
+    UPLOAD_MAX: {
+        description: string;
+        default: number;
+        type: "number";
+    };
+    FORM_RATE_LIMIT_WINDOW_SEC: {
+        description: string;
+        default: number;
+        type: "number";
+    };
+    FORM_RATE_LIMIT_MAX: {
+        description: string;
+        default: number;
+        type: "number";
+    };
+    FORM_MAX_ATTACHMENTS: {
+        description: string;
+        default: number;
+        type: "number";
+    };
+    FORM_KEEP_UPLOADS: {
+        description: string;
+        default: true;
+        type: "boolean";
+    };
+    FORM_CAPTCHA_PROVIDER: {
+        description: string;
+        options: string[];
+        default: string;
+    };
+    FORM_CAPTCHA_SECRET: {
+        description: string;
+        default: string;
+    };
+    FORM_CAPTCHA_REQUIRED: {
+        description: string;
+        default: false;
+        type: "boolean";
+    };
+    API_TOKEN_PEPPER: {
+        description: string;
+        required: true;
+        transform: (raw: string) => string;
+    };
+};

package/dist/esm/store/envloader.js

@@ -27,7 +27,7 @@ export const envOptions = defineEnvOptions({
     DB_SYNC_ALTER: {
         description: 'Alter existing tables on startup to match models (requires write access to the DB)',
         type: 'boolean',
-        default: true
+        default: false
     },
     API_URL: {
         description: 'Sets the public URL for the API (i.e. https://ml.example.com:3790)',
@@ -88,7 +88,7 @@ export const envOptions = defineEnvOptions({
     },
     DB_TYPE: {
         description: 'Database type for the API database',
-        options: ['sqlite'],
+        options: ['sqlite', 'mysql', 'postgres'],
         default: 'sqlite'
     },
     DB_LOG: {
@@ -121,8 +121,13 @@ export const envOptions = defineEnvOptions({
         type: 'boolean'
     },
     SMTP_TLS_REJECT: {
-        description: 'Reject bad cert/TLS connection to SMTP host',
-        default: false,
+        description: 'Validate the SMTP server TLS certificate. Set false to allow self-signed certificates.',
+        default: true,
+        type: 'boolean'
+    },
+    SMTP_REQUIRE_TLS: {
+        description: 'Require STARTTLS upgrade on SMTP connection. Set false for servers that do not support STARTTLS (e.g. MailHog).',
+        default: true,
         type: 'boolean'
     },
     SMTP_USER: {

package/dist/esm/store/store.d.ts

@@ -0,0 +1,37 @@
+import { envConfig } from '@technomoron/env-loader';
+import { Transporter } from 'nodemailer';
+import { Sequelize } from 'sequelize';
+import { envOptions } from './envloader.js';
+import type SMTPTransport from 'nodemailer/lib/smtp-transport';
+type UploadedFile = {
+    path: string;
+    filename?: string;
+    destination?: string;
+};
+export type MailStoreVars = envConfig<typeof envOptions>;
+type AutoReloadHandle = {
+    close: () => void;
+};
+type AutoReloadContext = {
+    vars: Pick<MailStoreVars, 'DB_AUTO_RELOAD'>;
+    config_filename: (name: string) => string;
+    print_debug: (msg: string) => void;
+};
+export declare function enableInitDataAutoReload(ctx: AutoReloadContext, reload: () => void): AutoReloadHandle | null;
+export declare class mailStore {
+    private env;
+    vars: MailStoreVars;
+    transport?: Transporter<SMTPTransport.SentMessageInfo>;
+    api_db: Sequelize | null;
+    configpath: string;
+    uploadTemplate?: string;
+    uploadStagingPath?: string;
+    autoReloadHandle: AutoReloadHandle | null;
+    print_debug(msg: string): void;
+    config_filename(name: string): string;
+    resolveUploadPath(domainName?: string): string;
+    getUploadStagingPath(): string;
+    relocateUploads(domainName: string | null, files: UploadedFile[]): Promise<void>;
+    init(overrides?: Partial<MailStoreVars>): Promise<this>;
+}
+export {};

package/dist/esm/store/store.js

@@ -13,7 +13,7 @@ function create_mail_transport(vars) {
         tls: {
             rejectUnauthorized: vars.SMTP_TLS_REJECT
         },
-        requireTLS: true,
+        requireTLS: vars.SMTP_REQUIRE_TLS,
         logger: vars.DEBUG,
         debug: vars.DEBUG
     };

package/dist/esm/swagger.d.ts

@@ -0,0 +1,10 @@
+import type { mailApiServer } from './server.js';
+type SwaggerInstallOptions = {
+    apiBasePath: string;
+    assetRoute: string;
+    apiUrl: string;
+    swaggerEnabled?: boolean;
+    swaggerPath?: string;
+};
+export declare function installMailMagicSwagger(server: mailApiServer, opts: SwaggerInstallOptions): void;
+export {};

package/dist/esm/types.d.ts

@@ -0,0 +1,32 @@
+import { ApiRequest } from '@technomoron/api-server-base';
+import { api_domain } from './models/domain.js';
+import { api_user } from './models/user.js';
+export interface mailApiKey {
+    uid: number;
+}
+export interface mailApiRequest extends ApiRequest {
+    user?: api_user;
+    domain?: api_domain;
+    locale?: string;
+}
+export interface formType {
+    rcpt: string;
+    sender: string;
+    subject: string;
+    template: string;
+}
+export interface StoredFile {
+    filename: string;
+    path: string;
+    cid?: string;
+}
+export interface RequestMeta {
+    client_ip: string;
+    received_at: string;
+    ip_chain: string[];
+}
+export interface UploadedFile {
+    originalname: string;
+    path: string;
+    fieldname: string;
+}

package/dist/esm/util/captcha.d.ts

@@ -0,0 +1,7 @@
+export type CaptchaProvider = 'turnstile' | 'hcaptcha' | 'recaptcha';
+export declare function verifyCaptcha(params: {
+    provider: CaptchaProvider;
+    secret: string;
+    token: string;
+    remoteip: string | null;
+}): Promise<boolean>;

package/dist/esm/util/captcha.js

@@ -4,7 +4,10 @@ export async function verifyCaptcha(params) {
         hcaptcha: 'https://hcaptcha.com/siteverify',
         recaptcha: 'https://www.google.com/recaptcha/api/siteverify'
     };
-    const endpoint = endpoints[params.provider] ?? endpoints.turnstile;
+    const endpoint = endpoints[params.provider];
+    if (!endpoint) {
+        throw new Error(`Unknown CAPTCHA provider: "${params.provider}"`);
+    }
     const body = new URLSearchParams();
     body.set('secret', params.secret);
     body.set('response', params.token);

package/dist/esm/util/email.d.ts

@@ -0,0 +1,3 @@
+import { ParsedMailbox } from 'email-addresses';
+export declare function validateEmail(email: string): string | undefined;
+export declare function parseMailbox(value: string): ParsedMailbox | undefined;

package/dist/esm/util/form-replyto.d.ts

@@ -0,0 +1,6 @@
+type ReplyToValue = string | {
+    name: string;
+    address: string;
+};
+export declare function extractReplyToFromSubmission(body: Record<string, unknown>): ReplyToValue | undefined;
+export {};

package/dist/esm/util/form-submission.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export declare const form_submission_schema: z.ZodObject<{
+    _mm_form_key: z.ZodString;
+    _mm_locale: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    _mm_recipients: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    email: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    first_name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    last_name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    'cf-turnstile-response': z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    'h-captcha-response': z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    'g-recaptcha-response': z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    captcha: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+}, z.core.$loose>;
+export type ParsedFormSubmission = {
+    mm: {
+        form_key: string;
+        locale: string;
+        captcha_token: string;
+        recipients_raw: unknown;
+    };
+    fields: Record<string, unknown>;
+};
+export declare function parseFormSubmissionInput(raw: unknown): ParsedFormSubmission;

package/dist/esm/util/forms.d.ts

@@ -0,0 +1,140 @@
+import { ApiRequest } from '@technomoron/api-server-base';
+import { api_form } from '../models/form.js';
+import { api_recipient } from '../models/recipient.js';
+import { ParsedFormSubmission } from './form-submission.js';
+import type { api_domain } from '../models/domain.js';
+import type { api_user } from '../models/user.js';
+import type { RequestMeta, UploadedFile } from '../types.js';
+export declare function parsePublicSubmissionOrThrow(apireq: ApiRequest): ParsedFormSubmission;
+export declare function enforceAttachmentPolicy(env: {
+    FORM_MAX_ATTACHMENTS: number;
+}, rawFiles: UploadedFile[]): void;
+export declare function filterSubmissionFields(rawFields: Record<string, unknown>, allowedFields: unknown): Record<string, unknown>;
+export declare function enforceCaptchaPolicy(params: {
+    vars: {
+        FORM_CAPTCHA_REQUIRED: boolean;
+        FORM_CAPTCHA_SECRET: string;
+        FORM_CAPTCHA_PROVIDER: string;
+    };
+    form: {
+        captcha_required: boolean;
+    };
+    captchaToken: string;
+    clientIp: string;
+}): Promise<void>;
+export declare function buildReplyToValue(form: {
+    replyto_email: string;
+    replyto_from_fields: boolean;
+}, fields: Record<string, unknown>): (string | {
+    name: string;
+    address: string;
+}) | undefined;
+export declare function parseIdnameList(value: unknown, field: string): string[];
+export type FormRecipientPayload = {
+    idnameRaw: string;
+    emailRaw: string;
+    nameRaw: string;
+    formKeyRaw: string;
+    formid: string;
+    localeRaw: string;
+};
+export declare function parseRecipientPayload(body: Record<string, unknown>): FormRecipientPayload;
+export declare function normalizeRecipientIdname(raw: string): string;
+export declare function normalizeRecipientEmail(raw: string): {
+    email: string;
+    mailbox: {
+        address: string;
+        name?: string | null;
+    };
+};
+export declare function normalizeRecipientName(raw: string, mailboxName?: string | null): string;
+export declare function resolveFormKeyForRecipient(params: {
+    formKeyRaw: string;
+    formid: string;
+    localeRaw: string;
+    user: api_user;
+    domain: api_domain;
+}): Promise<string>;
+export declare function parseAllowedFields(raw: unknown): string[];
+export type FormTemplateInput = {
+    template: string;
+    sender: string;
+    recipient: string;
+    idname: string;
+    subject: string;
+    locale: string;
+    secret: string;
+    replyto_email: string;
+    replyto_from_fields: boolean;
+    allowed_fields: string[];
+    captcha_required: boolean;
+};
+export declare function parseFormTemplatePayload(body: Record<string, unknown>): FormTemplateInput;
+export declare function validateFormTemplatePayload(payload: FormTemplateInput): void;
+export declare function buildFormTemplatePaths(params: {
+    user: api_user;
+    domain: api_domain;
+    idname: string;
+    locale: string;
+}): {
+    localeSlug: string;
+    slug: string;
+    filename: string;
+};
+export declare function resolveFormKeyForTemplate(params: {
+    user_id: number;
+    domain_id: number;
+    locale: string;
+    idname: string;
+}): Promise<string>;
+export declare function buildFormTemplateRecord(params: {
+    form_key: string;
+    user_id: number;
+    domain_id: number;
+    locale: string;
+    slug: string;
+    filename: string;
+    payload: FormTemplateInput;
+}): {
+    form_key: string;
+    user_id: number;
+    domain_id: number;
+    locale: string;
+    idname: string;
+    sender: string;
+    recipient: string;
+    subject: string;
+    template: string;
+    slug: string;
+    filename: string;
+    secret: string;
+    replyto_email: string;
+    replyto_from_fields: boolean;
+    allowed_fields: string[];
+    captcha_required: boolean;
+    files: never[];
+};
+export declare function resolveRecipients(form: api_form, recipientsRaw: unknown): Promise<api_recipient[]>;
+export declare function buildRecipientTo(form: api_form, recipients: api_recipient[]): string | (string | {
+    name: string;
+    address: string;
+})[];
+export declare function getPrimaryRecipientInfo(form: api_form, recipients: api_recipient[]): {
+    rcptEmail: string;
+    rcptName: string;
+    rcptIdname: string;
+    rcptIdnames: string[];
+};
+export declare function buildSubmissionContext(params: {
+    form_key: string;
+    localeRaw: string;
+    recipients: string[];
+    rcptEmail: string;
+    rcptName: string;
+    rcptIdname: string;
+    rcptIdnames: string[];
+    attachmentMap: Record<string, string>;
+    fields: Record<string, unknown>;
+    files: UploadedFile[];
+    meta: RequestMeta;
+}): Record<string, unknown>;

package/dist/esm/util/forms.js

@@ -1,4 +1,3 @@
-import path from 'path';
 import { ApiError } from '@technomoron/api-server-base';
 import { api_form } from '../models/form.js';
 import { api_recipient } from '../models/recipient.js';
@@ -6,6 +5,7 @@ import { verifyCaptcha } from './captcha.js';
 import { parseMailbox } from './email.js';
 import { extractReplyToFromSubmission } from './form-replyto.js';
 import { parseFormSubmissionInput } from './form-submission.js';
+import { buildFormSlugAndFilename } from './paths.js';
 import { normalizeBoolean, normalizeSlug } from './utils.js';
 export function parsePublicSubmissionOrThrow(apireq) {
     try {
@@ -297,36 +297,24 @@ export function validateFormTemplatePayload(payload) {
     }
 }
 export function buildFormTemplatePaths(params) {
-    const domainSlug = normalizeSlug(params.domain.name);
-    const formSlug = normalizeSlug(params.idname);
-    const localeSlug = normalizeSlug(params.locale || params.domain.locale || params.user.locale || '');
-    const slug = `${domainSlug}${localeSlug ? '-' + localeSlug : ''}-${formSlug}`;
-    const filenameParts = [domainSlug, 'form-template'];
-    if (localeSlug) {
-        filenameParts.push(localeSlug);
-    }
-    filenameParts.push(formSlug);
-    let filename = path.join(...filenameParts);
-    if (!filename.endsWith('.njk')) {
-        filename += '.njk';
-    }
-    return { localeSlug, slug, filename };
+    return buildFormSlugAndFilename({
+        domainName: params.domain.name,
+        domainLocale: params.domain.locale,
+        userLocale: params.user.locale,
+        idname: params.idname,
+        locale: params.locale
+    });
 }
 export async function resolveFormKeyForTemplate(params) {
-    try {
-        const existing = await api_form.findOne({
-            where: {
-                user_id: params.user_id,
-                domain_id: params.domain_id,
-                locale: params.locale,
-                idname: params.idname
-            }
-        });
-        return existing?.form_key || '';
-    }
-    catch {
-        return '';
-    }
+    const existing = await api_form.findOne({
+        where: {
+            user_id: params.user_id,
+            domain_id: params.domain_id,
+            locale: params.locale,
+            idname: params.idname
+        }
+    });
+    return existing?.form_key || '';
 }
 export function buildFormTemplateRecord(params) {
     return {

package/dist/esm/util/paths.d.ts

@@ -0,0 +1,15 @@
+export declare const SEGMENT_PATTERN: RegExp;
+export declare function normalizeSubdir(value: string): string;
+export declare function assertSafeRelativePath(filename: string, label: string): string;
+export declare function buildFormSlugAndFilename(params: {
+    domainName: string;
+    domainLocale: string;
+    userLocale: string;
+    idname: string;
+    locale: string;
+}): {
+    localeSlug: string;
+    slug: string;
+    filename: string;
+};
+export declare function buildAssetUrl(baseUrl: string, route: string, domainName: string, assetPath: string): string;

package/dist/esm/util/paths.js

@@ -1,5 +1,6 @@
 import path from 'path';
 import { ApiError } from '@technomoron/api-server-base';
+import { normalizeSlug } from './utils.js';
 export const SEGMENT_PATTERN = /^[a-zA-Z0-9._-]+$/;
 export function normalizeSubdir(value) {
     if (!value) {
@@ -27,6 +28,22 @@ export function assertSafeRelativePath(filename, label) {
     }
     return normalized;
 }
+export function buildFormSlugAndFilename(params) {
+    const domainSlug = normalizeSlug(params.domainName);
+    const formSlug = normalizeSlug(params.idname);
+    const localeSlug = normalizeSlug(params.locale || params.domainLocale || params.userLocale || '');
+    const slug = `${domainSlug}${localeSlug ? '-' + localeSlug : ''}-${formSlug}`;
+    const filenameParts = [domainSlug, 'form-template'];
+    if (localeSlug) {
+        filenameParts.push(localeSlug);
+    }
+    filenameParts.push(formSlug);
+    let filename = path.join(...filenameParts);
+    if (!filename.endsWith('.njk')) {
+        filename += '.njk';
+    }
+    return { localeSlug, slug, filename };
+}
 export function buildAssetUrl(baseUrl, route, domainName, assetPath) {
     const trimmedBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
     const normalizedRoute = route ? (route.startsWith('/') ? route : `/${route}`) : '';

package/dist/esm/util/ratelimit.d.ts

@@ -0,0 +1,16 @@
+import { ApiRequest } from '@technomoron/api-server-base';
+export type RateLimitDecision = {
+    allowed: boolean;
+    retryAfterSec: number;
+};
+export declare class FixedWindowRateLimiter {
+    private readonly maxKeys;
+    private readonly buckets;
+    constructor(maxKeys?: number);
+    check(key: string, max: number, windowMs: number): RateLimitDecision;
+    private prune;
+}
+export declare function enforceFormRateLimit(limiter: FixedWindowRateLimiter, env: {
+    FORM_RATE_LIMIT_WINDOW_SEC: number;
+    FORM_RATE_LIMIT_MAX: number;
+}, apireq: ApiRequest): void;

package/dist/esm/util/ratelimit.js

@@ -39,8 +39,13 @@ export class FixedWindowRateLimiter {
 }
 export function enforceFormRateLimit(limiter, env, apireq) {
     const clientIp = apireq.getClientIp() ?? '';
+    if (!clientIp) {
+        // Cannot rate-limit without a resolvable client IP; skip to avoid collapsing
+        // all IP-unknown requests into a single shared bucket.
+        return;
+    }
     const windowMs = Math.max(0, env.FORM_RATE_LIMIT_WINDOW_SEC) * 1000;
-    const decision = limiter.check(`form-message:${clientIp || 'unknown'}`, env.FORM_RATE_LIMIT_MAX, windowMs);
+    const decision = limiter.check(`form-message:${clientIp}`, env.FORM_RATE_LIMIT_MAX, windowMs);
     if (!decision.allowed) {
         apireq.res.set('Retry-After', String(decision.retryAfterSec));
         throw new ApiError({ code: 429, message: 'Too many form submissions; try again later' });

package/dist/esm/util/route.d.ts

@@ -0,0 +1 @@
+export declare function normalizeRoute(value: string, fallback?: string): string;

package/dist/esm/util/shared-template-flatten.d.ts

@@ -0,0 +1,17 @@
+export type FlattenedAsset = {
+    filename: string;
+    path: string;
+    cid?: string;
+};
+export type FlattenWithAssetsOptions = {
+    domainRoot: string;
+    templateKey: string;
+    baseUrl: string;
+    assetFormatter: (urlPath: string) => string;
+    normalizeInlineCid?: (urlPath: string) => string;
+};
+export type FlattenWithAssetsResult = {
+    html: string;
+    assets: FlattenedAsset[];
+};
+export declare function flattenTemplateWithAssets(options: FlattenWithAssetsOptions): FlattenWithAssetsResult;