@zerotal/notifications 1.0.0

package/src/drivers/SmtpDriver.ts

@@ -0,0 +1,510 @@
+import type { MailDriver, MailPayload, MailAddress } from "./MailDriver.ts";
+import { SmtpResponseError, SmtpConnectionError } from "../errors.ts";
+
+/** How long to wait for any single SMTP reply before giving up. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * SMTP driver — raw TCP via `Bun.connect()`, with TLS.
+ *
+ * Three transport modes, chosen by `secure` and what the server advertises:
+ *
+ * - `secure: true` — implicit TLS from the first byte (SMTPS, usually port 465).
+ * - `secure: false` on a server advertising STARTTLS — connects in the clear,
+ *   then upgrades before authenticating (submission, usually port 587).
+ * - `secure: false` on a server without STARTTLS — stays plaintext. Credentials
+ *   are refused in this mode unless `allowInsecureAuth` is set, because `AUTH
+ *   LOGIN` is base64, not encryption.
+ *
+ * Every reply is parsed and its status code checked, so a rejected recipient or a
+ * failed authentication raises {@link SmtpResponseError} instead of being
+ * mistaken for a successful send.
+ */
+export class SmtpDriver implements MailDriver {
+  constructor(
+    private _host: string,
+    private _port: number,
+    private _username: string,
+    private _password: string,
+    private _secure: boolean = false,
+    private _options: {
+      /** Permit AUTH over an unencrypted connection. Off by default. */
+      allowInsecureAuth?: boolean;
+      /** Reject servers presenting an untrusted certificate. Default: true. */
+      rejectUnauthorized?: boolean;
+      /** Per-reply timeout in milliseconds. Default: 30000. */
+      timeoutMs?: number;
+      /** Name sent in EHLO. Default: "zerotal". */
+      clientName?: string;
+    } = {},
+  ) {}
+
+  async send(message: MailPayload): Promise<void> {
+    const conn = await SmtpConnection.open(this._host, this._port, {
+      tls: this._secure,
+      rejectUnauthorized: this._options.rejectUnauthorized ?? true,
+      timeoutMs: this._options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    });
+
+    try {
+      await conn.expect(220);
+
+      const clientName = this._options.clientName ?? "zerotal";
+      let capabilities = await this._ehlo(conn, clientName);
+
+      // Upgrade an unencrypted submission connection before anything sensitive.
+      if (!this._secure && capabilities.includes("STARTTLS")) {
+        conn.send("STARTTLS");
+        await conn.expect(220);
+        await conn.upgradeTLS(this._host, this._options.rejectUnauthorized ?? true);
+        capabilities = await this._ehlo(conn, clientName);
+      }
+
+      if (this._username && this._password) {
+        if (!conn.encrypted && !this._options.allowInsecureAuth) {
+          throw new SmtpConnectionError(
+            `Refusing to send SMTP credentials over an unencrypted connection to ${this._host}:${this._port}. ` +
+              `Use secure: true (port 465), a server offering STARTTLS (port 587), or set ` +
+              `mail.smtp.allowInsecureAuth to accept the risk.`,
+          );
+        }
+        await this._authenticate(conn, capabilities);
+      }
+
+      conn.send(`MAIL FROM:<${message.from.address}>`);
+      await conn.expect(250);
+
+      const recipients = [...message.to, ...(message.cc ?? []), ...(message.bcc ?? [])];
+      if (recipients.length === 0) {
+        throw new SmtpConnectionError("Refusing to send a message with no recipients.");
+      }
+      for (const rcpt of recipients) {
+        conn.send(`RCPT TO:<${rcpt.address}>`);
+        // 251 = "not local, will forward" — a success.
+        await conn.expect(250, 251);
+      }
+
+      conn.send("DATA");
+      await conn.expect(354);
+
+      conn.write(`${buildRawMessage(message)}\r\n.\r\n`);
+      await conn.expect(250);
+
+      conn.send("QUIT");
+      // A server that drops the connection instead of replying 221 has still
+      // accepted the message — the 250 above was the commit point.
+      await conn.expect(221).catch(() => undefined);
+    } finally {
+      conn.close();
+    }
+  }
+
+  /** Send EHLO and return the advertised capability lines, uppercased. */
+  private async _ehlo(conn: SmtpConnection, clientName: string): Promise<string[]> {
+    conn.send(`EHLO ${clientName}`);
+    const reply = await conn.expect(250);
+    return reply.lines.map((l) => l.slice(4).toUpperCase());
+  }
+
+  private async _authenticate(conn: SmtpConnection, capabilities: string[]): Promise<void> {
+    const authLine = capabilities.find((c) => c.startsWith("AUTH"));
+    const mechanisms = authLine ? authLine.split(/\s+/).slice(1) : [];
+
+    // PLAIN is a single round trip; LOGIN is the fallback for servers without it.
+    if (mechanisms.length === 0 || mechanisms.includes("PLAIN")) {
+      const token = btoa(`\0${this._username}\0${this._password}`);
+      conn.send(`AUTH PLAIN ${token}`);
+      await conn.expect(235);
+      return;
+    }
+
+    if (mechanisms.includes("LOGIN")) {
+      conn.send("AUTH LOGIN");
+      await conn.expect(334);
+      conn.send(btoa(this._username));
+      await conn.expect(334);
+      conn.send(btoa(this._password));
+      await conn.expect(235);
+      return;
+    }
+
+    throw new SmtpConnectionError(
+      `No supported SMTP auth mechanism. Server offers: ${mechanisms.join(", ") || "none"}; ` +
+        `this driver supports PLAIN and LOGIN.`,
+    );
+  }
+}
+
+/** One parsed SMTP reply: its status code and every line of it. */
+interface SmtpReply {
+  code: number;
+  lines: string[];
+  text: string;
+}
+
+/**
+ * A single SMTP session — owns the socket, buffers incoming bytes, and hands
+ * back one complete reply at a time.
+ *
+ * SMTP replies are not one-per-packet: a multi-line greeting arrives as
+ * `250-SIZE\r\n250-STARTTLS\r\n250 HELP\r\n`, possibly split across TCP reads or
+ * coalesced with the next reply. Reading is therefore driven by the protocol's
+ * own framing — a reply ends at the first line whose code is followed by a space
+ * rather than a hyphen — not by packet boundaries.
+ */
+class SmtpConnection {
+  private _buffer = "";
+  private _replies: SmtpReply[] = [];
+  private _waiters: Array<{
+    resolve: (r: SmtpReply) => void;
+    reject: (e: Error) => void;
+  }> = [];
+  private _failure: Error | undefined;
+  private _closed = false;
+  private _encrypted: boolean;
+
+  private constructor(
+    private _socket: import("bun").Socket<undefined>,
+    private readonly _host: string,
+    private readonly _port: number,
+    private readonly _timeoutMs: number,
+    encrypted: boolean,
+  ) {
+    this._encrypted = encrypted;
+  }
+
+  /** True once the transport is TLS, whether implicit or upgraded. */
+  get encrypted(): boolean {
+    return this._encrypted;
+  }
+
+  static async open(
+    host: string,
+    port: number,
+    options: { tls: boolean; rejectUnauthorized: boolean; timeoutMs: number },
+  ): Promise<SmtpConnection> {
+    let conn!: SmtpConnection;
+    try {
+      const socket = await Bun.connect<undefined>({
+        hostname: host,
+        port,
+        ...(options.tls
+          ? { tls: { rejectUnauthorized: options.rejectUnauthorized, serverName: host } }
+          : {}),
+        socket: {
+          data: (_s, data) => conn._onData(data),
+          error: (_s, err) => conn._onError(err),
+          close: () => conn._onClose(),
+          open: () => {},
+        },
+      });
+      conn = new SmtpConnection(socket, host, port, options.timeoutMs, options.tls);
+      return conn;
+    } catch (error) {
+      throw new SmtpConnectionError(
+        `Could not connect to SMTP server ${host}:${port} — ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  /** Upgrade a plaintext connection to TLS after a 220 response to STARTTLS. */
+  async upgradeTLS(host: string, rejectUnauthorized: boolean): Promise<void> {
+    try {
+      const [, tls] = this._socket.upgradeTLS<undefined>({
+        tls: { rejectUnauthorized, serverName: host },
+        socket: {
+          data: (_s, data) => this._onData(data),
+          error: (_s, err) => this._onError(err),
+          close: () => this._onClose(),
+          open: () => {},
+        },
+      });
+      this._socket = tls;
+      this._encrypted = true;
+      // The post-upgrade session starts clean: anything buffered pre-handshake
+      // belongs to the discarded plaintext stream.
+      this._buffer = "";
+      this._replies = [];
+    } catch (error) {
+      throw new SmtpConnectionError(
+        `STARTTLS upgrade failed for ${host} — ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  /** Write a command plus its CRLF terminator. */
+  send(command: string): void {
+    this.write(`${command}\r\n`);
+  }
+
+  write(raw: string): void {
+    this._socket.write(new TextEncoder().encode(raw));
+  }
+
+  /**
+   * Read the next reply and require its code to be one of `codes`.
+   *
+   * @throws {SmtpResponseError} when the server answers with anything else.
+   */
+  async expect(...codes: number[]): Promise<SmtpReply> {
+    const reply = await this.read();
+    if (!codes.includes(reply.code)) {
+      throw new SmtpResponseError(reply.code, reply.text, codes);
+    }
+    return reply;
+  }
+
+  /** Read the next complete reply, waiting for it if it has not arrived. */
+  read(): Promise<SmtpReply> {
+    const buffered = this._replies.shift();
+    if (buffered) return Promise.resolve(buffered);
+    if (this._failure) return Promise.reject(this._failure);
+    if (this._closed) {
+      return Promise.reject(
+        new SmtpConnectionError(
+          `SMTP server ${this._host}:${this._port} closed the connection unexpectedly.`,
+        ),
+      );
+    }
+
+    return new Promise<SmtpReply>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._waiters = this._waiters.filter((w) => w.resolve !== wrapped);
+        reject(
+          new SmtpConnectionError(
+            `Timed out after ${this._timeoutMs}ms waiting for a reply from ${this._host}:${this._port}.`,
+          ),
+        );
+      }, this._timeoutMs);
+
+      const wrapped = (reply: SmtpReply): void => {
+        clearTimeout(timer);
+        resolve(reply);
+      };
+      this._waiters.push({
+        resolve: wrapped,
+        reject: (e) => {
+          clearTimeout(timer);
+          reject(e);
+        },
+      });
+    });
+  }
+
+  close(): void {
+    if (this._closed) return;
+    this._closed = true;
+    try {
+      this._socket.end();
+    } catch {
+      /* already gone */
+    }
+  }
+
+  private _onData(data: Uint8Array): void {
+    this._buffer += new TextDecoder().decode(data);
+    this._parse();
+  }
+
+  /** Split the buffer into complete replies, leaving any partial tail behind. */
+  private _parse(): void {
+    for (;;) {
+      let cursor = 0;
+      let end = -1;
+
+      for (;;) {
+        const nl = this._buffer.indexOf("\n", cursor);
+        if (nl === -1) break;
+        const line = this._buffer.slice(cursor, nl).replace(/\r$/, "");
+        // `250 ` terminates; `250-` continues. A bare code is also terminal.
+        if (/^\d{3}(?: |$)/.test(line)) {
+          end = nl;
+          break;
+        }
+        cursor = nl + 1;
+      }
+
+      if (end === -1) return;
+
+      const raw = this._buffer.slice(0, end).replace(/\r$/, "");
+      this._buffer = this._buffer.slice(end + 1);
+
+      const lines = raw.split("\n").map((l) => l.replace(/\r$/, ""));
+      const last = lines[lines.length - 1] ?? "";
+      const reply: SmtpReply = {
+        code: Number.parseInt(last.slice(0, 3), 10),
+        lines,
+        text: lines
+          .map((l) => l.slice(4))
+          .join(" ")
+          .trim(),
+      };
+
+      const waiter = this._waiters.shift();
+      if (waiter) waiter.resolve(reply);
+      else this._replies.push(reply);
+    }
+  }
+
+  private _onError(error: Error): void {
+    this._failure = new SmtpConnectionError(
+      `SMTP socket error on ${this._host}:${this._port} — ${error.message}`,
+    );
+    this._rejectAll(this._failure);
+  }
+
+  private _onClose(): void {
+    this._closed = true;
+    if (this._waiters.length > 0) {
+      this._rejectAll(
+        new SmtpConnectionError(
+          `SMTP server ${this._host}:${this._port} closed the connection unexpectedly.`,
+        ),
+      );
+    }
+  }
+
+  private _rejectAll(error: Error): void {
+    const waiters = this._waiters;
+    this._waiters = [];
+    for (const w of waiters) w.reject(error);
+  }
+}
+
+/**
+ * Strip CR and LF from a header value.
+ *
+ * A subject or display name is attacker-influenced often enough to matter: left
+ * raw, an embedded CRLF ends the header and lets the rest of the string be read
+ * as new headers (a `Bcc:` of the sender's choosing, or a second body).
+ */
+function sanitizeHeader(value: string): string {
+  return value.replace(/[\r\n]+/g, " ").trim();
+}
+
+/**
+ * Encode a header value as RFC 2047 base64 when it contains non-ASCII.
+ * Headers are 7-bit; a raw UTF-8 subject arrives mangled otherwise.
+ */
+function encodeHeaderValue(value: string): string {
+  const clean = sanitizeHeader(value);
+  // eslint-disable-next-line no-control-regex -- matching non-ASCII by definition
+  if (!/[^\x00-\x7F]/.test(clean)) return clean;
+  const base64 = Buffer.from(clean, "utf8").toString("base64");
+  return `=?UTF-8?B?${base64}?=`;
+}
+
+function formatAddr(a: MailAddress): string {
+  const address = sanitizeHeader(a.address);
+  return a.name ? `"${encodeHeaderValue(a.name).replace(/"/g, "")}" <${address}>` : address;
+}
+
+/**
+ * Escape a line beginning with a period.
+ *
+ * A bare `.` on its own line ends the DATA block, so any body line starting with
+ * one is doubled on the wire and halved again by the receiver (RFC 5321 §4.5.2).
+ * Without this a message containing such a line is silently truncated.
+ */
+function dotStuff(body: string): string {
+  return body.replace(/\r?\n\./g, "\r\n..").replace(/^\./, "..");
+}
+
+/** Normalise bare LF to CRLF — SMTP requires canonical line endings. */
+function toCrlf(text: string): string {
+  return text.replace(/\r\n/g, "\n").replace(/\n/g, "\r\n");
+}
+
+function buildRawMessage(msg: MailPayload): string {
+  const lines: string[] = [];
+
+  lines.push(`From: ${formatAddr(msg.from)}`);
+  lines.push(`To: ${msg.to.map(formatAddr).join(", ")}`);
+  if (msg.cc?.length) lines.push(`Cc: ${msg.cc.map(formatAddr).join(", ")}`);
+  if (msg.replyTo) lines.push(`Reply-To: ${formatAddr(msg.replyTo)}`);
+  lines.push(`Subject: ${encodeHeaderValue(msg.subject)}`);
+  lines.push(`Date: ${new Date().toUTCString()}`);
+  lines.push(
+    `Message-ID: <${crypto.randomUUID()}@${msg.from.address.split("@")[1] ?? "localhost"}>`,
+  );
+  lines.push("MIME-Version: 1.0");
+
+  const attachments = msg.attachments ?? [];
+  const body = renderBody(msg);
+
+  if (attachments.length === 0) {
+    lines.push(body.headers);
+    lines.push("");
+    lines.push(body.content);
+    return toCrlf(lines.join("\r\n"));
+  }
+
+  // Attachments wrap the whole body in multipart/mixed, with the text/html
+  // alternative (if any) nested as the first part.
+  const mixed = `zerotal-mixed-${crypto.randomUUID()}`;
+  lines.push(`Content-Type: multipart/mixed; boundary="${mixed}"`);
+  lines.push("");
+  lines.push(`--${mixed}`);
+  lines.push(body.headers);
+  lines.push("");
+  lines.push(body.content);
+
+  for (const attachment of attachments) {
+    lines.push(`--${mixed}`);
+    lines.push(
+      `Content-Type: ${sanitizeHeader(attachment.contentType ?? "application/octet-stream")}`,
+    );
+    lines.push("Content-Transfer-Encoding: base64");
+    const disposition = attachment.inline ? "inline" : "attachment";
+    lines.push(
+      `Content-Disposition: ${disposition}; filename="${encodeHeaderValue(attachment.filename).replace(/"/g, "")}"`,
+    );
+    if (attachment.cid) lines.push(`Content-ID: <${sanitizeHeader(attachment.cid)}>`);
+    lines.push("");
+    lines.push(chunk76(toBase64(attachment.content)));
+  }
+
+  lines.push(`--${mixed}--`);
+  return toCrlf(lines.join("\r\n"));
+}
+
+/** The body part: either a single type, or a multipart/alternative pair. */
+function renderBody(msg: MailPayload): { headers: string; content: string } {
+  if (msg.html && msg.text) {
+    const alt = `zerotal-alt-${crypto.randomUUID()}`;
+    const content = [
+      `--${alt}`,
+      "Content-Type: text/plain; charset=utf-8",
+      "",
+      dotStuff(msg.text),
+      `--${alt}`,
+      "Content-Type: text/html; charset=utf-8",
+      "",
+      dotStuff(msg.html),
+      `--${alt}--`,
+    ].join("\r\n");
+    return { headers: `Content-Type: multipart/alternative; boundary="${alt}"`, content };
+  }
+  if (msg.html) {
+    return { headers: "Content-Type: text/html; charset=utf-8", content: dotStuff(msg.html) };
+  }
+  return {
+    headers: "Content-Type: text/plain; charset=utf-8",
+    content: dotStuff(msg.text ?? ""),
+  };
+}
+
+function toBase64(content: string | Uint8Array): string {
+  return typeof content === "string"
+    ? Buffer.from(content, "utf8").toString("base64")
+    : Buffer.from(content).toString("base64");
+}
+
+/** Base64 in a MIME part is wrapped at 76 characters. */
+function chunk76(base64: string): string {
+  return (base64.match(/.{1,76}/g) ?? []).join("\r\n");
+}

package/src/errors.ts

@@ -0,0 +1,163 @@
+import { ZerotalError } from "@zerotal/core";
+
+/** Base class for all @zerotal/notifications errors. */
+export class NotificationError extends ZerotalError {
+  constructor(
+    message: string,
+    code = "E_NOTIFICATION",
+    status = 500,
+    context?: Record<string, unknown>,
+  ) {
+    super(message, code, status, context);
+  }
+}
+
+/** Thrown when a notification is routed to a channel the manager does not know. */
+export class UnknownNotificationChannelError extends NotificationError {
+  constructor(channel: string, known: string[] = []) {
+    super(
+      `Unknown notification channel: '${channel}'.` +
+        (known.length > 0
+          ? ` Registered: ${known.join(", ")}. Add your own with notifications.extend("${channel}", () => …).`
+          : ""),
+      "E_NOTIFICATION_UNKNOWN_CHANNEL",
+      500,
+      { channel, known },
+    );
+  }
+}
+
+/** Thrown when a channel is used but its config block is missing. */
+export class NotificationChannelNotConfiguredError extends NotificationError {
+  constructor(channel: string, hint = "") {
+    super(
+      `[Zerotal] Notifications ${channel} channel is not configured.${hint ? " " + hint : ""}`,
+      "E_NOTIFICATION_CHANNEL_NOT_CONFIGURED",
+      500,
+      { channel },
+    );
+  }
+}
+
+/** Thrown when a channel's delivery to its provider fails (non-2xx response or provider error). */
+export class NotificationDeliveryError extends NotificationError {
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(message, "E_NOTIFICATION_DELIVERY", 502, context);
+  }
+}
+
+/**
+ * Thrown when a channel cannot run because an optional peer package or required
+ * config is missing (e.g. the broadcast channel without `@zerotal/broadcasting`,
+ * or the SMS driver's credential block).
+ */
+export class NotificationChannelUnavailableError extends NotificationError {
+  constructor(message: string) {
+    super(message, "E_NOTIFICATION_CHANNEL_UNAVAILABLE", 500);
+  }
+}
+
+/**
+ * Thrown when a notification routes to a channel whose representation method
+ * (e.g. `toMail()`) hasn't been implemented on the notification class.
+ */
+export class NotificationContractError extends NotificationError {
+  constructor(notification: string, method: string, channel: string) {
+    super(
+      `${notification} must implement ${method}() to use the '${channel}' channel.`,
+      "E_NOTIFICATION_CONTRACT",
+      500,
+      { notification, method, channel },
+    );
+  }
+}
+
+/**
+ * Thrown when a queued notification names a class the worker cannot find — the
+ * notification lives outside `app/notifications/` and was never registered.
+ */
+export class UnknownNotificationTypeError extends NotificationError {
+  constructor(type: string, known: string[]) {
+    super(
+      `Cannot rebuild queued notification '${type}' — no class of that name is registered. ` +
+        `Notifications under app/notifications/ are found automatically; for one elsewhere, call ` +
+        `NotificationRegistry.register(${type}) where it is defined.` +
+        (known.length > 0 ? ` Known: ${known.join(", ")}.` : ""),
+      "E_NOTIFICATION_UNKNOWN_TYPE",
+      500,
+      { type, known },
+    );
+  }
+}
+
+/**
+ * Thrown when a notification finished dispatching but one or more channels
+ * failed. Every channel is attempted regardless — a broken Slack webhook must
+ * not cost the recipient their email — so this reports the failures together
+ * once the rest have been delivered.
+ */
+export class NotificationDispatchError extends NotificationError {
+  constructor(
+    readonly notification: string,
+    readonly failures: Array<{ channel: string; error: Error }>,
+    readonly delivered: string[],
+  ) {
+    super(
+      `${notification} failed on ${failures.length} of ${failures.length + delivered.length} channel(s): ` +
+        failures.map((f) => `${f.channel} (${f.error.message})`).join("; ") +
+        (delivered.length > 0 ? `. Delivered on: ${delivered.join(", ")}.` : "."),
+      "E_NOTIFICATION_DISPATCH",
+      500,
+      {
+        notification,
+        failures: failures.map((f) => ({ channel: f.channel, error: f.error.message })),
+        delivered,
+      },
+    );
+  }
+}
+
+/**
+ * Thrown when an SMTP server answers a command with an unexpected status code.
+ * Carries the server's own text, which is usually the most useful part.
+ */
+export class SmtpResponseError extends NotificationError {
+  constructor(
+    readonly replyCode: number,
+    readonly replyText: string,
+    expected: number[],
+  ) {
+    super(
+      `SMTP server replied ${replyCode} (${replyText || "no message"}); expected ${expected.join(" or ")}.`,
+      "E_NOTIFICATION_SMTP_RESPONSE",
+      502,
+      { replyCode, replyText, expected },
+    );
+  }
+}
+
+/** Thrown when the SMTP transport itself fails — connect, TLS, timeout, or early close. */
+export class SmtpConnectionError extends NotificationError {
+  constructor(message: string) {
+    super(`[Zerotal/notifications] ${message}`, "E_NOTIFICATION_SMTP_CONNECTION", 502);
+  }
+}
+
+/** Thrown when `config/notifications.ts` is internally inconsistent. */
+export class NotificationConfigError extends NotificationError {
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(`[Zerotal/notifications] ${message}`, "E_NOTIFICATION_CONFIG", 500, context);
+  }
+}
+
+/** Thrown when the configured SMS driver name is not recognised. */
+export class UnknownSmsDriverError extends NotificationError {
+  constructor(driver: string) {
+    super(
+      `[Zerotal/notifications] Unknown SMS driver: '${driver}'`,
+      "E_NOTIFICATION_UNKNOWN_SMS_DRIVER",
+      500,
+      { driver },
+    );
+  }
+}