approval-md 0.0.1 → 0.2.0

package/dist/src/adapters/smtp.d.ts

@@ -0,0 +1,213 @@
+/**
+ * A minimal SMTP client, for the email adapter and nothing else (APRV-69).
+ *
+ * ## Why this exists rather than a dependency
+ *
+ * `CLAUDE.md` and SPEC.md §14 both put minimal dependencies among this
+ * repository's invariants, and a mail library is a large surface to take on for
+ * one send: nodemailer pulls a templating layer, an attachment pipeline, a DKIM
+ * signer, OAuth2 token refresh, and a plugin system, all of it running inside
+ * the one call this project spends its whole design protecting. What is actually
+ * needed is RFC 5321's client half of a single transaction — greeting, EHLO,
+ * optionally STARTTLS, optionally AUTH, MAIL FROM, RCPT TO, DATA, QUIT — which
+ * is this file. `node:net` and `node:tls` and nothing else.
+ *
+ * ## What it deliberately does not do
+ *
+ * No connection pooling, no pipelining, no CHUNKING/BDAT, no SMTPUTF8, no DSN,
+ * no retry. One transaction per {@link sendMail} call, one message per
+ * transaction, and a failure is reported rather than retried: a retry inside an
+ * adapter would be a second side effect under one consumed token, and deciding
+ * to send again is a decision the gate exists to make.
+ *
+ * ## The probe, and the limit of what it proves
+ *
+ * {@link probeSmtp} runs the same session as {@link sendMail} up to and
+ * including AUTH, then says QUIT. It is the same code, one call away
+ * (`runSession` with no envelope), because a setup check that exercises a
+ * different client than the send does is a check that can pass while the send
+ * fails.
+ *
+ * A successful probe proves three things and no more: the host and port accept
+ * a connection, the requested transport security (implicit TLS, or the STARTTLS
+ * upgrade, with the same no-downgrade rule the send obeys) was actually
+ * established, and this server accepts this credential.
+ *
+ * It does **not** prove that a message would be accepted. MAIL FROM, RCPT TO
+ * and DATA are never issued, so nothing about the server's sender policy, its
+ * relaying rules, its recipient validation, its size limits or its content
+ * filtering is exercised. A probe that succeeds against a server which will
+ * later refuse `MAIL FROM:<…>` with a 550 is a probe behaving correctly. Any
+ * caller reporting the result to an operator (`setup adapter email` says
+ * "verified") owes them that distinction: the transport and the login are
+ * verified, the delivery is not.
+ *
+ * ## Failure vocabulary
+ *
+ * Everything is reported, nothing is thrown out of {@link sendMail}. Two
+ * families:
+ *
+ * - the transport codes in {@link SMTP_TRANSPORT_FAILURE_CODES}, which are a
+ *   frozen, additive union (SPEC.md §11.1(6)); and
+ * - a reply-code family, `smtp-<NNN>`, minted from the server's own three-digit
+ *   reply whenever the far side refuses a verb. It is a family rather than an
+ *   enumeration because RFC 5321 lets a server answer with codes this repository
+ *   cannot list in advance, and collapsing "mailbox unavailable" and
+ *   "authentication failed" into one local name would throw away the one piece
+ *   of information an operator needs. {@link SMTP_REPLY_CODE_PATTERN} pins the
+ *   shape.
+ *
+ * ## What may appear in a failure message
+ *
+ * The verb, the reply code, and **the first line of the server's reply text**.
+ * Not the whole reply: a multi-line refusal can run to a screen of banner text,
+ * and everything after the first line is the server explaining itself to a human
+ * rather than telling the client what happened. Not the command: an `AUTH PLAIN
+ * <base64>` echoed into a diagnostic would publish the credential in the one
+ * string the adapter's caller is most likely to print.
+ *
+ * And even the first line is passed through {@link SmtpTransportOptions.redact}
+ * before it is returned, because a server is entitled to quote back the username
+ * it just refused ("535 5.7.8 authentication failed for bot@example.com"), and a
+ * deployment whose username IS the credential would otherwise leak it through a
+ * channel the adapter contract's own guard also covers but which this module
+ * should not be relying on. Two independent scrubs, by design.
+ *
+ * Deterministic apart from the network and the clock it does not read: no
+ * randomness, no ambient configuration, no environment reads.
+ */
+/** How the connection is protected. */
+export type SmtpSecurity = 
+/** TLS from the first byte (the submissions port, 465). */
+"implicit"
+/** Plaintext, then a mandatory STARTTLS upgrade (the submission port, 587). */
+ | "starttls"
+/**
+ * Plaintext, and it stays that way. Only sane for a relay on the same host;
+ * the adapter refuses to AUTH over it, because a password on a cleartext
+ * socket is a password on the wire.
+ */
+ | "none";
+export declare function isSmtpSecurity(value: unknown): value is SmtpSecurity;
+/**
+ * Transport failures this client can report. Frozen union, additive only
+ * (SPEC.md §11.1(6)).
+ *
+ * They are distinguished because they call for four different responses: fix
+ * the address, fix the TLS configuration, look at why the far side is slow, and
+ * report a server that is not speaking SMTP.
+ */
+export declare const SMTP_TRANSPORT_FAILURE_CODES: readonly [
+/** The TCP connection could not be established at all. */
+"smtp-connect-failed", 
+/** TLS could not be established, or the server would not offer STARTTLS. */
+"smtp-tls-failed", 
+/** The session exceeded its whole-transaction budget. */
+"smtp-timeout", 
+/** The far side sent something that is not an SMTP reply, or hung up. */
+"smtp-protocol-error"];
+export type SmtpTransportFailureCode = (typeof SMTP_TRANSPORT_FAILURE_CODES)[number];
+/** The shape of a minted reply-code failure: `smtp-` and three digits. */
+export declare const SMTP_REPLY_CODE_PATTERN: RegExp;
+/** The default whole-session budget, in milliseconds. */
+export declare const DEFAULT_SMTP_TIMEOUT_MS = 30000;
+/** A parsed SMTP reply. `lines` holds the text of each line, code stripped. */
+export interface SmtpReply {
+    code: number;
+    lines: string[];
+    /** The first line's text, which is the only part any message may quote. */
+    first: string;
+}
+export interface SmtpTransportOptions {
+    host: string;
+    port: number;
+    security: SmtpSecurity;
+    /** Omitted (or empty) means the session does not authenticate. */
+    user?: string;
+    password?: string;
+    /** Whole-session budget. Exceeding it is `smtp-timeout`. */
+    timeoutMs?: number;
+    /** The name this client gives in EHLO. */
+    clientName?: string;
+    /**
+     * TLS certificate verification. **Defaults to `true`, and production must
+     * leave it there.** The only sanctioned `false` is a test against a mock on
+     * 127.0.0.1 holding a self-signed fixture certificate.
+     */
+    tlsRejectUnauthorized?: boolean;
+    /** Applied to every string this module returns. See the module header. */
+    redact?(text: string): string;
+}
+/** The SMTP envelope, which is not the message's headers. */
+export interface SmtpEnvelope {
+    /** MAIL FROM. The return path, not necessarily the From: header. */
+    from: string;
+    /** RCPT TO, once each: To, Cc, and **Bcc**, which appear in no header. */
+    recipients: readonly string[];
+}
+export type SmtpSendResult = {
+    ok: true;
+    /** The reply to the end-of-data terminator: the server accepting it. */
+    reply: {
+        code: number;
+        text: string;
+    };
+    /** `VERB code` for each step, in order. Never a command argument. */
+    transcript: string[];
+    /** Was the message handed over on an encrypted socket? */
+    secure: boolean;
+    /** Did the session authenticate, and with which mechanism? */
+    authenticated: "PLAIN" | "LOGIN" | null;
+} | {
+    ok: false;
+    code: SmtpTransportFailureCode | `smtp-${number}`;
+    message: string;
+    transcript: string[];
+    secure: boolean;
+};
+/**
+ * What {@link probeSmtp} reports: {@link SmtpSendResult} without `reply`, since
+ * a probe never issues a verb whose reply is anything but a step of the
+ * session. The failure codes are the same union, from the same code path.
+ */
+export type SmtpProbeResult = {
+    ok: true;
+    /** `VERB code` for each step, in order. Never a command argument. */
+    transcript: string[];
+    /** Was the session encrypted when it ended? */
+    secure: boolean;
+    /** Did the session authenticate, and with which mechanism? */
+    authenticated: "PLAIN" | "LOGIN" | null;
+} | {
+    ok: false;
+    code: SmtpTransportFailureCode | `smtp-${number}`;
+    message: string;
+    transcript: string[];
+    secure: boolean;
+};
+/**
+ * Run one SMTP transaction and report how it went. Never throws.
+ *
+ * The whole of it is {@link runSession}; this is the entry point that supplies
+ * an envelope and a message, and its result is unchanged from the day it was
+ * the whole function.
+ */
+export declare function sendMail(options: SmtpTransportOptions, envelope: SmtpEnvelope, message: string): Promise<SmtpSendResult>;
+/**
+ * Open a session, authenticate, send nothing, and report. Never throws.
+ *
+ * Exactly {@link sendMail}'s session up to AUTH — the same connection, the same
+ * STARTTLS rules including the no-downgrade refusal and the response-injection
+ * guard, the same refusal to put a password on a cleartext socket, the same
+ * one-session budget, the same redaction of every string it returns — and then
+ * QUIT. See this module's header for what a success does and does not prove:
+ * transport, TLS mode and credential, never that a message would be delivered.
+ */
+export declare function probeSmtp(options: SmtpTransportOptions): Promise<SmtpProbeResult>;
+/**
+ * RFC 5321 §4.5.2: a line of the message that begins with `.` gets a second
+ * one, so the terminator cannot be forged by the message's own content. The
+ * terminating `.` line is NOT added here; {@link sendMail} sends it as its own
+ * command so the transcript records the reply to it.
+ */
+export declare function dotStuff(message: string): string;