@serve.zone/interfaces 20.0.0 → 20.2.0

package/changelog.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 2026-07-29 - 20.2.0
+
+### Features
+
+- add CoreMail data and request contracts (coremail)
+  - Export CoreMail shared data models, transfer grants, desired-state structures, reconciliation status, and limits
+  - Add CoreMail TypedRequest interfaces for workload authentication, outbound submissions, inbound delivery handling, reconciliation, and gateway handoffs
+  - Document CoreMail authority, transfer, and desired-state constraints with contract coverage
+  - Bump @api.global/typedrequest-interfaces to ^4.0.0
+
+## 2026-07-29 - 20.1.0
+
+### Features
+
+- add fenced object-storage migration control contracts (platform.storagemigration)
+  - Export platform.storagemigration with versioned migration intent, status, and consumer acknowledgement contracts.
+  - Add strict normalizers, mutation fences, canonical SHA-256 digest helpers, and portable golden vectors for migration payloads.
+  - Introduce shared strict canonical JSON utilities and reuse them for isolated restore digests.
+
+### Fixes
+
+- deduplicate storage migration changelog entry (changelog)
+  - Consolidates the pending fenced object-storage migration notes under the platform.storagemigration entry.
+
 ## 2026-07-29 - 20.0.0
 
 ### Breaking Changes

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '20.0.0',
+    version: '20.2.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/coremail.d.ts

@@ -0,0 +1,216 @@
+/**
+ * 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 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;
+    /** 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;
+}
+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 declare const coreMailLimits: Readonly<{
+    readonly controlMessageBytes: number;
+    readonly desiredStateBytes: number;
+    readonly textPartBytes: number;
+    readonly htmlPartBytes: number;
+    readonly attachmentCount: 16;
+    readonly attachmentBytes: number;
+    readonly aggregateAttachmentBytes: number;
+    readonly mimeFramingBytes: number;
+    readonly serializedMimeBytes: number;
+    readonly transferGrantTtlMs: number;
+    readonly transferHeaderTimeoutMs: number;
+    readonly transferIdleTimeoutMs: number;
+    readonly transferOverallTimeoutMs: number;
+}>;

package/dist_ts/data/coremail.js

@@ -0,0 +1,24 @@
+/**
+ * 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 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,
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29yZW1haWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2NvcmVtYWlsLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7O0dBT0c7QUErUEgsTUFBTSxDQUFDLE1BQU0sY0FBYyxHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDMUMsbUJBQW1CLEVBQUUsRUFBRSxHQUFHLElBQUk7SUFDOUIsaUJBQWlCLEVBQUUsQ0FBQyxHQUFHLElBQUksR0FBRyxJQUFJO0lBQ2xDLGFBQWEsRUFBRSxDQUFDLEdBQUcsSUFBSSxHQUFHLElBQUk7SUFDOUIsYUFBYSxFQUFFLENBQUMsR0FBRyxJQUFJLEdBQUcsSUFBSTtJQUM5QixlQUFlLEVBQUUsRUFBRTtJQUNuQixlQUFlLEVBQUUsRUFBRSxHQUFHLElBQUksR0FBRyxJQUFJO0lBQ2pDLHdCQUF3QixFQUFFLEVBQUUsR0FBRyxJQUFJLEdBQUcsSUFBSTtJQUMxQyxnQkFBZ0IsRUFBRSxHQUFHLEdBQUcsSUFBSTtJQUM1QixtQkFBbUIsRUFBRSxFQUFFLEdBQUcsSUFBSSxHQUFHLElBQUk7SUFDckMsa0JBQWtCLEVBQUUsQ0FBQyxHQUFHLEVBQUUsR0FBRyxJQUFJO0lBQ2pDLHVCQUF1QixFQUFFLEVBQUUsR0FBRyxJQUFJO0lBQ2xDLHFCQUFxQixFQUFFLEVBQUUsR0FBRyxJQUFJO0lBQ2hDLHdCQUF3QixFQUFFLENBQUMsR0FBRyxFQUFFLEdBQUcsSUFBSTtDQUMvQixDQUFDLENBQUMifQ==

package/dist_ts/data/index.d.ts

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

package/dist_ts/data/index.js

@@ -1,6 +1,7 @@
 export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './config.js';
+export * from './coremail.js';
 export * from './deployment.js';
 export * from './deploymentadoption.js';
 export * from './deploymentoperation.js';
@@ -35,4 +36,4 @@ export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
 export * from './webpush.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyw2QkFBNkIsQ0FBQztBQUM1QyxjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGNBQWMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyw2QkFBNkIsQ0FBQztBQUM1QyxjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGNBQWMsQ0FBQyJ9