spamscanner 7.0.4 → 7.0.5

package/dist/types/arf.d.ts

@@ -28,7 +28,7 @@ export function findPart(raw: string, boundary: string, types: string[]): {
 export function isArfMessage(parsed: object): boolean;
 /**
  * Parse an ARF (RFC 5965) abuse report.
- * @param {Buffer|string} source - the raw report message
+ * @param {Buffer|Uint8Array|string} source - the raw report message
  * @returns {Promise<object>} feedbackType, userAgent, version, arrivalDate,
  *   sourceIp, originalMailFrom, originalRcptTo, reportingMta,
  *   originalEnvelopeId, authenticationResults, reportedDomain, reportedUri,
@@ -37,13 +37,13 @@ export function isArfMessage(parsed: object): boolean;
  *   message) and rawFeedbackReport
  * @throws {Error} when the message is not a valid ARF report
  */
-export function parse(source: Buffer | string): Promise<object>;
+export function parse(message: any): Promise<object>;
 /**
  * Parse an ARF report, or return null when the message is not one.
- * @param {Buffer|string} source
+ * @param {Buffer|Uint8Array|string} source
  * @returns {Promise<object|null>}
  */
-export function tryParse(source: Buffer | string): Promise<object | null>;
+export function tryParse(source: Buffer | Uint8Array | string): Promise<object | null>;
 /**
  * Write an ARF report.  (A string message gives a string report, and a
  * Buffer a Buffer, its bytes kept as they are, whatever their character set.)

package/dist/types/attachments.d.ts

@@ -21,7 +21,9 @@ export function sniff(buffer: Buffer): {
  * is read, as well as the last one found: archive programs differ in which
  * they use, so a directory hidden behind another record is read too.  ZIP64
  * archives, and archives after other data (self-extracting archives), are
- * read as well.
+ * read as well. Each entry is read once, however many directories overlap
+ * it; a name longer than 1 KiB keeps its first and last 512 bytes (with "…"
+ * between them), and reading stops after 1 MiB of names.
  * @param {Buffer} buffer
  * @param {number} [limit] - most entries to read
  * @returns {Array<{name: string, encrypted: boolean, size: number}>}

package/dist/types/auth.d.ts

@@ -8,6 +8,20 @@
  * @returns {(name: string, type: string) => Promise<any[]>}
  */
 export function createResolver(timeout?: number, servers?: string[]): (name: string, type: string) => Promise<any[]>;
+/**
+ * A resolver that answers through `resolver` at most `maxQueries` times and
+ * until `deadline` (a time in milliseconds, as Date.now() gives it): any
+ * lookup after either, or still unanswered at the deadline, fails at once
+ * with ETIMEOUT, so a message's checks stop sending queries when its time is
+ * up and never send more than `maxQueries`.
+ * @param {(name: string, type: string) => Promise<any[]>} resolver
+ * @param {{maxQueries?: number, deadline?: number}} [limits]
+ * @returns {(name: string, type: string) => Promise<any[]>}
+ */
+export function limitResolver(resolver: (name: string, type: string) => Promise<any[]>, { maxQueries, deadline }?: {
+    maxQueries?: number;
+    deadline?: number;
+}): (name: string, type: string) => Promise<any[]>;
 /**
  * Overall DKIM result from mailauth's per-signature results: "pass" when any
  * signature passes, "fail" when signatures exist and none passes, "none"
@@ -57,6 +71,7 @@ export function normalizeAuthOutput(output?: object, options?: {
  *
  * Needs the connecting client's IP address: without it nothing is checked and
  * every result is "none". DNS errors give "temperror" results, never a pass.
+ * Only the first MAX_DKIM_SIGNATURES DKIM signatures are checked.
  *
  * @param {Buffer|string} message - the raw message
  * @param {object} options
@@ -65,7 +80,11 @@ export function normalizeAuthOutput(output?: object, options?: {
  * @param {string} [options.sender] - envelope sender (MAIL FROM)
  * @param {string} [options.mta] - this server's hostname, for the headers
  * @param {Function} [options.resolver] - custom DNS resolver (name, type)
- * @param {number} [options.timeout] - DNS timeout in milliseconds
+ * @param {number} [options.timeout] - milliseconds for a DNS lookup, and for
+ *   all of the message's: no lookup is sent, nor waited for, after this long
+ *   (and 100 ms more)
+ * @param {number} [options.maxDnsQueries] - DNS lookups allowed for the
+ *   message (MAX_DNS_QUERIES); any more fail with a temporary error
  * @param {string[]} [options.dnsServers] - name servers to use
  * @param {string[]} [options.trustedArcSealers] - forwarders (such as a
  *   mailing list's domain) whose ARC seal is believed: a message they passed
@@ -81,6 +100,7 @@ export function authenticate(message: Buffer | string, options?: {
     mta?: string;
     resolver?: Function;
     timeout?: number;
+    maxDnsQueries?: number;
     dnsServers?: string[];
     trustedArcSealers?: string[];
 }): Promise<object>;
@@ -109,7 +129,8 @@ export function calculateAuthScore(auth: object, weights?: object): {
 };
 /**
  * The Authentication-Results header (RFC 8601) for a result, without the
- * header name. mailauth's own headers are used when present.
+ * header name. mailauth's own headers are used when present, with as many
+ * of their results as fit in 8 KiB.
  * @param {object} auth
  * @param {string} [hostname]
  * @returns {string}
@@ -121,6 +142,15 @@ export function formatAuthResultsHeader(auth: object, hostname?: string): string
  * @returns {string}
  */
 export function summarizeAuth(auth: object): string;
+export { MAX_DKIM_SIGNATURES } from "./parse.js";
+/**
+ * DNS lookups allowed for one message: room for SPF at the limits of RFC
+ * 7208 (10 lookups, each MX mechanism with up to 10 hosts, A and AAAA, about
+ * 220 in all, as mailauth counts them), MAX_DKIM_SIGNATURES keys (see
+ * boundedForAuth), the
+ * newest ARC seal, DMARC and BIMI.
+ */
+export const MAX_DNS_QUERIES: 300;
 export namespace DEFAULT_AUTH_WEIGHTS {
     let dkimPass: number;
     let dkimFail: number;

package/dist/types/milter.d.ts

@@ -116,6 +116,8 @@ export class MilterSession {
     body: any[];
     size: number;
     truncated: boolean;
+    headerSize: number;
+    keep(data: any): void;
     send(command: any, data: any): void;
     receive(chunk: any): void;
     process(): Promise<void>;
@@ -146,8 +148,10 @@ export class MilterServer extends EventEmitter<[never]> {
      * @param {boolean} [options.quarantine] - hold spam in the MTA's quarantine
      * @param {string|null} [options.subjectTag] - e.g. "[SPAM]"
      * @param {string} [options.hostname] - this server's name, for Authentication-Results
-     * @param {number} [options.maxSize] - body bytes kept for scanning
+     * @param {number} [options.maxSize] - body bytes kept for scanning (and the
+     *   most bytes of envelope and headers: beyond them a message is not scanned)
      * @param {'tempfail'|'accept'} [options.onError] - answer when a scan fails
+     * @param {number} [options.maxConnections] - connections kept open at once; more are closed at once
      */
     constructor(scanner: import("./index.js").SpamScanner, options?: {
         reject?: boolean;
@@ -158,6 +162,7 @@ export class MilterServer extends EventEmitter<[never]> {
         hostname?: string;
         maxSize?: number;
         onError?: "tempfail" | "accept";
+        maxConnections?: number;
     });
     scanner: import("./index.js").SpamScanner;
     options: {
@@ -169,6 +174,7 @@ export class MilterServer extends EventEmitter<[never]> {
         hostname: string;
         maxSize: number;
         onError: string;
+        maxConnections: number;
     };
     sockets: Set<any>;
     server: net.Server;

package/dist/types/model.d.ts

@@ -49,8 +49,9 @@ export function loadDefaultModel(options?: object, { file, sea }?: {
 export function loadModel(file: string, options?: object): Classifier;
 /**
  * Write a classifier to a file, creating its directory. The model is written
- * to a temporary file next to it first, then renamed, so a process loading
- * the file never reads half of it.
+ * to a new temporary file next to it first, flushed to disk, then renamed, so
+ * a process loading the file, or one reading it after a crash, never reads
+ * half of it. A file replaced keeps its permissions.
  * @param {Classifier} classifier
  * @param {string} file
  * @param {object} [options] - see Classifier#toJSON

package/dist/types/parse.d.ts

@@ -1,11 +1,49 @@
+/**
+ * The message as mailauth is to read it: its address fields bounded as
+ * parseMessage bounds them (mailauth reads From and Return-Path with the same
+ * parser), and, when the header would take mailauth longer than linear time
+ * (it joins folded lines, and finds the fields a DKIM signature names, in
+ * time that grows with the square of their number), the header cut down:
+ * its folded lines unfolded (which relaxed canonicalization of DKIM does
+ * too) and only the fields that say who sent the message and how, as many
+ * as smallerHeader keeps, each up to MAX_FIELD characters (address fields as
+ * bounded), and at most MAX_SIGNATURES signatures. Only the first
+ * MAX_DKIM_SIGNATURES DKIM-Signature fields are ever kept (with their folded
+ * lines; the body is untouched). `fromCut` is whether a
+ * From field was cut or left out: then mailauth did not read the From
+ * address the message gives.
+ * @param {Buffer} raw
+ * @returns {{raw: Buffer, fromCut: boolean}}
+ */
+export function boundedForAuth(raw: Buffer): {
+    raw: Buffer;
+    fromCut: boolean;
+};
+/**
+ * The simpleParser of mailparser on a message it can finish (see finishable),
+ * settled within `timeout`: a parse that has not settled by then is stopped
+ * (its parser destroyed) and rejected with an ETIMEDOUT error.
+ * @param {Buffer|string} raw
+ * @param {object} [options]
+ * @param {number} [options.timeout] - milliseconds (PARSE_TIMEOUT)
+ * @param {typeof simpleParser} [options.parser] - for tests
+ * @returns {Promise<object>} the parsed message
+ */
+export function simpleParse(raw: Buffer | string, { timeout, parser }?: {
+    timeout?: number;
+    parser?: typeof simpleParser;
+}): Promise<object>;
 /**
  * Parse a message with mailparser, which does not make text of HTML here:
  * `text` is that of the plain text parts only (empty for a message of HTML
  * alone), and the text HTML shows is read by getFeatures.
  * @param {Buffer|string} raw
+ * @param {{timeout?: number}} [options] - milliseconds for the parse (PARSE_TIMEOUT)
  * @returns {Promise<object>} the parsed message
  */
-export function parseMessage(raw: Buffer | string): Promise<object>;
+export function parseMessage(raw: Buffer | string, options?: {
+    timeout?: number;
+}): Promise<object>;
 /**
  * A message mailparser can finish: it never finishes one that ends in the
  * header of an attached message (however that header names or folds its
@@ -15,6 +53,17 @@ export function parseMessage(raw: Buffer | string): Promise<object>;
  * @returns {Buffer}
  */
 export function finishable(raw: Buffer | string): Buffer;
+/**
+ * The message with each header field folded on more than MAX_FOLDS lines
+ * unfolded: its line breaks and the white space after each made one space,
+ * as mailparser reads a field (libmime's decodeHeader), so what it reads is
+ * the same. Header fields are those of the message and, as mailsplit finds
+ * them, of each MIME part and each attached message inline; everything else
+ * is left as it is. The message itself when nothing is unfolded.
+ * @param {Buffer} raw
+ * @returns {Buffer}
+ */
+export function unfoldHeaders(raw: Buffer): Buffer;
 /**
  * Parse a message, reading what can be read of one beyond mailparser's
  * limits (more than 1000 MIME parts, a part's header over 1 MB): its parts
@@ -23,12 +72,16 @@ export function finishable(raw: Buffer | string): Buffer;
  * is too large, the message with its header lines cut down, or its first
  * megabyte when the header is that of a later part. `error` is the limit,
  * or null. Other errors are thrown, as earlier versions did (servers defer
- * the message).
+ * the message), and so is a parse not finished by `deadline` (ETIMEDOUT).
  * @param {Buffer} raw
- * @param {(raw: Buffer) => Promise<object>} [parse] - for tests
+ * @param {(raw: Buffer, options: {timeout: number}) => Promise<object>} [parse] - for tests
+ * @param {number} [deadline] - Date.now() milliseconds by which every try
+ *   ends (PARSE_TIMEOUT from now)
  * @returns {Promise<{mail: object, error: string|null}>}
  */
-export function parseWithin(raw: Buffer, parse?: (raw: Buffer) => Promise<object>): Promise<{
+export function parseWithin(raw: Buffer, parse?: (raw: Buffer, options: {
+    timeout: number;
+}) => Promise<object>, deadline?: number): Promise<{
     mail: object;
     error: string | null;
 }>;
@@ -43,4 +96,13 @@ export function parseWithin(raw: Buffer, parse?: (raw: Buffer) => Promise<object
  * @returns {Promise<Array<object>>}
  */
 export function expandAttachments(attachments?: Array<object>, errors?: string[], parse?: (raw: Buffer) => Promise<object>): Promise<Array<object>>;
+/**
+ * DKIM-Signature fields mailauth reads of a message (see boundedForAuth): it
+ * checks every signature, hashing the body once for each body length (l=)
+ * and canonicalization and looking up each signer's key, so hundreds of them
+ * would hold up the process and send as many DNS queries. Real mail carries
+ * one to three.
+ */
+export const MAX_DKIM_SIGNATURES: 8;
+export const PARSE_TIMEOUT: 60000;
 import { Buffer } from 'node:buffer';

package/dist/types/reputation.d.ts

@@ -71,7 +71,8 @@ export function reputationValues(mail?: object, session?: object): string[];
  * domain itself vouches for it. A DKIM signature of part of the body (l=
  * shorter than the body, mailauth's underSized) vouches for nothing, nor
  * does a DMARC pass that rests on one alone, and no signature vouches for a
- * From address when DMARC fails.
+ * From address when DMARC fails, nor for one of a From field too long to read
+ * whole (`mail.from.truncated`).
  * @param {object} mail - parsed message
  * @param {object} [session] - remoteAddress, resolvedClientHostname, envelope
  * @param {object|null} [authentication] - SPF, DKIM and DMARC results

package/dist/types/server.d.ts

@@ -35,12 +35,14 @@ export function sessionFromQuery(query: URLSearchParams): object;
  * @param {string} [options.token] - required as "Authorization: Bearer <token>" when set
  * @param {number} [options.maxSize] - largest message accepted, in bytes
  * @param {string} [options.modelPath] - where /learn saves the classifier
+ * @param {number} [options.maxConnections] - connections kept open, and requests handled, at once
  * @returns {http.Server}
  */
 export function createHttpServer(scanner: import("./index.js").SpamScanner, options?: {
     token?: string;
     maxSize?: number;
     modelPath?: string;
+    maxConnections?: number;
 }): http.Server;
 /**
  * A plain TCP server: a client sends a raw message and closes its side; the
@@ -54,12 +56,27 @@ export function createHttpServer(scanner: import("./index.js").SpamScanner, opti
  * @param {boolean} [options.json] - answer in JSON (default true)
  * @param {number} [options.maxSize]
  * @param {number} [options.timeout] - close a connection that sends nothing for this many milliseconds (default 60000)
+ * @param {number} [options.maxConnections] - connections kept open at once; more are closed at once
  * @returns {net.Server}
  */
 export function createTcpServer(scanner: import("./index.js").SpamScanner, options?: {
     json?: boolean;
     maxSize?: number;
     timeout?: number;
+    maxConnections?: number;
 }): net.Server;
+/**
+ * The largest message the servers and the command line read by default, in
+ * bytes (25 MiB): above Postfix's default message_size_limit (10 MB) and the
+ * limits of most mail services.
+ */
+export const MAX_MESSAGE_SIZE: number;
+/**
+ * The most connections each server keeps open at once by default (and, for
+ * the HTTP API, requests it handles at once): each may hold a message of up
+ * to MAX_MESSAGE_SIZE bytes while it is scanned. Postfix runs at most 100
+ * smtpd and 100 cleanup processes by default, each with one milter connection.
+ */
+export const MAX_CONNECTIONS: 200;
 import http from 'node:http';
 import net from 'node:net';

package/dist/types/spamd.d.ts

@@ -43,6 +43,7 @@ export function answer(scanner: import("./index.js").SpamScanner, request: {
  * @param {string} [options.modelPath] - where TELL saves the classifier
  * @param {string|null} [options.subjectTag] - tag for spam in PROCESS and HEADERS answers
  * @param {number} [options.timeout] - close a connection that sends nothing for this many milliseconds (default 60000)
+ * @param {number} [options.maxConnections] - connections kept open at once; more are closed at once
  * @returns {net.Server}
  */
 export function createSpamdServer(scanner: import("./index.js").SpamScanner, options?: {
@@ -51,6 +52,7 @@ export function createSpamdServer(scanner: import("./index.js").SpamScanner, opt
     modelPath?: string;
     subjectTag?: string | null;
     timeout?: number;
+    maxConnections?: number;
 }): net.Server;
 export namespace SPAMD_EXIT_CODES {
     export { EX_OK };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "spamscanner",
   "description": "Spam, phishing and malware filter for email in any language: a trainable classifier, link and attachment checks, SPF/DKIM/DMARC, and an optional AI second opinion from any LLM, including local Ollama models. Works as a library, CLI, Postfix milter or HTTP API.",
-  "version": "7.0.4",
+  "version": "7.0.5",
   "author": "Forward Email (https://forwardemail.net)",
   "bin": {
     "spamscanner": "./dist/esm/cli.js"