spamscanner 7.0.2 → 7.0.4

package/dist/types/arf.d.cts

@@ -0,0 +1,11 @@
+import type * as m from './arf.js' with {'resolution-mode': 'import'};
+export declare const parseReportFields: typeof m.parseReportFields;
+export declare const findPart: typeof m.findPart;
+export declare const isArfMessage: typeof m.isArfMessage;
+export declare const parse: typeof m.parse;
+export declare const tryParse: typeof m.tryParse;
+export declare const create: typeof m.create;
+export declare const VALID_FEEDBACK_TYPES: typeof m.VALID_FEEDBACK_TYPES;
+export declare const ArfParser: typeof m.ArfParser;
+declare const _default: typeof m.default;
+export {_default as default};

package/dist/types/arf.d.ts

@@ -32,8 +32,9 @@ export function isArfMessage(parsed: object): boolean;
  * @returns {Promise<object>} feedbackType, userAgent, version, arrivalDate,
  *   sourceIp, originalMailFrom, originalRcptTo, reportingMta,
  *   originalEnvelopeId, authenticationResults, reportedDomain, reportedUri,
- *   incidents, humanReadable, originalMessage, originalHeaders (always an
- *   object of lowercase header name to value) and rawFeedbackReport
+ *   incidents, humanReadable, originalMessage, originalHeaders (an object of
+ *   lowercase header name to value, or null when the report has no original
+ *   message) and rawFeedbackReport
  * @throws {Error} when the message is not a valid ARF report
  */
 export function parse(source: Buffer | string): Promise<object>;
@@ -44,36 +45,38 @@ export function parse(source: Buffer | string): Promise<object>;
  */
 export function tryParse(source: Buffer | string): Promise<object | null>;
 /**
- * Write an ARF report.
+ * 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.)
+ * @template {string|Buffer} M
  * @param {object} options
  * @param {string} options.feedbackType - abuse, fraud, virus, other, not-spam, ...
  * @param {string} options.userAgent
  * @param {string} options.from
  * @param {string} options.to
- * @param {string|Buffer} options.originalMessage
+ * @param {M} options.originalMessage
  * @param {string} [options.humanReadable]
  * @param {string} [options.subject]
  * @param {string} [options.sourceIp]
  * @param {string} [options.originalMailFrom]
- * @param {string[]} [options.originalRcptTo]
- * @param {Date} [options.arrivalDate]
+ * @param {string|string[]} [options.originalRcptTo]
+ * @param {Date|string|number} [options.arrivalDate]
  * @param {string} [options.reportingMta]
- * @returns {string}
+ * @returns {M extends Buffer ? Buffer : string} the report
  */
-export function create(options?: {
+export function create<M extends string | Buffer>(options?: {
     feedbackType: string;
     userAgent: string;
     from: string;
     to: string;
-    originalMessage: string | Buffer;
+    originalMessage: M;
     humanReadable?: string;
     subject?: string;
     sourceIp?: string;
     originalMailFrom?: string;
-    originalRcptTo?: string[];
-    arrivalDate?: Date;
+    originalRcptTo?: string | string[];
+    arrivalDate?: Date | string | number;
     reportingMta?: string;
-}): string;
+}): M extends Buffer ? Buffer : string;
 /**
  * Feedback types from RFC 5965, RFC 6591 (auth-failure) and RFC 7489 (dmarc).
  */

package/dist/types/attachments.d.ts

@@ -39,11 +39,15 @@ export function zipEntries(buffer: Buffer, limit?: number): Array<{
  * - disguised_executable: content is a program but the name says otherwise
  * - double_extension: "invoice.pdf.exe"
  * - rtl_override: a right-to-left override hides the real extension (a file named "invoice", U+202E, "fdp.exe" shows as "invoiceexe.pdf")
+ * - risky_attachment: a type that is risky by name but not a program
+ *   (a certificate, an Internet shortcut, a theme; see RISKY_EXTENSIONS)
  * - executable_in_archive: a ZIP holds a program, read without unpacking
  *   (extension: the first program's, extensions: every program's)
+ * - script_in_archive: a ZIP holds scripts (JavaScript, Python, shell, Perl)
+ *   but no other programs
  * - encrypted_archive: a password-protected ZIP, which virus scanners cannot open
  * - macro: an Office document with a VBA project
- * - pdf_active: a PDF with JavaScript, launch actions or embedded files
+ * - pdf_active: a PDF with JavaScript or launch actions
  * - rtf_object: an RTF document with an embedded OLE object
  * - html_attachment: an HTML or SVG file, the usual carrier of fake login pages
  *
@@ -69,4 +73,12 @@ export function inspectAttachments(attachments?: Array<{
  * campaigns.
  */
 export const EXECUTABLE_EXTENSIONS: Set<string>;
+/**
+ * File extensions Outlook blocks that are risky by name rather than programs:
+ * certificates (installing one trusts whoever holds its key), Internet
+ * shortcuts, Windows themes, and data files people send every day (MATLAB
+ * data, Outlook data, temporary files). Reported as risky_attachment, with
+ * few points.
+ */
+export const RISKY_EXTENSIONS: Set<string>;
 import { Buffer } from 'node:buffer';

package/dist/types/auth.d.ts

@@ -11,8 +11,11 @@ export function createResolver(timeout?: number, servers?: string[]): (name: str
 /**
  * Overall DKIM result from mailauth's per-signature results: "pass" when any
  * signature passes, "fail" when signatures exist and none passes, "none"
- * without signatures. `aligned` is the From domain a passing signature is
- * aligned with, if any.
+ * without signatures. `aligned` is the signing domain of a passing signature
+ * aligned with the From domain (relaxed: they share their registrable domain),
+ * in ASCII, if any. A signature whose body length (l=) is shorter than the
+ * body (mailauth's `status.underSized`) is aligned with nothing: it signs only
+ * the start of the body, and anyone can append to it.
  * @param {object} dkim
  * @returns {{status: {result: string, comment: string}, results: object[], aligned: string|null}}
  */
@@ -26,11 +29,29 @@ export function summarizeDkim(dkim: object): {
 };
 /**
  * Turn mailauth's output into this module's result shape, filling in "none"
- * for anything mailauth left out.
+ * for anything mailauth left out, and checking what mailauth does not:
+ *
+ * - the policy (`p`, `sp`) and alignment modes (`adkim`, `aspf`) of the
+ *   DMARC record are read without spaces and in any case, as RFC 7489 reads
+ *   them ("p= None" is none, "adkim=S" strict), and strict alignment is
+ *   enforced: under it only a signature or SPF pass of the From domain itself
+ *   aligns, and DMARC fails without one;
+ * - a message without exactly one From address, whose DMARC mailauth does
+ *   not check, fails DMARC, as RFC 7489 (6.6.1) allows;
+ * - `arc.sealer` is the domain of the newest ARC seal of a passing chain,
+ *   when its ARC-Message-Signature is of the same domain, and `arc.trusted`
+ *   whether it is one of `trustedArcSealers` (or under one) and the results
+ *   it sealed show the message passed DMARC, or DKIM or SPF aligned with the
+ *   From domain, when it got it.
  * @param {object} output
+ * @param {object} [options]
+ * @param {string[]} [options.trustedArcSealers] - forwarders whose ARC seal
+ *   is believed
  * @returns {object}
  */
-export function normalizeAuthOutput(output?: object): object;
+export function normalizeAuthOutput(output?: object, options?: {
+    trustedArcSealers?: string[];
+}): object;
 /**
  * Check SPF, DKIM, DMARC, ARC and BIMI for a message, using mailauth.
  *
@@ -46,6 +67,10 @@ export function normalizeAuthOutput(output?: object): object;
  * @param {Function} [options.resolver] - custom DNS resolver (name, type)
  * @param {number} [options.timeout] - DNS timeout in milliseconds
  * @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
+ *   on, which passed when they got it, gets no points for failing SPF, DKIM
+ *   and DMARC (see normalizeAuthOutput)
  * @returns {Promise<object>} dkim, spf, dmarc, arc, bimi, receivedChain and
  *   headers (Received-SPF and Authentication-Results, ready to prepend)
  */
@@ -57,9 +82,20 @@ export function authenticate(message: Buffer | string, options?: {
     resolver?: Function;
     timeout?: number;
     dnsServers?: string[];
+    trustedArcSealers?: string[];
 }): Promise<object>;
 /**
  * Score authentication results: failures add points, passes take some away.
+ *
+ * A DMARC failure scores `dmarcFail` when the domain's policy is quarantine
+ * or reject (or not known), and SPF failing as well adds nothing more: DMARC
+ * already counts it. When the policy is none it scores `dmarcFailNone`, on
+ * top of SPF's points, so a domain with policy none is never easier to
+ * spoof than one without DMARC. A DKIM signature of only part of the body
+ * (l=) earns no DKIM_PASS, nor a DMARC pass that rests on one alone
+ * DMARC_PASS. An ARC seal counts only from a trusted forwarder (`arc.trusted`,
+ * see authenticate's trustedArcSealers): its pass gets ARC_PASS, and no
+ * points for failing SPF, DKIM or DMARC, as forwarding is what broke them.
  * @param {object} auth - from authenticate
  * @param {object} [weights] - overrides for DEFAULT_AUTH_WEIGHTS
  * @returns {{score: number, tests: Array<{name: string, score: number}>}}
@@ -93,6 +129,7 @@ export namespace DEFAULT_AUTH_WEIGHTS {
     let spfSoftfail: number;
     let dmarcPass: number;
     let dmarcFail: number;
+    let dmarcFailNone: number;
     let arcPass: number;
     let arcFail: number;
 }

package/dist/types/clamav.d.ts

@@ -17,7 +17,7 @@ export function clamdAddress(options?: object): {
  * @param {string} [options.socket] - clamd's Unix socket
  * @param {string} [options.host] - or its TCP host
  * @param {number} [options.port] - and port (3310)
- * @param {number} [options.timeout] - milliseconds
+ * @param {number} [options.timeout] - milliseconds for the whole scan
  * @param {number} [options.chunkSize]
  * @returns {Promise<{infected: boolean, viruses: string[], reply: string}>}
  */

package/dist/types/classifier.d.ts

@@ -27,6 +27,9 @@ export const MODEL_VERSION: 2;
 export class Classifier {
     /**
      * Load a model written by toJSON. Options passed here override the model's.
+     * A model is data that may come from anywhere, so everything in it is
+     * checked: a damaged one throws a TypeError starting "Corrupt classifier
+     * model".
      * @param {object|string} json
      * @param {object} [options]
      * @returns {Classifier}
@@ -67,7 +70,7 @@ export class Classifier {
     /**
      * Score a message.
      * @param {string[]} features
-     * @returns {{probability: number, category: 'spam'|'ham'|'unsure', spam: number, ham: number, clues: Array<{feature: string, probability: number}>}}
+     * @returns {{probability: number, category: 'spam'|'ham'|'unsure', spam: number, ham: number, clues: Array<{feature: string, probability: number}>, coverage: {feature: string|null, spam: number, ham: number, confidence: number}}}
      */
     classify(features: string[]): {
         probability: number;
@@ -78,6 +81,12 @@ export class Classifier {
             feature: string;
             probability: number;
         }>;
+        coverage: {
+            feature: string | null;
+            spam: number;
+            ham: number;
+            confidence: number;
+        };
     };
     /**
      * How well the training data covers the language of a message, from the

package/dist/types/dnsbl.d.ts

@@ -1,6 +1,20 @@
+export function isLookupName(name: any): boolean;
+/**
+ * An IP address as blocklists and allowlists know it: without an IPv6 zone
+ * ("fe80::1%eth0"), and an IPv4 address mapped into IPv6 ("::ffff:192.0.2.1",
+ * as a dual-stack server reports IPv4 clients) as the IPv4 address, and any
+ * other IPv6 address in its canonical form (RFC 5952: "2001:db8::1", and an
+ * IPv4 address translated into IPv6 or under the NAT64 prefix in dotted form:
+ * "::ffff:0:192.0.2.1", "64:ff9b::192.0.2.1"). Anything
+ * that is not an IP address is returned as it is.
+ * @param {string} ip
+ * @returns {string}
+ */
+export function normalizeIp(ip: string): string;
 /**
  * The DNS name to query for an IP address in a blocklist zone: reversed
  * octets for IPv4 ("4.3.2.1.zen.spamhaus.org"), reversed nibbles for IPv6.
+ * An IPv4 address mapped into IPv6 is looked up as IPv4.
  * @param {string} ip
  * @param {string} zone
  * @returns {string|null}
@@ -8,8 +22,12 @@
 export function reverseName(ip: string, zone: string): string | null;
 /**
  * Whether an answer means "listed": an address in 127.0.0.0/8 that is not one
- * of the error codes lists return when queries are refused (127.255.255.x at
- * Spamhaus, 127.0.0.255 at SURBL, 127.0.0.1 at URIBL for blocked resolvers).
+ * of the error codes lists return when queries are refused or wrong: at
+ * Spamhaus, 127.255.255.x (127.255.255.252 for a misspelled zone,
+ * .254 for queries through a public resolver, .255 for too many queries) and
+ * 127.0.1.255 (an address looked up in the DBL), 127.0.0.255 anywhere, and
+ * 127.0.0.1 at SURBL and URIBL, which answer it to resolvers they block
+ * (SpamAssassin's SURBL_BLOCKED and URIBL_BLOCKED).
  * @param {string} address
  * @param {string} zone
  * @returns {boolean}
@@ -69,6 +87,16 @@ export class DnsChecker {
      * @returns {Promise<string[]>}
      */
     resolve4(name: string, servers?: string[] | null): Promise<string[]>;
+    /**
+     * A records for a name, an empty list when the name does not exist or has
+     * no A records, and null when no answer came: the lookup timed out or
+     * failed (SERVFAIL, refused, unreachable). Only answers are cached, so a
+     * failed lookup is tried again for the next message.
+     * @param {string} name
+     * @param {string[]|null} [servers]
+     * @returns {Promise<string[]|null>}
+     */
+    answer(name: string, servers?: string[] | null): Promise<string[] | null>;
     /**
      * Look an IP address up in IP blocklists.
      * @param {string} ip
@@ -94,13 +122,15 @@ export class DnsChecker {
     /**
      * Ask Cloudflare's filtering resolvers about host names. A name blocked by
      * the malware resolver is "malware"; one blocked only by the family
-     * resolver is "adult".
+     * resolver is "adult". The hosts that got no answer (from the malware
+     * resolver, or from the family resolver when asked) are listed in the
+     * result's (non-enumerable) `unanswered` property.
      * @param {string[]} hosts
      * @param {object} [options]
      * @param {boolean} [options.adult] - also ask the family resolver
      * @param {string[]} [options.malwareServers]
      * @param {string[]} [options.familyServers]
-     * @returns {Promise<Array<{host: string, category: 'malware'|'adult'}>>}
+     * @returns {Promise<Array<{host: string, category: 'malware'|'adult'}> & {unanswered: string[]}>}
      */
     checkCloudflare(hosts?: string[], options?: {
         adult?: boolean;
@@ -109,5 +139,7 @@ export class DnsChecker {
     }): Promise<Array<{
         host: string;
         category: "malware" | "adult";
-    }>>;
+    }> & {
+        unanswered: string[];
+    }>;
 }

package/dist/types/headers.d.ts

@@ -16,8 +16,9 @@ export function foldHeader(name: string, value: string, newline?: string): strin
  * - X-Spam-Level: one star per point (Sieve: header :contains "X-Spam-Level" "*****")
  * - X-Spam-Status: Yes or No, with score, threshold, tests and version
  * - X-Spam-Action: accept, tag or reject
+ * - X-Spam-Virus-Scan: failed, when ClamAV could not scan an attachment
  *
- * @param {{score: number, threshold: number, isSpam: boolean, action: string, tests: Array<{name: string}>}} result
+ * @param {{score: number, threshold: number, isSpam: boolean, action: string, tests: Array<{name: string}>, results?: {virusScanErrors?: Array<object>}}} result
  * @param {object} [options]
  * @param {string} [options.version]
  * @returns {Array<[string, string]>} header name and value pairs
@@ -30,6 +31,9 @@ export function spamHeaders(result: {
     tests: Array<{
         name: string;
     }>;
+    results?: {
+        virusScanErrors?: Array<object>;
+    };
 }, options?: {
     version?: string;
 }): Array<[string, string]>;
@@ -43,6 +47,31 @@ export function splitMessage(raw: Buffer): {
     body: Buffer;
     newline: string;
 };
+/**
+ * A subject tag as it can go in a header: on one line, and, when it is not
+ * printable ASCII, holds "=?" (which would read as the start of an encoded
+ * word) or a word too long to fold, as encoded words (RFC 2047) of at most
+ * 64 characters, split only between whole characters and separated by
+ * spaces, so "[垃圾]" survives and a tag cannot add header lines. A tag empty
+ * after cleanup is "".
+ * @param {string} tag
+ * @param {boolean} [spaceAfter] - for a tag before an encoded word: the space
+ *   after an encoded tag goes inside it, since the space between two encoded
+ *   words is not shown
+ * @returns {string}
+ */
+export function subjectTagText(tag: string, spaceAfter?: boolean): string;
+/**
+ * A Subject header's value with a tag before it (see subjectTagText), folded
+ * between the tag's words so a line with an encoded word stays within 76
+ * characters, and before the subject when the line would be too long, or
+ * null when the tag is empty or the subject already starts with it.
+ * @param {string} tag
+ * @param {string} current - the subject's value, as written, perhaps folded
+ * @param {string} [newline]
+ * @returns {string|null} the value, after "Subject: "
+ */
+export function taggedSubject(tag: string, current: string, newline?: string): string | null;
 /**
  * Add headers to a raw message and optionally tag its subject.
  *

package/dist/types/homograph.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Whether a name is a brand with one letter left out inside it, or with one
+ * of its letters doubled.
+ * @param {string} name
+ * @param {string} brand
+ * @returns {boolean}
+ */
+export function isDroppedOrDoubled(name: string, brand: string): boolean;
 /**
  * Map every lookalike character of a domain label to the Latin letter it
  * imitates (Cyrillic "рауpаl" becomes "paypal").
@@ -24,6 +32,14 @@ export function editDistance(a: string, b: string, max?: number): number;
  * @returns {string|null}
  */
 export function brandWithPhishingWord(name: string, brands: Set<string>): string | null;
+/**
+ * Whether two names differ only by two neighbouring letters swapped (not
+ * when they are the same).
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function isSwap(a: string, b: string): boolean;
 /**
  * Brands most often imitated in phishing: banks, payment services, mail and
  * cloud providers, shops, couriers and tax offices. A domain whose name is a
@@ -31,6 +47,7 @@ export function brandWithPhishingWord(name: string, brands: Set<string>): string
  * never flagged.
  */
 export const BRANDS: string[];
+export const PHISHING_WORDS: string[];
 /**
  * Detects domains made to look like well-known brands: lookalike letters from
  * other scripts (Cyrillic "а" for Latin "a"), mixed scripts in one label,
@@ -79,7 +96,7 @@ export default class HomographDetector {
         recommendations: string[];
         confidence: number;
     };
-    analyse(input: any): {
+    analyse(input: any, written?: any): {
         domain: any;
         unicode: any;
         isIDN: boolean;

package/dist/types/html.d.ts

@@ -12,6 +12,35 @@
 export function decodeEntities(value: string, { attribute }?: {
     attribute?: boolean;
 }): string;
+/**
+ * The values of the attributes of an HTML document that may hold words (see
+ * NO_WORD_ATTRIBUTES), with their character references decoded, where the
+ * tag that holds each starts and ends, and whether it is a form's help text
+ * (see FIELD_HELP), in order: not
+ * those in comments or in the raw text of scripts and styles, and none after
+ * a tag the input ends inside, as browsers read them. In time linear in the
+ * input.
+ * @param {string} html
+ * @returns {Array<{text: string, start: number, end: number, help: boolean}>}
+ */
+export function attributeText(html: string): Array<{
+    text: string;
+    start: number;
+    end: number;
+    help: boolean;
+}>;
+/**
+ * Where a form's help text is in an HTML document (see FIELD_HELP): the
+ * values of those attributes and the text of each <label> of at most
+ * MAX_HELP characters, as places in the input, in order of where they start
+ * (a label's text may hold another's). In time linear in the input.
+ * @param {string} html
+ * @returns {Array<{from: number, to: number}>}
+ */
+export function formHelp(html: string): Array<{
+    from: number;
+    to: number;
+}>;
 /**
  * The text of HTML as a mail client shows it, read in linear time: without
  * tags, comments, scripts, styles and the title, with character references

package/dist/types/index.d.cts

@@ -0,0 +1,22 @@
+import type * as m from './index.js' with {'resolution-mode': 'import'};
+type SpamScanner = m.SpamScanner;
+declare const SpamScanner: typeof m.SpamScanner & Omit<typeof m, 'default'> & {default: typeof m.SpamScanner};
+declare namespace SpamScanner {
+	export type SpamScanner = m.SpamScanner;
+	export type Classifier = m.Classifier;
+	export type MilterServer = m.MilterServer;
+	export type SmtpSession = m.SmtpSession;
+	export type ReputationOptions = m.ReputationOptions;
+	export type LegacyOptions = m.LegacyOptions;
+	export type SpamScannerOptions = m.SpamScannerOptions;
+	export type ScannerSettings = m.ScannerSettings;
+	export type ScanOptions = m.ScanOptions;
+	export type ScanTest = m.ScanTest;
+	export type ScanFinding = m.ScanFinding;
+	export type ReputationAnswer = m.ReputationAnswer;
+	export type ReputationResult = m.ReputationResult;
+	export type ScanDetails = m.ScanDetails;
+	export type ScanResult = m.ScanResult;
+	export type LLMClassifier = m.LLMClassifier;
+}
+export = SpamScanner;