spamscanner 6.0.0 → 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/enhanced-idn-detector.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Enhanced IDN Detector options
+ */
+export type EnhancedIdnDetectorOptions = {
+	/** Enable strict mode */
+	strictMode?: boolean;
+	/** Enable domain whitelist */
+	enableWhitelist?: boolean;
+	/** Enable brand protection */
+	enableBrandProtection?: boolean;
+	/** Enable context analysis */
+	enableContextAnalysis?: boolean;
+	/** Maximum similarity threshold (0-1) */
+	maxSimilarityThreshold?: number;
+	/** Minimum domain age in days */
+	minDomainAge?: number;
+};
+
+/**
+ * Context for IDN analysis
+ */
+export type IdnAnalysisContext = {
+	/** Email content */
+	emailContent?: string;
+	/** Display text (if different from domain) */
+	displayText?: string | undefined;
+	/** Sender reputation (0-1) */
+	senderReputation?: number;
+	/** Email headers */
+	emailHeaders?: Map<string, unknown> | Record<string, unknown>;
+};
+
+/**
+ * IDN analysis result
+ */
+export type IdnAnalysisResult = {
+	/** The domain analyzed */
+	domain: string;
+	/** Whether the domain is an IDN */
+	isIdn: boolean;
+	/** Risk score (0-1) */
+	riskScore: number;
+	/** Risk factors identified */
+	riskFactors: string[];
+	/** Recommendations */
+	recommendations: string[];
+	/** Confidence level (0-1) */
+	confidence: number;
+};
+
+/**
+ * Confusable character analysis result
+ */
+export type ConfusableAnalysis = {
+	/** Risk score contribution */
+	score: number;
+	/** Risk factors identified */
+	factors: string[];
+};
+
+/**
+ * Brand similarity analysis result
+ */
+export type BrandAnalysis = {
+	/** Risk score contribution */
+	score: number;
+	/** Risk factors identified */
+	factors: string[];
+};
+
+/**
+ * Script mixing analysis result
+ */
+export type ScriptAnalysis = {
+	/** Risk score contribution */
+	score: number;
+	/** Risk factors identified */
+	factors: string[];
+};
+
+/**
+ * Context analysis result
+ */
+export type ContextAnalysis = {
+	/** Risk score contribution */
+	score: number;
+	/** Risk factors identified */
+	factors: string[];
+};
+
+/**
+ * Punycode analysis result
+ */
+export type PunycodeAnalysis = {
+	/** Risk score contribution */
+	score: number;
+	/** Risk factors identified */
+	factors: string[];
+};
+
+/**
+ * Enhanced IDN Homograph Attack Detector
+ */
+declare class EnhancedIdnDetector {
+	/** Detector options */
+	options: EnhancedIdnDetectorOptions & {
+		strictMode: boolean;
+		enableWhitelist: boolean;
+		enableBrandProtection: boolean;
+		enableContextAnalysis: boolean;
+		maxSimilarityThreshold: number;
+		minDomainAge: number;
+	};
+
+	/** Analysis cache */
+	cache: Map<string, IdnAnalysisResult>;
+
+	/**
+	 * Create a new EnhancedIdnDetector instance
+	 * @param options - Configuration options
+	 */
+	constructor(options?: EnhancedIdnDetectorOptions);
+
+	/**
+	 * Detect homograph attack in a domain
+	 * @param domain - Domain to analyze
+	 * @param context - Analysis context
+	 * @returns Analysis result
+	 */
+	detectHomographAttack(domain: string, context?: IdnAnalysisContext): IdnAnalysisResult;
+
+	/**
+	 * Comprehensive analysis of a domain
+	 * @param domain - Domain to analyze
+	 * @param context - Analysis context
+	 * @returns Analysis result
+	 */
+	analyzeComprehensive(domain: string, context: IdnAnalysisContext): IdnAnalysisResult;
+
+	/**
+	 * Check if domain contains IDN characters
+	 * @param domain - Domain to check
+	 * @returns Whether the domain is an IDN
+	 */
+	isIdnDomain(domain: string): boolean;
+
+	/**
+	 * Check if domain is whitelisted
+	 * @param domain - Domain to check
+	 * @returns Whether the domain is whitelisted
+	 */
+	isWhitelisted(domain: string): boolean;
+
+	/**
+	 * Analyze confusable characters in domain
+	 * @param domain - Domain to analyze
+	 * @returns Confusable analysis result
+	 */
+	analyzeConfusableCharacters(domain: string): ConfusableAnalysis;
+
+	/**
+	 * Analyze brand similarity
+	 * @param domain - Domain to analyze
+	 * @returns Brand analysis result
+	 */
+	analyzeBrandSimilarity(domain: string): BrandAnalysis;
+
+	/**
+	 * Analyze script mixing patterns
+	 * @param domain - Domain to analyze
+	 * @returns Script analysis result
+	 */
+	analyzeScriptMixing(domain: string): ScriptAnalysis;
+
+	/**
+	 * Analyze context for additional risk factors
+	 * @param domain - Domain to analyze
+	 * @param context - Analysis context
+	 * @returns Context analysis result
+	 */
+	analyzeContext(domain: string, context: IdnAnalysisContext): ContextAnalysis;
+
+	/**
+	 * Analyze punycode domain
+	 * @param domain - Domain to analyze
+	 * @returns Punycode analysis result
+	 */
+	analyzePunycode(domain: string): PunycodeAnalysis;
+
+	/**
+	 * Normalize domain for comparison
+	 * @param domain - Domain to normalize
+	 * @returns Normalized domain
+	 */
+	normalizeDomain(domain: string): string;
+
+	/**
+	 * Calculate string similarity using Levenshtein distance
+	 * @param string1 - First string
+	 * @param string2 - Second string
+	 * @returns Similarity score (0-1)
+	 */
+	calculateSimilarity(string1: string, string2: string): number;
+
+	/**
+	 * Detect scripts used in domain
+	 * @param domain - Domain to analyze
+	 * @returns Set of detected scripts
+	 */
+	detectScripts(domain: string): Set<string>;
+
+	/**
+	 * Decode punycode domain
+	 * @param domain - Domain to decode
+	 * @returns Decoded domain
+	 */
+	decodePunycode(domain: string): string;
+
+	/**
+	 * Generate recommendations based on analysis
+	 * @param analysis - Analysis result
+	 * @returns Array of recommendations
+	 */
+	generateRecommendations(analysis: IdnAnalysisResult): string[];
+
+	/**
+	 * Get cache key for analysis
+	 * @param domain - Domain
+	 * @param context - Analysis context
+	 * @returns Cache key
+	 */
+	getCacheKey(domain: string, context: IdnAnalysisContext): string;
+}
+
+export default EnhancedIdnDetector;
+export {EnhancedIdnDetector};

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;