@serve.zone/dcrouter 18.4.1 → 18.6.0

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';

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

@@ -32,7 +32,7 @@ export class GatewayClientHandler {
   private async requireAuth(
     request: { identity?: interfaces.data.IIdentity; apiToken?: string },
     requiredScope?: interfaces.data.TApiTokenScope,
-    options: { allowCandidate?: boolean } = {},
+    options: { allowCandidate?: boolean; loadManagedZoneNames?: boolean } = {},
   ): Promise<TAuthContext> {
     return await requireGatewayMachineAuth(
       this.opsServerRef,
@@ -351,6 +351,48 @@ export class GatewayClientHandler {
       ),
     );
 
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.gateway.IReq_GetGatewayClientMailDomainCount>(
+        'getGatewayClientMailDomainCount',
+        async (dataArg) => {
+          const auth = await this.requireAuth(dataArg, 'gateway-clients:read', {
+            loadManagedZoneNames: false,
+          });
+          this.assertCapability(auth, 'readMail');
+          const untypedRequest = dataArg as Record<string, unknown>;
+          for (const forbiddenKey of [
+            'owner',
+            'gatewayClientId',
+            'gatewayClientType',
+            'workHosterId',
+            'workHosterType',
+            'appInstanceId',
+          ]) {
+            if (Object.prototype.hasOwnProperty.call(untypedRequest, forbiddenKey)) {
+              throw new plugins.typedrequest.TypedResponseError(
+                'mail-domain count ownership is derived from the gateway-client credential',
+              );
+            }
+          }
+          if (
+            auth.isAdmin
+            || auth.policy?.role !== 'gatewayClient'
+            || !auth.gatewayClient
+            || !auth.policy.gatewayClient
+          ) {
+            throw new plugins.typedrequest.TypedResponseError('gateway-client credential required');
+          }
+          const manager = this.opsServerRef.dcRouterRef.workAppMailManager;
+          return {
+            count: await manager.countMailDomains({
+              gatewayClientType: auth.gatewayClient.type,
+              gatewayClientId: auth.gatewayClient.id,
+            }),
+          };
+        },
+      ),
+    );
+
     this.typedrouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.gateway.IReq_GetGatewayClientDomains>(
         'getGatewayClientDomains',

package/ts/opsserver/helpers/gateway-client-auth.ts

@@ -17,6 +17,8 @@ export type TGatewayCredentialState = 'candidate' | 'active' | 'manual';
 
 export interface IRequireGatewayMachineAuthOptions {
   allowCandidate?: boolean;
+  /** Skip managed DNS-domain loading for APIs that do not evaluate hostnames. */
+  loadManagedZoneNames?: boolean;
 }
 
 export function getGatewayCredentialState(
@@ -124,8 +126,10 @@ export async function requireGatewayMachineAuth(
     scope: scopeArg,
     requireAdminIdentity: false,
   });
-  const managedZoneNames = (await opsServerRefArg.dcRouterRef.dnsManager?.listDomains() || [])
-    .map((domainArg) => domainArg.name);
+  const managedZoneNames = optionsArg.loadManagedZoneNames === false
+    ? []
+    : (await opsServerRefArg.dcRouterRef.dnsManager?.listDomains() || [])
+      .map((domainArg) => domainArg.name);
 
   if (auth.isAdmin) {
     return {

package/ts_web/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/readme.plan.md

@@ -1,22 +0,0 @@
-# Platform refactoring program
-
-Status: approved 2026-07-21, derived from that day's incident ledger (deploy-verification crashes, unbounded scans, DNS/IP logic duplication, version-skew scares). Upstream foundations are RELEASED; consumer adoption and the dcrouter-internal refactors are sequenced below — do not start them mid-wave, fold them into the next natural release of each surface.
-
-## Shipped upstream (adopt on next dependency bump)
-
-1. **Typed-request error boundary — already existed.** @api.global/typedrequest ≥ 3.3.2 sanitizes every handler/middleware throw into a structured error envelope (no socket destruction). Action: ensure every deployed consumer (cloudly, dcrouter, coreflow, onebox) resolves ≥ 3.3.2 and remove any local try/catch layers that only re-implement it.
-2. **Canonical IP helpers — @push.rocks/smartnetwork 4.9.0.** `isPublicIpAddress`, `toReverseDnsName` (non-throwing), `expandIpv6`, alongside the existing `getIpVersion`/`isValidIpv4`/`isValidIpv6`. Adoption: dcrouter ts/email/classes.mail-dns-sync.ts drops its private `toReverseDnsName`/`expandIpv6` (and the `Invalid IP address:` throw); cloudly's `isPublicDeploymentAddress` (classes.deploymentoperationmanager.ts) delegates to `isPublicIpAddress` (IPv4 semantics are byte-identical; IPv6 is 2000::/3 minus 2001:db8::/32).
-3. **Cursor pagination as the org default — @push.rocks/smartdata 7.4.0.** `SmartDataDbDoc.getPagedInstances({ filter, sortField, sortDirection, uniqueField, limit ≤ 1000, cursor, withTotal })` — seek pagination with a unique tiebreaker, never materializes the full set. Adoption: OpsConfigEventDoc.findFiltered becomes a thin wrapper; every future list surface uses it. Review rule: a list API without a cursor is a defect.
-4. **Binary provenance — @git.zone/tsrust 1.7.0.** Every built binary gets a JSON trailer (project, version, git commit, target, builtAt, tsrust version); `tsrust inspect <binary>` prints it. Adoption: bump tsrust across the Rust-bridge repos (smartdb, smartproxy, smartmta, smartnetwork, coretraffic, remoteingress) on their next releases; deployment verification can then assert binary identity instead of guessing (see the strings-on-x86 pitfall in smartdb readme.hints.md).
-
-## Sequenced (do NOT start mid-wave)
-
-5. **Ops-handler base class (dcrouter).** 25 handler files carry 11 copies of the requireAuth wrapper and 49 hand-written "manager not initialized" guards. Introduce a base with `registerMethod(name, scope, handlerFn)` doing auth, manager guard, error boundary, and realtime invalidation; migrate handlers opportunistically (new handlers must use it; old ones migrate when touched).
-6. **Composition-root service table (dcrouter).** classes.dcrouter.ts (2,326 lines) has 20 near-identical addService blocks with drift (withRetry presence, error logging). Replace with a declarative registration table; behavior-preserving.
-7. **Mail-detail contract dedup (interfaces + catalog + dcrouter).** IEmailDetail and friends exist twice by convention ("matches @serve.zone/catalog"). Move the contract into @serve.zone/interfaces; catalog and dcrouter consume it. Sequence AFTER the in-flight mail-detail wave (countdown, verdicts, transfer stats) fully lands — one migration wave, no compatibility layer.
-8. **Version-skew hardening (conventions).** (a) Tolerant-reader parsing for persisted operation/evidence/state documents that cross release boundaries; (b) version handshake wherever a live process or socket is reused across upgrades (LocalSmartDb engine reuse — smartdb plan Track 6; gateway-client policyGeneration is the precedent).
-
-## Non-goals
-
-- No big-bang rewrites: every item lands either additive-upstream or inside a surface's next natural release.
-- No compatibility layers (org rule): consumers move to the canonical helpers outright when their wave touches the code.