@bumail/mta-sts 0.0.0-stage → 0.1.0

package/dist/policy.d.ts

@@ -0,0 +1,25 @@
+import { type ParseResult } from './errors';
+/** The policy file of RFC 8461 §3.2. */
+export interface StsPolicy {
+    readonly version: 'STSv1';
+    readonly mode: 'enforce' | 'testing' | 'none';
+    /** MX patterns, lowercase: a host name or `*.` and a suffix (§4.1). Empty only for `none`. */
+    readonly mx: readonly string[];
+    /** Seconds the policy may be cached, 0 to {@link MAX_AGE_LIMIT}. */
+    readonly maxAge: number;
+}
+export type PolicyErrorCode = 'MISSING_VERSION' | 'BAD_VERSION' | 'MISSING_MODE' | 'BAD_MODE' | 'MISSING_MX' | 'BAD_MX' | 'MISSING_MAX_AGE' | 'BAD_MAX_AGE' | 'BAD_LINE';
+/** The largest `max_age` §3.2 allows: 31 557 600 seconds, about a year. */
+export declare const MAX_AGE_LIMIT = 31557600;
+/**
+ * Read a policy file: `key: value` lines, CRLF or LF, blank lines and
+ * unknown keys ignored, `mx` given once per pattern. Keys are lowercase; a
+ * key given twice keeps its first value, except `mx`. `mx` is required
+ * unless the mode is `none`.
+ */
+export declare function parsePolicy(text: string): ParseResult<StsPolicy, PolicyErrorCode>;
+/** The policy file, the inverse of {@link parsePolicy}: CRLF lines, the last ended too. */
+export declare function formatPolicy(policy: Omit<StsPolicy, 'version'> & {
+    readonly version?: 'STSv1';
+}): string;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAE/D,wCAAwC;AACxC,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAC9C,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,eAAe,GACxB,iBAAiB,GACjB,aAAa,GACb,cAAc,GACd,UAAU,GACV,YAAY,GACZ,QAAQ,GACR,iBAAiB,GACjB,aAAa,GACb,UAAU,CAAC;AAEd,2EAA2E;AAC3E,eAAO,MAAM,aAAa,WAAa,CAAC;AAUxC;;;;;GAKG;AACH,wBAAgB,WAAW,CAC1B,IAAI,EAAE,MAAM,GACV,WAAW,CAAC,SAAS,EAAE,eAAe,CAAC,CA2DzC;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAC3B,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACjE,MAAM,CAiCR"}

package/dist/report.d.ts

@@ -0,0 +1,59 @@
+import { type TlsResultType } from './tls-result';
+/** One failure line of a policy's `failure-details` (RFC 8460 §4.4). */
+export interface TlsFailureDetail {
+    readonly resultType: TlsResultType;
+    readonly sendingMtaIp?: string;
+    readonly receivingMxHostname?: string;
+    readonly receivingMxHelo?: string;
+    readonly receivingIp?: string;
+    readonly failedSessionCount: number;
+    readonly additionalInformation?: string;
+    readonly failureReasonCode?: string;
+}
+export interface TlsReportPolicy {
+    readonly policy: {
+        readonly type: 'sts' | 'no-policy-found';
+        /** The policy file as fetched, text or its lines; for `sts`. */
+        readonly string?: string | readonly string[];
+        readonly domain: string;
+        readonly mxHost?: readonly string[];
+    };
+    readonly summary: {
+        readonly success: number;
+        readonly failure: number;
+    };
+    readonly failureDetails?: readonly TlsFailureDetail[];
+}
+export interface TlsReportInput {
+    readonly organizationName: string;
+    readonly contactInfo: string;
+    readonly reportId: string;
+    /** A `Date`, or text such as `2026-11-02T00:00:00Z`. */
+    readonly dateRange: {
+        readonly start: Date | string;
+        readonly end: Date | string;
+    };
+    readonly policies: readonly TlsReportPolicy[];
+}
+/** The report as RFC 8460 §4 writes it, with its hyphenated keys. */
+export interface TlsReport {
+    readonly 'organization-name': string;
+    readonly 'date-range': {
+        readonly 'start-datetime': string;
+        readonly 'end-datetime': string;
+    };
+    readonly 'contact-info': string;
+    readonly 'report-id': string;
+    readonly policies: readonly Record<string, unknown>[];
+}
+/**
+ * The TLS report of RFC 8460 §4 for the given counts, validated: strings
+ * non-empty, counts whole numbers, dates as `YYYY-MM-DDTHH:MM:SSZ`, result
+ * types from §4.3, an `sts` policy with its policy text. Throws
+ * `MtaStsError` `INVALID_REPORT`, naming the field. Compressing it (§5.1)
+ * and sending it are the caller's.
+ */
+export declare function tlsReport(input: TlsReportInput): TlsReport;
+/** The report as JSON text (RFC 8460 §4: a JSON object, UTF-8). */
+export declare function serialiseTlsReport(report: TlsReport): string;
+//# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEpE,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,MAAM,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,iBAAiB,CAAC;QACzC,gEAAgE;QAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;QAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACzE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACtD;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE;QACnB,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,CAAC;QAC9B,QAAQ,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC9C;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE;QACtB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KAChC,CAAC;IACF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CACtD;AAkHD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAc1D;AAED,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAE5D"}

package/dist/sts-record.d.ts

@@ -0,0 +1,21 @@
+import { type ParseResult } from './errors';
+import { type TxtAnswer } from './txt';
+/**
+ * The `_mta-sts.<domain>` TXT record (RFC 8461 §3.1): `v=STSv1; id=<id>`.
+ */
+export interface StsRecord {
+    /** 1 to 32 letters and digits; a change tells senders to refetch the policy. */
+    readonly id: string;
+}
+export type StsRecordErrorCode = 'NO_RECORD' | 'MULTIPLE_RECORDS' | 'MISSING_ID' | 'BAD_ID';
+/**
+ * Read the `_mta-sts` TXT answer. Pass the strings of every TXT record of
+ * the name (one record's chunks joined), as strings or as `@bumail/dns`
+ * `TxtRecord`s; the ones that are not `v=STSv1`
+ * are ignored, and more than one that is makes the answer invalid (§3.1).
+ * Fields after the id are extensions and ignored.
+ */
+export declare function parseStsRecord(txt: TxtAnswer): ParseResult<StsRecord, StsRecordErrorCode>;
+/** The record's text, the inverse of {@link parseStsRecord}: `v=STSv1; id=<id>`. */
+export declare function formatStsRecord(record: StsRecord): string;
+//# sourceMappingURL=sts-record.d.ts.map

package/dist/sts-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sts-record.d.ts","sourceRoot":"","sources":["../src/sts-record.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,KAAK,SAAS,EAAS,MAAM,OAAO,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,kBAAkB,GAC3B,WAAW,GACX,kBAAkB,GAClB,YAAY,GACZ,QAAQ,CAAC;AAeZ;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,SAAS,GACZ,WAAW,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAwB5C;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAQzD"}

package/dist/tls-result.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The result types of RFC 8460 §4.3. `@bumail/smtp` names the same strings
+ * (`src/errors.ts`); this package peers on nothing, so it declares them
+ * itself. A deliberate duplication, see AGENTS.md: change both together;
+ * `tls-result.spec.ts` fails `typecheck` when they differ.
+ */
+export declare const TLS_RESULT_TYPES: readonly ["starttls-not-supported", "certificate-host-mismatch", "certificate-expired", "certificate-not-trusted", "validation-failure", "tlsa-invalid", "dnssec-invalid", "dane-required", "sts-policy-fetch-error", "sts-policy-invalid", "sts-webpki-invalid"];
+export type TlsResultType = (typeof TLS_RESULT_TYPES)[number];
+//# sourceMappingURL=tls-result.d.ts.map

package/dist/tls-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tls-result.d.ts","sourceRoot":"","sources":["../src/tls-result.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,mQAYnB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/tls-rpt-record.d.ts

@@ -0,0 +1,24 @@
+import { type ParseResult } from './errors';
+import { type TxtAnswer } from './txt';
+/**
+ * The `_smtp._tls.<domain>` TXT record (RFC 8460 §3): where to send TLS
+ * reports, `v=TLSRPTv1; rua=mailto:tls@example.com,https://example.com/r`.
+ */
+export interface TlsRptRecord {
+    /** One or more `mailto:` or `https:` URIs, in the record's order. */
+    readonly rua: readonly string[];
+}
+export type TlsRptRecordErrorCode = 'NO_RECORD' | 'MULTIPLE_RECORDS' | 'MISSING_RUA' | 'BAD_RUA';
+/**
+ * Read the `_smtp._tls` TXT answer, like {@link parseStsRecord}: strings
+ * that are not `v=TLSRPTv1` are ignored, more than one that is makes it
+ * invalid, unknown fields are ignored. `rua` is a comma-separated list;
+ * the entries that are not a `mailto:` address or an `https:` URL (another
+ * scheme a sender may support, or a malformed one) are left out, and the
+ * record is `BAD_RUA` only when none is left (§3). Pass the TXT strings or
+ * `@bumail/dns` `TxtRecord`s.
+ */
+export declare function parseTlsRptRecord(txt: TxtAnswer): ParseResult<TlsRptRecord, TlsRptRecordErrorCode>;
+/** The record's text, the inverse of {@link parseTlsRptRecord}. */
+export declare function formatTlsRptRecord(record: TlsRptRecord): string;
+//# sourceMappingURL=tls-rpt-record.d.ts.map

package/dist/tls-rpt-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tls-rpt-record.d.ts","sourceRoot":"","sources":["../src/tls-rpt-record.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,KAAK,SAAS,EAAS,MAAM,OAAO,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,MAAM,qBAAqB,GAC9B,WAAW,GACX,kBAAkB,GAClB,aAAa,GACb,SAAS,CAAC;AAiCb;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,SAAS,GACZ,WAAW,CAAC,YAAY,EAAE,qBAAqB,CAAC,CA8BlD;AAED,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAiB/D"}

package/dist/txt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The TXT answer of a name: its strings, or records with a `text` (what
+ * `@bumail/dns`'s `Resolver.txt` answers, matched by shape).
+ */
+export type TxtAnswer = string | readonly (string | {
+    readonly text: string;
+})[];
+export declare function texts(answer: TxtAnswer): string[];
+//# sourceMappingURL=txt.d.ts.map

package/dist/txt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"txt.d.ts","sourceRoot":"","sources":["../src/txt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,SAAS,GAClB,MAAM,GACN,SAAS,CAAC,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,CAAC;AAEnD,wBAAgB,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,EAAE,CAGjD"}

package/docs/README.md

@@ -0,0 +1,10 @@
+# @bumail/mta-sts documentation
+
+The [package README](../README.md) is the short version. This folder is the
+long one.
+
+| Page | Read it when |
+| --- | --- |
+| [Guide](guide.md) | publishing your own policy, reading another domain's, fetching it safely, or building a TLS report |
+| [Troubleshooting](troubleshooting.md) | a parser, `fetchPolicy`, a formatter or `tlsReport` refused something |
+| [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |

package/docs/guide.md

@@ -0,0 +1,130 @@
+# Guide
+
+- [Publishing your policy](#publishing-your-policy)
+- [Reading another domain's policy](#reading-another-domains-policy)
+- [The fetch rules](#the-fetch-rules)
+- [TLS-RPT: asking for reports](#tls-rpt-asking-for-reports)
+- [Building a TLS report](#building-a-tls-report)
+- [Specs: no network](#specs-no-network)
+
+## Publishing your policy
+
+MTA-STS is three things: a TXT record `_mta-sts.<domain>`, a policy file
+served at `https://mta-sts.<domain>/.well-known/mta-sts.txt`, and a
+certificate for the `mta-sts.<domain>` host. This package writes the first
+two.
+
+```ts
+import { formatPolicy, formatStsRecord } from '@bumail/mta-sts';
+
+// Start in testing: senders deliver anyway and report failures.
+const file = formatPolicy({ mode: 'testing', mx: ['mail.example.com'], maxAge: 86400 });
+// Serve `file` as text/plain at the well-known URL.
+
+// Change `id` every time the file changes, or senders keep the cached one.
+const txt = formatStsRecord({ id: String(Date.now()) });
+// Publish `txt` as the TXT record of _mta-sts.example.com
+```
+
+`mx` lists the hosts your MX records name. A pattern is a host name or
+`*.` and a suffix. Move to `enforce` once the reports are clean, and to
+`none` with a short `max_age` to retire the policy (`mx` may then be empty).
+
+## Reading another domain's policy
+
+Look the TXT up with a `@bumail/dns` resolver, then fetch:
+
+```ts
+import { nodeResolver } from '@bumail/dns';
+import { fetchPolicy, parseStsRecord } from '@bumail/mta-sts';
+
+const resolver = nodeResolver(); // txt(name) -> [{ text, ttl }, …], or throws a DnsError
+
+const answer = await resolver.txt('_mta-sts.gmail.com');
+const record = parseStsRecord(answer); // the TxtRecords go in as they are
+if (record.ok) {
+	const result = await fetchPolicy('gmail.com');
+	// Cache result.policy for policy.maxAge seconds, or until record.value.id changes.
+}
+```
+
+`parseStsRecord` takes every TXT string of the name: strings that are not
+`v=STSv1` are ignored, and two that are make the answer invalid (RFC 8461
+§3.1), because a domain must not have two policies.
+
+## The fetch rules
+
+`fetchPolicy` follows RFC 8461 §3.3 and refuses everything else:
+
+| Rule | Error code | Result type reported |
+| --- | --- | --- |
+| a valid certificate for `mta-sts.<domain>` | `CERTIFICATE` | `sts-webpki-invalid` |
+| no redirect, any 3xx is an error | `REDIRECT` | `sts-policy-fetch-error` |
+| status 200 | `STATUS` | `sts-policy-fetch-error` |
+| `Content-Type: text/plain` (a charset is fine) | `CONTENT_TYPE` | `sts-policy-fetch-error` |
+| at most 64 KiB, counted while reading | `TOO_LARGE` | `sts-policy-fetch-error` |
+| the whole fetch within `timeoutMs` (60 s by default) | `TIMEOUT` | `sts-policy-fetch-error` |
+| any other network failure, a body that fails mid-read, or the caller's `signal` aborting | `NETWORK` | `sts-policy-fetch-error` |
+| UTF-8 text | `NOT_UTF8` | `sts-policy-invalid` |
+| a policy `parsePolicy` accepts | `INVALID_POLICY` | `sts-policy-invalid` |
+
+`CONTENT_TYPE` and `TOO_LARGE` are reported as `sts-policy-fetch-error`, not
+`sts-policy-invalid`: RFC 8460 §4.3.2 uses `sts-policy-invalid` for a policy
+that was had and could not be read as one, and in both cases the fetch
+(§3.3 of RFC 8461) failed before there was a policy to read. A body that
+arrived, in the right type and size, and does not parse is the invalid one.
+
+`fetchPolicy` always answers a result: a network failure, a misbehaving
+`fetch`, a stream that errors, a non-string domain. Only an option out of
+range throws (`MtaStsError` `INVALID_OPTION`, before any fetch), because it
+is the caller's bug, not the network's. Pass `signal` to give up early; an
+already-aborted signal answers at once without fetching.
+
+The RFC fixes no timeout; 60 seconds is generous for a file of a few lines.
+A queue that delivers on the spot will pass a shorter `timeoutMs` (1 to
+2147483647: a timer takes no longer delay).
+`maxAgeCap` lowers the `max_age` of the policy you get back, so a peer
+cannot make you cache for a year.
+
+A certificate refusal is told from other failures by the error's `code`
+(`CERT_HAS_EXPIRED`, `DEPTH_ZERO_SELF_SIGNED_CERT`,
+`ERR_TLS_CERT_ALTNAME_INVALID`, …) or a message naming the certificate, on
+the error or its `cause`. A runtime whose `fetch` reports it otherwise is
+seen as a `NETWORK` failure; give a `fetch` that does.
+
+## TLS-RPT: asking for reports
+
+```ts
+import { formatTlsRptRecord } from '@bumail/mta-sts';
+
+formatTlsRptRecord({ rua: ['mailto:tls-reports@example.com'] });
+// Publish as the TXT record of _smtp._tls.example.com
+```
+
+`parseTlsRptRecord` reads a peer's, to know where to send yours. Each `rua`
+is `mailto:` or `https:`.
+
+## Building a TLS report
+
+`tlsReport` checks the counts and names, and returns the object of RFC 8460
+§4 with its hyphenated keys (`organization-name`, `policy-type`,
+`total-successful-session-count`, …). `policy.string` is the policy file as
+fetched (`result.text`), written as the array of its lines. A `no-policy-found`
+entry carries no policy text. Compress the JSON with gzip and send it to the
+`rua` (RFC 8460 §5); this package does neither. `@bumail/server` does both,
+when `[mtaSts] reports = true` (counting the queue's `tls` events per policy
+domain and day, then mailing or POSTing the report).
+
+## Specs: no network
+
+`fetchPolicy` calls the `fetch` you give it, with the URL and
+`{ redirect: 'manual', signal, headers }`:
+
+```ts
+const result = await fetchPolicy('example.com', {
+	fetch: async () =>
+		new Response('version: STSv1\nmode: none\nmax_age: 0\n', {
+			headers: { 'content-type': 'text/plain' },
+		}),
+});
+```

package/docs/roadmap.md

@@ -0,0 +1,27 @@
+# Roadmap
+
+What `@bumail/mta-sts` gives a mail server, and what is coming. This page is
+a direction, not a commitment: the version something shipped in is the only
+number on it.
+
+## Now
+
+## Next
+
+## Later
+
+- **Receiving reports**: reading the gzip JSON a peer sends to your `rua`.
+- **A `tlsa` policy type** in reports, with DANE.
+
+## Not planned
+
+- **DNS lookups, HTTP serving and caching.** The package is the format and
+  the fetch; the resolver is `@bumail/dns`, the cache is the caller's.
+
+## Shipped
+
+- **Used by the queue, the server and `bumail dns`**: the queue enforces a
+  recipient domain's policy with `fetchPolicy`, `bumail dns` prints what
+  `formatStsRecord` and `formatTlsRptRecord` write, and `@bumail/server`
+  builds its daily TLS reports with `tlsReport` and sends them (opt-in).
+  This package stays the format and the fetch.

package/docs/troubleshooting.md

@@ -0,0 +1,199 @@
+# Troubleshooting
+
+Each entry is headed by the message you will see; the parts shown as … vary.
+A parser or `fetchPolicy` answers `{ ok: false, error: { code, message } }`
+(`code` is the group below); a formatter, `tlsReport` or a bad `fetchPolicy`
+option throws `MtaStsError`, whose `code` is its group.
+
+**NO_RECORD, MULTIPLE_RECORDS**
+
+- [`No TXT record starts with v=STSv1`](#no-txt-record-starts-with-vstsv1)
+- [`No TXT record starts with v=TLSRPTv1`](#no-txt-record-starts-with-vtlsrptv1)
+- [`… TXT records start with v=STSv1; …`](#-txt-records-start-with-vstsv1-rfc-8461-31-treats-that-as-no-policy)
+- [`… TXT records start with v=TLSRPTv1; …`](#-txt-records-start-with-vtlsrptv1-rfc-8460-3-treats-that-as-no-record)
+
+**MISSING_ID, BAD_ID, MISSING_RUA, BAD_RUA**
+
+- [`The record has no id field`](#the-record-has-no-id-field)
+- [`id "…" is not 1 to 32 letters and digits`](#id--is-not-1-to-32-letters-and-digits)
+- [`The record has no rua field`](#the-record-has-no-rua-field)
+- [`rua "…" holds no mailto: or https: URI`](#rua--holds-no-mailto-or-https-uri)
+
+**`MISSING_*`, `BAD_*` and `BAD_LINE` of the policy**
+
+- the `The policy has no …` and `… is not …` entries from `version` to `"…" is not a key: value line`, below
+
+**STATUS, REDIRECT, CONTENT_TYPE, TOO_LARGE, NOT_UTF8, INVALID_POLICY (fetch)**
+
+- the `The policy host …`, `The policy was served …`, `The policy is …` entries, below
+
+**TIMEOUT, NETWORK, CERTIFICATE, INVALID_DOMAIN (fetch)**
+
+- the `The policy was not had …`, `The policy could not be …`, `The policy fetch was aborted …`, `The policy host's certificate …` and `"…" is not a domain …` entries, below
+
+**INVALID_OPTION, INVALID_RECORD, INVALID_POLICY, INVALID_REPORT (thrown)**
+
+- the `fetchPolicy(): …`, `formatStsRecord(): …`, `formatTlsRptRecord(): …`, `formatPolicy(): …` and `tlsReport(): …` entries, at the end
+
+## `No TXT record starts with v=STSv1`
+
+`NO_RECORD`. The `_mta-sts` name has no TXT string beginning `v=STSv1`
+(case-sensitive). The domain has no policy. Publish `formatStsRecord({ id })`.
+
+## `No TXT record starts with v=TLSRPTv1`
+
+`NO_RECORD` of `parseTlsRptRecord`: the `_smtp._tls` name has no report
+address. Publish `formatTlsRptRecord({ rua })`.
+
+## `… TXT records start with v=STSv1; RFC 8461 §3.1 treats that as no policy`
+
+`MULTIPLE_RECORDS`. Two records on the name. Delete the old one.
+
+## `… TXT records start with v=TLSRPTv1; RFC 8460 §3 treats that as no record`
+
+`MULTIPLE_RECORDS`. Same, on `_smtp._tls`.
+
+## `The record has no id field`
+
+`MISSING_ID`. Write `v=STSv1; id=<id>`.
+
+## `id "…" is not 1 to 32 letters and digits`
+
+`BAD_ID`. Use letters and digits only, such as a date and time:
+`20260103T0900`.
+
+## `The record has no rua field`
+
+`MISSING_RUA`. Write `v=TLSRPTv1; rua=mailto:…`.
+
+## `rua "…" holds no mailto: or https: URI`
+
+`BAD_RUA`. Entries that are not `mailto:name@host` or an `https:` URL (another
+scheme, `http:`, a malformed one) are left out; the record fails only when
+none is left.
+
+## `The policy has no version line`
+
+`MISSING_VERSION`. The first line is `version: STSv1`.
+
+## `version "…" is not STSv1`
+
+`BAD_VERSION`.
+
+## `The policy has no mode line`
+
+`MISSING_MODE`.
+
+## `mode "…" is not enforce, testing or none`
+
+`BAD_MODE`.
+
+## `The policy has no max_age line`
+
+`MISSING_MAX_AGE`.
+
+## `max_age "…" is not a whole number of seconds from 0 to 31557600`
+
+`BAD_MAX_AGE`. Digits only, at most a year.
+
+## `A policy in mode … needs at least one mx line`
+
+`MISSING_MX`. Only `mode: none` may omit `mx`.
+
+## `mx "…" is not a host name or a *. wildcard`
+
+`BAD_MX`. A host name such as `mail.example.com`, or `*.example.com`.
+
+## `"…" is not a key: value line`
+
+`BAD_LINE`. A non-blank line of the policy has no colon.
+
+## `The policy host answered …, not 200`
+
+`STATUS`. The `mta-sts.<domain>` host answered 404 or another status. Serve
+the file at `/.well-known/mta-sts.txt`.
+
+## `The policy host redirected; RFC 8461 §3.3 does not follow redirects`
+
+`REDIRECT`. Serve the file from that URL itself, not through a redirect
+(including http to https or www).
+
+## `The policy was served as "…", not text/plain`
+
+`CONTENT_TYPE`. Set `Content-Type: text/plain`.
+
+## `The policy is larger than 65536 bytes`
+
+`TOO_LARGE`. A policy is a few lines; something else is being served.
+
+## `The policy is not UTF-8 text`
+
+`NOT_UTF8`. Serve the file as UTF-8.
+
+## `The policy is invalid: …`
+
+`INVALID_POLICY`. The rest is one of the policy messages above.
+
+## `The policy was not had within … ms`
+
+`TIMEOUT`. The host is slow or silent. Raise `timeoutMs` if it is only slow.
+
+## `The policy host's certificate was refused: …`
+
+`CERTIFICATE`, reported as `sts-webpki-invalid`. The certificate of
+`mta-sts.<domain>` is expired, self-signed, untrusted or for another name.
+
+## `The policy could not be fetched: …`
+
+`NETWORK`. DNS, refused connection, reset. There is no `mta-sts` host, or it
+is down.
+
+## `The policy fetch was aborted by the caller`
+
+`NETWORK`. The `signal` you passed aborted, or was already aborted when
+`fetchPolicy` was called (then nothing was fetched). Not a fault of the host.
+
+## `The policy could not be read: …`
+
+`NETWORK`. The body's stream failed while it was read (a reset, a closed
+connection). Try again later.
+
+## `"…" is not a domain to fetch a policy for`
+
+`INVALID_DOMAIN`. Pass a plain domain name, no scheme, path or port.
+
+## `fetchPolicy(): timeoutMs must be a number of milliseconds from 1 to 2147483647`
+
+`INVALID_OPTION`, thrown before any fetch. Pass a number from 1 to 2147483647
+(about 24 days: a timer takes no longer delay), or leave it out for 60
+seconds.
+
+## `fetchPolicy(): maxAgeCap must be a whole number of seconds from 0 to 31557600`
+
+`INVALID_OPTION`, thrown before any fetch.
+
+## `formatStsRecord(): id must be 1 to 32 letters and digits`
+
+`INVALID_RECORD`.
+
+## `formatTlsRptRecord(): rua must hold at least one URI`
+
+`INVALID_RECORD`.
+
+## `formatTlsRptRecord(): rua "…" is not a mailto: or https: URI without a raw ! or , (write them %21 and %2C)`
+
+`INVALID_RECORD`. RFC 8460 §3 reserves `!` and `,` in a `rua` URI; encode them
+as `%21` and `%2C`.
+
+## `formatPolicy(): …`
+
+`INVALID_POLICY`. The rest names the field: `mode must be enforce, testing or
+none`, `maxAge must be a whole number of seconds from 0 to 31557600`,
+`mx "…" is not a host name or a *. wildcard`, `mode … needs at least one mx`.
+
+## `tlsReport(): …`
+
+`INVALID_REPORT`. The rest names the field, such as `policies[0].summary.success
+must be a whole number, 0 or more`, `dateRange.start must be a Date or
+YYYY-MM-DDTHH:MM:SSZ`, `policies must hold at least one policy`,
+`policies[0].policy.string is required for an sts policy`.

package/package.json

@@ -1,6 +1,55 @@
 {
-  "name": "@bumail/mta-sts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@bumail/mta-sts",
+	"version": "0.1.0",
+	"description": "MTA-STS (RFC 8461) and SMTP TLS reporting (RFC 8460): the _mta-sts and _smtp._tls TXT records, the policy file, a bounded policy fetch on an injected fetch, and the TLS report JSON",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"docs",
+		"README.md",
+		"package.json",
+		"LICENSE"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/bumail.git",
+		"directory": "packages/mta-sts"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun run ../../build.ts",
+		"test": "bun test src",
+		"typecheck": "tsc --noEmit"
+	},
+	"bumail": {
+		"entrypoints": [
+			"src/index.ts"
+		]
+	},
+	"devDependencies": {
+		"@bumail/smtp": "^0.13.0",
+		"@types/bun": "^1.4.2"
+	},
+	"peerDependencies": {
+		"typescript": "^6.0.3 || ^7.0.0"
+	},
+	"peerDependenciesMeta": {
+		"typescript": {
+			"optional": true
+		}
+	}
+}