@push.rocks/smartmta 8.0.1 → 8.1.1

package/dist_ts/mail/routing/classes.unified.email.server.d.ts

@@ -1,7 +1,8 @@
 import { EventEmitter } from 'events';
 import { DKIMCreator } from '../security/classes.dkimcreator.js';
 import type { IStorageManager } from '../interfaces.storage.js';
-import type { IEmailRoute, IEmailDomainConfig } from './interfaces.js';
+import type { IInboundEmailSecurityResult } from '../../security/classes.rustsecuritybridge.js';
+import type { IEmailRoute, IEmailAction, IEmailDomainConfig } from './interfaces.js';
 import { Email } from '../core/classes.email.js';
 import { DomainRegistry } from './classes.domain.registry.js';
 import { BounceType, BounceCategory } from '../core/classes.bouncemanager.js';
@@ -16,6 +17,25 @@ interface DcRouter {
     dnsServer?: any;
     options?: any;
 }
+export type TRecipientRouteSource = 'explicit-route' | 'domain-policy' | 'no-route';
+export type TRecipientRejectionReason = 'explicit-route' | 'domain-policy' | 'no-route' | 'domain-not-hosted' | 'relay-denied' | 'recipient-hook' | 'policy-error';
+export interface IResolvedRecipientRoute {
+    recipient: string;
+    localDomain: string | null;
+    route: IEmailRoute | null;
+    source: TRecipientRouteSource;
+}
+export interface IRecipientRejectedEvent {
+    timestamp: string;
+    sender: string;
+    recipient: string;
+    localDomain: string | null;
+    remoteAddress: string;
+    smtpCode: number;
+    smtpMessage: string;
+    routeName: string | null;
+    reason: TRecipientRejectionReason;
+}
 /**
  * Extended SMTP session interface with route information
  */
@@ -24,6 +44,10 @@ export interface IExtendedSmtpSession extends ISmtpSession {
      * Matched route for this session
      */
     matchedRoute?: IEmailRoute;
+    /** Per-envelope-recipient routes resolved before DATA acceptance. */
+    resolvedRecipientRoutes?: IResolvedRecipientRoute[];
+    /** Results computed by the Rust inbound pipeline before the message event is emitted. */
+    securityResults?: IInboundEmailSecurityResult | null;
 }
 export interface ISmtpDecision {
     accepted: boolean;
@@ -46,7 +70,78 @@ export interface IMessageAcceptanceContext {
     email: Email;
     rawMessage: Buffer;
     session: IExtendedSmtpSession;
+    matchedRoute?: IEmailRoute;
+    /** Full-envelope route resolution. */
+    resolvedRecipientRoutes: IResolvedRecipientRoute[];
+    abortSignal?: AbortSignal;
+}
+/**
+ * Terminal durable acceptance context for an envelope containing at least one `store` route.
+ * The consumer owns persistence and all recipient fan-out before this hook resolves.
+ */
+export interface IAcceptEnvelopeContext {
+    email: Email;
+    /** Exact bytes received during SMTP DATA, before parsing or transformation. */
+    rawMessage: Buffer;
+    session: IExtendedSmtpSession;
+    envelope: {
+        mailFrom: string;
+        rcptTo: string[];
+    };
+    /** Complete resolved plan for every SMTP envelope recipient. */
+    resolvedRecipientRoutes: IResolvedRecipientRoute[];
     abortSignal?: AbortSignal;
+    /** Immutable attachment count derived from the parsed message. */
+    readonly attachmentCount: number;
+    /** Rust-computed inbound verdicts, available before durable acceptance. */
+    securityResults: IInboundEmailSecurityResult | null;
+}
+/**
+ * JSON-safe, immutable snapshot of one accepted envelope recipient's exact
+ * routing decision. The snapshot is safe to persist and replay without
+ * consulting the live route table.
+ */
+export interface IAcceptedEnvelopeRecipientPlan {
+    readonly recipient: string;
+    readonly localDomain: string | null;
+    readonly routeName: string;
+    readonly source: TRecipientRouteSource;
+    readonly action: IEmailAction;
+    readonly idempotencyKey: string;
+}
+/** Serializable SMTP metadata needed to recreate an isolated action session. */
+export interface IAcceptedEnvelopeDispatchMetadata {
+    readonly mailFrom: string;
+    readonly session?: {
+        readonly id?: string;
+        readonly remoteAddress?: string;
+        readonly clientHostname?: string;
+        readonly secure?: boolean;
+        readonly authenticated?: boolean;
+        readonly authenticatedUser?: string | null;
+        readonly user?: Readonly<{
+            username: string;
+            [key: string]: unknown;
+        }>;
+    };
+}
+export type TAcceptedEnvelopeRecipientDispatchStatus = 'stored' | 'queued' | 'rejected' | 'failed';
+export interface IAcceptedEnvelopeRecipientDispatchResult {
+    recipient: string;
+    localDomain: string | null;
+    routeName: string;
+    source: TRecipientRouteSource;
+    actionType: IEmailAction['type'];
+    idempotencyKey: string;
+    status: TAcceptedEnvelopeRecipientDispatchStatus;
+    replayed: boolean;
+    queueId?: string;
+    smtpCode?: number;
+    message?: string;
+}
+export interface IAcceptedEnvelopeDispatchResult {
+    complete: boolean;
+    results: IAcceptedEnvelopeRecipientDispatchResult[];
 }
 export interface IMessageAcceptanceDecision extends ISmtpDecision {
     /** Continue SmartMTA's built-in route processing after the consumer accepted responsibility. */
@@ -69,6 +164,16 @@ export interface IOutboundConnectionProxy {
     ehloHostname?: string;
     close?: () => Promise<void> | void;
 }
+export interface IOutboundTopologyIdentity {
+    hostnames?: string[];
+    ipAddresses?: string[];
+}
+export interface ISelfMxIdentityMatch {
+    isSelf: boolean;
+    source: 'explicit' | 'dns-derived' | 'dynamic' | null;
+    indeterminate: boolean;
+    evidence: string[];
+}
 /**
  * Options for the unified email server
  */
@@ -123,10 +228,14 @@ export interface IUnifiedEmailServerOptions {
         };
     };
     hooks?: {
-        /** Async recipient policy hook, called before each RCPT TO is accepted. */
+        /** Async recipient policy hook that may further restrict an accepted built-in decision. */
         onRcptTo?: (context: IRcptToPolicyContext) => Promise<ISmtpDecision>;
-        /** Async message acceptance hook, called after DATA before the final SMTP response. */
+        /** Async message acceptance hook for envelopes with no resolved `store` action. */
         onMessageData?: (context: IMessageAcceptanceContext) => Promise<IMessageAcceptanceDecision>;
+        /** Required terminal durable owner for any envelope containing a resolved `store` action. */
+        onAcceptEnvelope?: (context: IAcceptEnvelopeContext) => Promise<void>;
+        /** Observer-safe callback for SMTP recipient rejections. */
+        onRecipientRejected?: (event: IRecipientRejectedEvent) => Promise<void> | void;
     };
     defaults?: {
         dnsMode?: 'forward' | 'internal-dns' | 'external-dns';
@@ -141,6 +250,10 @@ export interface IUnifiedEmailServerOptions {
         socketTimeout?: number;
         retryAttempts?: number;
         defaultFrom?: string;
+        /** Static public listener identities that must never be selected as outbound MX targets. */
+        selfListenerIdentities?: IOutboundTopologyIdentity;
+        /** Current proven mail-edge identities. Connection proxy targets are deliberately not identities. */
+        topologyIdentityProvider?: () => Promise<IOutboundTopologyIdentity | null | undefined>;
         connectionProxyProvider?: (context: IOutboundConnectionProxyContext) => Promise<IOutboundConnectionProxy | null | undefined>;
     };
     queue: IQueueOptions;
@@ -214,9 +327,18 @@ export declare class UnifiedEmailServer extends EventEmitter {
     private bridgeEmailReceivedHandler?;
     private bridgeAuthRequestHandler?;
     private bridgeScramCredentialRequestHandler?;
+    private acceptedEnvelopeDispatchCleanupTimer?;
+    private acceptedEnvelopeDispatchCleanupPromise?;
+    private acceptedEnvelopeDispatchCleanupCursor?;
     constructor(dcRouter: DcRouter, options: IUnifiedEmailServerOptions);
+    onRecipientRejected(listener: (event: IRecipientRejectedEvent) => Promise<void> | void): this;
+    offRecipientRejected(listener: (event: IRecipientRejectedEvent) => Promise<void> | void): this;
     private getAdvertisedHostname;
     private getOutboundHostname;
+    private normalizeTopologyIdentity;
+    private getExplicitTopologyIdentity;
+    private withTopologyTimeout;
+    private resolveTopologyHostname;
     /**
      * Whether a hostname refers to this server's own SMTP identity.
      * Used by MTA delivery to refuse self-addressed relaying: a domain whose
@@ -224,6 +346,8 @@ export declare class UnifiedEmailServer extends EventEmitter {
      * full outbound/inbound pipeline forever.
      */
     isSelfHostname(hostname: string): boolean;
+    /** Resolve a candidate MX against explicit and current proven listener topology. */
+    resolveSelfMxIdentity(hostnameArg: string): Promise<ISelfMxIdentityMatch>;
     /**
      * Send an outbound email via the Rust SMTP client.
      * Uses connection pooling in the Rust binary for efficiency.
@@ -257,13 +381,41 @@ export declare class UnifiedEmailServer extends EventEmitter {
     stop(): Promise<void>;
     private handleRustRcptToRequest;
     private evaluateDefaultRcptToPolicy;
-    private enforceAcceptedRcptToRelayPolicy;
+    private resolveRecipientPolicy;
+    private getRejectionReasonForResolution;
+    private notifyRecipientRejected;
     private buildPolicySession;
     private getAddressDomain;
     private getRecipientValidationTimeoutMs;
     private isRecipientValidationEnabled;
     private getMessageAcceptanceTimeoutMs;
     private runHookWithTimeout;
+    /** Build a route-evaluation view containing only the current SMTP envelope recipient. */
+    private cloneEmailForRoutingRecipient;
+    private scopeSessionForRoutingRecipient;
+    private buildDataPolicyContext;
+    private resolveDataRecipientRoutes;
+    private acceptDurableEnvelope;
+    private cloneJsonSafe;
+    private stableJson;
+    private validateAcceptedEnvelopeAction;
+    private normalizeAcceptedEnvelopePlan;
+    /**
+     * Snapshot the already-resolved acceptance plan for durable consumer storage.
+     * No live route lookup is performed when the returned plan is dispatched.
+     */
+    createAcceptedEnvelopeDispatchPlan(context: IAcceptEnvelopeContext, idempotencyKeys: readonly string[]): readonly IAcceptedEnvelopeRecipientPlan[];
+    private acceptedEnvelopeDispatchStorageKey;
+    private startAcceptedEnvelopeDispatchCleanup;
+    private cleanupExpiredAcceptedEnvelopeDispatchResults;
+    private readAcceptedEnvelopeDispatchResult;
+    private writeAcceptedEnvelopeDispatchResult;
+    /**
+     * Dispatch a durably accepted raw envelope using only its persisted exact
+     * action snapshots. Each recipient receives an isolated Email and session.
+     * Queue-backed actions require managed queue storage and are replay-safe.
+     */
+    dispatchAcceptedEnvelope(rawMessage: Uint8Array, planArg: readonly IAcceptedEnvelopeRecipientPlan[], metadataArg: IAcceptedEnvelopeDispatchMetadata): Promise<IAcceptedEnvelopeDispatchResult>;
     /**
      * Handle an emailReceived event from the Rust SMTP server.
      */