mailauth 4.11.0 → 4.12.0

package/lib/arc/index.d.ts

@@ -0,0 +1,47 @@
+// Type definitions for mailauth/lib/arc
+
+import { MessageInput, ARCData, ARCOptions, ARCResult, ARCSealOptions, ARCChainEntry } from '../../index';
+
+/**
+ * Verifies ARC chain in a message
+ *
+ * @param data - ARC chain data
+ * @param opts - ARC verification options
+ * @returns ARC verification result
+ */
+export function arc(data: ARCData, opts?: ARCOptions): Promise<ARCResult>;
+
+/**
+ * Seals a message with ARC headers
+ *
+ * @param input - RFC822 formatted message (stream, buffer, or string)
+ * @param seal - ARC sealing options
+ * @returns ARC headers to prepend
+ */
+export function sealMessage(input: MessageInput, seal: ARCSealOptions): Promise<Buffer>;
+
+/**
+ * Gets ARC chain from parsed headers
+ *
+ * @param headers - Parsed message headers
+ * @returns ARC chain or false if no chain found
+ */
+export function getARChain(headers: any): ARCChainEntry[] | false;
+
+/**
+ * Verifies ARC seal chain
+ *
+ * @param data - ARC chain data
+ * @param opts - ARC verification options
+ * @returns true if chain is valid
+ */
+export function verifyASChain(data: ARCData, opts: ARCOptions): Promise<boolean>;
+
+/**
+ * Creates ARC seal headers
+ *
+ * @param input - RFC822 formatted message or false for pre-calculated data
+ * @param data - Seal creation data
+ * @returns Seal headers
+ */
+export function createSeal(input: MessageInput | false, data: any): Promise<{ headers: string[] }>;

package/lib/bimi/index.d.ts

@@ -0,0 +1,20 @@
+// Type definitions for mailauth/lib/bimi
+
+import { BIMIOptions, BIMIResult, BIMIData, VMCValidationOptions, VMCValidationResult } from '../../index';
+
+/**
+ * Resolves BIMI record and logo location for a domain
+ *
+ * @param opts - BIMI lookup options
+ * @returns BIMI verification result
+ */
+export function bimi(opts: BIMIOptions): Promise<BIMIResult | false>;
+
+/**
+ * Validates BIMI VMC (Verified Mark Certificate) and logo file
+ *
+ * @param bimiData - BIMI data including location and authority URLs
+ * @param opts - VMC validation options
+ * @returns VMC validation result
+ */
+export function validateVMC(bimiData: BIMIData | null, opts?: VMCValidationOptions): Promise<VMCValidationResult | false>;

package/lib/dkim/sign.d.ts

@@ -0,0 +1,33 @@
+// Type definitions for mailauth/lib/dkim/sign
+
+/// <reference types="node" />
+
+import { Transform } from 'stream';
+import { MessageInput, DKIMSignOptions, DKIMSignResult } from '../../index';
+
+/**
+ * Signs an email message with DKIM signature(s)
+ *
+ * @param input - RFC822 formatted message (stream, buffer, or string)
+ * @param options - DKIM signing options
+ * @returns DKIM signature header(s) and any errors
+ */
+export function dkimSign(input: MessageInput, options: DKIMSignOptions): Promise<DKIMSignResult>;
+
+/**
+ * Transform stream for DKIM signing
+ * Prepends DKIM-Signature header to the message stream
+ */
+export class DkimSignStream extends Transform {
+    /**
+     * Creates a DKIM signing stream
+     *
+     * @param options - DKIM signing options
+     */
+    constructor(options: DKIMSignOptions);
+
+    /**
+     * Any errors encountered during signing
+     */
+    errors: Error[] | null;
+}

package/lib/dkim/verify.d.ts

@@ -0,0 +1,12 @@
+// Type definitions for mailauth/lib/dkim/verify
+
+import { MessageInput, DKIMVerifyOptions, DKIMVerifyResult } from '../../index';
+
+/**
+ * Verifies DKIM signatures in an email message
+ *
+ * @param input - RFC822 formatted message (stream, buffer, or string)
+ * @param options - DKIM verification options
+ * @returns DKIM verification results
+ */
+export function dkimVerify(input: MessageInput, options?: DKIMVerifyOptions): Promise<DKIMVerifyResult>;

package/lib/dmarc/index.d.ts

@@ -0,0 +1,11 @@
+// Type definitions for mailauth/lib/dmarc
+
+import { DMARCOptions, DMARCResult } from '../../index';
+
+/**
+ * Verifies DMARC policy for a message
+ *
+ * @param opts - DMARC verification options
+ * @returns DMARC verification result
+ */
+export function dmarc(opts: DMARCOptions): Promise<DMARCResult | false>;

package/lib/mailauth.js

@@ -1,13 +1,13 @@
 'use strict';
 
+const { dkimSign, DkimSignStream } = require('./dkim/sign');
 const { dkimVerify } = require('./dkim/verify');
 const { spf } = require('./spf');
 const { dmarc } = require('./dmarc');
-const { arc, createSeal } = require('./arc');
+const { arc, createSeal, sealMessage, getARChain, verifyASChain } = require('./arc');
 const { bimi, validateVMC: validateBimiVmc } = require('./bimi');
 const { validateSvg: validateBimiSvg } = require('./bimi/validate-svg');
 const { parseReceived } = require('./parse-received');
-const { sealMessage } = require('./arc');
 const libmime = require('libmime');
 const os = require('node:os');
 const { isIP } = require('net');
@@ -30,7 +30,7 @@ const { isIP } = require('net');
  * @param {Boolean} [opts.disableArc=false] If true then do not perform ARC validation and sealing
  * @param {Boolean} [opts.disableDmarc=false] If true then do not perform DMARC check
  * @param {Boolean} [opts.disableBimi=false] If true then do not perform BIMI check
- * @returns {Object} Authentication result
+ * @returns Authentication result
  */
 const authenticate = async (input, opts) => {
     opts = Object.assign({}, opts); // copy keys
@@ -191,7 +191,17 @@ const authenticate = async (input, opts) => {
 
 module.exports = {
     authenticate,
+    dkimSign,
+    DkimSignStream,
+    dkimVerify,
+    spf,
+    dmarc,
+    arc,
     sealMessage,
+    getARChain,
+    verifyASChain,
+    createSeal,
+    bimi,
     validateBimiVmc,
     validateBimiSvg
 };

package/lib/mta-sts.d.ts

@@ -0,0 +1,52 @@
+// Type definitions for mailauth/lib/mta-sts
+
+/// <reference types="node" />
+
+import { MTASTSOptions, MTASTSPolicy, MTASTSPolicyResult, MTASTSValidationResult } from '../index';
+
+/**
+ * Resolves MTA-STS policy ID from DNS
+ *
+ * @param address - Email address or domain name
+ * @param opts - MTA-STS options
+ * @returns Policy ID or false if not found
+ */
+export function resolvePolicy(address: string, opts?: MTASTSOptions): Promise<string | false>;
+
+/**
+ * Fetches and parses MTA-STS policy file from HTTPS
+ *
+ * @param domain - Domain name
+ * @param opts - MTA-STS options
+ * @returns Parsed policy or false if not found
+ */
+export function fetchPolicy(domain: string, opts?: MTASTSOptions): Promise<MTASTSPolicy | false>;
+
+/**
+ * Parses MTA-STS policy file content
+ *
+ * @param file - Policy file content
+ * @returns Parsed policy
+ * @throws Error if policy is invalid
+ */
+export function parsePolicy(file: Buffer | string): MTASTSPolicy;
+
+/**
+ * Validates MX hostname against MTA-STS policy
+ *
+ * @param mx - MX hostname to validate
+ * @param policy - MTA-STS policy
+ * @returns Validation result
+ */
+export function validateMx(mx: string, policy: MTASTSPolicy): MTASTSValidationResult;
+
+/**
+ * Gets complete MTA-STS policy for a domain
+ * Resolves DNS, fetches policy file, and handles caching
+ *
+ * @param domain - Domain name
+ * @param knownPolicy - Currently cached policy
+ * @param opts - MTA-STS options
+ * @returns Policy fetch result
+ */
+export function getPolicy(domain: string, knownPolicy?: MTASTSPolicy, opts?: MTASTSOptions): Promise<MTASTSPolicyResult>;

package/lib/mta-sts.js

@@ -22,7 +22,7 @@ const resolvePolicy = async (address, opts) => {
 
     address = (address || '').toString();
     let atPos = address.indexOf('@');
-    let domain = atPos < 0 ? address : atPos.substr(atPos + 1);
+    let domain = atPos < 0 ? address : address.substr(atPos + 1);
     if (/[\x7e-\xff]/.test(domain)) {
         // high bytes, probably U-label
         try {

package/lib/spf/index.d.ts

@@ -0,0 +1,11 @@
+// Type definitions for mailauth/lib/spf
+
+import { SPFOptions, SPFResult } from '../../index';
+
+/**
+ * Verifies SPF for a sender
+ *
+ * @param opts - SPF verification options
+ * @returns SPF verification result
+ */
+export function spf(opts: SPFOptions): Promise<SPFResult>;

package/package.json

@@ -1,8 +1,9 @@
 {
     "name": "mailauth",
-    "version": "4.11.0",
+    "version": "4.12.0",
     "description": "Email authentication library for Node.js",
     "main": "lib/mailauth.js",
+    "types": "index.d.ts",
     "scripts": {
         "test": "eslint \"lib/**/*.js\" \"test/**/*.js\" && mocha --recursive \"./test/**/*.js\" --reporter spec",
         "format": "prettier --write .",
@@ -34,25 +35,25 @@
     "homepage": "https://github.com/postalsys/mailauth",
     "devDependencies": {
         "chai": "4.4.1",
-        "eslint": "9.38.0",
+        "eslint": "9.39.2",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "10.1.8",
-        "js-yaml": "4.1.0",
+        "js-yaml": "4.1.1",
         "license-report": "6.8.1",
         "mbox-reader": "1.2.0",
-        "mocha": "11.7.4",
-        "prettier": "^3.6.2",
-        "resedit": "^3.0.0"
+        "mocha": "11.7.5",
+        "prettier": "3.7.4",
+        "resedit": "3.0.1"
     },
     "dependencies": {
         "@postalsys/vmc": "1.1.2",
         "fast-xml-parser": "4.5.2",
-        "ipaddr.js": "2.2.0",
-        "joi": "18.0.1",
+        "ipaddr.js": "2.3.0",
+        "joi": "18.0.2",
         "libmime": "5.3.7",
-        "nodemailer": "7.0.10",
+        "nodemailer": "7.0.11",
         "punycode.js": "2.3.1",
-        "tldts": "7.0.17",
+        "tldts": "7.0.19",
         "undici": "7.16.0",
         "yargs": "17.7.2"
     },