610 lines
12 KiB
TypeScript
610 lines
12 KiB
TypeScript
/**
|
|
* SMTP Server Module Interfaces
|
|
* This file contains all interfaces for the refactored SMTP server implementation
|
|
*/
|
|
|
|
import * as plugins from '../../../plugins.js';
|
|
import type { Email } from '../../core/classes.email.js';
|
|
import type { UnifiedEmailServer } from '../../routing/classes.unified.email.server.js';
|
|
import { SmtpState } from '../interfaces.js';
|
|
|
|
// Define all needed types/interfaces directly in this file
|
|
export { SmtpState };
|
|
|
|
// Define EmailProcessingMode directly in this file
|
|
export type EmailProcessingMode = 'forward' | 'mta' | 'process';
|
|
|
|
/**
|
|
* Envelope recipient information
|
|
*/
|
|
export interface IEnvelopeRecipient {
|
|
/**
|
|
* Email address of the recipient
|
|
*/
|
|
address: string;
|
|
|
|
/**
|
|
* Additional SMTP command arguments
|
|
*/
|
|
args: Record<string, string>;
|
|
}
|
|
|
|
/**
|
|
* SMTP session envelope information
|
|
*/
|
|
export interface ISmtpEnvelope {
|
|
/**
|
|
* Envelope sender (MAIL FROM) information
|
|
*/
|
|
mailFrom: {
|
|
/**
|
|
* Email address of the sender
|
|
*/
|
|
address: string;
|
|
|
|
/**
|
|
* Additional SMTP command arguments
|
|
*/
|
|
args: Record<string, string>;
|
|
};
|
|
|
|
/**
|
|
* Envelope recipients (RCPT TO) information
|
|
*/
|
|
rcptTo: IEnvelopeRecipient[];
|
|
}
|
|
|
|
/**
|
|
* SMTP Session interface - represents an active SMTP connection
|
|
*/
|
|
export interface ISmtpSession {
|
|
/**
|
|
* Unique session identifier
|
|
*/
|
|
id: string;
|
|
|
|
/**
|
|
* Current session state in the SMTP conversation
|
|
*/
|
|
state: SmtpState;
|
|
|
|
/**
|
|
* Hostname provided by the client in EHLO/HELO command
|
|
*/
|
|
clientHostname: string;
|
|
|
|
/**
|
|
* MAIL FROM email address (legacy format)
|
|
*/
|
|
mailFrom: string;
|
|
|
|
/**
|
|
* RCPT TO email addresses (legacy format)
|
|
*/
|
|
rcptTo: string[];
|
|
|
|
/**
|
|
* Raw email data being received
|
|
*/
|
|
emailData: string;
|
|
|
|
/**
|
|
* Chunks of email data for more efficient buffer management
|
|
*/
|
|
emailDataChunks?: string[];
|
|
|
|
/**
|
|
* Whether the connection is using TLS
|
|
*/
|
|
useTLS: boolean;
|
|
|
|
/**
|
|
* Whether the connection has ended
|
|
*/
|
|
connectionEnded: boolean;
|
|
|
|
/**
|
|
* Remote IP address of the client
|
|
*/
|
|
remoteAddress: string;
|
|
|
|
/**
|
|
* Whether the connection is secure (TLS)
|
|
*/
|
|
secure: boolean;
|
|
|
|
/**
|
|
* Whether the client has been authenticated
|
|
*/
|
|
authenticated: boolean;
|
|
|
|
/**
|
|
* SMTP envelope information (structured format)
|
|
*/
|
|
envelope: ISmtpEnvelope;
|
|
|
|
/**
|
|
* Email processing mode to use for this session
|
|
*/
|
|
processingMode?: EmailProcessingMode;
|
|
|
|
/**
|
|
* Timestamp of last activity for session timeout tracking
|
|
*/
|
|
lastActivity?: number;
|
|
|
|
/**
|
|
* Timeout ID for DATA command timeout
|
|
*/
|
|
dataTimeoutId?: NodeJS.Timeout;
|
|
}
|
|
|
|
/**
|
|
* SMTP authentication data
|
|
*/
|
|
export interface ISmtpAuth {
|
|
/**
|
|
* Authentication method used
|
|
*/
|
|
method: 'PLAIN' | 'LOGIN' | 'OAUTH2' | string;
|
|
|
|
/**
|
|
* Username for authentication
|
|
*/
|
|
username: string;
|
|
|
|
/**
|
|
* Password or token for authentication
|
|
*/
|
|
password: string;
|
|
}
|
|
|
|
/**
|
|
* SMTP server options
|
|
*/
|
|
export interface ISmtpServerOptions {
|
|
/**
|
|
* Port to listen on
|
|
*/
|
|
port: number;
|
|
|
|
/**
|
|
* TLS private key (PEM format)
|
|
*/
|
|
key: string;
|
|
|
|
/**
|
|
* TLS certificate (PEM format)
|
|
*/
|
|
cert: string;
|
|
|
|
/**
|
|
* Server hostname for SMTP banner
|
|
*/
|
|
hostname?: string;
|
|
|
|
/**
|
|
* Host address to bind to (defaults to all interfaces)
|
|
*/
|
|
host?: string;
|
|
|
|
/**
|
|
* Secure port for dedicated TLS connections
|
|
*/
|
|
securePort?: number;
|
|
|
|
/**
|
|
* CA certificates for TLS (PEM format)
|
|
*/
|
|
ca?: string;
|
|
|
|
/**
|
|
* Maximum size of messages in bytes
|
|
*/
|
|
maxSize?: number;
|
|
|
|
/**
|
|
* Maximum number of concurrent connections
|
|
*/
|
|
maxConnections?: number;
|
|
|
|
/**
|
|
* Authentication options
|
|
*/
|
|
auth?: {
|
|
/**
|
|
* Whether authentication is required
|
|
*/
|
|
required: boolean;
|
|
|
|
/**
|
|
* Allowed authentication methods
|
|
*/
|
|
methods: ('PLAIN' | 'LOGIN' | 'OAUTH2')[];
|
|
};
|
|
|
|
/**
|
|
* Socket timeout in milliseconds (default: 5 minutes / 300000ms)
|
|
*/
|
|
socketTimeout?: number;
|
|
|
|
/**
|
|
* Initial connection timeout in milliseconds (default: 30 seconds / 30000ms)
|
|
*/
|
|
connectionTimeout?: number;
|
|
|
|
/**
|
|
* Interval for checking idle sessions in milliseconds (default: 5 seconds / 5000ms)
|
|
* For testing, can be set lower (e.g. 1000ms) to detect timeouts more quickly
|
|
*/
|
|
cleanupInterval?: number;
|
|
|
|
/**
|
|
* Maximum number of recipients allowed per message (default: 100)
|
|
*/
|
|
maxRecipients?: number;
|
|
|
|
/**
|
|
* Maximum message size in bytes (default: 10MB / 10485760 bytes)
|
|
* This is advertised in the EHLO SIZE extension
|
|
*/
|
|
size?: number;
|
|
|
|
/**
|
|
* Timeout for the DATA command in milliseconds (default: 60000ms / 1 minute)
|
|
* This controls how long to wait for the complete email data
|
|
*/
|
|
dataTimeout?: number;
|
|
}
|
|
|
|
/**
|
|
* Result of SMTP transaction
|
|
*/
|
|
export interface ISmtpTransactionResult {
|
|
/**
|
|
* Whether the transaction was successful
|
|
*/
|
|
success: boolean;
|
|
|
|
/**
|
|
* Error message if failed
|
|
*/
|
|
error?: string;
|
|
|
|
/**
|
|
* Message ID if successful
|
|
*/
|
|
messageId?: string;
|
|
|
|
/**
|
|
* Resulting email if successful
|
|
*/
|
|
email?: Email;
|
|
}
|
|
|
|
/**
|
|
* Interface for SMTP session events
|
|
* These events are emitted by the session manager
|
|
*/
|
|
export interface ISessionEvents {
|
|
created: (session: ISmtpSession, socket: plugins.net.Socket | plugins.tls.TLSSocket) => void;
|
|
stateChanged: (session: ISmtpSession, previousState: SmtpState, newState: SmtpState) => void;
|
|
timeout: (session: ISmtpSession, socket: plugins.net.Socket | plugins.tls.TLSSocket) => void;
|
|
completed: (session: ISmtpSession, socket: plugins.net.Socket | plugins.tls.TLSSocket) => void;
|
|
error: (session: ISmtpSession, error: Error) => void;
|
|
}
|
|
|
|
/**
|
|
* Interface for the session manager component
|
|
*/
|
|
export interface ISessionManager {
|
|
/**
|
|
* Creates a new session for a socket connection
|
|
*/
|
|
createSession(socket: plugins.net.Socket | plugins.tls.TLSSocket, secure: boolean): ISmtpSession;
|
|
|
|
/**
|
|
* Updates the session state
|
|
*/
|
|
updateSessionState(session: ISmtpSession, newState: SmtpState): void;
|
|
|
|
/**
|
|
* Updates the session's last activity timestamp
|
|
*/
|
|
updateSessionActivity(session: ISmtpSession): void;
|
|
|
|
/**
|
|
* Removes a session
|
|
*/
|
|
removeSession(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
|
|
|
|
/**
|
|
* Gets a session for a socket
|
|
*/
|
|
getSession(socket: plugins.net.Socket | plugins.tls.TLSSocket): ISmtpSession | undefined;
|
|
|
|
/**
|
|
* Cleans up idle sessions
|
|
*/
|
|
cleanupIdleSessions(): void;
|
|
|
|
/**
|
|
* Gets the current number of active sessions
|
|
*/
|
|
getSessionCount(): number;
|
|
|
|
/**
|
|
* Clears all sessions (used when shutting down)
|
|
*/
|
|
clearAllSessions(): void;
|
|
|
|
/**
|
|
* Register an event listener
|
|
*/
|
|
on<K extends keyof ISessionEvents>(event: K, listener: ISessionEvents[K]): void;
|
|
|
|
/**
|
|
* Remove an event listener
|
|
*/
|
|
off<K extends keyof ISessionEvents>(event: K, listener: ISessionEvents[K]): void;
|
|
}
|
|
|
|
/**
|
|
* Interface for the connection manager component
|
|
*/
|
|
export interface IConnectionManager {
|
|
/**
|
|
* Handle a new connection
|
|
*/
|
|
handleNewConnection(socket: plugins.net.Socket): void;
|
|
|
|
/**
|
|
* Handle a new secure TLS connection
|
|
*/
|
|
handleNewSecureConnection(socket: plugins.tls.TLSSocket): void;
|
|
|
|
/**
|
|
* Set up event handlers for a socket
|
|
*/
|
|
setupSocketEventHandlers(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
|
|
|
|
/**
|
|
* Get the current connection count
|
|
*/
|
|
getConnectionCount(): number;
|
|
|
|
/**
|
|
* Check if the server has reached the maximum number of connections
|
|
*/
|
|
hasReachedMaxConnections(): boolean;
|
|
|
|
/**
|
|
* Close all active connections
|
|
*/
|
|
closeAllConnections(): void;
|
|
}
|
|
|
|
/**
|
|
* Interface for the command handler component
|
|
*/
|
|
export interface ICommandHandler {
|
|
/**
|
|
* Process a command from the client
|
|
*/
|
|
processCommand(socket: plugins.net.Socket | plugins.tls.TLSSocket, commandLine: string): void;
|
|
|
|
/**
|
|
* Send a response to the client
|
|
*/
|
|
sendResponse(socket: plugins.net.Socket | plugins.tls.TLSSocket, response: string): void;
|
|
|
|
/**
|
|
* Handle EHLO command
|
|
*/
|
|
handleEhlo(socket: plugins.net.Socket | plugins.tls.TLSSocket, clientHostname: string): void;
|
|
|
|
/**
|
|
* Handle MAIL FROM command
|
|
*/
|
|
handleMailFrom(socket: plugins.net.Socket | plugins.tls.TLSSocket, args: string): void;
|
|
|
|
/**
|
|
* Handle RCPT TO command
|
|
*/
|
|
handleRcptTo(socket: plugins.net.Socket | plugins.tls.TLSSocket, args: string): void;
|
|
|
|
/**
|
|
* Handle DATA command
|
|
*/
|
|
handleData(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
|
|
|
|
/**
|
|
* Handle RSET command
|
|
*/
|
|
handleRset(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
|
|
|
|
/**
|
|
* Handle NOOP command
|
|
*/
|
|
handleNoop(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
|
|
|
|
/**
|
|
* Handle QUIT command
|
|
*/
|
|
handleQuit(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
|
|
}
|
|
|
|
/**
|
|
* Interface for the data handler component
|
|
*/
|
|
export interface IDataHandler {
|
|
/**
|
|
* Process incoming email data
|
|
*/
|
|
processEmailData(socket: plugins.net.Socket | plugins.tls.TLSSocket, data: string): Promise<void>;
|
|
|
|
/**
|
|
* Process a complete email
|
|
*/
|
|
processEmail(session: ISmtpSession): Promise<ISmtpTransactionResult>;
|
|
|
|
/**
|
|
* Save an email to disk
|
|
*/
|
|
saveEmail(session: ISmtpSession): void;
|
|
|
|
/**
|
|
* Parse an email into an Email object
|
|
*/
|
|
parseEmail(session: ISmtpSession): Promise<Email>;
|
|
}
|
|
|
|
/**
|
|
* Interface for the TLS handler component
|
|
*/
|
|
export interface ITlsHandler {
|
|
/**
|
|
* Handle STARTTLS command
|
|
*/
|
|
handleStartTls(socket: plugins.net.Socket | plugins.tls.TLSSocket): void;
|
|
|
|
/**
|
|
* Upgrade a connection to TLS
|
|
*/
|
|
startTLS(socket: plugins.net.Socket): void;
|
|
|
|
/**
|
|
* Create a secure server
|
|
*/
|
|
createSecureServer(): plugins.tls.Server | undefined;
|
|
|
|
/**
|
|
* Check if TLS is enabled
|
|
*/
|
|
isTlsEnabled(): boolean;
|
|
}
|
|
|
|
/**
|
|
* Interface for the security handler component
|
|
*/
|
|
export interface ISecurityHandler {
|
|
/**
|
|
* Check IP reputation for a connection
|
|
*/
|
|
checkIpReputation(socket: plugins.net.Socket | plugins.tls.TLSSocket): Promise<boolean>;
|
|
|
|
/**
|
|
* Validate an email address
|
|
*/
|
|
isValidEmail(email: string): boolean;
|
|
|
|
/**
|
|
* Validate authentication credentials
|
|
*/
|
|
authenticate(session: ISmtpSession, username: string, password: string, method: string): Promise<boolean>;
|
|
|
|
/**
|
|
* Log a security event
|
|
*/
|
|
logSecurityEvent(event: string, level: string, message: string, details: Record<string, any>): void;
|
|
}
|
|
|
|
/**
|
|
* Interface for the SMTP server component
|
|
*/
|
|
export interface ISmtpServer {
|
|
/**
|
|
* Start the SMTP server
|
|
*/
|
|
listen(): Promise<void>;
|
|
|
|
/**
|
|
* Stop the SMTP server
|
|
*/
|
|
close(): Promise<void>;
|
|
|
|
/**
|
|
* Get the session manager
|
|
*/
|
|
getSessionManager(): ISessionManager;
|
|
|
|
/**
|
|
* Get the connection manager
|
|
*/
|
|
getConnectionManager(): IConnectionManager;
|
|
|
|
/**
|
|
* Get the command handler
|
|
*/
|
|
getCommandHandler(): ICommandHandler;
|
|
|
|
/**
|
|
* Get the data handler
|
|
*/
|
|
getDataHandler(): IDataHandler;
|
|
|
|
/**
|
|
* Get the TLS handler
|
|
*/
|
|
getTlsHandler(): ITlsHandler;
|
|
|
|
/**
|
|
* Get the security handler
|
|
*/
|
|
getSecurityHandler(): ISecurityHandler;
|
|
|
|
/**
|
|
* Get the server options
|
|
*/
|
|
getOptions(): ISmtpServerOptions;
|
|
|
|
/**
|
|
* Get the email server reference
|
|
*/
|
|
getEmailServer(): UnifiedEmailServer;
|
|
}
|
|
|
|
/**
|
|
* Configuration for creating an SMTP server
|
|
*/
|
|
export interface ISmtpServerConfig {
|
|
/**
|
|
* Email server reference
|
|
*/
|
|
emailServer: UnifiedEmailServer;
|
|
|
|
/**
|
|
* SMTP server options
|
|
*/
|
|
options: ISmtpServerOptions;
|
|
|
|
/**
|
|
* Optional session manager
|
|
*/
|
|
sessionManager?: ISessionManager;
|
|
|
|
/**
|
|
* Optional connection manager
|
|
*/
|
|
connectionManager?: IConnectionManager;
|
|
|
|
/**
|
|
* Optional command handler
|
|
*/
|
|
commandHandler?: ICommandHandler;
|
|
|
|
/**
|
|
* Optional data handler
|
|
*/
|
|
dataHandler?: IDataHandler;
|
|
|
|
/**
|
|
* Optional TLS handler
|
|
*/
|
|
tlsHandler?: ITlsHandler;
|
|
|
|
/**
|
|
* Optional security handler
|
|
*/
|
|
securityHandler?: ISecurityHandler;
|
|
} |