@serve.zone/dcrouter 18.5.0 → 18.6.0

package/dist_ts_web/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/dcrouter',
-    version: '18.5.0',
+    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.5.0",
+  "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.7.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. 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.
+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.5.0',
+  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;
@@ -77,33 +82,6 @@ class MailSubmissionValidationError extends Error {
   }
 }
 
-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[];
-}
-
 /**
  * WorkApp-generated routes and SMTP users contributed to the composed email
  * runtime config. Consumed by SmtpAccountManager, the single owner of the
@@ -125,11 +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>,
@@ -176,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',
@@ -227,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,
@@ -279,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,
@@ -369,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)!,
+      ),
     };
   }
 
@@ -735,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 || [];
-  }
-
-  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));
+    return await this.gatewayMailDomainStore.readAllIdentities();
   }
 
-  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 {
@@ -911,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 {

package/ts/email/gateway-mail-domain-authority.ts

@@ -0,0 +1,222 @@
+import * as plugins from '../plugins.js';
+import type {
+  IWorkAppMailInboundRoute,
+  IWorkAppMailOwnership,
+} from '../../ts_interfaces/data/workhoster.js';
+import type { TGatewayClientType } from '../../ts_interfaces/data/route-management.js';
+
+export interface IStoredWorkAppMailIdentity {
+  id: string;
+  externalKey: string;
+  ownership: IWorkAppMailOwnership;
+  address: string;
+  localPart: string;
+  domain: string;
+  enabled: boolean;
+  displayName?: string;
+  inbound?: IWorkAppMailInboundRoute;
+  inboundTarget?: plugins.servezoneInterfaces.data.IMailInboundTarget;
+  smtp: {
+    enabled: boolean;
+    username: string;
+  };
+  createdAt: number;
+  updatedAt: number;
+  createdBy: string;
+  smtpPassword: string;
+  smtpLastRotatedAt?: number;
+}
+
+export interface IGatewayMailDomainOwner {
+  gatewayClientType: TGatewayClientType;
+  gatewayClientId: string;
+}
+
+export interface IGatewayMailDomainGroup extends IGatewayMailDomainOwner {
+  id: string;
+  domain: string;
+  identities: IStoredWorkAppMailIdentity[];
+}
+
+const gatewayClientTypes = new Set<TGatewayClientType>(['onebox', 'cloudly', 'custom']);
+
+const requireTrimmedString = (valueArg: unknown, fieldNameArg: string): string => {
+  const value = typeof valueArg === 'string' ? valueArg.trim() : '';
+  if (!value) throw new Error(`${fieldNameArg} is required`);
+  return value;
+};
+
+const requireTimestamp = (valueArg: unknown, fieldNameArg: string): number => {
+  if (!Number.isSafeInteger(valueArg) || Number(valueArg) < 0) {
+    throw new Error(`${fieldNameArg} must be a non-negative safe integer`);
+  }
+  return Number(valueArg);
+};
+
+export function normalizeGatewayMailDomain(domainArg: unknown): string {
+  const candidate = typeof domainArg === 'string'
+    ? domainArg.trim().toLowerCase().replace(/\.+$/, '')
+    : '';
+  if (!candidate || candidate.includes('@') || !candidate.includes('.')) {
+    throw new Error(`Invalid email domain: ${String(domainArg || '')}`);
+  }
+  const ascii = plugins.url.domainToASCII(candidate);
+  if (!ascii || ascii.includes('@') || !ascii.includes('.')) {
+    throw new Error(`Invalid email domain: ${String(domainArg || '')}`);
+  }
+  return ascii;
+}
+
+export function normalizeGatewayMailDomainOwner(
+  ownerArg: {
+    gatewayClientType?: unknown;
+    gatewayClientId?: unknown;
+  },
+): IGatewayMailDomainOwner {
+  const gatewayClientType = ownerArg?.gatewayClientType as TGatewayClientType;
+  if (!gatewayClientTypes.has(gatewayClientType)) {
+    throw new Error(`Invalid gateway client type: ${String(ownerArg?.gatewayClientType || '')}`);
+  }
+  return {
+    gatewayClientType,
+    gatewayClientId: requireTrimmedString(ownerArg.gatewayClientId, 'gatewayClientId'),
+  };
+}
+
+export function gatewayMailOwnerFromLegacyOwnership(
+  ownershipArg: IWorkAppMailOwnership,
+): IGatewayMailDomainOwner & { appInstanceId: string } {
+  const owner = normalizeGatewayMailDomainOwner({
+    gatewayClientType: ownershipArg?.workHosterType,
+    gatewayClientId: ownershipArg?.workHosterId,
+  });
+  return {
+    ...owner,
+    appInstanceId: requireTrimmedString(ownershipArg?.workAppId, 'appInstanceId'),
+  };
+}
+
+export function createGatewayMailDomainId(
+  ownerArg: IGatewayMailDomainOwner,
+  domainArg: string,
+): string {
+  const owner = normalizeGatewayMailDomainOwner(ownerArg);
+  const domain = normalizeGatewayMailDomain(domainArg);
+  const digest = plugins.crypto.createHash('sha256')
+    .update(JSON.stringify([owner.gatewayClientType, owner.gatewayClientId, domain]))
+    .digest('hex');
+  return `gateway-mail-domain-${digest}`;
+}
+
+export function normalizeStoredWorkAppMailIdentity(
+  identityArg: unknown,
+): IStoredWorkAppMailIdentity {
+  if (!identityArg || typeof identityArg !== 'object' || Array.isArray(identityArg)) {
+    throw new Error('Stored WorkApp mail identity must be an object');
+  }
+  const identity = identityArg as Record<string, any>;
+  const owner = gatewayMailOwnerFromLegacyOwnership(identity.ownership);
+  const domain = normalizeGatewayMailDomain(identity.domain);
+  const localPart = requireTrimmedString(identity.localPart, 'localPart').toLowerCase();
+  if (localPart.includes('@') || /\s/.test(localPart)) {
+    throw new Error(`Invalid email local part: ${identity.localPart}`);
+  }
+  const rawAddress = requireTrimmedString(identity.address, 'address').toLowerCase();
+  const [addressLocalPart, addressDomain, addressExtra] = rawAddress.split('@');
+  if (!addressLocalPart || !addressDomain || addressExtra) {
+    throw new Error(`Invalid stored mail identity address: ${identity.address}`);
+  }
+  const address = `${addressLocalPart}@${normalizeGatewayMailDomain(addressDomain)}`;
+  if (address !== `${localPart}@${domain}`) {
+    throw new Error('Stored mail identity address, localPart, and domain do not match');
+  }
+  if (!identity.smtp || typeof identity.smtp !== 'object' || Array.isArray(identity.smtp)) {
+    throw new Error('Stored mail identity smtp configuration is required');
+  }
+  if (typeof identity.enabled !== 'boolean' || typeof identity.smtp.enabled !== 'boolean') {
+    throw new Error('Stored mail identity enabled flags must be boolean');
+  }
+  const createdAt = requireTimestamp(identity.createdAt, 'createdAt');
+  const updatedAt = requireTimestamp(identity.updatedAt, 'updatedAt');
+  const smtpLastRotatedAt = identity.smtpLastRotatedAt === undefined
+    ? undefined
+    : requireTimestamp(identity.smtpLastRotatedAt, 'smtpLastRotatedAt');
+  const ownership: IWorkAppMailOwnership = {
+    workHosterType: owner.gatewayClientType,
+    workHosterId: owner.gatewayClientId,
+    workAppId: owner.appInstanceId,
+  };
+  const externalKey = [
+    owner.gatewayClientType,
+    owner.gatewayClientId,
+    owner.appInstanceId,
+    address,
+  ].join(':');
+
+  return {
+    id: requireTrimmedString(identity.id, 'id'),
+    externalKey,
+    ownership,
+    address,
+    localPart,
+    domain,
+    enabled: identity.enabled,
+    ...(identity.displayName === undefined
+      ? {}
+      : { displayName: String(identity.displayName) }),
+    ...(identity.inbound === undefined
+      ? {}
+      : { inbound: structuredClone(identity.inbound) }),
+    ...(identity.inboundTarget === undefined
+      ? {}
+      : { inboundTarget: structuredClone(identity.inboundTarget) }),
+    smtp: {
+      enabled: identity.smtp.enabled,
+      username: requireTrimmedString(identity.smtp.username, 'smtp.username'),
+    },
+    createdAt,
+    updatedAt,
+    createdBy: requireTrimmedString(identity.createdBy, 'createdBy'),
+    smtpPassword: requireTrimmedString(identity.smtpPassword, 'smtpPassword'),
+    ...(smtpLastRotatedAt === undefined ? {} : { smtpLastRotatedAt }),
+  };
+}
+
+export function groupGatewayMailIdentities(
+  identitiesArg: unknown[],
+): IGatewayMailDomainGroup[] {
+  const groups = new Map<string, IGatewayMailDomainGroup>();
+  const identityIds = new Set<string>();
+  const externalKeys = new Set<string>();
+
+  for (const identityArg of identitiesArg) {
+    const identity = normalizeStoredWorkAppMailIdentity(identityArg);
+    if (identityIds.has(identity.id)) {
+      throw new Error(`Duplicate stored mail identity id: ${identity.id}`);
+    }
+    if (externalKeys.has(identity.externalKey)) {
+      throw new Error(`Duplicate stored mail identity externalKey: ${identity.externalKey}`);
+    }
+    identityIds.add(identity.id);
+    externalKeys.add(identity.externalKey);
+    const owner = gatewayMailOwnerFromLegacyOwnership(identity.ownership);
+    const id = createGatewayMailDomainId(owner, identity.domain);
+    const group = groups.get(id) || {
+      id,
+      gatewayClientType: owner.gatewayClientType,
+      gatewayClientId: owner.gatewayClientId,
+      domain: identity.domain,
+      identities: [],
+    };
+    group.identities.push(identity);
+    groups.set(id, group);
+  }
+
+  return Array.from(groups.values())
+    .map((groupArg) => ({
+      ...groupArg,
+      identities: groupArg.identities
+        .sort((leftArg, rightArg) => leftArg.externalKey.localeCompare(rightArg.externalKey)),
+    }))
+    .sort((leftArg, rightArg) => leftArg.id.localeCompare(rightArg.id));
+}

package/ts/email/index.ts

@@ -8,12 +8,14 @@ export * from './reconcile-mail-dns-singleton.js';
 export * from './classes.mail-egress-coordinator.js';
 export * from './classes.mail-edge-eligibility.js';
 export * from './classes.email-settings.manager.js';
+export * from './classes.gateway-mail-domain.store.js';
 export * from './classes.smartmta-blob-storage-manager.js';
 export * from './classes.smartmta-storage-manager.js';
 export * from './smartmta-storage-policy.js';
 export * from './classes.smtp-account.manager.js';
 export * from './smtp-scram.js';
 export * from './classes.workapp-mail-manager.js';
+export * from './gateway-mail-domain-authority.js';
 export * from './email-dns-records.js';
 export * from './helpers.email-log-traffic.js';
 export * from './helpers.inbound-security.js';