@serve.zone/interfaces 20.1.0 → 21.0.0

package/changelog.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 2026-07-29 - 21.0.0
+
+### Breaking Changes
+
+- harden runtime contracts with canonical digests and transfer-origin binding (coremail)
+  - Add strict CoreMail runtime normalization, canonicalization, desired-state digest creation, and digest verification helpers.
+  - Require versioned argon2id-v1 verifier format on CoreMail credential DTOs and expose the verifier policy/runtime keys.
+  - Add control bootstrap and gateway peer desired-state contracts for verifier metadata and authoritative transfer origins.
+  - Return dcrouter-bound CoreMail transfer origin from gateway authentication responses.
+
+## 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

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '20.1.0',
+    version: '21.0.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,253 @@
+/**
+ * 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 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;
+}>;
+export declare const coreMailCredentialVerifierPolicy: Readonly<{
+    readonly format: "argon2id-v1";
+    readonly version: 19;
+    readonly memoryCost: 65536;
+    readonly timeCost: 3;
+    readonly parallelism: 1;
+    readonly saltLengthBytes: 16;
+    readonly hashLengthBytes: 32;
+}>;
+export declare const coreMailRuntimeKeys: Readonly<{
+    readonly controlBootstrap: "COREMAIL_CONTROL_BOOTSTRAP";
+    readonly controlCredentialSecret: "COREMAIL_CONTROL_CREDENTIAL_SECRET";
+    readonly gatewayCredentialSecret: "COREMAIL_GATEWAY_CREDENTIAL";
+}>;

package/dist_ts/data/coremail.js

@@ -0,0 +1,38 @@
+/**
+ * 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,
+});
+export const coreMailCredentialVerifierPolicy = Object.freeze({
+    format: 'argon2id-v1',
+    version: 19,
+    memoryCost: 65_536,
+    timeCost: 3,
+    parallelism: 1,
+    saltLengthBytes: 16,
+    hashLengthBytes: 32,
+});
+export const coreMailRuntimeKeys = Object.freeze({
+    controlBootstrap: 'COREMAIL_CONTROL_BOOTSTRAP',
+    controlCredentialSecret: 'COREMAIL_CONTROL_CREDENTIAL_SECRET',
+    gatewayCredentialSecret: 'COREMAIL_GATEWAY_CREDENTIAL',
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29yZW1haWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2NvcmVtYWlsLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7O0dBT0c7QUF3UkgsTUFBTSxDQUFDLE1BQU0sY0FBYyxHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDMUMsbUJBQW1CLEVBQUUsRUFBRSxHQUFHLElBQUk7SUFDOUIsaUJBQWlCLEVBQUUsQ0FBQyxHQUFHLElBQUksR0FBRyxJQUFJO0lBQ2xDLGFBQWEsRUFBRSxDQUFDLEdBQUcsSUFBSSxHQUFHLElBQUk7SUFDOUIsYUFBYSxFQUFFLENBQUMsR0FBRyxJQUFJLEdBQUcsSUFBSTtJQUM5QixlQUFlLEVBQUUsRUFBRTtJQUNuQixlQUFlLEVBQUUsRUFBRSxHQUFHLElBQUksR0FBRyxJQUFJO0lBQ2pDLHdCQUF3QixFQUFFLEVBQUUsR0FBRyxJQUFJLEdBQUcsSUFBSTtJQUMxQyxnQkFBZ0IsRUFBRSxHQUFHLEdBQUcsSUFBSTtJQUM1QixtQkFBbUIsRUFBRSxFQUFFLEdBQUcsSUFBSSxHQUFHLElBQUk7SUFDckMsa0JBQWtCLEVBQUUsQ0FBQyxHQUFHLEVBQUUsR0FBRyxJQUFJO0lBQ2pDLHVCQUF1QixFQUFFLEVBQUUsR0FBRyxJQUFJO0lBQ2xDLHFCQUFxQixFQUFFLEVBQUUsR0FBRyxJQUFJO0lBQ2hDLHdCQUF3QixFQUFFLENBQUMsR0FBRyxFQUFFLEdBQUcsSUFBSTtDQUMvQixDQUFDLENBQUM7QUFFWixNQUFNLENBQUMsTUFBTSxnQ0FBZ0MsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQzVELE1BQU0sRUFBRSxhQUFzQjtJQUM5QixPQUFPLEVBQUUsRUFBRTtJQUNYLFVBQVUsRUFBRSxNQUFNO0lBQ2xCLFFBQVEsRUFBRSxDQUFDO0lBQ1gsV0FBVyxFQUFFLENBQUM7SUFDZCxlQUFlLEVBQUUsRUFBRTtJQUNuQixlQUFlLEVBQUUsRUFBRTtDQUNYLENBQUMsQ0FBQztBQUVaLE1BQU0sQ0FBQyxNQUFNLG1CQUFtQixHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDL0MsZ0JBQWdCLEVBQUUsNEJBQTRCO0lBQzlDLHVCQUF1QixFQUFFLG9DQUFvQztJQUM3RCx1QkFBdUIsRUFBRSw2QkFBNkI7Q0FDOUMsQ0FBQyxDQUFDIn0=

package/dist_ts/data/coremail.runtime.d.ts

@@ -0,0 +1,31 @@
+import { type ICoreMailBindingCredentialVerifier, type ICoreMailControlBootstrap, type ICoreMailDesiredState, type ICoreMailGatewayPeerDesiredState, type TCoreMailSha256 } from './coremail.js';
+export declare const coreMailCanonicalJsonRules: Readonly<{
+    version: 1;
+    encoding: "utf-8";
+    objectKeyOrdering: "utf-16-code-unit-ascending";
+    arrayOrdering: "preserved-dense";
+    unicodeNormalization: "preserved";
+    numberEncoding: "safe-integer-json-no-negative-zero";
+    digest: "sha256-lowercase-hex";
+}>;
+export declare const coreMailContractLimits: Readonly<{
+    readonly maximumIdentifierBytes: 128;
+    readonly maximumEnvironmentKeyBytes: 128;
+    readonly maximumEndpointBytes: 2048;
+    readonly maximumMailboxBytes: 254;
+    readonly maximumBindings: 10000;
+    readonly maximumCredentialsPerAuthority: 16;
+    readonly maximumAllowedSendersPerBinding: 1000;
+    readonly maximumInboundRecipientsPerBinding: 10000;
+}>;
+export declare class CoreMailContractError extends Error {
+    constructor(reasonArg: string);
+}
+export declare const normalizeCoreMailSha256: (valueArg: unknown, pathArg?: string) => TCoreMailSha256;
+export declare const normalizeCoreMailCredentialVerifier: (valueArg: unknown, pathArg?: string) => ICoreMailBindingCredentialVerifier;
+export declare const normalizeCoreMailDesiredState: (valueArg: unknown) => ICoreMailDesiredState;
+export declare const canonicalizeCoreMailDesiredState: (valueArg: unknown) => string;
+export declare const createCoreMailDesiredStateDigest: (valueArg: unknown) => Promise<TCoreMailSha256>;
+export declare const verifyCoreMailDesiredStateDigest: (valueArg: unknown, digestArg: unknown) => Promise<boolean>;
+export declare const normalizeCoreMailControlBootstrap: (valueArg: unknown) => ICoreMailControlBootstrap;
+export declare const normalizeCoreMailGatewayPeerDesiredState: (valueArg: unknown) => ICoreMailGatewayPeerDesiredState;