@push.rocks/smartmta 13.1.0 → 14.0.0

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

@@ -331,6 +331,68 @@ interface IEmailData {
     type: 'inline';
     base64: string;
 }
+/** A mailbox of the parsed-message bridge JSON. */
+export interface IBridgeMailAddress {
+    email: string;
+    name?: string;
+}
+/** The header fields of an inline nested message (never produced with smartmta's setting). */
+export interface IBridgeMessageHeader {
+    from: IBridgeMailAddress[];
+    to: IBridgeMailAddress[];
+    cc: IBridgeMailAddress[];
+    bcc: IBridgeMailAddress[];
+    subject?: string;
+    date?: string;
+}
+/** One body group: the text and HTML sections of one multipart/alternative or one body part. */
+export interface IBridgeMailBodyGroup {
+    text?: string;
+    html?: string;
+    messageHeader?: IBridgeMessageHeader;
+}
+export interface IBridgeParsedAttachment {
+    filename?: string;
+    contentType: string;
+    disposition?: 'attachment' | 'inline';
+    contentId?: string;
+    /** Standard base64 of the transfer-decoded bytes. */
+    content: string;
+    size: number;
+}
+/**
+ * A message as the Rust mailer-mime crate parsed it (docs/cleanroom/mailer-mime.md section 2.3).
+ * Each body travels once, in `bodyGroups`; the flattened From list is the concatenation of
+ * `fromFields`.
+ */
+export interface IBridgeParsedMessage {
+    headers: Array<{
+        key: string;
+        name: string;
+        value: string;
+    }>;
+    headerLines: Array<{
+        key: string;
+        line: string;
+    }>;
+    messageId?: string;
+    inReplyTo?: string;
+    references: string[];
+    /** ISO 8601 UTC with milliseconds. */
+    date?: string;
+    subject?: string;
+    sender?: IBridgeMailAddress;
+    replyTo: IBridgeMailAddress[];
+    to: IBridgeMailAddress[];
+    cc: IBridgeMailAddress[];
+    bcc: IBridgeMailAddress[];
+    bodyGroups: IBridgeMailBodyGroup[];
+    attachments: IBridgeParsedAttachment[];
+    /** One flattened mailbox list per From field, in field order. */
+    fromFields: IBridgeMailAddress[][];
+    partFilenames: string[];
+    abruptHeaderEnd: boolean;
+}
 interface IEmailReceivedEvent {
     correlationId: string;
     sessionId: string;
@@ -342,6 +404,8 @@ interface IEmailReceivedEvent {
     secure: boolean;
     authenticatedUser: string | null;
     securityResults: IInboundEmailSecurityResult | null;
+    /** The one parse Rust made at DATA. */
+    parsed: IBridgeParsedMessage;
 }
 interface IRcptToRequestEvent {
     correlationId: string;
@@ -395,7 +459,17 @@ export interface IBridgeResilienceConfig {
 export declare class RustSecurityBridge extends EventEmitter {
     private static instance;
     private static _resilienceConfig;
+    /** The server default maximum message size, used until `setMaxMessageSize` is called. */
+    private static readonly defaultMaxMessageSize;
+    /** The smartrust bridge of the running process; a new one is created at every spawn. */
     private bridge;
+    private readonly localPaths;
+    /** The IPC line cap the next spawn uses: 4 × the maximum message size. */
+    private _lineCap;
+    /** The line cap of the running process, which both transport ends were created with. */
+    private _runningLineCap;
+    /** Management event handlers, attached to every bridge this singleton creates. */
+    private readonly managementHandlers;
     private _running;
     private _state;
     private _restartAttempts;
@@ -406,12 +480,23 @@ export declare class RustSecurityBridge extends EventEmitter {
     private _deliberateStop;
     private _smtpServerConfig;
     /**
-     * Map Node.js process.platform / process.arch to the tsrust target suffix
+     * Map Node.js process.platform / process.arch to the rsrepo target suffix
      * of the shipped binaries. Linux binaries are static musl builds, e.g.
      * mailer-bin_linux_amd64_musl.
      */
     private static getPlatformSuffix;
     private constructor();
+    /**
+     * Creates the smartrust bridge for one spawn. The line cap is fixed per process at both ends
+     * of the transport: smartrust's `maxPayloadSize` and `mailer-bin --max-line-bytes` get the
+     * one computed value. Lifecycle listeners and every registered management handler are
+     * attached, so a handler registered before a spawn or restart keeps receiving events.
+     */
+    private createBridge;
+    /** Replaces the bridge with a new one for the current cap and spawns it. */
+    private spawnBridge;
+    /** The bridge of the running process; commands are guarded by ensureRunning() first. */
+    private get activeBridge();
     /** Get or create the singleton instance. */
     static getInstance(): RustSecurityBridge;
     /** Reset the singleton instance (for testing). */
@@ -435,6 +520,20 @@ export declare class RustSecurityBridge extends EventEmitter {
     start(): Promise<boolean>;
     /** Kill the Rust process deliberately. */
     stop(): Promise<void>;
+    /** The IPC line cap the next spawn uses (4 × the maximum message size). */
+    get lineCap(): number;
+    /**
+     * Sets the SMTP maximum message size the IPC line cap derives from: `cap = 4 × n`, the one
+     * value used as smartrust's `maxPayloadSize` and as `mailer-bin --max-line-bytes`. Outbound
+     * requests (`sendEmail`, `sendRawEmail`, `signDkim`, `verifyDkim`) are limited by the same
+     * cap. When the process runs with a different cap it is restarted deliberately (no crash
+     * count, no backoff) and a stored listener configuration is restored; otherwise the value is
+     * recorded for the next spawn. Throws, changing nothing, for an `n` that is not a positive
+     * safe integer or whose cap is not a safe integer.
+     */
+    setMaxMessageSize(maxMessageSize: number): Promise<void>;
+    /** A deliberate restart for a changed line cap; it is not a crash. */
+    private restartForLineCap;
     private attemptRestart;
     private executeRestartAttempt;
     /**
@@ -500,6 +599,12 @@ export declare class RustSecurityBridge extends EventEmitter {
         hostname?: string;
         mailFrom: string;
     }): Promise<IEmailSecurityResult>;
+    /**
+     * Parses stored message bytes with the parser and setting of the DATA path (`parseMessage`,
+     * ruling Q1), so a replay builds the same Email the live path built. Rejects with the
+     * parser's error text when a parser limit is exceeded or the answer would exceed the line cap.
+     */
+    parseMessage(rawMessage: Buffer): Promise<IBridgeParsedMessage>;
     /** Send a structured email via the Rust SMTP client. */
     sendOutboundEmail(opts: ISmtpSendOptions): Promise<ISmtpSendResult>;
     /**
@@ -571,6 +676,8 @@ export declare class RustSecurityBridge extends EventEmitter {
     }): Promise<void>;
     /** Update rate limit configuration at runtime. */
     configureRateLimits(config: IRateLimitConfig): Promise<void>;
+    private addManagementHandler;
+    private removeManagementHandler;
     /**
      * Register a handler for emailReceived events from the Rust SMTP server.
      * These events fire when a complete email has been received and needs processing.