@serve.zone/dcrouter 11.0.22 → 11.0.23

package/dist_ts/security/classes.ipreputationchecker.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Reputation check result information
+ */
+export interface IReputationResult {
+    score: number;
+    isSpam: boolean;
+    isProxy: boolean;
+    isTor: boolean;
+    isVPN: boolean;
+    country?: string;
+    asn?: string;
+    org?: string;
+    blacklists?: string[];
+    timestamp: number;
+    error?: string;
+}
+/**
+ * Reputation threshold scores
+ */
+export declare enum ReputationThreshold {
+    HIGH_RISK = 20,// Score below this is considered high risk
+    MEDIUM_RISK = 50,// Score below this is considered medium risk
+    LOW_RISK = 80
+}
+/**
+ * IP type classifications
+ */
+export declare enum IPType {
+    RESIDENTIAL = "residential",
+    DATACENTER = "datacenter",
+    PROXY = "proxy",
+    TOR = "tor",
+    VPN = "vpn",
+    UNKNOWN = "unknown"
+}
+/**
+ * Options for the IP Reputation Checker
+ */
+export interface IIPReputationOptions {
+    maxCacheSize?: number;
+    cacheTTL?: number;
+    dnsblServers?: string[];
+    highRiskThreshold?: number;
+    mediumRiskThreshold?: number;
+    lowRiskThreshold?: number;
+    enableLocalCache?: boolean;
+    enableDNSBL?: boolean;
+    enableIPInfo?: boolean;
+}
+/**
+ * Class for checking IP reputation of inbound email senders
+ */
+export declare class IPReputationChecker {
+    private static instance;
+    private reputationCache;
+    private options;
+    private storageManager?;
+    private saveCacheTimer;
+    private static readonly SAVE_CACHE_DEBOUNCE_MS;
+    private static readonly DEFAULT_DNSBL_SERVERS;
+    private static readonly DEFAULT_OPTIONS;
+    /**
+     * Constructor for IPReputationChecker
+     * @param options Configuration options
+     * @param storageManager Optional StorageManager instance for persistence
+     */
+    constructor(options?: IIPReputationOptions, storageManager?: any);
+    /**
+     * Get the singleton instance of the checker
+     * @param options Configuration options
+     * @param storageManager Optional StorageManager instance for persistence
+     * @returns Singleton instance
+     */
+    static getInstance(options?: IIPReputationOptions, storageManager?: any): IPReputationChecker;
+    /**
+     * Reset the singleton instance (for shutdown/testing)
+     */
+    static resetInstance(): void;
+    /**
+     * Check an IP address's reputation
+     * @param ip IP address to check
+     * @returns Reputation check result
+     */
+    checkReputation(ip: string): Promise<IReputationResult>;
+    /**
+     * Check an IP against DNS blacklists
+     * @param ip IP address to check
+     * @returns DNSBL check results
+     */
+    private checkDNSBL;
+    /**
+     * Get information about an IP address
+     * @param ip IP address to check
+     * @returns IP information
+     */
+    private getIPInfo;
+    /**
+     * Simplified method to determine country from IP
+     * In a real implementation, this would use a geolocation database or service
+     * @param ip IP address
+     * @returns Country code
+     */
+    private determineCountry;
+    /**
+     * Simplified method to determine organization from IP
+     * In a real implementation, this would use an IP-to-org database or service
+     * @param ip IP address
+     * @returns Organization name
+     */
+    private determineOrg;
+    /**
+     * Reverse an IP address for DNSBL lookups (e.g., 1.2.3.4 -> 4.3.2.1)
+     * @param ip IP address to reverse
+     * @returns Reversed IP for DNSBL queries
+     */
+    private reverseIP;
+    /**
+     * Create an error result for when reputation check fails
+     * @param ip IP address
+     * @param errorMessage Error message
+     * @returns Error result
+     */
+    private createErrorResult;
+    /**
+     * Validate IP address format
+     * @param ip IP address to validate
+     * @returns Whether the IP is valid
+     */
+    private isValidIPAddress;
+    /**
+     * Log reputation check to security logger
+     * @param ip IP address
+     * @param result Reputation result
+     */
+    private logReputationCheck;
+    /**
+     * Schedule a debounced cache save (at most once per SAVE_CACHE_DEBOUNCE_MS)
+     */
+    private debouncedSaveCache;
+    /**
+     * Save cache to disk or storage manager
+     */
+    private saveCache;
+    /**
+     * Load cache from disk or storage manager
+     */
+    private loadCache;
+    /**
+     * Get the risk level for a reputation score
+     * @param score Reputation score (0-100)
+     * @returns Risk level description
+     */
+    static getRiskLevel(score: number): 'high' | 'medium' | 'low' | 'trusted';
+    /**
+     * Update the storage manager after instantiation
+     * This is useful when the storage manager is not available at construction time
+     * @param storageManager The StorageManager instance to use
+     */
+    updateStorageManager(storageManager: any): void;
+}