@serve.zone/interfaces 21.0.0 → 22.0.0

package/dist_ts/requests/coremail.d.ts

@@ -1,5 +1,5 @@
 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 { ICoreMailEnvelope, ICoreMailInboundDeliveryPage, ICoreMailDownloadGrant, ICoreMailGatewayMessageDescriptor, ICoreMailGatewayOutboundStatus, ICoreMailInboundDelivery, ICoreMailOutboundMessageDescriptor, ICoreMailRecipientResolution, ICoreMailReconciliationStatus, ICoreMailReplicaIdentity, ICoreMailSubmission, ICoreMailUploadGrant, TCoreMailInboundAckOutcome, TCoreMailSha256, TCoreMailWorkloadOperation } 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';
@@ -11,8 +11,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;
     };
 }
 export interface IReq_CoreMailPrepareOutboundSubmission extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailPrepareOutboundSubmission> {
@@ -71,12 +76,11 @@ export interface IReq_CoreMailGetOutboundSubmission extends plugins.typedrequest
 export interface IReq_CoreMailListInboundDeliveries extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailListInboundDeliveries> {
     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<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailPrepareInboundFetch> {
     method: 'coreMailPrepareInboundFetch';
@@ -119,6 +123,8 @@ export interface IReq_CoreMailAuthenticateControl extends plugins.typedrequestIn
     };
     response: {
         authenticated: true;
+        credentialId: string;
+        credentialVersion: number;
         replica: ICoreMailReplicaIdentity;
     };
 }
@@ -167,6 +173,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;

package/dist_ts/requests/status.d.ts

@@ -1,6 +1,13 @@
 import * as plugins from '../plugins.js';
 import * as serviceInterfaces from '../data/service.js';
 import * as userInterfaces from '../data/user.js';
+type TReportReconciliationRolloutIdentity = {
+    rolloutId: string;
+    rolloutGeneration: number;
+} | {
+    rolloutId?: never;
+    rolloutGeneration?: never;
+};
 /**
  * a status update dashboard
  */
@@ -24,6 +31,7 @@ export interface IRequest_Coreflow_Cloudly_ReportReconciliationStatus extends pl
         message?: string;
         errorText?: string;
         reportedAt?: number;
-    };
+    } & TReportReconciliationRolloutIdentity;
     response: {};
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "21.0.0",
+  "version": "22.0.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/readme.md

@@ -487,8 +487,12 @@ sessions, Coreflow reconciliation, and the CoreMail-to-dcrouter gateway
 session. Only the three authentication handshakes carry reusable peer
 credentials. Subsequent transfer operations may carry a scoped, short-lived,
 one-time bearer capability, while every subsequent workload request derives
-tenant, service, binding, capabilities, allowed senders, and credential version
-from the server-owned TypedSocket peer.
+tenant, service, binding, capabilities, allowed senders, and the composite
+credential ID/version identity from the server-owned TypedSocket peer.
+Successful workload authentication also returns the effective binding state and
+the exact `allowedOperations` derived from
+`data.coreMailWorkloadOperationPolicy`. Disabled bindings never authenticate;
+draining bindings permit outbound status plus inbound list/fetch/ack only.
 
 Large content never travels inside TypedRequest JSON. Outbound body parts and
 attachments use prepare/upload/complete operations with short-lived one-time
@@ -496,8 +500,8 @@ HTTP transfer grants. Inbound delivery uses bounded delivery listing followed
 by prepare/fetch/complete and an explicit acknowledgement after the workload
 has processed the exact byte count and SHA-256 digest. `data.coreMailLimits`
 defines the 64 KiB control-frame boundary, bounded structured content, the
-30 MiB serialized MIME ceiling, transfer deadlines, and five-minute grant
-lifetime.
+30 MiB serialized MIME ceiling, a 56 KiB inbound page budget, bounded opaque
+cursors, transfer deadlines, and five-minute grant lifetime.
 
 Coreflow applies `data.ICoreMailDesiredState` with a config-epoch
 compare-and-set fence. It stages the digest-fenced JSON snapshot through a
@@ -526,22 +530,65 @@ canonical environment keys for the verifier-only bootstrap payload and the
 separate control and gateway secret values; no consumer may derive or embed
 plaintext material in desired state.
 
+CoreMail schema v2 keeps durable authority at the stable tenant, service, and
+binding identity while revisions, config epochs, and composite
+`credentialId`/`version` values fence sessions and new actions. Credential
+versions are authority-wide monotonic and unique even when rotation changes the
+credential ID. `active`
+bindings accept new mail, `draining` bindings permit existing status and
+inbound fetch/ack work without accepting new mail, and `disabled` bindings
+reject authentication. Cloudly retains a draining binding until pending
+inbound delivery reaches zero as reported by
+`ICoreMailBindingReconciliationStatus.pendingInboundCount`.
+
 `data.ICoreMailGatewayPeerDesiredState` gives dcrouter the authoritative HTTPS
 CoreMail transfer origin associated with an authenticated CoreMail service.
-The origin is control-plane state and must never be inferred from a socket,
-Host header, TypedSocket tag, or unrestricted peer input. The gateway
-authentication response repeats dcrouter's bound origin so CoreMail can reject
-configuration drift before handing over a path-only transfer grant.
+The same origin is carried in CoreMail desired state and returned by workload
+and gateway authentication. It must never be inferred from a socket, Host
+header, TypedSocket tag, or unrestricted peer input. CoreMail compares both
+authoritative views before handing over a path-only transfer grant.
+
+Inbound delivery pagination uses an opaque CoreMail-owned `cursor`, is bounded
+by `data.coreMailLimits.inboundPageSize`, and returns `nextCursor` only when
+another page may exist. Consumers must not construct or parse cursor contents.
+Cursor signing keys are value-free runtime references with one current and bounded
+retiring versions; plaintext remains in resolved runtime secrets.
+
+Quota windows are fixed UTC minute/day buckets. A new outbound quota unit is
+consumed only by the first durable insertion of an idempotency identity, while
+replays consume none. Pending inbound includes every state except
+`acknowledged`. These semantics are exported as `data.coreMailQuotaPolicy`.
+Every binding carries finite `messagesPerMinute`, `messagesPerDay`, and
+`maxPendingInbound` values; omitted or unlimited quotas are not valid schema-v2
+desired state.
+`data.coreMailRetentionPolicy` retains terminal outbound,
+acknowledged inbound, and idempotency receipts for 30 days and expired
+capabilities for 24 hours. Pending inbound is never age-purged.
+
+HTTP transfers use canonical `/transfers/<uuid>` paths and one-time Bearer
+tokens. `data.coreMailTransferTokenPolicy` requires canonical 256-bit
+base64url token material, while `issuedAt` and `expiresAt` prove the exact
+five-minute lifetime. PUT succeeds with 204 and GET with 200. Content length
+and type must match the grant; digest integrity is bound by grant metadata and repeated in
+the completion RPC rather than an optional HTTP digest header. Apply the
+exported strict normalizers for outbound message descriptors, envelopes,
+method-specific upload/download grants, submissions, gateway outbound
+statuses, inbound deliveries,
+desired state, bootstrap state, and gateway-peer state at their corresponding
+untrusted request and response boundaries.
 
 Control and gateway credential rotation is ordered: provision the candidate
 plaintext through resolved runtime secrets, publish and activate the matching
 `argon2id-v1` verifier, roll or reconnect every affected replica, observe
 per-task authentication and readiness, then mark the previous verifier
 `retiring` with `acceptUntil`. Remove the previous verifier and secret only
-after its acceptance window has elapsed and no session uses that version.
+after its acceptance window has elapsed and no session uses that composite
+credential identity.
 Reconciliation status carries the exact CoreMail task, rollout generation, and
 image digest so Coreflow can correlate every response with its authoritative
-current task roster.
+current task roster. Apply `data.normalizeCoreMailReconciliationStatus` before
+using pending-inbound or composite active-session counts for drain and rotation
+decisions.
 
 Request groups are exported by product area:
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '21.0.0',
+  version: '22.0.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }