spamscanner 6.0.1 → 6.1.0

package/dist/types/arf.d.ts

@@ -0,0 +1,129 @@
+/**
+ * ARF (Abuse Reporting Format) Parser Type Definitions
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc5965.html
+ */
+
+/**
+ * Valid feedback types as defined in RFC 5965 and extensions
+ */
+export declare const VALID_FEEDBACK_TYPES: Set<string>;
+
+/**
+ * Reporting MTA information
+ */
+export interface ReportingMta {
+	/** MTA type (dns, smtp, etc.) */
+	type: string;
+	/** MTA hostname */
+	name: string;
+}
+
+/**
+ * Parsed ARF report result
+ */
+export interface ArfResult {
+	/** Whether this is a valid ARF message */
+	isArf: boolean;
+	/** ARF version (usually "1") */
+	version: string | null;
+	/** Feedback type (abuse, fraud, virus, other, not-spam, auth-failure, dmarc) */
+	feedbackType: string | null;
+	/** Original feedback type if it was normalized to "other" */
+	feedbackTypeOriginal?: string;
+	/** User agent that generated the report */
+	userAgent: string | null;
+	/** Arrival date of the original message */
+	arrivalDate: Date | null;
+	/** Source IP address of the original message */
+	sourceIp: string | null;
+	/** Original MAIL FROM address */
+	originalMailFrom: string | null;
+	/** Original RCPT TO addresses */
+	originalRcptTo: string[] | null;
+	/** Reporting MTA information */
+	reportingMta: ReportingMta | null;
+	/** Original envelope ID */
+	originalEnvelopeId: string | null;
+	/** Authentication results */
+	authenticationResults: string[] | null;
+	/** Reported domains */
+	reportedDomain: string[] | null;
+	/** Reported URIs */
+	reportedUri: string[] | null;
+	/** Number of incidents */
+	incidents: number;
+	/** Human-readable description */
+	humanReadable: string | null;
+	/** Original message content */
+	originalMessage: string | null;
+	/** Parsed headers from original message */
+	originalHeaders: Record<string, unknown> | null;
+	/** Raw feedback report content */
+	rawFeedbackReport: string | null;
+}
+
+/**
+ * Options for creating an ARF report
+ */
+export interface ArfCreateOptions {
+	/** Feedback type (abuse, fraud, virus, other) */
+	feedbackType: string;
+	/** User agent string */
+	userAgent: string;
+	/** From address for the report */
+	from: string;
+	/** To address for the report */
+	to: string;
+	/** Original message content */
+	originalMessage: string;
+	/** Human-readable description */
+	humanReadable?: string;
+	/** Source IP of original message */
+	sourceIp?: string;
+	/** Original MAIL FROM address */
+	originalMailFrom?: string;
+	/** Original RCPT TO addresses */
+	originalRcptTo?: string[];
+	/** Arrival date of original message */
+	arrivalDate?: Date;
+	/** Reporting MTA name */
+	reportingMta?: string;
+}
+
+/**
+ * ARF Parser class for parsing and creating ARF (Abuse Reporting Format) messages
+ */
+export declare class ArfParser {
+	/**
+	 * Check if a parsed email message is an ARF report
+	 * @param parsed - Parsed email message from mailparser
+	 * @returns True if message is ARF
+	 */
+	static isArfMessage(parsed: unknown): boolean;
+
+	/**
+	 * Parse an ARF message
+	 * @param source - Raw email message as Buffer or string
+	 * @returns Parsed ARF report
+	 * @throws Error if not a valid ARF message
+	 */
+	static parse(source: Buffer | string): Promise<ArfResult>;
+
+	/**
+	 * Try to parse a message as ARF, return null if not ARF
+	 * @param source - Raw email message as Buffer or string
+	 * @returns Parsed ARF report or null if not ARF
+	 */
+	static tryParse(source: Buffer | string): Promise<ArfResult | null>;
+
+	/**
+	 * Create an ARF report message
+	 * @param options - Report options
+	 * @returns ARF message as string
+	 * @throws Error if missing required fields
+	 */
+	static create(options: ArfCreateOptions): string;
+}
+
+export default ArfParser;

package/dist/types/auth.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Email Authentication Module Type Definitions
+ */
+
+export interface DkimResult {
+	results: DkimSignatureResult[];
+	status: AuthStatus;
+}
+
+export interface DkimSignatureResult {
+	signingDomain?: string;
+	selector?: string;
+	algo?: string;
+	format?: string;
+	signature?: string;
+	bodyHash?: string;
+	status: AuthStatus;
+}
+
+export interface SpfResult {
+	status: AuthStatus;
+	domain: string | null;
+	explanation?: string | null;
+}
+
+export interface DmarcResult {
+	status: AuthStatus;
+	policy: string | null;
+	domain: string | null;
+	p?: string | null;
+	sp?: string | null;
+	pct?: number | null;
+}
+
+export interface ArcResult {
+	status: AuthStatus;
+	chain: ArcChainEntry[];
+	i?: number | null;
+}
+
+export interface ArcChainEntry {
+	i: number;
+	cv: string;
+	status: AuthStatus;
+}
+
+export interface BimiResult {
+	status: AuthStatus;
+	location: string | null;
+	authority: string | null;
+	selector?: string | null;
+}
+
+export interface AuthStatus {
+	result: 'pass' | 'fail' | 'softfail' | 'neutral' | 'none' | 'temperror' | 'permerror';
+	comment?: string;
+}
+
+export interface AuthResult {
+	dkim: DkimResult;
+	spf: SpfResult;
+	dmarc: DmarcResult;
+	arc: ArcResult;
+	bimi: BimiResult;
+	receivedChain: ReceivedChainEntry[];
+	headers: Record<string, string>;
+}
+
+export interface ReceivedChainEntry {
+	from?: string;
+	by?: string;
+	with?: string;
+	id?: string;
+	for?: string;
+	date?: string;
+}
+
+export interface AuthOptions {
+	ip: string;
+	helo?: string;
+	mta?: string;
+	sender?: string;
+	resolver?: (name: string, type: string) => Promise<string[]>;
+	timeout?: number;
+}
+
+export interface AuthScoreWeights {
+	dkimPass?: number;
+	dkimFail?: number;
+	spfPass?: number;
+	spfFail?: number;
+	spfSoftfail?: number;
+	dmarcPass?: number;
+	dmarcFail?: number;
+	arcPass?: number;
+	arcFail?: number;
+}
+
+export interface AuthScoreResult {
+	score: number;
+	tests: string[];
+	details: {
+		dkim: string;
+		spf: string;
+		dmarc: string;
+		arc: string;
+	};
+}
+
+/**
+ * Authenticate an email message
+ */
+export function authenticate(
+	message: Buffer | string,
+	options?: AuthOptions
+): Promise<AuthResult>;
+
+/**
+ * Perform SPF check only
+ */
+export function checkSpf(
+	ip: string,
+	sender: string,
+	helo?: string,
+	options?: Partial<AuthOptions>
+): Promise<SpfResult>;
+
+/**
+ * Verify DKIM signature
+ */
+export function verifyDkim(
+	message: Buffer | string,
+	options?: Partial<AuthOptions>
+): Promise<DkimResult>;
+
+/**
+ * Calculate authentication score based on results
+ */
+export function calculateAuthScore(
+	authResult: AuthResult,
+	weights?: AuthScoreWeights
+): AuthScoreResult;
+
+/**
+ * Format authentication results as Authentication-Results header
+ */
+export function formatAuthResultsHeader(
+	authResult: AuthResult,
+	hostname?: string
+): string;
+
+/**
+ * Create a DNS resolver with timeout support
+ */
+export function createResolver(
+	timeout?: number
+): (name: string, type: string) => Promise<string[]>;

package/dist/types/get-attributes.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Get Attributes Module Type Definitions
+ * Based on Forward Email's get-attributes helper
+ */
+
+import type {AuthenticationResults} from './auth';
+
+/**
+ * Session information for attribute extraction
+ */
+export interface SessionInfo {
+	/** Resolved hostname of connecting client */
+	resolvedClientHostname?: string;
+	/** Root domain of resolved client hostname */
+	resolvedRootClientHostname?: string;
+	/** IP address of connecting client */
+	remoteAddress?: string;
+	/** Email address from From header */
+	originalFromAddress?: string;
+	/** Domain from From header */
+	originalFromAddressDomain?: string;
+	/** Root domain from From header */
+	originalFromAddressRootDomain?: string;
+	/** SMTP envelope */
+	envelope?: {
+		mailFrom?: {address: string};
+		rcptTo?: Array<{address: string}>;
+	};
+	/** Whether DKIM was aligned and passing */
+	hadAlignedAndPassingDKIM?: boolean;
+	/** SPF result for From header */
+	spfFromHeader?: {
+		status?: {result: string};
+	};
+	/** Whether client hostname matches From domain */
+	hasSameHostnameAsFrom?: boolean;
+	/** Whether sender is allowlisted */
+	isAllowlisted?: boolean;
+	/** Set of DKIM signing domains */
+	signingDomains?: Set<string>;
+	/** SPF domain */
+	spf?: {
+		domain?: string;
+	};
+	/** Whether message is potential phishing */
+	isPotentialPhishing?: boolean;
+}
+
+/**
+ * Options for attribute extraction
+ */
+export interface GetAttributesOptions {
+	/** Only return attributes that are verified and aligned */
+	isAligned?: boolean;
+	/** Authentication results from mailauth */
+	authResults?: AuthenticationResults | null;
+}
+
+/**
+ * Options for extractAttributes convenience function
+ */
+export interface ExtractAttributesOptions extends GetAttributesOptions {
+	/** Sender IP address */
+	senderIp?: string;
+	/** Sender hostname */
+	senderHostname?: string;
+}
+
+/**
+ * Result from extractAttributes
+ */
+export interface ExtractAttributesResult {
+	/** Array of unique attributes to check */
+	attributes: string[];
+	/** Session information built from parsed email */
+	session: SessionInfo;
+}
+
+/**
+ * Get attributes from an email for reputation checking
+ * @param parsed - Parsed email message
+ * @param session - Session information
+ * @param options - Options
+ * @returns Array of unique attributes to check
+ */
+export function getAttributes(
+	parsed: object,
+	session?: SessionInfo,
+	options?: GetAttributesOptions,
+): Promise<string[]>;
+
+/**
+ * Build session info from parsed email
+ * @param parsed - Parsed email
+ * @param existingSession - Existing session info to merge
+ * @returns Session information
+ */
+export function buildSessionFromParsed(
+	parsed: object,
+	existingSession?: Partial<SessionInfo>,
+): SessionInfo;
+
+/**
+ * Extract all checkable attributes from an email
+ * @param parsed - Parsed email message
+ * @param options - Options
+ * @returns Attributes and session info
+ */
+export function extractAttributes(
+	parsed: object,
+	options?: ExtractAttributesOptions,
+): Promise<ExtractAttributesResult>;
+
+/**
+ * Check and remove SRS (Sender Rewriting Scheme) encoding from an address
+ * @param address - Email address
+ * @returns Address with SRS removed
+ */
+export function checkSRS(address: string): string;
+
+/**
+ * Parse host/domain from an email address or domain string
+ * @param addressOrDomain - Email address or domain
+ * @returns Domain portion
+ */
+export function parseHostFromDomainOrAddress(addressOrDomain: string): string;
+
+/**
+ * Get root domain from a hostname
+ * @param hostname - Hostname
+ * @returns Root domain
+ */
+export function parseRootDomain(hostname: string): string;
+
+/**
+ * Parse addresses from a header value
+ * @param headerValue - Header value
+ * @returns Array of email addresses
+ */
+export function parseAddresses(headerValue: string | object | unknown[]): string[];
+
+/**
+ * Get header value from parsed email
+ * @param headers - Headers object
+ * @param name - Header name
+ * @returns Header value or null
+ */
+export function getHeaders(headers: object, name: string): string | null;

package/dist/types/index.d.ts

@@ -1,4 +1,14 @@
 import type {ParsedMail, Attachment} from 'mailparser';
+import type {AuthResult, AuthOptions, AuthScoreWeights, AuthScoreResult} from './auth.d.ts';
+import type {ReputationResult, ReputationOptions} from './reputation.d.ts';
+import type {SessionInfo, GetAttributesOptions, ExtractAttributesResult} from './get-attributes.d.ts';
+import type {ArbitraryResult, ArbitraryOptions} from './is-arbitrary.d.ts';
+
+// Re-export auth and reputation types
+export type {AuthResult, AuthOptions, AuthScoreWeights, AuthScoreResult} from './auth.d.ts';
+export type {ReputationResult, ReputationOptions} from './reputation.d.ts';
+export type {SessionInfo, GetAttributesOptions, ExtractAttributesResult} from './get-attributes.d.ts';
+export type {ArbitraryResult, ArbitraryOptions} from './is-arbitrary.d.ts';
 
 /**
  * ClamScan configuration options
@@ -68,6 +78,20 @@ export type SpamScannerConfig = {
 	strictIdnDetection?: boolean;
 	/** Enable token hashing */
 	hashTokens?: boolean;
+	/** Enable email authentication (DKIM/SPF/ARC/DMARC/BIMI) */
+	enableAuthentication?: boolean;
+	/** Authentication options */
+	authOptions?: AuthOptions;
+	/** Authentication score weights */
+	authScoreWeights?: AuthScoreWeights;
+	/** Enable Forward Email reputation checking */
+	enableReputation?: boolean;
+	/** Reputation API options */
+	reputationOptions?: ReputationOptions;
+	/** Enable arbitrary spam detection */
+	enableArbitraryDetection?: boolean;
+	/** Arbitrary spam score threshold */
+	arbitraryThreshold?: number;
 };
 
 /**
@@ -135,13 +159,19 @@ export type MacroResult = {
 };
 
 /**
- * Arbitrary detection result (e.g., GTUBE)
+ * Arbitrary detection result (e.g., GTUBE, spam patterns)
  */
 export type ArbitraryResult = {
 	/** Type of detection */
 	type: 'arbitrary';
+	/** Subtype of arbitrary detection */
+	subtype?: 'gtube' | 'pattern';
 	/** Description of the issue */
 	description: string;
+	/** Arbitrary spam score */
+	score?: number;
+	/** List of reasons why the message was flagged */
+	reasons?: string[];
 };
 
 /**
@@ -236,6 +266,29 @@ export type NsfwResult = {
 	description: string;
 };
 
+/**
+ * All scan results
+ */
+/**
+ * Extended authentication result with score
+ */
+export type AuthenticationResult = AuthResult & {
+	/** Authentication score */
+	score: AuthScoreResult;
+	/** Formatted Authentication-Results header */
+	authResultsHeader: string;
+};
+
+/**
+ * Extended reputation result with details
+ */
+export type ExtendedReputationResult = ReputationResult & {
+	/** Values that were checked */
+	checkedValues: string[];
+	/** Detailed results per value */
+	details: Record<string, ReputationResult>;
+};
+
 /**
  * All scan results
  */
@@ -260,6 +313,10 @@ export type ScanResults = {
 	toxicity: ToxicityResult[];
 	/** NSFW detection results */
 	nsfw: NsfwResult[];
+	/** Authentication results (if enabled) */
+	authentication?: AuthenticationResult | null;
+	/** Reputation results (if enabled) */
+	reputation?: ExtendedReputationResult | null;
 };
 
 /**
@@ -432,12 +489,32 @@ declare class SpamScanner {
 	 */
 	initializeRegex(): void;
 
+	/**
+	 * Scan options for per-scan configuration
+	 */
+	scanOptions?: {
+		/** Enable authentication for this scan */
+		enableAuthentication?: boolean;
+		/** Authentication options for this scan */
+		authOptions?: AuthOptions;
+		/** Enable reputation checking for this scan */
+		enableReputation?: boolean;
+		/** Reputation options for this scan */
+		reputationOptions?: ReputationOptions;
+	};
+
 	/**
 	 * Scan an email for spam
 	 * @param source - Email source (string, Uint8Array, or file path)
+	 * @param scanOptions - Optional per-scan configuration
 	 * @returns Scan result
 	 */
-	scan(source: ScanSource): Promise<ScanResult>;
+	scan(source: ScanSource, scanOptions?: {
+		enableAuthentication?: boolean;
+		authOptions?: AuthOptions;
+		enableReputation?: boolean;
+		reputationOptions?: ReputationOptions;
+	}): Promise<ScanResult>;
 
 	/**
 	 * Get tokens and parsed mail from source
@@ -616,6 +693,32 @@ declare class SpamScanner {
 	 * @returns IDN detector or null
 	 */
 	getIdnDetector(): Promise<EnhancedIdnDetector | undefined>;
+
+	/**
+	 * Get authentication results using mailauth
+	 * @param source - Email source
+	 * @param mail - Parsed mail object
+	 * @param options - Authentication options
+	 * @returns Authentication result or null
+	 */
+	getAuthenticationResults(
+		source: ScanSource,
+		mail: MailObject,
+		options?: AuthOptions
+	): Promise<AuthenticationResult | null>;
+
+	/**
+	 * Get reputation results from Forward Email API
+	 * @param mail - Parsed mail object
+	 * @param authOptions - Authentication options (for IP/sender)
+	 * @param reputationOptions - Reputation API options
+	 * @returns Reputation result or null
+	 */
+	getReputationResults(
+		mail: MailObject,
+		authOptions?: AuthOptions,
+		reputationOptions?: ReputationOptions
+	): Promise<ExtendedReputationResult | null>;
 }
 
 /**