@push.rocks/smartmta 7.0.0 → 8.0.1

package/ts/security/classes.rustsecuritybridge.ts

@@ -69,6 +69,251 @@ interface IContentScanResult {
 
 // --- SMTP Client types ---
 
+export type TSmtpDeliveryPhase =
+  | 'connect'
+  | 'greeting'
+  | 'ehlo'
+  | 'starttls'
+  | 'tls_handshake'
+  | 'post_tls_ehlo'
+  | 'auth'
+  | 'mail_from'
+  | 'rcpt_to'
+  | 'data_command'
+  | 'message_body'
+  | 'final_response'
+  | 'rset'
+  | 'quit'
+  | 'unknown';
+
+export interface ISmtpTranscriptEntry {
+  timestampMs: number;
+  phase: TSmtpDeliveryPhase;
+  direction: 'client' | 'server' | 'system';
+  text: string;
+  responseCode?: number;
+}
+
+/** Persisted SMTP traces are bounded by entries, Unicode code points, and UTF-8 bytes. */
+export const SMTP_TRANSCRIPT_MAX_ENTRIES = 200;
+export const SMTP_TRANSCRIPT_MAX_ENTRY_CODE_POINTS = 2_048;
+export const SMTP_TRANSCRIPT_MAX_UTF8_BYTES = 64 * 1_024;
+export const SMTP_TRANSCRIPT_TRUNCATION_MARKER = 'SMTP transcript truncated';
+
+const utf8ByteLength = (valueArg: string): number => Buffer.byteLength(valueArg, 'utf8');
+
+const truncateCodePoints = (valueArg: string): string => {
+  const codePoints = [...valueArg];
+  if (codePoints.length <= SMTP_TRANSCRIPT_MAX_ENTRY_CODE_POINTS) return valueArg;
+  return `${codePoints.slice(0, SMTP_TRANSCRIPT_MAX_ENTRY_CODE_POINTS - 1).join('')}…`;
+};
+
+const redactAuthTranscriptText = (
+  phaseArg: TSmtpDeliveryPhase,
+  directionArg: ISmtpTranscriptEntry['direction'],
+  textArg: string,
+): string => {
+  if (phaseArg !== 'auth') return textArg;
+  if (directionArg === 'client') return '[AUTH command redacted]';
+  if (directionArg === 'server') return '[AUTH response redacted]';
+  return '[AUTH diagnostic redacted]';
+};
+
+/**
+ * Normalize an untrusted SMTP trace before exposing or persisting it.
+ * Entry text is measured in Unicode code points; the aggregate is measured in UTF-8 bytes.
+ */
+export const normalizeSmtpTranscript = (entriesArg: unknown[]): ISmtpTranscriptEntry[] => {
+  const normalized: ISmtpTranscriptEntry[] = [];
+  let totalUtf8Bytes = 0;
+
+  const appendTruncationMarker = (referenceArg?: Partial<ISmtpTranscriptEntry>): void => {
+    const markerBytes = utf8ByteLength(SMTP_TRANSCRIPT_TRUNCATION_MARKER);
+    while (
+      normalized.length >= SMTP_TRANSCRIPT_MAX_ENTRIES
+      || totalUtf8Bytes + markerBytes > SMTP_TRANSCRIPT_MAX_UTF8_BYTES
+    ) {
+      const removed = normalized.pop();
+      if (!removed) break;
+      totalUtf8Bytes -= utf8ByteLength(removed.text);
+    }
+    if (
+      normalized.length < SMTP_TRANSCRIPT_MAX_ENTRIES
+      && totalUtf8Bytes + markerBytes <= SMTP_TRANSCRIPT_MAX_UTF8_BYTES
+    ) {
+      normalized.push({
+        timestampMs: typeof referenceArg?.timestampMs === 'number'
+          && Number.isFinite(referenceArg.timestampMs)
+          ? referenceArg.timestampMs
+          : Date.now(),
+        phase: isSmtpDeliveryPhase(referenceArg?.phase) ? referenceArg.phase : 'unknown',
+        direction: 'system',
+        text: SMTP_TRANSCRIPT_TRUNCATION_MARKER,
+      });
+      totalUtf8Bytes += markerBytes;
+    }
+  };
+
+  for (const valueArg of entriesArg) {
+    if (!valueArg || typeof valueArg !== 'object') continue;
+    const value = valueArg as Partial<ISmtpTranscriptEntry>;
+    if (
+      typeof value.timestampMs !== 'number'
+      || !Number.isFinite(value.timestampMs)
+      || !isSmtpDeliveryPhase(value.phase)
+      || !['client', 'server', 'system'].includes(value.direction as string)
+      || typeof value.text !== 'string'
+    ) {
+      continue;
+    }
+
+    const direction = value.direction as ISmtpTranscriptEntry['direction'];
+    const text = truncateCodePoints(redactAuthTranscriptText(value.phase, direction, value.text));
+    const textBytes = utf8ByteLength(text);
+    if (
+      normalized.length >= SMTP_TRANSCRIPT_MAX_ENTRIES
+      || totalUtf8Bytes + textBytes > SMTP_TRANSCRIPT_MAX_UTF8_BYTES
+    ) {
+      appendTruncationMarker(value);
+      break;
+    }
+
+    normalized.push({
+      timestampMs: value.timestampMs,
+      phase: value.phase,
+      direction,
+      text,
+      ...(typeof value.responseCode === 'number' && Number.isInteger(value.responseCode)
+        ? { responseCode: value.responseCode }
+        : {}),
+    });
+    totalUtf8Bytes += textBytes;
+  }
+
+  return normalized;
+};
+
+export interface ISmtpDeliveryErrorDetails {
+  message: string;
+  errorType: string;
+  retryable: boolean;
+  smtpCode?: number;
+  phase: TSmtpDeliveryPhase;
+  transactionLog: ISmtpTranscriptEntry[];
+  recipients?: string[];
+  recipientDomain?: string;
+  recipientResults?: ISmtpRecipientResult[];
+}
+
+interface ISmtpRecipientResult {
+  recipient: string;
+  accepted: boolean;
+  responseCode: number;
+}
+
+export class SmtpDeliveryError extends Error implements ISmtpDeliveryErrorDetails {
+  public readonly errorType: string;
+  public readonly retryable: boolean;
+  public readonly smtpCode?: number;
+  public readonly phase: TSmtpDeliveryPhase;
+  public readonly transactionLog: ISmtpTranscriptEntry[];
+  public readonly recipients: string[];
+  public readonly recipientDomain?: string;
+  public readonly recipientResults: ISmtpRecipientResult[];
+
+  constructor(details: ISmtpDeliveryErrorDetails, cause?: unknown) {
+    const transactionLog = normalizeSmtpTranscript(details.transactionLog);
+    const authFailure = (
+      details.phase === 'auth'
+      || details.errorType === 'authentication'
+      || transactionLog.some((entry) => entry.phase === 'auth')
+    );
+    super(authFailure ? 'SMTP authentication failed' : details.message);
+    this.name = 'SmtpDeliveryError';
+    this.errorType = details.errorType;
+    this.retryable = details.retryable;
+    this.smtpCode = details.smtpCode;
+    this.phase = details.phase;
+    this.transactionLog = transactionLog;
+    this.recipients = details.recipients || [];
+    this.recipientDomain = details.recipientDomain;
+    this.recipientResults = (details.recipientResults || []).map((result) => ({ ...result }));
+    if (cause !== undefined && !authFailure) {
+      (this as Error & { cause?: unknown }).cause = cause;
+    }
+  }
+
+  public static from(errorArg: unknown): SmtpDeliveryError {
+    if (errorArg instanceof SmtpDeliveryError) {
+      return errorArg;
+    }
+    const source = errorArg instanceof Error ? errorArg : new Error(String(errorArg));
+    try {
+      const parsed = JSON.parse(source.message) as Partial<ISmtpDeliveryErrorDetails>;
+      if (typeof parsed.message !== 'string' || typeof parsed.retryable !== 'boolean') {
+        throw new Error('Incomplete SMTP error payload');
+      }
+      const phase = isSmtpDeliveryPhase(parsed.phase) ? parsed.phase : 'unknown';
+      const transactionLog = Array.isArray(parsed.transactionLog)
+        ? normalizeSmtpTranscript(parsed.transactionLog)
+        : [];
+      return new SmtpDeliveryError({
+        message: parsed.message,
+        errorType: typeof parsed.errorType === 'string' ? parsed.errorType : 'unknown',
+        retryable: parsed.retryable,
+        ...(typeof parsed.smtpCode === 'number' ? { smtpCode: parsed.smtpCode } : {}),
+        phase,
+        transactionLog,
+        recipients: Array.isArray(parsed.recipients)
+          ? parsed.recipients.filter((value): value is string => typeof value === 'string')
+          : [],
+        recipientResults: Array.isArray(parsed.recipientResults)
+          ? parsed.recipientResults.filter((value): value is ISmtpRecipientResult => (
+              Boolean(value)
+              && typeof value === 'object'
+              && typeof (value as ISmtpRecipientResult).recipient === 'string'
+              && typeof (value as ISmtpRecipientResult).accepted === 'boolean'
+              && Number.isInteger((value as ISmtpRecipientResult).responseCode)
+            )).map((value) => ({ ...value }))
+          : [],
+        ...(typeof parsed.recipientDomain === 'string'
+          ? { recipientDomain: parsed.recipientDomain }
+          : {}),
+      }, source);
+    } catch {
+      return new SmtpDeliveryError({
+        message: source.message,
+        errorType: 'unknown',
+        retryable: true,
+        phase: 'unknown',
+        transactionLog: [],
+        recipients: [],
+      }, source);
+    }
+  }
+}
+
+const smtpDeliveryPhases = new Set<TSmtpDeliveryPhase>([
+  'connect',
+  'greeting',
+  'ehlo',
+  'starttls',
+  'tls_handshake',
+  'post_tls_ehlo',
+  'auth',
+  'mail_from',
+  'rcpt_to',
+  'data_command',
+  'message_body',
+  'final_response',
+  'rset',
+  'quit',
+  'unknown',
+]);
+
+const isSmtpDeliveryPhase = (valueArg: unknown): valueArg is TSmtpDeliveryPhase =>
+  typeof valueArg === 'string' && smtpDeliveryPhases.has(valueArg as TSmtpDeliveryPhase);
+
 interface IOutboundEmail {
   from: string;
   to: string[];
@@ -83,9 +328,11 @@ interface IOutboundEmail {
 interface ISmtpSendResult {
   accepted: string[];
   rejected: string[];
+  recipientResults?: ISmtpRecipientResult[];
   messageId?: string;
   response: string;
   envelope: { from: string; to: string[] };
+  transactionLog: ISmtpTranscriptEntry[];
 }
 
 interface ISmtpSendOptions {
@@ -442,7 +689,9 @@ export class RustSecurityBridge extends EventEmitter {
     this.bridge = new plugins.smartrust.RustBridge<TMailerCommands>({
       binaryName: 'mailer-bin',
       cliArgs: ['--management'],
-      requestTimeoutMs: 30_000,
+      // A full SMTP transaction can legitimately span several socket waits.
+      // Health checks retain their own short timeout and run concurrently.
+      requestTimeoutMs: 300_000,
       readyTimeoutMs: 10_000,
       localPaths,
       searchSystemPath: false,
@@ -877,13 +1126,29 @@ export class RustSecurityBridge extends EventEmitter {
   /** Send a structured email via the Rust SMTP client. */
   public async sendOutboundEmail(opts: ISmtpSendOptions): Promise<ISmtpSendResult> {
     this.ensureRunning();
-    return this.bridge.sendCommand('sendEmail', opts);
+    try {
+      const result = await this.bridge.sendCommand('sendEmail', opts);
+      return {
+        ...result,
+        transactionLog: normalizeSmtpTranscript(result.transactionLog),
+      };
+    } catch (error) {
+      throw SmtpDeliveryError.from(error);
+    }
   }
 
   /** Send a pre-formatted raw email via the Rust SMTP client. */
   public async sendRawEmail(opts: ISmtpSendRawOptions): Promise<ISmtpSendResult> {
     this.ensureRunning();
-    return this.bridge.sendCommand('sendRawEmail', opts);
+    try {
+      const result = await this.bridge.sendCommand('sendRawEmail', opts);
+      return {
+        ...result,
+        transactionLog: normalizeSmtpTranscript(result.transactionLog),
+      };
+    } catch (error) {
+      throw SmtpDeliveryError.from(error);
+    }
   }
 
   /** Verify connectivity to an SMTP server. */
@@ -1065,6 +1330,7 @@ export type {
   IScramCredentialRequestEvent,
   IOutboundEmail,
   ISmtpSendResult,
+  ISmtpRecipientResult,
   ISmtpSendOptions,
   ISmtpSendRawOptions,
   ISmtpVerifyOptions,

package/ts/security/classes.securitylogger.ts

@@ -146,12 +146,14 @@ export class SecurityLogger {
         filteredEvents = filteredEvents.filter(event => event.type === filter.type);
       }
       
-      if (filter.fromTimestamp) {
-        filteredEvents = filteredEvents.filter(event => event.timestamp >= filter.fromTimestamp);
+      const fromTimestamp = filter.fromTimestamp;
+      if (fromTimestamp !== undefined) {
+        filteredEvents = filteredEvents.filter(event => event.timestamp >= fromTimestamp);
       }
       
-      if (filter.toTimestamp) {
-        filteredEvents = filteredEvents.filter(event => event.timestamp <= filter.toTimestamp);
+      const toTimestamp = filter.toTimestamp;
+      if (toTimestamp !== undefined) {
+        filteredEvents = filteredEvents.filter(event => event.timestamp <= toTimestamp);
       }
     }
     

package/ts/security/index.ts

@@ -23,7 +23,11 @@ export {
 export {
   RustSecurityBridge,
   BridgeState,
+  SmtpDeliveryError,
   type IBridgeResilienceConfig,
+  type TSmtpDeliveryPhase,
+  type ISmtpTranscriptEntry,
+  type ISmtpDeliveryErrorDetails,
   type IDkimVerificationResult,
   type ISpfResult,
   type IDmarcResult,
@@ -34,7 +38,8 @@ export {
   type IVersionInfo,
   type IOutboundEmail,
   type ISmtpSendResult,
+  type ISmtpRecipientResult,
   type ISmtpSendOptions,
   type ISmtpVerifyResult,
   type ISmtpPoolStatus,
-} from './classes.rustsecuritybridge.js';
+} from './classes.rustsecuritybridge.js';