import * as plugins from '../plugins.js'; import * as paths from '../paths.js'; import { logger } from '../logger.js'; // --------------------------------------------------------------------------- // IPC command type map — mirrors the methods in mailer-bin's management mode // --------------------------------------------------------------------------- interface IDkimVerificationResult { is_valid: boolean; domain: string | null; selector: string | null; status: string; details: string | null; } interface ISpfResult { result: string; domain: string; ip: string; explanation: string | null; } interface IDmarcResult { passed: boolean; policy: string; domain: string; dkim_result: string; spf_result: string; action: string; details: string | null; } interface IEmailSecurityResult { dkim: IDkimVerificationResult[]; spf: ISpfResult | null; dmarc: IDmarcResult | null; } interface IValidationResult { valid: boolean; formatValid: boolean; score: number; error: string | null; } interface IBounceDetection { bounce_type: string; category: string; } interface IReputationResult { ip: string; score: number; risk_level: string; ip_type: string; dnsbl_results: Array<{ server: string; listed: boolean; response: string | null }>; listed_count: number; total_checked: number; } interface IContentScanResult { threatScore: number; threatType: string | null; threatDetails: string | null; scannedElements: string[]; } interface IVersionInfo { bin: string; core: string; security: string; smtp: string; } // --- SMTP Server types --- interface ISmtpServerConfig { hostname: string; ports: number[]; securePort?: number; tlsCertPem?: string; tlsKeyPem?: string; maxMessageSize?: number; maxConnections?: number; maxRecipients?: number; connectionTimeoutSecs?: number; dataTimeoutSecs?: number; authEnabled?: boolean; maxAuthFailures?: number; socketTimeoutSecs?: number; processingTimeoutSecs?: number; rateLimits?: IRateLimitConfig; } interface IRateLimitConfig { maxConnectionsPerIp?: number; maxMessagesPerSender?: number; maxAuthFailuresPerIp?: number; windowSecs?: number; } interface IEmailData { type: 'inline' | 'file'; base64?: string; path?: string; } interface IEmailReceivedEvent { correlationId: string; sessionId: string; mailFrom: string; rcptTo: string[]; data: IEmailData; remoteAddr: string; clientHostname: string | null; secure: boolean; authenticatedUser: string | null; securityResults: any | null; } interface IAuthRequestEvent { correlationId: string; sessionId: string; username: string; password: string; remoteAddr: string; } /** * Type-safe command map for the mailer-bin IPC bridge. */ type TMailerCommands = { ping: { params: Record; result: { pong: boolean }; }; version: { params: Record; result: IVersionInfo; }; validateEmail: { params: { email: string }; result: IValidationResult; }; detectBounce: { params: { smtpResponse?: string; diagnosticCode?: string; statusCode?: string }; result: IBounceDetection; }; checkIpReputation: { params: { ip: string }; result: IReputationResult; }; verifyDkim: { params: { rawMessage: string }; result: IDkimVerificationResult[]; }; signDkim: { params: { rawMessage: string; domain: string; selector?: string; privateKey: string }; result: { header: string; signedMessage: string }; }; checkSpf: { params: { ip: string; heloDomain: string; hostname?: string; mailFrom: string }; result: ISpfResult; }; scanContent: { params: { subject?: string; textBody?: string; htmlBody?: string; attachmentNames?: string[]; }; result: IContentScanResult; }; verifyEmail: { params: { rawMessage: string; ip: string; heloDomain: string; hostname?: string; mailFrom: string; }; result: IEmailSecurityResult; }; startSmtpServer: { params: ISmtpServerConfig; result: { started: boolean }; }; stopSmtpServer: { params: Record; result: { stopped: boolean; wasRunning?: boolean }; }; emailProcessingResult: { params: { correlationId: string; accepted: boolean; smtpCode?: number; smtpMessage?: string; }; result: { resolved: boolean }; }; authResult: { params: { correlationId: string; success: boolean; message?: string; }; result: { resolved: boolean }; }; configureRateLimits: { params: IRateLimitConfig; result: { configured: boolean }; }; }; // --------------------------------------------------------------------------- // RustSecurityBridge — singleton wrapper around smartrust.RustBridge // --------------------------------------------------------------------------- /** * Bridge between TypeScript and the Rust `mailer-bin` binary. * * Uses `@push.rocks/smartrust` for JSON-over-stdin/stdout IPC. * Singleton — access via `RustSecurityBridge.getInstance()`. */ export class RustSecurityBridge { private static instance: RustSecurityBridge | null = null; private bridge: InstanceType>; private _running = false; private constructor() { this.bridge = new plugins.smartrust.RustBridge({ binaryName: 'mailer-bin', cliArgs: ['--management'], requestTimeoutMs: 30_000, readyTimeoutMs: 10_000, localPaths: [ plugins.path.join(paths.packageDir, 'dist_rust', 'mailer-bin'), plugins.path.join(paths.packageDir, 'rust', 'target', 'release', 'mailer-bin'), plugins.path.join(paths.packageDir, 'rust', 'target', 'debug', 'mailer-bin'), ], searchSystemPath: false, }); // Forward lifecycle events this.bridge.on('ready', () => { this._running = true; logger.log('info', 'Rust security bridge is ready'); }); this.bridge.on('exit', (code: number | null, signal: string | null) => { this._running = false; logger.log('warn', `Rust security bridge exited (code=${code}, signal=${signal})`); }); this.bridge.on('stderr', (line: string) => { logger.log('debug', `[rust-bridge] ${line}`); }); } /** Get or create the singleton instance. */ public static getInstance(): RustSecurityBridge { if (!RustSecurityBridge.instance) { RustSecurityBridge.instance = new RustSecurityBridge(); } return RustSecurityBridge.instance; } /** Whether the Rust process is currently running and accepting commands. */ public get running(): boolean { return this._running; } // ----------------------------------------------------------------------- // Lifecycle // ----------------------------------------------------------------------- /** * Spawn the Rust binary and wait for the ready signal. * @returns `true` if the binary started successfully, `false` otherwise. */ public async start(): Promise { if (this._running) { return true; } try { const ok = await this.bridge.spawn(); this._running = ok; if (ok) { logger.log('info', 'Rust security bridge started'); } else { logger.log('warn', 'Rust security bridge failed to start (binary not found or timeout)'); } return ok; } catch (err) { logger.log('error', `Failed to start Rust security bridge: ${(err as Error).message}`); return false; } } /** Kill the Rust process. */ public async stop(): Promise { if (!this._running) { return; } try { this.bridge.kill(); this._running = false; logger.log('info', 'Rust security bridge stopped'); } catch (err) { logger.log('error', `Error stopping Rust security bridge: ${(err as Error).message}`); } } // ----------------------------------------------------------------------- // Commands — thin typed wrappers over sendCommand // ----------------------------------------------------------------------- /** Ping the Rust process. */ public async ping(): Promise { const res = await this.bridge.sendCommand('ping', {} as any); return res?.pong === true; } /** Get version information for all Rust crates. */ public async getVersion(): Promise { return this.bridge.sendCommand('version', {} as any); } /** Validate an email address. */ public async validateEmail(email: string): Promise { return this.bridge.sendCommand('validateEmail', { email }); } /** Detect bounce type from SMTP response / diagnostic code. */ public async detectBounce(opts: { smtpResponse?: string; diagnosticCode?: string; statusCode?: string; }): Promise { return this.bridge.sendCommand('detectBounce', opts); } /** Scan email content for threats (phishing, spam, malware, etc.). */ public async scanContent(opts: { subject?: string; textBody?: string; htmlBody?: string; attachmentNames?: string[]; }): Promise { return this.bridge.sendCommand('scanContent', opts); } /** Check IP reputation via DNSBL. */ public async checkIpReputation(ip: string): Promise { return this.bridge.sendCommand('checkIpReputation', { ip }); } /** Verify DKIM signatures on a raw email message. */ public async verifyDkim(rawMessage: string): Promise { return this.bridge.sendCommand('verifyDkim', { rawMessage }); } /** Sign an email with DKIM. */ public async signDkim(opts: { rawMessage: string; domain: string; selector?: string; privateKey: string; }): Promise<{ header: string; signedMessage: string }> { return this.bridge.sendCommand('signDkim', opts); } /** Check SPF for a sender. */ public async checkSpf(opts: { ip: string; heloDomain: string; hostname?: string; mailFrom: string; }): Promise { return this.bridge.sendCommand('checkSpf', opts); } /** * Compound email security verification: DKIM + SPF + DMARC in one IPC call. * * This is the preferred method for inbound email verification — it avoids * 3 sequential round-trips and correctly passes raw mail-auth types internally. */ public async verifyEmail(opts: { rawMessage: string; ip: string; heloDomain: string; hostname?: string; mailFrom: string; }): Promise { return this.bridge.sendCommand('verifyEmail', opts); } // ----------------------------------------------------------------------- // SMTP Server lifecycle // ----------------------------------------------------------------------- /** * Start the Rust SMTP server. * The server will listen on the configured ports and emit events for * emailReceived and authRequest that must be handled by the caller. */ public async startSmtpServer(config: ISmtpServerConfig): Promise { const result = await this.bridge.sendCommand('startSmtpServer', config); return result?.started === true; } /** Stop the Rust SMTP server. */ public async stopSmtpServer(): Promise { await this.bridge.sendCommand('stopSmtpServer', {} as any); } /** * Send the result of email processing back to the Rust SMTP server. * This resolves a pending correlation-ID callback, allowing the Rust * server to send the SMTP response to the client. */ public async sendEmailProcessingResult(opts: { correlationId: string; accepted: boolean; smtpCode?: number; smtpMessage?: string; }): Promise { await this.bridge.sendCommand('emailProcessingResult', opts); } /** * Send the result of authentication validation back to the Rust SMTP server. */ public async sendAuthResult(opts: { correlationId: string; success: boolean; message?: string; }): Promise { await this.bridge.sendCommand('authResult', opts); } /** Update rate limit configuration at runtime. */ public async configureRateLimits(config: IRateLimitConfig): Promise { await this.bridge.sendCommand('configureRateLimits', config); } // ----------------------------------------------------------------------- // Event registration — delegates to the underlying bridge EventEmitter // ----------------------------------------------------------------------- /** * Register a handler for emailReceived events from the Rust SMTP server. * These events fire when a complete email has been received and needs processing. */ public onEmailReceived(handler: (data: IEmailReceivedEvent) => void): void { this.bridge.on('management:emailReceived', handler); } /** * Register a handler for authRequest events from the Rust SMTP server. * The handler must call sendAuthResult() with the correlationId. */ public onAuthRequest(handler: (data: IAuthRequestEvent) => void): void { this.bridge.on('management:authRequest', handler); } /** Remove an emailReceived event handler. */ public offEmailReceived(handler: (data: IEmailReceivedEvent) => void): void { this.bridge.off('management:emailReceived', handler); } /** Remove an authRequest event handler. */ public offAuthRequest(handler: (data: IAuthRequestEvent) => void): void { this.bridge.off('management:authRequest', handler); } } // Re-export interfaces for consumers export type { IDkimVerificationResult, ISpfResult, IDmarcResult, IEmailSecurityResult, IValidationResult, IBounceDetection, IContentScanResult, IReputationResult as IRustReputationResult, IVersionInfo, ISmtpServerConfig, IRateLimitConfig, IEmailData, IEmailReceivedEvent, IAuthRequestEvent, };