@zintrust/core 3.5.0 → 3.5.1

package/src/tools/mail/MailDriverRegistry.ts

@@ -0,0 +1,34 @@
+export type MailSendHandler = (
+  config: unknown,
+  message: unknown
+) => Promise<{ ok: boolean; messageId?: string }>;
+
+const registry = new Map<string, MailSendHandler>();
+
+function register(driver: string, handler: MailSendHandler): void {
+  registry.set(driver, handler);
+}
+
+function get(driver: string): MailSendHandler | undefined {
+  return registry.get(driver);
+}
+
+function has(driver: string): boolean {
+  return registry.has(driver);
+}
+
+function list(): string[] {
+  return Array.from(registry.keys());
+}
+
+function reset(): void {
+  registry.clear();
+}
+
+export const MailDriverRegistry = Object.freeze({
+  register,
+  get,
+  has,
+  list,
+  reset,
+});

package/src/tools/mail/MailMessage.ts

@@ -0,0 +1,140 @@
+import { generateUuid } from '@/common/utility';
+import { isNonEmptyString } from '@helper/index';
+
+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[];
+};
+
+const normalizeRecipients = (to: string | string[]): string[] => (Array.isArray(to) ? to : [to]);
+
+const trimMessageIdDomainDecorators = (value: string): string => {
+  let start = 0;
+  let end = value.length;
+
+  while (start < end && value[start] === '<') {
+    start += 1;
+  }
+
+  while (end > start && value[end - 1] === '>') {
+    end -= 1;
+  }
+
+  while (end > start && value[end - 1] === '.') {
+    end -= 1;
+  }
+
+  return value.slice(start, end);
+};
+
+const resolveMessageIdDomain = (senderEmail: string): string => {
+  const domainCandidate = senderEmail.split('@')[1]?.trim().toLowerCase() ?? '';
+  if (!isNonEmptyString(domainCandidate)) return 'localhost';
+
+  const normalizedDomain = trimMessageIdDomainDecorators(domainCandidate);
+  if (!isNonEmptyString(normalizedDomain) || !normalizedDomain.includes('.')) {
+    return normalizedDomain === '' ? 'localhost' : normalizedDomain;
+  }
+
+  return normalizedDomain;
+};
+
+export 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 messageId = `<${generateUuid().replaceAll('-', '')}@${resolveMessageIdDomain(msg.from.email)}>`;
+
+  const headers: string[] = [
+    `From: ${fromHeader}`,
+    `To: ${toHeader}`,
+    `Subject: ${subject}`,
+    `Date: ${new Date().toUTCString()}`,
+    `Message-ID: ${messageId}`,
+    '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
+    );
+
+    for (const attachment of attachments) {
+      const b64 = attachment.content.toString('base64');
+      lines.push(
+        `--${mixedBoundary}`,
+        `Content-Type: application/octet-stream; name="${attachment.filename}"`,
+        'Content-Transfer-Encoding: base64',
+        `Content-Disposition: attachment; filename="${attachment.filename}"`,
+        ''
+      );
+      for (let index = 0; index < b64.length; index += 76) {
+        lines.push(b64.slice(index, index + 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) {
+      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}`;
+  }
+
+  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`;
+};

package/src/tools/mail/attachments.ts

@@ -0,0 +1,47 @@
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+export type DiskAttachment = { disk: string; path: string; filename?: string };
+export type InlineAttachment = { content: Buffer | string; filename: string };
+export type AttachmentInput = DiskAttachment | InlineAttachment;
+
+export type ResolvedAttachment = { filename: string; content: Buffer };
+
+export type StorageLike = {
+  get: (disk: string, path: string) => Promise<Buffer> | Buffer;
+  exists?: (disk: string, path: string) => Promise<boolean> | boolean;
+  url?: (disk: string, path: string) => string;
+};
+
+export async function resolveAttachments(
+  attachments: Array<AttachmentInput> | undefined,
+  options: { storage?: StorageLike } = {}
+): Promise<ResolvedAttachment[]> {
+  if (!attachments || attachments.length === 0) return [];
+
+  const storage = options.storage;
+
+  const resolveOne = async (att: AttachmentInput): Promise<ResolvedAttachment> => {
+    if ('content' in (att as InlineAttachment)) {
+      const a = att as InlineAttachment;
+      const content = typeof a.content === 'string' ? Buffer.from(a.content) : a.content;
+      return { filename: a.filename, content };
+    }
+
+    // Disk-based attachment
+    const d = att as DiskAttachment;
+    if (!storage) {
+      throw ErrorFactory.createValidationError('Storage is required to resolve disk attachments');
+    }
+
+    const exists = storage.exists ? await Promise.resolve(storage.exists(d.disk, d.path)) : true;
+    if (!exists) {
+      throw ErrorFactory.createNotFoundError(`Attachment not found: ${d.disk}:${d.path}`);
+    }
+
+    const content = await Promise.resolve(storage.get(d.disk, d.path));
+    const filename = d.filename ?? d.path.split('/').pop() ?? 'attachment';
+    return { filename, content };
+  };
+
+  return Promise.all(attachments.map(resolveOne));
+}

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

@@ -0,0 +1,10 @@
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+export const BaseDriver = Object.freeze({
+  async send(): Promise<unknown> {
+    await Promise.resolve();
+    throw ErrorFactory.createConfigError('Mail driver must implement send()');
+  },
+});
+
+export default BaseDriver;

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

@@ -0,0 +1,192 @@
+import { RemoteSignedJson, type RemoteSignedJsonSettings } from '@common/RemoteSignedJson';
+import { Cloudflare } from '@config/cloudflare';
+import { Env } from '@config/env';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { parseCustomHeadersFromEnv } from '@orm/adapters/SqlProxyAdapterUtils';
+
+import { buildRfc2822Message, type MailAddress, type MailMessage } from '@tools/mail/MailMessage';
+
+export type CloudflareMailConfig = {
+  driver: 'cl';
+  binding: string;
+};
+
+type SendEmailBinding = {
+  send: (message: unknown) => Promise<unknown>;
+};
+
+type CloudflareEmailModule = {
+  EmailMessage: new (from: string, to: string, raw: string) => unknown;
+};
+
+type AttachmentPayload = {
+  filename: string;
+  contentBase64: string;
+};
+
+type ProxyMessagePayload = {
+  to: string | string[];
+  from: MailAddress;
+  subject: string;
+  text: string;
+  html?: string;
+  attachments?: AttachmentPayload[];
+};
+
+type ProxySendResponse = {
+  ok: boolean;
+  messageId?: string;
+};
+
+const MAIL_PROXY_KEY_ID_ENV = 'MAIL_CLOUDFLARE_PROXY_KEY_ID';
+const MAIL_PROXY_SECRET_ENV = ['MAIL_CLOUDFLARE_PROXY', 'SECRET'].join('_');
+const APP_KEY_ID_ENV = 'APP_NAME';
+const APP_SECRET_ENV = ['APP', 'KEY'].join('_');
+
+const createMissingMailProxyCredentialsMessage = (): string => {
+  return `Cloudflare mail proxy signing credentials are missing (${MAIL_PROXY_KEY_ID_ENV} / ${MAIL_PROXY_SECRET_ENV}). Fallbacks: ${APP_KEY_ID_ENV} and ${APP_SECRET_ENV}.`;
+};
+
+const resolveSigningPrefix = (baseUrl: string): string | undefined => {
+  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: string | string[]): string[] => (Array.isArray(to) ? to : [to]);
+
+const shouldUseProxy = (): boolean => Env.get('MAIL_CLOUDFLARE_PROXY_URL', '').trim() !== '';
+
+const createRemoteConfig = (): RemoteSignedJsonSettings => {
+  const baseUrl = Env.get('MAIL_CLOUDFLARE_PROXY_URL', '');
+  const timeoutMs = Env.getInt(
+    'MAIL_CLOUDFLARE_PROXY_TIMEOUT_MS',
+    Env.getInt('ZT_PROXY_TIMEOUT_MS', Env.REQUEST_TIMEOUT)
+  );
+
+  return {
+    baseUrl,
+    keyId: Env.get('MAIL_CLOUDFLARE_PROXY_KEY_ID', ''),
+    secret: Env.get('MAIL_CLOUDFLARE_PROXY_SECRET', ''),
+    timeoutMs,
+    signaturePathPrefixToStrip: resolveSigningPrefix(baseUrl),
+    customHeaders: parseCustomHeadersFromEnv('MAIL_CLOUDFLARE_PROXY'),
+    missingUrlMessage: 'Cloudflare mail proxy URL is missing (MAIL_CLOUDFLARE_PROXY_URL)',
+    missingCredentialsMessage: createMissingMailProxyCredentialsMessage(),
+    messages: {
+      unauthorized: 'Cloudflare mail proxy unauthorized',
+      forbidden: 'Cloudflare mail proxy forbidden',
+      rateLimited: 'Cloudflare mail proxy rate limited',
+      rejected: 'Cloudflare mail proxy rejected request',
+      error: 'Cloudflare mail proxy error',
+      timedOut: 'Cloudflare mail proxy request timed out',
+    },
+  };
+};
+
+const serializeMessage = (message: MailMessage): ProxyMessagePayload => ({
+  to: message.to,
+  from: message.from,
+  subject: message.subject,
+  text: message.text,
+  html: message.html,
+  attachments: message.attachments?.map((attachment) => ({
+    filename: attachment.filename,
+    contentBase64: attachment.content.toString('base64'),
+  })),
+});
+
+const sendViaProxy = async (
+  config: CloudflareMailConfig,
+  message: MailMessage
+): Promise<{ ok: boolean; messageId?: string }> => {
+  const response = await RemoteSignedJson.request<ProxySendResponse>(
+    createRemoteConfig(),
+    '/zin/mail/cloudflare/send',
+    {
+      binding: config.binding,
+      message: serializeMessage(message),
+    }
+  );
+
+  return {
+    ok: response.ok === true,
+    messageId: response.messageId,
+  };
+};
+
+const resolveBinding = (config: CloudflareMailConfig): SendEmailBinding => {
+  const env = Cloudflare.getWorkersEnv();
+
+  if (env === null) {
+    throw ErrorFactory.createConfigError(
+      'Cloudflare mail driver requires a Cloudflare Workers runtime with a send_email binding'
+    );
+  }
+
+  const candidateNames = [config.binding, 'SEND_EMAIL', 'SEB'].filter(
+    (name, index, all) => name.trim() !== '' && all.indexOf(name) === index
+  );
+
+  for (const name of candidateNames) {
+    const binding = env[name] as SendEmailBinding | undefined;
+    if (binding !== undefined && typeof binding.send === 'function') return binding;
+  }
+
+  throw ErrorFactory.createConfigError(
+    `Cloudflare mail binding not found. Set MAIL_CLOUDFLARE_BINDING to a Wrangler send_email binding name (tried: ${candidateNames.join(', ')})`
+  );
+};
+
+const importCloudflareEmail = async (): Promise<CloudflareEmailModule> => {
+  try {
+    return (await import('cloudflare:email')) as CloudflareEmailModule;
+  } catch {
+    throw ErrorFactory.createConfigError(
+      'Cloudflare mail driver could not load the cloudflare:email runtime API'
+    );
+  }
+};
+
+export const CloudflareDriver = Object.freeze({
+  async send(
+    config: CloudflareMailConfig,
+    message: MailMessage
+  ): Promise<{ ok: boolean; messageId?: string }> {
+    const from = message.from.email.trim();
+    if (from === '') {
+      throw ErrorFactory.createConfigError('Cloudflare mail driver requires from.email');
+    }
+
+    const recipients = normalizeRecipients(message.to)
+      .map((recipient) => recipient.trim())
+      .filter((recipient) => recipient !== '');
+
+    if (recipients.length === 0) {
+      throw ErrorFactory.createConfigError(
+        'Cloudflare mail driver requires at least one recipient'
+      );
+    }
+
+    if (shouldUseProxy()) {
+      return sendViaProxy(config, message);
+    }
+
+    const binding = resolveBinding(config);
+    const { EmailMessage } = await importCloudflareEmail();
+    const raw = buildRfc2822Message(message);
+
+    await Promise.all(
+      recipients.map(async (recipient) => binding.send(new EmailMessage(from, recipient, raw)))
+    );
+
+    return { ok: true };
+  },
+});
+
+export default CloudflareDriver;

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

@@ -0,0 +1,135 @@
+import { tracedFetch } from '@common/ExternalServiceUtils';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+export type MailgunConfig = {
+  apiKey: string;
+  domain: string;
+  baseUrl?: string;
+};
+
+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: 'mailgun';
+  messageId?: string;
+};
+
+const normalizeRecipients = (to: string | string[]): string[] => (Array.isArray(to) ? to : [to]);
+
+const base64 = (value: string): string => Buffer.from(value, 'utf8').toString('base64');
+
+const toArrayBuffer = (buf: Buffer): ArrayBuffer => {
+  const ab = new ArrayBuffer(buf.byteLength);
+  new Uint8Array(ab).set(buf);
+  return ab;
+};
+
+const normalizeBaseUrl = (value?: string): string => {
+  let v = (value ?? '').trim();
+  if (v === '') return 'https://api.mailgun.net';
+
+  // Avoid regex backtracking (Sonar S5852) by trimming trailing slashes in linear time.
+  while (v.endsWith('/')) v = v.slice(0, -1);
+
+  return v;
+};
+
+const ensureConfig = (
+  config: MailgunConfig
+): Required<Pick<MailgunConfig, 'apiKey' | 'domain'>> & {
+  baseUrl: string;
+} => {
+  const apiKey = (config.apiKey ?? '').trim();
+  const domain = (config.domain ?? '').trim();
+  const baseUrl = normalizeBaseUrl(config.baseUrl);
+
+  if (apiKey === '') throw ErrorFactory.createConfigError('Mailgun: missing MAILGUN_API_KEY');
+  if (domain === '') throw ErrorFactory.createConfigError('Mailgun: missing MAILGUN_DOMAIN');
+
+  return { apiKey, domain, baseUrl };
+};
+
+const ensureMessage = (message: MailMessage): void => {
+  if (message.from.email.trim() === '') {
+    throw ErrorFactory.createConfigError('Mail: missing from.email');
+  }
+};
+
+export const MailgunDriver = Object.freeze({
+  async send(config: MailgunConfig, message: MailMessage): Promise<SendResult> {
+    const { apiKey, domain, baseUrl } = ensureConfig(config);
+    ensureMessage(message);
+
+    const url = `${baseUrl}/v3/${encodeURIComponent(domain)}/messages`;
+
+    const form = new FormData();
+
+    const fromName = (message.from.name ?? '').trim();
+    const from = fromName === '' ? message.from.email : `${fromName} <${message.from.email}>`;
+
+    form.set('from', from);
+    form.set('to', normalizeRecipients(message.to).join(','));
+    form.set('subject', message.subject);
+    form.set('text', message.text);
+
+    if (typeof message.html === 'string' && message.html !== '') {
+      form.set('html', message.html);
+    }
+
+    if (message.attachments && message.attachments.length > 0) {
+      for (const a of message.attachments) {
+        // In Node.js, Buffer is a Uint8Array, which works as a BlobPart.
+        // In other runtimes, callers typically won't supply Buffer attachments.
+        const blob = new Blob([toArrayBuffer(a.content)]);
+        form.append('attachment', blob, a.filename);
+      }
+    }
+
+    const auth = `Basic ${base64('api:' + apiKey)}`;
+
+    const res = await tracedFetch(
+      url,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: auth,
+        },
+        body: form,
+      },
+      { source: 'mailgun' }
+    );
+
+    if (res.ok) {
+      try {
+        const json = (await res.json()) as Record<string, unknown>;
+        const id = typeof json?.['id'] === 'string' ? json['id'] : undefined;
+        return { ok: true, provider: 'mailgun', messageId: id };
+      } catch {
+        return { ok: true, provider: 'mailgun' };
+      }
+    }
+
+    const text = await res.text();
+    throw ErrorFactory.createConnectionError(`Mailgun send failed (${res.status})`, {
+      status: res.status,
+      body: text,
+    });
+  },
+});
+
+export default MailgunDriver;

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

@@ -0,0 +1,108 @@
+import { MIME_TYPES } from '@/config/constants';
+import { tracedFetch } from '@common/ExternalServiceUtils';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+export type SendGridConfig = {
+  apiKey: string;
+};
+
+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: 'sendgrid';
+  messageId?: string;
+};
+
+const normalizeRecipients = (to: string | string[]): string[] => (Array.isArray(to) ? to : [to]);
+
+export const SendGridDriver = Object.freeze({
+  async send(config: SendGridConfig, message: MailMessage): Promise<SendResult> {
+    if (config.apiKey.trim() === '') {
+      throw ErrorFactory.createConfigError('SendGrid: missing SENDGRID_API_KEY');
+    }
+
+    if (message.from.email.trim() === '') {
+      throw ErrorFactory.createConfigError('Mail: missing from.email');
+    }
+
+    const personalizations = [
+      {
+        to: normalizeRecipients(message.to).map((email) => ({ email })),
+      },
+    ];
+
+    const content: Array<{ type: string; value: string }> = [
+      { type: MIME_TYPES.TEXT, value: message.text },
+    ];
+    if (typeof message.html === 'string' && message.html !== '') {
+      content.push({ type: MIME_TYPES.HTML, value: message.html });
+    }
+
+    type SendGridAttachment = { content: string; filename: string };
+
+    const body: {
+      personalizations: Array<Record<string, unknown>>;
+      from: { email: string; name?: string };
+      subject: string;
+      content: Array<{ type: string; value: string }>;
+      attachments?: SendGridAttachment[];
+    } = {
+      personalizations,
+      from: {
+        email: message.from.email,
+        name: message.from.name?.trim() === '' ? undefined : message.from.name,
+      },
+      subject: message.subject,
+      content,
+    };
+
+    if (message.attachments && message.attachments.length > 0) {
+      body.attachments = message.attachments.map((a) => ({
+        content: a.content.toString('base64'),
+        filename: a.filename,
+      }));
+    }
+
+    const res = await tracedFetch(
+      'https://api.sendgrid.com/v3/mail/send',
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${config.apiKey}`,
+          'content-type': MIME_TYPES.JSON,
+        },
+        body: JSON.stringify(body),
+      },
+      { source: 'sendgrid' }
+    );
+
+    // SendGrid typically returns 202 for success.
+    if (res.status === 202) {
+      const messageId = res.headers.get('x-message-id') ?? undefined;
+      return { ok: true, provider: 'sendgrid', messageId };
+    }
+
+    const text = await res.text();
+    throw ErrorFactory.createConnectionError(`SendGrid send failed (${res.status})`, {
+      status: res.status,
+      body: text,
+    });
+  },
+});
+
+export default SendGridDriver;