@serve.zone/interfaces 21.1.0 → 22.0.0

package/ts/data/coremail.ts

@@ -10,7 +10,7 @@
 export type TCoreMailSha256 = `sha256:${string}`;
 
 export type TCoreMailCapability = 'outbound' | 'inbound';
-export type TCoreMailBindingState = 'active' | 'disabled';
+export type TCoreMailBindingState = 'active' | 'draining' | 'disabled';
 export type TCoreMailCredentialState = 'current' | 'retiring';
 export type TCoreMailCredentialVerifierFormat = 'argon2id-v1';
 export type TCoreMailPartKind = 'text' | 'html' | 'attachment';
@@ -30,6 +30,16 @@ export type TCoreMailInboundDeliveryState = 'pending' | 'fetching' | 'fetched' |
 export type TCoreMailInboundAckOutcome = 'processed' | 'discarded';
 export type TCoreMailRecipientAction = 'accept' | 'reject' | 'defer';
 export type TCoreMailReconciliationState = 'applying' | 'ready' | 'failed';
+export type TCoreMailWorkloadOperation =
+  | 'coreMailPrepareOutboundSubmission'
+  | 'coreMailPrepareOutboundPartUpload'
+  | 'coreMailCompleteOutboundPartUpload'
+  | 'coreMailFinalizeOutboundSubmission'
+  | 'coreMailGetOutboundSubmission'
+  | 'coreMailListInboundDeliveries'
+  | 'coreMailPrepareInboundFetch'
+  | 'coreMailCompleteInboundFetch'
+  | 'coreMailAcknowledgeInboundDelivery';
 
 export type TCoreMailErrorCode =
   | 'AUTHENTICATION_FAILED'
@@ -43,6 +53,7 @@ export type TCoreMailErrorCode =
   | 'INVALID_RECIPIENT'
   | 'INVALID_HEADER'
   | 'PAYLOAD_LIMIT_EXCEEDED'
+  | 'QUOTA_EXCEEDED'
   | 'IDEMPOTENCY_CONFLICT'
   | 'STATE_CONFLICT'
   | 'TRANSFER_GRANT_EXPIRED'
@@ -52,6 +63,9 @@ export type TCoreMailErrorCode =
   | 'TRANSFER_ENCODING_UNSUPPORTED'
   | 'OBJECT_INTEGRITY_CONFLICT'
   | 'DELIVERY_NOT_FETCHED'
+  | 'DELIVERY_DEFERRED'
+  | 'DELIVERY_FAILED'
+  | 'DELIVERY_DEAD_LETTERED'
   | 'GATEWAY_UNAVAILABLE'
   | 'RECONCILIATION_FENCE_MISMATCH';
 
@@ -111,6 +125,7 @@ export interface ICoreMailTransferGrant {
   sha256: TCoreMailSha256;
   lengthBytes: number;
   contentType: string;
+  issuedAt: number;
   expiresAt: number;
 }
 
@@ -138,8 +153,10 @@ export interface ICoreMailSubmission {
   transportMessageId?: string;
   attempts: number;
   nextAttemptAt?: number;
+  error?: ICoreMailErrorData;
   acceptedAt?: number;
   deliveredAt?: number;
+  terminalAt?: number;
   createdAt: number;
   updatedAt: number;
 }
@@ -158,6 +175,13 @@ export interface ICoreMailInboundDelivery {
   subject?: string;
   receivedAt: number;
   updatedAt: number;
+  acknowledgedAt?: number;
+  acknowledgedOutcome?: TCoreMailInboundAckOutcome;
+}
+
+export interface ICoreMailInboundDeliveryPage {
+  deliveries: ICoreMailInboundDelivery[];
+  nextCursor?: string;
 }
 
 export interface ICoreMailBindingCredentialVerifier {
@@ -172,7 +196,7 @@ export interface ICoreMailBindingCredentialVerifier {
 }
 
 export interface ICoreMailBindingDesiredState {
-  schemaVersion: 1;
+  schemaVersion: 2;
   bindingId: string;
   serviceId: string;
   tenantId: string;
@@ -183,15 +207,17 @@ export interface ICoreMailBindingDesiredState {
   allowedSenders: string[];
   inboundRecipients: string[];
   defaultSender?: string;
-  limits?: {
-    messagesPerMinute?: number;
-    messagesPerDay?: number;
-    maxPendingInbound?: number;
+  limits: {
+    messagesPerMinute: number;
+    messagesPerDay: number;
+    maxPendingInbound: number;
   };
 }
 
 export interface ICoreMailGatewayDesiredState {
   endpointUrl: string;
+  /** Canonical CoreMail HTTPS origin authorized for path-only transfer grants. */
+  coreMailTransferOrigin: string;
   credentialId: string;
   credentialVersion: number;
   /** Key in CoreMail's resolved runtime secret material, never a plaintext value. */
@@ -220,11 +246,21 @@ export interface ICoreMailGatewayPeerDesiredState {
   credentials: ICoreMailBindingCredentialVerifier[];
 }
 
+export interface ICoreMailRuntimeKeyReference {
+  keyId: string;
+  version: number;
+  state: TCoreMailCredentialState;
+  /** Key in CoreMail's resolved runtime secret material, never a plaintext value. */
+  secretKey: string;
+  acceptUntil?: number;
+}
+
 export interface ICoreMailDesiredState {
-  schemaVersion: 1;
+  schemaVersion: 2;
   configEpoch: number;
   bindings: ICoreMailBindingDesiredState[];
   gateway: ICoreMailGatewayDesiredState;
+  cursorKeys: ICoreMailRuntimeKeyReference[];
 }
 
 export interface ICoreMailReplicaIdentity {
@@ -239,7 +275,9 @@ export interface ICoreMailBindingReconciliationStatus {
   bindingId: string;
   revision: number;
   state: TCoreMailBindingState;
-  activeSessionsByCredentialVersion: Array<{
+  pendingInboundCount: number;
+  activeSessionsByCredential: Array<{
+    credentialId: string;
     version: number;
     count: number;
   }>;
@@ -281,7 +319,10 @@ export interface ICoreMailGatewayOutboundStatus {
   >;
   attempts: number;
   nextAttemptAt?: number;
+  error?: ICoreMailErrorData;
   smtpCode?: number;
+  deliveredAt?: number;
+  terminalAt?: number;
   updatedAt: number;
 }
 
@@ -295,12 +336,83 @@ export const coreMailLimits = Object.freeze({
   aggregateAttachmentBytes: 17 * 1024 * 1024,
   mimeFramingBytes: 512 * 1024,
   serializedMimeBytes: 30 * 1024 * 1024,
+  recipientCount: 100,
+  inboundPageSize: 100,
+  inboundPageBytes: 56 * 1024,
+  cursorBytes: 1_024,
+  cursorMinimumDecodedBytes: 32,
+  routingHandleTtlMs: 5 * 60 * 1000,
   transferGrantTtlMs: 5 * 60 * 1000,
   transferHeaderTimeoutMs: 10 * 1000,
   transferIdleTimeoutMs: 15 * 1000,
   transferOverallTimeoutMs: 2 * 60 * 1000,
 } as const);
 
+export const coreMailTransferTokenPolicy = Object.freeze({
+  format: 'base64url-256' as const,
+  decodedBytes: 32,
+  encodedCharacters: 43,
+});
+
+export const coreMailWorkloadOperationPolicy = Object.freeze({
+  active: Object.freeze({
+    outbound: Object.freeze([
+      'coreMailPrepareOutboundSubmission',
+      'coreMailPrepareOutboundPartUpload',
+      'coreMailCompleteOutboundPartUpload',
+      'coreMailFinalizeOutboundSubmission',
+      'coreMailGetOutboundSubmission',
+    ] satisfies TCoreMailWorkloadOperation[]),
+    inbound: Object.freeze([
+      'coreMailListInboundDeliveries',
+      'coreMailPrepareInboundFetch',
+      'coreMailCompleteInboundFetch',
+      'coreMailAcknowledgeInboundDelivery',
+    ] satisfies TCoreMailWorkloadOperation[]),
+  }),
+  draining: Object.freeze({
+    outbound: Object.freeze([
+      'coreMailGetOutboundSubmission',
+    ] satisfies TCoreMailWorkloadOperation[]),
+    inbound: Object.freeze([
+      'coreMailListInboundDeliveries',
+      'coreMailPrepareInboundFetch',
+      'coreMailCompleteInboundFetch',
+      'coreMailAcknowledgeInboundDelivery',
+    ] satisfies TCoreMailWorkloadOperation[]),
+  }),
+  disabled: Object.freeze({
+    outbound: Object.freeze([] satisfies TCoreMailWorkloadOperation[]),
+    inbound: Object.freeze([] satisfies TCoreMailWorkloadOperation[]),
+  }),
+});
+
+export const coreMailRetentionPolicy = Object.freeze({
+  terminalOutboundMs: 30 * 24 * 60 * 60 * 1000,
+  acknowledgedInboundMs: 30 * 24 * 60 * 60 * 1000,
+  idempotencyReceiptMs: 30 * 24 * 60 * 60 * 1000,
+  expiredCapabilityMs: 24 * 60 * 60 * 1000,
+  pendingInboundAgePurge: false as const,
+});
+
+export const coreMailQuotaPolicy = Object.freeze({
+  windows: 'fixed-utc-minute-and-day' as const,
+  outboundUnit: 'first-durable-idempotency-insert' as const,
+  outboundReplayConsumesUnit: false as const,
+  pendingInboundStates: ['pending', 'fetching', 'fetched'] as const,
+  inboundAcknowledgementReleasesUnit: true as const,
+});
+
+export const coreMailTransferProtocol = Object.freeze({
+  pathPrefix: '/transfers/',
+  authorizationScheme: 'Bearer',
+  putSuccessStatus: 204,
+  getSuccessStatus: 200,
+  requireContentLength: true,
+  requireContentType: true,
+  integritySource: 'grant-metadata-and-completion' as const,
+});
+
 export const coreMailCredentialVerifierPolicy = Object.freeze({
   format: 'argon2id-v1' as const,
   version: 19,

package/ts/requests/coremail.ts

@@ -1,6 +1,7 @@
 import type * as plugins from '../plugins.js';
 import type {
   ICoreMailEnvelope,
+  ICoreMailInboundDeliveryPage,
   ICoreMailDownloadGrant,
   ICoreMailGatewayMessageDescriptor,
   ICoreMailGatewayOutboundStatus,
@@ -13,6 +14,7 @@ import type {
   ICoreMailUploadGrant,
   TCoreMailInboundAckOutcome,
   TCoreMailSha256,
+  TCoreMailWorkloadOperation,
 } from '../data/coremail.js';
 import type { IMailConnectionInfo } from '../data/mail.js';
 
@@ -29,8 +31,13 @@ export interface IReq_CoreMailAuthenticateWorkload extends plugins.typedrequestI
   };
   response: {
     authenticated: true;
+    credentialId: string;
     credentialVersion: number;
+    bindingState: 'active' | 'draining';
     capabilities: Array<'outbound' | 'inbound'>;
+    allowedOperations: TCoreMailWorkloadOperation[];
+    /** Authenticated CoreMail HTTPS origin for path-only transfer grants. */
+    coreMailTransferOrigin: string;
   };
 }
 
@@ -113,12 +120,11 @@ export interface IReq_CoreMailListInboundDeliveries extends plugins.typedrequest
 > {
   method: 'coreMailListInboundDeliveries';
   request: {
-    afterDeliveryId?: string;
+    /** Opaque CoreMail-owned composite cursor. */
+    cursor?: string;
     limit: number;
   };
-  response: {
-    deliveries: ICoreMailInboundDelivery[];
-  };
+  response: ICoreMailInboundDeliveryPage;
 }
 
 export interface IReq_CoreMailPrepareInboundFetch extends plugins.typedrequestInterfaces.implementsTR<
@@ -177,6 +183,8 @@ export interface IReq_CoreMailAuthenticateControl extends plugins.typedrequestIn
   };
   response: {
     authenticated: true;
+    credentialId: string;
+    credentialVersion: number;
     replica: ICoreMailReplicaIdentity;
   };
 }
@@ -241,6 +249,7 @@ export interface IReq_CoreMailGatewayAuthenticate extends plugins.typedrequestIn
   };
   response: {
     authenticated: true;
+    credentialId: string;
     credentialVersion: number;
     /** dcrouter's authoritative, control-plane-bound origin for CoreMail transfer paths. */
     coreMailTransferOrigin: string;