@serve.zone/interfaces 30.11.0 → 30.13.0

package/dist_ts/data/mail.d.ts

@@ -1,6 +1,6 @@
 export type TMailGatewayClientType = 'onebox' | 'cloudly' | 'custom' | (string & {});
 export type TMailAddressPatternType = 'exactAddress' | 'domainWildcard' | 'localPartPattern';
-export type TMailInboundTargetType = 'webhook' | 'smtpForward' | 'typedEndpoint' | 'discard' | 'reject';
+export type TMailInboundTargetType = 'webhook' | 'smtpForward' | 'typedEndpoint' | 'coreMail' | 'discard' | 'reject';
 export type TMailRecipientPolicyMode = 'acceptAll' | 'staticList' | 'cachedResolver' | 'appResolver';
 export type TMailCredentialType = 'smtp' | 'api';
 export type TMailCredentialStatus = 'active' | 'disabled' | 'rotated' | 'revoked';
@@ -12,7 +12,12 @@ export type TMailBounceType = 'hard' | 'soft' | 'complaint' | 'unknown';
 export type TMailInboundProtocol = 'smtp' | 'submission' | 'api';
 export type TMailRecipientResolutionAction = 'accept' | 'reject' | 'defer';
 export type TMailDeliveryJournalEventType = 'accepted' | 'queued' | 'deliveryStarted' | 'deliverySucceeded' | 'deliveryDeferred' | 'deliveryFailed' | 'deadLettered' | 'rejected' | 'bounced' | 'complaint';
-export type TMailSubmissionErrorCode = 'INVALID_REPLY_TO' | 'REPLY_TO_FIELD_HEADER_CONFLICT';
+/**
+ * Error codes a mail submission may return. The CoreMail-fronted path maps the
+ * matching `TCoreMailErrorCode` values through unchanged so applications can
+ * branch on them regardless of which transport carried the submission.
+ */
+export type TMailSubmissionErrorCode = 'INVALID_REPLY_TO' | 'REPLY_TO_FIELD_HEADER_CONFLICT' | 'AUTHENTICATION_FAILED' | 'CAPABILITY_DENIED' | 'INVALID_REQUEST' | 'INVALID_MAILBOX' | 'INVALID_SENDER' | 'INVALID_RECIPIENT' | 'INVALID_HEADER' | 'PAYLOAD_LIMIT_EXCEEDED' | 'QUOTA_EXCEEDED' | 'IDEMPOTENCY_CONFLICT' | 'STATE_CONFLICT' | 'NOT_FOUND';
 /**
  * Runtime owner of a mail resource. `appInstanceId` is the deployed WorkApp or service
  * instance, not an App Store template id.
@@ -48,11 +53,16 @@ export interface IMailTypedEndpointTarget {
     queueName?: string;
     timeoutMs?: number;
 }
+export interface IMailCoreMailTarget {
+    /** CoreMail service identity that owns the inbound mailbox. */
+    coreMailServiceId: string;
+}
 export interface IMailInboundTarget {
     type: TMailInboundTargetType;
     webhook?: IMailWebhookTarget;
     smtpForward?: IMailSmtpForwardTarget;
     typedEndpoint?: IMailTypedEndpointTarget;
+    coreMail?: IMailCoreMailTarget;
     reject?: {
         smtpCode: number;
         message: string;
@@ -175,8 +185,11 @@ export interface IWorkAppMailBinding {
 export type TServiceMailSubmissionTlsMode = 'plain' | 'starttls' | 'implicitTls';
 export interface IServiceMailInboundConfig {
     enabled?: boolean;
-    /** Platformclient apps use typedEndpoint; third-party apps with their own SMTP server use smtpForward. */
-    targetType?: 'typedEndpoint' | 'smtpForward';
+    /**
+     * Platformclient apps use typedEndpoint; third-party apps with their own SMTP
+     * server use smtpForward; services bound to a CoreMail workload use coreMail.
+     */
+    targetType?: 'typedEndpoint' | 'smtpForward' | 'coreMail';
     /** TypedRequest method exposed by platformclient over TypedSocket for inbound delivery. */
     typedMethod?: string;
     /** Published Docker/Swarm port that dcrouter may SMTP-forward inbound mail to. */

package/dist_ts/data/networkcredential.d.ts

@@ -0,0 +1,32 @@
+import type { IRuntimeAuthorityReferenceV1 } from './runtimeassignment.js';
+import { type IRuntimeSessionBindingV1 } from './runtimesession.js';
+export interface IGetRuntimeManagedVpnCredentialRequestV1 {
+    session: IRuntimeSessionBindingV1;
+    projection: IRuntimeAuthorityReferenceV1;
+}
+/** Secret response over the current authenticated physical peer only. Never
+ * persist, hash, log, or include it in a signed network projection. The native
+ * Noise owner validates and uses the keys; these shapes confer no TUN readiness. */
+export interface IGetRuntimeManagedVpnCredentialResponseV1 extends IGetRuntimeManagedVpnCredentialRequestV1 {
+    transport: 'quic';
+    relay: {
+        id: string;
+        address: string;
+        port: number;
+    };
+    authorityId: string;
+    serverPublicKey: string;
+    clientPublicKey: string;
+    clientPrivateKey: string;
+    /** Unix milliseconds; cannot outlive the referenced projection's DNS lease. */
+    expiresAt: number;
+}
+export declare const snapshotGetRuntimeManagedVpnCredentialRequestV1: (value: unknown) => IGetRuntimeManagedVpnCredentialRequestV1;
+export declare const snapshotGetRuntimeManagedVpnCredentialResponseV1: (value: unknown) => IGetRuntimeManagedVpnCredentialResponseV1;
+/** Content binding only. The caller must resolve the exact current projection
+ * and authenticate/fence the current physical peer before and after native work. */
+export declare const bindGetRuntimeManagedVpnCredentialRequestV1: (value: unknown, projectionValue: unknown, trustedSessionValue: unknown) => Promise<IGetRuntimeManagedVpnCredentialRequestV1>;
+/** Bind the secret response to the original request and exact selected router
+ * UDP endpoint. Time is caller-qualified; this helper does not sample a clock,
+ * authenticate a transport, admit policy or prove a running managed connection. */
+export declare const bindGetRuntimeManagedVpnCredentialResponseV1: (value: unknown, requestValue: unknown, projectionValue: unknown, trustedSessionValue: unknown, nowValue: unknown) => Promise<IGetRuntimeManagedVpnCredentialResponseV1>;

package/dist_ts/data/networkcredential.js

@@ -0,0 +1,66 @@
+import { snapshotRuntimeSessionBindingV1 } from './runtimesession.js';
+import { validateRuntimeNetworkProjectionV1 } from './networkprojection.js';
+import { captureNetwork, failNetwork, networkCounter, networkEqual, networkId, networkIpv4, networkRecord, networkReference, networkReferenceOf, networkSafe, requireNetwork } from '../private/networkcontract.js';
+/** Canonical 32-byte key encoding only. Cryptographic key agreement and pair
+ * validation belong to the native Noise implementation, not this JSON parser. */
+const key = (value) => {
+    requireNetwork(typeof value === 'string' && /^[A-Za-z0-9+/]{43}=$/.test(value));
+    const decoded = atob(value);
+    requireNetwork(decoded.length === 32 && btoa(decoded) === value && [...decoded].some(byte => byte.charCodeAt(0) !== 0));
+    return value;
+};
+export const snapshotGetRuntimeManagedVpnCredentialRequestV1 = (value) => networkSafe(() => {
+    const item = networkRecord(captureNetwork(value), ['session', 'projection']);
+    return { session: snapshotRuntimeSessionBindingV1(item.session), projection: networkReference(item.projection) };
+});
+export const snapshotGetRuntimeManagedVpnCredentialResponseV1 = (value) => networkSafe(() => {
+    const item = networkRecord(captureNetwork(value), ['session', 'projection', 'transport', 'relay', 'authorityId',
+        'serverPublicKey', 'clientPublicKey', 'clientPrivateKey', 'expiresAt']);
+    const relay = networkRecord(item.relay, ['id', 'address', 'port']);
+    requireNetwork(item.transport === 'quic');
+    return { session: snapshotRuntimeSessionBindingV1(item.session), projection: networkReference(item.projection), transport: 'quic',
+        relay: { id: networkId(relay.id), address: networkIpv4(relay.address), port: networkCounter(relay.port, 65535) },
+        authorityId: networkId(item.authorityId), serverPublicKey: key(item.serverPublicKey), clientPublicKey: key(item.clientPublicKey),
+        clientPrivateKey: key(item.clientPrivateKey), expiresAt: networkCounter(item.expiresAt) };
+});
+const bindRequest = (request, projection, trusted) => {
+    requireNetwork(networkEqual(request.session, trusted) && networkEqual(request.projection, networkReferenceOf(projection))
+        && networkEqual(projection.controller, trusted.controller) && projection.nodeId === trusted.nodeId
+        && projection.runtimeNamespace === trusted.runtimeNamespace && projection.handoff);
+};
+/** Content binding only. The caller must resolve the exact current projection
+ * and authenticate/fence the current physical peer before and after native work. */
+export const bindGetRuntimeManagedVpnCredentialRequestV1 = async (value, projectionValue, trustedSessionValue) => {
+    try {
+        const request = snapshotGetRuntimeManagedVpnCredentialRequestV1(value);
+        const trusted = snapshotRuntimeSessionBindingV1(trustedSessionValue);
+        const projection = await validateRuntimeNetworkProjectionV1(projectionValue);
+        bindRequest(request, projection, trusted);
+        return request;
+    }
+    catch {
+        return failNetwork();
+    }
+};
+/** Bind the secret response to the original request and exact selected router
+ * UDP endpoint. Time is caller-qualified; this helper does not sample a clock,
+ * authenticate a transport, admit policy or prove a running managed connection. */
+export const bindGetRuntimeManagedVpnCredentialResponseV1 = async (value, requestValue, projectionValue, trustedSessionValue, nowValue) => {
+    try {
+        const response = snapshotGetRuntimeManagedVpnCredentialResponseV1(value);
+        const request = snapshotGetRuntimeManagedVpnCredentialRequestV1(requestValue);
+        const trusted = snapshotRuntimeSessionBindingV1(trustedSessionValue), now = networkCounter(nowValue);
+        const projection = await validateRuntimeNetworkProjectionV1(projectionValue);
+        bindRequest(request, projection, trusted);
+        requireNetwork(networkEqual(response.session, request.session) && networkEqual(response.projection, request.projection));
+        requireNetwork(projection.router?.platformEndpointIds.includes(response.relay.id));
+        const endpoint = projection.protectedAuthority.platformEndpoints.find(item => item.id === response.relay.id);
+        requireNetwork(endpoint && endpoint.protocol === 'udp' && endpoint.address === response.relay.address && endpoint.port === response.relay.port);
+        requireNetwork(projection.dns.notBefore <= now && now < response.expiresAt && response.expiresAt <= projection.dns.expiresAt);
+        return response;
+    }
+    catch {
+        return failNetwork();
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmV0d29ya2NyZWRlbnRpYWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL25ldHdvcmtjcmVkZW50aWFsLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUNBLE9BQU8sRUFBRSwrQkFBK0IsRUFBaUMsTUFBTSxxQkFBcUIsQ0FBQztBQUNyRyxPQUFPLEVBQUUsa0NBQWtDLEVBQW9DLE1BQU0sd0JBQXdCLENBQUM7QUFDOUcsT0FBTyxFQUFFLGNBQWMsRUFBRSxXQUFXLEVBQUUsY0FBYyxFQUFFLFlBQVksRUFBRSxTQUFTLEVBQUUsV0FBVyxFQUN4RixhQUFhLEVBQUUsZ0JBQWdCLEVBQUUsa0JBQWtCLEVBQUUsV0FBVyxFQUFFLGNBQWMsRUFBRSxNQUFNLCtCQUErQixDQUFDO0FBcUIxSDtpRkFDaUY7QUFDakYsTUFBTSxHQUFHLEdBQUcsQ0FBQyxLQUFjLEVBQVUsRUFBRTtJQUNyQyxjQUFjLENBQUMsT0FBTyxLQUFLLEtBQUssUUFBUSxJQUFJLHNCQUFzQixDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDO0lBQ2hGLE1BQU0sT0FBTyxHQUFHLElBQUksQ0FBQyxLQUFLLENBQUMsQ0FBQztJQUM1QixjQUFjLENBQUMsT0FBTyxDQUFDLE1BQU0sS0FBSyxFQUFFLElBQUksSUFBSSxDQUFDLE9BQU8sQ0FBQyxLQUFLLEtBQUssSUFBSSxDQUFDLEdBQUcsT0FBTyxDQUFDLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxFQUFFLENBQUMsSUFBSSxDQUFDLFVBQVUsQ0FBQyxDQUFDLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDO0lBQ3hILE9BQU8sS0FBSyxDQUFDO0FBQ2YsQ0FBQyxDQUFDO0FBRUYsTUFBTSxDQUFDLE1BQU0sK0NBQStDLEdBQUcsQ0FBQyxLQUFjLEVBQTRDLEVBQUUsQ0FBQyxXQUFXLENBQUMsR0FBRyxFQUFFO0lBQzVJLE1BQU0sSUFBSSxHQUFHLGFBQWEsQ0FBQyxjQUFjLENBQUMs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

package/dist_ts/requests/coremail.d.ts

@@ -1,5 +1,5 @@
 import type * as plugins from '../plugins.js';
-import type { ICoreMailEnvelope, ICoreMailInboundDeliveryPage, ICoreMailDownloadGrant, ICoreMailGatewayMessageDescriptor, ICoreMailGatewayOutboundStatus, ICoreMailInboundDelivery, ICoreMailOutboundMessageDescriptor, ICoreMailRecipientResolution, ICoreMailReconciliationStatus, ICoreMailReplicaIdentity, ICoreMailSubmission, ICoreMailUploadGrant, TCoreMailInboundAckOutcome, TCoreMailSha256, TCoreMailWorkloadOperation } from '../data/coremail.js';
+import type { ICoreMailEnvelope, ICoreMailInboundDeliveryPage, ICoreMailDownloadGrant, ICoreMailGatewayMessageDescriptor, ICoreMailGatewayOutboundStatus, ICoreMailInboundDelivery, ICoreMailOutboundMessageDescriptor, ICoreMailRecipientResolution, ICoreMailReconciliationStatus, ICoreMailReplicaIdentity, ICoreMailServiceMailStatistics, 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';
@@ -164,6 +164,29 @@ export interface IReq_CoreMailGetReconciliationStatus extends plugins.typedreque
         status: ICoreMailReconciliationStatus;
     };
 }
+/**
+ * Control-session read of per-service mail counters. Authority comes from the
+ * authenticated control session; the request carries no tenant or binding
+ * authority of its own.
+ */
+export interface IReq_CoreMailGetServiceMailStatistics extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailGetServiceMailStatistics> {
+    method: 'coreMailGetServiceMailStatistics';
+    request: {
+        /** Inclusive first UTC calendar day, `YYYY-MM-DD`. */
+        fromDayUtc: string;
+        /** Inclusive last UTC calendar day, `YYYY-MM-DD`. */
+        toDayUtc: string;
+        /** Optional service filter. Omitted means every service known to this CoreMail. */
+        serviceIds?: string[];
+        /** Opaque CoreMail-owned composite cursor. */
+        cursor?: string;
+        limit: number;
+    };
+    response: {
+        statistics: ICoreMailServiceMailStatistics[];
+        nextCursor?: string;
+    };
+}
 export interface IReq_CoreMailGatewayAuthenticate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailGatewayAuthenticate> {
     method: 'coreMailGatewayAuthenticate';
     request: {
@@ -179,6 +202,13 @@ export interface IReq_CoreMailGatewayAuthenticate extends plugins.typedrequestIn
         coreMailTransferOrigin: string;
     };
 }
+/**
+ * CoreMail binds every issued routing handle to a digest of the exact
+ * normalized `envelope` and `source` sent here. The following
+ * `coreMailGatewayPrepareInboundHandoff` call must therefore resend
+ * byte-identical values: the full `rcptTo` set in the same order, the same
+ * `mailFrom`, and the same connection source fields.
+ */
 export interface IReq_CoreMailGatewayResolveRecipients extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailGatewayResolveRecipients> {
     method: 'coreMailGatewayResolveRecipients';
     request: {
@@ -190,6 +220,13 @@ export interface IReq_CoreMailGatewayResolveRecipients extends plugins.typedrequ
         resolutions: ICoreMailRecipientResolution[];
     };
 }
+/**
+ * The handoff is validated against the routing handles issued by
+ * `coreMailGatewayResolveRecipients`. `message.envelope` and `source` must be
+ * byte-identical to the resolve-time values, including the full `rcptTo` set in
+ * the same order, because CoreMail recomputes the envelope digest the handles
+ * are bound to.
+ */
 export interface IReq_CoreMailGatewayPrepareInboundHandoff extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailGatewayPrepareInboundHandoff> {
     method: 'coreMailGatewayPrepareInboundHandoff';
     request: {
@@ -246,6 +283,12 @@ export interface IReq_CoreMailGatewayCompleteOutboundHandoff extends plugins.typ
         replayed: boolean;
     };
 }
+/**
+ * Status polling for one accepted transport message. `status.updatedAt` must be
+ * monotonic per `transportMessageId`. A `transportMessageId` that is
+ * permanently unknown to the gateway must be answered with a terminal `failed`
+ * status rather than an error, because CoreMail retries errors indefinitely.
+ */
 export interface IReq_CoreMailGatewayGetOutboundStatus extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailGatewayGetOutboundStatus> {
     method: 'coreMailGatewayGetOutboundStatus';
     request: {

package/dist_ts/requests/mail.d.ts

@@ -1,4 +1,5 @@
 import * as plugins from '../plugins.js';
+import type { ICoreMailGatewayPeerDesiredState } from '../data/coremail.js';
 import type { IIdentity } from '../data/user.js';
 import type { IMailAddressBinding, IMailCredentialOneTimeSecret, IMailConnectionInfo, IMailDeliveryJournalEvent, IMailDeliveryStatus, IMailDomainAuthority, IMailEnvelope, IMailInboundMessagePayload, IMailOutboundIdentity, IMailOutboundMessagePayload, IMailRecipientResolution, IMailResourceOwner, IMailSpoolItem, IWorkAppMailBinding, TMailSubmissionErrorCode } from '../data/mail.js';
 export interface IMailControlRequestAuth {
@@ -89,6 +90,55 @@ export interface IReq_DeleteMailAddressBinding extends plugins.typedrequestInter
         message?: string;
     };
 }
+/**
+ * dcrouter-owned CoreMail gateway peer state.
+ *
+ * `peer.transferOrigin` must equal the `gateway.coreMailTransferOrigin` carried
+ * in that CoreMail service's own desired state. The producer (Cloudly or
+ * Onebox) is the single owner of that string: dcrouter never infers it from a
+ * socket, Host header, TypedSocket tag, or peer input.
+ */
+export interface IReq_ListCoreMailGatewayPeers extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ListCoreMailGatewayPeers> {
+    method: 'listCoreMailGatewayPeers';
+    request: {
+        auth: IMailControlRequestAuth;
+        owner: IMailResourceOwner;
+    };
+    response: {
+        peers: ICoreMailGatewayPeerDesiredState[];
+    };
+}
+/**
+ * Creates or replaces one CoreMail gateway peer. On success the accepted peer is
+ * returned in its stored form so the producer can compare the exact applied
+ * state. `owner` is required (not partial) because a peer is producer-owned
+ * provisioning state, never a filtered listing.
+ */
+export interface IReq_SyncCoreMailGatewayPeer extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_SyncCoreMailGatewayPeer> {
+    method: 'syncCoreMailGatewayPeer';
+    request: {
+        auth: IMailControlRequestAuth;
+        owner: IMailResourceOwner;
+        peer: ICoreMailGatewayPeerDesiredState;
+    };
+    response: {
+        success: boolean;
+        peer?: ICoreMailGatewayPeerDesiredState;
+        message?: string;
+    };
+}
+export interface IReq_DeleteCoreMailGatewayPeer extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_DeleteCoreMailGatewayPeer> {
+    method: 'deleteCoreMailGatewayPeer';
+    request: {
+        auth: IMailControlRequestAuth;
+        owner: IMailResourceOwner;
+        coreMailServiceId: string;
+    };
+    response: {
+        success: boolean;
+        message?: string;
+    };
+}
 export interface IReq_ListWorkAppMailBindings extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ListWorkAppMailBindings> {
     method: 'listWorkAppMailBindings';
     request: {

package/dist_ts/requests/runtimesession.d.ts

@@ -3,6 +3,13 @@ import type * as data from '../data/runtimesession.js';
 import type * as terminal from '../data/runtimeterminalreceipt.js';
 import type * as network from '../data/networkdelivery.js';
 import type * as protection from '../data/networkprotection.js';
+import type * as credential from '../data/networkcredential.js';
+/** Current-peer, exact-projection authorization; response contains secret keys. */
+export interface IReq_Pallet_Controller_GetRuntimeManagedVpnCredentialV1 extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Pallet_Controller_GetRuntimeManagedVpnCredentialV1> {
+    method: 'getRuntimeManagedVpnCredentialV1';
+    request: credential.IGetRuntimeManagedVpnCredentialRequestV1;
+    response: credential.IGetRuntimeManagedVpnCredentialResponseV1;
+}
 /** Current authenticated peer reports its durable complete native protection journal. */
 export interface IReq_Pallet_Controller_ReportRuntimeNetworkProtectionV1 extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Pallet_Controller_ReportRuntimeNetworkProtectionV1> {
     method: 'reportRuntimeNetworkProtectionV1';

package/package.json

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

package/readme.md

@@ -415,6 +415,31 @@ exported material only through its encrypted internal secret store. The dedicate
 peer. Their response acknowledges durable admission only, never application,
 readiness, independent fencing or pool activation.
 
+The `getRuntimeManagedVpnCredentialV1` method contract in `requests.runtimesession`
+uses `IGetRuntimeManagedVpnCredentialRequestV1` and
+`IGetRuntimeManagedVpnCredentialResponseV1`. Its request carries the exact current
+session and signed projection reference. The secret response repeats those
+bindings and supplies a QUIC relay tuple, managed authority ID, Noise server
+public key, client keypair and expiry in Unix milliseconds. Keep the response
+process-local; never persist, hash, log or embed it in a signed projection.
+
+`snapshotGetRuntimeManagedVpnCredentialRequestV1` and its response counterpart
+capture closed detached JSON shapes and canonical 32-byte key encodings.
+`bindGetRuntimeManagedVpnCredentialRequestV1(request, projection, trustedSession)`
+validates the complete projection digest and binds node, controller, namespace,
+physical-session identity and projection reference. The response binder takes
+`(response, request, projection, trustedSession, now)` and additionally requires
+the relay's exact UDP tuple to be selected in `router.platformEndpointIds`.
+Expiry must be after the caller-qualified time and no later than the referenced
+projection's DNS lease; acceptance before that lease starts rejects.
+
+These helpers perform content validation. Callers authenticate and fence the
+current physical peer and projection before and after native work, qualify time
+independently, and retain ownership through revocation and shutdown. The native
+Noise implementation owns cryptographic validation and authentication. Credential
+delivery does not prove a connected VPN, TUN ownership, packet enforcement or
+workload readiness, and does not replace explicit packet withdrawals.
+
 ### Node-Bound Runtime Assignments
 
 The `data` namespace exports `IRuntimeAssignmentV1`, canonical digest helpers,
@@ -1192,6 +1217,17 @@ may continue its next configured resolver. Consumers must apply
 `data.normalizeCoreMailRecipientResolutions()` against the exact requested
 recipient set before acting on a peer response.
 
+CoreMail binds every issued routing handle to a digest of the exact normalized
+`envelope` and `source` sent at resolve time. A following
+`coreMailGatewayPrepareInboundHandoff` must resend byte-identical values,
+including the complete `rcptTo` set in the same order. Both peers use
+`data.normalizeCoreMailGatewayMessage` and
+`data.normalizeCoreMailConnectionInfo` so the digested bytes come from one
+shared implementation. Outbound status is monotonic per `transportMessageId`,
+and a permanently unknown `transportMessageId` is answered with a terminal
+`failed` status rather than an error, because CoreMail retries errors
+indefinitely.
+
 Large content never travels inside TypedRequest JSON. Outbound body parts and
 attachments use prepare/upload/complete operations with short-lived one-time
 HTTP transfer grants. Inbound delivery uses bounded delivery listing followed
@@ -1220,6 +1256,23 @@ credential-lifecycle inconsistencies. CoreMail credential verifiers use the
 versioned `argon2id-v1` format and the exact policy exported as
 `data.coreMailCredentialVerifierPolicy`.
 
+`data.ICoreMailDesiredState.smtp` is the optional CoreMail SMTP submission
+listener (MSA). It carries the listener port, the advertised EHLO hostname, and
+the runtime secret keys holding certificate and private-key PEM text; plaintext
+PEM material never appears in desired state. SMTP AUTH uses the binding
+identity directly: the username is the `bindingId` and the password is any
+current or retiring credential secret of that binding. The listener stays
+unavailable until the referenced PEM material resolves. Omitting `smtp` keeps
+the exact canonical bytes and digest of an API-only CoreMail. Accepted
+submissions report their entry point through the optional
+`ICoreMailSubmission.source`, either `api` or `smtp`.
+
+`data.ICoreMailServiceMailStatistics` reports per-service outbound and inbound
+counters for one UTC calendar day. Control sessions read them through
+`coreMailGetServiceMailStatistics` using an inclusive day range, an optional
+service filter, and an opaque cursor. Apply
+`data.normalizeCoreMailServiceMailStatistics` before using reported counters.
+
 `data.ICoreMailControlBootstrap` is installed before ordinary reconciliation.
 It contains the CoreMail service identity and verifier metadata only. The
 matching plaintext control credential is delivered exclusively to Coreflow
@@ -1244,7 +1297,13 @@ CoreMail transfer origin associated with an authenticated CoreMail service.
 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.
+authoritative views before handing over a path-only transfer grant. Cloudly and
+Onebox provision that peer state through `listCoreMailGatewayPeers`,
+`syncCoreMailGatewayPeer`, and `deleteCoreMailGatewayPeer` on the gateway-client
+mail surface, and the producer is the single owner of `peer.transferOrigin`. A
+mail inbound target may point at a CoreMail service using `type: 'coreMail'`
+with `coreMail.coreMailServiceId`, mirrored by the `coreMail` member of
+`IServiceMailInboundConfig.targetType`.
 
 Inbound delivery pagination uses an opaque CoreMail-owned `cursor`, is bounded
 by `data.coreMailLimits.inboundPageSize`, and returns `nextCursor` only when

package/ts/00_commitinfo_data.ts

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