@serve.zone/dcrouter 18.4.1 → 18.6.0

package/dist_ts_web/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/dcrouter',
-    version: '18.4.1',
+    version: '18.6.0',
     description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHNfd2ViLzAwX2NvbW1pdGluZm9fZGF0YS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7R0FFRztBQUNILE1BQU0sQ0FBQyxNQUFNLFVBQVUsR0FBRztJQUN4QixJQUFJLEVBQUUsc0JBQXNCO0lBQzVCLE9BQU8sRUFBRSxRQUFRO0lBQ2pCLFdBQVcsRUFBRSwwRUFBMEU7Q0FDeEYsQ0FBQSJ9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@serve.zone/dcrouter",
   "private": false,
-  "version": "18.4.1",
+  "version": "18.6.0",
   "description": "A multifaceted routing service handling mail and SMS delivery functions.",
   "type": "module",
   "bin": {
@@ -64,7 +64,7 @@
     "@push.rocks/smartvpn": "1.22.0",
     "@push.rocks/taskbuffer": "^8.0.2",
     "@serve.zone/catalog": "^2.21.1",
-    "@serve.zone/interfaces": "^19.2.0",
+    "@serve.zone/interfaces": "^19.8.0",
     "@serve.zone/remoteingress": "^5.1.0",
     "@tsclass/tsclass": "^9.5.1",
     "@types/qrcode": "^1.5.6",

package/readme.md

@@ -472,7 +472,7 @@ await route.toggle(true);
 
 Use `@serve.zone/dcrouter/interfaces` or `@serve.zone/dcrouter-interfaces` when you want dcrouter-local raw TypedRequest contracts instead of resource managers. Use `@serve.zone/interfaces` for the canonical machine-facing gateway client route, DNS, domain, and mail contracts shared with Onebox and Cloudly.
 
-Gateway-client mail contracts let Cloudly or Onebox claim exact app addresses, attach inbound `smtpForward` targets, enable managed outbound SMTP credentials, rotate those credentials, enqueue service mail, and query delivery status through TypedRequest. Managed SMTP users can only send as their exact claimed address; mismatched envelope or header `From` values are rejected before relay. Delivery status queries return the dcrouter spool item state, including deferred SmartMTA errors and next retry timestamps when outbound delivery is temporarily delayed.
+Gateway-client mail contracts let Cloudly or Onebox claim exact app addresses, attach inbound `smtpForward` targets, enable managed outbound SMTP credentials, rotate those credentials, enqueue service mail, and query delivery status through TypedRequest. `getGatewayClientMailDomainCount` requires an authenticated, enabled gateway-client credential with the `gateway-clients:read` scope and `readMail` capability. It returns only that credential owner's distinct domain count; it does not accept a caller-selected owner and does not load bindings, DNS details, or recent mail. Managed SMTP users can only send as their exact claimed address; mismatched envelope or header `From` values are rejected before relay. Typed submissions may set `replyTo` to one bare printable-ASCII mailbox address. Dcrouter validates it authoritatively and renders one `Reply-To` header; custom headers remain unable to override `Reply-To` or any other protected MIME field. Delivery status queries return the dcrouter spool item state, including deferred SmartMTA errors and next retry timestamps when outbound delivery is temporarily delayed.
 
 ### Email Operations Views
 

package/ts/00_commitinfo_data.ts

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

package/ts/classes.dcrouter.ts

@@ -42,7 +42,7 @@ import { DomainOwnershipError } from './dns/domain-ownership.js';
 import { AcmeConfigManager } from './acme/manager.acme-config.js';
 import { SmartAcmeLifecycle } from './acme/classes.smartacme-lifecycle.js';
 import { AcmePermanentFailureError, classifyAcmeFailure } from './acme/acme-failure-classification.js';
-import { AcceptedEmailSpool, EmailDomainManager, EmailRouteBuilder, EmailSettingsManager, MailDnsSync, MailEdgeEligibility, MailEgressCoordinator, ReleasedRemoteIngressEgressIdentitySource, SmartMtaBlobStorageManager, SmartMtaStorageManager, SmtpAccountManager, WorkAppMailManager, type ISmartMtaBlobStorageConfig, type TSmartMtaQueueItemLike } from './email/index.js';
+import { AcceptedEmailSpool, EmailDomainManager, EmailRouteBuilder, EmailSettingsManager, GatewayMailDomainStore, MailDnsSync, MailEdgeEligibility, MailEgressCoordinator, ReleasedRemoteIngressEgressIdentitySource, SmartMtaBlobStorageManager, SmartMtaStorageManager, SmtpAccountManager, WorkAppMailManager, type ISmartMtaBlobStorageConfig, type TSmartMtaQueueItemLike } from './email/index.js';
 import { WebPushManager } from './webpush/index.js';
 import type { IRoute } from '../ts_interfaces/data/route-management.js';
 import type { IEmailOutboundEgressStatus, IEmailPortConfig, IEmailServerSettings, IEmailServerSettingsSeed, TEmailOutboundMode, TEmailServerSettingsUpdate } from '../ts_interfaces/data/email-settings.js';
@@ -355,6 +355,7 @@ export class DcRouter {
   public acmeConfigManager?: AcmeConfigManager;
   public emailSettingsManager?: EmailSettingsManager;
   public emailDomainManager?: EmailDomainManager;
+  public gatewayMailDomainStore: GatewayMailDomainStore;
   public workAppMailManager: WorkAppMailManager;
   /** Single composition owner of the email runtime auth block and route list. */
   public smtpAccountManager: SmtpAccountManager;
@@ -427,6 +428,7 @@ export class DcRouter {
 
     // Resolve all data paths from baseDir
     this.resolvedPaths = paths.resolvePaths(this.options.baseDir);
+    this.gatewayMailDomainStore = new GatewayMailDomainStore();
     this.workAppMailManager = new WorkAppMailManager(this);
     this.smtpAccountManager = new SmtpAccountManager(this);
     this.acceptedEmailSpool = new AcceptedEmailSpool(this);

package/ts/db/documents/classes.gateway-mail-domain.doc.ts

@@ -0,0 +1,42 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { TGatewayClientType } from '../../../ts_interfaces/data/route-management.js';
+import type { IStoredWorkAppMailIdentity } from '../../email/gateway-mail-domain-authority.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+/**
+ * Authoritative WorkApp mail identity storage, grouped so one document equals
+ * one distinct gateway-client-owned mail domain.
+ */
+@plugins.smartdata.Collection(() => getDb())
+export class GatewayMailDomainDoc extends plugins.smartdata.SmartDataDbDoc<
+  GatewayMailDomainDoc,
+  GatewayMailDomainDoc
+> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.index()
+  @plugins.smartdata.svDb()
+  public ownerGatewayClientType!: TGatewayClientType;
+
+  @plugins.smartdata.index()
+  @plugins.smartdata.svDb()
+  public ownerGatewayClientId!: string;
+
+  @plugins.smartdata.index()
+  @plugins.smartdata.svDb()
+  public domain!: string;
+
+  @plugins.smartdata.svDb()
+  public identities: IStoredWorkAppMailIdentity[] = [];
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+}
+

package/ts/db/documents/index.ts

@@ -43,6 +43,7 @@ export * from './classes.acme-config.doc.js';
 
 // Email domain management
 export * from './classes.email-domain.doc.js';
+export * from './classes.gateway-mail-domain.doc.js';
 export * from './classes.email-server-settings.doc.js';
 export * from './classes.smtp-account.doc.js';
 

package/ts/email/classes.gateway-mail-domain.store.ts

@@ -0,0 +1,89 @@
+import { DcRouterDb } from '../db/classes.dcrouter-db.js';
+import { GatewayMailDomainDoc } from '../db/documents/classes.gateway-mail-domain.doc.js';
+import {
+  createGatewayMailDomainId,
+  groupGatewayMailIdentities,
+  normalizeGatewayMailDomain,
+  normalizeGatewayMailDomainOwner,
+  type IGatewayMailDomainOwner,
+  type IStoredWorkAppMailIdentity,
+} from './gateway-mail-domain-authority.js';
+
+export interface IGatewayMailDomainStore {
+  readAllIdentities(): Promise<IStoredWorkAppMailIdentity[]>;
+  writeAllIdentities(identitiesArg: IStoredWorkAppMailIdentity[]): Promise<IStoredWorkAppMailIdentity[]>;
+  countDomains(ownerArg: IGatewayMailDomainOwner): Promise<number>;
+}
+
+const validateDocument = (documentArg: GatewayMailDomainDoc): IStoredWorkAppMailIdentity[] => {
+  const owner = normalizeGatewayMailDomainOwner({
+    gatewayClientType: documentArg.ownerGatewayClientType,
+    gatewayClientId: documentArg.ownerGatewayClientId,
+  });
+  const domain = normalizeGatewayMailDomain(documentArg.domain);
+  const expectedId = createGatewayMailDomainId(owner, domain);
+  if (documentArg.id !== expectedId) {
+    throw new Error(`GatewayMailDomainDoc has a non-canonical id: ${documentArg.id}`);
+  }
+  const groups = groupGatewayMailIdentities(documentArg.identities || []);
+  if (groups.length !== 1 || groups[0].id !== expectedId) {
+    throw new Error(`GatewayMailDomainDoc identities do not match owner/domain: ${documentArg.id}`);
+  }
+  return groups[0].identities;
+};
+
+export class GatewayMailDomainStore implements IGatewayMailDomainStore {
+  public async readAllIdentities(): Promise<IStoredWorkAppMailIdentity[]> {
+    const documents = await GatewayMailDomainDoc.getInstances({});
+    const identities = documents.flatMap((documentArg) => validateDocument(documentArg));
+    return groupGatewayMailIdentities(identities).flatMap((groupArg) => groupArg.identities);
+  }
+
+  public async writeAllIdentities(
+    identitiesArg: IStoredWorkAppMailIdentity[],
+  ): Promise<IStoredWorkAppMailIdentity[]> {
+    const desiredGroups = groupGatewayMailIdentities(identitiesArg);
+    const desiredById = new Map(desiredGroups.map((groupArg) => [groupArg.id, groupArg]));
+    const db = DcRouterDb.getInstance().getDb();
+    const session = db.startSession();
+    try {
+      await session.withTransaction(async () => {
+        const existingDocuments = await GatewayMailDomainDoc.getInstances({}, { session });
+        const existingById = new Map(existingDocuments.map((documentArg) => {
+          validateDocument(documentArg);
+          return [documentArg.id, documentArg];
+        }));
+        const now = Date.now();
+
+        for (const group of desiredGroups) {
+          const document = existingById.get(group.id) || new GatewayMailDomainDoc();
+          document.id = group.id;
+          document.ownerGatewayClientType = group.gatewayClientType;
+          document.ownerGatewayClientId = group.gatewayClientId;
+          document.domain = group.domain;
+          document.identities = group.identities;
+          document.createdAt = document.createdAt || now;
+          document.updatedAt = now;
+          await document.save({ session });
+        }
+        for (const existingDocument of existingDocuments) {
+          if (!desiredById.has(existingDocument.id)) {
+            await existingDocument.delete({ session });
+          }
+        }
+      });
+    } finally {
+      await session.endSession();
+    }
+
+    return await this.readAllIdentities();
+  }
+
+  public async countDomains(ownerArg: IGatewayMailDomainOwner): Promise<number> {
+    const owner = normalizeGatewayMailDomainOwner(ownerArg);
+    return await GatewayMailDomainDoc.getCount({
+      ownerGatewayClientType: owner.gatewayClientType,
+      ownerGatewayClientId: owner.gatewayClientId,
+    });
+  }
+}

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

@@ -4,7 +4,6 @@ import type {
   IMessageAcceptanceContext,
   IMessageAcceptanceDecision,
   IUnifiedEmailServerOptions,
-  IStorageManagerLike,
 } from '@push.rocks/smartmta';
 import type { Buffer } from 'node:buffer';
 import * as plugins from '../plugins.js';
@@ -12,6 +11,12 @@ import { CachedEmail } from '../db/index.js';
 import type { ICachedEmailSmtpTransaction } from '../db/documents/classes.cached.email.js';
 import type { DcRouter } from '../classes.dcrouter.js';
 import type * as interfaces from '../../ts_interfaces/index.js';
+import { GatewayMailDomainStore, type IGatewayMailDomainStore } from './classes.gateway-mail-domain.store.js';
+import {
+  normalizeGatewayMailDomain,
+  normalizeGatewayMailDomainOwner,
+  type IStoredWorkAppMailIdentity,
+} from './gateway-mail-domain-authority.js';
 
 type TSyncRequest = {
   ownership: interfaces.data.IWorkAppMailOwnership;
@@ -32,6 +37,7 @@ type TMailAddressBindingSyncResponse = plugins.servezoneInterfaces.requests.mail
 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 TMailSubmissionErrorCode = plugins.servezoneInterfaces.data.TMailSubmissionErrorCode;
 type TMailDeliveryStatusResponse = plugins.servezoneInterfaces.requests.mail.IReq_GetMailDeliveryStatus['response'];
 type TMailEndpointRegistrationResponse = plugins.servezoneInterfaces.requests.mail.IReq_RegisterServiceMailEndpoint['response'];
 type TWorkAppMailBinding = plugins.servezoneInterfaces.data.IWorkAppMailBinding;
@@ -66,31 +72,14 @@ type TCachedEmailRouteData = {
   };
 };
 
-interface IStoredWorkAppMailIdentity {
-  id: string;
-  externalKey: string;
-  ownership: interfaces.data.IWorkAppMailOwnership;
-  address: string;
-  localPart: string;
-  domain: string;
-  enabled: boolean;
-  displayName?: string;
-  inbound?: interfaces.data.IWorkAppMailInboundRoute;
-  inboundTarget?: plugins.servezoneInterfaces.data.IMailInboundTarget;
-  smtp: {
-    enabled: boolean;
-    username: string;
-  };
-  createdAt: number;
-  updatedAt: number;
-  createdBy: string;
-  smtpPassword: string;
-  smtpLastRotatedAt?: number;
-}
-
-interface IStoredWorkAppMailState {
-  version: 1;
-  identities: IStoredWorkAppMailIdentity[];
+class MailSubmissionValidationError extends Error {
+  constructor(
+    public readonly code: TMailSubmissionErrorCode,
+    messageArg: string,
+  ) {
+    super(messageArg);
+    this.name = 'MailSubmissionValidationError';
+  }
 }
 
 /**
@@ -114,10 +103,13 @@ export function isWorkAppManagedSmtpUsername(username: string): boolean {
 }
 
 export class WorkAppMailManager {
-  private readonly storageKey = '/workhosters/mail-identities.json';
+  private readonly emailValidator = new plugins.smartmta.Core.EmailValidator();
+  private readonly gatewayMailDomainStore: IGatewayMailDomainStore;
   private identityMutationPromise: Promise<unknown> = Promise.resolve();
 
-  constructor(private dcRouterRef: DcRouter) {}
+  constructor(private dcRouterRef: DcRouter) {
+    this.gatewayMailDomainStore = dcRouterRef.gatewayMailDomainStore || new GatewayMailDomainStore();
+  }
 
   public async listMailIdentities(
     ownership?: Partial<interfaces.data.IWorkAppMailOwnership>,
@@ -164,8 +156,8 @@ export class WorkAppMailManager {
         return { success: true, action: 'unchanged' };
       }
       const [deletedIdentity] = identities.splice(existingIndex, 1);
-      await this.writeStoredIdentities(identities);
-      await this.applyStoredIdentitiesToRuntime(identities);
+      const persistedIdentities = await this.writeStoredIdentities(identities);
+      await this.applyStoredIdentitiesToRuntime(persistedIdentities);
       return {
         success: true,
         action: 'deleted',
@@ -215,8 +207,8 @@ export class WorkAppMailManager {
       identities.push(identity);
     }
 
-    await this.writeStoredIdentities(identities);
-    await this.applyStoredIdentitiesToRuntime(identities);
+    const persistedIdentities = await this.writeStoredIdentities(identities);
+    await this.applyStoredIdentitiesToRuntime(persistedIdentities);
 
     const response: interfaces.data.IWorkAppMailIdentitySyncResult = {
       success: true,
@@ -267,6 +259,14 @@ export class WorkAppMailManager {
     return Array.from(groups.values()).map((group) => this.toWorkAppMailBinding(group));
   }
 
+  public async countMailDomains(
+    ownerArg: Pick<TMailResourceOwner, 'gatewayClientType' | 'gatewayClientId'>,
+  ): Promise<number> {
+    return await this.gatewayMailDomainStore.countDomains(
+      normalizeGatewayMailDomainOwner(ownerArg),
+    );
+  }
+
   public async syncMailAddressBinding(
     binding: TMailAddressBindingSync,
     createdBy: string,
@@ -357,12 +357,14 @@ export class WorkAppMailManager {
       updatedAt: now,
     };
 
-    await this.writeStoredIdentities(identities);
-    await this.applyStoredIdentitiesToRuntime(identities);
+    const persistedIdentities = await this.writeStoredIdentities(identities);
+    await this.applyStoredIdentitiesToRuntime(persistedIdentities);
 
     return {
       success: true,
-      credential: this.toMailCredentialSecret(identities[identityIndex]),
+      credential: this.toMailCredentialSecret(
+        persistedIdentities.find((identityArg) => identityArg.id === identity.id)!,
+      ),
     };
   }
 
@@ -459,6 +461,7 @@ export class WorkAppMailManager {
     } catch (error) {
       return {
         accepted: false,
+        ...(error instanceof MailSubmissionValidationError ? { errorCode: error.code } : {}),
         message: (error as Error).message,
       };
     }
@@ -722,36 +725,13 @@ export class WorkAppMailManager {
   }
 
   private async readStoredIdentities(): Promise<IStoredWorkAppMailIdentity[]> {
-    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 || [];
+    return await this.gatewayMailDomainStore.readAllIdentities();
   }
 
-  private async writeStoredIdentities(identities: IStoredWorkAppMailIdentity[]): Promise<void> {
-    const state: IStoredWorkAppMailState = {
-      version: 1,
-      identities,
-    };
-    const storageManager = this.getRequiredStorageManager();
-    await storageManager.set(this.storageKey, JSON.stringify(state, null, 2));
-  }
-
-  private getRequiredStorageManager(): IStorageManagerLike & Required<
-    Pick<IStorageManagerLike, 'get' | 'set'>
-  > {
-    const storageManager = this.dcRouterRef.storageManager;
-    if (
-      !storageManager
-      || typeof storageManager.get !== 'function'
-      || typeof storageManager.set !== 'function'
-    ) {
-      throw new Error('DcRouter storage manager does not support managed mail identity persistence');
-    }
-    return storageManager as IStorageManagerLike & Required<
-      Pick<IStorageManagerLike, 'get' | 'set'>
-    >;
+  private async writeStoredIdentities(
+    identities: IStoredWorkAppMailIdentity[],
+  ): Promise<IStoredWorkAppMailIdentity[]> {
+    return await this.gatewayMailDomainStore.writeAllIdentities(identities);
   }
 
   private buildInboundRoute(identity: IStoredWorkAppMailIdentity): IEmailRoute {
@@ -898,11 +878,7 @@ export class WorkAppMailManager {
   }
 
   private normalizeDomain(domain: string): string {
-    const normalized = domain?.trim().toLowerCase();
-    if (!normalized || normalized.includes('@') || !normalized.includes('.')) {
-      throw new Error(`Invalid email domain: ${domain}`);
-    }
-    return normalized;
+    return normalizeGatewayMailDomain(domain);
   }
 
   private normalizeLocalPart(localPart: string): string {
@@ -1341,11 +1317,23 @@ export class WorkAppMailManager {
     if (!messageArg.text && !messageArg.html) {
       throw new Error('Either text or html is required');
     }
+    const customReplyToHeader = Object.keys(messageArg.headers || {})
+      .find((keyArg) => keyArg.toLowerCase() === 'reply-to');
+    if (messageArg.replyTo !== undefined && customReplyToHeader) {
+      throw new MailSubmissionValidationError(
+        'REPLY_TO_FIELD_HEADER_CONFLICT',
+        'replyTo cannot be combined with a custom Reply-To header',
+      );
+    }
+    const replyTo = messageArg.replyTo === undefined
+      ? undefined
+      : this.validateReplyTo(messageArg.replyTo);
     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(', ') } : {}),
+      ...(replyTo ? { 'Reply-To': replyTo } : {}),
       Subject: messageArg.subject,
       Date: new Date().toUTCString(),
       'Message-ID': messageId,
@@ -1521,6 +1509,40 @@ export class WorkAppMailManager {
     ]).has(valueArg.toLowerCase());
   }
 
+  private validateReplyTo(valueArg: unknown): string {
+    const invalid = (): never => {
+      throw new MailSubmissionValidationError(
+        'INVALID_REPLY_TO',
+        'replyTo must be one bare printable ASCII mailbox address',
+      );
+    };
+    if (
+      typeof valueArg !== 'string'
+      || valueArg.length === 0
+      || valueArg.length > 254
+      || !/^[\x21-\x7e]+$/.test(valueArg)
+      || /[(),:;<>"[\]\\]/.test(valueArg)
+    ) {
+      return invalid();
+    }
+    const parts = valueArg.split('@');
+    if (parts.length !== 2) return invalid();
+    const [localPart, domain] = parts;
+    if (!localPart || localPart.length > 64 || !domain) return invalid();
+    const domainLabels = domain.split('.');
+    if (
+      domainLabels.some((labelArg) => (
+        labelArg.length === 0
+        || labelArg.length > 63
+        || !/^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/.test(labelArg)
+      ))
+      || !this.emailValidator.isValidFormat(valueArg)
+    ) {
+      return invalid();
+    }
+    return valueArg;
+  }
+
   private sanitizeHeaderValue(valueArg: string): string {
     return String(valueArg).replace(/[\r\n]+/g, ' ').trim();
   }