@serve.zone/dcrouter 15.4.1 → 15.6.0

package/ts/email/classes.workapp-mail-manager.ts

@@ -1,11 +1,14 @@
 import type {
   IEmailRoute,
+  IExtendedSmtpSession,
   IMessageAcceptanceContext,
   IMessageAcceptanceDecision,
   IUnifiedEmailServerOptions,
 } from '@push.rocks/smartmta';
 import type { Buffer } from 'node:buffer';
 import * as plugins from '../plugins.js';
+import type { CachedEmail } from '../db/index.js';
+import type { DcRouter } from '../classes.dcrouter.js';
 import type * as interfaces from '../../ts_interfaces/index.js';
 
 type TSyncRequest = {
@@ -14,6 +17,7 @@ type TSyncRequest = {
   domain: string;
   displayName?: string;
   inbound?: interfaces.data.IWorkAppMailInboundRoute;
+  inboundTarget?: plugins.servezoneInterfaces.data.IMailInboundTarget;
   enabled?: boolean;
   smtpEnabled?: boolean;
   resetSmtpPassword?: boolean;
@@ -25,6 +29,8 @@ type TMailAddressBindingSync = plugins.servezoneInterfaces.requests.mail.TMailAd
 type TMailAddressBindingSyncResponse = plugins.servezoneInterfaces.requests.mail.IReq_SyncMailAddressBinding['response'];
 type TMailAddressBindingDeleteResponse = plugins.servezoneInterfaces.requests.mail.IReq_DeleteMailAddressBinding['response'];
 type TMailCredentialRotateResponse = plugins.servezoneInterfaces.requests.mail.IReq_RotateMailCredential['response'];
+type TMailEnqueueResponse = plugins.servezoneInterfaces.requests.mail.IReq_EnqueueMail['response'];
+type TMailEndpointRegistrationResponse = plugins.servezoneInterfaces.requests.mail.IReq_RegisterServiceMailEndpoint['response'];
 type TWorkAppMailBinding = plugins.servezoneInterfaces.data.IWorkAppMailBinding;
 
 interface IStoredWorkAppMailIdentity {
@@ -37,6 +43,7 @@ interface IStoredWorkAppMailIdentity {
   enabled: boolean;
   displayName?: string;
   inbound?: interfaces.data.IWorkAppMailInboundRoute;
+  inboundTarget?: plugins.servezoneInterfaces.data.IMailInboundTarget;
   smtp: {
     enabled: boolean;
     username: string;
@@ -57,7 +64,7 @@ export class WorkAppMailManager {
   private readonly storageKey = '/workhosters/mail-identities.json';
   private identityMutationPromise: Promise<unknown> = Promise.resolve();
 
-  constructor(private dcRouterRef: any) {}
+  constructor(private dcRouterRef: DcRouter) {}
 
   public async listMailIdentities(
     ownership?: Partial<interfaces.data.IWorkAppMailOwnership>,
@@ -130,7 +137,8 @@ export class WorkAppMailManager {
       domain,
       enabled: request.enabled ?? existingIdentity?.enabled ?? true,
       displayName: request.displayName ?? existingIdentity?.displayName,
-      inbound: this.normalizeInboundRoute(request.inbound ?? existingIdentity?.inbound),
+      inboundTarget: this.resolveNextInboundTarget(request, existingIdentity),
+      inbound: this.toLegacyInboundRouteIfSmtpForward(this.resolveNextInboundTarget(request, existingIdentity)),
       smtp: {
         enabled: request.smtpEnabled ?? existingIdentity?.smtp.enabled ?? true,
         username: existingIdentity?.smtp.username || this.buildSmtpUsername(externalKey),
@@ -210,7 +218,8 @@ export class WorkAppMailManager {
         ownership,
         localPart,
         domain,
-        inbound: this.toLegacyInboundRoute(binding.inboundTarget),
+        inboundTarget: binding.inboundTarget,
+        inbound: this.toLegacyInboundRouteIfSmtpForward(binding.inboundTarget),
         enabled: binding.enabled,
       };
 
@@ -320,6 +329,141 @@ export class WorkAppMailManager {
     return undefined;
   }
 
+  public async enqueueMail(
+    authArg: plugins.servezoneInterfaces.requests.mail.IMailSubmissionRequestAuth,
+    messageArg: plugins.servezoneInterfaces.data.IMailOutboundMessagePayload,
+    outboundIdentityIdArg?: string,
+  ): Promise<TMailEnqueueResponse> {
+    if (!this.dcRouterRef.emailServer) {
+      return { accepted: false, message: 'Email server is not running' };
+    }
+    try {
+      const identity = await this.authenticateMailCredential(
+        authArg,
+        messageArg.from,
+        outboundIdentityIdArg,
+      );
+      const rawMessage = this.buildOutboundRawMessage(identity, messageArg);
+      const recipients = this.getMessageRecipients(messageArg);
+      const session = this.buildAuthenticatedSession(identity, messageArg.from, recipients, rawMessage);
+      const acceptance = await this.dcRouterRef.acceptedEmailSpool.acceptRawMessage({
+        rawMessage,
+        envelope: {
+          mailFrom: identity.address,
+          rcptTo: recipients,
+        },
+        session,
+        messageId: this.extractHeader(rawMessage, 'message-id'),
+        subject: messageArg.subject,
+      });
+      return {
+        accepted: acceptance.accepted,
+        spoolItemId: acceptance.spoolItemId,
+        outboundIdentity: this.toMailOutboundIdentity(identity),
+        message: acceptance.smtpMessage,
+      };
+    } catch (error) {
+      return {
+        accepted: false,
+        message: (error as Error).message,
+      };
+    }
+  }
+
+  public async registerServiceMailEndpoint(
+    authArg: plugins.servezoneInterfaces.requests.mail.IMailSubmissionRequestAuth,
+    peerArg: { tags?: Set<string> },
+    addressesArg?: string[],
+  ): Promise<TMailEndpointRegistrationResponse> {
+    if (!peerArg?.tags) {
+      return { success: false, message: 'TypedSocket peer context is required' };
+    }
+    try {
+      const identity = await this.authenticateMailCredential(authArg);
+      const requestedAddresses = addressesArg?.length
+        ? addressesArg.map((addressArg) => this.normalizeAddress(addressArg))
+        : [identity.address];
+      const registeredAddresses: string[] = [];
+      for (const address of requestedAddresses) {
+        const addressIdentity = await this.authenticateMailCredential(authArg, address);
+        peerArg.tags.add(this.buildServiceMailAddressTag(addressIdentity.address));
+        registeredAddresses.push(addressIdentity.address);
+      }
+      return { success: true, addresses: registeredAddresses };
+    } catch (error) {
+      return { success: false, message: (error as Error).message };
+    }
+  }
+
+  public async deliverCachedEmailToTypedEndpoint(
+    cachedEmailArg: CachedEmail,
+    rawMessageArg: Buffer | plugins.buffer.Buffer,
+    sessionArg: IExtendedSmtpSession,
+  ): Promise<boolean> {
+    const identities = await this.readStoredIdentities();
+    const recipientIdentity = identities.find((identityArg) => {
+      if (!identityArg.enabled) return false;
+      const inboundTarget = this.getCanonicalInboundTarget(identityArg);
+      return inboundTarget?.type === 'typedEndpoint'
+        && cachedEmailArg.to.some((recipientArg) => this.normalizeAddress(recipientArg) === identityArg.address);
+    });
+    if (!recipientIdentity) return false;
+
+    const inboundTarget = this.getCanonicalInboundTarget(recipientIdentity)!;
+    const typedEndpoint = inboundTarget.typedEndpoint;
+    if (!typedEndpoint?.method) {
+      throw new Error(`Typed mail endpoint method is missing for ${recipientIdentity.address}`);
+    }
+    const typedsocket = this.dcRouterRef.opsServer?.server?.typedserver?.typedsocket;
+    if (!typedsocket) {
+      throw new Error('OpsServer TypedSocket is not available for inbound mail delivery');
+    }
+    const connection = await typedsocket.findTargetConnectionByTag(
+      this.buildServiceMailAddressTag(recipientIdentity.address) as any,
+    );
+    if (!connection) {
+      throw new Error(`No registered typed mail endpoint for ${recipientIdentity.address}`);
+    }
+
+    const rawMessage = plugins.buffer.Buffer.isBuffer(rawMessageArg)
+      ? rawMessageArg.toString('utf8')
+      : plugins.buffer.Buffer.from(rawMessageArg).toString('utf8');
+    const delivery: plugins.servezoneInterfaces.data.IMailInboundMessagePayload = {
+      spoolItemId: cachedEmailArg.id,
+      owner: this.toMailOwner(recipientIdentity.ownership),
+      envelope: {
+        mailFrom: cachedEmailArg.from,
+        rcptTo: cachedEmailArg.to,
+      },
+      rawMessage,
+      sizeBytes: plugins.buffer.Buffer.byteLength(rawMessage),
+      messageId: cachedEmailArg.messageId,
+      subject: cachedEmailArg.subject,
+      headers: this.extractHeaders(rawMessage),
+      source: {
+        protocol: sessionArg.authenticated ? 'submission' : 'smtp',
+        remoteAddress: sessionArg.remoteAddress,
+        heloName: sessionArg.clientHostname,
+        tls: !!sessionArg.secure,
+        authUsername: sessionArg.user?.username,
+      },
+      receivedAt: Date.now(),
+    };
+
+    const request = typedsocket.createTypedRequest<plugins.servezoneInterfaces.requests.mail.IReq_DeliverInboundMail>(
+      typedEndpoint.method as 'deliverInboundMail',
+      connection,
+    );
+    const result = await request.fire({
+      auth: {},
+      delivery,
+    });
+    if (!result.accepted) {
+      throw new Error(result.message || `Typed mail endpoint rejected ${cachedEmailArg.id}`);
+    }
+    return true;
+  }
+
   public async deleteMailAddressBinding(
     id: string,
     createdBy: string,
@@ -378,7 +522,8 @@ export class WorkAppMailManager {
   }
 
   private async readStoredIdentities(): Promise<IStoredWorkAppMailIdentity[]> {
-    const storedData = await this.dcRouterRef.storageManager.get(this.storageKey);
+    const storageManager = this.getRequiredStorageManager();
+    const storedData = await storageManager.get(this.storageKey);
     if (!storedData) return [];
     const parsed = JSON.parse(storedData) as IStoredWorkAppMailState | IStoredWorkAppMailIdentity[];
     return Array.isArray(parsed) ? parsed : parsed.identities || [];
@@ -389,7 +534,15 @@ export class WorkAppMailManager {
       version: 1,
       identities,
     };
-    await this.dcRouterRef.storageManager.set(this.storageKey, JSON.stringify(state, null, 2));
+    const storageManager = this.getRequiredStorageManager();
+    await storageManager.set(this.storageKey, JSON.stringify(state, null, 2));
+  }
+
+  private getRequiredStorageManager() {
+    if (!plugins.smartmta.hasStorageManagerMethods(this.dcRouterRef.storageManager, ['get', 'set'])) {
+      throw new Error('DcRouter storage manager does not support managed mail identity persistence');
+    }
+    return this.dcRouterRef.storageManager;
   }
 
   private mergeIdentitiesIntoEmailConfig<TConfig extends IUnifiedEmailServerOptions>(
@@ -397,7 +550,10 @@ export class WorkAppMailManager {
     identities: IStoredWorkAppMailIdentity[],
   ): TConfig {
     const generatedRoutes = identities
-      .filter((identity) => identity.enabled && identity.inbound?.enabled)
+      .filter((identity) => {
+        const inboundTarget = this.getCanonicalInboundTarget(identity);
+        return identity.enabled && ['smtpForward', 'typedEndpoint'].includes(inboundTarget?.type || '');
+      })
       .map((identity) => this.buildInboundRoute(identity));
     const generatedOutboundRoutes = identities
       .filter((identity) => identity.enabled && identity.smtp.enabled)
@@ -424,7 +580,27 @@ export class WorkAppMailManager {
   }
 
   private buildInboundRoute(identity: IStoredWorkAppMailIdentity): IEmailRoute {
-    const inbound = identity.inbound!;
+    const inboundTarget = this.getCanonicalInboundTarget(identity);
+    if (inboundTarget?.type === 'typedEndpoint') {
+      return {
+        name: this.buildRouteName(identity.externalKey),
+        priority: 1000,
+        match: {
+          recipients: identity.address,
+        },
+        action: {
+          type: 'process',
+          process: {
+            scan: true,
+            queue: 'normal',
+          },
+        },
+      };
+    }
+    const smtpForward = inboundTarget?.smtpForward;
+    if (inboundTarget?.type !== 'smtpForward' || !smtpForward) {
+      throw new Error(`SMTP forward target is missing for ${identity.address}`);
+    }
     return {
       name: this.buildRouteName(identity.externalKey),
       priority: 1000,
@@ -434,14 +610,14 @@ export class WorkAppMailManager {
       action: {
         type: 'forward',
         forward: {
-          host: inbound.targetHost,
-          port: inbound.targetPort,
-          preserveHeaders: inbound.preserveHeaders ?? true,
+          host: smtpForward.host,
+          port: smtpForward.port,
+          preserveHeaders: smtpForward.preserveHeaders ?? true,
           addHeaders: {
             'X-Dcrouter-WorkHoster-Type': identity.ownership.workHosterType,
             'X-Dcrouter-WorkHoster-Id': identity.ownership.workHosterId,
             'X-Dcrouter-WorkApp-Id': identity.ownership.workAppId,
-            ...(inbound.addHeaders || {}),
+            ...(smtpForward.addHeaders || {}),
           },
         },
       },
@@ -649,6 +825,334 @@ export class WorkAppMailManager {
     };
   }
 
+  private toLegacyInboundRouteIfSmtpForward(
+    inboundTarget?: plugins.servezoneInterfaces.data.IMailInboundTarget,
+  ): interfaces.data.IWorkAppMailInboundRoute | undefined {
+    if (!inboundTarget || inboundTarget.type !== 'smtpForward') return undefined;
+    return this.toLegacyInboundRoute(inboundTarget);
+  }
+
+  private resolveNextInboundTarget(
+    request: TSyncRequest,
+    existingIdentity?: IStoredWorkAppMailIdentity,
+  ): plugins.servezoneInterfaces.data.IMailInboundTarget | undefined {
+    if (request.inboundTarget !== undefined) {
+      return this.normalizeInboundTarget(request.inboundTarget);
+    }
+    if (request.inbound !== undefined) {
+      const inbound = this.normalizeInboundRoute(request.inbound);
+      return inbound ? this.toMailInboundTarget(inbound) : undefined;
+    }
+    return this.normalizeInboundTarget(
+      existingIdentity?.inboundTarget || this.toMailInboundTarget(existingIdentity?.inbound),
+    );
+  }
+
+  private normalizeInboundTarget(
+    inboundTarget?: plugins.servezoneInterfaces.data.IMailInboundTarget,
+  ): plugins.servezoneInterfaces.data.IMailInboundTarget | undefined {
+    if (!inboundTarget) return undefined;
+    if (inboundTarget.type === 'smtpForward') {
+      const smtpForward = inboundTarget.smtpForward;
+      if (!smtpForward?.host) throw new Error('smtpForward.host is required');
+      const port = Number(smtpForward.port);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid smtpForward.port: ${smtpForward.port}`);
+      }
+      return {
+        type: 'smtpForward',
+        smtpForward: {
+          ...smtpForward,
+          host: smtpForward.host.trim(),
+          port,
+        },
+      };
+    }
+    if (inboundTarget.type === 'typedEndpoint') {
+      const typedEndpoint = inboundTarget.typedEndpoint;
+      return {
+        type: 'typedEndpoint',
+        typedEndpoint: {
+          method: typedEndpoint?.method?.trim() || 'deliverInboundMail',
+          ...(typedEndpoint?.serviceRef ? { serviceRef: typedEndpoint.serviceRef } : {}),
+          ...(typedEndpoint?.queueName ? { queueName: typedEndpoint.queueName } : {}),
+          ...(typedEndpoint?.timeoutMs !== undefined ? { timeoutMs: typedEndpoint.timeoutMs } : {}),
+        },
+      };
+    }
+    throw new Error(`Unsupported WorkApp mail inbound target: ${inboundTarget.type}`);
+  }
+
+  private getCanonicalInboundTarget(
+    identity: Pick<IStoredWorkAppMailIdentity, 'inbound' | 'inboundTarget'>,
+  ): plugins.servezoneInterfaces.data.IMailInboundTarget | undefined {
+    return this.normalizeInboundTarget(identity.inboundTarget || this.toMailInboundTarget(identity.inbound));
+  }
+
+  private async authenticateMailCredential(
+    authArg: plugins.servezoneInterfaces.requests.mail.IMailSubmissionRequestAuth,
+    addressArg?: string,
+    credentialIdArg?: string,
+  ): Promise<IStoredWorkAppMailIdentity> {
+    const credentialId = (credentialIdArg || authArg.credentialId || '').trim();
+    const credentialSecret = authArg.credentialSecret || '';
+    if (!credentialId || !credentialSecret) {
+      throw new Error('credentialId and credentialSecret are required');
+    }
+    const normalizedAddress = addressArg ? this.normalizeAddress(addressArg) : undefined;
+    const identities = await this.readStoredIdentities();
+    const identity = identities.find((identityArg) => {
+      return identityArg.id === credentialId
+        || identityArg.externalKey === credentialId
+        || identityArg.smtp.username === credentialId;
+    });
+    if (!identity || !identity.enabled || !identity.smtp.enabled) {
+      throw new Error('Mail credential is not active');
+    }
+    if (identity.smtpPassword !== credentialSecret) {
+      throw new Error('Mail credential secret is invalid');
+    }
+    if (normalizedAddress && identity.address !== normalizedAddress) {
+      throw new Error('Mail credential is not authorized for this address');
+    }
+    return identity;
+  }
+
+  private buildAuthenticatedSession(
+    identityArg: IStoredWorkAppMailIdentity,
+    fromArg: string,
+    recipientsArg: string[],
+    rawMessageArg: string,
+  ): IExtendedSmtpSession {
+    return {
+      id: `typed-${plugins.crypto.randomUUID()}`,
+      state: 'DATA' as IExtendedSmtpSession['state'],
+      mailFrom: fromArg,
+      rcptTo: recipientsArg,
+      emailData: rawMessageArg,
+      useTLS: true,
+      connectionEnded: false,
+      remoteAddress: '127.0.0.1',
+      clientHostname: 'typed-service-mail',
+      secure: true,
+      authenticated: true,
+      user: {
+        username: identityArg.smtp.username,
+      },
+      envelope: {
+        mailFrom: { address: fromArg, args: {} },
+        rcptTo: recipientsArg.map((recipientArg) => ({ address: recipientArg, args: {} })),
+      },
+    } as IExtendedSmtpSession;
+  }
+
+  private buildOutboundRawMessage(
+    identityArg: IStoredWorkAppMailIdentity,
+    messageArg: plugins.servezoneInterfaces.data.IMailOutboundMessagePayload,
+  ): string {
+    const from = this.normalizeAddress(messageArg.from);
+    if (from !== identityArg.address) {
+      throw new Error('Mail credential is not authorized for this From address');
+    }
+    if (!messageArg.text && !messageArg.html) {
+      throw new Error('Either text or html is required');
+    }
+    const messageId = `<${plugins.crypto.randomUUID()}@${identityArg.domain}>`;
+    const headers: Record<string, string> = {
+      From: identityArg.address,
+      To: messageArg.to.join(', '),
+      ...(messageArg.cc?.length ? { Cc: messageArg.cc.join(', ') } : {}),
+      Subject: messageArg.subject,
+      Date: new Date().toUTCString(),
+      'Message-ID': messageId,
+      'MIME-Version': '1.0',
+    };
+    for (const [keyArg, valueArg] of Object.entries(messageArg.headers || {})) {
+      const headerKey = this.sanitizeHeaderKey(keyArg);
+      if (this.isProtectedOutboundHeader(headerKey)) {
+        throw new Error(`Custom mail header is not allowed to override ${headerKey}`);
+      }
+      headers[headerKey] = String(valueArg);
+    }
+    const body = this.buildMimeBody(messageArg, headers);
+    return `${Object.entries(headers)
+      .map(([keyArg, valueArg]) => `${this.sanitizeHeaderKey(keyArg)}: ${this.sanitizeHeaderValue(valueArg)}`)
+      .join('\r\n')}\r\n\r\n${body}`;
+  }
+
+  private buildMimeBody(
+    messageArg: plugins.servezoneInterfaces.data.IMailOutboundMessagePayload,
+    headersArg: Record<string, string>,
+  ): string {
+    const attachments = messageArg.attachments || [];
+    if (attachments.length === 0) {
+      return this.buildTextHtmlPart(messageArg, headersArg);
+    }
+    const mixedBoundary = `mixed-${plugins.crypto.randomBytes(12).toString('hex')}`;
+    headersArg['Content-Type'] = `multipart/mixed; boundary="${mixedBoundary}"`;
+    const parts = [`--${mixedBoundary}\r\n${this.buildBodyPart(messageArg)}`];
+    for (const attachment of attachments) {
+      parts.push(`--${mixedBoundary}\r\n${this.buildAttachmentPart(attachment)}`);
+    }
+    parts.push(`--${mixedBoundary}--`);
+    return parts.join('\r\n');
+  }
+
+  private buildTextHtmlPart(
+    messageArg: plugins.servezoneInterfaces.data.IMailOutboundMessagePayload,
+    headersArg: Record<string, string>,
+  ): string {
+    if (messageArg.text && messageArg.html) {
+      const boundary = `alternative-${plugins.crypto.randomBytes(12).toString('hex')}`;
+      headersArg['Content-Type'] = `multipart/alternative; boundary="${boundary}"`;
+      return [
+        `--${boundary}`,
+        'Content-Type: text/plain; charset=utf-8',
+        'Content-Transfer-Encoding: 8bit',
+        '',
+        this.normalizeNewlines(messageArg.text),
+        `--${boundary}`,
+        'Content-Type: text/html; charset=utf-8',
+        'Content-Transfer-Encoding: 8bit',
+        '',
+        this.normalizeNewlines(messageArg.html),
+        `--${boundary}--`,
+      ].join('\r\n');
+    }
+    headersArg['Content-Type'] = `${messageArg.html ? 'text/html' : 'text/plain'}; charset=utf-8`;
+    headersArg['Content-Transfer-Encoding'] = '8bit';
+    return this.normalizeNewlines(messageArg.html || messageArg.text || '');
+  }
+
+  private buildBodyPart(messageArg: plugins.servezoneInterfaces.data.IMailOutboundMessagePayload): string {
+    const headers: Record<string, string> = {};
+    const body = this.buildTextHtmlPart(messageArg, headers);
+    return `${Object.entries(headers).map(([keyArg, valueArg]) => `${keyArg}: ${valueArg}`).join('\r\n')}\r\n\r\n${body}`;
+  }
+
+  private buildAttachmentPart(attachmentArg: plugins.servezoneInterfaces.data.IMailOutboundAttachmentPayload): string {
+    const filename = this.sanitizeHeaderValue(attachmentArg.filename);
+    return [
+      `Content-Type: ${attachmentArg.contentType || 'application/octet-stream'}; name="${filename}"`,
+      'Content-Transfer-Encoding: base64',
+      `Content-Disposition: attachment; filename="${filename}"`,
+      '',
+      this.wrapBase64(attachmentArg.binaryAttachmentString),
+    ].join('\r\n');
+  }
+
+  private getMessageRecipients(messageArg: plugins.servezoneInterfaces.data.IMailOutboundMessagePayload): string[] {
+    const recipients = [
+      ...(messageArg.to || []),
+      ...(messageArg.cc || []),
+      ...(messageArg.bcc || []),
+    ].map((recipientArg) => this.normalizeAddress(recipientArg));
+    if (recipients.length === 0) {
+      throw new Error('At least one mail recipient is required');
+    }
+    return recipients;
+  }
+
+  private toMailOutboundIdentity(
+    identityArg: IStoredWorkAppMailIdentity,
+  ): plugins.servezoneInterfaces.data.IMailOutboundIdentity {
+    return {
+      id: identityArg.smtp.username,
+      owner: this.toMailOwner(identityArg.ownership),
+      enabled: identityArg.enabled && identityArg.smtp.enabled,
+      status: identityArg.enabled && identityArg.smtp.enabled ? 'active' : 'disabled',
+      allowedFromPatterns: [{ type: 'exactAddress', domain: identityArg.domain, localPart: identityArg.localPart }],
+      defaultFrom: identityArg.address,
+      domain: identityArg.domain,
+      dkimSelector: 'default',
+      credential: this.toMailCredentialPublic(identityArg),
+      createdAt: identityArg.createdAt,
+      updatedAt: identityArg.updatedAt,
+      createdBy: identityArg.createdBy,
+    };
+  }
+
+  private extractHeaders(rawMessageArg: string): Record<string, string | string[]> {
+    const headers: Record<string, string | string[]> = {};
+    const headerText = rawMessageArg.split(/\r?\n\r?\n/, 1)[0] || '';
+    let currentHeader = '';
+    for (const line of headerText.split(/\r?\n/)) {
+      if (/^[\t ]/.test(line) && currentHeader) {
+        headers[currentHeader] = `${headers[currentHeader] || ''} ${line.trim()}`;
+        continue;
+      }
+      const separatorIndex = line.indexOf(':');
+      if (separatorIndex < 1) continue;
+      currentHeader = line.slice(0, separatorIndex).trim();
+      const value = line.slice(separatorIndex + 1).trim();
+      const existing = headers[currentHeader];
+      if (Array.isArray(existing)) {
+        existing.push(value);
+      } else if (existing) {
+        headers[currentHeader] = [String(existing), value];
+      } else {
+        headers[currentHeader] = value;
+      }
+    }
+    return headers;
+  }
+
+  private extractHeader(rawMessageArg: string, headerNameArg: string): string | undefined {
+    const lowerName = `${headerNameArg.toLowerCase()}:`;
+    for (const line of rawMessageArg.split(/\r?\n/)) {
+      if (!line) return undefined;
+      if (line.toLowerCase().startsWith(lowerName)) {
+        return line.slice(lowerName.length).trim();
+      }
+    }
+  }
+
+  private sanitizeHeaderKey(valueArg: string): string {
+    if (!/^[a-z0-9-]+$/i.test(valueArg)) {
+      throw new Error(`Invalid header key: ${valueArg}`);
+    }
+    return valueArg;
+  }
+
+  private isProtectedOutboundHeader(valueArg: string): boolean {
+    return new Set([
+      'bcc',
+      'cc',
+      'content-disposition',
+      'content-transfer-encoding',
+      'content-type',
+      'date',
+      'dkim-signature',
+      'from',
+      'message-id',
+      'mime-version',
+      'received',
+      'reply-to',
+      'resent-from',
+      'resent-sender',
+      'return-path',
+      'sender',
+      'subject',
+      'to',
+    ]).has(valueArg.toLowerCase());
+  }
+
+  private sanitizeHeaderValue(valueArg: string): string {
+    return String(valueArg).replace(/[\r\n]+/g, ' ').trim();
+  }
+
+  private normalizeNewlines(valueArg: string): string {
+    return valueArg.replace(/\r?\n/g, '\r\n');
+  }
+
+  private wrapBase64(valueArg: string): string {
+    return valueArg.match(/.{1,76}/g)?.join('\r\n') || '';
+  }
+
+  private buildServiceMailAddressTag(addressArg: string): string {
+    return `serviceMailAddress:${this.normalizeAddress(addressArg)}`;
+  }
+
   private matchesOwnership(
     ownership: interfaces.data.IWorkAppMailOwnership,
     filter?: Partial<interfaces.data.IWorkAppMailOwnership>,
@@ -794,7 +1298,7 @@ export class WorkAppMailManager {
       domain: identity.domain,
       enabled: identity.enabled,
       status: identity.enabled ? 'active' : 'disabled',
-      inboundTarget: this.toMailInboundTarget(identity.inbound),
+      inboundTarget: this.getCanonicalInboundTarget(identity as IStoredWorkAppMailIdentity),
       outboundIdentityId: identity.smtp.enabled ? identity.smtp.username : undefined,
       ...(identity.smtp.enabled ? {
         outboundCredential: this.toMailCredentialPublic(identity as IStoredWorkAppMailIdentity),
@@ -825,7 +1329,7 @@ export class WorkAppMailManager {
       addressBindingIds: identities.map((identity) => identity.id),
       outboundIdentityIds: smtpIdentities.map((identity) => identity.smtp.username),
       defaultFrom: enabledIdentities[0]?.address || firstIdentity.address,
-      inboundTarget: identities.length === 1 ? this.toMailInboundTarget(firstIdentity.inbound) : undefined,
+      inboundTarget: identities.length === 1 ? this.getCanonicalInboundTarget(firstIdentity) : undefined,
       createdAt: Math.min(...identities.map((identity) => identity.createdAt)),
       updatedAt: Math.max(...identities.map((identity) => identity.updatedAt)),
       createdBy: firstIdentity.createdBy,

package/ts/opsserver/handlers/gatewayclient.handler.ts

@@ -314,6 +314,41 @@ export class GatewayClientHandler {
         },
       ),
     );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.mail.IReq_EnqueueMail>(
+        'enqueueMail',
+        async (dataArg) => {
+          const manager = this.opsServerRef.dcRouterRef.workAppMailManager;
+          if (!manager) {
+            return { accepted: false, message: 'WorkApp mail manager not initialized' };
+          }
+          return await manager.enqueueMail(
+            dataArg.auth || {},
+            dataArg.message,
+            dataArg.outboundIdentityId,
+          );
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.mail.IReq_RegisterServiceMailEndpoint>(
+        'registerServiceMailEndpoint',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.workAppMailManager;
+          if (!manager) {
+            return { success: false, message: 'WorkApp mail manager not initialized' };
+          }
+          const peer = toolsArg?.localData?.peer as { tags?: Set<string> } | undefined;
+          return await manager.registerServiceMailEndpoint(
+            dataArg.auth || {},
+            peer as { tags?: Set<string> },
+            dataArg.addresses,
+          );
+        },
+      ),
+    );
   }
 
   private getGatewayCapabilities(): plugins.servezoneInterfaces.data.IGatewayCapabilities {

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/dcrouter',
-  version: '15.4.1',
+  version: '15.6.0',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }