@technomoron/mail-magic 1.0.38 → 1.0.41

package/dist/esm/models/user.d.ts

@@ -0,0 +1,33 @@
+import { Sequelize, Model } from 'sequelize';
+import { z } from 'zod';
+export declare const api_user_schema: z.ZodObject<{
+    user_id: z.ZodNumber;
+    idname: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+    token_hmac: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    email: z.ZodString;
+    domain: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    locale: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type api_user_input = z.input<typeof api_user_schema>;
+export type api_user_type = z.output<typeof api_user_schema>;
+export type api_user_creation_type = Omit<api_user_input, 'user_id'> & {
+    user_id?: number;
+};
+export declare class api_user extends Model<api_user_type, api_user_creation_type> {
+    user_id: number;
+    idname: string;
+    token: string | undefined;
+    token_hmac: string | undefined;
+    name: string;
+    email: string;
+    domain: number | null | undefined;
+    locale: string;
+}
+export declare function apiTokenToHmac(token: string, pepper: string): string;
+export declare function migrateLegacyApiTokens(pepper: string): Promise<{
+    migrated: number;
+    cleared: number;
+}>;
+export declare function init_api_user(api_db: Sequelize): Promise<typeof api_user>;

package/dist/esm/models/user.js

@@ -13,8 +13,6 @@ export const api_user_schema = z
     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/esm/server.d.ts

@@ -0,0 +1,8 @@
+import { ApiServerConf, ApiServer } from '@technomoron/api-server-base';
+import { mailStore } from './store/store.js';
+export declare class mailApiServer extends ApiServer {
+    private store;
+    storage: mailStore;
+    constructor(config: Partial<ApiServerConf>, store: mailStore);
+    getApiKey<ApiKey>(token: string): Promise<ApiKey | null>;
+}

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)',
@@ -67,6 +67,11 @@ export const envOptions = defineEnvOptions({
         description: 'Path to directory where config files are located',
         default: './data/'
     },
+    GEN_ENV_TEMPLATE: {
+        description: 'Write .env-dist to current working directory on startup',
+        default: false,
+        type: 'boolean'
+    },
     DB_USER: {
         description: 'Database username for API database'
     },
@@ -83,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: {
@@ -116,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
     };
@@ -22,10 +22,7 @@ function create_mail_transport(vars) {
     if (user && pass) {
         args.auth = { user, pass };
     }
-    const mailer = createTransport({
-        ...args
-    });
-    return mailer;
+    return createTransport(args);
 }
 export function enableInitDataAutoReload(ctx, reload) {
     if (!ctx.vars.DB_AUTO_RELOAD) {
@@ -167,10 +164,12 @@ export class mailStore {
         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');
+        if (this.vars.GEN_ENV_TEMPLATE) {
+            EnvLoader.genTemplate(envOptions, '.env-dist');
+        }
         const p = this.vars.CONFIG_PATH;
         this.configpath = path.isAbsolute(p) ? p : path.resolve(process.cwd(), p);
-        console.log(`Config path is ${this.configpath}`);
+        this.print_debug(`Config path is ${this.configpath}`);
         if (this.vars.UPLOAD_PATH && this.vars.UPLOAD_PATH.includes('{domain}')) {
             this.uploadTemplate = this.vars.UPLOAD_PATH;
             this.uploadStagingPath = path.resolve(this.configpath, '_uploads');

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 {
@@ -90,15 +90,13 @@ export async function enforceCaptchaPolicy(params) {
 }
 export function buildReplyToValue(form, fields) {
     const forced = typeof form.replyto_email === 'string' ? form.replyto_email.trim() : '';
-    const forcedValue = forced ? forced : '';
     if (form.replyto_from_fields) {
         const extracted = extractReplyToFromSubmission(fields);
         if (extracted) {
             return extracted;
         }
-        return forcedValue || undefined;
     }
-    return forcedValue || undefined;
+    return forced || undefined;
 }
 export function parseIdnameList(value, field) {
     if (value === undefined || value === null || value === '') {
@@ -299,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 {