update
This commit is contained in:
610
ts/mail/delivery/smtpserver/interfaces.ts
Normal file
610
ts/mail/delivery/smtpserver/interfaces.ts
Normal file
@ -0,0 +1,610 @@
|
||||
/**
|
||||
* 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;
|
||||
}
|
||||
Reference in New Issue
Block a user