@zintrust/core 0.1.40 → 0.1.42

package/src/tools/mail/drivers/Smtp.js

@@ -1,13 +1,31 @@
 import { generateUuid } from '../../../common/utility.js';
+import { RemoteSignedJson } from '../../../common/RemoteSignedJson.js';
+import { Cloudflare } from '../../../config/cloudflare.js';
+import { Env } from '../../../config/env.js';
+import { Logger } from '../../../config/logger.js';
 import { ErrorFactory } from '../../../exceptions/ZintrustError.js';
 import * as net from '../../../node-singletons/net.js';
 import * as tls from '../../../node-singletons/tls.js';
+import { normalizeSigningCredentials } from '../../../proxy/SigningService.js';
+const resolveSigningPrefix = (baseUrl) => {
+    try {
+        const parsed = new URL(baseUrl);
+        const path = parsed.pathname.endsWith('/') ? parsed.pathname.slice(0, -1) : parsed.pathname;
+        if (path === '' || path === '/')
+            return undefined;
+        return path;
+    }
+    catch {
+        return undefined;
+    }
+};
 const normalizeRecipients = (to) => (Array.isArray(to) ? to : [to]);
 const toBase64 = (value) => Buffer.from(value, 'utf8').toString('base64');
 const isNodeRuntime = () => typeof process !== 'undefined' && typeof process.versions?.node === 'string';
+const isWorkersRuntime = () => Cloudflare.getWorkersEnv() !== null;
 const validateConfig = (config) => {
-    if (!isNodeRuntime()) {
-        throw ErrorFactory.createConfigError('SMTP driver requires Node.js runtime');
+    if (!isNodeRuntime() && !isWorkersRuntime()) {
+        throw ErrorFactory.createConfigError('SMTP driver requires Node.js or Workers runtime');
     }
     if (config.host.trim() === '') {
         throw ErrorFactory.createConfigError('SMTP: missing MAIL_HOST');
@@ -16,7 +34,101 @@ const validateConfig = (config) => {
         throw ErrorFactory.createConfigError('SMTP: invalid MAIL_PORT');
     }
 };
-const createSocket = async (config, implicitTls) => {
+const resolveProxyBaseUrl = () => {
+    const explicit = Env.SMTP_PROXY_URL.trim();
+    if (explicit !== '')
+        return explicit;
+    const host = Env.SMTP_PROXY_HOST || '127.0.0.1';
+    const port = Env.SMTP_PROXY_PORT;
+    return `http://${host}:${port}`;
+};
+const buildProxySettings = () => {
+    const baseUrl = resolveProxyBaseUrl();
+    const keyId = Env.SMTP_PROXY_KEY_ID ?? '';
+    const secret = Env.SMTP_PROXY_SECRET ?? '';
+    const timeoutMs = Env.SMTP_PROXY_TIMEOUT_MS;
+    return { baseUrl, keyId, secret, timeoutMs };
+};
+const buildSignedSettings = (settings) => {
+    const creds = normalizeSigningCredentials({
+        keyId: settings.keyId ?? '',
+        secret: settings.secret ?? '',
+    });
+    return {
+        baseUrl: settings.baseUrl,
+        keyId: creds.keyId,
+        secret: creds.secret,
+        timeoutMs: settings.timeoutMs,
+        signaturePathPrefixToStrip: resolveSigningPrefix(settings.baseUrl),
+        missingUrlMessage: 'SMTP proxy URL is missing (SMTP_PROXY_URL)',
+        missingCredentialsMessage: 'SMTP proxy signing credentials are missing (SMTP_PROXY_KEY_ID / SMTP_PROXY_SECRET)',
+        messages: {
+            unauthorized: 'SMTP proxy unauthorized',
+            forbidden: 'SMTP proxy forbidden',
+            rateLimited: 'SMTP proxy rate limited',
+            rejected: 'SMTP proxy rejected request',
+            error: 'SMTP proxy error',
+            timedOut: 'SMTP proxy request timed out',
+        },
+    };
+};
+const ensureSignedSettings = (settings) => {
+    const signedSettings = buildSignedSettings(settings);
+    if (signedSettings.baseUrl.trim() === '') {
+        throw ErrorFactory.createConfigError('SMTP proxy URL is missing (SMTP_PROXY_URL)');
+    }
+    if (signedSettings.keyId.trim() === '' || signedSettings.secret.trim() === '') {
+        throw ErrorFactory.createConfigError('SMTP proxy signing credentials are missing (SMTP_PROXY_KEY_ID / SMTP_PROXY_SECRET)');
+    }
+    return signedSettings;
+};
+const shouldUseProxy = () => {
+    if (Env.USE_SMTP_PROXY === true)
+        return true;
+    // In Cloudflare Workers, SMTP requires TCP sockets; if sockets are disabled,
+    // we must use the HTTP SMTP proxy transport when a URL is configured.
+    if (isWorkersRuntime() && Cloudflare.isCloudflareSocketsEnabled() === false) {
+        return Env.SMTP_PROXY_URL.trim() !== '';
+    }
+    // Default: do not use proxy unless explicitly enabled.
+    return false;
+};
+const serializeMessage = (message) => {
+    const attachments = message.attachments?.map((attachment) => {
+        const raw = Buffer.isBuffer(attachment.content)
+            ? attachment.content
+            : Buffer.from(attachment.content);
+        return {
+            filename: attachment.filename,
+            contentBase64: raw.toString('base64'),
+        };
+    });
+    return {
+        to: message.to,
+        from: message.from,
+        subject: message.subject,
+        text: message.text,
+        html: message.html,
+        attachments: attachments && attachments.length > 0 ? attachments : undefined,
+    };
+};
+const sendViaProxy = async (message) => {
+    const settings = buildProxySettings();
+    const signedSettings = ensureSignedSettings(settings);
+    return RemoteSignedJson.request(signedSettings, '/zin/smtp/send', {
+        message: serializeMessage(message),
+    });
+};
+const loadCloudflareSocketFactory = async () => {
+    const mod = (await import('../../../sockets/CloudflareSocket.js'));
+    const record = mod;
+    const socketFactory = record.CloudflareSocket;
+    if (!socketFactory || typeof socketFactory.create !== 'function') {
+        throw ErrorFactory.createConnectionError('Cloudflare socket factory unavailable');
+    }
+    return socketFactory;
+};
+const createNodeSocket = async (config, implicitTls) => {
     validateConfig(config);
     return new Promise((resolve, reject) => {
         const onError = (err) => {
@@ -34,6 +146,16 @@ const createSocket = async (config, implicitTls) => {
                 servername: config.host,
             })
             : net.connect({ host: config.host, port: config.port });
+        if (typeof socket.setTimeout === 'function') {
+            socket.setTimeout(10000);
+        }
+        socket.once('timeout', () => {
+            socket.destroy();
+            reject(ErrorFactory.createConnectionError('SMTP connection timed out', {
+                host: config.host,
+                port: config.port,
+            }));
+        });
         if (implicitTls) {
             socket.once('secureConnect', () => resolve(socket));
         }
@@ -43,9 +165,67 @@ const createSocket = async (config, implicitTls) => {
         socket.once('error', onError);
     });
 };
+const createWorkersSocket = async (config, implicitTls) => {
+    validateConfig(config);
+    return new Promise((resolve, reject) => {
+        let cleanup = () => undefined;
+        const onError = (err) => {
+            cleanup();
+            reject(ErrorFactory.createConnectionError('SMTP connection failed', {
+                host: config.host,
+                port: config.port,
+                secure: implicitTls,
+                error: err,
+            }));
+        };
+        const socketFactoryPromise = loadCloudflareSocketFactory();
+        socketFactoryPromise
+            .then((socketFactory) => {
+            const socket = socketFactory.create(config.host, config.port, {
+                tls: implicitTls,
+            });
+            if (!socket) {
+                reject(ErrorFactory.createConnectionError('SMTP socket initialization failed'));
+                return;
+            }
+            const onConnect = () => {
+                cleanup(socket);
+                resolve(socket);
+            };
+            cleanup = (target) => {
+                if (!target)
+                    return;
+                if (typeof target.off === 'function') {
+                    target.off('connect', onConnect);
+                    target.off('error', onError);
+                }
+                else if (typeof target.removeListener === 'function') {
+                    target.removeListener('connect', onConnect);
+                    target.removeListener('error', onError);
+                }
+            };
+            socket.once('connect', onConnect);
+            socket.once('error', onError);
+        })
+            .catch((err) => {
+            reject(ErrorFactory.createConnectionError('SMTP socket initialization failed', {
+                error: err,
+            }));
+        });
+    });
+};
+const createSocket = async (config, implicitTls) => {
+    if (isWorkersRuntime())
+        return createWorkersSocket(config, implicitTls);
+    return createNodeSocket(config, implicitTls);
+};
 const upgradeToStartTls = async (socket, host) => {
+    if (typeof socket.startTls === 'function') {
+        await socket.startTls();
+        return socket;
+    }
     return new Promise((resolve, reject) => {
-        const tlsSocket = tls.connect({ socket, servername: host });
+        const tlsSocket = tls.connect({ socket: socket, servername: host });
         tlsSocket.once('secureConnect', () => {
             resolve(tlsSocket);
         });
@@ -68,7 +248,8 @@ const createLineReader = (socket) => {
         }
     };
     const onData = (data) => {
-        buffer += data.toString('utf8');
+        const chunk = data instanceof Uint8Array ? data : Buffer.from(String(data));
+        buffer += Buffer.from(chunk).toString('utf8');
         wake();
     };
     socket.on('data', onData);
@@ -84,7 +265,19 @@ const createLineReader = (socket) => {
         const immediate = tryReadLineFromBuffer();
         if (typeof immediate === 'string')
             return immediate;
-        await new Promise((resolve) => waiters.push(resolve));
+        await new Promise((resolve, reject) => {
+            let fired = false;
+            const timer = globalThis.setTimeout(() => {
+                fired = true;
+                reject(ErrorFactory.createConnectionError('SMTP read timeout'));
+            }, 30000);
+            waiters.push(() => {
+                if (fired)
+                    return;
+                clearTimeout(timer);
+                resolve();
+            });
+        });
         return readLine();
     };
     const readMultiline = async (code, message) => {
@@ -112,20 +305,39 @@ const createLineReader = (socket) => {
         return { code, message };
     };
     const close = () => {
-        socket.off('data', onData);
+        if (typeof socket.off === 'function') {
+            socket.off('data', onData);
+        }
     };
     return { readResponse, close };
 };
-const writeLine = async (socket, line) => {
+const writeRaw = async (socket, data) => {
     return new Promise((resolve, reject) => {
-        socket.write(`${line}\r\n`, (err) => {
+        let settled = false;
+        const finish = (err) => {
+            if (settled)
+                return;
+            settled = true;
             if (err)
                 reject(err);
             else
                 resolve();
-        });
+        };
+        try {
+            const writer = socket;
+            writer.write(data, (err) => finish(err));
+            if (writer.write.length < 2) {
+                finish();
+            }
+        }
+        catch (err) {
+            finish(err);
+        }
     });
 };
+const writeLine = async (socket, line) => {
+    return writeRaw(socket, `${line}\r\n`);
+};
 const assertCode = (res, expected, context) => {
     const allowed = Array.isArray(expected) ? expected : [expected];
     if (!allowed.includes(res.code)) {
@@ -213,14 +425,7 @@ const doData = async (socket, reader, message) => {
     assertCode(dataRes, 354, 'DATA');
     const raw = buildRfc2822Message(message);
     const stuffed = dotStuff(raw);
-    await new Promise((resolve, reject) => {
-        socket.write(`${stuffed}\r\n.\r\n`, (err) => {
-            if (err)
-                reject(err);
-            else
-                resolve();
-        });
-    });
+    await writeRaw(socket, `${stuffed}\r\n.\r\n`);
     const queued = await reader.readResponse();
     assertCode(queued, 250, 'message body');
 };
@@ -304,6 +509,12 @@ export const SmtpDriver = Object.freeze({
      * - `secure='starttls'` performs STARTTLS after EHLO.
      */
     async send(config, message) {
+        if (shouldUseProxy()) {
+            const proxyUrl = Env.SMTP_PROXY_URL;
+            Logger.debug('[SmtpDriver] Using SmtpProxy', { proxyUrl });
+            const result = await sendViaProxy(message);
+            return { ok: Boolean(result.ok), provider: 'smtp', messageId: result.messageId };
+        }
         let mode = 'none';
         if (config.secure === true)
             mode = 'tls';

package/src/tools/mail/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tools/mail/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAI7E,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,YAAY,CAAC;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAoJF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAcD,eAAO,MAAM,IAAI;IACf;;OAEG;kBACiB,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAIrD,sBAAsB;gBACJ,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAGnD;;;;OAIG;iBACU,MAAM;cA5Db,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC;;gBAgErC,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;EAGzD,CAAC;AAEH,eAAe,IAAI,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tools/mail/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAI7E,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,YAAY,CAAC;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAgJF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAsBD,eAAO,MAAM,IAAI;IACf;;OAEG;kBACiB,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAIrD,sBAAsB;gBACJ,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAGnD;;;;OAIG;iBACU,MAAM;cAnEb,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC;;gBAuErC,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;EAGzD,CAAC;AAEH,eAAe,IAAI,CAAC"}

package/src/tools/mail/index.js

@@ -70,10 +70,7 @@ const sendWithDriver = async (driver, message) => {
         throw ErrorFactory.createConfigError(`Mail driver not registered: ${driver.driver} (run \`zin add mail:${driver.driver}\` / \`npm i @zintrust/mail-${driver.driver}\`)`);
     }
     // Config exists for future drivers, but implementations are intentionally CLI/runtime-safe and added incrementally.
-    {
-        const err = ErrorFactory.createConfigError(`Mail driver not implemented: ${mailConfig.default}`);
-        throw err;
-    }
+    throw ErrorFactory.createConfigError(`Mail driver not registered: ${mailConfig.default}. Available drivers: ses, sendgrid, mailgun, smtp. Run \`zin add mail:${mailConfig.default}\` to install.`);
 };
 const createMailer = (name) => Object.freeze({
     async send(input) {
@@ -95,10 +92,14 @@ const createMailer = (name) => Object.freeze({
         });
     },
 });
+const looksLikeHtml = (value) => /<\s*html\b|<!doctype\b|<\s*body\b/i.test(value);
 async function renderTemplateToHtml(input) {
     const { template, variables } = input;
     // Import lazily to avoid circular deps
     const { loadTemplate } = await import('./template-loader.js');
+    if (looksLikeHtml(template)) {
+        return loadTemplate(template, (variables ?? {}));
+    }
     // template-loader expects full filename
     const fileName = template.endsWith('.html') ? template : `${template}.html`;
     return loadTemplate(fileName, (variables ?? {}));

package/src/tools/mail/template-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template-loader.d.ts","sourceRoot":"","sources":["../../../../src/tools/mail/template-loader.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9D;;GAEG;AACH,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,iBAAsB,GAChC,OAAO,CAAC,MAAM,CAAC,CA6CjB;AAuDD;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAShD"}
+{"version":3,"file":"template-loader.d.ts","sourceRoot":"","sources":["../../../../src/tools/mail/template-loader.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAoM9D;;GAEG;AACH,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,iBAAsB,GAChC,OAAO,CAAC,MAAM,CAAC,CAwBjB;AA2FD;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAShD"}

package/src/tools/mail/template-loader.js

@@ -1,37 +1,173 @@
 import { ErrorFactory } from '../../exceptions/ZintrustError.js';
 import { readFile } from '../../node-singletons/fs.js';
 import { dirname, join } from '../../node-singletons/path.js';
-import { fileURLToPath } from '../../node-singletons/url.js';
+import { fileURLToPath, pathToFileURL } from '../../node-singletons/url.js';
 import { Env } from '../../config/env.js';
 import { interpolate } from './template-utils.js';
+const looksLikeHtml = (value) => /<\s*html\b|<!doctype\b|<\s*body\b/i.test(value);
+const builtinTemplateLoaders = Object.freeze({
+    'auth-password-reset': async () => import('./templates/auth-password-reset.js'),
+    'auth-welcome': async () => import('./templates/auth-welcome.js'),
+    general: async () => import('./templates/general.js'),
+    'job-completed': async () => import('./templates/job-completed.js'),
+    'notifications-new-comment': async () => import('./templates/notifications-new-comment.js'),
+    'password-reset': async () => import('./templates/password-reset.js'),
+    'performance-report': async () => import('./templates/performance-report.js'),
+    welcome: async () => import('./templates/welcome.js'),
+    'worker-alert': async () => import('./templates/worker-alert.js'),
+});
+const getSafeCwd = () => {
+    try {
+        if (typeof process !== 'undefined' && typeof process.cwd === 'function') {
+            const cwd = process.cwd();
+            if (typeof cwd === 'string' && cwd.trim() !== '')
+                return cwd;
+        }
+    }
+    catch {
+        return '';
+    }
+    return '';
+};
 /**
- * Load and render email template with variable substitution
+ * Get the base directory for templates.
+ * In Cloudflare Workers, import.meta.url may be undefined, so we handle that case.
  */
-export async function loadTemplate(templateName, variables = {}) {
+function getBaseDir() {
     try {
-        const baseDir = dirname(fileURLToPath(import.meta.url));
-        const isPath = templateName.includes('/') || templateName.endsWith('.html');
-        let templatePath;
-        if (isPath) {
-            if (templateName.startsWith('/')) {
-                templatePath = templateName;
-            }
-            else {
-                templatePath = join(process.cwd(), templateName);
-            }
+        // Check if import.meta.url is available (Node.js, Deno, modern bundlers)
+        if (typeof import.meta.url === 'string' && import.meta.url.trim() !== '') {
+            return dirname(fileURLToPath(import.meta.url));
+        }
+    }
+    catch {
+        // Fallback for environments where fileURLToPath fails
+    }
+    // Fallback: use cwd if available
+    const cwd = getSafeCwd();
+    if (cwd.trim() !== '') {
+        return join(cwd, 'src', 'tools', 'mail');
+    }
+    // Last resort: return a relative path that might work
+    return './src/tools/mail';
+}
+function resolveTemplatePath(templateName) {
+    const baseDir = getBaseDir();
+    const isPath = templateName.includes('/') || templateName.endsWith('.html');
+    if (!isPath) {
+        return join(baseDir, 'templates', `${templateName}.html`);
+    }
+    if (templateName.startsWith('/')) {
+        return templateName;
+    }
+    const cwd = getSafeCwd();
+    return cwd.trim() === '' ? join(baseDir, templateName) : join(cwd, templateName);
+}
+function normalizeTemplateName(templateName) {
+    return {
+        normalizedTemplate: templateName.endsWith('.html') ? templateName : `${templateName}.html`,
+        normalizedModuleName: templateName.endsWith('.html') ? templateName.slice(0, -5) : templateName,
+    };
+}
+async function tryBuiltinLoader(normalizedModuleName) {
+    const builtinLoader = builtinTemplateLoaders[normalizedModuleName];
+    if (builtinLoader === undefined) {
+        return null;
+    }
+    try {
+        const imported = (await builtinLoader());
+        if (typeof imported.default === 'string' && imported.default.trim() !== '') {
+            return imported.default;
+        }
+    }
+    catch {
+        // Fall through to filesystem/module path probes.
+    }
+    return null;
+}
+function getFileCandidates(templatePath, normalizedTemplate) {
+    const cwd = getSafeCwd();
+    const baseDir = getBaseDir();
+    return [
+        templatePath,
+        join(baseDir, 'templates', normalizedTemplate),
+        join(cwd, 'dist', 'src', 'tools', 'mail', 'templates', normalizedTemplate),
+        join(cwd, 'src', 'tools', 'mail', 'templates', normalizedTemplate),
+    ].filter((path, index, arr) => path.trim() !== '' && arr.indexOf(path) === index);
+}
+function getModuleCandidates(normalizedModuleName) {
+    const cwd = getSafeCwd();
+    const baseDir = getBaseDir();
+    return [
+        join(cwd, 'dist', 'src', 'tools', 'mail', 'templates', `${normalizedModuleName}.js`),
+        join(cwd, 'src', 'tools', 'mail', 'templates', `${normalizedModuleName}.ts`),
+        join(baseDir, 'templates', `${normalizedModuleName}.js`),
+        join(baseDir, 'templates', `${normalizedModuleName}.ts`),
+    ].filter((path, index, arr) => path.trim() !== '' && arr.indexOf(path) === index);
+}
+async function tryReadFromCandidates(candidates) {
+    let lastError;
+    for (const candidate of candidates) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            const content = await readFile(candidate, 'utf-8');
+            return { content };
         }
-        else {
-            templatePath = join(baseDir, 'templates', `${templateName}.html`);
+        catch (error) {
+            lastError = error;
         }
-        let template;
+    }
+    return { error: lastError };
+}
+async function tryImportFromCandidates(moduleCandidates) {
+    let lastError;
+    for (const modulePath of moduleCandidates) {
         try {
-            template = await readFile(templatePath, 'utf-8');
+            // eslint-disable-next-line no-await-in-loop
+            const imported = (await import(pathToFileURL(modulePath).href));
+            if (typeof imported.default === 'string' && imported.default.trim() !== '') {
+                return { content: imported.default };
+            }
         }
-        catch {
-            // Fallback to built-in directory if the supplied name looked like a file but wasn't found
-            const fallbackPath = join(baseDir, 'templates', templateName.endsWith('.html') ? templateName : `${templateName}.html`);
-            template = await readFile(fallbackPath, 'utf-8');
+        catch (error) {
+            lastError = error;
         }
+    }
+    return { error: lastError };
+}
+async function loadTemplateContent(templateName) {
+    const templatePath = resolveTemplatePath(templateName);
+    const { normalizedTemplate, normalizedModuleName } = normalizeTemplateName(templateName);
+    // Try builtin loader first
+    const builtinResult = await tryBuiltinLoader(normalizedModuleName);
+    if (builtinResult !== null && typeof builtinResult === 'string') {
+        return builtinResult;
+    }
+    // Try file system candidates
+    const fileCandidates = getFileCandidates(templatePath, normalizedTemplate);
+    const fileResult = await tryReadFromCandidates(fileCandidates);
+    if (fileResult.content !== undefined) {
+        return fileResult.content;
+    }
+    // Try module candidates
+    const moduleCandidates = getModuleCandidates(normalizedModuleName);
+    const moduleResult = await tryImportFromCandidates(moduleCandidates);
+    if (moduleResult.content !== undefined) {
+        return moduleResult.content;
+    }
+    // Extract last error from failed attempts
+    const lastError = fileResult.error ?? moduleResult.error;
+    throw ErrorFactory.createConfigError(`Failed to load template from known paths: ${[...fileCandidates, ...moduleCandidates].join(', ')}` +
+        (lastError === undefined ? '' : `. Last error: ${String(lastError)}`));
+}
+/**
+ * Load and render email template with variable substitution
+ */
+export async function loadTemplate(templateName, variables = {}) {
+    try {
+        const template = looksLikeHtml(templateName)
+            ? templateName
+            : await loadTemplateContent(templateName);
         // Replace variables using shared interpolate util
         const mergedVars = {
             year: new Date().getFullYear().toString(),
@@ -53,21 +189,16 @@ export async function loadTemplate(templateName, variables = {}) {
  * Render conditional blocks {{#if_condition}}...{{/if_condition}}
  */
 function renderConditionals(template, variables) {
-    const conditionalRegex = /{{#if_(\w+)}}(.+?){{\/if_\1}}/gs;
-    return template.replaceAll(conditionalRegex, (_fullMatch, condition, content) => {
+    return renderBlockTags(template, 'if', (condition, content) => {
         const value = variables[condition];
-        if (value === true || value === 'true') {
-            return content;
-        }
-        return '';
+        return value === true || value === 'true' ? content : '';
     });
 }
 /**
  * Render loop blocks {{#each_array}}...{{/each_array}}
  */
 function renderLoops(template, variables) {
-    const loopRegex = /{{#each_(\w+)}}(.+?){{\/each_\1}}/gs;
-    return template.replaceAll(loopRegex, (_fullMatch, arrayName, content) => {
+    return renderBlockTags(template, 'each', (arrayName, content) => {
         const array = variables[arrayName];
         if (!Array.isArray(array)) {
             return '';
@@ -86,6 +217,43 @@ function renderLoops(template, variables) {
             .join('');
     });
 }
+const isSafeBlockName = (value) => /^\w+$/.test(value);
+const renderBlockTags = (template, tagPrefix, resolver) => {
+    const openPrefix = `{{#${tagPrefix}_`;
+    let cursor = 0;
+    let output = '';
+    while (cursor < template.length) {
+        const openIndex = template.indexOf(openPrefix, cursor);
+        if (openIndex < 0) {
+            output += template.slice(cursor);
+            break;
+        }
+        output += template.slice(cursor, openIndex);
+        const nameStart = openIndex + openPrefix.length;
+        const openEnd = template.indexOf('}}', nameStart);
+        if (openEnd < 0) {
+            output += template.slice(openIndex);
+            break;
+        }
+        const name = template.slice(nameStart, openEnd);
+        if (!isSafeBlockName(name)) {
+            output += template.slice(openIndex, openEnd + 2);
+            cursor = openEnd + 2;
+            continue;
+        }
+        const closeToken = `{{/${tagPrefix}_${name}}}`;
+        const contentStart = openEnd + 2;
+        const closeIndex = template.indexOf(closeToken, contentStart);
+        if (closeIndex < 0) {
+            output += template.slice(openIndex);
+            break;
+        }
+        const content = template.slice(contentStart, closeIndex);
+        output += resolver(name, content);
+        cursor = closeIndex + closeToken.length;
+    }
+    return output;
+};
 /**
  * Get list of available templates
  */

package/src/tools/mail/templates/auth-password-reset.d.ts

@@ -0,0 +1,3 @@
+declare const _default: "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"UTF-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n    <meta http-equiv=\"X-UA-Compatible\" content=\"IE=edge\" />\n    <title>Password Reset Request</title>\n    <style>\n      body {\n        margin: 0;\n        padding: 0;\n        background-color: #0b1220;\n        color: #e2e8f0;\n        font-family:\n          -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;\n      }\n\n      .email-container {\n        max-width: 600px;\n        margin: 40px auto;\n        background-color: #0f172a;\n        border: 1px solid #334155;\n        border-radius: 12px;\n        overflow: hidden;\n      }\n\n      .header {\n        padding: 40px 40px 30px;\n        text-align: center;\n        background: linear-gradient(180deg, rgba(239, 68, 68, 0.15), rgba(220, 38, 38, 0.08));\n        border-bottom: 1px solid #334155;\n      }\n\n      .icon {\n        width: 48px;\n        height: 48px;\n        margin: 0 auto 20px;\n        border-radius: 12px;\n        border: 1px solid rgba(239, 68, 68, 0.35);\n        background: linear-gradient(180deg, rgba(239, 68, 68, 0.2), rgba(220, 38, 38, 0.1));\n        display: inline-flex;\n        align-items: center;\n        justify-content: center;\n      }\n\n      .title {\n        margin: 0 0 8px;\n        font-size: 28px;\n        font-weight: 700;\n        color: #e2e8f0;\n        line-height: 1.2;\n      }\n\n      .subtitle {\n        margin: 0;\n        font-size: 16px;\n        color: #e2e8f0;\n        line-height: 1.5;\n      }\n\n      .content {\n        padding: 40px;\n      }\n\n      .greeting {\n        margin: 0 0 24px;\n        font-size: 15px;\n        color: #f1f5f9;\n        line-height: 1.6;\n      }\n\n      .message {\n        margin: 0 0 24px;\n        font-size: 15px;\n        color: #f1f5f9;\n        line-height: 1.6;\n      }\n\n      .button-container {\n        margin-bottom: 30px;\n        text-align: center;\n      }\n\n      .reset-button {\n        display: inline-block;\n        padding: 14px 32px;\n        background: linear-gradient(135deg, #ef4444, #dc2626);\n        color: #ffffff;\n        text-decoration: none;\n        border-radius: 8px;\n        font-weight: 600;\n        font-size: 15px;\n        border: 1px solid rgba(217, 82, 82, 0.8);\n      }\n\n      .security-notice {\n        padding: 16px;\n        background: rgba(251, 191, 36, 0.08);\n        border-left: 3px solid #fbbf24;\n        border-radius: 6px;\n        margin-bottom: 30px;\n      }\n\n      .security-notice p {\n        margin: 0;\n        font-size: 14px;\n        color: #e2e8f0;\n        line-height: 1.6;\n      }\n\n      .security-notice strong {\n        color: #fbbf24;\n      }\n\n      .expiry {\n        margin: 0 0 16px;\n        font-size: 14px;\n        color: #e2e8f0;\n        line-height: 1.6;\n      }\n\n      .expiry strong {\n        color: #e2e8f0;\n      }\n\n      .alternative-link {\n        margin: 0;\n        font-size: 13px;\n        color: #e2e8f0;\n        line-height: 1.6;\n      }\n\n      .alternative-link a {\n        color: #bae6fd;\n        text-decoration: none;\n        word-break: break-all;\n      }\n\n      .divider {\n        margin: 30px 0;\n        border-top: 1px solid #334155;\n      }\n\n      .support {\n        margin: 0;\n        font-size: 14px;\n        color: #e2e8f0;\n        line-height: 1.6;\n      }\n\n      .support a {\n        color: #bae6fd;\n        text-decoration: none;\n      }\n\n      .footer {\n        padding: 30px 40px;\n        background: rgba(15, 23, 42, 0.65);\n        border-top: 1px solid #334155;\n        text-align: center;\n      }\n\n      .footer p {\n        margin: 0;\n        font-size: 12px;\n        color: #64748b;\n      }\n    </style>\n  </head>\n  <body>\n    <div class=\"email-container\">\n      <!-- Header -->\n      <div class=\"header\">\n        <div class=\"icon\">\n          <span style=\"font-size: 24px\">\uD83D\uDD12</span>\n        </div>\n        <h1 class=\"title\">Password Reset Request</h1>\n        <p class=\"subtitle\">We received a request to reset your password</p>\n      </div>\n\n      <!-- Main Content -->\n      <div class=\"content\">\n        <p class=\"greeting\">Hi <strong style=\"color: #e2e8f0\">{{name}}</strong>,</p>\n\n        <p class=\"message\">\n          Someone requested a password reset for your {{APP_NAME}} account (<strong\n            style=\"color: #e2e8f0\"\n            >{{email}}</strong\n          >). If this was you, click the button below to reset your password:\n        </p>\n\n        <!-- CTA Button -->\n        <div class=\"button-container\">\n          <a href=\"{{reset_url}}\" class=\"reset-button\">Reset Password</a>\n        </div>\n\n        <!-- Security Notice -->\n        <div class=\"security-notice\">\n          <p>\n            <strong>\u26A0 Security Notice</strong><br />\n            If you didn't request this password reset, please ignore this email. Your password will\n            remain unchanged.\n          </p>\n        </div>\n\n        <p class=\"expiry\">\n          For security reasons, this link will expire in <strong>{{expiryMinutes}} minutes</strong>.\n        </p>\n\n        <!-- Alternative Link -->\n        <p class=\"alternative-link\">\n          If the button above doesn't work, copy and paste this link into your browser:<br />\n          <a href=\"{{reset_url}}\">{{reset_url}}</a>\n        </p>\n\n        <!-- Divider -->\n        <div class=\"divider\"></div>\n\n        <p class=\"support\">\n          If you continue to have problems, please contact our\n          <a href=\"{{support_url}}\">support team</a>.\n        </p>\n      </div>\n\n      <!-- Footer -->\n      <div class=\"footer\">\n        <p>&copy; {{year}} {{APP_NAME}}. All rights reserved.</p>\n      </div>\n    </div>\n  </body>\n</html>";
+export default _default;
+//# sourceMappingURL=auth-password-reset.d.ts.map

package/src/tools/mail/templates/auth-password-reset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-password-reset.d.ts","sourceRoot":"","sources":["../../../../../src/tools/mail/templates/auth-password-reset.ts"],"names":[],"mappings":";AAAA,wBAsOS"}