@zintrust/core 0.1.26 → 0.1.28

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

@@ -0,0 +1,490 @@
+import { generateUuid } from '@/common/utility';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+import * as net from '@node-singletons/net';
+import * as tls from '@node-singletons/tls';
+
+export type SmtpConfig = {
+  host: string;
+  port: number;
+  username?: string;
+  password?: string;
+  secure?: boolean | 'starttls';
+};
+
+export type MailAddress = {
+  email: string;
+  name?: string;
+};
+
+export type MailAttachment = { filename: string; content: Buffer };
+
+export type MailMessage = {
+  to: string | string[];
+  from: MailAddress;
+  subject: string;
+  text: string;
+  html?: string;
+  attachments?: MailAttachment[];
+};
+
+export type SendResult = {
+  ok: boolean;
+  provider: 'smtp';
+  messageId?: string;
+};
+
+type SmtpResponse = {
+  code: number;
+  message: string;
+};
+
+const normalizeRecipients = (to: string | string[]): string[] => (Array.isArray(to) ? to : [to]);
+
+const toBase64 = (value: string): string => Buffer.from(value, 'utf8').toString('base64');
+
+const isNodeRuntime = (): boolean =>
+  typeof process !== 'undefined' && typeof process.versions?.node === 'string';
+
+const validateConfig = (config: SmtpConfig): void => {
+  if (!isNodeRuntime()) {
+    throw ErrorFactory.createConfigError('SMTP driver requires Node.js runtime');
+  }
+
+  if (config.host.trim() === '') {
+    throw ErrorFactory.createConfigError('SMTP: missing MAIL_HOST');
+  }
+
+  if (!Number.isFinite(config.port) || config.port <= 0) {
+    throw ErrorFactory.createConfigError('SMTP: invalid MAIL_PORT');
+  }
+};
+
+const createSocket = async (config: SmtpConfig, implicitTls: boolean): Promise<net.Socket> => {
+  validateConfig(config);
+
+  return new Promise((resolve, reject) => {
+    const onError = (err: unknown): void => {
+      reject(
+        ErrorFactory.createConnectionError('SMTP connection failed', {
+          host: config.host,
+          port: config.port,
+          secure: implicitTls,
+          error: err,
+        })
+      );
+    };
+
+    const socket = implicitTls
+      ? (tls.connect({
+          host: config.host,
+          port: config.port,
+          servername: config.host,
+        }) as unknown as net.Socket)
+      : net.connect({ host: config.host, port: config.port });
+
+    if (implicitTls) {
+      (socket as unknown as tls.TLSSocket).once('secureConnect', () => resolve(socket));
+    } else {
+      socket.once('connect', () => resolve(socket));
+    }
+
+    socket.once('error', onError);
+  });
+};
+
+const upgradeToStartTls = async (socket: net.Socket, host: string): Promise<net.Socket> => {
+  return new Promise((resolve, reject) => {
+    const tlsSocket = tls.connect({ socket, servername: host });
+
+    tlsSocket.once('secureConnect', () => {
+      resolve(tlsSocket as unknown as net.Socket);
+    });
+
+    tlsSocket.once('error', (err) => {
+      reject(
+        ErrorFactory.createConnectionError('SMTP STARTTLS upgrade failed', {
+          host,
+          error: err,
+        })
+      );
+    });
+  });
+};
+
+const createLineReader = (
+  socket: net.Socket
+): {
+  readResponse: () => Promise<SmtpResponse>;
+  close: () => void;
+} => {
+  let buffer = '';
+  const waiters: Array<() => void> = [];
+
+  const wake = (): void => {
+    while (waiters.length > 0) {
+      const w = waiters.shift();
+      if (w) w();
+    }
+  };
+
+  const onData = (data: Buffer): void => {
+    buffer += data.toString('utf8');
+    wake();
+  };
+
+  socket.on('data', onData);
+
+  const tryReadLineFromBuffer = (): string | undefined => {
+    const idx = buffer.indexOf('\n');
+    if (idx < 0) return undefined;
+    const line = buffer.slice(0, idx + 1);
+    buffer = buffer.slice(idx + 1);
+    return line.replace(/\r?\n$/, '');
+  };
+
+  const readLine = async (): Promise<string> => {
+    const immediate = tryReadLineFromBuffer();
+    if (typeof immediate === 'string') return immediate;
+    await new Promise<void>((resolve) => waiters.push(resolve));
+    return readLine();
+  };
+
+  const readMultiline = async (code: number, message: string): Promise<string> => {
+    const line = await readLine();
+    const nextCodeStr = line.slice(0, 3);
+    const nextCode = Number.parseInt(nextCodeStr, 10);
+    const nextMsg = line.length > 4 ? line.slice(4) : '';
+    const nextMessage = `${message}\n${nextMsg}`.trim();
+
+    if (Number.isFinite(nextCode) && nextCode === code && line[3] === ' ') return nextMessage;
+    return readMultiline(code, nextMessage);
+  };
+
+  const readResponse = async (): Promise<SmtpResponse> => {
+    const first = await readLine();
+    const codeStr = first.slice(0, 3);
+    const code = Number.parseInt(codeStr, 10);
+    if (!Number.isFinite(code)) {
+      throw ErrorFactory.createConnectionError('SMTP: invalid response code', { first });
+    }
+
+    let message = first.length > 4 ? first.slice(4) : '';
+
+    // Multiline response: "250-..." then "250 ..."
+    if (first[3] === '-') {
+      message = await readMultiline(code, message);
+    }
+
+    return { code, message };
+  };
+
+  const close = (): void => {
+    socket.off('data', onData);
+  };
+
+  return { readResponse, close };
+};
+
+const writeLine = async (socket: net.Socket, line: string): Promise<void> => {
+  return new Promise((resolve, reject) => {
+    socket.write(`${line}\r\n`, (err?: Error | null) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+};
+
+const assertCode = (res: SmtpResponse, expected: number | number[], context: string): void => {
+  const allowed = Array.isArray(expected) ? expected : [expected];
+  if (!allowed.includes(res.code)) {
+    throw ErrorFactory.createConnectionError(`SMTP: unexpected response for ${context}`, {
+      expected: allowed,
+      got: res.code,
+      message: res.message,
+    });
+  }
+};
+
+const hasCapability = (res: SmtpResponse, capability: string): boolean => {
+  const cap = capability.trim().toUpperCase();
+  if (cap === '') return false;
+  return res.message
+    .split('\n')
+    .some(
+      (line) => line.trim().toUpperCase().startsWith(cap) || line.trim().toUpperCase().includes(cap)
+    );
+};
+
+const doEhlo = async (
+  socket: net.Socket,
+  reader: ReturnType<typeof createLineReader>
+): Promise<SmtpResponse> => {
+  await writeLine(socket, 'EHLO zintrust');
+  const res = await reader.readResponse();
+  assertCode(res, 250, 'EHLO');
+  return res;
+};
+
+const doAuthLoginIfNeeded = async (
+  socket: net.Socket,
+  reader: ReturnType<typeof createLineReader>,
+  config: SmtpConfig
+): Promise<void> => {
+  const username = config.username ?? '';
+  const password = config.password ?? '';
+
+  const wantsAuth = username.trim() !== '' || password.trim() !== '';
+  if (!wantsAuth) return;
+
+  if (username.trim() === '' || password.trim() === '') {
+    throw ErrorFactory.createConfigError('SMTP: both MAIL_USERNAME and MAIL_PASSWORD are required');
+  }
+
+  // Try AUTH PLAIN first (more widely supported)
+  try {
+    // AUTH PLAIN format: base64("\0username\0password")
+    const authPlainString = `\0${username}\0${password}`;
+    const authPlainEncoded = toBase64(authPlainString);
+
+    await writeLine(socket, `AUTH PLAIN ${authPlainEncoded}`);
+    const authPlain = await reader.readResponse();
+    assertCode(authPlain, 235, 'AUTH PLAIN');
+    return; // Success!
+  } catch (plainError) {
+    // AUTH PLAIN failed, try AUTH LOGIN as fallback
+    try {
+      await writeLine(socket, 'AUTH LOGIN');
+      const auth1 = await reader.readResponse();
+      assertCode(auth1, 334, 'AUTH LOGIN');
+
+      await writeLine(socket, toBase64(username));
+      const auth2 = await reader.readResponse();
+      assertCode(auth2, 334, 'AUTH username');
+
+      await writeLine(socket, toBase64(password));
+      const auth3 = await reader.readResponse();
+      assertCode(auth3, 235, 'AUTH password');
+    } catch (loginError) {
+      // Both methods failed, throw the original error
+      throw ErrorFactory.createConnectionError('SMTP authentication failed', {
+        error: plainError,
+        loginError,
+      });
+    }
+  }
+};
+
+const doMailFrom = async (
+  socket: net.Socket,
+  reader: ReturnType<typeof createLineReader>,
+  fromEmail: string
+): Promise<void> => {
+  await writeLine(socket, `MAIL FROM:<${fromEmail}>`);
+  const mailFrom = await reader.readResponse();
+  assertCode(mailFrom, [250, 251], 'MAIL FROM');
+};
+
+const doRcptToAll = async (
+  socket: net.Socket,
+  reader: ReturnType<typeof createLineReader>,
+  recipients: string[]
+): Promise<void> => {
+  if (recipients.length === 0) {
+    throw ErrorFactory.createValidationError('SMTP: missing recipients');
+  }
+
+  await recipients.reduce(async (prev, rcpt) => {
+    await prev;
+    await writeLine(socket, `RCPT TO:<${rcpt}>`);
+    const rcptRes = await reader.readResponse();
+    assertCode(rcptRes, [250, 251], 'RCPT TO');
+  }, Promise.resolve());
+};
+
+const doData = async (
+  socket: net.Socket,
+  reader: ReturnType<typeof createLineReader>,
+  message: MailMessage
+): Promise<void> => {
+  await writeLine(socket, 'DATA');
+  const dataRes = await reader.readResponse();
+  assertCode(dataRes, 354, 'DATA');
+
+  const raw = buildRfc2822Message(message);
+  const stuffed = dotStuff(raw);
+
+  await new Promise<void>((resolve, reject) => {
+    socket.write(`${stuffed}\r\n.\r\n`, (err?: Error | null) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+
+  const queued = await reader.readResponse();
+  assertCode(queued, 250, 'message body');
+};
+
+const doQuit = async (
+  socket: net.Socket,
+  reader: ReturnType<typeof createLineReader>
+): Promise<void> => {
+  await writeLine(socket, 'QUIT');
+  const quit = await reader.readResponse();
+  assertCode(quit, [221, 250], 'QUIT');
+};
+
+const buildRfc2822Message = (msg: MailMessage): string => {
+  const toList = normalizeRecipients(msg.to);
+
+  const fromNameRaw = msg.from.name;
+  const fromName = typeof fromNameRaw === 'string' ? fromNameRaw.trim() : '';
+  const fromHeader = fromName === '' ? msg.from.email : `${fromName} <${msg.from.email}>`;
+
+  const toHeader = toList.join(', ');
+  const subject = msg.subject;
+
+  const headers: string[] = [
+    `From: ${fromHeader}`,
+    `To: ${toHeader}`,
+    `Subject: ${subject}`,
+    'MIME-Version: 1.0',
+  ];
+
+  const attachParts = (attachments: MailAttachment[], innerBody: string): string => {
+    const mixedBoundary = `mixed_${generateUuid().replaceAll('-', '')}`;
+    const lines: string[] = [];
+
+    lines.push(
+      `Content-Type: multipart/mixed; boundary="${mixedBoundary}"`,
+      '',
+      `--${mixedBoundary}`,
+      innerBody
+    );
+
+    // attachments
+    for (const a of attachments) {
+      const b64 = a.content.toString('base64');
+      lines.push(
+        `--${mixedBoundary}`,
+        `Content-Type: application/octet-stream; name="${a.filename}"`,
+        'Content-Transfer-Encoding: base64',
+        `Content-Disposition: attachment; filename="${a.filename}"`,
+        ''
+      );
+      // break base64 into 76 char lines per RFC
+      for (let i = 0; i < b64.length; i += 76) {
+        lines.push(b64.slice(i, i + 76));
+      }
+    }
+
+    lines.push(`--${mixedBoundary}--`, '');
+
+    return lines.join('\r\n');
+  };
+
+  if (typeof msg.html === 'string' && msg.html !== '') {
+    const boundary = `zintrust_${generateUuid().replaceAll('-', '')}`;
+    headers.push(`Content-Type: multipart/alternative; boundary="${boundary}"`);
+
+    const parts = [
+      `--${boundary}`,
+      'Content-Type: text/plain; charset=utf-8',
+      'Content-Transfer-Encoding: 7bit',
+      '',
+      msg.text,
+      `--${boundary}`,
+      'Content-Type: text/html; charset=utf-8',
+      'Content-Transfer-Encoding: 7bit',
+      '',
+      msg.html,
+      `--${boundary}--`,
+      '',
+    ];
+
+    const inner = `${parts.join('\r\n')}`;
+
+    if (msg.attachments && msg.attachments.length > 0) {
+      // wrap in multipart/mixed
+      const mixed = attachParts(msg.attachments, inner);
+      return `${headers.join('\r\n')}\r\n\r\n${mixed}`;
+    }
+
+    return `${headers.join('\r\n')}\r\n\r\n${inner}`;
+  }
+
+  // plain text
+  if (msg.attachments && msg.attachments.length > 0) {
+    const inner = ['Content-Type: text/plain; charset=utf-8', '', msg.text, ''].join('\r\n');
+    const mixed = attachParts(msg.attachments, inner);
+    return `${headers.join('\r\n')}\r\n\r\n${mixed}`;
+  }
+
+  headers.push('Content-Type: text/plain; charset=utf-8');
+  return `${headers.join('\r\n')}\r\n\r\n${msg.text}\r\n`;
+};
+
+const dotStuff = (data: string): string =>
+  data
+    .replaceAll(/\r?\n/g, '\r\n')
+    .split('\r\n')
+    .map((line) => (line.startsWith('.') ? `.${line}` : line))
+    .join('\r\n');
+
+export const SmtpDriver = Object.freeze({
+  /**
+   * NOTE: This is a minimal SMTP implementation intended for Node.js runtimes.
+   * - `secure=true` means TLS from the start (SMTPS).
+   * - `secure='starttls'` performs STARTTLS after EHLO.
+   */
+  async send(config: SmtpConfig, message: MailMessage): Promise<SendResult> {
+    let mode: 'none' | 'tls' | 'starttls' = 'none';
+    if (config.secure === true) mode = 'tls';
+    if (config.secure === 'starttls') mode = 'starttls';
+
+    let socket = await createSocket(config, mode === 'tls');
+    let reader = createLineReader(socket);
+
+    try {
+      const greeting = await reader.readResponse();
+      assertCode(greeting, 220, 'greeting');
+
+      const ehlo = await doEhlo(socket, reader);
+
+      if (mode === 'starttls') {
+        const supportsStartTls = hasCapability(ehlo, 'STARTTLS');
+
+        if (!supportsStartTls) {
+          throw ErrorFactory.createConnectionError('SMTP server does not support STARTTLS');
+        }
+
+        await writeLine(socket, 'STARTTLS');
+        const startTls = await reader.readResponse();
+        assertCode(startTls, 220, 'STARTTLS');
+
+        // Swap reader/socket to the upgraded TLS stream
+        reader.close();
+        socket = await upgradeToStartTls(socket, config.host);
+        reader = createLineReader(socket);
+
+        // RFC: EHLO again after STARTTLS
+        await doEhlo(socket, reader);
+      }
+
+      await doAuthLoginIfNeeded(socket, reader, config);
+      await doMailFrom(socket, reader, message.from.email);
+      await doRcptToAll(socket, reader, normalizeRecipients(message.to));
+      await doData(socket, reader, message);
+      await doQuit(socket, reader);
+
+      return { ok: true, provider: 'smtp' };
+    } catch (err: unknown) {
+      throw ErrorFactory.createConnectionError('SMTP send failed', { error: err });
+    } finally {
+      reader.close();
+      socket.end();
+    }
+  },
+});
+
+export default SmtpDriver;

package/src/tools/mail/index.ts

@@ -0,0 +1,218 @@
+import { mailConfig } from '@config/mail';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+import type { MailAddress } from '@mail/drivers/SendGrid';
+import { SesDriver } from '@mail/drivers/Ses';
+
+import { resolveAttachments, type AttachmentInput } from '@mail/attachments';
+import { MailDriverRegistry } from '@mail/MailDriverRegistry';
+import { Storage } from '@tools/storage';
+
+export type SendMailInput = {
+  to: string | string[];
+  subject: string;
+  text: string;
+  html?: string;
+  from?: {
+    address?: string;
+    name?: string;
+  };
+  attachments?: AttachmentInput[];
+};
+
+export type SendMailResult = {
+  ok: boolean;
+  driver: 'sendgrid' | 'disabled' | 'smtp' | 'ses' | 'mailgun' | 'nodemailer';
+  messageId?: string;
+};
+
+type StorageWrapper = {
+  get: (disk: string, path: string) => Promise<Buffer>;
+  exists: (disk: string, path: string) => Promise<boolean>;
+};
+
+type StorageDiskLike = {
+  driver: {
+    get: (config: unknown, path: string) => Promise<Buffer> | Buffer;
+    exists: (config: unknown, path: string) => Promise<boolean> | boolean;
+  };
+  config: unknown;
+};
+
+const resolveFrom = (input?: SendMailInput['from']): MailAddress => {
+  const address = input?.address ?? mailConfig.from.address;
+  const name = input?.name ?? mailConfig.from.name;
+
+  if (address.trim() === '') {
+    const err = ErrorFactory.createConfigError(
+      'Mail: missing from address (set MAIL_FROM_ADDRESS or pass from.address)'
+    );
+    throw err;
+  }
+
+  return { email: address, name: name.trim() === '' ? undefined : name };
+};
+
+function assertStorageDiskLike(value: unknown): asserts value is StorageDiskLike {
+  if (typeof value !== 'object' || value === null) {
+    const err = ErrorFactory.createConfigError('Storage disk is invalid (expected object)');
+    throw err;
+  }
+
+  const v = value as Record<string, unknown>;
+  const driver = v['driver'];
+
+  if (typeof driver !== 'object' || driver === null) {
+    const err = ErrorFactory.createConfigError('Storage disk driver is invalid (expected object)');
+    throw err;
+  }
+
+  const d = driver as Record<string, unknown>;
+
+  if (typeof d['get'] !== 'function') {
+    const err = ErrorFactory.createConfigError('Storage disk driver is missing get()');
+    throw err;
+  }
+
+  if (typeof d['exists'] !== 'function') {
+    const err = ErrorFactory.createConfigError('Storage disk driver is missing exists()');
+    throw err;
+  }
+}
+
+const getDiskSafe = (disk: string): StorageDiskLike => {
+  const diskValue = Storage.getDisk(disk) as unknown;
+  assertStorageDiskLike(diskValue);
+  return diskValue;
+};
+
+const createStorageWrapper = (): StorageWrapper => ({
+  async get(disk: string, path: string) {
+    const d = getDiskSafe(disk);
+    const result = await Promise.resolve(d.driver.get(d.config, path));
+    return result;
+  },
+  async exists(disk: string, path: string) {
+    const d = getDiskSafe(disk);
+    const result = await Promise.resolve(d.driver.exists(d.config, path));
+    return Boolean(result);
+  },
+});
+
+type MailMessage = {
+  to: SendMailInput['to'];
+  from: MailAddress;
+  subject: string;
+  text: string;
+  html?: string;
+  attachments: Awaited<ReturnType<typeof resolveAttachments>>;
+};
+
+const sendWithDriver = async (
+  driver: ReturnType<typeof mailConfig.getDriver>,
+  message: MailMessage
+): Promise<SendMailResult> => {
+  if (driver.driver === 'ses') {
+    const result = await SesDriver.send({ region: driver.region }, message);
+    return { ok: result.ok, driver: 'ses', messageId: result.messageId };
+  }
+
+  // Drivers resolve via MailDriverRegistry (external packages)
+  const external = MailDriverRegistry.get(driver.driver);
+  if (external !== undefined) {
+    const result = await external(driver as unknown, message);
+    return {
+      ok: Boolean(result?.ok),
+      driver: driver.driver as SendMailResult['driver'],
+      messageId: typeof result?.messageId === 'string' ? result.messageId : undefined,
+    };
+  }
+
+  if (driver.driver === 'sendgrid' || driver.driver === 'mailgun' || driver.driver === 'smtp') {
+    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;
+  }
+};
+
+const createMailer = (
+  name?: string
+): Readonly<{
+  send: (input: SendMailInput) => Promise<SendMailResult>;
+}> =>
+  Object.freeze({
+    async send(input: SendMailInput): Promise<SendMailResult> {
+      const driver = mailConfig.getDriver(name);
+
+      if (driver.driver === 'disabled') {
+        const err = ErrorFactory.createConfigError('Mail driver is disabled (set MAIL_DRIVER)');
+        throw err;
+      }
+
+      const from = resolveFrom(input.from);
+      const storage = createStorageWrapper();
+      const attachments = await resolveAttachments(input.attachments, { storage });
+
+      return sendWithDriver(driver, {
+        to: input.to,
+        from,
+        subject: input.subject,
+        text: input.text,
+        html: input.html,
+        attachments,
+      });
+    },
+  });
+
+export interface RenderMailInput {
+  template: string; // template filename without .html extension
+  variables?: Record<string, unknown>;
+}
+
+async function renderTemplateToHtml(input: RenderMailInput): Promise<string> {
+  const { template, variables } = input;
+  // Import lazily to avoid circular deps
+  const { loadTemplate } = await import('./template-loader.js');
+  // template-loader expects full filename
+  const fileName = template.endsWith('.html') ? template : `${template}.html`;
+  return loadTemplate(
+    fileName,
+    (variables ?? {}) as import('@mail/template-utils').TemplateVariables
+  );
+}
+
+export const Mail = Object.freeze({
+  /**
+   * Render a template with variables and return HTML (preview only).
+   */
+  async render(input: RenderMailInput): Promise<string> {
+    return renderTemplateToHtml(input);
+  },
+
+  /** Alias of render */
+  async view(input: RenderMailInput): Promise<string> {
+    return renderTemplateToHtml(input);
+  },
+  /**
+   * Select a named mailer (key from mailConfig.drivers).
+   *
+   * Example: `Mail.mailer('transactional').send(...)`
+   */
+  mailer(name: string) {
+    return createMailer(name);
+  },
+
+  async send(input: SendMailInput): Promise<SendMailResult> {
+    return createMailer().send(input);
+  },
+});
+
+export default Mail;