mailauth 4.12.1 → 4.13.0

package/docs/dkim.md

@@ -0,0 +1,202 @@
+# DKIM Verification Result Reference
+
+This document describes the result object returned by `dkimVerify()`.
+
+## Overview
+
+The `dkimVerify` function verifies all DKIM-Signature headers in an email message and returns an object containing verification results for each signature.
+
+```javascript
+const { dkimVerify } = require('mailauth/lib/dkim/verify');
+
+const result = await dkimVerify(message);
+// result.results is an array of signature verification results
+```
+
+## Top-Level Result Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `headerFrom` | `string[]` | Array of email addresses from the From header |
+| `envelopeFrom` | `string\|false` | Email address from Return-Path header or sender option |
+| `results` | `object[]` | Array of verification results for each DKIM signature |
+
+## Signature Result Object
+
+Each entry in the `results` array has the following structure:
+
+| Field | Type | Presence | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Always | SHA256 hash of signature value, or UUID if no signature |
+| `signingDomain` | `string` | Signature exists | Domain from `d=` tag |
+| `selector` | `string` | Signature exists | DKIM selector from `s=` tag |
+| `signature` | `string` | Signature exists | Base64-encoded signature value from `b=` tag |
+| `algo` | `string` | Signature exists | Signing algorithm (e.g., `"rsa-sha256"`, `"ed25519-sha256"`) |
+| `format` | `string` | Signature exists | Canonicalization format from `c=` tag (e.g., `"relaxed/relaxed"`) |
+| `bodyHash` | `string` | Signature exists | Calculated body hash (base64) |
+| `bodyHashExpecting` | `string` | Signature exists | Expected body hash from `bh=` tag |
+| `signingHeaders` | `object` | Signature exists | Signing header details (see below) |
+| `status` | `object` | Always | Verification status (see below) |
+| `signTime` | `string\|null` | Always | ISO 8601 timestamp from `t=` tag, or null |
+| `expiresAfter` | `string\|null` | Always | ISO 8601 expiration from `x=` tag, or null |
+| `signatureTimeValid` | `boolean` | Always | Whether signature is within validity window |
+| `sourceBodyLength` | `number` | Body processed | Original body length in bytes |
+| `canonBodyLength` | `number` | Body processed | Canonicalized bytes actually hashed |
+| `canonBodyLengthTotal` | `number` | Body processed | Total canonicalized body length |
+| `canonBodyLengthLimited` | `boolean` | Signature exists | Whether body length is limited by `l=` tag |
+| `canonBodyLengthLimit` | `number` | `l=` tag present | Maximum body length from `l=` tag |
+| `mimeStructureStart` | `number` | MIME detected | Position where MIME boundary structure starts |
+| `publicKey` | `string` | Key retrieved | PEM-formatted public key |
+| `modulusLength` | `number` | RSA key | RSA key length in bits |
+| `rr` | `string` | DNS lookup done | Raw DNS TXT record value |
+| `info` | `string` | Always | Formatted Authentication-Results header value |
+
+### signingHeaders Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `keys` | `string[]` | List of header field names that were signed |
+| `headers` | `string[]` | Raw header lines that were signed |
+| `canonicalizedHeader` | `string` | Base64-encoded canonicalized header data |
+
+### status Object
+
+| Field | Type | Presence | Description |
+|-------|------|----------|-------------|
+| `result` | `string` | Always | Verification result code (see below) |
+| `comment` | `string` | On error/info | Human-readable explanation |
+| `aligned` | `string\|false` | DKIM signatures | DMARC-aligned domain, or false |
+| `header` | `object` | Always | Signature header info |
+| `policy` | `object` | Policy result | Policy violation details |
+| `underSized` | `number` | Body limited | Number of unsigned bytes |
+
+#### status.header Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `i` | `string\|false` | Signing domain with @ prefix (e.g., `"@example.com"`) |
+| `s` | `string` | DKIM selector |
+| `a` | `string` | Algorithm |
+| `b` | `string` | First 8 characters of signature value |
+
+## Result Values
+
+| Result | Description |
+|--------|-------------|
+| `pass` | Signature verified successfully |
+| `fail` | Signature verification failed (bad signature) |
+| `neutral` | Signature could not be verified (missing key, expired, body hash mismatch) |
+| `policy` | Signature failed policy check (e.g., weak key) |
+| `temperror` | Temporary error (DNS failure) |
+| `none` | Message not signed |
+
+## Comment Values
+
+Common values for `status.comment`:
+
+| Comment | Description |
+|---------|-------------|
+| `"body hash did not verify"` | Calculated body hash does not match `bh=` tag |
+| `"bad signature"` | Cryptographic signature verification failed |
+| `"invalid expiration"` | Expiration timestamp is before signing timestamp |
+| `"expired"` | Signature has expired (past `x=` timestamp) |
+| `"no key"` | No DKIM key found in DNS |
+| `"unknown key version"` | Unsupported key version in DNS record |
+| `"unknown key type"` | Unsupported key type in DNS record |
+| `"invalid public key"` | Public key in DNS record is malformed |
+| `"DNS failure: {code}"` | DNS lookup failed with error code |
+| `"message not signed"` | No DKIM-Signature headers found |
+
+## Example Output
+
+### Successful Verification
+
+```json
+{
+  "headerFrom": ["sender@example.com"],
+  "envelopeFrom": "sender@example.com",
+  "results": [
+    {
+      "id": "a1b2c3d4e5f6...",
+      "signingDomain": "example.com",
+      "selector": "selector1",
+      "signature": "dGhpcyBpcyBhIHNpZ25hdHVyZQ==",
+      "algo": "rsa-sha256",
+      "format": "relaxed/relaxed",
+      "bodyHash": "YWJjZGVmZ2hpamtsbW5vcA==",
+      "bodyHashExpecting": "YWJjZGVmZ2hpamtsbW5vcA==",
+      "signingHeaders": {
+        "keys": ["from", "to", "subject", "date"],
+        "headers": ["From: sender@example.com", "..."],
+        "canonicalizedHeader": "..."
+      },
+      "status": {
+        "result": "pass",
+        "aligned": "example.com",
+        "header": {
+          "i": "@example.com",
+          "s": "selector1",
+          "a": "rsa-sha256",
+          "b": "dGhpcyBp"
+        }
+      },
+      "signTime": "2024-01-15T10:30:00.000Z",
+      "expiresAfter": null,
+      "signatureTimeValid": true,
+      "sourceBodyLength": 1024,
+      "canonBodyLength": 1020,
+      "canonBodyLengthTotal": 1020,
+      "canonBodyLengthLimited": false,
+      "publicKey": "-----BEGIN PUBLIC KEY-----\n...",
+      "modulusLength": 2048,
+      "rr": "v=DKIM1; k=rsa; p=...",
+      "info": "dkim=pass header.i=@example.com header.s=selector1 header.a=rsa-sha256 header.b=\"dGhpcyBp\""
+    }
+  ]
+}
+```
+
+### Failed Verification
+
+```json
+{
+  "headerFrom": ["sender@example.com"],
+  "envelopeFrom": "sender@example.com",
+  "results": [
+    {
+      "id": "a1b2c3d4e5f6...",
+      "signingDomain": "example.com",
+      "selector": "selector1",
+      "status": {
+        "result": "neutral",
+        "comment": "no key",
+        "header": {
+          "i": "@example.com",
+          "s": "selector1",
+          "a": "rsa-sha256",
+          "b": "dGhpcyBp"
+        }
+      },
+      "info": "dkim=neutral (no key) header.i=@example.com header.s=selector1 header.a=rsa-sha256 header.b=\"dGhpcyBp\""
+    }
+  ]
+}
+```
+
+### Unsigned Message
+
+```json
+{
+  "headerFrom": ["sender@example.com"],
+  "envelopeFrom": "sender@example.com",
+  "results": [
+    {
+      "status": {
+        "result": "none",
+        "comment": "message not signed"
+      },
+      "info": "dkim=none (message not signed)"
+    }
+  ]
+}
+```

package/docs/dmarc.md

@@ -0,0 +1,225 @@
+# DMARC Verification Result Reference
+
+This document describes the result object returned by DMARC verification.
+
+## Overview
+
+DMARC (Domain-based Message Authentication, Reporting, and Conformance) is verified during the authentication process. The DMARC result depends on both SPF and DKIM verification results.
+
+```javascript
+const { authenticate } = require('mailauth');
+
+const { dmarc } = await authenticate(message, {
+    ip: '192.0.2.1',
+    helo: 'mail.example.com',
+    sender: 'user@example.com'
+});
+```
+
+## Result Object Fields
+
+| Field | Type | Presence | Description |
+|-------|------|----------|-------------|
+| `status` | `object` | Always | Verification status object (see below) |
+| `domain` | `string` | Always | Organizational domain used for DMARC lookup |
+| `policy` | `string` | Record found | Effective policy (`"reject"`, `"quarantine"`, or `"none"`) |
+| `p` | `string` | Record found | Policy from `p=` tag |
+| `sp` | `string` | Record found | Subdomain policy from `sp=` tag (defaults to `p` value) |
+| `pct` | `number` | Record found | Percentage of messages to apply policy (0-100) |
+| `rr` | `string` | Record found | Raw DMARC DNS TXT record |
+| `alignment` | `object` | Record found | SPF and DKIM alignment details (see below) |
+| `error` | `string` | On temperror | Error message |
+| `info` | `string` | Always | Formatted Authentication-Results header value |
+
+## status Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `result` | `string` | DMARC result code (see below) |
+| `header` | `object` | Header information |
+| `comment` | `string` | Policy and ARC information |
+
+### status.header Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `from` | `string` | Organizational domain from the From header |
+| `d` | `string` | Domain where DMARC record was found |
+
+## alignment Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `spf` | `object` | SPF alignment details |
+| `dkim` | `object` | DKIM alignment details |
+
+### alignment.spf Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `result` | `string\|false` | Aligned domain if SPF passed and aligned, otherwise `false` |
+| `strict` | `boolean` | Whether strict alignment is required (`aspf=s`) |
+
+### alignment.dkim Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `result` | `string\|false` | Aligned domain if DKIM passed and aligned, otherwise `false` |
+| `strict` | `boolean` | Whether strict alignment is required (`adkim=s`) |
+| `underSized` | `number` | Number of unsigned body bytes (if `l=` tag limited body) |
+
+## Result Values
+
+| Result | Description |
+|--------|-------------|
+| `pass` | Message passed DMARC (SPF or DKIM aligned and passed) |
+| `fail` | Message failed DMARC (neither SPF nor DKIM aligned) |
+| `none` | No DMARC record found |
+| `temperror` | Temporary error during DNS lookup |
+
+## Policy Values
+
+| Policy | Description |
+|--------|-------------|
+| `none` | No specific action requested (monitor mode) |
+| `quarantine` | Suspicious messages should be quarantined |
+| `reject` | Failed messages should be rejected |
+
+## Comment Format
+
+The `status.comment` field contains policy information in the format:
+
+```
+p=POLICY sp=SUBDOMAIN_POLICY arc=ARC_RESULT
+```
+
+For example: `"p=REJECT sp=REJECT arc=pass"`
+
+## Example Output
+
+### DMARC Pass
+
+```json
+{
+  "status": {
+    "result": "pass",
+    "header": {
+      "from": "example.com",
+      "d": "example.com"
+    },
+    "comment": "p=REJECT arc=none"
+  },
+  "domain": "example.com",
+  "policy": "reject",
+  "p": "reject",
+  "sp": "reject",
+  "pct": 100,
+  "rr": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com",
+  "alignment": {
+    "spf": {
+      "result": false,
+      "strict": false
+    },
+    "dkim": {
+      "result": "example.com",
+      "strict": false
+    }
+  },
+  "info": "dmarc=pass (p=REJECT arc=none) header.from=example.com"
+}
+```
+
+### DMARC Fail
+
+```json
+{
+  "status": {
+    "result": "fail",
+    "header": {
+      "from": "example.com",
+      "d": "example.com"
+    },
+    "comment": "p=REJECT"
+  },
+  "domain": "example.com",
+  "policy": "reject",
+  "p": "reject",
+  "sp": "reject",
+  "pct": 100,
+  "rr": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com",
+  "alignment": {
+    "spf": {
+      "result": false,
+      "strict": false
+    },
+    "dkim": {
+      "result": false,
+      "strict": false
+    }
+  },
+  "info": "dmarc=fail (p=REJECT) header.from=example.com"
+}
+```
+
+### DMARC None (No Record)
+
+```json
+{
+  "status": {
+    "result": "none",
+    "header": {
+      "from": "no-dmarc.example.com"
+    }
+  },
+  "domain": "no-dmarc.example.com",
+  "info": "dmarc=none header.from=no-dmarc.example.com"
+}
+```
+
+### DMARC with Subdomain Policy
+
+```json
+{
+  "status": {
+    "result": "pass",
+    "header": {
+      "from": "example.com",
+      "d": "sub.example.com"
+    },
+    "comment": "p=NONE sp=QUARANTINE"
+  },
+  "domain": "example.com",
+  "policy": "quarantine",
+  "p": "none",
+  "sp": "quarantine",
+  "pct": 100,
+  "rr": "v=DMARC1; p=none; sp=quarantine; rua=mailto:dmarc@example.com",
+  "alignment": {
+    "spf": {
+      "result": "example.com",
+      "strict": false
+    },
+    "dkim": {
+      "result": false,
+      "strict": false
+    }
+  },
+  "info": "dmarc=pass (p=NONE sp=QUARANTINE) header.from=example.com"
+}
+```
+
+### DMARC Temperror
+
+```json
+{
+  "status": {
+    "result": "temperror",
+    "header": {
+      "from": "example.com"
+    }
+  },
+  "domain": "example.com",
+  "error": "DNS timeout",
+  "info": "dmarc=temperror header.from=example.com"
+}
+```

package/docs/mta-sts.md

@@ -0,0 +1,239 @@
+# MTA-STS Result Reference
+
+This document describes the result objects returned by MTA-STS (Mail Transfer Agent Strict Transport Security) functions.
+
+## Overview
+
+MTA-STS allows domain owners to declare that their mail servers support TLS and specify policies for message delivery. mailauth provides functions to fetch, parse, and validate MTA-STS policies.
+
+```javascript
+const { getPolicy, validateMx } = require('mailauth/lib/mta-sts');
+```
+
+## getPolicy Result
+
+The `getPolicy` function fetches and returns the MTA-STS policy for a domain.
+
+```javascript
+const { policy, status } = await getPolicy('example.com', knownPolicy);
+```
+
+### Result Object Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `policy` | `object` | The MTA-STS policy object (see below) |
+| `status` | `string` | Policy retrieval status (see below) |
+
+### Status Values
+
+| Status | Description |
+|--------|-------------|
+| `found` | New or updated policy was fetched successfully |
+| `not_found` | No MTA-STS policy exists for the domain |
+| `renewed` | Existing policy is still valid (ID unchanged, not expired) |
+| `errored` | Policy discovery failed due to an error |
+
+### Policy Object Fields
+
+| Field | Type | Presence | Description |
+|-------|------|----------|-------------|
+| `id` | `string\|false` | Always | Policy ID from DNS TXT record, or `false` if not found |
+| `version` | `string` | Policy found | Always `"STSv1"` for valid policies |
+| `mode` | `string` | Always | Policy mode (see below) |
+| `mx` | `string[]` | Mode not "none" | Array of allowed MX hostnames (may include wildcards) |
+| `maxAge` | `number` | Policy found | Policy validity period in seconds |
+| `expires` | `string` | Policy found | ISO 8601 expiration timestamp |
+| `error` | `Error` | On error | Error object if discovery failed |
+
+### Mode Values
+
+| Mode | Description |
+|------|-------------|
+| `testing` | Policy is in test mode; report violations but don't enforce |
+| `enforce` | Strictly enforce TLS and MX restrictions |
+| `none` | No policy in effect |
+
+## validateMx Result
+
+The `validateMx` function checks if an MX hostname is valid according to the MTA-STS policy.
+
+```javascript
+const result = validateMx('alt1.mx.example.com', policy);
+```
+
+### Result Object Fields
+
+| Field | Type | Presence | Description |
+|-------|------|----------|-------------|
+| `valid` | `boolean` | Always | Whether the MX hostname is allowed |
+| `mode` | `string` | Always | Policy mode (`"testing"`, `"enforce"`, or `"none"`) |
+| `match` | `string` | Valid match | The pattern that matched (exact hostname or wildcard) |
+| `testing` | `boolean` | Always | Whether policy is in testing mode |
+
+## Example Output
+
+### Policy Found
+
+```json
+{
+  "policy": {
+    "id": "20240115T120000",
+    "version": "STSv1",
+    "mode": "enforce",
+    "mx": [
+      "mx1.example.com",
+      "mx2.example.com",
+      "*.mail.example.com"
+    ],
+    "maxAge": 86400,
+    "expires": "2024-01-16T12:00:00.000Z"
+  },
+  "status": "found"
+}
+```
+
+### Policy Not Found
+
+```json
+{
+  "policy": {
+    "id": false,
+    "mode": "none"
+  },
+  "status": "not_found"
+}
+```
+
+### Policy Renewed (Cached)
+
+```json
+{
+  "policy": {
+    "id": "20240115T120000",
+    "version": "STSv1",
+    "mode": "enforce",
+    "mx": [
+      "mx1.example.com",
+      "mx2.example.com"
+    ],
+    "maxAge": 86400,
+    "expires": "2024-01-16T12:00:00.000Z"
+  },
+  "status": "renewed"
+}
+```
+
+### Policy Error
+
+```json
+{
+  "policy": {
+    "id": "20240115T120000",
+    "mode": "none",
+    "expires": "2024-01-15T13:00:00.000Z",
+    "error": {
+      "message": "Request timeout for https://mta-sts.example.com/.well-known/mta-sts.txt",
+      "code": "HTTP_SOCKET_TIMEOUT"
+    }
+  },
+  "status": "errored"
+}
+```
+
+### MX Validation - Valid Match
+
+```json
+{
+  "valid": true,
+  "mode": "enforce",
+  "match": "mx1.example.com",
+  "testing": false
+}
+```
+
+### MX Validation - Wildcard Match
+
+```json
+{
+  "valid": true,
+  "mode": "enforce",
+  "match": ".mail.example.com",
+  "testing": false
+}
+```
+
+### MX Validation - Invalid
+
+```json
+{
+  "valid": false,
+  "mode": "enforce",
+  "testing": false
+}
+```
+
+### MX Validation - Testing Mode
+
+```json
+{
+  "valid": true,
+  "mode": "testing",
+  "match": "mx1.example.com",
+  "testing": true
+}
+```
+
+### MX Validation - No Policy
+
+```json
+{
+  "valid": true,
+  "mode": "none",
+  "testing": false
+}
+```
+
+## Error Codes
+
+Errors that may appear in `policy.error`:
+
+| Code | Description |
+|------|-------------|
+| `multi_sts_records` | Multiple TXT records found for `_mta-sts.{domain}` |
+| `invalid_sts_version` | Policy file has invalid or missing version field |
+| `invalid_sts_mode` | Policy file has invalid mode value |
+| `invalid_sts_max_age` | Policy file has invalid max_age value |
+| `invalid_sts_mx` | Policy file missing mx field in enforce/testing mode |
+| `HTTP_SOCKET_TIMEOUT` | HTTP request timed out |
+| `http_status_{code}` | HTTP request returned non-2xx status |
+| `ENOTFOUND` | DNS lookup failed (domain not found) |
+| `ENODATA` | DNS lookup returned no data |
+
+## Usage Example
+
+```javascript
+const { getPolicy, validateMx } = require('mailauth/lib/mta-sts');
+
+// Fetch policy
+const { policy, status } = await getPolicy('gmail.com');
+
+console.log(`Policy status: ${status}`);
+console.log(`Policy mode: ${policy.mode}`);
+
+if (policy.mode !== 'none') {
+    // Validate MX hostname
+    const mx = 'alt1.gmail-smtp-in.l.google.com';
+    const validation = validateMx(mx, policy);
+
+    if (!validation.valid && !validation.testing) {
+        console.error(`MX ${mx} is not allowed by MTA-STS policy`);
+        // Reject delivery attempt
+    } else if (!validation.valid && validation.testing) {
+        console.warn(`MX ${mx} violates MTA-STS policy (testing mode)`);
+        // Report violation but continue
+    } else {
+        console.log(`MX ${mx} is allowed`);
+    }
+}
+```