@tsdmarc/smtp 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @tsdmarc/smtp
+
+## 1.0.0
+
+### Major Changes
+
+- a1c5fad: First release: a 1:1 TypeScript port of parsedmarc 11.2.1 and of the parts of mailsuite 2.3.4 it uses, for Node.js 24+, Bun and Deno.
+
+### Patch Changes
+
+- Updated dependencies [a1c5fad]
+  - tsdmarc@1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,61 @@
+tsdmarc
+Copyright 2026 tsdmarc contributors
+
+This product is a TypeScript port of parsedmarc
+(https://github.com/domainaware/parsedmarc), Copyright Sean Whalen and
+parsedmarc contributors, licensed under the Apache License, Version 2.0.
+Ported from parsedmarc 11.2.1, commit 7bbc405c01a1c4c37811b2a3746e8881c00cda39.
+
+The mailbox connection and SMTP code is a port of mailsuite
+(https://github.com/seanthegeek/mailsuite), Copyright Sean Whalen,
+licensed under the Apache License, Version 2.0.
+Ported from mailsuite 2.3.4, commit 3bd62831d137c9aa7884be33b83323ca3a1bd1de.
+
+All source files were translated from Python to TypeScript; this is a
+modification of the original works within the meaning of section 4(b) of
+the Apache License.
+
+Third-party data files in resources/:
+- ipinfo_lite.mmdb: IPinfo Lite, (c) IPinfo (https://ipinfo.io/lite),
+  licensed under CC BY-SA 4.0.
+- base_reverse_dns_map.csv: from parsedmarc, derived in part from IPinfo
+  Lite data, licensed under CC BY-SA 4.0.
+
+Ported third-party code in packages/tsdmarc/src (behavior reimplemented in
+TypeScript to reproduce parsedmarc's output exactly):
+- xml/expat.ts, xml/expat-names.ts: port of parts of Expat 2.9.0
+  (https://libexpat.github.io/), Copyright (c) 1997-2000 Thai Open Source
+  Software Center Ltd and Copyright (c) 2000-2026 Expat development team,
+  licensed under the MIT License.
+- xml/xmltodict.ts: port of xmltodict (https://github.com/martinblech/xmltodict),
+  Copyright (c) 2012 Martin Blech, licensed under the MIT License.
+- xml/recover.ts: emulates the observable recovery behavior of libxml2
+  (https://gitlab.gnome.org/GNOME/libxml2), MIT License.
+- utils/py-email/, utils/py-codecs*.ts, utils/py-binascii.ts, utils/py-str.ts,
+  csv.ts, utils/csv-reader.ts, utils/url-split.ts: ports of parts of the
+  CPython standard library (https://github.com/python/cpython), Copyright (c)
+  2001 Python Software Foundation, licensed under the PSF License Agreement.
+- utils/mailparser/: port of mail-parser 4.8.0
+  (https://github.com/SpamScope/mail-parser), Copyright Fedele Mantuano,
+  licensed under the Apache License, Version 2.0.
+- utils/dns*.ts: port of parts of dnspython (https://www.dnspython.org/),
+  Copyright (c) Dnspython Contributors, licensed under the ISC License.
+- utils/timestamps.ts: date parsing compatible with python-dateutil
+  (https://github.com/dateutil/dateutil), Apache License 2.0 / BSD 3-Clause.
+- internal/zipfile.ts and the decompressor wrappers in internal/bz2.ts,
+  internal/lzma.ts, internal/zstd.ts and internal/zlib.ts: ports of parts of
+  the CPython standard library (zipfile, bz2, lzma, compression.zstd, zlib
+  modules), Copyright (c) 2001 Python Software Foundation, licensed under the
+  PSF License Agreement.
+- internal/zlib.ts: port of the inflate code of zlib 1.3 (https://zlib.net/),
+  Copyright (C) 1995-2023 Jean-loup Gailly and Mark Adler, licensed under the
+  zlib License.
+- internal/bz2.ts: port of the libbzip2 1.0.8 decompressor
+  (https://sourceware.org/bzip2/), Copyright (C) 1996-2019 Julian R Seward,
+  licensed under the bzip2 license (BSD-style).
+- internal/lzma.ts: port of the LZMA1 decoder of liblzma 5.8
+  (https://tukaani.org/xz/), by Igor Pavlov and Lasse Collin, licensed under
+  the BSD Zero Clause License (0BSD).
+- internal/zstd.ts: port of the libzstd 1.5.7 decoder
+  (https://github.com/facebook/zstd), Copyright (c) Meta Platforms, Inc. and
+  affiliates, licensed under the BSD 3-Clause License.

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# @tsdmarc/smtp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Send [tsdmarc](https://github.com/helixnebulatech/tsdmarc#readme) results by email over SMTP, built on [nodemailer](https://nodemailer.com). Port of `mailsuite.smtp.send_email` and parsedmarc's `email_results()`.
+
+## Install
+
+```sh
+npm install tsdmarc @tsdmarc/smtp
+```
+
+`tsdmarc` is a peer dependency. With pnpm or Bun: `pnpm add tsdmarc @tsdmarc/smtp` / `bun add tsdmarc @tsdmarc/smtp`. Requires Node 24 or later (Bun and Deno also work).
+
+## Usage
+
+Email parsing results as a zip file (the same JSON and CSV files that `saveOutput()` writes):
+
+```ts
+import { emailResults } from '@tsdmarc/smtp';
+import { getDmarcReportsFromMailbox, getReportZip } from 'tsdmarc';
+
+const results = await getDmarcReportsFromMailbox(connection, {
+  reportsFolder: 'INBOX',
+});
+
+await emailResults(
+  results,
+  'smtp.example.com', // host
+  'dmarc@example.com', // from
+  ['dmarc-team@example.com'], // to
+  {
+    reportZip: getReportZip,
+    port: 587,
+    username: 'dmarc@example.com',
+    password: process.env.SMTP_PASSWORD,
+  },
+);
+```
+
+`connection` is any mailbox connection, for example from [`@tsdmarc/imap`](https://www.npmjs.com/package/@tsdmarc/imap). Any `ParsingResults` object works.
+
+Send an arbitrary message:
+
+```ts
+import { readFile } from 'node:fs/promises';
+
+import { sendEmail } from '@tsdmarc/smtp';
+
+await sendEmail('smtp.example.com', 'dmarc@example.com', {
+  messageTo: ['dmarc-team@example.com'],
+  requireEncryption: true, // SMTPS on port 465
+  username: 'dmarc@example.com',
+  password: process.env.SMTP_PASSWORD,
+  subject: 'Weekly DMARC summary',
+  plainMessage: 'See the attachment.',
+  attachments: [['summary.csv', await readFile('summary.csv')]],
+});
+```
+
+## Options
+
+`emailResults(results, host, mailFrom, mailTo, options)`. `EmailResultsOptions`:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `reportZip` | `Uint8Array \| (results) => Uint8Array \| Promise<Uint8Array>` | required | The zip attachment, or how to build it. Pass the core's `getReportZip`. |
+| `subject` | `string \| null` | `DMARC results for YYYY-MM-DD` | Subject. |
+| `message` | `string \| null` | `DMARC results for YYYY-MM-DD` | Plain text body. |
+| `attachmentFilename` | `string \| null` | `DMARC-YYYY-MM-DD.zip` | Attachment filename. `.zip` is appended if missing. |
+| `mailCc` | `string[] \| null` | `null` | Cc addresses. |
+| `mailBcc` | `string[] \| null` | `null` | Bcc addresses. |
+| `port` | `number` | `0` | `0` means 465 with `requireEncryption`, else 25. |
+| `requireEncryption` | `boolean` | `false` | Use TLS from the start (SMTPS). Otherwise the connection starts in plain text and `starttls` decides whether it is upgraded. |
+| `verify` | `boolean` | `true` | Verify the server's TLS certificate. |
+| `starttls` | `boolean \| null` | `null` | Without `requireEncryption`: `null` upgrades when the server advertises STARTTLS and refuses to send credentials otherwise, `true` requires the upgrade, `false` never upgrades (credentials are sent in plain text, with a warning). |
+| `username` | `string \| null` | `null` | SMTP username. |
+| `password` | `string \| null` | `null` | SMTP password. |
+
+`sendEmail(host, messageFrom, options)`. `SendEmailOptions`:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `messageTo` | `string[] \| null` | required | Recipients. A missing value throws `TypeError`. |
+| `messageCc` | `string[] \| null` | `null` | Cc addresses. |
+| `messageBcc` | `string[] \| null` | `null` | Bcc addresses (SMTP envelope only, never in the headers). |
+| `port` | `number` | `0` | `0` means 465 with `requireEncryption`, else 25, like smtplib. |
+| `requireEncryption` | `boolean` | `false` | Use TLS from the start (SMTPS). |
+| `starttls` | `boolean \| null` | `null` | As in `EmailResultsOptions`. |
+| `verify` | `boolean` | `true` | Verify the server's TLS certificate. |
+| `username` | `string \| null` | `null` | SMTP username. Credentials are sent only when both `username` and `password` are set. |
+| `password` | `string \| null` | `null` | SMTP password. |
+| `subject` | `string \| null` | `null` | Subject. |
+| `plainMessage` | `string \| null` | `null` | Plain text body. |
+| `attachments` | `[filename, Uint8Array][] \| null` | `null` | Attached as `application/octet-stream`. |
+
+`EmailResultsOptions` also takes `starttls`, like parsedmarc 11.2.1's `email_results()`.
+
+Connection and protocol failures throw `SMTPError`.
+
+## Notes
+
+- **No credentials over plain text** (mailsuite 2.3.4, GHSA-2x4j-7g3q-wr6f). `starttls` is ignored with `requireEncryption`:
+  - `null` (default) upgrades when STARTTLS is advertised. When it is not, a username and password make it throw `SMTPError("The SMTP server does not advertise STARTTLS, so credentials would be sent in plain text. ...")` before `AUTH`; without credentials the mail is sent in plain text with a warning.
+  - `true` requires the upgrade and throws `SMTPError("STARTTLS required but not supported by the server")`.
+  - `false` never upgrades: credentials and mail are sent in plain text, with the warning `Sending SMTP credentials unencrypted because starttls=False` when there are credentials. Only for local or otherwise trusted servers.
+- **CLI:** the `[smtp]` section of [`@tsdmarc/cli`](https://www.npmjs.com/package/@tsdmarc/cli) configures `emailResults()`. Its `starttls` key (or `TSDMARC_SMTP_STARTTLS`), as in parsedmarc 11.2.1, is passed as `starttls`; with `starttls = False` and `ssl = False` a warning is logged at startup.
+
+All deliberate differences from parsedmarc are listed in [Differences from parsedmarc](https://github.com/helixnebulatech/tsdmarc/blob/main/architecture/README.md#differences-from-parsedmarc).
+
+---
+
+Part of [tsdmarc](https://github.com/helixnebulatech/tsdmarc#readme), a TypeScript port of [parsedmarc](https://github.com/domainaware/parsedmarc). Licensed under Apache-2.0.
+
+Created by [HelixNebula](https://helixnebula.tech).

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+import { ParsingResults } from "tsdmarc";
+/**
+ * The zip attachment: its bytes, or a function that builds them from the
+ * results. Pass the core's `getReportZip` (parsedmarc's `get_report_zip()`).
+ */
+type ReportZip = Uint8Array | ((results: ParsingResults) => Promise<Uint8Array> | Uint8Array);
+interface ReportEmailContentOptions {
+  /** Overrides the default subject (`DMARC results for YYYY-MM-DD`). */
+  subject?: string | null;
+  /** Overrides the default attachment filename; `.zip` is appended if missing. */
+  attachmentFilename?: string | null;
+  /** Overrides the default plain text body. */
+  message?: string | null;
+  /** The zip attachment, or how to build it. */
+  reportZip: ReportZip;
+}
+interface ReportEmailContent {
+  subject: string;
+  message: string;
+  attachments: [string, Uint8Array][];
+}
+interface EmailResultsOptions extends ReportEmailContentOptions {
+  mailCc?: string[] | null;
+  mailBcc?: string[] | null;
+  /** 0 (default): 465 with `requireEncryption`, else 25. */
+  port?: number;
+  /**
+   * Connect with implicit SSL/TLS from the start (usually port 465). When
+   * false, the connection starts in plain text and `starttls` decides
+   * whether it is upgraded.
+   */
+  requireEncryption?: boolean;
+  /**
+   * Whether to upgrade a plain-text (`requireEncryption: false`) connection
+   * with STARTTLS (parsedmarc 11.2.1). `null`/`undefined` (default)
+   * upgrades when the server advertises STARTTLS; when it does not,
+   * `SMTPError` is thrown before authenticating if `username` and
+   * `password` are given, and without credentials the message is sent in
+   * plain text with a warning. `true` requires the upgrade. `false` never
+   * upgrades, so any credentials and the message are sent in plain text (a
+   * warning is logged when credentials are sent). Ignored with
+   * `requireEncryption`. See `SendEmailOptions.starttls`.
+   */
+  starttls?: boolean | null;
+  /** Verify the TLS certificate. Default: true. */
+  verify?: boolean;
+  username?: string | null;
+  password?: string | null;
+}
+/**
+ * Build the subject, plain text body and zip attachment shared by every
+ * report-summary email transport (SMTP here, Microsoft Graph in
+ * `@tsdmarc/msgraph`).
+ */
+export declare function buildReportEmailContent(results: ParsingResults, options: ReportEmailContentOptions): Promise<ReportEmailContent>;
+/**
+ * Email parsing results as a zip file.
+ *
+ * `options.reportZip` provides the attachment: pass the core's
+ * `getReportZip` (or bytes already built). parsedmarc calls
+ * `get_report_zip()` itself; taking it as an argument keeps this package
+ * independent of the output module.
+ */
+export declare function emailResults(results: ParsingResults, host: string, mailFrom: string, mailTo: string[] | null, options: EmailResultsOptions): Promise<void>;
+/** Raised when a SMTP error occurs. */
+export declare class SMTPError extends Error {
+  override name: string;
+}
+interface SendEmailOptions {
+  /** Addresses to send mail to. Required (mailsuite raises when it is missing). */
+  messageTo?: string[] | null;
+  /** Addresses to Carbon Copy. */
+  messageCc?: string[] | null;
+  /** Addresses to Blind Carbon Copy (envelope only, never in the headers). */
+  messageBcc?: string[] | null;
+  /** Port. 0 (the default) means 465 with `requireEncryption`, else 25, like smtplib. */
+  port?: number;
+  /**
+   * Use TLS from the start (SMTPS). Otherwise the connection starts in
+   * plain text and `starttls` decides whether it is upgraded.
+   */
+  requireEncryption?: boolean;
+  /**
+   * Whether to upgrade a plain-text (`requireEncryption: false`) connection
+   * with STARTTLS (mailsuite 2.3.4). `null`/`undefined` (default) upgrades
+   * when the server advertises STARTTLS. When it does not, it throws
+   * `SMTPError` before authenticating if credentials (`username` and
+   * `password`) were given, so they are never sent in plain text; without
+   * credentials the message is sent in plain text and a warning is logged.
+   * `false` never upgrades, so the connection stays plain text even when
+   * STARTTLS is advertised, and any credentials are sent unencrypted (a
+   * warning is logged when they are). `true` requires the upgrade and
+   * throws `SMTPError("STARTTLS required but not supported by the server")`
+   * if the server does not advertise STARTTLS. Ignored with
+   * `requireEncryption`, because the connection is already TLS.
+   */
+  starttls?: boolean | null;
+  /** Verify the server's TLS certificate. Default: true. */
+  verify?: boolean;
+  username?: string | null;
+  password?: string | null;
+  subject?: string | null;
+  /** `[filename, content]` pairs, attached as `application/octet-stream`. */
+  attachments?: [string, Uint8Array][] | null;
+  /** The plain text body. */
+  plainMessage?: string | null;
+}
+/**
+ * Send an email using a SMTP relay.
+ *
+ * Without `requireEncryption` the connection starts in plain text and is
+ * upgraded with STARTTLS when the server offers it (see `starttls` to never
+ * or always upgrade). When it is not offered, credentials are refused with
+ * `SMTPError` before they are sent, and a message without credentials goes
+ * out unencrypted with a warning, as with mailsuite. Every
+ * recipient (To, Cc and Bcc) is in the SMTP envelope; Bcc is never in the
+ * headers. Connection and protocol failures raise `SMTPError`.
+ */
+export declare function sendEmail(host: string, messageFrom: string, options?: SendEmailOptions): Promise<void>;
+export type { EmailResultsOptions, ReportEmailContent, ReportEmailContentOptions, ReportZip, SendEmailOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,211 @@
+import { AssertionError } from "node:assert";
+import { createEmail, logger } from "tsdmarc";
+import addressparser from "nodemailer/lib/addressparser";
+import SMTPConnection from "nodemailer/lib/smtp-connection";
+// src/send-email.ts
+/** Raised when a SMTP error occurs. */
+var SMTPError = class extends Error {
+	name = "SMTPError";
+};
+const SMTP_PORT = 25;
+const SMTPS_PORT = 465;
+const PLAINTEXT_REFUSAL = "The SMTP server does not advertise STARTTLS, so credentials would be sent in plain text. Use require_encryption=True for implicit TLS, or pass starttls=False to allow plain-text authentication";
+/**
+* Build the message with the core's port of mailsuite's `create_email()`,
+* with CRLF line endings as smtplib's `sendmail()` sends it.
+*/
+function buildMessage(messageFrom, options) {
+	return createEmail({
+		attachments: options.attachments ?? null,
+		messageCc: options.messageCc ?? null,
+		messageFrom,
+		messageTo: options.messageTo ?? null,
+		plainMessage: options.plainMessage ?? null,
+		subject: options.subject ?? null
+	}).replaceAll(/\r?\n/gu, "\r\n");
+}
+/** smtplib's `quoteaddr()`: the bare address of `Name <user@host>`. */
+function envelopeAddress(address) {
+	const [parsed] = addressparser(address, { flatten: true });
+	return parsed?.address || address;
+}
+const DNS_CODES = /* @__PURE__ */ new Set([
+	"EAI_AGAIN",
+	"EAI_FAIL",
+	"EAI_NONAME",
+	"EDNS",
+	"ENOTFOUND"
+]);
+const CERTIFICATE_CODE = /^(?:CERT_|ERR_TLS_CERT|DEPTH_ZERO_SELF_SIGNED_CERT|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_(?:GET_ISSUER_CERT|VERIFY_LEAF_SIGNATURE)|HOSTNAME_MISMATCH)/u;
+const CERTIFICATE_MESSAGE = /certificate|self[- ]signed/iu;
+/** mailsuite's `str(error).lstrip("b'").rstrip("'").rstrip(".")`. */
+function stripErrorText(text) {
+	return text.replace(/^[b']+/u, "").replace(/'+$/u, "").replace(/\.+$/u, "");
+}
+/**
+* Translate a nodemailer/socket error into mailsuite's `SMTPError`
+* messages. Errors that don't come from the connection (no `code`) are
+* returned unchanged, as Python lets non-SMTP exceptions propagate.
+*/
+function toSMTPError(error) {
+	if (!(error instanceof Error) || error instanceof SMTPError) return error;
+	const fields = error;
+	const code = typeof fields.code === "string" ? fields.code : "";
+	const originalCode = typeof fields.originalCode === "string" ? fields.originalCode : code;
+	if (code === "") return error;
+	const options = { cause: error };
+	if (DNS_CODES.has(originalCode) || code === "EDNS") return new SMTPError("DNS resolution failed", options);
+	if (originalCode === "ECONNREFUSED") return new SMTPError("Connection refused", options);
+	if (originalCode === "ECONNRESET") return new SMTPError("Connection reset", options);
+	if (originalCode === "ECONNABORTED") return new SMTPError("Connection aborted", options);
+	if (originalCode === "ETIMEDOUT" || code === "ETIMEDOUT") return new SMTPError("Connection timed out", options);
+	if (CERTIFICATE_CODE.test(originalCode) || code === "ETLS" && CERTIFICATE_MESSAGE.test(error.message)) return new SMTPError(`Certificate error: ${error.message}`, options);
+	if (code === "ETLS" || originalCode.startsWith("ERR_SSL_")) return new SMTPError(`SSL error: ${error.message}`, options);
+	return new SMTPError(stripErrorText(error.message), options);
+}
+/**
+* Whether the server's (plain-text) EHLO reply advertised STARTTLS. With
+* `ignoreTLS`, nodemailer keeps that reply in `_ehloLines` (it has no public
+* accessor); without it, the answer is false.
+*/
+function advertisesStartTls(connection) {
+	const lines = connection._ehloLines;
+	return Array.isArray(lines) && lines.some((line) => typeof line === "string" && /^STARTTLS\b/iu.test(line.trim()));
+}
+/** Run one callback-style SMTPConnection step, failing on an 'error' event too. */
+function step(connection, start) {
+	return new Promise((resolve, reject) => {
+		const onError = (error) => reject(error);
+		connection.once("error", onError);
+		start((error, value) => {
+			connection.removeListener("error", onError);
+			if (error) reject(error);
+			else resolve(value);
+		});
+	});
+}
+/**
+* Send an email using a SMTP relay.
+*
+* Without `requireEncryption` the connection starts in plain text and is
+* upgraded with STARTTLS when the server offers it (see `starttls` to never
+* or always upgrade). When it is not offered, credentials are refused with
+* `SMTPError` before they are sent, and a message without credentials goes
+* out unencrypted with a warning, as with mailsuite. Every
+* recipient (To, Cc and Bcc) is in the SMTP envelope; Bcc is never in the
+* headers. Connection and protocol failures raise `SMTPError`.
+*/
+async function sendEmail(host, messageFrom, options = {}) {
+	const message = buildMessage(messageFrom, options);
+	const requireEncryption = options.requireEncryption ?? false;
+	const starttls = requireEncryption ? null : options.starttls ?? null;
+	const { username, password } = options;
+	const auth = username && password ? {
+		user: username,
+		pass: password
+	} : null;
+	let connection = null;
+	try {
+		connection = new SMTPConnection({
+			host,
+			port: options.port || (requireEncryption ? SMTPS_PORT : SMTP_PORT),
+			secure: requireEncryption,
+			...starttls === false ? { ignoreTLS: true } : {},
+			tls: options.verify === false ? { rejectUnauthorized: false } : {},
+			logger: false
+		});
+		connection.on("error", () => void 0);
+		const active = connection;
+		await step(active, (done) => active.connect((error) => done(error)));
+		if (!(requireEncryption || active.secure)) {
+			if (starttls === false) {
+				if (advertisesStartTls(active)) logger.info("SMTP server supports STARTTLS, but it is disabled ... staying in plain text");
+				if (auth !== null) logger.warning("Sending SMTP credentials unencrypted because starttls=False");
+			} else if (starttls === true) throw new SMTPError("STARTTLS required but not supported by the server");
+			else if (auth === null) logger.warning("SMTP server does not support STARTTLS. Proceeding in plain text!");
+			else throw new SMTPError(PLAINTEXT_REFUSAL);
+		}
+		if (auth !== null) await step(active, (done) => active.login(auth, done));
+		const messageTo = options.messageTo ?? null;
+		if (messageTo === null) throw new TypeError("message_to cannot be None");
+		const envelopeTo = [.../* @__PURE__ */ new Set([
+			...messageTo,
+			...options.messageCc ?? [],
+			...options.messageBcc ?? []
+		])].map(envelopeAddress);
+		const envelope = {
+			from: envelopeAddress(messageFrom),
+			to: envelopeTo
+		};
+		await step(active, (done) => active.send(envelope, message, done));
+	} catch (error) {
+		throw toSMTPError(error);
+	} finally {
+		connection?.quit();
+	}
+}
+// src/email-results.ts
+function pad(value) {
+	return String(value).padStart(2, "0");
+}
+/** `datetime.now().strftime("%Y-%m-%d")`: today's local date. */
+function localDateString(now = /* @__PURE__ */ new Date()) {
+	return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+/**
+* Build the subject, plain text body and zip attachment shared by every
+* report-summary email transport (SMTP here, Microsoft Graph in
+* `@tsdmarc/msgraph`).
+*/
+async function buildReportEmailContent(results, options) {
+	const dateString = localDateString();
+	let filename;
+	if (options.attachmentFilename) {
+		filename = options.attachmentFilename;
+		if (!filename.toLowerCase().endsWith(".zip")) filename += ".zip";
+	} else filename = `DMARC-${dateString}.zip`;
+	const subject = options.subject ?? `DMARC results for ${dateString}`;
+	const message = options.message ?? `DMARC results for ${dateString}`;
+	const { reportZip } = options;
+	const zipBytes = typeof reportZip === "function" ? await reportZip(results) : reportZip;
+	return {
+		subject,
+		message,
+		attachments: [[filename, zipBytes]]
+	};
+}
+/**
+* Email parsing results as a zip file.
+*
+* `options.reportZip` provides the attachment: pass the core's
+* `getReportZip` (or bytes already built). parsedmarc calls
+* `get_report_zip()` itself; taking it as an argument keeps this package
+* independent of the output module.
+*/
+async function emailResults(results, host, mailFrom, mailTo, options) {
+	logger.debug("Emailing report");
+	if (!Array.isArray(mailTo)) throw new AssertionError({
+		message: "mail_to must be a list",
+		actual: mailTo,
+		expected: "an array",
+		operator: "Array.isArray"
+	});
+	const { subject, message, attachments } = await buildReportEmailContent(results, options);
+	await sendEmail(host, mailFrom, {
+		messageTo: mailTo,
+		messageCc: options.mailCc ?? null,
+		messageBcc: options.mailBcc ?? null,
+		port: options.port ?? 0,
+		requireEncryption: options.requireEncryption ?? false,
+		verify: options.verify ?? true,
+		username: options.username ?? null,
+		password: options.password ?? null,
+		subject,
+		attachments,
+		plainMessage: message,
+		starttls: options.starttls ?? null
+	});
+}
+export { SMTPError, buildReportEmailContent, emailResults, sendEmail };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/send-email.ts","../src/email-results.ts"],"sourcesContent":["// Send an email over SMTP, ported from mailsuite.smtp.send_email.\n//\n// Only the arguments parsedmarc passes are ported (see `email_results()`):\n// DKIM signing, OAuth2, `envelope_from`, custom headers and HTML bodies are\n// mailsuite features parsedmarc never uses. The message is built with\n// the core's createEmail() and sent with nodemailer's SMTPConnection, which gives\n// the same control smtplib does: implicit TLS or opportunistic STARTTLS,\n// optional login, and an explicit envelope.\n\nimport addressparser from 'nodemailer/lib/addressparser';\nimport SMTPConnection from 'nodemailer/lib/smtp-connection';\nimport { createEmail, logger } from 'tsdmarc';\n\n/** Raised when a SMTP error occurs. */\nexport class SMTPError extends Error {\n  override name = 'SMTPError';\n}\n\nexport interface SendEmailOptions {\n  /** Addresses to send mail to. Required (mailsuite raises when it is missing). */\n  messageTo?: string[] | null;\n  /** Addresses to Carbon Copy. */\n  messageCc?: string[] | null;\n  /** Addresses to Blind Carbon Copy (envelope only, never in the headers). */\n  messageBcc?: string[] | null;\n  /** Port. 0 (the default) means 465 with `requireEncryption`, else 25, like smtplib. */\n  port?: number;\n  /**\n   * Use TLS from the start (SMTPS). Otherwise the connection starts in\n   * plain text and `starttls` decides whether it is upgraded.\n   */\n  requireEncryption?: boolean;\n  /**\n   * Whether to upgrade a plain-text (`requireEncryption: false`) connection\n   * with STARTTLS (mailsuite 2.3.4). `null`/`undefined` (default) upgrades\n   * when the server advertises STARTTLS. When it does not, it throws\n   * `SMTPError` before authenticating if credentials (`username` and\n   * `password`) were given, so they are never sent in plain text; without\n   * credentials the message is sent in plain text and a warning is logged.\n   * `false` never upgrades, so the connection stays plain text even when\n   * STARTTLS is advertised, and any credentials are sent unencrypted (a\n   * warning is logged when they are). `true` requires the upgrade and\n   * throws `SMTPError(\"STARTTLS required but not supported by the server\")`\n   * if the server does not advertise STARTTLS. Ignored with\n   * `requireEncryption`, because the connection is already TLS.\n   */\n  starttls?: boolean | null;\n  /** Verify the server's TLS certificate. Default: true. */\n  verify?: boolean;\n  username?: string | null;\n  password?: string | null;\n  subject?: string | null;\n  /** `[filename, content]` pairs, attached as `application/octet-stream`. */\n  attachments?: [string, Uint8Array][] | null;\n  /** The plain text body. */\n  plainMessage?: string | null;\n}\n\nconst SMTP_PORT = 25;\nconst SMTPS_PORT = 465;\nconst PLAINTEXT_REFUSAL =\n  'The SMTP server does not advertise STARTTLS, so credentials would be sent in plain text. Use require_encryption=True for implicit TLS, or pass starttls=False to allow plain-text authentication';\n\n/**\n * Build the message with the core's port of mailsuite's `create_email()`,\n * with CRLF line endings as smtplib's `sendmail()` sends it.\n */\nfunction buildMessage(messageFrom: string, options: SendEmailOptions): string {\n  return createEmail({\n    attachments: options.attachments ?? null,\n    messageCc: options.messageCc ?? null,\n    messageFrom,\n    messageTo: options.messageTo ?? null,\n    plainMessage: options.plainMessage ?? null,\n    subject: options.subject ?? null,\n  }).replaceAll(/\\r?\\n/gu, '\\r\\n');\n}\n\n/** smtplib's `quoteaddr()`: the bare address of `Name <user@host>`. */\nfunction envelopeAddress(address: string): string {\n  const [parsed] = addressparser(address, { flatten: true });\n  return parsed?.address || address;\n}\n\ninterface NodemailerErrorFields {\n  code?: unknown;\n  originalCode?: unknown;\n}\n\nconst DNS_CODES: ReadonlySet<string> = new Set([\n  'EAI_AGAIN',\n  'EAI_FAIL',\n  'EAI_NONAME',\n  'EDNS',\n  'ENOTFOUND',\n]);\nconst CERTIFICATE_CODE =\n  /^(?:CERT_|ERR_TLS_CERT|DEPTH_ZERO_SELF_SIGNED_CERT|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_(?:GET_ISSUER_CERT|VERIFY_LEAF_SIGNATURE)|HOSTNAME_MISMATCH)/u;\nconst CERTIFICATE_MESSAGE = /certificate|self[- ]signed/iu;\n\n/** mailsuite's `str(error).lstrip(\"b'\").rstrip(\"'\").rstrip(\".\")`. */\nfunction stripErrorText(text: string): string {\n  return text\n    .replace(/^[b']+/u, '')\n    .replace(/'+$/u, '')\n    .replace(/\\.+$/u, '');\n}\n\n/**\n * Translate a nodemailer/socket error into mailsuite's `SMTPError`\n * messages. Errors that don't come from the connection (no `code`) are\n * returned unchanged, as Python lets non-SMTP exceptions propagate.\n */\nfunction toSMTPError(error: unknown): unknown {\n  if (!(error instanceof Error) || error instanceof SMTPError) {\n    return error;\n  }\n  const fields = error as NodemailerErrorFields;\n  const code = typeof fields.code === 'string' ? fields.code : '';\n  const originalCode =\n    typeof fields.originalCode === 'string' ? fields.originalCode : code;\n  if (code === '') {\n    return error;\n  }\n  const options = { cause: error };\n  if (DNS_CODES.has(originalCode) || code === 'EDNS') {\n    return new SMTPError('DNS resolution failed', options);\n  }\n  if (originalCode === 'ECONNREFUSED') {\n    return new SMTPError('Connection refused', options);\n  }\n  if (originalCode === 'ECONNRESET') {\n    return new SMTPError('Connection reset', options);\n  }\n  if (originalCode === 'ECONNABORTED') {\n    return new SMTPError('Connection aborted', options);\n  }\n  if (originalCode === 'ETIMEDOUT' || code === 'ETIMEDOUT') {\n    return new SMTPError('Connection timed out', options);\n  }\n  if (\n    CERTIFICATE_CODE.test(originalCode) ||\n    (code === 'ETLS' && CERTIFICATE_MESSAGE.test(error.message))\n  ) {\n    return new SMTPError(`Certificate error: ${error.message}`, options);\n  }\n  if (code === 'ETLS' || originalCode.startsWith('ERR_SSL_')) {\n    return new SMTPError(`SSL error: ${error.message}`, options);\n  }\n  return new SMTPError(stripErrorText(error.message), options);\n}\n\n/**\n * Whether the server's (plain-text) EHLO reply advertised STARTTLS. With\n * `ignoreTLS`, nodemailer keeps that reply in `_ehloLines` (it has no public\n * accessor); without it, the answer is false.\n */\nfunction advertisesStartTls(connection: SMTPConnection): boolean {\n  const lines = (connection as unknown as { _ehloLines?: unknown })._ehloLines;\n  return (\n    Array.isArray(lines) &&\n    lines.some(\n      line => typeof line === 'string' && /^STARTTLS\\b/iu.test(line.trim()),\n    )\n  );\n}\n\n/** Run one callback-style SMTPConnection step, failing on an 'error' event too. */\nfunction step<T>(\n  connection: SMTPConnection,\n  start: (done: (error: Error | null | undefined, value?: T) => void) => void,\n): Promise<T> {\n  return new Promise((resolve, reject) => {\n    const onError = (error: Error): void => reject(error);\n    connection.once('error', onError);\n    start((error, value) => {\n      connection.removeListener('error', onError);\n      if (error) {\n        reject(error);\n      } else {\n        resolve(value as T);\n      }\n    });\n  });\n}\n\n/**\n * Send an email using a SMTP relay.\n *\n * Without `requireEncryption` the connection starts in plain text and is\n * upgraded with STARTTLS when the server offers it (see `starttls` to never\n * or always upgrade). When it is not offered, credentials are refused with\n * `SMTPError` before they are sent, and a message without credentials goes\n * out unencrypted with a warning, as with mailsuite. Every\n * recipient (To, Cc and Bcc) is in the SMTP envelope; Bcc is never in the\n * headers. Connection and protocol failures raise `SMTPError`.\n */\nexport async function sendEmail(\n  host: string,\n  messageFrom: string,\n  options: SendEmailOptions = {},\n): Promise<void> {\n  const message = buildMessage(messageFrom, options);\n  const requireEncryption = options.requireEncryption ?? false;\n  // Ignored with implicit TLS, like mailsuite.\n  const starttls = requireEncryption ? null : (options.starttls ?? null);\n  const { username, password } = options;\n  const auth = username && password ? { user: username, pass: password } : null;\n  let connection: SMTPConnection | null = null;\n  try {\n    connection = new SMTPConnection({\n      host,\n      port: options.port || (requireEncryption ? SMTPS_PORT : SMTP_PORT),\n      secure: requireEncryption,\n      // starttls: false never upgrades; otherwise nodemailer upgrades when\n      // STARTTLS is advertised (a failed upgrade is an error).\n      ...(starttls === false ? { ignoreTLS: true } : {}),\n      tls: options.verify === false ? { rejectUnauthorized: false } : {},\n      logger: false,\n    });\n    // Late errors (after a step settled) must not crash the process.\n    connection.on('error', () => undefined);\n    const active = connection;\n    await step<void>(active, done => active.connect(error => done(error)));\n    if (!(requireEncryption || active.secure)) {\n      if (starttls === false) {\n        if (advertisesStartTls(active)) {\n          logger.info(\n            'SMTP server supports STARTTLS, but it is disabled ... staying in plain text',\n          );\n        }\n        if (auth !== null) {\n          logger.warning(\n            'Sending SMTP credentials unencrypted because starttls=False',\n          );\n        }\n      } else if (starttls === true) {\n        // Not upgraded without ignoreTLS: STARTTLS was not advertised.\n        throw new SMTPError(\n          'STARTTLS required but not supported by the server',\n        );\n      } else if (auth === null) {\n        logger.warning(\n          'SMTP server does not support STARTTLS. Proceeding in plain text!',\n        );\n      } else {\n        // Checked before AUTH: an attacker can strip STARTTLS from the\n        // plain-text EHLO reply (GHSA-2x4j-7g3q-wr6f).\n        throw new SMTPError(PLAINTEXT_REFUSAL);\n      }\n    }\n    if (auth !== null) {\n      await step<boolean>(active, done => active.login(auth, done));\n    }\n    const messageTo = options.messageTo ?? null;\n    if (messageTo === null) {\n      throw new TypeError('message_to cannot be None');\n    }\n    // Every recipient, deduplicated: the envelope is Bcc's only path.\n    const envelopeTo = [\n      ...new Set([\n        ...messageTo,\n        ...(options.messageCc ?? []),\n        ...(options.messageBcc ?? []),\n      ]),\n    ].map(envelopeAddress);\n    const envelope = { from: envelopeAddress(messageFrom), to: envelopeTo };\n    await step(active, done => active.send(envelope, message, done));\n  } catch (error) {\n    throw toSMTPError(error);\n  } finally {\n    connection?.quit();\n  }\n}\n","// Email parsing results as a zip file, ported from parsedmarc's\n// `email_results()` and `_build_report_email_content()`.\n\nimport { AssertionError } from 'node:assert';\n\nimport { logger, type ParsingResults } from 'tsdmarc';\n\nimport { sendEmail } from './send-email';\n\n/**\n * The zip attachment: its bytes, or a function that builds them from the\n * results. Pass the core's `getReportZip` (parsedmarc's `get_report_zip()`).\n */\nexport type ReportZip =\n  | Uint8Array\n  | ((results: ParsingResults) => Promise<Uint8Array> | Uint8Array);\n\nexport interface ReportEmailContentOptions {\n  /** Overrides the default subject (`DMARC results for YYYY-MM-DD`). */\n  subject?: string | null;\n  /** Overrides the default attachment filename; `.zip` is appended if missing. */\n  attachmentFilename?: string | null;\n  /** Overrides the default plain text body. */\n  message?: string | null;\n  /** The zip attachment, or how to build it. */\n  reportZip: ReportZip;\n}\n\nexport interface ReportEmailContent {\n  subject: string;\n  message: string;\n  attachments: [string, Uint8Array][];\n}\n\nexport interface EmailResultsOptions extends ReportEmailContentOptions {\n  mailCc?: string[] | null;\n  mailBcc?: string[] | null;\n  /** 0 (default): 465 with `requireEncryption`, else 25. */\n  port?: number;\n  /**\n   * Connect with implicit SSL/TLS from the start (usually port 465). When\n   * false, the connection starts in plain text and `starttls` decides\n   * whether it is upgraded.\n   */\n  requireEncryption?: boolean;\n  /**\n   * Whether to upgrade a plain-text (`requireEncryption: false`) connection\n   * with STARTTLS (parsedmarc 11.2.1). `null`/`undefined` (default)\n   * upgrades when the server advertises STARTTLS; when it does not,\n   * `SMTPError` is thrown before authenticating if `username` and\n   * `password` are given, and without credentials the message is sent in\n   * plain text with a warning. `true` requires the upgrade. `false` never\n   * upgrades, so any credentials and the message are sent in plain text (a\n   * warning is logged when credentials are sent). Ignored with\n   * `requireEncryption`. See `SendEmailOptions.starttls`.\n   */\n  starttls?: boolean | null;\n  /** Verify the TLS certificate. Default: true. */\n  verify?: boolean;\n  username?: string | null;\n  password?: string | null;\n}\n\nfunction pad(value: number): string {\n  return String(value).padStart(2, '0');\n}\n\n/** `datetime.now().strftime(\"%Y-%m-%d\")`: today's local date. */\nfunction localDateString(now: Date = new Date()): string {\n  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;\n}\n\n/**\n * Build the subject, plain text body and zip attachment shared by every\n * report-summary email transport (SMTP here, Microsoft Graph in\n * `@tsdmarc/msgraph`).\n */\nexport async function buildReportEmailContent(\n  results: ParsingResults,\n  options: ReportEmailContentOptions,\n): Promise<ReportEmailContent> {\n  const dateString = localDateString();\n  let filename: string;\n  if (options.attachmentFilename) {\n    filename = options.attachmentFilename;\n    if (!filename.toLowerCase().endsWith('.zip')) {\n      filename += '.zip';\n    }\n  } else {\n    filename = `DMARC-${dateString}.zip`;\n  }\n  const subject = options.subject ?? `DMARC results for ${dateString}`;\n  const message = options.message ?? `DMARC results for ${dateString}`;\n  const { reportZip } = options;\n  const zipBytes =\n    typeof reportZip === 'function' ? await reportZip(results) : reportZip;\n  return { subject, message, attachments: [[filename, zipBytes]] };\n}\n\n/**\n * Email parsing results as a zip file.\n *\n * `options.reportZip` provides the attachment: pass the core's\n * `getReportZip` (or bytes already built). parsedmarc calls\n * `get_report_zip()` itself; taking it as an argument keeps this package\n * independent of the output module.\n */\nexport async function emailResults(\n  results: ParsingResults,\n  host: string,\n  mailFrom: string,\n  mailTo: string[] | null,\n  options: EmailResultsOptions,\n): Promise<void> {\n  logger.debug('Emailing report');\n  if (!Array.isArray(mailTo)) {\n    throw new AssertionError({\n      message: 'mail_to must be a list',\n      actual: mailTo,\n      expected: 'an array',\n      operator: 'Array.isArray',\n    });\n  }\n  const { subject, message, attachments } = await buildReportEmailContent(\n    results,\n    options,\n  );\n  await sendEmail(host, mailFrom, {\n    messageTo: mailTo,\n    messageCc: options.mailCc ?? null,\n    messageBcc: options.mailBcc ?? null,\n    port: options.port ?? 0,\n    requireEncryption: options.requireEncryption ?? false,\n    verify: options.verify ?? true,\n    username: options.username ?? null,\n    password: options.password ?? null,\n    subject,\n    attachments,\n    plainMessage: message,\n    starttls: options.starttls ?? null,\n  });\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@tsdmarc/smtp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "SMTP sender for tsdmarc: email DMARC report results as a zip attachment (port of mailsuite.smtp).",
+  "license": "Apache-2.0",
+  "author": "HelixNebula (https://helixnebula.tech)",
+  "homepage": "https://github.com/helixnebulatech/tsdmarc/tree/main/packages/smtp#readme",
+  "bugs": {
+    "url": "https://github.com/helixnebulatech/tsdmarc/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "nodemailer": "^10.2.1"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@tsdmarc/tsconfig": "0.0.0",
+    "@tsdmarc/tsdown-config": "0.0.0",
+    "@types/node": "26.6.5",
+    "tsdmarc": "1.0.0",
+    "tsdown": "0.23.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "tsdmarc": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/helixnebulatech/tsdmarc.git",
+    "directory": "packages/smtp"
+  },
+  "keywords": [
+    "dmarc",
+    "tsdmarc",
+    "smtp",
+    "email",
+    "nodemailer",
+    "dmarc-reports"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "publint": "publint && attw --pack . --profile esm-only --ignore-rules cjs-resolves-to-esm",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "type-check": "tsrs --noEmit -p tsconfig.json"
+  }
 }