@zerotal/notifications 1.8.1 → 1.10.0

package/CHANGELOG.md

@@ -8,6 +8,71 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.10.0] — 2026-08-30
+
+### Fixed
+
+- **SMTP submission on port 587 works.** The STARTTLS upgrade completed its handshake
+  and then sent nothing: `upgradeTLS()` returns the new socket while the handshake is
+  still in flight, and a write issued in that window is **dropped** — not buffered,
+  not an error, gone. The `EHLO` that has to follow STARTTLS went into that gap on
+  every send, so the server waited for a command that never came while the client
+  waited for a reply that never came, until the read timed out.
+
+  Everything either side looked healthy, which is what made it expensive: the server
+  logged a good TLS session and then a connection lost. Port 465 was unaffected,
+  because implicit TLS finishes before `Bun.connect()` resolves and there is no window
+  to write into — so mail worked on the port nobody documents, and configuring the 587
+  that every provider _does_ document produced silence. No error, no bounce, no log
+  line, and password resets that never arrived. `upgradeTLS()` now resolves only once
+  the handshake has completed, bounded by the reply timeout.
+
+- **TLS certificates are actually verified, on both transports.** `rejectUnauthorized`
+  is not enforced by the runtime: Bun reports `authorized: true` for a self-signed
+  certificate on `Bun.connect()` and on `upgradeTLS()` alike, whether the flag is set
+  or not, and puts the real reason in `authorizationError` beside it. Trusting the
+  flag made TLS decorative — the connection was encrypted, and would have accepted
+  that encryption from anyone in the network path, which is the one property TLS
+  exists to provide. The driver now reads the handshake result itself and fails
+  closed; `rejectUnauthorized: false` still accepts a self-signed relay, deliberately.
+
+- **The server greeting cannot be lost to a race.** `Bun.connect()` resolves after the
+  socket opens, and the 220 can arrive before the `await` returns — the data callback
+  reached for a connection object that did not exist yet. Early bytes are now buffered
+  and replayed.
+
+### Added
+
+- **A doctor check for a production `mail.driver` of `"log"`.** It is the default, it
+  is right in development, and it is the quietest possible production failure: every
+  message is written to a log file, nothing reports a problem, and password resets
+  stop arriving until someone asks why. `zt doctor` reports it and `zt deploy` refuses
+  on it.
+
+  Two tiers, because the same value means two things. An app with a real
+  `mail.from.address` configured `log` by accident, or had it knocked back, and its
+  mail is going nowhere — that fails. An app still on the placeholder address probably
+  sends no mail at all, and failing its deploy over a setting it never touched would be
+  the framework inventing a problem — that warns.
+
+### Testing
+
+- `SmtpSubmission.test.ts` runs the whole 587 flow against a real STARTTLS peer.
+  The existing tests could not: they upgrade into a peer that is already speaking TLS,
+  because Bun cannot be a STARTTLS _server_ — and the bug lived in the one step that
+  arrangement skips. The fixture peer runs under Node, which can wrap a connected
+  socket as a TLS server. The limitation was the harness's, never the client's.
+
+## [1.9.0] — 2026-08-29
+
+### Documented
+
+- **Every promised export is documented.** The `docs-coverage` gate reads `maturity: stable` as a
+  promise about a package's exports, and measures how much of that promise is written down. It
+  was 798 gaps across the suite; it is now zero. This package's share is covered on its own
+  pages — types named, options shapes described, and the decisions behind them recorded where
+  somebody looking for them will find them.
+
 ## [1.8.0] — 2026-08-24
 
 ### Fixed

package/api-surface.md

@@ -375,8 +375,8 @@ interface NotificationChannel = {
 interface NotificationConfigShape = {
   database: {    table: string;}
   mail: MailConfigShape
-  slack?: {    webhook?: string;}
-  sms?: SmsConfigShape
+  slack?: {    webhook?: string;} | undefined
+  sms?: SmsConfigShape | undefined
 }
 
 interface NotificationRecord = {
@@ -415,8 +415,8 @@ interface SlackMessage = {
 
 interface SmsConfigShape = {
   driver: 'twilio' | 'vonage'
-  twilio?: TwilioConfigShape
-  vonage?: VonageConfigShape
+  twilio?: TwilioConfigShape | undefined
+  vonage?: VonageConfigShape | undefined
 }
 
 interface SmsMessage = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/notifications",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,12 +30,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.8.1",
-    "@zerotal/orm": "1.8.1",
-    "@zerotal/queue": "1.8.1"
+    "@zerotal/core": "1.10.0",
+    "@zerotal/orm": "1.10.0",
+    "@zerotal/queue": "1.10.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.8.1",
+    "@zerotal/broadcasting": "1.10.0",
     "typescript": "^5.8.0"
   },
   "description": "Multi-channel notifications for Zerotal — mail (SMTP/Resend), database, broadcast, Slack, and SMS.",

package/src/doctor.ts

@@ -0,0 +1,74 @@
+/**
+ * The deployment check `zt doctor` and `zt deploy` run against the mail config.
+ *
+ * `mail.driver` defaults to `"log"`, which is right in development and is the
+ * quietest possible production failure: every message is written to a log file and
+ * nothing anywhere reports a problem. No error, no bounce, no send — just password
+ * resets that never arrive, found days later by someone asking why.
+ *
+ * @module
+ */
+import { deployEnv, isProdLike } from "@zerotal/core";
+import type { Application } from "@zerotal/core";
+import type { DoctorCheck, DoctorCheckResult } from "@zerotal/core";
+import { NotificationConfig } from "./config.ts";
+import type { NotificationConfigShape } from "./types.ts";
+
+/**
+ * The from-address a project that never configured mail still has.
+ *
+ * It is what tells "this app does not send mail" apart from "this app sends mail
+ * and its driver got knocked back to the default", which are the same setting and
+ * very different problems. Anyone who set up mail changed this.
+ */
+const PLACEHOLDER_FROM = "hello@example.com";
+
+/** The loaded notification config, or the defaults when the app declares none. */
+function _mailConfig(app: Application): NotificationConfigShape["mail"] | undefined {
+  try {
+    const config = app.container.makeSync("config") as {
+      get<T>(key: string, fallback: T): T;
+    };
+    return config.get<NotificationConfigShape>("notifications", NotificationConfig()).mail;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Refuse a production release whose mail goes to a log file.
+ *
+ * Two tiers, because the same value means two things. An app with a real
+ * from-address configured `log` by accident — or had it knocked back — and its mail
+ * is silently going nowhere: that fails. An app still on the placeholder address
+ * probably sends no mail at all, and failing its deploy over a setting it never
+ * touched would be the framework inventing a problem: that warns.
+ */
+export const mailDriverCheck: DoctorCheck = {
+  id: "mail-driver",
+  label: "Mail driver",
+  run(app: Application): DoctorCheckResult {
+    const mail = _mailConfig(app);
+    if (!mail) return { status: "ok", message: "no mail config to check" };
+
+    if (mail.driver !== "log") {
+      return { status: "ok", message: `${mail.driver}` };
+    }
+
+    if (!isProdLike(deployEnv())) {
+      return { status: "ok", message: "log (fine outside production)" };
+    }
+
+    const configured = mail.from.address !== PLACEHOLDER_FROM;
+    return {
+      status: configured ? "fail" : "warn",
+      message: configured
+        ? `mail.driver is "log" in production, but mail.from.address is set to ` +
+          `${mail.from.address} — every message this app sends is being written to a ` +
+          `log file and delivered to nobody.`
+        : `mail.driver is "log" in production. Nothing is delivered. ` +
+          `(mail.from.address is still the default, so this app may not send mail at all.)`,
+      fix: 'Set mail.driver to "smtp" or "resend" in config/notifications.ts, and its credentials with it.',
+    };
+  },
+};

package/src/drivers/SmtpDriver.ts

@@ -19,6 +19,12 @@ const DEFAULT_TIMEOUT_MS = 30_000;
  * 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.
+ *
+ * Certificate verification is enforced here rather than by the runtime. Bun does
+ * not honour `rejectUnauthorized` on either `Bun.connect()` or `upgradeTLS()` — it
+ * reports the peer as authorized and puts the real reason beside it — so both
+ * transports check the handshake result themselves and fail closed. See
+ * `_certificateFailure`.
  */
 export class SmtpDriver implements MailDriver {
   constructor(
@@ -142,6 +148,34 @@ interface SmtpReply {
   text: string;
 }
 
+/**
+ * Whether a completed handshake should be treated as a failure.
+ *
+ * **`rejectUnauthorized` is not enforced by the runtime.** Bun reports
+ * `authorized: true` for a self-signed certificate whether the flag is on or off,
+ * on `Bun.connect()` and on `upgradeTLS()` alike, and hands back the real reason in
+ * `authorizationError` beside it. Trusting the flag made TLS decorative on both
+ * paths: the connection was encrypted and would have accepted that encryption from
+ * anyone in the network path, which is the property TLS exists to provide.
+ *
+ * So the error is the signal and the flag is not. Verification is the framework's
+ * to enforce, and it fails closed.
+ *
+ * @param authorized - What the runtime claims about the peer.
+ * @param authorizationError - Why it would not have been authorized, if anything.
+ * @param rejectUnauthorized - Whether this connection asked for verification.
+ * @returns The error to fail with, or `undefined` to accept the peer.
+ */
+function _certificateFailure(
+  authorized: boolean,
+  authorizationError: Error | null | undefined,
+  rejectUnauthorized: boolean,
+): Error | undefined {
+  if (!rejectUnauthorized) return undefined;
+  if (authorized && !authorizationError) return undefined;
+  return authorizationError ?? new Error("the server's certificate could not be verified");
+}
+
 /**
  * A single SMTP session — owns the socket, buffers incoming bytes, and hands
  * back one complete reply at a time.
@@ -210,9 +244,26 @@ export class SmtpConnection {
     port: number,
     options: { tls: boolean; rejectUnauthorized: boolean; timeoutMs: number },
   ): Promise<SmtpConnection> {
-    let conn!: SmtpConnection;
+    // The session, once there is one. A box rather than a bare `let`, because the
+    // socket callbacks below are installed before it exists and have to see it
+    // appear — `Bun.connect()` resolves after the socket is open, so the server's
+    // 220 greeting can beat the `await` that produces it.
+    const session: { conn?: SmtpConnection } = {};
+
+    // Bytes that arrive in that window. Dropping the greeting deadlocks the session
+    // on its own first read.
+    const early: Uint8Array[] = [];
+
+    let settle: (error?: Error) => void = () => {};
+    const verified = options.tls
+      ? new Promise<void>((resolve, reject) => {
+          settle = (error) => (error ? reject(error) : resolve());
+        })
+      : undefined;
+
+    let socket: import("bun").Socket<undefined>;
     try {
-      const socket = await Bun.connect<undefined>({
+      socket = await Bun.connect<undefined>({
         hostname: host,
         port,
         ...(options.tls
@@ -220,14 +271,23 @@ export class SmtpConnection {
           : {}),
         socket: {
           // Generation 0: the connection as opened. An upgrade supersedes it.
-          data: (_s, data) => conn._onData(data, 0),
-          error: (_s, err) => conn._onError(err, 0),
-          close: () => conn._onClose(0),
+          data: (_s, data) => {
+            if (session.conn) session.conn._onData(data, 0);
+            else early.push(data);
+          },
+          error: (_s, err) => {
+            settle(err);
+            session.conn?._onError(err, 0);
+          },
+          close: () => {
+            settle(new Error("the server closed the connection during the TLS handshake"));
+            session.conn?._onClose(0);
+          },
+          handshake: (_s, authorized, authorizationError) =>
+            settle(_certificateFailure(authorized, authorizationError, options.rejectUnauthorized)),
           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} — ${
@@ -235,20 +295,78 @@ export class SmtpConnection {
         }`,
       );
     }
+
+    const conn = new SmtpConnection(socket, host, port, options.timeoutMs, options.tls);
+    session.conn = conn;
+    for (const chunk of early) conn._onData(chunk, 0);
+
+    // Implicit TLS (465) verifies here, for the same reason STARTTLS verifies in
+    // `upgradeTLS`: `rejectUnauthorized` is not enforced by the runtime, so a
+    // connection that asked for a verified certificate has to check that it got one.
+    if (verified) {
+      try {
+        await conn._withTimeout(verified, `completing the TLS handshake with ${host}`);
+      } catch (error) {
+        conn.close();
+        throw new SmtpConnectionError(
+          `TLS connection to ${host}:${port} failed — ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    }
+
+    return conn;
   }
 
-  /** Upgrade a plaintext connection to TLS after a 220 response to STARTTLS. */
+  /**
+   * Upgrade a plaintext connection to TLS after a 220 response to STARTTLS.
+   *
+   * Resolves once the handshake has actually completed, and that is the whole
+   * point of it being async. `upgradeTLS()` returns the new socket immediately,
+   * while the handshake is still in flight, and **a write issued in that window is
+   * dropped** — not buffered and flushed, not an error, just gone. The `EHLO` that
+   * has to follow STARTTLS was written into that gap, so the server sat waiting
+   * for a command that was never sent while the client sat waiting for a reply
+   * that was never coming, until the read timed out thirty seconds later.
+   *
+   * What made it expensive to place is that everything either side looks right.
+   * The handshake completes; the server logs a healthy TLS session and then a
+   * connection lost. Port 465 is unaffected, because implicit TLS finishes its
+   * handshake before `Bun.connect()` resolves and there is no window to write
+   * into. So mail worked, on the port that is not the one every provider
+   * documents, and configuring the documented 587 produced silence — no error, no
+   * bounce, no log line, just password resets that never arrived.
+   *
+   * @param host - Hostname, used as the TLS server name.
+   * @param rejectUnauthorized - Refuse a certificate that does not verify.
+   * @throws {@link SmtpConnectionError} When the upgrade or the handshake fails.
+   */
   async upgradeTLS(host: string, rejectUnauthorized: boolean): Promise<void> {
     try {
       // Bumped before the call, so the plaintext socket's callbacks are already
       // stale by the time the handshake can deliver its first record.
       const generation = ++this._generation;
+
+      let settle!: (error?: Error) => void;
+      const handshake = new Promise<void>((resolve, reject) => {
+        settle = (error) => (error ? reject(error) : resolve());
+      });
+
       const [, tls] = this._socket.upgradeTLS<undefined>({
         tls: { rejectUnauthorized, serverName: host },
         socket: {
           data: (_s, data) => this._onData(data, generation),
-          error: (_s, err) => this._onError(err, generation),
-          close: () => this._onClose(generation),
+          error: (_s, err) => {
+            settle(err);
+            this._onError(err, generation);
+          },
+          close: () => {
+            settle(new Error("the server closed the connection during the TLS handshake"));
+            this._onClose(generation);
+          },
+          handshake: (_s, authorized, authorizationError) =>
+            settle(_certificateFailure(authorized, authorizationError, rejectUnauthorized)),
           open: () => {},
         },
       });
@@ -258,6 +376,8 @@ export class SmtpConnection {
       // belongs to the discarded plaintext stream.
       this._buffer = "";
       this._replies = [];
+
+      await this._withTimeout(handshake, `completing the TLS handshake with ${host}`);
     } catch (error) {
       throw new SmtpConnectionError(
         `STARTTLS upgrade failed for ${host} — ${
@@ -267,6 +387,33 @@ export class SmtpConnection {
     }
   }
 
+  /**
+   * Reject `work` if it has not settled within the session's reply timeout.
+   *
+   * A handshake that never completes and never errors is a hang with no reply to
+   * time out on, so the read timeout that covers every other step does not cover
+   * this one.
+   *
+   * @param work - The promise to bound.
+   * @param what - Named in the timeout message.
+   */
+  private async _withTimeout<T>(work: Promise<T>, what: string): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      return await Promise.race([
+        work,
+        new Promise<never>((_resolve, reject) => {
+          timer = setTimeout(
+            () => reject(new Error(`timed out after ${this._timeoutMs}ms ${what}`)),
+            this._timeoutMs,
+          );
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
   /** Write a command plus its CRLF terminator. */
   send(command: string): void {
     this.write(`${command}\r\n`);

package/src/provider/NotificationProvider.ts

@@ -6,6 +6,7 @@ import { NotificationConfig } from "../config.ts";
 import { installNotificationsObservability } from "../observability.ts";
 import { installNotificationStats } from "../stats.ts";
 import { installNotificationsAdmin } from "../admin.ts";
+import { mailDriverCheck } from "../doctor.ts";
 
 declare module "@zerotal/core" {
   interface ContainerBindings {
@@ -35,6 +36,10 @@ export class NotificationProvider extends ServiceProvider {
     // The admin panel binds its contribution surface during registration, so the
     // booting phase reaches it regardless of provider order.
     installNotificationsAdmin(this.app);
+
+    // `zt doctor`, and through it `zt deploy`: mail going to a log file in
+    // production is the quietest failure this package has.
+    this.app.registerDoctorCheck?.(mailDriverCheck);
   }
 
   override async onBooted(): Promise<void> {

package/src/types.ts

@@ -98,8 +98,8 @@ export interface VonageConfigShape {
 
 export interface SmsConfigShape {
   driver: "twilio" | "vonage";
-  twilio?: TwilioConfigShape;
-  vonage?: VonageConfigShape;
+  twilio?: TwilioConfigShape | undefined;
+  vonage?: VonageConfigShape | undefined;
 }
 
 export interface NotificationConfigShape {
@@ -117,13 +117,15 @@ export interface NotificationConfigShape {
    * The per-notification toSlack() method provides the webhookUrl, so this is
    * only needed if you want a global fallback URL.
    */
-  slack?: {
-    /** Default webhook URL — can be overridden per-notification in toSlack(). */
-    webhook?: string;
-  };
+  slack?:
+    | {
+        /** Default webhook URL — can be overridden per-notification in toSlack(). */
+        webhook?: string;
+      }
+    | undefined;
   /**
    * SMS provider settings (Twilio or Vonage).
    * Required when any notification uses the 'sms' channel.
    */
-  sms?: SmsConfigShape;
+  sms?: SmsConfigShape | undefined;
 }