@serve.zone/interfaces 20.1.0 → 21.0.0

package/ts/data/coremail.ts

@@ -0,0 +1,318 @@
+/**
+ * Shared CoreMail contracts.
+ *
+ * Workload authority is always derived from an authenticated transport
+ * session. Application-facing request DTOs therefore carry message or
+ * delivery identifiers only and never caller-selected tenant, service, or
+ * binding authority.
+ */
+
+export type TCoreMailSha256 = `sha256:${string}`;
+
+export type TCoreMailCapability = 'outbound' | 'inbound';
+export type TCoreMailBindingState = 'active' | 'disabled';
+export type TCoreMailCredentialState = 'current' | 'retiring';
+export type TCoreMailCredentialVerifierFormat = 'argon2id-v1';
+export type TCoreMailPartKind = 'text' | 'html' | 'attachment';
+export type TCoreMailTransferMethod = 'PUT' | 'GET';
+export type TCoreMailSubmissionState =
+  | 'preparing'
+  | 'uploading'
+  | 'ready'
+  | 'accepted'
+  | 'queued'
+  | 'delivering'
+  | 'delivered'
+  | 'deferred'
+  | 'failed'
+  | 'deadLettered';
+export type TCoreMailInboundDeliveryState = 'pending' | 'fetching' | 'fetched' | 'acknowledged';
+export type TCoreMailInboundAckOutcome = 'processed' | 'discarded';
+export type TCoreMailRecipientAction = 'accept' | 'reject' | 'defer';
+export type TCoreMailReconciliationState = 'applying' | 'ready' | 'failed';
+
+export type TCoreMailErrorCode =
+  | 'AUTHENTICATION_FAILED'
+  | 'AUTHENTICATION_EXPIRED'
+  | 'AUTHORITY_REVOKED'
+  | 'CAPABILITY_DENIED'
+  | 'NOT_FOUND'
+  | 'INVALID_REQUEST'
+  | 'INVALID_MAILBOX'
+  | 'INVALID_SENDER'
+  | 'INVALID_RECIPIENT'
+  | 'INVALID_HEADER'
+  | 'PAYLOAD_LIMIT_EXCEEDED'
+  | 'IDEMPOTENCY_CONFLICT'
+  | 'STATE_CONFLICT'
+  | 'TRANSFER_GRANT_EXPIRED'
+  | 'TRANSFER_GRANT_REPLAYED'
+  | 'TRANSFER_LENGTH_MISMATCH'
+  | 'TRANSFER_DIGEST_MISMATCH'
+  | 'TRANSFER_ENCODING_UNSUPPORTED'
+  | 'OBJECT_INTEGRITY_CONFLICT'
+  | 'DELIVERY_NOT_FETCHED'
+  | 'GATEWAY_UNAVAILABLE'
+  | 'RECONCILIATION_FENCE_MISMATCH';
+
+export interface ICoreMailErrorData {
+  code: TCoreMailErrorCode;
+  retryable: boolean;
+  retryAfterMs?: number;
+}
+
+export interface ICoreMailMailbox {
+  address: string;
+  displayName?: string;
+}
+
+export interface ICoreMailEnvelope {
+  mailFrom: string;
+  rcptTo: string[];
+}
+
+export interface ICoreMailHeader {
+  name: string;
+  value: string;
+}
+
+export interface ICoreMailContentDescriptor {
+  partId: string;
+  kind: TCoreMailPartKind;
+  contentType: string;
+  filename?: string;
+  contentId?: string;
+  sha256: TCoreMailSha256;
+  lengthBytes: number;
+}
+
+export interface ICoreMailOutboundMessageDescriptor {
+  sender: ICoreMailMailbox;
+  recipients: {
+    to: ICoreMailMailbox[];
+    cc?: ICoreMailMailbox[];
+    bcc?: ICoreMailMailbox[];
+  };
+  replyTo?: ICoreMailMailbox;
+  subject: string;
+  /** Ordered headers. Transport-owned MIME headers are not accepted here. */
+  headers?: ICoreMailHeader[];
+  /** Ordered body and attachment descriptors. Bytes move through bounded HTTP transfers. */
+  parts: ICoreMailContentDescriptor[];
+}
+
+export interface ICoreMailTransferGrant {
+  grantId: string;
+  method: TCoreMailTransferMethod;
+  /** Same-origin path. Callers use the authenticated CoreMail or gateway endpoint they already hold. */
+  path: string;
+  /** One-time bearer capability. It must never be logged or persisted by a consumer. */
+  bearerToken: string;
+  sha256: TCoreMailSha256;
+  lengthBytes: number;
+  contentType: string;
+  expiresAt: number;
+}
+
+export interface ICoreMailUploadGrant extends ICoreMailTransferGrant {
+  method: 'PUT';
+}
+
+export interface ICoreMailDownloadGrant extends ICoreMailTransferGrant {
+  method: 'GET';
+}
+
+export interface ICoreMailPartStatus {
+  partId: string;
+  state: 'missing' | 'uploading' | 'complete' | 'failed';
+  sha256: TCoreMailSha256;
+  lengthBytes: number;
+}
+
+export interface ICoreMailSubmission {
+  submissionId: string;
+  idempotencyKey: string;
+  submissionDigest: TCoreMailSha256;
+  state: TCoreMailSubmissionState;
+  parts: ICoreMailPartStatus[];
+  transportMessageId?: string;
+  attempts: number;
+  nextAttemptAt?: number;
+  acceptedAt?: number;
+  deliveredAt?: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface ICoreMailInboundDelivery {
+  deliveryId: string;
+  transportDeliveryId: string;
+  state: TCoreMailInboundDeliveryState;
+  envelope: ICoreMailEnvelope;
+  rawMime: {
+    sha256: TCoreMailSha256;
+    lengthBytes: number;
+    contentType: 'message/rfc822';
+  };
+  messageId?: string;
+  subject?: string;
+  receivedAt: number;
+  updatedAt: number;
+}
+
+export interface ICoreMailBindingCredentialVerifier {
+  credentialId: string;
+  version: number;
+  state: TCoreMailCredentialState;
+  /** Versioned verifier contract. CoreMail currently accepts only argon2id-v1. */
+  format: TCoreMailCredentialVerifierFormat;
+  /** Password-verifier string only. Plaintext credential material is never part of desired state. */
+  verificationHash: string;
+  acceptUntil?: number;
+}
+
+export interface ICoreMailBindingDesiredState {
+  schemaVersion: 1;
+  bindingId: string;
+  serviceId: string;
+  tenantId: string;
+  revision: number;
+  state: TCoreMailBindingState;
+  capabilities: TCoreMailCapability[];
+  credentials: ICoreMailBindingCredentialVerifier[];
+  allowedSenders: string[];
+  inboundRecipients: string[];
+  defaultSender?: string;
+  limits?: {
+    messagesPerMinute?: number;
+    messagesPerDay?: number;
+    maxPendingInbound?: number;
+  };
+}
+
+export interface ICoreMailGatewayDesiredState {
+  endpointUrl: string;
+  credentialId: string;
+  credentialVersion: number;
+  /** Key in CoreMail's resolved runtime secret material, never a plaintext value. */
+  credentialSecretKey: string;
+}
+
+/**
+ * Bootstrap authority installed in CoreMail before Coreflow can reconcile
+ * ordinary desired state. The verifier payload is safe to deliver as runtime
+ * configuration; the matching plaintext is delivered only to Coreflow.
+ */
+export interface ICoreMailControlBootstrap {
+  schemaVersion: 1;
+  coreMailServiceId: string;
+  credentials: ICoreMailBindingCredentialVerifier[];
+}
+
+/**
+ * dcrouter-owned desired state for one authenticated CoreMail gateway peer.
+ * transferOrigin is authoritative control-plane data, never peer supplied.
+ */
+export interface ICoreMailGatewayPeerDesiredState {
+  schemaVersion: 1;
+  coreMailServiceId: string;
+  transferOrigin: string;
+  credentials: ICoreMailBindingCredentialVerifier[];
+}
+
+export interface ICoreMailDesiredState {
+  schemaVersion: 1;
+  configEpoch: number;
+  bindings: ICoreMailBindingDesiredState[];
+  gateway: ICoreMailGatewayDesiredState;
+}
+
+export interface ICoreMailReplicaIdentity {
+  taskId: string;
+  serviceId: string;
+  rolloutId: string;
+  rolloutGeneration: number;
+  imageDigest: TCoreMailSha256;
+}
+
+export interface ICoreMailBindingReconciliationStatus {
+  bindingId: string;
+  revision: number;
+  state: TCoreMailBindingState;
+  activeSessionsByCredentialVersion: Array<{
+    version: number;
+    count: number;
+  }>;
+}
+
+export interface ICoreMailReconciliationStatus {
+  replica: ICoreMailReplicaIdentity;
+  state: TCoreMailReconciliationState;
+  appliedConfigEpoch: number;
+  appliedDesiredStateDigest: TCoreMailSha256;
+  bindings: ICoreMailBindingReconciliationStatus[];
+  updatedAt: number;
+  errorCode?: TCoreMailErrorCode;
+}
+
+export interface ICoreMailRecipientResolution {
+  recipient: string;
+  action: TCoreMailRecipientAction;
+  /** Opaque, short-lived handle returned only for accepted recipients. */
+  routingHandle?: string;
+  smtpCode?: number;
+  message?: string;
+}
+
+export interface ICoreMailGatewayMessageDescriptor {
+  envelope: ICoreMailEnvelope;
+  rawMime: {
+    sha256: TCoreMailSha256;
+    lengthBytes: number;
+    contentType: 'message/rfc822';
+  };
+}
+
+export interface ICoreMailGatewayOutboundStatus {
+  transportMessageId: string;
+  state: Extract<
+    TCoreMailSubmissionState,
+    'accepted' | 'queued' | 'delivering' | 'delivered' | 'deferred' | 'failed' | 'deadLettered'
+  >;
+  attempts: number;
+  nextAttemptAt?: number;
+  smtpCode?: number;
+  updatedAt: number;
+}
+
+export const coreMailLimits = Object.freeze({
+  controlMessageBytes: 64 * 1024,
+  desiredStateBytes: 8 * 1024 * 1024,
+  textPartBytes: 1 * 1024 * 1024,
+  htmlPartBytes: 2 * 1024 * 1024,
+  attachmentCount: 16,
+  attachmentBytes: 10 * 1024 * 1024,
+  aggregateAttachmentBytes: 17 * 1024 * 1024,
+  mimeFramingBytes: 512 * 1024,
+  serializedMimeBytes: 30 * 1024 * 1024,
+  transferGrantTtlMs: 5 * 60 * 1000,
+  transferHeaderTimeoutMs: 10 * 1000,
+  transferIdleTimeoutMs: 15 * 1000,
+  transferOverallTimeoutMs: 2 * 60 * 1000,
+} as const);
+
+export const coreMailCredentialVerifierPolicy = Object.freeze({
+  format: 'argon2id-v1' as const,
+  version: 19,
+  memoryCost: 65_536,
+  timeCost: 3,
+  parallelism: 1,
+  saltLengthBytes: 16,
+  hashLengthBytes: 32,
+} as const);
+
+export const coreMailRuntimeKeys = Object.freeze({
+  controlBootstrap: 'COREMAIL_CONTROL_BOOTSTRAP',
+  controlCredentialSecret: 'COREMAIL_CONTROL_CREDENTIAL_SECRET',
+  gatewayCredentialSecret: 'COREMAIL_GATEWAY_CREDENTIAL',
+} as const);

package/ts/data/index.ts

@@ -1,6 +1,8 @@
 export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './config.js';
+export * from './coremail.js';
+export * from './coremail.runtime.js';
 export * from './deployment.js';
 export * from './deploymentadoption.js';
 export * from './deploymentoperation.js';

package/ts/requests/coremail.ts

@@ -0,0 +1,348 @@
+import type * as plugins from '../plugins.js';
+import type {
+  ICoreMailEnvelope,
+  ICoreMailDownloadGrant,
+  ICoreMailGatewayMessageDescriptor,
+  ICoreMailGatewayOutboundStatus,
+  ICoreMailInboundDelivery,
+  ICoreMailOutboundMessageDescriptor,
+  ICoreMailRecipientResolution,
+  ICoreMailReconciliationStatus,
+  ICoreMailReplicaIdentity,
+  ICoreMailSubmission,
+  ICoreMailUploadGrant,
+  TCoreMailInboundAckOutcome,
+  TCoreMailSha256,
+} from '../data/coremail.js';
+import type { IMailConnectionInfo } from '../data/mail.js';
+
+export interface IReq_CoreMailAuthenticateWorkload extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailAuthenticateWorkload
+> {
+  method: 'coreMailAuthenticateWorkload';
+  request: {
+    bindingId: string;
+    credentialId: string;
+    credentialVersion: number;
+    credentialSecret: string;
+  };
+  response: {
+    authenticated: true;
+    credentialVersion: number;
+    capabilities: Array<'outbound' | 'inbound'>;
+  };
+}
+
+export interface IReq_CoreMailPrepareOutboundSubmission extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailPrepareOutboundSubmission
+> {
+  method: 'coreMailPrepareOutboundSubmission';
+  request: {
+    /** Required replay key. Authority is added by the authenticated server session. */
+    idempotencyKey: string;
+    message: ICoreMailOutboundMessageDescriptor;
+  };
+  response: {
+    submission: ICoreMailSubmission;
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailPrepareOutboundPartUpload extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailPrepareOutboundPartUpload
+> {
+  method: 'coreMailPrepareOutboundPartUpload';
+  request: {
+    submissionId: string;
+    partId: string;
+  };
+  response: {
+    grant: ICoreMailUploadGrant;
+  };
+}
+
+export interface IReq_CoreMailCompleteOutboundPartUpload extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailCompleteOutboundPartUpload
+> {
+  method: 'coreMailCompleteOutboundPartUpload';
+  request: {
+    submissionId: string;
+    partId: string;
+    grantId: string;
+    sha256: TCoreMailSha256;
+    lengthBytes: number;
+  };
+  response: {
+    submission: ICoreMailSubmission;
+  };
+}
+
+export interface IReq_CoreMailFinalizeOutboundSubmission extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailFinalizeOutboundSubmission
+> {
+  method: 'coreMailFinalizeOutboundSubmission';
+  request: {
+    submissionId: string;
+  };
+  response: {
+    submission: ICoreMailSubmission;
+  };
+}
+
+export interface IReq_CoreMailGetOutboundSubmission extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGetOutboundSubmission
+> {
+  method: 'coreMailGetOutboundSubmission';
+  request: {
+    submissionId: string;
+  };
+  response: {
+    submission: ICoreMailSubmission;
+  };
+}
+
+export interface IReq_CoreMailListInboundDeliveries extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailListInboundDeliveries
+> {
+  method: 'coreMailListInboundDeliveries';
+  request: {
+    afterDeliveryId?: string;
+    limit: number;
+  };
+  response: {
+    deliveries: ICoreMailInboundDelivery[];
+  };
+}
+
+export interface IReq_CoreMailPrepareInboundFetch extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailPrepareInboundFetch
+> {
+  method: 'coreMailPrepareInboundFetch';
+  request: {
+    deliveryId: string;
+  };
+  response: {
+    grant: ICoreMailDownloadGrant;
+  };
+}
+
+export interface IReq_CoreMailCompleteInboundFetch extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailCompleteInboundFetch
+> {
+  method: 'coreMailCompleteInboundFetch';
+  request: {
+    deliveryId: string;
+    grantId: string;
+    sha256: TCoreMailSha256;
+    lengthBytes: number;
+  };
+  response: {
+    delivery: ICoreMailInboundDelivery;
+  };
+}
+
+export interface IReq_CoreMailAcknowledgeInboundDelivery extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailAcknowledgeInboundDelivery
+> {
+  method: 'coreMailAcknowledgeInboundDelivery';
+  request: {
+    deliveryId: string;
+    outcome: TCoreMailInboundAckOutcome;
+  };
+  response: {
+    delivery: ICoreMailInboundDelivery;
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailAuthenticateControl extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailAuthenticateControl
+> {
+  method: 'coreMailAuthenticateControl';
+  request: {
+    credentialId: string;
+    credentialVersion: number;
+    credentialSecret: string;
+  };
+  response: {
+    authenticated: true;
+    replica: ICoreMailReplicaIdentity;
+  };
+}
+
+export interface IReq_CoreMailPrepareDesiredStateUpload extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailPrepareDesiredStateUpload
+> {
+  method: 'coreMailPrepareDesiredStateUpload';
+  request: {
+    expectedAppliedConfigEpoch: number;
+    configEpoch: number;
+    desiredStateDigest: TCoreMailSha256;
+    lengthBytes: number;
+  };
+  response: {
+    reconciliationId: string;
+    grant: ICoreMailUploadGrant;
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailApplyDesiredState extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailApplyDesiredState
+> {
+  method: 'coreMailApplyDesiredState';
+  request: {
+    reconciliationId: string;
+    grantId: string;
+    desiredStateDigest: TCoreMailSha256;
+    lengthBytes: number;
+  };
+  response: {
+    status: ICoreMailReconciliationStatus;
+  };
+}
+
+export interface IReq_CoreMailGetReconciliationStatus extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGetReconciliationStatus
+> {
+  method: 'coreMailGetReconciliationStatus';
+  request: {
+    configEpoch: number;
+    desiredStateDigest: TCoreMailSha256;
+  };
+  response: {
+    status: ICoreMailReconciliationStatus;
+  };
+}
+
+export interface IReq_CoreMailGatewayAuthenticate extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayAuthenticate
+> {
+  method: 'coreMailGatewayAuthenticate';
+  request: {
+    credentialId: string;
+    credentialVersion: number;
+    credentialSecret: string;
+  };
+  response: {
+    authenticated: true;
+    credentialVersion: number;
+    /** dcrouter's authoritative, control-plane-bound origin for CoreMail transfer paths. */
+    coreMailTransferOrigin: string;
+  };
+}
+
+export interface IReq_CoreMailGatewayResolveRecipients extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayResolveRecipients
+> {
+  method: 'coreMailGatewayResolveRecipients';
+  request: {
+    envelope: ICoreMailEnvelope;
+    recipients: string[];
+    source: IMailConnectionInfo;
+  };
+  response: {
+    resolutions: ICoreMailRecipientResolution[];
+  };
+}
+
+export interface IReq_CoreMailGatewayPrepareInboundHandoff extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayPrepareInboundHandoff
+> {
+  method: 'coreMailGatewayPrepareInboundHandoff';
+  request: {
+    transportDeliveryId: string;
+    routingHandles: string[];
+    message: ICoreMailGatewayMessageDescriptor;
+    source: IMailConnectionInfo;
+  };
+  response: {
+    handoffId: string;
+    grant?: ICoreMailUploadGrant;
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailGatewayCompleteInboundHandoff extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayCompleteInboundHandoff
+> {
+  method: 'coreMailGatewayCompleteInboundHandoff';
+  request: {
+    handoffId: string;
+    grantId: string;
+    sha256: TCoreMailSha256;
+    lengthBytes: number;
+  };
+  response: {
+    accepted: true;
+    deliveryIds: string[];
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailGatewayPrepareOutboundHandoff extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayPrepareOutboundHandoff
+> {
+  method: 'coreMailGatewayPrepareOutboundHandoff';
+  request: {
+    transportSubmissionId: string;
+    submissionDigest: TCoreMailSha256;
+    message: ICoreMailGatewayMessageDescriptor;
+    /** CoreMail-issued GET grant. dcrouter resolves the path against the authenticated peer. */
+    grant: ICoreMailDownloadGrant;
+  };
+  response: {
+    transportMessageId: string;
+    status: ICoreMailGatewayOutboundStatus;
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailGatewayCompleteOutboundHandoff extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayCompleteOutboundHandoff
+> {
+  method: 'coreMailGatewayCompleteOutboundHandoff';
+  request: {
+    transportMessageId: string;
+    grantId: string;
+    sha256: TCoreMailSha256;
+    lengthBytes: number;
+  };
+  response: {
+    status: ICoreMailGatewayOutboundStatus;
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailGatewayGetOutboundStatus extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayGetOutboundStatus
+> {
+  method: 'coreMailGatewayGetOutboundStatus';
+  request: {
+    transportMessageId: string;
+  };
+  response: {
+    status: ICoreMailGatewayOutboundStatus;
+  };
+}

package/ts/requests/index.ts

@@ -8,6 +8,7 @@ import * as backupRequests from './backup.js';
 import * as certificateRequests from './certificate.js';
 import * as clusterRequests from './cluster.js';
 import * as configRequests from './config.js';
+import * as coreMailRequests from './coremail.js';
 import * as corestoreRequests from './corestore.js';
 import * as deploymentRequests from './deployment.js';
 import * as dnsRequests from './dns.js';
@@ -45,6 +46,7 @@ export {
   certificateRequests as certificate,
   clusterRequests as cluster,
   configRequests as config,
+  coreMailRequests as coremail,
   corestoreRequests as corestore,
   deploymentRequests as deployment,
   dnsRequests as dns,