@serve.zone/coremail 1.0.0

package/ts/classes.inbound.ts

@@ -0,0 +1,898 @@
+import * as plugins from './plugins.js';
+import { type ICoreMailModels } from './classes.models.js';
+import {
+  createOpaqueToken,
+  createSha256,
+} from './classes.storage.js';
+import { CoreMailTransferService } from './classes.transfer.js';
+import {
+  normalizeCoreMailConnectionInfo,
+  normalizeCoreMailEnvelope,
+  normalizeCoreMailGatewayMessage,
+  normalizeCoreMailMailboxAddress,
+} from './coremail.validation.js';
+import { CoreMailInboundCursorCodec } from './coremail.cursor.js';
+import {
+  createCoreMailPendingQuotaDescriptor,
+  decrementCoreMailQuotaCounter,
+  ensureCoreMailQuotaCounter,
+  incrementCoreMailQuotaCounter,
+  withCoreMailTransaction,
+} from './coremail.quota.js';
+import {
+  requireCoreMailIdentifier,
+  requireCoreMailUuid,
+} from './coremail.selectors.js';
+import type {
+  ICoreMailInboundDeliveryRecord,
+  ICoreMailInboundHandoffRecord,
+  ICoreMailRecipientHandleRecord,
+} from './coremail.persistence.js';
+import type {
+  ICoreMailWorkloadSession,
+  ITransferAuthority,
+} from './interfaces.js';
+
+type TDesiredState = plugins.serveZoneInterfaces.data.ICoreMailDesiredState;
+type TInboundDelivery = plugins.serveZoneInterfaces.data.ICoreMailInboundDelivery;
+type TStoredInboundDelivery =
+  plugins.smartdata.TStoredDocument<ICoreMailInboundDeliveryRecord>;
+type TStoredInboundHandoff =
+  plugins.smartdata.TStoredDocument<ICoreMailInboundHandoffRecord>;
+type TStoredRecipientHandle =
+  plugins.smartdata.TStoredDocument<ICoreMailRecipientHandleRecord>;
+
+const routingHandleTtlMs =
+  plugins.serveZoneInterfaces.data.coreMailLimits.routingHandleTtlMs;
+const listLimitMaximum =
+  plugins.serveZoneInterfaces.data.coreMailLimits.inboundPageSize;
+
+const gatewayAuthority = (serviceIdArg: string): ITransferAuthority => ({
+  kind: 'gateway',
+  tenantId: '-',
+  serviceId: serviceIdArg,
+  bindingId: '-',
+});
+
+const workloadAuthority = (
+  sessionArg: ICoreMailWorkloadSession,
+): ITransferAuthority => ({
+  kind: 'workload',
+  tenantId: sessionArg.tenantId,
+  serviceId: sessionArg.serviceId,
+  bindingId: sessionArg.bindingId,
+});
+
+const workloadFilter = (
+  sessionArg: ICoreMailWorkloadSession,
+  deliveryIdArg: string | undefined,
+) => ({
+  tenantId: requireCoreMailIdentifier(sessionArg.tenantId, 'session.tenantId'),
+  serviceId: requireCoreMailIdentifier(sessionArg.serviceId, 'session.serviceId'),
+  bindingId: requireCoreMailIdentifier(sessionArg.bindingId, 'session.bindingId'),
+  bindingRevision: sessionArg.bindingRevision,
+  ...(deliveryIdArg === undefined
+    ? {}
+    : { deliveryId: requireCoreMailUuid(deliveryIdArg, 'deliveryId') }),
+});
+
+const toPublicDelivery = (
+  deliveryArg: ICoreMailInboundDeliveryRecord,
+): TInboundDelivery => ({
+  deliveryId: deliveryArg.deliveryId,
+  transportDeliveryId: deliveryArg.transportDeliveryId,
+  state: deliveryArg.state,
+  envelope: deliveryArg.envelope,
+  rawMime: {
+    sha256: deliveryArg.rawMimeSha256,
+    lengthBytes: deliveryArg.rawMimeLengthBytes,
+    contentType: 'message/rfc822',
+  },
+  ...(deliveryArg.messageId ? { messageId: deliveryArg.messageId } : {}),
+  ...(deliveryArg.subject ? { subject: deliveryArg.subject } : {}),
+  receivedAt: deliveryArg.receivedAt,
+  updatedAt: deliveryArg.updatedAt,
+  ...(deliveryArg.state === 'acknowledged'
+    ? {
+        acknowledgedAt: deliveryArg.updatedAt,
+        acknowledgedOutcome: deliveryArg.acknowledgedOutcome!,
+      }
+    : {}),
+});
+
+const createEnvelopeDigest = (
+  envelopeArg: plugins.serveZoneInterfaces.data.ICoreMailEnvelope,
+  sourceArg: plugins.serveZoneInterfaces.data.IMailConnectionInfo,
+) => createSha256(JSON.stringify({
+  envelope: envelopeArg,
+  source: sourceArg,
+}));
+
+const canonicalJson = (valueArg: unknown): string => {
+  const visit = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(visit);
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(
+        Object.keys(value as Record<string, unknown>)
+          .sort()
+          .map((keyArg) => [
+            keyArg,
+            visit((value as Record<string, unknown>)[keyArg]),
+          ]),
+      );
+    }
+    return value;
+  };
+  return JSON.stringify(visit(valueArg));
+};
+
+const isUniqueConflict = (errorArg: unknown): boolean =>
+  errorArg instanceof plugins.smartdata.SmartdataExactPersistenceError
+  && errorArg.code === 'unique_conflict';
+
+export class CoreMailInboundService {
+  private readonly cursorCodec: CoreMailInboundCursorCodec;
+
+  public constructor(
+    private readonly database: plugins.smartdata.SmartdataDb,
+    private readonly models: ICoreMailModels,
+    private readonly transfers: CoreMailTransferService,
+    private readonly serviceId: string,
+    private readonly getDesiredState: () => Promise<TDesiredState | null>,
+    resolveRuntimeSecretArg: (secretKeyArg: string) => string,
+    private readonly now: () => number = Date.now,
+  ) {
+    this.cursorCodec = new CoreMailInboundCursorCodec(resolveRuntimeSecretArg);
+  }
+
+  public async resolveRecipients(
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailGatewayResolveRecipients['request'],
+  ): Promise<{
+    resolutions: plugins.serveZoneInterfaces.data.ICoreMailRecipientResolution[];
+  }> {
+    const desiredState = await this.getDesiredState();
+    if (!desiredState) {
+      throw new Error('CoreMail desired state is unavailable.');
+    }
+    if (
+      !Array.isArray(requestArg.recipients)
+      || requestArg.recipients.length === 0
+      || requestArg.recipients.length > 100
+    ) {
+      throw new Error('CoreMail gateway recipients are invalid.');
+    }
+    const envelope = normalizeCoreMailEnvelope(requestArg.envelope);
+    const source = normalizeCoreMailConnectionInfo(requestArg.source);
+    const envelopeDigest = createEnvelopeDigest(envelope, source);
+    const recipients = requestArg.recipients.map(normalizeCoreMailMailboxAddress);
+    if (new Set(recipients).size !== recipients.length) {
+      throw new Error('CoreMail gateway recipients contain duplicates.');
+    }
+    const resolutions:
+      plugins.serveZoneInterfaces.data.ICoreMailRecipientResolution[] = [];
+    const pendingCounts = new Map<string, number>();
+    for (const recipient of recipients) {
+      const binding = desiredState.bindings.find((bindingArg) =>
+        bindingArg.state === 'active'
+        && bindingArg.capabilities.includes('inbound')
+        && bindingArg.inboundRecipients.includes(recipient)
+      );
+      if (!binding) {
+        resolutions.push({
+          recipient,
+          action: 'reject',
+          smtpCode: 550,
+          message: 'Recipient unavailable',
+        });
+        continue;
+      }
+      let pendingCount = pendingCounts.get(binding.bindingId);
+      if (pendingCount === undefined) {
+        pendingCount = await this.models.InboundDelivery.exact.count({
+          tenantId: binding.tenantId,
+          serviceId: binding.serviceId,
+          bindingId: binding.bindingId,
+          bindingRevision: binding.revision,
+          state: {
+            $in: [...plugins.serveZoneInterfaces.data.coreMailQuotaPolicy
+              .pendingInboundStates],
+          },
+        });
+        pendingCounts.set(binding.bindingId, pendingCount);
+      }
+      if (pendingCount >= binding.limits.maxPendingInbound) {
+        resolutions.push({
+          recipient,
+          action: 'defer',
+          smtpCode: 452,
+          message: 'Recipient temporarily unavailable',
+        });
+        continue;
+      }
+      const routingHandle = createOpaqueToken();
+      const createdAt = this.now();
+      const inserted = await this.models.RecipientHandle.exact.insert({
+        routingHandle: createSha256(routingHandle),
+        tenantId: binding.tenantId,
+        serviceId: binding.serviceId,
+          bindingId: binding.bindingId,
+          bindingRevision: binding.revision,
+          maxPendingInbound: binding.limits.maxPendingInbound,
+          recipient,
+        envelopeDigest,
+        state: 'issued',
+        expiresAt: createdAt + routingHandleTtlMs,
+        createdAt,
+      });
+      if (inserted.status === 'conflict') {
+        throw new Error('CoreMail routing handle identity conflict.');
+      }
+      resolutions.push({
+        recipient,
+        action: 'accept',
+        routingHandle,
+      });
+    }
+    return { resolutions };
+  }
+
+  public async prepareInboundHandoff(
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailGatewayPrepareInboundHandoff['request'],
+  ): Promise<{
+    handoffId: string;
+    grant?: plugins.serveZoneInterfaces.data.ICoreMailUploadGrant;
+    replayed: boolean;
+  }> {
+    if (
+      !Array.isArray(requestArg.routingHandles)
+      || requestArg.routingHandles.length === 0
+      || requestArg.routingHandles.length > 100
+    ) {
+      throw new Error('CoreMail inbound handoff identity is invalid.');
+    }
+    const transportDeliveryId = requireCoreMailIdentifier(
+      requestArg.transportDeliveryId,
+      'transportDeliveryId',
+    );
+    const routingHandles = requestArg.routingHandles.map((handleArg) => {
+      if (typeof handleArg !== 'string' || handleArg.length < 32 || handleArg.length > 512) {
+        throw new Error('CoreMail routing handle is invalid.');
+      }
+      return createSha256(handleArg);
+    });
+    if (new Set(routingHandles).size !== routingHandles.length) {
+      throw new Error('CoreMail inbound handoff contains duplicate routing handles.');
+    }
+    const message = normalizeCoreMailGatewayMessage(requestArg.message);
+    const source = normalizeCoreMailConnectionInfo(requestArg.source);
+    const envelopeDigest = createEnvelopeDigest(message.envelope, source);
+    const existing = await this.models.InboundHandoff.exact.findStoredOne({
+      transportDeliveryId,
+    });
+    if (existing) {
+      if (
+        canonicalJson(existing.routingHandles) !== canonicalJson(routingHandles)
+        || canonicalJson(existing.message) !== canonicalJson(message)
+        || canonicalJson(existing.source) !== canonicalJson(source)
+        || existing.state === 'failed'
+      ) {
+        throw new Error('CoreMail inbound handoff replay conflicts with persisted intent.');
+      }
+      if (existing.state === 'completed') {
+        return {
+          handoffId: existing.handoffId,
+          replayed: true,
+        };
+      }
+      const grant = await this.issueInboundGrant(existing);
+      return {
+        handoffId: existing.handoffId,
+        grant,
+        replayed: true,
+      };
+    }
+    const now = this.now();
+    for (const routingHandle of routingHandles) {
+      const handle = await this.models.RecipientHandle.exact.findStoredOne({
+        routingHandle,
+        state: 'issued',
+        expiresAt: { $gte: now },
+      });
+      if (!handle) {
+        throw new Error('CoreMail routing authority is unavailable.');
+      }
+      if (handle.envelopeDigest !== envelopeDigest) {
+        throw new Error('CoreMail routing authority is bound to another envelope.');
+      }
+    }
+    const handoffId = plugins.nodeCrypto.randomUUID();
+    const handoff: ICoreMailInboundHandoffRecord = {
+      handoffId,
+      revision: 0,
+      transportDeliveryId,
+      routingHandles,
+      message,
+      source,
+      state: 'prepared',
+      objectKey: `inbound-mime/${handoffId}/${message.rawMime.sha256.slice(7)}`,
+      deliveryIds: [],
+      createdAt: now,
+      updatedAt: now,
+    };
+    let storedHandoff: TStoredInboundHandoff;
+    try {
+      const inserted = await this.models.InboundHandoff.exact.insert(handoff);
+      if (inserted.status === 'conflict') {
+        throw new Error('CoreMail inbound handoff identity conflict.');
+      }
+      storedHandoff = inserted.document;
+    } catch (error) {
+      if (!isUniqueConflict(error)) {
+        throw error;
+      }
+      const concurrent =
+        await this.models.InboundHandoff.exact.findStoredOne({
+          transportDeliveryId,
+        });
+      if (
+        !concurrent
+          || canonicalJson(concurrent.routingHandles)
+            !== canonicalJson(routingHandles)
+          || canonicalJson(concurrent.message) !== canonicalJson(message)
+          || canonicalJson(concurrent.source) !== canonicalJson(source)
+        || concurrent.state === 'failed'
+      ) {
+        throw new Error(
+          'CoreMail inbound handoff conflicts with persisted intent.',
+        );
+      }
+      if (concurrent.state === 'completed') {
+        return {
+          handoffId: concurrent.handoffId,
+          replayed: true,
+        };
+      }
+      const concurrentGrant = await this.issueInboundGrant(concurrent);
+      return {
+        handoffId: concurrent.handoffId,
+        grant: concurrentGrant,
+        replayed: true,
+      };
+    }
+    const grant = await this.issueInboundGrant(storedHandoff);
+    return { handoffId, grant, replayed: false };
+  }
+
+  private async issueInboundGrant(
+    handoffArg: TStoredInboundHandoff,
+  ): Promise<plugins.serveZoneInterfaces.data.ICoreMailUploadGrant> {
+    if (handoffArg.state !== 'prepared' && handoffArg.state !== 'uploaded') {
+      throw new Error('CoreMail inbound handoff cannot issue an upload grant.');
+    }
+    const grant = await this.transfers.issueGrant({
+      authority: gatewayAuthority(this.serviceId),
+      purpose: 'inbound-mime-upload',
+      method: 'PUT',
+      expectedSha256: handoffArg.message.rawMime.sha256,
+      lengthBytes: handoffArg.message.rawMime.lengthBytes,
+      contentType: 'message/rfc822',
+      objectKey: handoffArg.objectKey,
+    });
+    const update = await this.models.InboundHandoff.exact.transition({
+      current: handoffArg,
+      change: (modelArg) => {
+        modelArg.grantId = grant.grantId;
+        modelArg.state = 'uploaded';
+        modelArg.updatedAt = this.now();
+        modelArg.revision += 1;
+      },
+    });
+    if (update.status !== 'transitioned') {
+      throw new Error('CoreMail inbound handoff upload fence changed.');
+    }
+    return grant as plugins.serveZoneInterfaces.data.ICoreMailUploadGrant;
+  }
+
+  public async completeInboundHandoff(
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailGatewayCompleteInboundHandoff['request'],
+  ): Promise<{ accepted: true; deliveryIds: string[]; replayed: boolean }> {
+    const handoff = await this.models.InboundHandoff.exact.findStoredOne({
+      handoffId: requireCoreMailUuid(requestArg.handoffId, 'handoffId'),
+    });
+    if (!handoff || handoff.state === 'failed') {
+      throw new Error('CoreMail inbound handoff is unavailable.');
+    }
+    const sha256 = plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(
+      requestArg.sha256,
+    );
+    if (
+      (handoff.state !== 'uploaded' && handoff.state !== 'completed')
+      || handoff.message.rawMime.sha256 !== sha256
+      || handoff.message.rawMime.lengthBytes !== requestArg.lengthBytes
+    ) {
+      throw new Error('CoreMail inbound handoff completion is invalid.');
+    }
+    await this.transfers.assertConsumed({
+      grantId: requestArg.grantId,
+      authority: gatewayAuthority(this.serviceId),
+      purpose: 'inbound-mime-upload',
+      expectedSha256: handoff.message.rawMime.sha256,
+      lengthBytes: handoff.message.rawMime.lengthBytes,
+      objectKey: handoff.objectKey,
+    });
+    if (handoff.state === 'completed') {
+      return {
+        accepted: true,
+        deliveryIds: [...handoff.deliveryIds],
+        replayed: true,
+      };
+    }
+    const handles: TStoredRecipientHandle[] = [];
+    for (const routingHandle of handoff.routingHandles) {
+      const handle = await this.models.RecipientHandle.exact.findStoredOne({
+        routingHandle,
+      });
+      if (
+        !handle
+        || (
+          handle.state === 'consumed'
+          && handle.handoffId !== handoff.handoffId
+        )
+        || (
+          handle.state === 'issued'
+          && handle.expiresAt < this.now()
+        )
+        || handle.envelopeDigest !== createEnvelopeDigest(
+          handoff.message.envelope,
+          handoff.source,
+        )
+      ) {
+        throw new Error('CoreMail routing handle fence changed.');
+      }
+      handles.push(handle);
+    }
+    const grouped = new Map<string, TStoredRecipientHandle[]>();
+    for (const handle of handles) {
+      const key = JSON.stringify([
+        handle.tenantId,
+        handle.serviceId,
+        handle.bindingId,
+        handle.bindingRevision,
+      ]);
+      const group = grouped.get(key) ?? [];
+      group.push(handle);
+      grouped.set(key, group);
+    }
+    const groups = [...grouped.values()];
+    const candidates: ICoreMailInboundDeliveryRecord[] = [];
+    for (const group of groups) {
+      const authority = group[0];
+      if (group.some((handleArg) =>
+        handleArg.maxPendingInbound !== authority.maxPendingInbound
+      )) {
+        throw new Error('CoreMail routing handles disagree on pending quota.');
+      }
+      const quota = createCoreMailPendingQuotaDescriptor(authority);
+      await ensureCoreMailQuotaCounter(this.models, quota);
+      const receivedAt = this.now();
+      candidates.push({
+        deliveryId: plugins.nodeCrypto.randomUUID(),
+        tenantId: authority.tenantId,
+        serviceId: authority.serviceId,
+        bindingId: authority.bindingId,
+        bindingRevision: authority.bindingRevision,
+        revision: 0,
+        transportDeliveryId: handoff.transportDeliveryId,
+        state: 'pending',
+        envelope: {
+          mailFrom: handoff.message.envelope.mailFrom,
+          rcptTo: group.map((handleArg) => handleArg.recipient),
+        },
+        rawMimeSha256: handoff.message.rawMime.sha256,
+        rawMimeLengthBytes: handoff.message.rawMime.lengthBytes,
+        rawMimeObjectKey: handoff.objectKey,
+        receivedAt,
+        updatedAt: receivedAt,
+      });
+    }
+    try {
+      const deliveryIds = await withCoreMailTransaction(
+        this.database,
+        async (transactionArg) => {
+          const transactionHandoff =
+            await this.models.InboundHandoff.exact.findStoredOne({
+              handoffId: handoff.handoffId,
+              state: 'uploaded',
+              revision: handoff.revision,
+            }, { session: transactionArg });
+          if (!transactionHandoff) {
+            throw new Error('CoreMail inbound handoff completion fence changed.');
+          }
+          const committedIds: string[] = [];
+          for (const [index, group] of groups.entries()) {
+            const authority = group[0];
+            const candidate = candidates[index];
+            const quota = createCoreMailPendingQuotaDescriptor(authority);
+            const existing = await this.models.InboundDelivery.exact.findStoredOne({
+              transportDeliveryId: handoff.transportDeliveryId,
+              bindingId: authority.bindingId,
+              bindingRevision: authority.bindingRevision,
+            }, { session: transactionArg });
+            if (!existing) {
+              await incrementCoreMailQuotaCounter(
+                this.models,
+                quota,
+                authority.maxPendingInbound,
+                candidate.receivedAt,
+                transactionArg,
+              );
+              const inserted = await this.models.InboundDelivery.exact.insert(
+                candidate,
+                { session: transactionArg },
+              );
+              if (inserted.status === 'conflict') {
+                throw new Error('CoreMail inbound delivery identity conflict.');
+              }
+            }
+            for (const originalHandle of group) {
+              const handle = await this.models.RecipientHandle.exact.findStoredOne(
+                { routingHandle: originalHandle.routingHandle },
+                { session: transactionArg },
+              );
+              if (
+                !handle
+                || handle.tenantId !== authority.tenantId
+                || handle.serviceId !== authority.serviceId
+                || handle.bindingId !== authority.bindingId
+                || handle.bindingRevision !== authority.bindingRevision
+                || handle.maxPendingInbound !== authority.maxPendingInbound
+                || (
+                  handle.state === 'consumed'
+                  && handle.handoffId !== handoff.handoffId
+                )
+                || (
+                  handle.state === 'issued'
+                  && handle.expiresAt < candidate.receivedAt
+                )
+              ) {
+                throw new Error('CoreMail routing handle fence changed.');
+              }
+              if (handle.state === 'issued') {
+                const claim = await this.models.RecipientHandle.exact.transition({
+                  current: handle,
+                  change: (modelArg) => {
+                    modelArg.state = 'consumed';
+                    modelArg.handoffId = handoff.handoffId;
+                  },
+                }, { session: transactionArg });
+                if (claim.status !== 'transitioned') {
+                  throw new Error('CoreMail routing handle claim fence changed.');
+                }
+              }
+            }
+            committedIds.push(existing?.deliveryId ?? candidate.deliveryId);
+          }
+          committedIds.sort();
+          const completion = await this.models.InboundHandoff.exact.transition({
+            current: transactionHandoff,
+            change: (modelArg) => {
+              modelArg.state = 'completed';
+              modelArg.grantId = requestArg.grantId;
+              modelArg.deliveryIds = committedIds;
+              modelArg.completedAt = this.now();
+              modelArg.updatedAt = modelArg.completedAt;
+              modelArg.revision += 1;
+            },
+          }, { session: transactionArg });
+          if (completion.status !== 'transitioned') {
+            throw new Error('CoreMail inbound handoff completion fence changed.');
+          }
+          return committedIds;
+        },
+      );
+      return { accepted: true, deliveryIds, replayed: false };
+    } catch (error) {
+      const replay = await this.models.InboundHandoff.exact.findStoredOne({
+        handoffId: handoff.handoffId,
+        state: 'completed',
+      });
+      if (replay) {
+        return {
+          accepted: true,
+          deliveryIds: [...replay.deliveryIds],
+          replayed: true,
+        };
+      }
+      throw error;
+    }
+  }
+
+  public async listDeliveries(
+    sessionArg: ICoreMailWorkloadSession,
+    requestArg: {
+      cursor?: string;
+      limit: number;
+    },
+  ): Promise<{
+    deliveries: TInboundDelivery[];
+    nextCursor?: string;
+  }> {
+    if (
+      !Number.isSafeInteger(requestArg.limit)
+      || requestArg.limit < 1
+      || requestArg.limit > listLimitMaximum
+      || (
+        requestArg.cursor !== undefined
+        && (
+          typeof requestArg.cursor !== 'string'
+          || requestArg.cursor.length >
+            plugins.serveZoneInterfaces.data.coreMailLimits.cursorBytes
+        )
+      )
+    ) {
+      throw new Error('CoreMail inbound list window is invalid.');
+    }
+    const authority = {
+      tenantId: sessionArg.tenantId,
+      serviceId: sessionArg.serviceId,
+      bindingId: sessionArg.bindingId,
+      bindingRevision: sessionArg.bindingRevision,
+    };
+    const now = this.now();
+    const desiredState = await this.getDesiredState();
+    if (!desiredState) {
+      throw new Error('CoreMail desired state is unavailable.');
+    }
+    const position = requestArg.cursor
+      ? this.cursorCodec.decode(
+          requestArg.cursor,
+          authority,
+          now,
+          desiredState.cursorKeys,
+        )
+      : null;
+    const snapshotAt = position?.snapshotAt ?? now;
+    const deliveries = await this.models.InboundDelivery.exact.findStored({
+      filter: {
+        ...workloadFilter(sessionArg, undefined),
+        receivedAt: { $lt: snapshotAt },
+        ...(position
+          ? {
+              $or: [{
+                receivedAt: { $gt: position.receivedAt },
+              }, {
+                receivedAt: position.receivedAt,
+                deliveryId: { $gt: position.deliveryId },
+              }],
+            }
+          : {}),
+      },
+      sort: { receivedAt: 1, deliveryId: 1 },
+      limit: requestArg.limit + 1,
+    });
+    const page: TInboundDelivery[] = [];
+    for (const delivery of deliveries.slice(0, requestArg.limit)) {
+      const publicDelivery = toPublicDelivery(delivery);
+      const cursor = this.cursorCodec.encode(
+        authority,
+        {
+          snapshotAt,
+          receivedAt: delivery.receivedAt,
+          deliveryId: delivery.deliveryId,
+        },
+        desiredState.cursorKeys,
+      );
+      const candidate = {
+        deliveries: [...page, publicDelivery],
+        nextCursor: cursor,
+      };
+      if (
+        Buffer.byteLength(JSON.stringify(candidate), 'utf8')
+        > plugins.serveZoneInterfaces.data.coreMailLimits.inboundPageBytes
+      ) {
+        break;
+      }
+      page.push(publicDelivery);
+    }
+    if (page.length === 0 && deliveries.length > 0) {
+      throw new Error('CoreMail inbound delivery exceeds the page byte budget.');
+    }
+    const hasMore = page.length < deliveries.length;
+    const last = page.at(-1);
+    const response = {
+      deliveries: page,
+      ...(hasMore && last
+        ? {
+            nextCursor: this.cursorCodec.encode(
+              authority,
+              {
+                snapshotAt,
+                receivedAt: last.receivedAt,
+                deliveryId: last.deliveryId,
+              },
+              desiredState.cursorKeys,
+            ),
+          }
+        : {}),
+    };
+    return plugins.serveZoneInterfaces.data
+      .normalizeCoreMailInboundDeliveryPage(response);
+  }
+
+  public async prepareFetch(
+    sessionArg: ICoreMailWorkloadSession,
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailPrepareInboundFetch['request'],
+  ): Promise<{ grant: plugins.serveZoneInterfaces.data.ICoreMailDownloadGrant }> {
+    const delivery = await this.requireDelivery(sessionArg, requestArg.deliveryId);
+    if (delivery.state === 'acknowledged') {
+      throw new Error('CoreMail inbound delivery is already acknowledged.');
+    }
+    const grant = await this.transfers.issueGrant({
+      authority: workloadAuthority(sessionArg),
+      purpose: 'inbound-mime-download',
+      method: 'GET',
+      expectedSha256: delivery.rawMimeSha256,
+      lengthBytes: delivery.rawMimeLengthBytes,
+      contentType: 'message/rfc822',
+      objectKey: delivery.rawMimeObjectKey,
+    });
+    const update = await this.models.InboundDelivery.exact.transition({
+      current: delivery,
+      change: (modelArg) => {
+        modelArg.state = 'fetching';
+        modelArg.fetchGrantId = grant.grantId;
+        modelArg.updatedAt = this.now();
+        modelArg.revision += 1;
+      },
+    });
+    if (update.status !== 'transitioned') {
+      throw new Error('CoreMail inbound fetch preparation fence changed.');
+    }
+    return {
+      grant: grant as plugins.serveZoneInterfaces.data.ICoreMailDownloadGrant,
+    };
+  }
+
+  public async completeFetch(
+    sessionArg: ICoreMailWorkloadSession,
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailCompleteInboundFetch['request'],
+  ): Promise<{ delivery: TInboundDelivery }> {
+    const delivery = await this.requireDelivery(sessionArg, requestArg.deliveryId);
+    const sha256 = plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(
+      requestArg.sha256,
+    );
+    if (
+      (delivery.state !== 'fetching' && delivery.state !== 'fetched')
+      || delivery.rawMimeSha256 !== sha256
+      || delivery.rawMimeLengthBytes !== requestArg.lengthBytes
+    ) {
+      throw new Error('CoreMail inbound fetch completion is invalid.');
+    }
+    await this.transfers.assertConsumed({
+      grantId: requestArg.grantId,
+      authority: workloadAuthority(sessionArg),
+      purpose: 'inbound-mime-download',
+      expectedSha256: delivery.rawMimeSha256,
+      lengthBytes: delivery.rawMimeLengthBytes,
+      objectKey: delivery.rawMimeObjectKey,
+    });
+    if (delivery.state === 'fetched') {
+      return { delivery: toPublicDelivery(delivery) };
+    }
+    const updatedAt = this.now();
+    const update = await this.models.InboundDelivery.exact.transition({
+      current: delivery,
+      change: (modelArg) => {
+        modelArg.state = 'fetched';
+        modelArg.fetchGrantId = requestArg.grantId;
+        modelArg.updatedAt = updatedAt;
+        modelArg.revision += 1;
+      },
+    });
+    if (update.status !== 'transitioned') {
+      throw new Error('CoreMail inbound fetch completion fence changed.');
+    }
+    return {
+      delivery: toPublicDelivery(update.document),
+    };
+  }
+
+  public async acknowledge(
+    sessionArg: ICoreMailWorkloadSession,
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailAcknowledgeInboundDelivery['request'],
+  ): Promise<{ delivery: TInboundDelivery; replayed: boolean }> {
+    if (requestArg.outcome !== 'processed' && requestArg.outcome !== 'discarded') {
+      throw new Error('CoreMail inbound acknowledgement outcome is invalid.');
+    }
+    const delivery = await this.requireDelivery(sessionArg, requestArg.deliveryId);
+    if (delivery.state === 'acknowledged') {
+      if (delivery.acknowledgedOutcome !== requestArg.outcome) {
+        throw new Error('CoreMail inbound acknowledgement conflicts with persisted intent.');
+      }
+      return { delivery: toPublicDelivery(delivery), replayed: true };
+    }
+    if (delivery.state !== 'fetched') {
+      throw new Error('CoreMail inbound delivery must be fetched before acknowledgement.');
+    }
+    const updatedAt = this.now();
+    const quota = createCoreMailPendingQuotaDescriptor({
+      tenantId: sessionArg.tenantId,
+      serviceId: sessionArg.serviceId,
+      bindingId: sessionArg.bindingId,
+      bindingRevision: sessionArg.bindingRevision,
+    });
+    await ensureCoreMailQuotaCounter(this.models, quota);
+    const transactionResult = await withCoreMailTransaction(
+      this.database,
+      async (transactionArg) => {
+        const current = await this.models.InboundDelivery.exact.findStoredOne(
+          workloadFilter(sessionArg, requestArg.deliveryId),
+          { session: transactionArg },
+        );
+        if (!current) {
+          throw new Error('CoreMail inbound delivery is unavailable.');
+        }
+        if (current.state === 'acknowledged') {
+          if (current.acknowledgedOutcome !== requestArg.outcome) {
+            throw new Error(
+              'CoreMail inbound acknowledgement conflicts with persisted intent.',
+            );
+          }
+          return { replayed: true };
+        }
+        if (current.state !== 'fetched') {
+          throw new Error('CoreMail inbound delivery must be fetched before acknowledgement.');
+        }
+        await decrementCoreMailQuotaCounter(
+          this.models,
+          quota,
+          updatedAt,
+          transactionArg,
+        );
+        const update = await this.models.InboundDelivery.exact.transition({
+          current,
+          change: (modelArg) => {
+            modelArg.state = 'acknowledged';
+            modelArg.acknowledgedOutcome = requestArg.outcome;
+            modelArg.updatedAt = updatedAt;
+            modelArg.revision += 1;
+          },
+        }, { session: transactionArg });
+        if (update.status !== 'transitioned') {
+          throw new Error('CoreMail inbound acknowledgement fence changed.');
+        }
+        return { replayed: false };
+      },
+    );
+    const committed = await this.requireDelivery(sessionArg, requestArg.deliveryId);
+    if (
+      committed.state !== 'acknowledged'
+      || committed.acknowledgedOutcome !== requestArg.outcome
+    ) {
+      throw new Error('CoreMail committed inbound acknowledgement is unavailable.');
+    }
+    return {
+      delivery: toPublicDelivery(committed),
+      replayed: transactionResult.replayed,
+    };
+  }
+
+  private async requireDelivery(
+    sessionArg: ICoreMailWorkloadSession,
+    deliveryIdArg: string,
+  ): Promise<TStoredInboundDelivery> {
+    const delivery = await this.models.InboundDelivery.exact.findStoredOne({
+      ...workloadFilter(sessionArg, deliveryIdArg),
+    });
+    if (!delivery) {
+      throw new Error('CoreMail inbound delivery is unavailable.');
+    }
+    return delivery;
+  }
+}