@serve.zone/interfaces 23.0.3 → 23.1.0

package/readme.md

@@ -67,6 +67,46 @@ Primary v23 additions include:
 - Mandatory `IImmutableContainerInvocationV1` evidence on immutable image
   deployment plans.
 
+### Secrets v23.1 Runtime Registration And Reporting
+
+The Node-only `@serve.zone/interfaces/runtime` export adds the live contract
+that Cloudly must validate before publishing secret-bearing desired state to a
+Coreflow connection:
+
+- `getSecretRecipientEnrollmentState` returns either an exact generation-zero
+  empty state or the complete valid recipient set for the cluster derived from
+  the verified JWT.
+- `ICoreflowSecretRuntimeRegistrationV1` binds a reporter session to the exact
+  authoritative schedulable target-node set, required secret capabilities,
+  active recipient, approved WorkloadInit OCI index, and exact per-platform
+  manifest and installed-executable digests.
+- `validateCoreflowSecretRuntimeRegistration` compares the registration with a
+  trusted expectation built by Cloudly, including the live reporter session.
+  Missing, extra, duplicate, reordered, or mismatched node evidence fails
+  closed. Consumers must discard the registration on transport disconnect, tag
+  removal or replacement, or any live session, placement, artifact, or
+  recipient expectation change before publishing more secret-bearing state.
+- `reportSecretDeploymentState` reports only `applying`, `applied`, `drifted`,
+  or `failed` for the manifest and plan revision selected by Cloudly. The
+  validator receives the trusted cluster ID after JWT verification and the
+  trusted live reporter session. Wire-provided manifest scope is checked
+  against, and never replaces, that trusted authority.
+
+The package validates report shape, digest, trusted cluster, and trusted live
+session; it does not persist replay state or mutate deployment plans. Deployment
+report consumers must persist an atomic receipt keyed by the verified cluster,
+reporter session, service, and positive sequence. The report digest uses
+fixed-order JSON and excludes only the JWT identity and `reportDigest`. The
+consumer accepts the exact next sequence once, returns the prior response for a
+same-digest replay, rejects a different-digest replay, and ensures a plan
+revision CAS failure consumes neither the sequence nor a receipt. Timestamps
+are informational and never replace live session, placement, artifact,
+recipient, sequence, or plan-revision fences.
+
+`createWorkloadInitEnvironmentMap` now rejects manifests without any
+`launcher-environment` delivery. Consumers must bypass WorkloadInit for
+file-only manifests.
+
 ## Portable Storage Contracts
 
 App Store templates can declare logical, template-local `storageClasses` and
@@ -547,6 +587,13 @@ the exact `allowedOperations` derived from
 `data.coreMailWorkloadOperationPolicy`. Disabled bindings never authenticate;
 draining bindings permit outbound status plus inbound list/fetch/ack only.
 
+Gateway recipient resolution uses four strict outcomes. `accept`, `defer`, and
+`reject` are authoritative only for recipients owned by an active binding.
+`unhandled` means the CoreMail peer does not own that recipient, so the gateway
+may continue its next configured resolver. Consumers must apply
+`data.normalizeCoreMailRecipientResolutions()` against the exact requested
+recipient set before acting on a peer response.
+
 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

package/ts/00_commitinfo_data.ts

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

package/ts/data/coremail.runtime.ts

@@ -27,6 +27,7 @@ import {
   type ICoreMailMailbox,
   type ICoreMailOutboundMessageDescriptor,
   type ICoreMailPartStatus,
+  type ICoreMailRecipientResolution,
   type ICoreMailRuntimeKeyReference,
   type ICoreMailReconciliationStatus,
   type ICoreMailReplicaIdentity,
@@ -77,6 +78,7 @@ export const coreMailContractLimits = Object.freeze({
   maximumFilenameBytes: 512,
   maximumContentIdBytes: 256,
   maximumBearerTokenBytes: 1_024,
+  maximumRecipientResolutionMessageBytes: 512,
 } as const);
 
 export class CoreMailContractError extends Error {
@@ -587,6 +589,139 @@ export const normalizeCoreMailEnvelope = (
   return deepFreezeValue({ mailFrom, rcptTo });
 };
 
+const requireCoreMailOpaqueToken = (valueArg: unknown, pathArg: string): string => {
+  const value = requireString(
+    valueArg,
+    pathArg,
+    coreMailContractLimits.maximumBearerTokenBytes,
+  );
+  let decodedValue: string;
+  try {
+    decodedValue = globalThis.atob(
+      `${value.replace(/-/g, '+').replace(/_/g, '/')}${'='.repeat((4 - (value.length % 4)) % 4)}`,
+    );
+  } catch {
+    return fail(`${pathArg} must use ${coreMailTransferTokenPolicy.format}`);
+  }
+  const canonicalValue = globalThis.btoa(decodedValue)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/u, '');
+  if (
+    decodedValue.length !== coreMailTransferTokenPolicy.decodedBytes
+    || value.length !== coreMailTransferTokenPolicy.encodedCharacters
+    || canonicalValue !== value
+  ) {
+    fail(`${pathArg} must use ${coreMailTransferTokenPolicy.format}`);
+  }
+  return value;
+};
+
+export const normalizeCoreMailRecipientResolution = (
+  valueArg: unknown,
+  pathArg = 'recipientResolution',
+): ICoreMailRecipientResolution => {
+  const record = readRecord(valueArg, pathArg);
+  const actionDescriptor = Object.getOwnPropertyDescriptor(record, 'action');
+  if (
+    !actionDescriptor
+    || !actionDescriptor.enumerable
+    || !Object.hasOwn(actionDescriptor, 'value')
+  ) {
+    return fail(`${pathArg}.action must be an enumerable data property`);
+  }
+  const action = actionDescriptor.value;
+  if (action === 'accept') {
+    assertKeys(record, pathArg, ['recipient', 'action', 'routingHandle']);
+    return deepFreezeValue({
+      recipient: requireCanonicalMailbox(record.recipient, `${pathArg}.recipient`),
+      action,
+      routingHandle: requireCoreMailOpaqueToken(
+        record.routingHandle,
+        `${pathArg}.routingHandle`,
+      ),
+    });
+  }
+  if (action === 'reject' || action === 'defer') {
+    assertKeys(record, pathArg, ['recipient', 'action', 'smtpCode', 'message']);
+    const minimumCode = action === 'reject' ? 500 : 400;
+    const maximumCode = action === 'reject' ? 599 : 499;
+    return deepFreezeValue({
+      recipient: requireCanonicalMailbox(record.recipient, `${pathArg}.recipient`),
+      action,
+      smtpCode: requireSafeInteger(
+        record.smtpCode,
+        `${pathArg}.smtpCode`,
+        minimumCode,
+        maximumCode,
+      ),
+      message: requireDisplayText(
+        record.message,
+        `${pathArg}.message`,
+        coreMailContractLimits.maximumRecipientResolutionMessageBytes,
+      ),
+    });
+  }
+  if (action === 'unhandled') {
+    assertKeys(record, pathArg, ['recipient', 'action']);
+    return deepFreezeValue({
+      recipient: requireCanonicalMailbox(record.recipient, `${pathArg}.recipient`),
+      action,
+    });
+  }
+  return fail(`${pathArg}.action must be accept, reject, defer, or unhandled`);
+};
+
+export const normalizeCoreMailRecipientResolutions = (
+  valueArg: unknown,
+  expectedRecipientsArg: readonly string[],
+  pathArg = 'recipientResolutions',
+): readonly ICoreMailRecipientResolution[] => {
+  const expectedRecipients = readArray(
+    expectedRecipientsArg,
+    `${pathArg}.expectedRecipients`,
+    coreMailLimits.recipientCount,
+  ).map((recipientArg, indexArg) =>
+    requireCanonicalMailbox(
+      recipientArg,
+      `${pathArg}.expectedRecipients[${indexArg}]`,
+    ),
+  );
+  if (
+    expectedRecipients.length === 0
+    || new Set(expectedRecipients).size !== expectedRecipients.length
+  ) {
+    fail(`${pathArg}.expectedRecipients must contain unique recipients`);
+  }
+  const resolutions = readArray(
+    valueArg,
+    pathArg,
+    coreMailLimits.recipientCount,
+  ).map((resolutionArg, indexArg) =>
+    normalizeCoreMailRecipientResolution(resolutionArg, `${pathArg}[${indexArg}]`),
+  );
+  const byRecipient = new Map<string, ICoreMailRecipientResolution>();
+  for (const resolution of resolutions) {
+    if (byRecipient.has(resolution.recipient)) {
+      fail(`${pathArg} contains a duplicate recipient resolution`);
+    }
+    byRecipient.set(resolution.recipient, resolution);
+  }
+  if (
+    resolutions.length !== expectedRecipients.length
+    || resolutions.some((resolutionArg) => !expectedRecipients.includes(resolutionArg.recipient))
+  ) {
+    fail(`${pathArg} must resolve the exact expected recipient set`);
+  }
+  return deepFreezeValue(expectedRecipients.map((recipientArg) => {
+    const resolution = byRecipient.get(recipientArg);
+    if (!resolution) {
+      return fail(`${pathArg} is missing a recipient resolution`);
+    }
+    return { ...resolution };
+  }));
+};
+
 const forbiddenHeaderNames = new Set([
   'bcc',
   'cc',
@@ -864,30 +999,10 @@ export const normalizeCoreMailTransferGrant = (
   if (path !== `${coreMailTransferProtocol.pathPrefix}${grantId}`) {
     fail(`${pathArg}.path must match its grantId`);
   }
-  const bearerToken = requireString(
+  const bearerToken = requireCoreMailOpaqueToken(
     record.bearerToken,
     `${pathArg}.bearerToken`,
-    coreMailContractLimits.maximumBearerTokenBytes,
   );
-  let decodedToken: string;
-  try {
-    decodedToken = globalThis.atob(
-      `${bearerToken.replace(/-/g, '+').replace(/_/g, '/')}${'='.repeat((4 - (bearerToken.length % 4)) % 4)}`,
-    );
-  } catch {
-    return fail(`${pathArg}.bearerToken must use ${coreMailTransferTokenPolicy.format}`);
-  }
-  const canonicalToken = globalThis.btoa(decodedToken)
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=+$/u, '');
-  if (
-    decodedToken.length !== coreMailTransferTokenPolicy.decodedBytes
-    || bearerToken.length !== coreMailTransferTokenPolicy.encodedCharacters
-    || canonicalToken !== bearerToken
-  ) {
-    fail(`${pathArg}.bearerToken must use ${coreMailTransferTokenPolicy.format}`);
-  }
   const issuedAt = requireSafeInteger(record.issuedAt, `${pathArg}.issuedAt`, 1);
   const expiresAt = requireSafeInteger(record.expiresAt, `${pathArg}.expiresAt`, 1);
   if (expiresAt - issuedAt !== coreMailLimits.transferGrantTtlMs) {

package/ts/data/coremail.ts

@@ -28,7 +28,7 @@ export type TCoreMailSubmissionState =
   | 'deadLettered';
 export type TCoreMailInboundDeliveryState = 'pending' | 'fetching' | 'fetched' | 'acknowledged';
 export type TCoreMailInboundAckOutcome = 'processed' | 'discarded';
-export type TCoreMailRecipientAction = 'accept' | 'reject' | 'defer';
+export type TCoreMailRecipientAction = 'accept' | 'reject' | 'defer' | 'unhandled';
 export type TCoreMailReconciliationState = 'applying' | 'ready' | 'failed';
 export type TCoreMailWorkloadOperation =
   | 'coreMailPrepareOutboundSubmission'

package/ts/data/immutableimage.ts

@@ -71,6 +71,8 @@ export interface ICoreflowRuntimeCapabilities {
   sealedSecretMaterialVersion: 1;
   secretRecipientEnrollmentVersion: 1;
   workloadInitEnvironmentVersion: 1;
+  /** Coreflow can submit replay-safe schema-v1 secret deployment reports. */
+  secretDeploymentReportVersion?: 1;
 }
 
 export type TImmutableContainerPlatform = 'linux/amd64' | 'linux/arm64';

package/ts/data/secret.ts

@@ -922,7 +922,7 @@ export const validateResolvedSecretManifest = (
   return errors;
 };
 
-const validateResolvedSecretManifestReference = (
+const validateResolvedSecretManifestReferenceAtPath = (
   referenceArg: unknown,
   expectedClusterIdArg: string,
   pathArg: string,
@@ -958,6 +958,25 @@ const validateResolvedSecretManifestReference = (
   return [];
 };
 
+/** Strict public validator for a cluster-scoped resolved manifest reference. */
+export const validateResolvedSecretManifestReference = (
+  referenceArg: unknown,
+  expectedClusterIdArg: string,
+): string[] => {
+  try {
+    if (!isSecretIdentifier(expectedClusterIdArg)) {
+      return ['expected cluster id must be canonical'];
+    }
+    return validateResolvedSecretManifestReferenceAtPath(
+      referenceArg,
+      expectedClusterIdArg,
+      'resolved secret manifest reference',
+    );
+  } catch {
+    return ['resolved secret manifest reference must be safely inspectable'];
+  }
+};
+
 export const validateServiceSecretDeploymentPlan = (
   planArg: unknown,
   expectedTargetClusterIdsArg?: string[],
@@ -992,7 +1011,7 @@ export const validateServiceSecretDeploymentPlan = (
     expectedClusterIdArg: string,
     pathArg: string,
   ): void => {
-    const referenceErrors = validateResolvedSecretManifestReference(
+    const referenceErrors = validateResolvedSecretManifestReferenceAtPath(
       referenceArg,
       expectedClusterIdArg,
       pathArg,
@@ -1183,6 +1202,9 @@ export const createWorkloadInitEnvironmentMap = async (
         source: createLauncherSecretSourcePath(resource),
       };
     }));
+  if (entries.length === 0) {
+    throw new Error('workload init map requires at least one launcher-environment delivery');
+  }
   entries.sort((leftArg, rightArg) => (
     leftArg.variableName < rightArg.variableName
       ? -1