@serve.zone/interfaces 30.12.0 → 30.13.0

package/dist_ts/data/mail.d.ts

@@ -1,6 +1,6 @@
 export type TMailGatewayClientType = 'onebox' | 'cloudly' | 'custom' | (string & {});
 export type TMailAddressPatternType = 'exactAddress' | 'domainWildcard' | 'localPartPattern';
-export type TMailInboundTargetType = 'webhook' | 'smtpForward' | 'typedEndpoint' | 'discard' | 'reject';
+export type TMailInboundTargetType = 'webhook' | 'smtpForward' | 'typedEndpoint' | 'coreMail' | 'discard' | 'reject';
 export type TMailRecipientPolicyMode = 'acceptAll' | 'staticList' | 'cachedResolver' | 'appResolver';
 export type TMailCredentialType = 'smtp' | 'api';
 export type TMailCredentialStatus = 'active' | 'disabled' | 'rotated' | 'revoked';
@@ -12,7 +12,12 @@ export type TMailBounceType = 'hard' | 'soft' | 'complaint' | 'unknown';
 export type TMailInboundProtocol = 'smtp' | 'submission' | 'api';
 export type TMailRecipientResolutionAction = 'accept' | 'reject' | 'defer';
 export type TMailDeliveryJournalEventType = 'accepted' | 'queued' | 'deliveryStarted' | 'deliverySucceeded' | 'deliveryDeferred' | 'deliveryFailed' | 'deadLettered' | 'rejected' | 'bounced' | 'complaint';
-export type TMailSubmissionErrorCode = 'INVALID_REPLY_TO' | 'REPLY_TO_FIELD_HEADER_CONFLICT';
+/**
+ * Error codes a mail submission may return. The CoreMail-fronted path maps the
+ * matching `TCoreMailErrorCode` values through unchanged so applications can
+ * branch on them regardless of which transport carried the submission.
+ */
+export type TMailSubmissionErrorCode = 'INVALID_REPLY_TO' | 'REPLY_TO_FIELD_HEADER_CONFLICT' | 'AUTHENTICATION_FAILED' | 'CAPABILITY_DENIED' | 'INVALID_REQUEST' | 'INVALID_MAILBOX' | 'INVALID_SENDER' | 'INVALID_RECIPIENT' | 'INVALID_HEADER' | 'PAYLOAD_LIMIT_EXCEEDED' | 'QUOTA_EXCEEDED' | 'IDEMPOTENCY_CONFLICT' | 'STATE_CONFLICT' | 'NOT_FOUND';
 /**
  * Runtime owner of a mail resource. `appInstanceId` is the deployed WorkApp or service
  * instance, not an App Store template id.
@@ -48,11 +53,16 @@ export interface IMailTypedEndpointTarget {
     queueName?: string;
     timeoutMs?: number;
 }
+export interface IMailCoreMailTarget {
+    /** CoreMail service identity that owns the inbound mailbox. */
+    coreMailServiceId: string;
+}
 export interface IMailInboundTarget {
     type: TMailInboundTargetType;
     webhook?: IMailWebhookTarget;
     smtpForward?: IMailSmtpForwardTarget;
     typedEndpoint?: IMailTypedEndpointTarget;
+    coreMail?: IMailCoreMailTarget;
     reject?: {
         smtpCode: number;
         message: string;
@@ -175,8 +185,11 @@ export interface IWorkAppMailBinding {
 export type TServiceMailSubmissionTlsMode = 'plain' | 'starttls' | 'implicitTls';
 export interface IServiceMailInboundConfig {
     enabled?: boolean;
-    /** Platformclient apps use typedEndpoint; third-party apps with their own SMTP server use smtpForward. */
-    targetType?: 'typedEndpoint' | 'smtpForward';
+    /**
+     * Platformclient apps use typedEndpoint; third-party apps with their own SMTP
+     * server use smtpForward; services bound to a CoreMail workload use coreMail.
+     */
+    targetType?: 'typedEndpoint' | 'smtpForward' | 'coreMail';
     /** TypedRequest method exposed by platformclient over TypedSocket for inbound delivery. */
     typedMethod?: string;
     /** Published Docker/Swarm port that dcrouter may SMTP-forward inbound mail to. */

package/dist_ts/requests/coremail.d.ts

@@ -1,5 +1,5 @@
 import type * as plugins from '../plugins.js';
-import type { ICoreMailEnvelope, ICoreMailInboundDeliveryPage, ICoreMailDownloadGrant, ICoreMailGatewayMessageDescriptor, ICoreMailGatewayOutboundStatus, ICoreMailInboundDelivery, ICoreMailOutboundMessageDescriptor, ICoreMailRecipientResolution, ICoreMailReconciliationStatus, ICoreMailReplicaIdentity, ICoreMailSubmission, ICoreMailUploadGrant, TCoreMailInboundAckOutcome, TCoreMailSha256, TCoreMailWorkloadOperation } from '../data/coremail.js';
+import type { ICoreMailEnvelope, ICoreMailInboundDeliveryPage, ICoreMailDownloadGrant, ICoreMailGatewayMessageDescriptor, ICoreMailGatewayOutboundStatus, ICoreMailInboundDelivery, ICoreMailOutboundMessageDescriptor, ICoreMailRecipientResolution, ICoreMailReconciliationStatus, ICoreMailReplicaIdentity, ICoreMailServiceMailStatistics, ICoreMailSubmission, ICoreMailUploadGrant, TCoreMailInboundAckOutcome, TCoreMailSha256, TCoreMailWorkloadOperation } from '../data/coremail.js';
 import type { IMailConnectionInfo } from '../data/mail.js';
 export interface IReq_CoreMailAuthenticateWorkload extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailAuthenticateWorkload> {
     method: 'coreMailAuthenticateWorkload';
@@ -164,6 +164,29 @@ export interface IReq_CoreMailGetReconciliationStatus extends plugins.typedreque
         status: ICoreMailReconciliationStatus;
     };
 }
+/**
+ * Control-session read of per-service mail counters. Authority comes from the
+ * authenticated control session; the request carries no tenant or binding
+ * authority of its own.
+ */
+export interface IReq_CoreMailGetServiceMailStatistics extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailGetServiceMailStatistics> {
+    method: 'coreMailGetServiceMailStatistics';
+    request: {
+        /** Inclusive first UTC calendar day, `YYYY-MM-DD`. */
+        fromDayUtc: string;
+        /** Inclusive last UTC calendar day, `YYYY-MM-DD`. */
+        toDayUtc: string;
+        /** Optional service filter. Omitted means every service known to this CoreMail. */
+        serviceIds?: string[];
+        /** Opaque CoreMail-owned composite cursor. */
+        cursor?: string;
+        limit: number;
+    };
+    response: {
+        statistics: ICoreMailServiceMailStatistics[];
+        nextCursor?: string;
+    };
+}
 export interface IReq_CoreMailGatewayAuthenticate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailGatewayAuthenticate> {
     method: 'coreMailGatewayAuthenticate';
     request: {
@@ -179,6 +202,13 @@ export interface IReq_CoreMailGatewayAuthenticate extends plugins.typedrequestIn
         coreMailTransferOrigin: string;
     };
 }
+/**
+ * CoreMail binds every issued routing handle to a digest of the exact
+ * normalized `envelope` and `source` sent here. The following
+ * `coreMailGatewayPrepareInboundHandoff` call must therefore resend
+ * byte-identical values: the full `rcptTo` set in the same order, the same
+ * `mailFrom`, and the same connection source fields.
+ */
 export interface IReq_CoreMailGatewayResolveRecipients extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailGatewayResolveRecipients> {
     method: 'coreMailGatewayResolveRecipients';
     request: {
@@ -190,6 +220,13 @@ export interface IReq_CoreMailGatewayResolveRecipients extends plugins.typedrequ
         resolutions: ICoreMailRecipientResolution[];
     };
 }
+/**
+ * The handoff is validated against the routing handles issued by
+ * `coreMailGatewayResolveRecipients`. `message.envelope` and `source` must be
+ * byte-identical to the resolve-time values, including the full `rcptTo` set in
+ * the same order, because CoreMail recomputes the envelope digest the handles
+ * are bound to.
+ */
 export interface IReq_CoreMailGatewayPrepareInboundHandoff extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailGatewayPrepareInboundHandoff> {
     method: 'coreMailGatewayPrepareInboundHandoff';
     request: {
@@ -246,6 +283,12 @@ export interface IReq_CoreMailGatewayCompleteOutboundHandoff extends plugins.typ
         replayed: boolean;
     };
 }
+/**
+ * Status polling for one accepted transport message. `status.updatedAt` must be
+ * monotonic per `transportMessageId`. A `transportMessageId` that is
+ * permanently unknown to the gateway must be answered with a terminal `failed`
+ * status rather than an error, because CoreMail retries errors indefinitely.
+ */
 export interface IReq_CoreMailGatewayGetOutboundStatus extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailGatewayGetOutboundStatus> {
     method: 'coreMailGatewayGetOutboundStatus';
     request: {

package/dist_ts/requests/mail.d.ts

@@ -1,4 +1,5 @@
 import * as plugins from '../plugins.js';
+import type { ICoreMailGatewayPeerDesiredState } from '../data/coremail.js';
 import type { IIdentity } from '../data/user.js';
 import type { IMailAddressBinding, IMailCredentialOneTimeSecret, IMailConnectionInfo, IMailDeliveryJournalEvent, IMailDeliveryStatus, IMailDomainAuthority, IMailEnvelope, IMailInboundMessagePayload, IMailOutboundIdentity, IMailOutboundMessagePayload, IMailRecipientResolution, IMailResourceOwner, IMailSpoolItem, IWorkAppMailBinding, TMailSubmissionErrorCode } from '../data/mail.js';
 export interface IMailControlRequestAuth {
@@ -89,6 +90,55 @@ export interface IReq_DeleteMailAddressBinding extends plugins.typedrequestInter
         message?: string;
     };
 }
+/**
+ * dcrouter-owned CoreMail gateway peer state.
+ *
+ * `peer.transferOrigin` must equal the `gateway.coreMailTransferOrigin` carried
+ * in that CoreMail service's own desired state. The producer (Cloudly or
+ * Onebox) is the single owner of that string: dcrouter never infers it from a
+ * socket, Host header, TypedSocket tag, or peer input.
+ */
+export interface IReq_ListCoreMailGatewayPeers extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ListCoreMailGatewayPeers> {
+    method: 'listCoreMailGatewayPeers';
+    request: {
+        auth: IMailControlRequestAuth;
+        owner: IMailResourceOwner;
+    };
+    response: {
+        peers: ICoreMailGatewayPeerDesiredState[];
+    };
+}
+/**
+ * Creates or replaces one CoreMail gateway peer. On success the accepted peer is
+ * returned in its stored form so the producer can compare the exact applied
+ * state. `owner` is required (not partial) because a peer is producer-owned
+ * provisioning state, never a filtered listing.
+ */
+export interface IReq_SyncCoreMailGatewayPeer extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_SyncCoreMailGatewayPeer> {
+    method: 'syncCoreMailGatewayPeer';
+    request: {
+        auth: IMailControlRequestAuth;
+        owner: IMailResourceOwner;
+        peer: ICoreMailGatewayPeerDesiredState;
+    };
+    response: {
+        success: boolean;
+        peer?: ICoreMailGatewayPeerDesiredState;
+        message?: string;
+    };
+}
+export interface IReq_DeleteCoreMailGatewayPeer extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_DeleteCoreMailGatewayPeer> {
+    method: 'deleteCoreMailGatewayPeer';
+    request: {
+        auth: IMailControlRequestAuth;
+        owner: IMailResourceOwner;
+        coreMailServiceId: string;
+    };
+    response: {
+        success: boolean;
+        message?: string;
+    };
+}
 export interface IReq_ListWorkAppMailBindings extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ListWorkAppMailBindings> {
     method: 'listWorkAppMailBindings';
     request: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "30.12.0",
+  "version": "30.13.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/readme.md

@@ -1217,6 +1217,17 @@ may continue its next configured resolver. Consumers must apply
 `data.normalizeCoreMailRecipientResolutions()` against the exact requested
 recipient set before acting on a peer response.
 
+CoreMail binds every issued routing handle to a digest of the exact normalized
+`envelope` and `source` sent at resolve time. A following
+`coreMailGatewayPrepareInboundHandoff` must resend byte-identical values,
+including the complete `rcptTo` set in the same order. Both peers use
+`data.normalizeCoreMailGatewayMessage` and
+`data.normalizeCoreMailConnectionInfo` so the digested bytes come from one
+shared implementation. Outbound status is monotonic per `transportMessageId`,
+and a permanently unknown `transportMessageId` is answered with a terminal
+`failed` status rather than an error, because CoreMail retries errors
+indefinitely.
+
 Large content never travels inside TypedRequest JSON. Outbound body parts and
 attachments use prepare/upload/complete operations with short-lived one-time
 HTTP transfer grants. Inbound delivery uses bounded delivery listing followed
@@ -1245,6 +1256,23 @@ credential-lifecycle inconsistencies. CoreMail credential verifiers use the
 versioned `argon2id-v1` format and the exact policy exported as
 `data.coreMailCredentialVerifierPolicy`.
 
+`data.ICoreMailDesiredState.smtp` is the optional CoreMail SMTP submission
+listener (MSA). It carries the listener port, the advertised EHLO hostname, and
+the runtime secret keys holding certificate and private-key PEM text; plaintext
+PEM material never appears in desired state. SMTP AUTH uses the binding
+identity directly: the username is the `bindingId` and the password is any
+current or retiring credential secret of that binding. The listener stays
+unavailable until the referenced PEM material resolves. Omitting `smtp` keeps
+the exact canonical bytes and digest of an API-only CoreMail. Accepted
+submissions report their entry point through the optional
+`ICoreMailSubmission.source`, either `api` or `smtp`.
+
+`data.ICoreMailServiceMailStatistics` reports per-service outbound and inbound
+counters for one UTC calendar day. Control sessions read them through
+`coreMailGetServiceMailStatistics` using an inclusive day range, an optional
+service filter, and an opaque cursor. Apply
+`data.normalizeCoreMailServiceMailStatistics` before using reported counters.
+
 `data.ICoreMailControlBootstrap` is installed before ordinary reconciliation.
 It contains the CoreMail service identity and verifier metadata only. The
 matching plaintext control credential is delivered exclusively to Coreflow
@@ -1269,7 +1297,13 @@ CoreMail transfer origin associated with an authenticated CoreMail service.
 The same origin is carried in CoreMail desired state and returned by workload
 and gateway authentication. It must never be inferred from a socket, Host
 header, TypedSocket tag, or unrestricted peer input. CoreMail compares both
-authoritative views before handing over a path-only transfer grant.
+authoritative views before handing over a path-only transfer grant. Cloudly and
+Onebox provision that peer state through `listCoreMailGatewayPeers`,
+`syncCoreMailGatewayPeer`, and `deleteCoreMailGatewayPeer` on the gateway-client
+mail surface, and the producer is the single owner of `peer.transferOrigin`. A
+mail inbound target may point at a CoreMail service using `type: 'coreMail'`
+with `coreMail.coreMailServiceId`, mirrored by the `coreMail` member of
+`IServiceMailInboundConfig.targetType`.
 
 Inbound delivery pagination uses an opaque CoreMail-owned `cursor`, is bounded
 by `data.coreMailLimits.inboundPageSize`, and returns `nextCursor` only when

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '30.12.0',
+  version: '30.13.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/coremail.runtime.ts

@@ -20,17 +20,22 @@ import {
   type ICoreMailEnvelope,
   type ICoreMailErrorData,
   type ICoreMailGatewayDesiredState,
+  type ICoreMailGatewayMessageDescriptor,
   type ICoreMailGatewayOutboundStatus,
   type ICoreMailGatewayPeerDesiredState,
   type ICoreMailInboundDelivery,
   type ICoreMailInboundDeliveryPage,
+  type ICoreMailInboundMailCounters,
   type ICoreMailMailbox,
+  type ICoreMailOutboundMailCounters,
   type ICoreMailOutboundMessageDescriptor,
   type ICoreMailPartStatus,
   type ICoreMailRecipientResolution,
   type ICoreMailRuntimeKeyReference,
   type ICoreMailReconciliationStatus,
   type ICoreMailReplicaIdentity,
+  type ICoreMailServiceMailStatistics,
+  type ICoreMailSmtpDesiredState,
   type ICoreMailSubmission,
   type ICoreMailTransferGrant,
   type ICoreMailUploadGrant,
@@ -38,8 +43,10 @@ import {
   type TCoreMailBindingState,
   type TCoreMailErrorCode,
   type TCoreMailSha256,
+  type TCoreMailSubmissionSource,
   type TCoreMailWorkloadOperation,
 } from './coremail.js';
+import type { IMailConnectionInfo } from './mail.js';
 
 export const coreMailCanonicalJsonRules = strictCanonicalJsonRules;
 
@@ -79,6 +86,7 @@ export const coreMailContractLimits = Object.freeze({
   maximumContentIdBytes: 256,
   maximumBearerTokenBytes: 1_024,
   maximumRecipientResolutionMessageBytes: 512,
+  maximumConnectionInfoFieldBytes: 512,
 } as const);
 
 export class CoreMailContractError extends Error {
@@ -533,6 +541,24 @@ const requireCanonicalMailbox = (valueArg: unknown, pathArg: string): string =>
   return value;
 };
 
+const requireCanonicalHostname = (valueArg: unknown, pathArg: string): string => {
+  const value = requireString(
+    valueArg,
+    pathArg,
+    coreMailContractLimits.maximumMailboxBytes,
+  );
+  const labels = value.split('.');
+  if (
+    value !== value.toLowerCase()
+    || value.length > 253
+    || labels.length < 2
+    || labels.some((labelArg) => !mailboxDomainLabelRegex.test(labelArg))
+  ) {
+    fail(`${pathArg} must be a canonical lowercase hostname`);
+  }
+  return value;
+};
+
 const normalizeMailbox = (valueArg: unknown, pathArg: string): ICoreMailMailbox => {
   const record = readRecord(valueArg, pathArg);
   assertKeys(record, pathArg, ['address'], ['displayName']);
@@ -1157,6 +1183,7 @@ export const normalizeCoreMailSubmission = (
     ],
     [
       'transportMessageId',
+      'source',
       'nextAttemptAt',
       'error',
       'acceptedAt',
@@ -1209,6 +1236,12 @@ export const normalizeCoreMailSubmission = (
       `${pathArg}.transportMessageId`,
     );
   }
+  if (Object.hasOwn(record, 'source')) {
+    if (record.source !== 'api' && record.source !== 'smtp') {
+      fail(`${pathArg}.source must be api or smtp`);
+    }
+    normalized.source = record.source as TCoreMailSubmissionSource;
+  }
   if (Object.hasOwn(record, 'error')) {
     normalized.error = normalizeCoreMailErrorData(record.error, `${pathArg}.error`);
   }
@@ -1698,6 +1731,38 @@ const normalizeGateway = (
   };
 };
 
+const normalizeSmtpDesiredState = (
+  valueArg: unknown,
+  pathArg: string,
+): ICoreMailSmtpDesiredState => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(record, pathArg, ['enabled', 'port', 'hostname', 'tls']);
+  if (typeof record.enabled !== 'boolean') {
+    fail(`${pathArg}.enabled must be boolean`);
+  }
+  const tlsRecord = readRecord(record.tls, `${pathArg}.tls`);
+  assertKeys(
+    tlsRecord,
+    `${pathArg}.tls`,
+    ['certificatePemSecretKey', 'privateKeyPemSecretKey'],
+  );
+  return {
+    enabled: record.enabled as boolean,
+    port: requireSafeInteger(record.port, `${pathArg}.port`, 1, 65_535),
+    hostname: requireCanonicalHostname(record.hostname, `${pathArg}.hostname`),
+    tls: {
+      certificatePemSecretKey: requireEnvironmentKey(
+        tlsRecord.certificatePemSecretKey,
+        `${pathArg}.tls.certificatePemSecretKey`,
+      ),
+      privateKeyPemSecretKey: requireEnvironmentKey(
+        tlsRecord.privateKeyPemSecretKey,
+        `${pathArg}.tls.privateKeyPemSecretKey`,
+      ),
+    },
+  };
+};
+
 export const normalizeCoreMailDesiredState = (
   valueArg: unknown,
 ): ICoreMailDesiredState => {
@@ -1706,6 +1771,7 @@ export const normalizeCoreMailDesiredState = (
     record,
     'desiredState',
     ['schemaVersion', 'configEpoch', 'bindings', 'gateway', 'cursorKeys'],
+    ['smtp'],
   );
   if (record.schemaVersion !== 2) {
     fail('desiredState.schemaVersion must be 2');
@@ -1736,13 +1802,17 @@ export const normalizeCoreMailDesiredState = (
   bindings.sort((leftArg, rightArg) =>
     compareStrings(leftArg.bindingId, rightArg.bindingId),
   );
-  return deepFreezeValue({
+  const normalized: ICoreMailDesiredState = {
     schemaVersion: 2,
     configEpoch: requireSafeInteger(record.configEpoch, 'desiredState.configEpoch', 1),
     bindings,
     gateway: normalizeGateway(record.gateway, 'desiredState.gateway'),
     cursorKeys: normalizeRuntimeKeySet(record.cursorKeys, 'desiredState.cursorKeys'),
-  });
+  };
+  if (Object.hasOwn(record, 'smtp')) {
+    normalized.smtp = normalizeSmtpDesiredState(record.smtp, 'desiredState.smtp');
+  }
+  return deepFreezeValue(normalized);
 };
 
 export const normalizeCoreMailReplicaIdentity = (
@@ -1976,3 +2046,209 @@ export const normalizeCoreMailGatewayPeerDesiredState = (
     ),
   });
 };
+
+const utcCalendarDayRegex = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
+
+const requireUtcCalendarDay = (valueArg: unknown, pathArg: string): string => {
+  const value = requireString(valueArg, pathArg, 10);
+  if (!utcCalendarDayRegex.test(value)) {
+    fail(`${pathArg} must be a canonical YYYY-MM-DD UTC day`);
+  }
+  const [year, month, day] = value.split('-').map(Number);
+  const parsed = new Date(Date.UTC(year, month - 1, day));
+  if (
+    parsed.getUTCFullYear() !== year
+    || parsed.getUTCMonth() + 1 !== month
+    || parsed.getUTCDate() !== day
+  ) {
+    fail(`${pathArg} must be a real UTC calendar day`);
+  }
+  return value;
+};
+
+const normalizeOutboundMailCounters = (
+  valueArg: unknown,
+  pathArg: string,
+): ICoreMailOutboundMailCounters => {
+  const record = readRecord(valueArg, pathArg);
+  const keys = [
+    'submittedApi',
+    'submittedSmtp',
+    'delivered',
+    'deferred',
+    'failed',
+    'deadLettered',
+  ] as const;
+  assertKeys(record, pathArg, [...keys]);
+  const normalized = {} as ICoreMailOutboundMailCounters;
+  for (const key of keys) {
+    normalized[key] = requireSafeInteger(record[key], `${pathArg}.${key}`, 0);
+  }
+  return normalized;
+};
+
+const normalizeInboundMailCounters = (
+  valueArg: unknown,
+  pathArg: string,
+): ICoreMailInboundMailCounters => {
+  const record = readRecord(valueArg, pathArg);
+  const keys = [
+    'received',
+    'acknowledgedProcessed',
+    'acknowledgedDiscarded',
+  ] as const;
+  assertKeys(record, pathArg, [...keys]);
+  const normalized = {} as ICoreMailInboundMailCounters;
+  for (const key of keys) {
+    normalized[key] = requireSafeInteger(record[key], `${pathArg}.${key}`, 0);
+  }
+  return normalized;
+};
+
+export const normalizeCoreMailServiceMailStatistics = (
+  valueArg: unknown,
+  pathArg = 'serviceMailStatistics',
+): ICoreMailServiceMailStatistics => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    [
+      'tenantId',
+      'serviceId',
+      'bindingId',
+      'dayUtc',
+      'outbound',
+      'inbound',
+      'updatedAt',
+    ],
+  );
+  return deepFreezeValue({
+    tenantId: requireIdentifier(record.tenantId, `${pathArg}.tenantId`),
+    serviceId: requireIdentifier(record.serviceId, `${pathArg}.serviceId`),
+    bindingId: requireIdentifier(record.bindingId, `${pathArg}.bindingId`),
+    dayUtc: requireUtcCalendarDay(record.dayUtc, `${pathArg}.dayUtc`),
+    outbound: normalizeOutboundMailCounters(record.outbound, `${pathArg}.outbound`),
+    inbound: normalizeInboundMailCounters(record.inbound, `${pathArg}.inbound`),
+    updatedAt: requireSafeInteger(record.updatedAt, `${pathArg}.updatedAt`, 1),
+  });
+};
+
+/**
+ * Strict gateway message descriptor normalization.
+ *
+ * CoreMail digests the normalized envelope together with the normalized
+ * connection source, so the emitted field set and order is part of the
+ * contract and must not change.
+ */
+export const normalizeCoreMailGatewayMessage = (
+  valueArg: unknown,
+  pathArg = 'gatewayMessage',
+): ICoreMailGatewayMessageDescriptor => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(record, pathArg, ['envelope', 'rawMime']);
+  const rawMime = readRecord(record.rawMime, `${pathArg}.rawMime`);
+  assertKeys(rawMime, `${pathArg}.rawMime`, ['sha256', 'lengthBytes', 'contentType']);
+  if (rawMime.contentType !== 'message/rfc822') {
+    fail(`${pathArg}.rawMime.contentType must be message/rfc822`);
+  }
+  const normalized: ICoreMailGatewayMessageDescriptor = {
+    envelope: normalizeCoreMailEnvelope(record.envelope, `${pathArg}.envelope`),
+    rawMime: {
+      sha256: normalizeCoreMailSha256(rawMime.sha256, `${pathArg}.rawMime.sha256`),
+      lengthBytes: requireSafeInteger(
+        rawMime.lengthBytes,
+        `${pathArg}.rawMime.lengthBytes`,
+        1,
+        coreMailLimits.serializedMimeBytes,
+      ),
+      contentType: 'message/rfc822',
+    },
+  };
+  return deepFreezeValue(normalized);
+};
+
+const requireConnectionInfoField = (valueArg: unknown, pathArg: string): string => {
+  const value = requireString(
+    valueArg,
+    pathArg,
+    coreMailContractLimits.maximumConnectionInfoFieldBytes,
+  );
+  if (value.trim() !== value) {
+    fail(`${pathArg} must not carry leading or trailing whitespace`);
+  }
+  return value;
+};
+
+/**
+ * Strict connection-source normalization for gateway resolve and handoff
+ * requests. CoreMail binds routing handles to a digest of the normalized
+ * envelope and this normalized source, so the emitted field set and order is
+ * part of the contract and must not change.
+ */
+export const normalizeCoreMailConnectionInfo = (
+  valueArg: unknown,
+  pathArg = 'connectionInfo',
+): IMailConnectionInfo => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    ['protocol'],
+    [
+      'remoteAddress',
+      'proxyAddress',
+      'heloName',
+      'tls',
+      'authUsername',
+      'authenticatedCredentialId',
+    ],
+  );
+  if (
+    record.protocol !== 'smtp'
+    && record.protocol !== 'submission'
+    && record.protocol !== 'api'
+  ) {
+    fail(`${pathArg}.protocol must be smtp, submission, or api`);
+  }
+  const normalized: IMailConnectionInfo = {
+    protocol: record.protocol as IMailConnectionInfo['protocol'],
+  };
+  if (record.remoteAddress !== undefined) {
+    normalized.remoteAddress = requireConnectionInfoField(
+      record.remoteAddress,
+      `${pathArg}.remoteAddress`,
+    );
+  }
+  if (record.proxyAddress !== undefined) {
+    normalized.proxyAddress = requireConnectionInfoField(
+      record.proxyAddress,
+      `${pathArg}.proxyAddress`,
+    );
+  }
+  if (record.heloName !== undefined) {
+    normalized.heloName = requireConnectionInfoField(
+      record.heloName,
+      `${pathArg}.heloName`,
+    );
+  }
+  if (record.tls !== undefined) {
+    if (typeof record.tls !== 'boolean') {
+      fail(`${pathArg}.tls must be boolean`);
+    }
+    normalized.tls = record.tls as boolean;
+  }
+  if (record.authUsername !== undefined) {
+    normalized.authUsername = requireConnectionInfoField(
+      record.authUsername,
+      `${pathArg}.authUsername`,
+    );
+  }
+  if (record.authenticatedCredentialId !== undefined) {
+    normalized.authenticatedCredentialId = requireConnectionInfoField(
+      record.authenticatedCredentialId,
+      `${pathArg}.authenticatedCredentialId`,
+    );
+  }
+  return deepFreezeValue(normalized);
+};