@serve.zone/coremail 1.0.0

package/ts/classes.transfer.ts

@@ -0,0 +1,379 @@
+import * as plugins from './plugins.js';
+import {
+  type ICoreMailModels,
+} from './classes.models.js';
+import {
+  CoreMailStorage,
+  createOpaqueToken,
+  createSha256,
+} from './classes.storage.js';
+import type {
+  ITransferAuthority,
+  TTransferGrantPurpose,
+} from './interfaces.js';
+import { logCoreMailFailure } from './coremail.log.js';
+import type { ICoreMailTransferGrantRecord } from './coremail.persistence.js';
+import {
+  requireCoreMailIdentifier,
+  requireCoreMailUuid,
+} from './coremail.selectors.js';
+
+type TCoreMailSha256 = plugins.serveZoneInterfaces.data.TCoreMailSha256;
+type TStoredTransferGrant =
+  plugins.smartdata.TStoredDocument<ICoreMailTransferGrantRecord>;
+
+const transferPathRegex = /^\/transfers\/([a-f0-9-]{36})$/;
+
+const maximumBytesForPurpose = (purposeArg: TTransferGrantPurpose): number => {
+  const limits = plugins.serveZoneInterfaces.data.coreMailLimits;
+  switch (purposeArg) {
+    case 'desired-state-upload':
+      return limits.desiredStateBytes;
+    case 'outbound-part-upload':
+      return limits.attachmentBytes;
+    case 'outbound-mime-download':
+    case 'inbound-mime-upload':
+    case 'inbound-mime-download':
+      return limits.serializedMimeBytes;
+  }
+};
+
+const secureDigestEqual = (
+  leftArg: TCoreMailSha256,
+  rightArg: TCoreMailSha256,
+): boolean => {
+  const left = Buffer.from(leftArg.slice('sha256:'.length), 'hex');
+  const right = Buffer.from(rightArg.slice('sha256:'.length), 'hex');
+  return left.byteLength === right.byteLength
+    && plugins.nodeCrypto.timingSafeEqual(left, right);
+};
+
+const authorityFilter = (
+  grantIdArg: string,
+  authorityArg: ITransferAuthority,
+) => ({
+  grantId: requireCoreMailUuid(grantIdArg, 'grantId'),
+  authorityKind: authorityArg.kind,
+  tenantId: authorityArg.tenantId === '-'
+    ? '-'
+    : requireCoreMailIdentifier(authorityArg.tenantId, 'authority.tenantId'),
+  serviceId: requireCoreMailIdentifier(
+    authorityArg.serviceId,
+    'authority.serviceId',
+  ),
+  bindingId: authorityArg.bindingId === '-'
+    ? '-'
+    : requireCoreMailIdentifier(authorityArg.bindingId, 'authority.bindingId'),
+});
+
+export class CoreMailTransferService {
+  private readonly completionTasks = new Set<Promise<unknown>>();
+  private readonly operationControllers = new Set<AbortController>();
+  private readonly stopController = new AbortController();
+  private stopping = false;
+
+  public constructor(
+    private readonly models: ICoreMailModels,
+    private readonly storage: CoreMailStorage,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  public async stop(): Promise<void> {
+    this.stopping = true;
+    this.stopController.abort(new Error('CoreMail transfer service is stopping.'));
+    for (const controller of this.operationControllers) {
+      controller.abort(new Error('CoreMail transfer service is stopping.'));
+    }
+    await Promise.allSettled([...this.completionTasks]);
+  }
+
+  private track<T>(taskArg: Promise<T>, controllerArg: AbortController): void {
+    this.completionTasks.add(taskArg);
+    this.operationControllers.add(controllerArg);
+    void taskArg.then(
+      () => {
+        this.completionTasks.delete(taskArg);
+        this.operationControllers.delete(controllerArg);
+      },
+      () => {
+        this.completionTasks.delete(taskArg);
+        this.operationControllers.delete(controllerArg);
+      },
+    );
+  }
+
+  public async issueGrant(optionsArg: {
+    authority: ITransferAuthority;
+    purpose: TTransferGrantPurpose;
+    method: 'PUT' | 'GET';
+    expectedSha256: TCoreMailSha256;
+    lengthBytes: number;
+    contentType: string;
+    objectKey: string;
+  }): Promise<plugins.serveZoneInterfaces.data.ICoreMailTransferGrant> {
+    if (this.stopping) {
+      throw new Error('CoreMail transfer service is stopping.');
+    }
+    const maximumBytes = maximumBytesForPurpose(optionsArg.purpose);
+    if (
+      !Number.isSafeInteger(optionsArg.lengthBytes)
+      || optionsArg.lengthBytes < 0
+      || optionsArg.lengthBytes > maximumBytes
+    ) {
+      throw new Error('CoreMail transfer length exceeds its purpose budget.');
+    }
+    const grantId = plugins.nodeCrypto.randomUUID();
+    const bearerToken = createOpaqueToken();
+    const path = `/transfers/${grantId}`;
+    const createdAt = this.now();
+    const expiresAt =
+      createdAt + plugins.serveZoneInterfaces.data.coreMailLimits.transferGrantTtlMs;
+    const inserted = await this.models.TransferGrant.exact.insert({
+      grantId,
+      authorityKind: optionsArg.authority.kind,
+      tenantId: optionsArg.authority.tenantId,
+      serviceId: optionsArg.authority.serviceId,
+      bindingId: optionsArg.authority.bindingId,
+      purpose: optionsArg.purpose,
+      method: optionsArg.method,
+      path,
+      bearerSha256: createSha256(bearerToken),
+      expectedSha256: optionsArg.expectedSha256,
+      lengthBytes: optionsArg.lengthBytes,
+      contentType: optionsArg.contentType,
+      objectKey: optionsArg.objectKey,
+      state: 'issued',
+      expiresAt,
+      createdAt,
+    });
+    if (inserted.status === 'conflict') {
+      throw new Error('CoreMail transfer grant identity conflict.');
+    }
+    return {
+      grantId,
+      method: optionsArg.method,
+      path,
+      bearerToken,
+      sha256: optionsArg.expectedSha256,
+      lengthBytes: optionsArg.lengthBytes,
+      contentType: optionsArg.contentType,
+      issuedAt: createdAt,
+      expiresAt,
+    };
+  }
+
+  public async assertConsumed(optionsArg: {
+    grantId: string;
+    authority: ITransferAuthority;
+    purpose: TTransferGrantPurpose;
+    expectedSha256: TCoreMailSha256;
+    lengthBytes: number;
+    objectKey?: string;
+  }): Promise<TStoredTransferGrant> {
+    const grant = await this.models.TransferGrant.exact.findStoredOne({
+      ...authorityFilter(optionsArg.grantId, optionsArg.authority),
+      state: 'consumed',
+      purpose: optionsArg.purpose,
+      expectedSha256: optionsArg.expectedSha256,
+      lengthBytes: optionsArg.lengthBytes,
+      ...(optionsArg.objectKey === undefined
+        ? {}
+        : { objectKey: optionsArg.objectKey }),
+    });
+    if (!grant) {
+      throw new Error('CoreMail transfer grant is not consumed by this authority.');
+    }
+    await this.storage.verifyObject(
+      grant.objectKey,
+      grant.lengthBytes,
+      grant.expectedSha256,
+      maximumBytesForPurpose(grant.purpose),
+    );
+    return grant;
+  }
+
+  public async handleHttp(
+    contextArg: plugins.typedserver.IRequestContext,
+  ): Promise<Response | null> {
+    const match = transferPathRegex.exec(contextArg.path);
+    if (!match) {
+      return null;
+    }
+    if (contextArg.method !== 'GET' && contextArg.method !== 'PUT') {
+      return new Response('Method Not Allowed', {
+        status: 405,
+        headers: { Allow: 'GET, PUT' },
+      });
+    }
+    const authorization = contextArg.headers.get('authorization');
+    if (!authorization?.startsWith('Bearer ')) {
+      return new Response('Unauthorized', { status: 401 });
+    }
+    const bearer = authorization.slice('Bearer '.length);
+    if (bearer.length < 32 || bearer.length > 512) {
+      return new Response('Unauthorized', { status: 401 });
+    }
+    const grantId = match[1];
+    const grant = await this.models.TransferGrant.exact.findStoredOne({
+      grantId,
+      method: contextArg.method,
+      state: 'issued',
+    });
+    if (
+      !grant
+      || grant.expiresAt < this.now()
+      || !secureDigestEqual(grant.bearerSha256, createSha256(bearer))
+    ) {
+      return new Response('Unauthorized', { status: 401 });
+    }
+    const claim = await this.models.TransferGrant.exact.transition({
+      current: grant,
+      change: (modelArg) => {
+        modelArg.state = 'transferring';
+      },
+    });
+    if (claim.status !== 'transitioned') {
+      return new Response('Conflict', { status: 409 });
+    }
+    if (contextArg.method === 'PUT') {
+      return await this.handleUpload(contextArg, claim.document);
+    }
+    return await this.handleDownload(contextArg, claim.document);
+  }
+
+  private async handleUpload(
+    contextArg: plugins.typedserver.IRequestContext,
+    grantArg: TStoredTransferGrant,
+  ): Promise<Response> {
+    const contentLength = Number(contextArg.headers.get('content-length'));
+    if (
+      !contextArg.request.body
+      || !Number.isSafeInteger(contentLength)
+      || contentLength !== grantArg.lengthBytes
+      || contextArg.headers.get('content-type') !== grantArg.contentType
+    ) {
+      await this.failGrant(grantArg.grantId);
+      return new Response('Invalid transfer metadata', { status: 400 });
+    }
+    const operationController = new AbortController();
+    const signal = AbortSignal.any([
+      contextArg.request.signal,
+      this.stopController.signal,
+      operationController.signal,
+      AbortSignal.timeout(
+        plugins.serveZoneInterfaces.data.coreMailLimits.transferOverallTimeoutMs,
+      ),
+    ]);
+    const task = (async (): Promise<Response> => {
+      try {
+        await this.storage.putExact(
+          grantArg.objectKey,
+          contextArg.request.body as ReadableStream<Uint8Array>,
+          grantArg.lengthBytes,
+          grantArg.expectedSha256,
+          grantArg.contentType,
+          maximumBytesForPurpose(grantArg.purpose),
+          signal,
+        );
+        const consumed = await this.models.TransferGrant.exact.transition({
+          current: grantArg,
+          change: (modelArg) => {
+            modelArg.state = 'consumed';
+            modelArg.consumedAt = this.now();
+          },
+        });
+        if (consumed.status !== 'transitioned') {
+          throw new Error('CoreMail transfer completion fence changed.');
+        }
+        return new Response(null, { status: 204 });
+      } catch {
+        operationController.abort();
+        await this.failGrant(grantArg.grantId);
+        return new Response('Transfer failed', { status: 409 });
+      }
+    })();
+    this.track(task, operationController);
+    return await task;
+  }
+
+  private async handleDownload(
+    contextArg: plugins.typedserver.IRequestContext,
+    grantArg: TStoredTransferGrant,
+  ): Promise<Response> {
+    const operationController = new AbortController();
+    const signal = AbortSignal.any([
+      contextArg.request.signal,
+      this.stopController.signal,
+      operationController.signal,
+      AbortSignal.timeout(
+        plugins.serveZoneInterfaces.data.coreMailLimits.transferOverallTimeoutMs,
+      ),
+    ]);
+    try {
+      const verified = await this.storage.getVerifiedStream(
+        grantArg.objectKey,
+        grantArg.lengthBytes,
+        grantArg.expectedSha256,
+        maximumBytesForPurpose(grantArg.purpose),
+        signal,
+      );
+      const completion = verified.completion.then(async () => {
+        const consumed = await this.models.TransferGrant.exact.transition({
+          current: grantArg,
+          change: (modelArg) => {
+            modelArg.state = 'consumed';
+            modelArg.consumedAt = this.now();
+          },
+        });
+        if (consumed.status !== 'transitioned') {
+          throw new Error('CoreMail transfer completion fence changed.');
+        }
+      }).catch(async () => {
+        await this.failGrant(grantArg.grantId);
+      });
+      this.track(completion, operationController);
+      return new Response(verified.stream, {
+        status: 200,
+        headers: {
+          'Content-Type': grantArg.contentType,
+          'Content-Length': String(grantArg.lengthBytes),
+          'Cache-Control': 'no-store',
+          'X-Content-Type-Options': 'nosniff',
+        },
+      });
+    } catch {
+      operationController.abort();
+      await this.failGrant(grantArg.grantId);
+      return new Response('Transfer failed', { status: 409 });
+    }
+  }
+
+  private async failGrant(grantIdArg: string): Promise<void> {
+    try {
+      const grant = await this.models.TransferGrant.exact.findStoredOne({
+        grantId: grantIdArg,
+        state: { $in: ['issued', 'transferring'] },
+      });
+      if (!grant) {
+        return;
+      }
+      const failed = await this.models.TransferGrant.exact.transition({
+        current: grant,
+        change: (modelArg) => {
+          modelArg.state = 'failed';
+        },
+      });
+      if (failed.status === 'concurrent_change') {
+        const current = await this.models.TransferGrant.exact.findStoredOne({
+          grantId: grantIdArg,
+        });
+        if (current?.state === 'issued' || current?.state === 'transferring') {
+          throw new Error('CoreMail transfer failure fence changed.');
+        }
+      }
+    } catch {
+      await logCoreMailFailure('transfer', 'GRANT_FAILURE_PERSISTENCE_FAILED')
+        .catch(() => undefined);
+    }
+  }
+}

package/ts/coremail.cursor.ts

@@ -0,0 +1,328 @@
+import * as plugins from './plugins.js';
+import {
+  requireCoreMailIdentifier,
+  requireCoreMailSafeInteger,
+  requireCoreMailUuid,
+} from './coremail.selectors.js';
+
+export interface ICoreMailInboundCursorAuthority {
+  tenantId: string;
+  serviceId: string;
+  bindingId: string;
+  bindingRevision: number;
+}
+
+export interface ICoreMailInboundCursorPosition {
+  snapshotAt: number;
+  receivedAt: number;
+  deliveryId: string;
+}
+
+interface ICoreMailInboundCursorPayload
+  extends ICoreMailInboundCursorAuthority, ICoreMailInboundCursorPosition {
+  version: 1;
+}
+
+interface ICoreMailInboundCursorEnvelope {
+  version: 1;
+  keyId: string;
+  keyVersion: number;
+  payload: string;
+  signature: string;
+}
+
+type TCursorKey = plugins.serveZoneInterfaces.data.ICoreMailRuntimeKeyReference;
+
+const maximumCursorAgeMs = 24 * 60 * 60 * 1_000;
+const maximumFutureSkewMs = 1_000;
+const payloadKeys = new Set([
+  'version',
+  'tenantId',
+  'serviceId',
+  'bindingId',
+  'bindingRevision',
+  'snapshotAt',
+  'receivedAt',
+  'deliveryId',
+]);
+const envelopeKeys = new Set([
+  'version',
+  'keyId',
+  'keyVersion',
+  'payload',
+  'signature',
+]);
+
+const canonicalPayload = (
+  payloadArg: ICoreMailInboundCursorPayload,
+): string => JSON.stringify({
+  version: payloadArg.version,
+  tenantId: payloadArg.tenantId,
+  serviceId: payloadArg.serviceId,
+  bindingId: payloadArg.bindingId,
+  bindingRevision: payloadArg.bindingRevision,
+  snapshotAt: payloadArg.snapshotAt,
+  receivedAt: payloadArg.receivedAt,
+  deliveryId: payloadArg.deliveryId,
+});
+
+const canonicalEnvelope = (
+  envelopeArg: ICoreMailInboundCursorEnvelope,
+): string => JSON.stringify({
+  version: envelopeArg.version,
+  keyId: envelopeArg.keyId,
+  keyVersion: envelopeArg.keyVersion,
+  payload: envelopeArg.payload,
+  signature: envelopeArg.signature,
+});
+
+const requireAuthority = (
+  authorityArg: ICoreMailInboundCursorAuthority,
+): ICoreMailInboundCursorAuthority => ({
+  tenantId: requireCoreMailIdentifier(
+    authorityArg.tenantId,
+    'cursor.tenantId',
+  ),
+  serviceId: requireCoreMailIdentifier(
+    authorityArg.serviceId,
+    'cursor.serviceId',
+  ),
+  bindingId: requireCoreMailIdentifier(
+    authorityArg.bindingId,
+    'cursor.bindingId',
+  ),
+  bindingRevision: requireCoreMailSafeInteger(
+    authorityArg.bindingRevision,
+    'cursor.bindingRevision',
+    1,
+  ),
+});
+
+const parseCanonicalRecord = (
+  encodedArg: string,
+  keysArg: Set<string>,
+): Record<string, unknown> => {
+  let decoded: Buffer;
+  let parsed: unknown;
+  try {
+    decoded = Buffer.from(encodedArg, 'base64url');
+    if (decoded.toString('base64url') !== encodedArg) {
+      throw new Error('noncanonical encoding');
+    }
+    parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(decoded));
+  } catch {
+    throw new Error('CoreMail inbound cursor is invalid.');
+  }
+  if (
+    !parsed
+    || typeof parsed !== 'object'
+    || Array.isArray(parsed)
+    || Object.getPrototypeOf(parsed) !== Object.prototype
+    || Object.keys(parsed).length !== keysArg.size
+    || Object.keys(parsed).some((keyArg) => !keysArg.has(keyArg))
+  ) {
+    throw new Error('CoreMail inbound cursor is invalid.');
+  }
+  return parsed as Record<string, unknown>;
+};
+
+const parsePayload = (encodedArg: string): ICoreMailInboundCursorPayload => {
+  const value = parseCanonicalRecord(encodedArg, payloadKeys);
+  if (value.version !== 1) {
+    throw new Error('CoreMail inbound cursor version is unsupported.');
+  }
+  const payload: ICoreMailInboundCursorPayload = {
+    version: 1,
+    tenantId: requireCoreMailIdentifier(value.tenantId, 'cursor.tenantId'),
+    serviceId: requireCoreMailIdentifier(value.serviceId, 'cursor.serviceId'),
+    bindingId: requireCoreMailIdentifier(value.bindingId, 'cursor.bindingId'),
+    bindingRevision: requireCoreMailSafeInteger(
+      value.bindingRevision,
+      'cursor.bindingRevision',
+      1,
+    ),
+    snapshotAt: requireCoreMailSafeInteger(
+      value.snapshotAt,
+      'cursor.snapshotAt',
+    ),
+    receivedAt: requireCoreMailSafeInteger(
+      value.receivedAt,
+      'cursor.receivedAt',
+    ),
+    deliveryId: requireCoreMailUuid(value.deliveryId, 'cursor.deliveryId'),
+  };
+  if (canonicalPayload(payload) !== Buffer.from(encodedArg, 'base64url').toString('utf8')) {
+    throw new Error('CoreMail inbound cursor is not canonical.');
+  }
+  return payload;
+};
+
+const deriveHmacKey = (secretArg: string): Buffer => {
+  if (
+    typeof secretArg !== 'string'
+    || Buffer.byteLength(secretArg, 'utf8') < 32
+    || Buffer.byteLength(secretArg, 'utf8') > 512
+    || secretArg.trim() !== secretArg
+  ) {
+    throw new Error('CoreMail cursor secret is invalid.');
+  }
+  return plugins.nodeCrypto.createHash('sha256').update(secretArg, 'utf8').digest();
+};
+
+const signatureInput = (
+  keyIdArg: string,
+  keyVersionArg: number,
+  payloadArg: string,
+): string => `${keyIdArg}:${keyVersionArg}:${payloadArg}`;
+
+const sign = (
+  keyArg: Buffer,
+  keyIdArg: string,
+  keyVersionArg: number,
+  payloadArg: string,
+): string => plugins.nodeCrypto
+  .createHmac('sha256', keyArg)
+  .update(signatureInput(keyIdArg, keyVersionArg, payloadArg), 'ascii')
+  .digest('base64url');
+
+export class CoreMailInboundCursorCodec {
+  public constructor(
+    private readonly resolveRuntimeSecret: (secretKeyArg: string) => string,
+  ) {}
+
+  public encode(
+    authorityArg: ICoreMailInboundCursorAuthority,
+    positionArg: ICoreMailInboundCursorPosition,
+    keysArg: TCursorKey[],
+  ): string {
+    const currentKey = keysArg.find((keyArg) => keyArg.state === 'current');
+    if (!currentKey) {
+      throw new Error('CoreMail current cursor key is unavailable.');
+    }
+    const authority = requireAuthority(authorityArg);
+    const payload: ICoreMailInboundCursorPayload = {
+      version: 1,
+      ...authority,
+      snapshotAt: requireCoreMailSafeInteger(
+        positionArg.snapshotAt,
+        'cursor.snapshotAt',
+      ),
+      receivedAt: requireCoreMailSafeInteger(
+        positionArg.receivedAt,
+        'cursor.receivedAt',
+      ),
+      deliveryId: requireCoreMailUuid(
+        positionArg.deliveryId,
+        'cursor.deliveryId',
+      ),
+    };
+    if (payload.receivedAt >= payload.snapshotAt) {
+      throw new Error('CoreMail inbound cursor position is invalid.');
+    }
+    const encodedPayload = Buffer.from(
+      canonicalPayload(payload),
+      'utf8',
+    ).toString('base64url');
+    const envelope: ICoreMailInboundCursorEnvelope = {
+      version: 1,
+      keyId: currentKey.keyId,
+      keyVersion: currentKey.version,
+      payload: encodedPayload,
+      signature: sign(
+        deriveHmacKey(this.resolveRuntimeSecret(currentKey.secretKey)),
+        currentKey.keyId,
+        currentKey.version,
+        encodedPayload,
+      ),
+    };
+    return plugins.serveZoneInterfaces.data.normalizeCoreMailInboundCursor(
+      Buffer.from(canonicalEnvelope(envelope), 'utf8').toString('base64url'),
+    );
+  }
+
+  public decode(
+    cursorArg: string,
+    authorityArg: ICoreMailInboundCursorAuthority,
+    nowArg: number,
+    keysArg: TCursorKey[],
+  ): ICoreMailInboundCursorPosition {
+    const cursor = plugins.serveZoneInterfaces.data.normalizeCoreMailInboundCursor(
+      cursorArg,
+    );
+    const value = parseCanonicalRecord(cursor, envelopeKeys);
+    if (value.version !== 1) {
+      throw new Error('CoreMail inbound cursor version is unsupported.');
+    }
+    const now = requireCoreMailSafeInteger(nowArg, 'cursor.now');
+    const keyId = requireCoreMailIdentifier(value.keyId, 'cursor.keyId');
+    const keyVersion = requireCoreMailSafeInteger(
+      value.keyVersion,
+      'cursor.keyVersion',
+      1,
+    );
+    if (typeof value.payload !== 'string' || typeof value.signature !== 'string') {
+      throw new Error('CoreMail inbound cursor is invalid.');
+    }
+    const envelope: ICoreMailInboundCursorEnvelope = {
+      version: 1,
+      keyId,
+      keyVersion,
+      payload: value.payload,
+      signature: value.signature,
+    };
+    if (canonicalEnvelope(envelope) !== Buffer.from(cursor, 'base64url').toString('utf8')) {
+      throw new Error('CoreMail inbound cursor is not canonical.');
+    }
+    const key = keysArg.find((keyArg) =>
+      keyArg.keyId === keyId
+      && keyArg.version === keyVersion
+      && (
+        keyArg.state === 'current'
+        || (
+          keyArg.state === 'retiring'
+          && keyArg.acceptUntil !== undefined
+          && keyArg.acceptUntil >= now
+        )
+      )
+    );
+    if (!key) {
+      throw new Error('CoreMail inbound cursor key is unavailable.');
+    }
+    const actualSignature = Buffer.from(envelope.signature, 'base64url');
+    const expectedSignature = Buffer.from(sign(
+      deriveHmacKey(this.resolveRuntimeSecret(key.secretKey)),
+      key.keyId,
+      key.version,
+      envelope.payload,
+    ), 'base64url');
+    if (
+      actualSignature.toString('base64url') !== envelope.signature
+      || actualSignature.byteLength !== expectedSignature.byteLength
+      || !plugins.nodeCrypto.timingSafeEqual(actualSignature, expectedSignature)
+    ) {
+      throw new Error('CoreMail inbound cursor is invalid.');
+    }
+    const payload = parsePayload(envelope.payload);
+    const authority = requireAuthority(authorityArg);
+    if (
+      payload.tenantId !== authority.tenantId
+      || payload.serviceId !== authority.serviceId
+      || payload.bindingId !== authority.bindingId
+      || payload.bindingRevision !== authority.bindingRevision
+    ) {
+      throw new Error('CoreMail inbound cursor authority is invalid.');
+    }
+    if (
+      payload.receivedAt >= payload.snapshotAt
+      || payload.snapshotAt > now + maximumFutureSkewMs
+      || now - payload.snapshotAt > maximumCursorAgeMs
+    ) {
+      throw new Error('CoreMail inbound cursor window is invalid.');
+    }
+    return {
+      snapshotAt: payload.snapshotAt,
+      receivedAt: payload.receivedAt,
+      deliveryId: payload.deliveryId,
+    };
+  }
+}