@serve.zone/interfaces 30.12.0 → 30.14.0

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);
+};

package/ts/data/coremail.ts

@@ -26,6 +26,11 @@ export type TCoreMailSubmissionState =
   | 'deferred'
   | 'failed'
   | 'deadLettered';
+/**
+ * Entry point that produced an outbound submission. `api` is the authenticated
+ * workload TypedRequest surface, `smtp` is the CoreMail submission listener.
+ */
+export type TCoreMailSubmissionSource = 'api' | 'smtp';
 export type TCoreMailInboundDeliveryState = 'pending' | 'fetching' | 'fetched' | 'acknowledged';
 export type TCoreMailInboundAckOutcome = 'processed' | 'discarded';
 export type TCoreMailRecipientAction = 'accept' | 'reject' | 'defer' | 'unhandled';
@@ -149,6 +154,8 @@ export interface ICoreMailSubmission {
   idempotencyKey: string;
   submissionDigest: TCoreMailSha256;
   state: TCoreMailSubmissionState;
+  /** Entry point that produced this submission. Omitted means an API submission. */
+  source?: TCoreMailSubmissionSource;
   parts: ICoreMailPartStatus[];
   transportMessageId?: string;
   attempts: number;
@@ -255,11 +262,38 @@ export interface ICoreMailRuntimeKeyReference {
   acceptUntil?: number;
 }
 
+export interface ICoreMailSmtpTlsDesiredState {
+  /** Keys in CoreMail's resolved runtime secret material holding PEM text, never plaintext values. */
+  certificatePemSecretKey: string;
+  privateKeyPemSecretKey: string;
+}
+
+/**
+ * Desired state for CoreMail's own SMTP submission listener (MSA).
+ *
+ * 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, so credential rotation windows behave exactly as they do for
+ * the workload TypedRequest surface. The listener stays unavailable until the
+ * referenced PEM material resolves; an enabled listener without resolvable
+ * certificate and private key material never accepts submissions.
+ */
+export interface ICoreMailSmtpDesiredState {
+  enabled: boolean;
+  /** Listener port inside the CoreMail workload. */
+  port: number;
+  /** Advertised EHLO hostname. */
+  hostname: string;
+  tls: ICoreMailSmtpTlsDesiredState;
+}
+
 export interface ICoreMailDesiredState {
   schemaVersion: 2;
   configEpoch: number;
   bindings: ICoreMailBindingDesiredState[];
   gateway: ICoreMailGatewayDesiredState;
+  /** Optional SMTP submission listener. An omitted listener keeps the API-only surface. */
+  smtp?: ICoreMailSmtpDesiredState;
   cursorKeys: ICoreMailRuntimeKeyReference[];
 }
 
@@ -293,6 +327,36 @@ export interface ICoreMailReconciliationStatus {
   errorCode?: TCoreMailErrorCode;
 }
 
+export interface ICoreMailOutboundMailCounters {
+  submittedApi: number;
+  submittedSmtp: number;
+  delivered: number;
+  deferred: number;
+  failed: number;
+  deadLettered: number;
+}
+
+export interface ICoreMailInboundMailCounters {
+  received: number;
+  acknowledgedProcessed: number;
+  acknowledgedDiscarded: number;
+}
+
+/**
+ * Per-service mail counters for one UTC calendar day, reported over the
+ * authenticated CoreMail control session.
+ */
+export interface ICoreMailServiceMailStatistics {
+  tenantId: string;
+  serviceId: string;
+  bindingId: string;
+  /** UTC calendar day, `YYYY-MM-DD`. */
+  dayUtc: string;
+  outbound: ICoreMailOutboundMailCounters;
+  inbound: ICoreMailInboundMailCounters;
+  updatedAt: number;
+}
+
 export interface ICoreMailRecipientResolution {
   recipient: string;
   action: TCoreMailRecipientAction;
@@ -311,6 +375,14 @@ export interface ICoreMailGatewayMessageDescriptor {
   };
 }
 
+/**
+ * dcrouter-reported delivery status for one accepted transport message.
+ *
+ * `updatedAt` must be monotonic per `transportMessageId`. A
+ * `transportMessageId` the gateway can never recognize again must be reported
+ * as a terminal `failed` status instead of an error, because CoreMail retries
+ * errors indefinitely.
+ */
 export interface ICoreMailGatewayOutboundStatus {
   transportMessageId: string;
   state: Extract<

package/ts/data/mail.ts

@@ -1,8 +1,16 @@
+import type { TCoreMailBindingState } from './coremail.js';
+
 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';
 
@@ -50,9 +58,26 @@ export type TMailDeliveryJournalEventType =
   | 'bounced'
   | 'complaint';
 
+/**
+ * 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';
+  | '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
@@ -94,11 +119,17 @@ export interface IMailTypedEndpointTarget {
   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;
@@ -231,8 +262,11 @@ 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. */
@@ -258,10 +292,68 @@ export interface IServiceMailAddressConfig {
   outbound?: IServiceMailOutboundConfig;
 }
 
+/**
+ * Public CoreMail binding metadata for one service. Verifier metadata and
+ * lifecycle state only: never plaintext credential material, exactly like
+ * `IServiceMailOutboundConfig`.
+ */
+export interface ICoreMailServiceBinding {
+  bindingId: string;
+  credentialId: string;
+  credentialVersion: number;
+  verificationHash: string;
+  state: TCoreMailBindingState;
+  lastRotatedAt?: number;
+  /** Previous credential during a rotation window. */
+  retiring?: {
+    credentialId: string;
+    credentialVersion: number;
+    verificationHash: string;
+    acceptUntil: number;
+  };
+}
+
 export interface IServiceMailConfig {
   enabled?: boolean;
   defaultFrom?: string;
+  /**
+   * Explicit outbound sender allowlist for this service. Absent means the
+   * allowlist is still inferred from the per-address `outbound.enabled` flags.
+   */
+  allowedSenders?: string[];
   addresses: IServiceMailAddressConfig[];
+  /**
+   * Control-plane owned CoreMail binding metadata. Public metadata only; never
+   * plaintext. Callers never write this field.
+   */
+  coreMail?: ICoreMailServiceBinding;
+}
+
+/** Caller-writable mail configuration. CoreMail binding metadata is excluded. */
+export type TServiceMailWritableConfig = Omit<IServiceMailConfig, 'coreMail'>;
+
+export interface IServiceMailTargetAddressSummary {
+  address: string;
+  inbound: {
+    enabled: boolean;
+    targetType: IServiceMailInboundConfig['targetType'] | undefined;
+  };
+  outbound: {
+    enabled: boolean;
+    credentialId?: string;
+  };
+}
+
+/** One service row of the operator-facing mail target inventory. */
+export interface IServiceMailTargetSummary {
+  serviceId: string;
+  serviceName: string;
+  organizationId: string;
+  addresses: IServiceMailTargetAddressSummary[];
+  coreMail?: {
+    bindingId: string;
+    state: TCoreMailBindingState;
+  };
 }
 
 export interface IMailEnvelope {

package/ts/data/secret.ts

@@ -28,6 +28,7 @@ export type TSecretManagementSource =
   | 'operator'
   | 'appstore'
   | 'mail'
+  | 'coremail'
   | 'oidc'
   | 'webpush'
   | 'platform'
@@ -37,6 +38,7 @@ export type TSecretManagementScope =
   | 'operator'
   | `appstore:${string}`
   | `mail:${string}`
+  | `coremail:${string}`
   | `oidc:${string}`
   | `webpush:${string}`
   | `platform:${string}`
@@ -505,7 +507,7 @@ export const validateSecretVersionMetadata = (
   }
   if (!isNonNegativeSafeInteger(versionArg.createdAt)
     || !isSecretIdentifier(versionArg.createdBy)
-    || !['operator', 'appstore', 'mail', 'oidc', 'webpush', 'platform', 'system']
+    || !['operator', 'appstore', 'mail', 'coremail', 'oidc', 'webpush', 'platform', 'system']
       .includes(versionArg.source as string)) {
     errors.push('secret version metadata creation fields must be canonical');
   }
@@ -712,7 +714,8 @@ export const validateSecretManagementScope = (
   const scopeIdentifier = scopeArg.slice(separatorIndex + 1);
   if (
     separatorIndex < 1
-    || !['appstore', 'mail', 'oidc', 'webpush', 'platform', 'system'].includes(scopeSource)
+    || !['appstore', 'mail', 'coremail', 'oidc', 'webpush', 'platform', 'system']
+      .includes(scopeSource)
     || !isSecretIdentifier(scopeIdentifier)
   ) {
     return ['management scope must be canonical'];
@@ -819,7 +822,7 @@ export const validateSecretMetadata = (secretArg: unknown): string[] => {
       errors.push('secret metadata tag keys must be unique');
     }
   }
-  if (!['operator', 'appstore', 'mail', 'oidc', 'webpush', 'platform', 'system']
+  if (!['operator', 'appstore', 'mail', 'coremail', 'oidc', 'webpush', 'platform', 'system']
     .includes(secretArg.managementSource as string)) {
     errors.push('secret metadata managementSource must be canonical');
   } else {

package/ts/data/service.ts

@@ -2,7 +2,7 @@ import type { IServiceRessources } from './docker.js';
 import type { IRegistryTarget } from './registry.js';
 import type { IAppStorePublishedPort } from '../appstore/index.js';
 import type { IHostedAppLifecycleState } from './hostedapp.js';
-import type { IServiceMailConfig } from './mail.js';
+import type { IServiceMailConfig, TServiceMailWritableConfig } from './mail.js';
 import type { IServiceWebPushConfig } from './webpush.js';
 import type {
   IImageRolloutStatus,
@@ -254,7 +254,14 @@ export type TServiceWritableData = Omit<
   | 'imageRolloutStatus'
   | 'secretConfiguration'
   | 'secretDeployment'
->;
+  | 'mail'
+> & {
+  /**
+   * Mail configuration stays caller-writable, except for the CoreMail binding
+   * metadata Cloudly derives from reconciliation.
+   */
+  mail?: TServiceMailWritableConfig;
+};
 
 /** Caller-writable update data. Null explicitly removes an existing argument vector. */
 export type TServiceUpdateWritableData = Omit<