mymx 0.3.5 → 0.3.7

package/dist/contract.d.ts

@@ -1,4 +1,4 @@
-import { EmailAddress, EmailReceivedEvent, ParsedDataComplete, ParsedDataFailed, ParsedError, RawContentDownloadOnly, RawContentInline, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookAttachment } from "./types-DJTmrgCz.js";
+import { EmailAddress, EmailReceivedEvent, ParsedDataComplete, ParsedDataFailed, ParsedError, RawContentDownloadOnly, RawContentInline, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookAttachment } from "./types-C8JlcpcT.js";
 import { SignResult, signWebhookPayload$1 as signWebhookPayload } from "./signing-Ecohrukk.js";
 
 //#region src/contract.d.ts

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { EmailAddress, EmailReceivedEvent, KnownWebhookEvent, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, RawContent, RawContentDownloadOnly, RawContentInline, UnknownEvent, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookAttachment, WebhookEvent } from "./types-DJTmrgCz.js";
+import { AuthConfidence, AuthVerdict, DkimSignature, DkimSignatureResult, DmarcPolicy, DmarcResult, EmailAddress, EmailAuth, EmailReceivedEvent, KnownWebhookEvent, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, RawContent, RawContentDownloadOnly, RawContentInline, SpfResult, UnknownEvent, ValidateEmailAuthResult, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookAttachment, WebhookEvent } from "./types-C8JlcpcT.js";
 import { MYMX_CONFIRMED_HEADER$1 as MYMX_CONFIRMED_HEADER, MYMX_SIGNATURE_HEADER$1 as MYMX_SIGNATURE_HEADER, VerifyOptions, verifyWebhookSignature$1 as verifyWebhookSignature } from "./signing-Ecohrukk.js";
 import { MyMXWebhookError$1 as MyMXWebhookError, PAYLOAD_ERRORS$1 as PAYLOAD_ERRORS, RAW_EMAIL_ERRORS$1 as RAW_EMAIL_ERRORS, RawEmailDecodeError$1 as RawEmailDecodeError, RawEmailDecodeErrorCode, VERIFICATION_ERRORS$1 as VERIFICATION_ERRORS, WebhookErrorCode, WebhookPayloadError$1 as WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError$1 as WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError$1 as WebhookVerificationError, WebhookVerificationErrorCode } from "./errors-CSPHzZB_.js";
 
@@ -171,6 +171,10 @@ declare const emailReceivedEventJsonSchema: {
               readonly additionalProperties: false;
               readonly description: "Email analysis and classification results. May be absent if analysis was not performed.";
             };
+            readonly auth: {
+              readonly $ref: "#/definitions/EmailAuth";
+              readonly description: "Email authentication results (SPF, DKIM, DMARC). May be absent if authentication was not performed.";
+            };
           };
           readonly required: ["id", "received_at", "smtp", "headers", "content", "parsed"];
           readonly additionalProperties: false;
@@ -483,10 +487,170 @@ declare const emailReceivedEventJsonSchema: {
       readonly additionalProperties: false;
       readonly description: "Error details when email parsing fails.";
     };
+    readonly EmailAuth: {
+      readonly type: "object";
+      readonly properties: {
+        readonly spf: {
+          readonly $ref: "#/definitions/SpfResult";
+          readonly description: "SPF verification result.\n\nSPF checks if the sending IP is authorized by the envelope sender's domain. \"pass\" means the IP is authorized; \"fail\" means it's explicitly not allowed.";
+        };
+        readonly dmarc: {
+          readonly $ref: "#/definitions/DmarcResult";
+          readonly description: "DMARC verification result.\n\nDMARC passes if either SPF or DKIM passes AND aligns with the From: domain. \"pass\" means the email is authenticated according to the sender's policy.";
+        };
+        readonly dmarcPolicy: {
+          readonly $ref: "#/definitions/DmarcPolicy";
+          readonly description: "DMARC policy from the sender's DNS record.\n\n- `reject`: Domain wants receivers to reject failing emails\n- `quarantine`: Domain wants failing emails marked as suspicious\n- `none`: Domain is monitoring only (no action requested)\n- `null`: No DMARC record found for this domain";
+        };
+        readonly dmarcFromDomain: {
+          readonly type: ["string", "null"];
+          readonly description: "The organizational domain used for DMARC lookups.\n\nFor example, if the From: address is `user@mail.example.com`, the DMARC lookup checks `_dmarc.mail.example.com`, then falls back to `_dmarc.example.com`. This field shows which domain's policy was used.";
+        };
+        readonly dmarcSpfAligned: {
+          readonly type: "boolean";
+          readonly description: "Whether SPF aligned with the From: domain for DMARC purposes.\n\nTrue if the envelope sender domain matches the From: domain (per alignment mode).";
+        };
+        readonly dmarcDkimAligned: {
+          readonly type: "boolean";
+          readonly description: "Whether DKIM aligned with the From: domain for DMARC purposes.\n\nTrue if at least one DKIM signature's domain matches the From: domain.";
+        };
+        readonly dmarcSpfStrict: {
+          readonly type: ["boolean", "null"];
+          readonly description: "Whether DMARC SPF alignment mode is strict.\n\n- `true`: Strict alignment required (exact domain match)\n- `false`: Relaxed alignment allowed (organizational domain match)\n- `null`: No DMARC record found";
+        };
+        readonly dmarcDkimStrict: {
+          readonly type: ["boolean", "null"];
+          readonly description: "Whether DMARC DKIM alignment mode is strict.\n\n- `true`: Strict alignment required (exact domain match)\n- `false`: Relaxed alignment allowed (organizational domain match)\n- `null`: No DMARC record found";
+        };
+        readonly dkimSignatures: {
+          readonly type: "array";
+          readonly items: {
+            readonly $ref: "#/definitions/DkimSignature";
+          };
+          readonly description: "All DKIM signatures found in the email with their verification results.\n\nMay be empty if no DKIM signatures were present.";
+        };
+      };
+      readonly required: ["spf", "dmarc", "dmarcPolicy", "dmarcFromDomain", "dmarcSpfAligned", "dmarcDkimAligned", "dmarcSpfStrict", "dmarcDkimStrict", "dkimSignatures"];
+      readonly additionalProperties: false;
+      readonly description: "Email authentication results for SPF, DKIM, and DMARC.\n\nUse `validateEmailAuth()` to compute a verdict based on these results.";
+    };
+    readonly SpfResult: {
+      readonly type: "string";
+      readonly enum: ["pass", "fail", "softfail", "neutral", "none", "temperror", "permerror"];
+      readonly description: "SPF verification result.";
+    };
+    readonly DmarcResult: {
+      readonly type: "string";
+      readonly enum: ["pass", "fail", "none", "temperror", "permerror"];
+      readonly description: "DMARC verification result.";
+    };
+    readonly DmarcPolicy: {
+      readonly type: ["string", "null"];
+      readonly enum: ["reject", "quarantine", "none", null];
+      readonly description: "DMARC policy action specified in the domain's DMARC record.\n\n- `reject`: The domain owner requests that receivers reject failing emails\n- `quarantine`: The domain owner requests that failing emails be treated as suspicious\n- `none`: The domain owner is only monitoring (no action requested)\n- `null`: No DMARC policy was found for the domain";
+    };
+    readonly DkimSignature: {
+      readonly type: "object";
+      readonly properties: {
+        readonly domain: {
+          readonly type: "string";
+          readonly description: "The domain that signed this DKIM signature (d= tag). This may differ from the From: domain (that's what alignment checks).";
+        };
+        readonly selector: {
+          readonly type: "string";
+          readonly description: "The DKIM selector used to locate the public key (s= tag). Combined with the domain to form the DNS lookup: `selector._domainkey.domain`";
+        };
+        readonly result: {
+          readonly $ref: "#/definitions/DkimSignatureResult";
+          readonly description: "Verification result for this specific signature.";
+        };
+        readonly aligned: {
+          readonly type: "boolean";
+          readonly description: "Whether this signature's domain aligns with the From: domain (for DMARC).\n\nAlignment can be \"strict\" (exact match) or \"relaxed\" (organizational domain match). For example, if From: is `user@sub.example.com` and DKIM is signed by `example.com`:\n- Relaxed alignment: true (same organizational domain)\n- Strict alignment: false (not exact match)";
+        };
+        readonly keyBits: {
+          readonly type: ["number", "null"];
+          readonly description: "Key size in bits (e.g., 1024, 2048). Null if the key size couldn't be determined.";
+        };
+        readonly algo: {
+          readonly type: "string";
+          readonly description: "Signing algorithm (e.g., \"rsa-sha256\", \"ed25519-sha256\").";
+        };
+      };
+      readonly required: ["domain", "selector", "result", "aligned", "keyBits", "algo"];
+      readonly additionalProperties: false;
+      readonly description: "Details about a single DKIM signature found in the email.\n\nAn email may have multiple DKIM signatures (e.g., one from the sending domain and one from the ESP). Each signature is verified independently.";
+    };
+    readonly DkimSignatureResult: {
+      readonly type: "string";
+      readonly enum: ["pass", "fail", "temperror", "permerror"];
+      readonly description: "DKIM signature verification result for a single signature.";
+    };
   };
 }; //#endregion
-//#region src/index.d.ts
+//#region src/auth.d.ts
 
+/**
+ * Validate email authentication and compute a verdict.
+ *
+ * This function analyzes SPF, DKIM, and DMARC results to determine
+ * whether an email is likely authentic ("legit"), potentially spoofed
+ * ("suspicious"), or indeterminate ("unknown").
+ *
+ * ## Verdict Logic
+ *
+ * **Legit (high confidence):**
+ * - DMARC pass with DKIM alignment (cryptographic proof of authenticity)
+ *
+ * **Legit (medium confidence):**
+ * - DMARC pass with SPF alignment only (no DKIM)
+ *   - Note: SPF can break through forwarding, but DMARC pass is still meaningful
+ *
+ * **Suspicious (high confidence):**
+ * - DMARC fail when domain has `reject` or `quarantine` policy
+ *   - The domain owner explicitly says to distrust failing emails
+ * - SPF explicitly fails (IP not authorized by sender)
+ *
+ * **Suspicious (low confidence):**
+ * - DMARC fail when domain has `none` policy (monitoring mode)
+ * - No DMARC record but SPF/DKIM fail
+ *
+ * **Unknown:**
+ * - No DMARC record and no clear pass/fail
+ * - Temporary errors during authentication
+ * - No authentication data available
+ *
+ * @param auth - Email authentication results from the webhook
+ * @returns Verdict, confidence level, and explanatory reasons
+ *
+ * @example
+ * ```typescript
+ * const result = validateEmailAuth({
+ *   spf: 'pass',
+ *   dmarc: 'pass',
+ *   dmarcPolicy: 'reject',
+ *   dmarcFromDomain: 'example.com',
+ *   dmarcSpfAligned: true,
+ *   dmarcDkimAligned: true,
+ *   dmarcSpfStrict: false,
+ *   dmarcDkimStrict: false,
+ *   dkimSignatures: [{
+ *     domain: 'example.com',
+ *     selector: 'default',
+ *     result: 'pass',
+ *     aligned: true,
+ *     keyBits: 2048,
+ *     algo: 'rsa-sha256',
+ *   }],
+ * });
+ *
+ * // result.verdict === 'legit'
+ * // result.confidence === 'high'
+ * // result.reasons === ['DMARC passed with DKIM alignment']
+ * ```
+ */
+declare function validateEmailAuth(auth: EmailAuth): ValidateEmailAuthResult; //#endregion
+//#region src/index.d.ts
 /**
  * Parse a webhook payload, returning typed events for known types
  * and UnknownEvent for future event types.
@@ -760,5 +924,7 @@ declare function decodeRawEmail(event: EmailReceivedEvent, options?: DecodeRawEm
  * }
  * ```
  */
-declare function verifyRawEmailDownload(downloaded: Buffer | ArrayBuffer | Uint8Array, event: EmailReceivedEvent): Buffer; //#endregion
-export { DecodeRawEmailOptions, EmailAddress, EmailReceivedEvent, HandleWebhookOptions, KnownWebhookEvent, MYMX_CONFIRMED_HEADER, MYMX_SIGNATURE_HEADER, MyMXWebhookError, PAYLOAD_ERRORS, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, UnknownEvent, VERIFICATION_ERRORS, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, verifyRawEmailDownload, verifyWebhookSignature };
+declare function verifyRawEmailDownload(downloaded: Buffer | ArrayBuffer | Uint8Array, event: EmailReceivedEvent): Buffer;
+
+//#endregion
+export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimSignature, DkimSignatureResult, DmarcPolicy, DmarcResult, EmailAddress, EmailAuth, EmailReceivedEvent, HandleWebhookOptions, KnownWebhookEvent, MYMX_CONFIRMED_HEADER, MYMX_SIGNATURE_HEADER, MyMXWebhookError, PAYLOAD_ERRORS, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, SpfResult, UnknownEvent, VERIFICATION_ERRORS, ValidateEmailAuthResult, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, validateEmailAuth, verifyRawEmailDownload, verifyWebhookSignature };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { MyMXWebhookError, PAYLOAD_ERRORS, RAW_EMAIL_ERRORS, RawEmailDecodeError, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError } from "./errors-2CwICC_t.js";
 import { MYMX_CONFIRMED_HEADER, MYMX_SIGNATURE_HEADER, bufferToString, verifyWebhookSignature } from "./signing-kfnmqAcK.js";
-import { validateEmailReceivedEvent } from "./zod-Ced9Kav9.js";
+import { validateEmailReceivedEvent } from "./zod-CalKEwR4.js";
 import { createHash } from "node:crypto";
 
 //#region src/schema.generated.ts
@@ -167,6 +167,10 @@ const emailReceivedEventJsonSchema = {
 							"required": ["spamassassin"],
 							"additionalProperties": false,
 							"description": "Email analysis and classification results. May be absent if analysis was not performed."
+						},
+						"auth": {
+							"$ref": "#/definitions/EmailAuth",
+							"description": "Email authentication results (SPF, DKIM, DMARC). May be absent if authentication was not performed."
 						}
 					},
 					"required": [
@@ -508,10 +512,345 @@ const emailReceivedEventJsonSchema = {
 			],
 			"additionalProperties": false,
 			"description": "Error details when email parsing fails."
+		},
+		"EmailAuth": {
+			"type": "object",
+			"properties": {
+				"spf": {
+					"$ref": "#/definitions/SpfResult",
+					"description": "SPF verification result.\n\nSPF checks if the sending IP is authorized by the envelope sender's domain. \"pass\" means the IP is authorized; \"fail\" means it's explicitly not allowed."
+				},
+				"dmarc": {
+					"$ref": "#/definitions/DmarcResult",
+					"description": "DMARC verification result.\n\nDMARC passes if either SPF or DKIM passes AND aligns with the From: domain. \"pass\" means the email is authenticated according to the sender's policy."
+				},
+				"dmarcPolicy": {
+					"$ref": "#/definitions/DmarcPolicy",
+					"description": "DMARC policy from the sender's DNS record.\n\n- `reject`: Domain wants receivers to reject failing emails\n- `quarantine`: Domain wants failing emails marked as suspicious\n- `none`: Domain is monitoring only (no action requested)\n- `null`: No DMARC record found for this domain"
+				},
+				"dmarcFromDomain": {
+					"type": ["string", "null"],
+					"description": "The organizational domain used for DMARC lookups.\n\nFor example, if the From: address is `user@mail.example.com`, the DMARC lookup checks `_dmarc.mail.example.com`, then falls back to `_dmarc.example.com`. This field shows which domain's policy was used."
+				},
+				"dmarcSpfAligned": {
+					"type": "boolean",
+					"description": "Whether SPF aligned with the From: domain for DMARC purposes.\n\nTrue if the envelope sender domain matches the From: domain (per alignment mode)."
+				},
+				"dmarcDkimAligned": {
+					"type": "boolean",
+					"description": "Whether DKIM aligned with the From: domain for DMARC purposes.\n\nTrue if at least one DKIM signature's domain matches the From: domain."
+				},
+				"dmarcSpfStrict": {
+					"type": ["boolean", "null"],
+					"description": "Whether DMARC SPF alignment mode is strict.\n\n- `true`: Strict alignment required (exact domain match)\n- `false`: Relaxed alignment allowed (organizational domain match)\n- `null`: No DMARC record found"
+				},
+				"dmarcDkimStrict": {
+					"type": ["boolean", "null"],
+					"description": "Whether DMARC DKIM alignment mode is strict.\n\n- `true`: Strict alignment required (exact domain match)\n- `false`: Relaxed alignment allowed (organizational domain match)\n- `null`: No DMARC record found"
+				},
+				"dkimSignatures": {
+					"type": "array",
+					"items": { "$ref": "#/definitions/DkimSignature" },
+					"description": "All DKIM signatures found in the email with their verification results.\n\nMay be empty if no DKIM signatures were present."
+				}
+			},
+			"required": [
+				"spf",
+				"dmarc",
+				"dmarcPolicy",
+				"dmarcFromDomain",
+				"dmarcSpfAligned",
+				"dmarcDkimAligned",
+				"dmarcSpfStrict",
+				"dmarcDkimStrict",
+				"dkimSignatures"
+			],
+			"additionalProperties": false,
+			"description": "Email authentication results for SPF, DKIM, and DMARC.\n\nUse `validateEmailAuth()` to compute a verdict based on these results."
+		},
+		"SpfResult": {
+			"type": "string",
+			"enum": [
+				"pass",
+				"fail",
+				"softfail",
+				"neutral",
+				"none",
+				"temperror",
+				"permerror"
+			],
+			"description": "SPF verification result."
+		},
+		"DmarcResult": {
+			"type": "string",
+			"enum": [
+				"pass",
+				"fail",
+				"none",
+				"temperror",
+				"permerror"
+			],
+			"description": "DMARC verification result."
+		},
+		"DmarcPolicy": {
+			"type": ["string", "null"],
+			"enum": [
+				"reject",
+				"quarantine",
+				"none",
+				null
+			],
+			"description": "DMARC policy action specified in the domain's DMARC record.\n\n- `reject`: The domain owner requests that receivers reject failing emails\n- `quarantine`: The domain owner requests that failing emails be treated as suspicious\n- `none`: The domain owner is only monitoring (no action requested)\n- `null`: No DMARC policy was found for the domain"
+		},
+		"DkimSignature": {
+			"type": "object",
+			"properties": {
+				"domain": {
+					"type": "string",
+					"description": "The domain that signed this DKIM signature (d= tag). This may differ from the From: domain (that's what alignment checks)."
+				},
+				"selector": {
+					"type": "string",
+					"description": "The DKIM selector used to locate the public key (s= tag). Combined with the domain to form the DNS lookup: `selector._domainkey.domain`"
+				},
+				"result": {
+					"$ref": "#/definitions/DkimSignatureResult",
+					"description": "Verification result for this specific signature."
+				},
+				"aligned": {
+					"type": "boolean",
+					"description": "Whether this signature's domain aligns with the From: domain (for DMARC).\n\nAlignment can be \"strict\" (exact match) or \"relaxed\" (organizational domain match). For example, if From: is `user@sub.example.com` and DKIM is signed by `example.com`:\n- Relaxed alignment: true (same organizational domain)\n- Strict alignment: false (not exact match)"
+				},
+				"keyBits": {
+					"type": ["number", "null"],
+					"description": "Key size in bits (e.g., 1024, 2048). Null if the key size couldn't be determined."
+				},
+				"algo": {
+					"type": "string",
+					"description": "Signing algorithm (e.g., \"rsa-sha256\", \"ed25519-sha256\")."
+				}
+			},
+			"required": [
+				"domain",
+				"selector",
+				"result",
+				"aligned",
+				"keyBits",
+				"algo"
+			],
+			"additionalProperties": false,
+			"description": "Details about a single DKIM signature found in the email.\n\nAn email may have multiple DKIM signatures (e.g., one from the sending domain and one from the ESP). Each signature is verified independently."
+		},
+		"DkimSignatureResult": {
+			"type": "string",
+			"enum": [
+				"pass",
+				"fail",
+				"temperror",
+				"permerror"
+			],
+			"description": "DKIM signature verification result for a single signature."
 		}
 	}
 };
 
+//#endregion
+//#region src/auth.ts
+/**
+* Minimum DKIM key size considered acceptable.
+*
+* 1024-bit RSA keys are cryptographically weak by modern standards (NIST
+* deprecated them in 2013), but they remain extremely common in email due to:
+* - DNS TXT record size limits (255 bytes per string)
+* - Legacy infrastructure constraints
+* - Major ESPs like Amazon SES and Resend still use 1024-bit keys
+*
+* We flag keys <1024 bits as weak (these are truly dangerous), while accepting
+* ≥1024 bits to avoid false positives against legitimate senders. For maximum
+* security, domain owners should use 2048+ bit keys where possible.
+*/
+const MIN_SECURE_KEY_BITS = 1024;
+/**
+* Validate email authentication and compute a verdict.
+*
+* This function analyzes SPF, DKIM, and DMARC results to determine
+* whether an email is likely authentic ("legit"), potentially spoofed
+* ("suspicious"), or indeterminate ("unknown").
+*
+* ## Verdict Logic
+*
+* **Legit (high confidence):**
+* - DMARC pass with DKIM alignment (cryptographic proof of authenticity)
+*
+* **Legit (medium confidence):**
+* - DMARC pass with SPF alignment only (no DKIM)
+*   - Note: SPF can break through forwarding, but DMARC pass is still meaningful
+*
+* **Suspicious (high confidence):**
+* - DMARC fail when domain has `reject` or `quarantine` policy
+*   - The domain owner explicitly says to distrust failing emails
+* - SPF explicitly fails (IP not authorized by sender)
+*
+* **Suspicious (low confidence):**
+* - DMARC fail when domain has `none` policy (monitoring mode)
+* - No DMARC record but SPF/DKIM fail
+*
+* **Unknown:**
+* - No DMARC record and no clear pass/fail
+* - Temporary errors during authentication
+* - No authentication data available
+*
+* @param auth - Email authentication results from the webhook
+* @returns Verdict, confidence level, and explanatory reasons
+*
+* @example
+* ```typescript
+* const result = validateEmailAuth({
+*   spf: 'pass',
+*   dmarc: 'pass',
+*   dmarcPolicy: 'reject',
+*   dmarcFromDomain: 'example.com',
+*   dmarcSpfAligned: true,
+*   dmarcDkimAligned: true,
+*   dmarcSpfStrict: false,
+*   dmarcDkimStrict: false,
+*   dkimSignatures: [{
+*     domain: 'example.com',
+*     selector: 'default',
+*     result: 'pass',
+*     aligned: true,
+*     keyBits: 2048,
+*     algo: 'rsa-sha256',
+*   }],
+* });
+*
+* // result.verdict === 'legit'
+* // result.confidence === 'high'
+* // result.reasons === ['DMARC passed with DKIM alignment']
+* ```
+*/
+function validateEmailAuth(auth) {
+	const reasons = [];
+	let verdict;
+	let confidence;
+	if (auth.dmarc === "temperror" || auth.dmarc === "permerror") return {
+		verdict: "unknown",
+		confidence: "low",
+		reasons: [`DMARC verification error (${auth.dmarc})`, "Cannot determine email authenticity due to DNS or policy errors"]
+	};
+	if (auth.spf === "temperror" || auth.spf === "permerror") reasons.push(`SPF verification error (${auth.spf})`);
+	const weakKeySignatures = auth.dkimSignatures.filter((sig) => sig.keyBits !== null && sig.keyBits < MIN_SECURE_KEY_BITS);
+	if (weakKeySignatures.length > 0) for (const sig of weakKeySignatures) reasons.push(`Weak DKIM key (${sig.keyBits} bits) for ${sig.domain} - minimum ${MIN_SECURE_KEY_BITS} bits recommended`);
+	if (auth.dmarc === "pass") {
+		const alignedSigs = auth.dkimSignatures.filter((sig) => sig.result === "pass" && sig.aligned);
+		if (auth.dmarcDkimAligned && alignedSigs.length > 0) {
+			const domains = alignedSigs.map((sig) => sig.domain).join(", ");
+			reasons.unshift(`DMARC passed with DKIM alignment (${domains})`);
+			verdict = "legit";
+			confidence = weakKeySignatures.length > 0 ? "medium" : "high";
+			return {
+				verdict,
+				confidence,
+				reasons
+			};
+		}
+		if (auth.dmarcSpfAligned && auth.spf === "pass") {
+			reasons.unshift("DMARC passed with SPF alignment");
+			reasons.push("No aligned DKIM signature (SPF can break through forwarding)");
+			return {
+				verdict: "legit",
+				confidence: "medium",
+				reasons
+			};
+		}
+		reasons.unshift("DMARC passed");
+		return {
+			verdict: "legit",
+			confidence: "medium",
+			reasons
+		};
+	}
+	if (auth.dmarc === "fail") {
+		if (auth.dmarcPolicy === "reject") {
+			reasons.unshift("DMARC failed and domain has reject policy");
+			reasons.push("The sender's domain explicitly rejects emails that fail authentication");
+			return {
+				verdict: "suspicious",
+				confidence: "high",
+				reasons
+			};
+		}
+		if (auth.dmarcPolicy === "quarantine") {
+			reasons.unshift("DMARC failed and domain has quarantine policy");
+			reasons.push("The sender's domain marks failing emails as suspicious");
+			return {
+				verdict: "suspicious",
+				confidence: "high",
+				reasons
+			};
+		}
+		reasons.unshift("DMARC failed (domain is in monitoring mode)");
+		if (auth.spf === "fail") {
+			reasons.push("SPF failed - sending IP not authorized");
+			return {
+				verdict: "suspicious",
+				confidence: "medium",
+				reasons
+			};
+		}
+		return {
+			verdict: "suspicious",
+			confidence: "low",
+			reasons
+		};
+	}
+	if (auth.dmarc === "none") {
+		if (auth.spf === "fail") {
+			reasons.push("No DMARC record for sender domain");
+			reasons.push("SPF failed - sending IP not authorized");
+			return {
+				verdict: "suspicious",
+				confidence: "medium",
+				reasons
+			};
+		}
+		const passingDkim = auth.dkimSignatures.filter((sig) => sig.result === "pass");
+		if (passingDkim.length > 0) {
+			const domains = passingDkim.map((sig) => sig.domain).join(", ");
+			reasons.push("No DMARC record for sender domain");
+			reasons.push(`DKIM verified for: ${domains}`);
+			if (auth.spf === "pass") reasons.push("SPF passed");
+			return {
+				verdict: "unknown",
+				confidence: "low",
+				reasons
+			};
+		}
+		if (auth.spf === "pass") {
+			reasons.push("No DMARC record for sender domain");
+			reasons.push("No DKIM signatures present");
+			reasons.push("SPF passed (but SPF alone is weak authentication)");
+			return {
+				verdict: "unknown",
+				confidence: "low",
+				reasons
+			};
+		}
+		reasons.push("No DMARC record for sender domain");
+		reasons.push("No valid authentication found");
+		return {
+			verdict: "unknown",
+			confidence: "low",
+			reasons
+		};
+	}
+	return {
+		verdict: "unknown",
+		confidence: "low",
+		reasons: ["Unable to determine email authenticity"]
+	};
+}
+
 //#endregion
 //#region src/parsing.ts
 /**
@@ -844,4 +1183,4 @@ function verifyRawEmailDownload(downloaded, event) {
 }
 
 //#endregion
-export { MYMX_CONFIRMED_HEADER, MYMX_SIGNATURE_HEADER, MyMXWebhookError, PAYLOAD_ERRORS, RAW_EMAIL_ERRORS, RawEmailDecodeError, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, verifyRawEmailDownload, verifyWebhookSignature };
+export { MYMX_CONFIRMED_HEADER, MYMX_SIGNATURE_HEADER, MyMXWebhookError, PAYLOAD_ERRORS, RAW_EMAIL_ERRORS, RawEmailDecodeError, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, validateEmailAuth, verifyRawEmailDownload, verifyWebhookSignature };