@serve.zone/coremail 1.0.0

package/ts/coremail.quota.ts

@@ -0,0 +1,214 @@
+import * as plugins from './plugins.js';
+import type { ICoreMailModels } from './classes.models.js';
+import { createSha256 } from './classes.storage.js';
+import type { ICoreMailQuotaCounterRecord } from './coremail.persistence.js';
+
+export interface ICoreMailQuotaAuthority {
+  tenantId: string;
+  serviceId: string;
+  bindingId: string;
+  bindingRevision: number;
+}
+
+export interface ICoreMailQuotaDescriptor extends ICoreMailQuotaAuthority {
+  counterId: plugins.serveZoneInterfaces.data.TCoreMailSha256;
+  kind: ICoreMailQuotaCounterRecord['kind'];
+  windowStartedAt?: number;
+}
+
+export class CoreMailQuotaExceededError extends Error {
+  public constructor(public readonly retryAfterMs?: number) {
+    super('CoreMail quota is exhausted.');
+    this.name = 'CoreMailQuotaExceededError';
+  }
+}
+
+const createDescriptor = (
+  authorityArg: ICoreMailQuotaAuthority,
+  kindArg: ICoreMailQuotaCounterRecord['kind'],
+  windowStartedAtArg?: number,
+): ICoreMailQuotaDescriptor => {
+  const identity = JSON.stringify({
+    tenantId: authorityArg.tenantId,
+    serviceId: authorityArg.serviceId,
+    bindingId: authorityArg.bindingId,
+    bindingRevision: authorityArg.bindingRevision,
+    kind: kindArg,
+  });
+  return {
+    tenantId: authorityArg.tenantId,
+    serviceId: authorityArg.serviceId,
+    bindingId: authorityArg.bindingId,
+    bindingRevision: authorityArg.bindingRevision,
+    counterId: createSha256(identity),
+    kind: kindArg,
+    ...(windowStartedAtArg === undefined
+      ? {}
+      : { windowStartedAt: windowStartedAtArg }),
+  };
+};
+
+export const createCoreMailOutboundQuotaDescriptors = (
+  authorityArg: ICoreMailQuotaAuthority,
+  nowArg: number,
+): {
+  minute: ICoreMailQuotaDescriptor;
+  day: ICoreMailQuotaDescriptor;
+  minuteRetryAfterMs: number;
+  dayRetryAfterMs: number;
+} => {
+  const minuteStartedAt = Math.floor(nowArg / 60_000) * 60_000;
+  const dayStartedAt = Math.floor(nowArg / 86_400_000) * 86_400_000;
+  return {
+    minute: createDescriptor(authorityArg, 'outbound-minute', minuteStartedAt),
+    day: createDescriptor(authorityArg, 'outbound-day', dayStartedAt),
+    minuteRetryAfterMs: minuteStartedAt + 60_000 - nowArg,
+    dayRetryAfterMs: dayStartedAt + 86_400_000 - nowArg,
+  };
+};
+
+export const createCoreMailPendingQuotaDescriptor = (
+  authorityArg: ICoreMailQuotaAuthority,
+): ICoreMailQuotaDescriptor => createDescriptor(authorityArg, 'pending-inbound');
+
+export const ensureCoreMailQuotaCounter = async (
+  modelsArg: ICoreMailModels,
+  descriptorArg: ICoreMailQuotaDescriptor,
+): Promise<void> => {
+  const matchesDescriptor = (
+    counterArg: plugins.smartdata.TStoredDocument<ICoreMailQuotaCounterRecord>,
+  ): boolean =>
+    counterArg.tenantId === descriptorArg.tenantId
+    && counterArg.serviceId === descriptorArg.serviceId
+    && counterArg.bindingId === descriptorArg.bindingId
+    && counterArg.bindingRevision === descriptorArg.bindingRevision
+    && counterArg.kind === descriptorArg.kind;
+  const existing = await modelsArg.QuotaCounter.exact.findStoredOne({
+    counterId: descriptorArg.counterId,
+  });
+  if (existing) {
+    if (!matchesDescriptor(existing)) {
+      throw new Error('CoreMail quota counter identity conflicts with persisted state.');
+    }
+    return;
+  }
+  const deterministicTimestamp = 0;
+  try {
+    const result = await modelsArg.QuotaCounter.exact.insert({
+      ...descriptorArg,
+      count: 0,
+      createdAt: deterministicTimestamp,
+      updatedAt: deterministicTimestamp,
+    });
+    if (result.status !== 'conflict') {
+      return;
+    }
+  } catch (error) {
+    if (
+      !(error instanceof plugins.smartdata.SmartdataExactPersistenceError)
+      || error.code !== 'unique_conflict'
+    ) {
+      throw error;
+    }
+  }
+  const concurrent = await modelsArg.QuotaCounter.exact.findStoredOne({
+    counterId: descriptorArg.counterId,
+  });
+  if (!concurrent || !matchesDescriptor(concurrent)) {
+    throw new Error('CoreMail quota counter identity conflicts with persisted state.');
+  }
+};
+
+export const incrementCoreMailQuotaCounter = async (
+  modelsArg: ICoreMailModels,
+  descriptorArg: ICoreMailQuotaDescriptor,
+  limitArg: number,
+  updatedAtArg: number,
+  sessionArg: plugins.smartdata.SmartdataSession,
+  retryAfterMsArg?: number,
+): Promise<void> => {
+  const counter = await modelsArg.QuotaCounter.exact.findStoredOne(
+    { counterId: descriptorArg.counterId },
+    { session: sessionArg },
+  );
+  if (!counter) {
+    throw new Error('CoreMail quota counter is unavailable.');
+  }
+  if (
+    descriptorArg.windowStartedAt !== undefined
+    && counter.windowStartedAt !== descriptorArg.windowStartedAt
+  ) {
+    if (
+      counter.windowStartedAt !== undefined
+      && descriptorArg.windowStartedAt < counter.windowStartedAt
+    ) {
+      throw new Error('CoreMail quota window fence advanced.');
+    }
+    const reset = await modelsArg.QuotaCounter.exact.transition({
+      current: counter,
+      change: (modelArg) => {
+        modelArg.windowStartedAt = descriptorArg.windowStartedAt;
+        modelArg.count = 1;
+        modelArg.updatedAt = updatedAtArg;
+      },
+    }, { session: sessionArg });
+    if (reset.status !== 'transitioned') {
+      throw new Error('CoreMail quota counter transition was contended.');
+    }
+    return;
+  }
+  if (counter.count >= limitArg) {
+    throw new CoreMailQuotaExceededError(retryAfterMsArg);
+  }
+  const update = await modelsArg.QuotaCounter.exact.transition({
+    current: counter,
+    change: (modelArg) => {
+      modelArg.count += 1;
+      modelArg.updatedAt = updatedAtArg;
+    },
+  }, { session: sessionArg });
+  if (update.status !== 'transitioned') {
+    throw new Error('CoreMail quota counter transition was contended.');
+  }
+};
+
+export const decrementCoreMailQuotaCounter = async (
+  modelsArg: ICoreMailModels,
+  descriptorArg: ICoreMailQuotaDescriptor,
+  updatedAtArg: number,
+  sessionArg: plugins.smartdata.SmartdataSession,
+): Promise<void> => {
+  const counter = await modelsArg.QuotaCounter.exact.findStoredOne(
+    { counterId: descriptorArg.counterId },
+    { session: sessionArg },
+  );
+  if (!counter || counter.count <= 0) {
+    throw new Error('CoreMail pending-inbound quota counter would underflow.');
+  }
+  const update = await modelsArg.QuotaCounter.exact.transition({
+    current: counter,
+    change: (modelArg) => {
+      modelArg.count -= 1;
+      modelArg.updatedAt = updatedAtArg;
+    },
+  }, { session: sessionArg });
+  if (update.status !== 'transitioned') {
+    throw new Error('CoreMail quota counter transition was contended.');
+  }
+};
+
+export const withCoreMailTransaction = async <T>(
+  databaseArg: plugins.smartdata.SmartdataDb,
+  callbackArg: (sessionArg: plugins.smartdata.SmartdataSession) => Promise<T>,
+): Promise<T> => {
+  const session = databaseArg.createSession();
+  try {
+    const result = await session.withTransaction(callbackArg);
+    if (result === undefined) {
+      throw new Error('CoreMail transaction did not commit a result.');
+    }
+    return result;
+  } finally {
+    await session.close();
+  }
+};

package/ts/coremail.selectors.ts

@@ -0,0 +1,35 @@
+const identifierRegex =
+  /^[A-Za-z0-9](?:[A-Za-z0-9._:-]{0,126}[A-Za-z0-9])?$/;
+const uuidRegex =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+export const requireCoreMailIdentifier = (
+  valueArg: unknown,
+  labelArg: string,
+): string => {
+  if (typeof valueArg !== 'string' || !identifierRegex.test(valueArg)) {
+    throw new Error(`${labelArg} must be a canonical CoreMail identifier.`);
+  }
+  return valueArg;
+};
+
+export const requireCoreMailUuid = (
+  valueArg: unknown,
+  labelArg: string,
+): string => {
+  if (typeof valueArg !== 'string' || !uuidRegex.test(valueArg)) {
+    throw new Error(`${labelArg} must be a canonical UUID.`);
+  }
+  return valueArg;
+};
+
+export const requireCoreMailSafeInteger = (
+  valueArg: unknown,
+  labelArg: string,
+  minimumArg = 0,
+): number => {
+  if (!Number.isSafeInteger(valueArg) || Number(valueArg) < minimumArg) {
+    throw new Error(`${labelArg} must be a bounded safe integer.`);
+  }
+  return Number(valueArg);
+};

package/ts/coremail.validation.ts

@@ -0,0 +1,446 @@
+import * as plugins from './plugins.js';
+import { createSha256 } from './classes.storage.js';
+
+type TMessage = plugins.serveZoneInterfaces.data.ICoreMailOutboundMessageDescriptor;
+type TMailbox = plugins.serveZoneInterfaces.data.ICoreMailMailbox;
+type TPart = plugins.serveZoneInterfaces.data.ICoreMailContentDescriptor;
+
+const mailboxLocalPartRegex = /^[a-z0-9!#$%&'*+/=?^_`{|}~.-]+$/;
+const mailboxDomainLabelRegex = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const idRegex = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const contentTypeRegex =
+  /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+(?:; ?[a-z0-9!#$&^_.+-]+=(?:"[^"\r\n]{1,100}"|[a-z0-9!#$&^_.+-]+))*$/i;
+
+const requirePlainRecord = (
+  valueArg: unknown,
+  labelArg: string,
+): Record<string, unknown> => {
+  if (
+    !valueArg
+    || typeof valueArg !== 'object'
+    || Array.isArray(valueArg)
+    || (
+      Object.getPrototypeOf(valueArg) !== Object.prototype
+      && Object.getPrototypeOf(valueArg) !== null
+    )
+  ) {
+    throw new Error(`${labelArg} must be a plain object.`);
+  }
+  return valueArg as Record<string, unknown>;
+};
+
+const requireExactKeys = (
+  recordArg: Record<string, unknown>,
+  requiredArg: string[],
+  optionalArg: string[],
+  labelArg: string,
+): void => {
+  const allowed = new Set([...requiredArg, ...optionalArg]);
+  if (
+    requiredArg.some((keyArg) => !Object.hasOwn(recordArg, keyArg))
+    || Object.keys(recordArg).some((keyArg) => !allowed.has(keyArg))
+  ) {
+    throw new Error(`${labelArg} contains missing or unknown fields.`);
+  }
+};
+
+export const normalizeCoreMailMailboxAddress = (valueArg: unknown): string => {
+  if (
+    typeof valueArg !== 'string'
+    || valueArg.length < 3
+    || Buffer.byteLength(valueArg, 'utf8') > 254
+    || valueArg !== valueArg.toLowerCase()
+  ) {
+    throw new Error('CoreMail mailbox must be canonical lowercase ASCII.');
+  }
+  const atIndex = valueArg.lastIndexOf('@');
+  const localPart = atIndex > 0 ? valueArg.slice(0, atIndex) : '';
+  const domain = atIndex > 0 ? valueArg.slice(atIndex + 1) : '';
+  const labels = domain.split('.');
+  if (
+    localPart.length === 0
+    || localPart.length > 64
+    || !mailboxLocalPartRegex.test(localPart)
+    || localPart.startsWith('.')
+    || localPart.endsWith('.')
+    || localPart.includes('..')
+    || domain.length === 0
+    || domain.length > 253
+    || labels.length < 2
+    || labels.some((labelArg) => !mailboxDomainLabelRegex.test(labelArg))
+  ) {
+    throw new Error('CoreMail mailbox is invalid.');
+  }
+  return valueArg;
+};
+
+export const normalizeCoreMailEnvelope = (
+  valueArg: unknown,
+): plugins.serveZoneInterfaces.data.ICoreMailEnvelope => {
+  const value = requirePlainRecord(valueArg, 'envelope');
+  requireExactKeys(value, ['mailFrom', 'rcptTo'], [], 'envelope');
+  if (
+    typeof value.mailFrom !== 'string'
+    || !Array.isArray(value.rcptTo)
+    || value.rcptTo.length === 0
+    || value.rcptTo.length > 100
+  ) {
+    throw new Error('CoreMail gateway envelope is invalid.');
+  }
+  const mailFrom = value.mailFrom === ''
+    ? ''
+    : normalizeCoreMailMailboxAddress(value.mailFrom);
+  const rcptTo = value.rcptTo.map(normalizeCoreMailMailboxAddress);
+  if (new Set(rcptTo).size !== rcptTo.length) {
+    throw new Error('CoreMail gateway envelope contains duplicate recipients.');
+  }
+  return { mailFrom, rcptTo };
+};
+
+export const normalizeCoreMailConnectionInfo = (
+  valueArg: unknown,
+): plugins.serveZoneInterfaces.data.IMailConnectionInfo => {
+  const value = requirePlainRecord(valueArg, 'connectionInfo');
+  requireExactKeys(
+    value,
+    ['protocol'],
+    [
+      'remoteAddress',
+      'proxyAddress',
+      'heloName',
+      'tls',
+      'authUsername',
+      'authenticatedCredentialId',
+    ],
+    'connectionInfo',
+  );
+  if (
+    value.protocol !== 'smtp'
+    && value.protocol !== 'submission'
+    && value.protocol !== 'api'
+  ) {
+    throw new Error('CoreMail gateway connection protocol is invalid.');
+  }
+  for (const key of [
+    'remoteAddress',
+    'proxyAddress',
+    'heloName',
+    'authUsername',
+    'authenticatedCredentialId',
+  ] as const) {
+    if (
+      value[key] !== undefined
+      && (
+        typeof value[key] !== 'string'
+        || value[key].length === 0
+        || Buffer.byteLength(value[key], 'utf8') > 512
+        || value[key].trim() !== value[key]
+      )
+    ) {
+      throw new Error(`CoreMail gateway connection ${key} is invalid.`);
+    }
+  }
+  if (value.tls !== undefined && typeof value.tls !== 'boolean') {
+    throw new Error('CoreMail gateway connection TLS state is invalid.');
+  }
+  return {
+    protocol: value.protocol,
+    ...(value.remoteAddress === undefined
+      ? {}
+      : { remoteAddress: value.remoteAddress as string }),
+    ...(value.proxyAddress === undefined
+      ? {}
+      : { proxyAddress: value.proxyAddress as string }),
+    ...(value.heloName === undefined
+      ? {}
+      : { heloName: value.heloName as string }),
+    ...(value.tls === undefined ? {} : { tls: value.tls }),
+    ...(value.authUsername === undefined
+      ? {}
+      : { authUsername: value.authUsername as string }),
+    ...(value.authenticatedCredentialId === undefined
+      ? {}
+      : {
+          authenticatedCredentialId:
+            value.authenticatedCredentialId as string,
+        }),
+  };
+};
+
+export const normalizeCoreMailGatewayMessage = (
+  valueArg: unknown,
+): plugins.serveZoneInterfaces.data.ICoreMailGatewayMessageDescriptor => {
+  const value = requirePlainRecord(valueArg, 'gatewayMessage');
+  requireExactKeys(value, ['envelope', 'rawMime'], [], 'gatewayMessage');
+  const rawMime = requirePlainRecord(value.rawMime, 'gatewayMessage.rawMime');
+  requireExactKeys(
+    rawMime,
+    ['sha256', 'lengthBytes', 'contentType'],
+    [],
+    'gatewayMessage.rawMime',
+  );
+  if (
+    rawMime.contentType !== 'message/rfc822'
+    || !Number.isSafeInteger(rawMime.lengthBytes)
+    || Number(rawMime.lengthBytes) < 1
+    || Number(rawMime.lengthBytes)
+      > plugins.serveZoneInterfaces.data.coreMailLimits.serializedMimeBytes
+  ) {
+    throw new Error('CoreMail gateway MIME descriptor is invalid.');
+  }
+  return {
+    envelope: normalizeCoreMailEnvelope(value.envelope),
+    rawMime: {
+      sha256: plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(
+        rawMime.sha256,
+      ),
+      lengthBytes: Number(rawMime.lengthBytes),
+      contentType: 'message/rfc822',
+    },
+  };
+};
+
+const normalizeDisplayText = (
+  valueArg: unknown,
+  labelArg: string,
+  maximumBytesArg: number,
+  allowEmptyArg = false,
+): string => {
+  if (
+    typeof valueArg !== 'string'
+    || (!allowEmptyArg && valueArg.length === 0)
+    || valueArg.trim() !== valueArg
+    || /[\u0000-\u001f\u007f]/.test(valueArg)
+    || Buffer.byteLength(valueArg, 'utf8') > maximumBytesArg
+  ) {
+    throw new Error(`${labelArg} is invalid.`);
+  }
+  return valueArg;
+};
+
+const normalizeMailbox = (valueArg: unknown, labelArg: string): TMailbox => {
+  const value = requirePlainRecord(valueArg, labelArg);
+  requireExactKeys(value, ['address'], ['displayName'], labelArg);
+  return {
+    address: normalizeCoreMailMailboxAddress(value.address),
+    ...(value.displayName === undefined
+      ? {}
+      : {
+          displayName: normalizeDisplayText(
+            value.displayName,
+            `${labelArg}.displayName`,
+            256,
+          ),
+        }),
+  };
+};
+
+const normalizeMailboxArray = (
+  valueArg: unknown,
+  labelArg: string,
+  allowEmptyArg = false,
+): TMailbox[] => {
+  if (
+    !Array.isArray(valueArg)
+    || (!allowEmptyArg && valueArg.length === 0)
+    || valueArg.length > 100
+  ) {
+    throw new Error(`${labelArg} must be a bounded mailbox array.`);
+  }
+  const normalized = valueArg.map((entryArg, indexArg) =>
+    normalizeMailbox(entryArg, `${labelArg}[${indexArg}]`)
+  );
+  const addresses = normalized.map((entryArg) => entryArg.address);
+  if (new Set(addresses).size !== addresses.length) {
+    throw new Error(`${labelArg} contains duplicate addresses.`);
+  }
+  return normalized;
+};
+
+const forbiddenHeaderNames = new Set([
+  'bcc',
+  'cc',
+  'content-transfer-encoding',
+  'content-type',
+  'date',
+  'dkim-signature',
+  'from',
+  'message-id',
+  'mime-version',
+  'received',
+  'reply-to',
+  'return-path',
+  'subject',
+  'to',
+]);
+
+const normalizePart = (valueArg: unknown, labelArg: string): TPart => {
+  const value = requirePlainRecord(valueArg, labelArg);
+  requireExactKeys(
+    value,
+    ['partId', 'kind', 'contentType', 'sha256', 'lengthBytes'],
+    ['filename', 'contentId'],
+    labelArg,
+  );
+  if (typeof value.partId !== 'string' || !idRegex.test(value.partId)) {
+    throw new Error(`${labelArg}.partId is invalid.`);
+  }
+  if (value.kind !== 'text' && value.kind !== 'html' && value.kind !== 'attachment') {
+    throw new Error(`${labelArg}.kind is invalid.`);
+  }
+  if (typeof value.contentType !== 'string' || !contentTypeRegex.test(value.contentType)) {
+    throw new Error(`${labelArg}.contentType is invalid.`);
+  }
+  const sha256 = plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(value.sha256);
+  if (!Number.isSafeInteger(value.lengthBytes) || Number(value.lengthBytes) < 0) {
+    throw new Error(`${labelArg}.lengthBytes is invalid.`);
+  }
+  const lengthBytes = Number(value.lengthBytes);
+  const maximum = value.kind === 'text'
+    ? plugins.serveZoneInterfaces.data.coreMailLimits.textPartBytes
+    : value.kind === 'html'
+      ? plugins.serveZoneInterfaces.data.coreMailLimits.htmlPartBytes
+      : plugins.serveZoneInterfaces.data.coreMailLimits.attachmentBytes;
+  if (lengthBytes > maximum) {
+    throw new Error(`${labelArg} exceeds its content budget.`);
+  }
+  return {
+    partId: value.partId,
+    kind: value.kind,
+    contentType: value.contentType,
+    sha256,
+    lengthBytes,
+    ...(value.filename === undefined
+      ? {}
+      : {
+          filename: normalizeDisplayText(
+            value.filename,
+            `${labelArg}.filename`,
+            512,
+          ),
+        }),
+    ...(value.contentId === undefined
+      ? {}
+      : {
+          contentId: normalizeDisplayText(
+            value.contentId,
+            `${labelArg}.contentId`,
+            256,
+          ),
+        }),
+  };
+};
+
+export const normalizeCoreMailOutboundMessage = (
+  valueArg: unknown,
+  bindingArg: plugins.serveZoneInterfaces.data.ICoreMailBindingDesiredState,
+): TMessage => {
+  const value = requirePlainRecord(valueArg, 'message');
+  requireExactKeys(
+    value,
+    ['sender', 'recipients', 'subject', 'parts'],
+    ['replyTo', 'headers'],
+    'message',
+  );
+  const sender = normalizeMailbox(value.sender, 'message.sender');
+  if (!bindingArg.allowedSenders.includes(sender.address)) {
+    throw new Error('CoreMail sender is not authorized by the binding.');
+  }
+  const recipientsRecord = requirePlainRecord(value.recipients, 'message.recipients');
+  requireExactKeys(recipientsRecord, ['to'], ['cc', 'bcc'], 'message.recipients');
+  const to = normalizeMailboxArray(recipientsRecord.to, 'message.recipients.to');
+  const cc = recipientsRecord.cc === undefined
+    ? undefined
+    : normalizeMailboxArray(recipientsRecord.cc, 'message.recipients.cc', true);
+  const bcc = recipientsRecord.bcc === undefined
+    ? undefined
+    : normalizeMailboxArray(recipientsRecord.bcc, 'message.recipients.bcc', true);
+  const allRecipientAddresses = [...to, ...(cc ?? []), ...(bcc ?? [])]
+    .map((entryArg) => entryArg.address);
+  if (
+    allRecipientAddresses.length === 0
+    || new Set(allRecipientAddresses).size !== allRecipientAddresses.length
+  ) {
+    throw new Error('CoreMail recipients must be globally unique and non-empty.');
+  }
+  const partsValue = value.parts;
+  if (!Array.isArray(partsValue) || partsValue.length === 0) {
+    throw new Error('CoreMail message requires at least one part.');
+  }
+  const parts = partsValue.map((entryArg, indexArg) =>
+    normalizePart(entryArg, `message.parts[${indexArg}]`)
+  );
+  if (
+    new Set(parts.map((partArg) => partArg.partId)).size !== parts.length
+    || parts.filter((partArg) => partArg.kind === 'text').length > 1
+    || parts.filter((partArg) => partArg.kind === 'html').length > 1
+    || parts.filter((partArg) => partArg.kind === 'attachment').length >
+      plugins.serveZoneInterfaces.data.coreMailLimits.attachmentCount
+    || parts
+      .filter((partArg) => partArg.kind === 'attachment')
+      .reduce((totalArg, partArg) => totalArg + partArg.lengthBytes, 0) >
+        plugins.serveZoneInterfaces.data.coreMailLimits.aggregateAttachmentBytes
+  ) {
+    throw new Error('CoreMail message part set is invalid.');
+  }
+  const headers = value.headers === undefined
+    ? undefined
+    : (() => {
+        if (!Array.isArray(value.headers) || value.headers.length > 32) {
+          throw new Error('CoreMail custom headers are invalid.');
+        }
+        const seen = new Set<string>();
+        return value.headers.map((entryArg, indexArg) => {
+          const record = requirePlainRecord(entryArg, `message.headers[${indexArg}]`);
+          requireExactKeys(record, ['name', 'value'], [], `message.headers[${indexArg}]`);
+          if (
+            typeof record.name !== 'string'
+            || !/^[A-Za-z][A-Za-z0-9-]{0,62}$/.test(record.name)
+          ) {
+            throw new Error('CoreMail header name is invalid.');
+          }
+          const lowerName = record.name.toLowerCase();
+          if (forbiddenHeaderNames.has(lowerName) || seen.has(lowerName)) {
+            throw new Error('CoreMail header is transport-owned or duplicated.');
+          }
+          seen.add(lowerName);
+          return {
+            name: record.name,
+            value: normalizeDisplayText(
+              record.value,
+              `message.headers[${indexArg}].value`,
+              768,
+              true,
+            ),
+          };
+        });
+      })();
+  return {
+    sender,
+    recipients: {
+      to,
+      ...(cc ? { cc } : {}),
+      ...(bcc ? { bcc } : {}),
+    },
+    ...(value.replyTo === undefined
+      ? {}
+      : { replyTo: normalizeMailbox(value.replyTo, 'message.replyTo') }),
+    subject: normalizeDisplayText(value.subject, 'message.subject', 768, true),
+    ...(headers ? { headers } : {}),
+    parts,
+  };
+};
+
+export const createCoreMailSubmissionDigest = (
+  idempotencyKeyArg: string,
+  messageArg: TMessage,
+): plugins.serveZoneInterfaces.data.TCoreMailSha256 => {
+  if (!idRegex.test(idempotencyKeyArg)) {
+    throw new Error('CoreMail idempotency key is invalid.');
+  }
+  return createSha256(JSON.stringify({
+    schemaVersion: 1,
+    idempotencyKey: idempotencyKeyArg,
+    message: messageArg,
+  }));
+};