@serve.zone/interfaces 30.11.0 → 30.13.0

package/ts/data/coremail.runtime.ts

@@ -20,17 +20,22 @@ import {
   type ICoreMailEnvelope,
   type ICoreMailErrorData,
   type ICoreMailGatewayDesiredState,
+  type ICoreMailGatewayMessageDescriptor,
   type ICoreMailGatewayOutboundStatus,
   type ICoreMailGatewayPeerDesiredState,
   type ICoreMailInboundDelivery,
   type ICoreMailInboundDeliveryPage,
+  type ICoreMailInboundMailCounters,
   type ICoreMailMailbox,
+  type ICoreMailOutboundMailCounters,
   type ICoreMailOutboundMessageDescriptor,
   type ICoreMailPartStatus,
   type ICoreMailRecipientResolution,
   type ICoreMailRuntimeKeyReference,
   type ICoreMailReconciliationStatus,
   type ICoreMailReplicaIdentity,
+  type ICoreMailServiceMailStatistics,
+  type ICoreMailSmtpDesiredState,
   type ICoreMailSubmission,
   type ICoreMailTransferGrant,
   type ICoreMailUploadGrant,
@@ -38,8 +43,10 @@ import {
   type TCoreMailBindingState,
   type TCoreMailErrorCode,
   type TCoreMailSha256,
+  type TCoreMailSubmissionSource,
   type TCoreMailWorkloadOperation,
 } from './coremail.js';
+import type { IMailConnectionInfo } from './mail.js';
 
 export const coreMailCanonicalJsonRules = strictCanonicalJsonRules;
 
@@ -79,6 +86,7 @@ export const coreMailContractLimits = Object.freeze({
   maximumContentIdBytes: 256,
   maximumBearerTokenBytes: 1_024,
   maximumRecipientResolutionMessageBytes: 512,
+  maximumConnectionInfoFieldBytes: 512,
 } as const);
 
 export class CoreMailContractError extends Error {
@@ -533,6 +541,24 @@ const requireCanonicalMailbox = (valueArg: unknown, pathArg: string): string =>
   return value;
 };
 
+const requireCanonicalHostname = (valueArg: unknown, pathArg: string): string => {
+  const value = requireString(
+    valueArg,
+    pathArg,
+    coreMailContractLimits.maximumMailboxBytes,
+  );
+  const labels = value.split('.');
+  if (
+    value !== value.toLowerCase()
+    || value.length > 253
+    || labels.length < 2
+    || labels.some((labelArg) => !mailboxDomainLabelRegex.test(labelArg))
+  ) {
+    fail(`${pathArg} must be a canonical lowercase hostname`);
+  }
+  return value;
+};
+
 const normalizeMailbox = (valueArg: unknown, pathArg: string): ICoreMailMailbox => {
   const record = readRecord(valueArg, pathArg);
   assertKeys(record, pathArg, ['address'], ['displayName']);
@@ -1157,6 +1183,7 @@ export const normalizeCoreMailSubmission = (
     ],
     [
       'transportMessageId',
+      'source',
       'nextAttemptAt',
       'error',
       'acceptedAt',
@@ -1209,6 +1236,12 @@ export const normalizeCoreMailSubmission = (
       `${pathArg}.transportMessageId`,
     );
   }
+  if (Object.hasOwn(record, 'source')) {
+    if (record.source !== 'api' && record.source !== 'smtp') {
+      fail(`${pathArg}.source must be api or smtp`);
+    }
+    normalized.source = record.source as TCoreMailSubmissionSource;
+  }
   if (Object.hasOwn(record, 'error')) {
     normalized.error = normalizeCoreMailErrorData(record.error, `${pathArg}.error`);
   }
@@ -1698,6 +1731,38 @@ const normalizeGateway = (
   };
 };
 
+const normalizeSmtpDesiredState = (
+  valueArg: unknown,
+  pathArg: string,
+): ICoreMailSmtpDesiredState => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(record, pathArg, ['enabled', 'port', 'hostname', 'tls']);
+  if (typeof record.enabled !== 'boolean') {
+    fail(`${pathArg}.enabled must be boolean`);
+  }
+  const tlsRecord = readRecord(record.tls, `${pathArg}.tls`);
+  assertKeys(
+    tlsRecord,
+    `${pathArg}.tls`,
+    ['certificatePemSecretKey', 'privateKeyPemSecretKey'],
+  );
+  return {
+    enabled: record.enabled as boolean,
+    port: requireSafeInteger(record.port, `${pathArg}.port`, 1, 65_535),
+    hostname: requireCanonicalHostname(record.hostname, `${pathArg}.hostname`),
+    tls: {
+      certificatePemSecretKey: requireEnvironmentKey(
+        tlsRecord.certificatePemSecretKey,
+        `${pathArg}.tls.certificatePemSecretKey`,
+      ),
+      privateKeyPemSecretKey: requireEnvironmentKey(
+        tlsRecord.privateKeyPemSecretKey,
+        `${pathArg}.tls.privateKeyPemSecretKey`,
+      ),
+    },
+  };
+};
+
 export const normalizeCoreMailDesiredState = (
   valueArg: unknown,
 ): ICoreMailDesiredState => {
@@ -1706,6 +1771,7 @@ export const normalizeCoreMailDesiredState = (
     record,
     'desiredState',
     ['schemaVersion', 'configEpoch', 'bindings', 'gateway', 'cursorKeys'],
+    ['smtp'],
   );
   if (record.schemaVersion !== 2) {
     fail('desiredState.schemaVersion must be 2');
@@ -1736,13 +1802,17 @@ export const normalizeCoreMailDesiredState = (
   bindings.sort((leftArg, rightArg) =>
     compareStrings(leftArg.bindingId, rightArg.bindingId),
   );
-  return deepFreezeValue({
+  const normalized: ICoreMailDesiredState = {
     schemaVersion: 2,
     configEpoch: requireSafeInteger(record.configEpoch, 'desiredState.configEpoch', 1),
     bindings,
     gateway: normalizeGateway(record.gateway, 'desiredState.gateway'),
     cursorKeys: normalizeRuntimeKeySet(record.cursorKeys, 'desiredState.cursorKeys'),
-  });
+  };
+  if (Object.hasOwn(record, 'smtp')) {
+    normalized.smtp = normalizeSmtpDesiredState(record.smtp, 'desiredState.smtp');
+  }
+  return deepFreezeValue(normalized);
 };
 
 export const normalizeCoreMailReplicaIdentity = (
@@ -1976,3 +2046,209 @@ export const normalizeCoreMailGatewayPeerDesiredState = (
     ),
   });
 };
+
+const utcCalendarDayRegex = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
+
+const requireUtcCalendarDay = (valueArg: unknown, pathArg: string): string => {
+  const value = requireString(valueArg, pathArg, 10);
+  if (!utcCalendarDayRegex.test(value)) {
+    fail(`${pathArg} must be a canonical YYYY-MM-DD UTC day`);
+  }
+  const [year, month, day] = value.split('-').map(Number);
+  const parsed = new Date(Date.UTC(year, month - 1, day));
+  if (
+    parsed.getUTCFullYear() !== year
+    || parsed.getUTCMonth() + 1 !== month
+    || parsed.getUTCDate() !== day
+  ) {
+    fail(`${pathArg} must be a real UTC calendar day`);
+  }
+  return value;
+};
+
+const normalizeOutboundMailCounters = (
+  valueArg: unknown,
+  pathArg: string,
+): ICoreMailOutboundMailCounters => {
+  const record = readRecord(valueArg, pathArg);
+  const keys = [
+    'submittedApi',
+    'submittedSmtp',
+    'delivered',
+    'deferred',
+    'failed',
+    'deadLettered',
+  ] as const;
+  assertKeys(record, pathArg, [...keys]);
+  const normalized = {} as ICoreMailOutboundMailCounters;
+  for (const key of keys) {
+    normalized[key] = requireSafeInteger(record[key], `${pathArg}.${key}`, 0);
+  }
+  return normalized;
+};
+
+const normalizeInboundMailCounters = (
+  valueArg: unknown,
+  pathArg: string,
+): ICoreMailInboundMailCounters => {
+  const record = readRecord(valueArg, pathArg);
+  const keys = [
+    'received',
+    'acknowledgedProcessed',
+    'acknowledgedDiscarded',
+  ] as const;
+  assertKeys(record, pathArg, [...keys]);
+  const normalized = {} as ICoreMailInboundMailCounters;
+  for (const key of keys) {
+    normalized[key] = requireSafeInteger(record[key], `${pathArg}.${key}`, 0);
+  }
+  return normalized;
+};
+
+export const normalizeCoreMailServiceMailStatistics = (
+  valueArg: unknown,
+  pathArg = 'serviceMailStatistics',
+): ICoreMailServiceMailStatistics => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    [
+      'tenantId',
+      'serviceId',
+      'bindingId',
+      'dayUtc',
+      'outbound',
+      'inbound',
+      'updatedAt',
+    ],
+  );
+  return deepFreezeValue({
+    tenantId: requireIdentifier(record.tenantId, `${pathArg}.tenantId`),
+    serviceId: requireIdentifier(record.serviceId, `${pathArg}.serviceId`),
+    bindingId: requireIdentifier(record.bindingId, `${pathArg}.bindingId`),
+    dayUtc: requireUtcCalendarDay(record.dayUtc, `${pathArg}.dayUtc`),
+    outbound: normalizeOutboundMailCounters(record.outbound, `${pathArg}.outbound`),
+    inbound: normalizeInboundMailCounters(record.inbound, `${pathArg}.inbound`),
+    updatedAt: requireSafeInteger(record.updatedAt, `${pathArg}.updatedAt`, 1),
+  });
+};
+
+/**
+ * Strict gateway message descriptor normalization.
+ *
+ * CoreMail digests the normalized envelope together with the normalized
+ * connection source, so the emitted field set and order is part of the
+ * contract and must not change.
+ */
+export const normalizeCoreMailGatewayMessage = (
+  valueArg: unknown,
+  pathArg = 'gatewayMessage',
+): ICoreMailGatewayMessageDescriptor => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(record, pathArg, ['envelope', 'rawMime']);
+  const rawMime = readRecord(record.rawMime, `${pathArg}.rawMime`);
+  assertKeys(rawMime, `${pathArg}.rawMime`, ['sha256', 'lengthBytes', 'contentType']);
+  if (rawMime.contentType !== 'message/rfc822') {
+    fail(`${pathArg}.rawMime.contentType must be message/rfc822`);
+  }
+  const normalized: ICoreMailGatewayMessageDescriptor = {
+    envelope: normalizeCoreMailEnvelope(record.envelope, `${pathArg}.envelope`),
+    rawMime: {
+      sha256: normalizeCoreMailSha256(rawMime.sha256, `${pathArg}.rawMime.sha256`),
+      lengthBytes: requireSafeInteger(
+        rawMime.lengthBytes,
+        `${pathArg}.rawMime.lengthBytes`,
+        1,
+        coreMailLimits.serializedMimeBytes,
+      ),
+      contentType: 'message/rfc822',
+    },
+  };
+  return deepFreezeValue(normalized);
+};
+
+const requireConnectionInfoField = (valueArg: unknown, pathArg: string): string => {
+  const value = requireString(
+    valueArg,
+    pathArg,
+    coreMailContractLimits.maximumConnectionInfoFieldBytes,
+  );
+  if (value.trim() !== value) {
+    fail(`${pathArg} must not carry leading or trailing whitespace`);
+  }
+  return value;
+};
+
+/**
+ * Strict connection-source normalization for gateway resolve and handoff
+ * requests. CoreMail binds routing handles to a digest of the normalized
+ * envelope and this normalized source, so the emitted field set and order is
+ * part of the contract and must not change.
+ */
+export const normalizeCoreMailConnectionInfo = (
+  valueArg: unknown,
+  pathArg = 'connectionInfo',
+): IMailConnectionInfo => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    ['protocol'],
+    [
+      'remoteAddress',
+      'proxyAddress',
+      'heloName',
+      'tls',
+      'authUsername',
+      'authenticatedCredentialId',
+    ],
+  );
+  if (
+    record.protocol !== 'smtp'
+    && record.protocol !== 'submission'
+    && record.protocol !== 'api'
+  ) {
+    fail(`${pathArg}.protocol must be smtp, submission, or api`);
+  }
+  const normalized: IMailConnectionInfo = {
+    protocol: record.protocol as IMailConnectionInfo['protocol'],
+  };
+  if (record.remoteAddress !== undefined) {
+    normalized.remoteAddress = requireConnectionInfoField(
+      record.remoteAddress,
+      `${pathArg}.remoteAddress`,
+    );
+  }
+  if (record.proxyAddress !== undefined) {
+    normalized.proxyAddress = requireConnectionInfoField(
+      record.proxyAddress,
+      `${pathArg}.proxyAddress`,
+    );
+  }
+  if (record.heloName !== undefined) {
+    normalized.heloName = requireConnectionInfoField(
+      record.heloName,
+      `${pathArg}.heloName`,
+    );
+  }
+  if (record.tls !== undefined) {
+    if (typeof record.tls !== 'boolean') {
+      fail(`${pathArg}.tls must be boolean`);
+    }
+    normalized.tls = record.tls as boolean;
+  }
+  if (record.authUsername !== undefined) {
+    normalized.authUsername = requireConnectionInfoField(
+      record.authUsername,
+      `${pathArg}.authUsername`,
+    );
+  }
+  if (record.authenticatedCredentialId !== undefined) {
+    normalized.authenticatedCredentialId = requireConnectionInfoField(
+      record.authenticatedCredentialId,
+      `${pathArg}.authenticatedCredentialId`,
+    );
+  }
+  return deepFreezeValue(normalized);
+};

package/ts/data/coremail.ts

@@ -26,6 +26,11 @@ export type TCoreMailSubmissionState =
   | 'deferred'
   | 'failed'
   | 'deadLettered';
+/**
+ * Entry point that produced an outbound submission. `api` is the authenticated
+ * workload TypedRequest surface, `smtp` is the CoreMail submission listener.
+ */
+export type TCoreMailSubmissionSource = 'api' | 'smtp';
 export type TCoreMailInboundDeliveryState = 'pending' | 'fetching' | 'fetched' | 'acknowledged';
 export type TCoreMailInboundAckOutcome = 'processed' | 'discarded';
 export type TCoreMailRecipientAction = 'accept' | 'reject' | 'defer' | 'unhandled';
@@ -149,6 +154,8 @@ export interface ICoreMailSubmission {
   idempotencyKey: string;
   submissionDigest: TCoreMailSha256;
   state: TCoreMailSubmissionState;
+  /** Entry point that produced this submission. Omitted means an API submission. */
+  source?: TCoreMailSubmissionSource;
   parts: ICoreMailPartStatus[];
   transportMessageId?: string;
   attempts: number;
@@ -255,11 +262,38 @@ export interface ICoreMailRuntimeKeyReference {
   acceptUntil?: number;
 }
 
+export interface ICoreMailSmtpTlsDesiredState {
+  /** Keys in CoreMail's resolved runtime secret material holding PEM text, never plaintext values. */
+  certificatePemSecretKey: string;
+  privateKeyPemSecretKey: string;
+}
+
+/**
+ * Desired state for CoreMail's own SMTP submission listener (MSA).
+ *
+ * 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, so credential rotation windows behave exactly as they do for
+ * the workload TypedRequest surface. The listener stays unavailable until the
+ * referenced PEM material resolves; an enabled listener without resolvable
+ * certificate and private key material never accepts submissions.
+ */
+export interface ICoreMailSmtpDesiredState {
+  enabled: boolean;
+  /** Listener port inside the CoreMail workload. */
+  port: number;
+  /** Advertised EHLO hostname. */
+  hostname: string;
+  tls: ICoreMailSmtpTlsDesiredState;
+}
+
 export interface ICoreMailDesiredState {
   schemaVersion: 2;
   configEpoch: number;
   bindings: ICoreMailBindingDesiredState[];
   gateway: ICoreMailGatewayDesiredState;
+  /** Optional SMTP submission listener. An omitted listener keeps the API-only surface. */
+  smtp?: ICoreMailSmtpDesiredState;
   cursorKeys: ICoreMailRuntimeKeyReference[];
 }
 
@@ -293,6 +327,36 @@ export interface ICoreMailReconciliationStatus {
   errorCode?: TCoreMailErrorCode;
 }
 
+export interface ICoreMailOutboundMailCounters {
+  submittedApi: number;
+  submittedSmtp: number;
+  delivered: number;
+  deferred: number;
+  failed: number;
+  deadLettered: number;
+}
+
+export interface ICoreMailInboundMailCounters {
+  received: number;
+  acknowledgedProcessed: number;
+  acknowledgedDiscarded: number;
+}
+
+/**
+ * Per-service mail counters for one UTC calendar day, reported over the
+ * authenticated CoreMail control session.
+ */
+export interface ICoreMailServiceMailStatistics {
+  tenantId: string;
+  serviceId: string;
+  bindingId: string;
+  /** UTC calendar day, `YYYY-MM-DD`. */
+  dayUtc: string;
+  outbound: ICoreMailOutboundMailCounters;
+  inbound: ICoreMailInboundMailCounters;
+  updatedAt: number;
+}
+
 export interface ICoreMailRecipientResolution {
   recipient: string;
   action: TCoreMailRecipientAction;
@@ -311,6 +375,14 @@ export interface ICoreMailGatewayMessageDescriptor {
   };
 }
 
+/**
+ * dcrouter-reported delivery status for one accepted transport message.
+ *
+ * `updatedAt` must be monotonic per `transportMessageId`. A
+ * `transportMessageId` the gateway can never recognize again must be reported
+ * as a terminal `failed` status instead of an error, because CoreMail retries
+ * errors indefinitely.
+ */
 export interface ICoreMailGatewayOutboundStatus {
   transportMessageId: string;
   state: Extract<

package/ts/data/index.ts

@@ -23,6 +23,7 @@ export * from './mail.js';
 export * from './nodecredential.js';
 export * from './nodeenrollment.js';
 export * from './networkauthority.js';
+export * from './networkcredential.js';
 export * from './networkdelivery.js';
 export * from './networkprojection.js';
 export type { IRuntimeNetworkRouterPacketGrantV1, IRuntimeNetworkRouterProjectionV1 } from './networkrouter.js';

package/ts/data/mail.ts

@@ -2,7 +2,13 @@ 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';
 
@@ -50,9 +56,26 @@ export type TMailDeliveryJournalEventType =
   | 'bounced'
   | 'complaint';
 
+/**
+ * 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';
+  | '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
@@ -94,11 +117,17 @@ export interface IMailTypedEndpointTarget {
   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;
@@ -231,8 +260,11 @@ 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/ts/data/networkcredential.ts

@@ -0,0 +1,88 @@
+import type { IRuntimeAuthorityReferenceV1 } from './runtimeassignment.js';
+import { snapshotRuntimeSessionBindingV1, type IRuntimeSessionBindingV1 } from './runtimesession.js';
+import { validateRuntimeNetworkProjectionV1, type IRuntimeNetworkProjectionV1 } from './networkprojection.js';
+import { captureNetwork, failNetwork, networkCounter, networkEqual, networkId, networkIpv4,
+  networkRecord, networkReference, networkReferenceOf, networkSafe, requireNetwork } from '../private/networkcontract.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;
+}
+
+/** 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: unknown): string => {
+  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: unknown): IGetRuntimeManagedVpnCredentialRequestV1 => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['session', 'projection']);
+  return { session: snapshotRuntimeSessionBindingV1(item.session), projection: networkReference(item.projection) };
+});
+
+export const snapshotGetRuntimeManagedVpnCredentialResponseV1 = (value: unknown): IGetRuntimeManagedVpnCredentialResponseV1 => 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: IGetRuntimeManagedVpnCredentialRequestV1,
+  projection: IRuntimeNetworkProjectionV1, trusted: IRuntimeSessionBindingV1): void => {
+  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: unknown, projectionValue: unknown,
+  trustedSessionValue: unknown): Promise<IGetRuntimeManagedVpnCredentialRequestV1> => {
+  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: unknown, requestValue: unknown,
+  projectionValue: unknown, trustedSessionValue: unknown, nowValue: unknown): Promise<IGetRuntimeManagedVpnCredentialResponseV1> => {
+  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(); }
+};