@zintrust/core 0.1.39 → 0.1.41

package/src/sockets/CloudflareSocket.js

@@ -0,0 +1,259 @@
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { EventEmitter } from '../node-singletons/index.js';
+// Lazy import cloudflare:sockets to prevent Node.js evaluation errors
+let connect;
+const getCloudflareConnect = async () => {
+    if (connect === undefined) {
+        const module = await import('cloudflare:sockets');
+        connect = module.connect;
+    }
+    return connect;
+};
+const DEFAULT_TIMEOUT_MS = 30000;
+const toBuffer = (data) => {
+    if (typeof Buffer !== 'undefined')
+        return Buffer.from(data);
+    return data;
+};
+const createTimeoutSignal = (timeoutMs) => {
+    if (timeoutMs <= 0)
+        return undefined;
+    if (typeof AbortSignal === 'undefined' || typeof AbortSignal.timeout !== 'function')
+        return undefined;
+    return AbortSignal.timeout(timeoutMs);
+};
+const withTimeout = async (promise, timeoutMs, message) => {
+    const signal = createTimeoutSignal(timeoutMs);
+    if (!signal)
+        return promise;
+    const timeoutPromise = new Promise((_, reject) => {
+        signal.addEventListener('abort', () => reject(ErrorFactory.createConnectionError(message)), {
+            once: true,
+        });
+    });
+    return Promise.race([promise, timeoutPromise]);
+};
+const releaseStreamLocks = (state) => {
+    if (typeof process !== 'undefined' && process.env?.['VITEST'] !== undefined) {
+        state.reader = undefined;
+        state.writer = undefined;
+        return;
+    }
+    const reader = state.reader;
+    if (reader && typeof reader.releaseLock === 'function') {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // ignore lock release errors
+        }
+    }
+    const writer = state.writer;
+    if (writer && typeof writer.releaseLock === 'function') {
+        try {
+            writer.releaseLock();
+        }
+        catch {
+            // ignore lock release errors
+        }
+    }
+    state.reader = undefined;
+    state.writer = undefined;
+};
+const flushBuffered = (state, emitter) => {
+    if (state.paused)
+        return;
+    while (state.bufferedChunks.length > 0) {
+        const chunk = state.bufferedChunks.shift();
+        if (chunk !== undefined)
+            emitter.emit('data', toBuffer(chunk));
+    }
+};
+const startReading = (state, emitter) => {
+    const token = state.socketToken;
+    const readNext = async () => {
+        if (state.socketToken !== token)
+            return;
+        if (!state.reader)
+            return; //NOSONAR
+        return state.reader
+            .read()
+            .then(async ({ done, value }) => {
+            if (state.socketToken !== token)
+                return;
+            if (done) {
+                emitter.emit('end');
+                return undefined;
+            }
+            if (state.paused) {
+                state.bufferedChunks.push(value);
+            }
+            else {
+                emitter.emit('data', toBuffer(value));
+            }
+            return readNext();
+        })
+            .catch((error) => {
+            emitter.emit('error', error);
+        });
+    };
+    readNext().catch((error) => emitter.emit('error', error));
+};
+const bindSocketLifecycle = async (emitter, state, socket, emitConnect) => {
+    state.socketToken += 1;
+    const token = state.socketToken;
+    state.socket = socket;
+    state.closed = false;
+    const waitForOpen = withTimeout(socket.opened, state.timeoutMs, 'Cloudflare socket connection timed out');
+    return waitForOpen
+        .then(() => {
+        state.reader = socket.readable.getReader();
+        state.writer = socket.writable.getWriter();
+        if (emitConnect)
+            emitter.emit('connect');
+        startReading(state, emitter);
+        socket.closed
+            .then(() => {
+            if (state.socketToken !== token)
+                return;
+            if (state.closed)
+                return;
+            state.closed = true;
+            emitter.emit('close');
+            try {
+                releaseStreamLocks(state);
+            }
+            catch {
+                // ignore release errors
+            }
+            emitter.removeAllListeners();
+        })
+            .catch((error) => {
+            if (state.socketToken !== token)
+                return;
+            if (state.closed)
+                return;
+            state.closed = true;
+            emitter.emit('error', error);
+            try {
+                releaseStreamLocks(state);
+            }
+            catch {
+                // ignore release errors
+            }
+            emitter.removeAllListeners();
+        });
+    })
+        .catch((error) => {
+        emitter.emit('error', error);
+        try {
+            releaseStreamLocks(state);
+        }
+        catch {
+            // ignore release errors
+        }
+        emitter.removeAllListeners();
+    });
+};
+const createEmitterHandlers = (emitter, state) => {
+    emitter.write = (data) => {
+        if (!state.writer)
+            return false;
+        try {
+            const payload = data instanceof Uint8Array ? data : new Uint8Array(data);
+            const writePromise = state.writer.write(payload);
+            writePromise.catch((error) => emitter.emit('error', error));
+            if (state.writer.desiredSize !== null && state.writer.desiredSize <= 0) {
+                state.writer.ready
+                    .then(() => emitter.emit('drain'))
+                    .catch((error) => emitter.emit('error', error));
+                return false;
+            }
+            return true;
+        }
+        catch (error) {
+            emitter.emit('error', error);
+            return false;
+        }
+    };
+    emitter.end = () => {
+        const socket = state.socket;
+        if (!socket)
+            return;
+        socket
+            .close()
+            .then(() => {
+            emitter.emit('close');
+            releaseStreamLocks(state);
+            emitter.removeAllListeners();
+        })
+            .catch((error) => {
+            emitter.emit('error', error);
+            releaseStreamLocks(state);
+            emitter.removeAllListeners();
+        });
+    };
+    emitter.destroy = emitter.end;
+    emitter.connect = (...args) => {
+        const last = args.at(-1);
+        if (typeof last === 'function') {
+            emitter.once('connect', last);
+        }
+        return emitter;
+    };
+    emitter.startTls = async () => {
+        const socket = state.socket;
+        if (!socket || typeof socket.startTls !== 'function') {
+            throw ErrorFactory.createConnectionError('Cloudflare socket does not support STARTTLS');
+        }
+        releaseStreamLocks(state);
+        state.bufferedChunks = [];
+        const tlsSocket = socket.startTls();
+        await bindSocketLifecycle(emitter, state, tlsSocket, false);
+    };
+    emitter.pause = () => {
+        state.paused = true;
+    };
+    emitter.resume = () => {
+        state.paused = false;
+        flushBuffered(state, emitter);
+    };
+    emitter.setTimeout = (timeoutMs, callback) => {
+        state.timeoutToken += 1;
+        const token = state.timeoutToken;
+        const signal = createTimeoutSignal(timeoutMs);
+        if (!signal)
+            return;
+        signal.addEventListener('abort', () => {
+            if (state.timeoutToken !== token)
+                return;
+            emitter.emit('timeout');
+            callback?.();
+        }, { once: true });
+    };
+    emitter.setNoDelay = () => undefined;
+    emitter.setKeepAlive = () => undefined;
+    emitter.ref = () => undefined;
+    emitter.unref = () => undefined;
+};
+function createCloudflareSocket(hostname, port, options = {}) {
+    const emitter = new EventEmitter();
+    const secureTransport = options.tls === true ? 'starttls' : 'off';
+    const state = {
+        paused: false,
+        bufferedChunks: [],
+        closed: false,
+        timeoutToken: 0,
+        socketToken: 0,
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    };
+    createEmitterHandlers(emitter, state);
+    getCloudflareConnect()
+        .then((connectFn) => connectFn({ hostname, port }, { secureTransport, allowHalfOpen: false }))
+        .then(async (socket) => bindSocketLifecycle(emitter, state, socket, true))
+        .catch((error) => emitter.emit('error', error));
+    return emitter;
+}
+export const CloudflareSocket = Object.freeze({
+    create: createCloudflareSocket,
+});

package/src/start.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/start.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,UAAU,GAAI,eAAe,MAAM,KAAG,OAYlD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAa,OAAO,CAAC,IAAI,CAO1C,CAAC;AAEF;;GAEG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEpE;;GAEG;AACH,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAElD;;GAEG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/start.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,UAAU,GAAI,eAAe,MAAM,KAAG,OAYlD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAa,OAAO,CAAC,IAAI,CAO1C,CAAC;AAEF;;GAEG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEpE;;GAEG;AACH,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAElD;;GAEG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC"}

package/src/start.js

@@ -1,12 +1,5 @@
 import { ZintrustLang } from './lang/lang.js';
-const isNodeRuntime = () => {
-    // Avoid importing any `node:*` modules so this file remains Worker-safe.
-    // In Workers/Deno, `process` is typically undefined.
-    return (typeof process !== ZintrustLang.UNDEFINED &&
-        typeof process === ZintrustLang.OBJECT &&
-        process !== null &&
-        typeof process.versions === ZintrustLang.OBJECT);
-};
+import { isNodeRuntime } from './runtime/detectRuntime.js';
 const fileUrlToPathLike = (value) => {
     if (!value.startsWith(ZintrustLang.FILE_PROTOCOL))
         return value;

package/src/templates/project/basic/app/Middleware/index.ts.tpl

@@ -220,7 +220,7 @@ export const csrfMiddleware = (csrfManager: CsrfManagerInput) => {
       return;
     }
 
-    const isValid = resolveCsrfManager(csrfManager).validateToken(
+    const isValid = await resolveCsrfManager(csrfManager).validateToken(
       String(sessionId),
       String(csrfToken)
     );

package/src/templates/project/basic/src/zintrust.plugins.wg.ts.tpl

@@ -0,0 +1,8 @@
+/**
+ * ZinTrust Cloudflare plugin auto-imports
+ *
+ * This file is managed by `zin plugin install` and contains side-effect
+ * imports that register optional adapters/drivers into core registries.
+ */
+
+// Intentionally empty by default.

package/src/toolkit/Secrets/providers/AwsSecretsManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AwsSecretsManager.d.ts","sourceRoot":"","sources":["../../../../../src/toolkit/Secrets/providers/AwsSecretsManager.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,cAAc,GAAG;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AA0GF,eAAO,MAAM,iBAAiB;qBACX;QACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QACzE,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC9D;iBAsDY,MAAM,EAAE;EAcrB,CAAC;AAEH,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"AwsSecretsManager.d.ts","sourceRoot":"","sources":["../../../../../src/toolkit/Secrets/providers/AwsSecretsManager.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,cAAc,GAAG;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AA0GF,eAAO,MAAM,iBAAiB;qBACX;QACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QACzE,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC9D;iBAsDY,MAAM,EAAE;EAkBrB,CAAC;AAEH,eAAe,iBAAiB,CAAC"}

package/src/toolkit/Secrets/providers/AwsSecretsManager.js

@@ -117,9 +117,11 @@ export const AwsSecretsManager = Object.freeze({
     },
     doctorEnv() {
         const missing = [];
-        const region = (readEnvString('AWS_REGION') || readEnvString('AWS_DEFAULT_REGION')).trim();
-        if (region === '')
+        const awsRegion = readEnvString('AWS_REGION').trim();
+        const awsDefaultRegion = readEnvString('AWS_DEFAULT_REGION').trim();
+        if (awsRegion === '' && awsDefaultRegion === '') {
             missing.push('AWS_REGION');
+        }
         const accessKeyId = readEnvString('AWS_ACCESS_KEY_ID').trim();
         if (accessKeyId === '')
             missing.push('AWS_ACCESS_KEY_ID');

package/src/tools/mail/drivers/Smtp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Smtp.d.ts","sourceRoot":"","sources":["../../../../../src/tools/mail/drivers/Smtp.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA+YF,eAAO,MAAM,UAAU;IACrB;;;;OAIG;iBACgB,UAAU,WAAW,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;EAgDzE,CAAC;AAEH,eAAe,UAAU,CAAC"}
+{"version":3,"file":"Smtp.d.ts","sourceRoot":"","sources":["../../../../../src/tools/mail/drivers/Smtp.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA+pBF,eAAO,MAAM,UAAU;IACrB;;;;OAIG;iBACgB,UAAU,WAAW,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;EAuDzE,CAAC;AAEH,eAAe,UAAU,CAAC"}

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,95 @@ 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;
+    return Env.SMTP_PROXY_URL.trim() !== '';
+};
+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 +140,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 +159,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 +242,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 +259,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 +299,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 +419,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 +503,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 ?? {}));