@serve.zone/interfaces 19.8.0 → 20.1.0

package/readme.md

@@ -120,6 +120,130 @@ must reject unknown manifest fields and unsupported required feature IDs before
 provisioning. Legacy `volumes` and `platformRequirements.s3` remain deprecated
 inputs for strict resolver normalization only.
 
+`platform.storagemigration` defines the provider-neutral cutover contract for a
+named object-storage binding. Corestore atomically owns and fences the source
+binding after validating a distinct, unfenced active-object snapshot. Onebox
+only receives a held candidate, stages that exact candidate, stops the matching
+workload generation, and attests the quiesced state. The candidate cannot start
+until `destinationBindingStartAuthorized` is true. Corestore continues returning
+`consumerAction: 'startDestination'` until Onebox submits the mutation-fenced
+consumer activation request and the acknowledgement becomes durable evidence.
+Candidate-issued abort tombstones authorize only `startSource` and never retain
+the staged candidate binding.
+
+Every migration DTO and status has an exact, versioned runtime normalizer.
+Unknown fields, provider or pool identifiers, unbounded strings, unsafe
+integers, stale mutation revisions, identity drift, and lifecycle-inconsistent
+fields are rejected. Migration-created digests use strict canonical JSON and a
+bare lowercase 64-hex SHA-256 value; portable golden vectors cover the source
+snapshot, target request, prepare intent, and candidate binding. Pre-cutover
+failures may retry or abort; after the durable commit point, recovery can only
+retry or roll forward. Physical pool IDs, mount details, provider receipts, and
+publication capabilities remain private.
+
+Primary exports include:
+
+- `IObjectStorageMigrationPrepareRequest` and
+  `TObjectStorageMigrationStatus` for the immutable intent and status journal.
+- `IObjectStorageMigrationConsumerQuiesceRequest` with
+  `IStorageMigrationConsumerQuiesceEvidence` for exact candidate staging and
+  source-workload shutdown.
+- `IObjectStorageMigrationConsumerActivationRequest` with
+  `IStorageMigrationConsumerActivationEvidence` for durable destination-start
+  acknowledgement.
+- `normalizeObjectStorageMigrationStatus`,
+  `bindObjectStorageMigrationConsumerQuiesceRequest`, and
+  `bindObjectStorageMigrationConsumerActivationRequest` for strict ingress and
+  current-revision mutation fencing.
+- The `create*Sha256` helpers for source snapshots, prepare intent, target
+  requests, candidate/active bindings, and persisted staging or activation
+  evidence.
+
+The phase and consumer-action progression is exact:
+
+| Phase | `consumerAction` | Destination start authorized |
+| --- | --- | --- |
+| `preparing`, `transferring` | `wait` | No |
+| `awaitingConsumerQuiesce` | `stageCandidateAndStop` | No |
+| `finalizing`, `committing` | `wait` | No |
+| `readyToStart` | `startDestination` | Yes |
+| `cleanupPending`, `complete` | `none` | Yes; durable activation evidence is required |
+| `aborting` | `wait` | No |
+| `aborted` | `startSource` | No; only the active source binding may restart |
+
+Normalize every status before acting, and bind consumer mutations to that exact
+status revision:
+
+```typescript
+const status =
+  await platform.storagemigration.normalizeObjectStorageMigrationStatus(
+    untrustedStatusPayload,
+  );
+
+if (status.phase === 'awaitingConsumerQuiesce') {
+  const request =
+    await platform.storagemigration.bindObjectStorageMigrationConsumerQuiesceRequest(
+      untrustedQuiescePayload,
+      status,
+    );
+  await submitQuiesceAcknowledgement(request);
+}
+
+if (status.phase === 'readyToStart') {
+  if (
+    !status.destinationBindingStartAuthorized ||
+    status.consumerAction !== 'startDestination'
+  ) {
+    throw new Error('destination binding is not authorized to start');
+  }
+  await startWorkload(status.activeBinding);
+  const request =
+    await platform.storagemigration.bindObjectStorageMigrationConsumerActivationRequest(
+      untrustedActivationPayload,
+      status,
+    );
+  await submitActivationAcknowledgement(request);
+}
+
+if (status.phase === 'cleanupPending') {
+  // Cleanup is reachable only after this durable acknowledgement was accepted.
+  const durableActivation = status.consumerActivationEvidence;
+}
+
+if (status.phase === 'aborted') {
+  if (
+    status.destinationBindingStartAuthorized ||
+    status.consumerAction !== 'startSource'
+  ) {
+    throw new Error('invalid aborted migration status');
+  }
+  await startWorkload(status.activeBinding);
+}
+```
+
+Here `startWorkload`, `submitQuiesceAcknowledgement`, and
+`submitActivationAcknowledgement` are consumer-owned operations, not package
+exports. Canonical digests are produced from normalized payloads:
+
+```typescript
+const snapshotSha256 =
+  await platform.storagemigration.createUnfencedObjectStorageBindingControlSnapshotSha256(
+    snapshotDigestPayload,
+  );
+const migrationSha256 =
+  await platform.storagemigration.createObjectStorageMigrationSha256(
+    prepareRequest,
+  );
+const candidateSha256 =
+  await platform.storagemigration.createObjectStorageMigrationBindingSha256(
+    candidateBinding,
+  );
+const activationRecordSha256 =
+  await platform.storagemigration.createObjectStorageMigrationPersistedActivationSha256(
+    activationDigestPayload,
+  );
+```
+
 ## Data Contracts
 
 Use `data` when you need object shapes that are persisted, exchanged between services, or exposed through the Cloudly API.
@@ -137,7 +261,6 @@ const service: data.IService = {
     environment: {
       NODE_ENV: 'production',
     },
-    secretBundleId: 'secretbundle-api',
     serviceCategory: 'workload',
     deploymentStrategy: 'limited-replicas',
     scaleFactor: 2,
@@ -186,7 +309,17 @@ Common data contracts include:
 - Service port contracts including `IServiceTargetPort`, `IServiceDomainRoute`, and `IServicePublicPortMapping` for canonical backend targets, domain target references, and edge/Coretraffic TCP/UDP public exposure.
 - `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
 - Traffic and gateway route contracts including `ICoretrafficPortRouteConfig`, routing `portRoutes`, and `IGatewayClientRoute` client-owned route views. Gateway route intent supports optional match `domains`, `transport`, and `remoteIngress`, plus explicit route `priority` and `managedRouteKind`. Ownership can combine `hostname` with `routeRef` so a normal route and a path-specific managed route for the same hostname reconcile independently.
-- `ISecretBundle` and `ISecretGroup` for secret ownership and shared secret groups.
+- Value-free `ISecretMetadata`, `ISecretVersionMetadata`, and `ISecretSetMetadata`
+  contracts for operator views, plus exact-version `IResolvedSecretManifest`
+  contracts for cluster delivery. Manifest helpers enforce canonical shared
+  digests, globally unique environment/file delivery targets, and per-cluster
+  desired/applied/previous-accepted rollout state. `ISecretBundle` and
+  `ISecretGroup` remain legacy compatibility contracts during the versioned
+  migration.
+  `listSecrets` exposes the dedicated `targetSecretsRevision` CAS fence;
+  `createSecret` consumes and returns that fence, while
+  `setServiceSecretSetAttachments` returns the independent
+  `secretConfigurationRevision`. Generic service writes own neither revision.
 - Mail gateway contracts for domain authorities, address bindings, WorkApp bindings, managed SMTP/API credentials, spool items, delivery journals, and inbound/outbound message payloads.
 - Service-level mail configuration through `IService.data.mail`, including per-address inbound `smtpForward` settings and outbound credential metadata. Cloudly settings include dcrouter gateway, SMTP submission, and inbound forward-target keys for reconciling those bindings.
 - Web Push contracts for environment-specific service bindings, public credential state, public VAPID key rotation metadata, privacy-minimal notification signals, and redacted delivery state. Subscription endpoints, browser key material, provider ciphertext, VAPID private keys, and credential secrets are intentionally absent from public binding and status DTOs.
@@ -374,6 +507,7 @@ Request groups are exported by product area:
 - `requests.node`
 - `requests.platform`
 - `requests.routing`
+- `requests.secret`
 - `requests.secretbundle`
 - `requests.secretgroup`
 - `requests.server`
@@ -384,6 +518,30 @@ Request groups are exported by product area:
 - `requests.version`
 - `requests.webpush`
 
+Secret material response contracts are not exported from the universal
+browser-facing entrypoint. Node runtimes import the isolated subpath:
+
+```typescript
+import {
+  verifyResolvedSecretMaterial,
+} from '@serve.zone/interfaces/runtime';
+import type {
+  IReq_GetResolvedSecretMaterial,
+  IResolvedSecretMaterial,
+} from '@serve.zone/interfaces/runtime';
+
+async function acceptMaterial(material: IResolvedSecretMaterial) {
+  if (!await verifyResolvedSecretMaterial(material)) {
+    throw new Error('secret material does not match its immutable manifest');
+  }
+}
+```
+
+Runtime material is shaped as `{ manifest, values }`. The helper verifies the
+canonical manifest digest and exact one-to-one version-ID coverage before
+plaintext use. The runtime must separately compare the verified manifest
+reference and cluster to its request and authenticated deployment scope.
+
 ## Platform Contracts
 
 Use `platform` for current platform-service capabilities and application-facing platform RPCs.
@@ -404,6 +562,8 @@ Available platform modules:
 - `platform.pushnotification` is the deprecated legacy device-token push contract. New browser Web Push integrations use `requests.webpush`.
 - `platform.letter` for physical letter workflows.
 - `platform.ai`, `platform.database`, `platform.objectstorage`, `platform.logging`, `platform.backup`, and `platform.sip` for infrastructure and application capabilities.
+- `platform.storage` for provider-neutral storage classes, requests, capabilities, and resolved bindings.
+- `platform.storagemigration` for fenced object-storage migration intent, status, consumer acknowledgements, canonical digests, and strict normalizers.
 - `platform.types` plus root re-exports for shared capability, provider, binding, credential, and endpoint metadata.
 
 ## Legacy Platformservice Contracts

package/ts/00_commitinfo_data.ts

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

package/ts/data/immutableimage.ts

@@ -66,6 +66,8 @@ export interface ICoreflowRuntimeCapabilities {
   immutableImageDeploymentVersion: 1;
   /** Coreflow can answer the versioned, node-scoped Corestore inventory probe. */
   corestoreInventoryVersion?: 1;
+  /** Coreflow can consume exact, cluster-scoped resolved secret manifests. */
+  secretManifestVersion?: 1;
 }
 
 /**

package/ts/data/index.ts

@@ -19,6 +19,7 @@ export * from './isolatedrestore.js';
 export * from './isolatedrestore.golden.js';
 export * from './mail.js';
 export * from './registry.js';
+export * from './secret.js';
 export * from './secretbundle.js';
 export * from './secretgroup.js';
 export * from './baremetal.js';

package/ts/data/isolatedrestore.ts

@@ -3,6 +3,13 @@ import type {
   IBackupArchiveObject,
   TIsolatedRestoreResourceMapping,
 } from './backup.js';
+import {
+  canonicalizeStrictJson,
+  createCanonicalJsonSha256Hex,
+  createSha256Hex,
+  deepFreezeValue,
+  strictCanonicalJsonRules,
+} from '../private/canonicaljson.js';
 
 /** Operations carried by a short-lived, single-operation restore grant. */
 export const isolatedRestoreGrantOperations = Object.freeze([
@@ -307,15 +314,7 @@ export class IsolatedRestoreContractError extends Error {
 }
 
 /** Cross-runtime rules for restore authority digests. */
-export const isolatedRestoreCanonicalJsonRules = Object.freeze({
-  version: 1 as const,
-  encoding: 'utf-8' as const,
-  objectKeyOrdering: 'utf-16-code-unit-ascending' as const,
-  arrayOrdering: 'preserved-dense' as const,
-  unicodeNormalization: 'preserved' as const,
-  numberEncoding: 'safe-integer-json-no-negative-zero' as const,
-  digest: 'sha256-lowercase-hex' as const,
-});
+export const isolatedRestoreCanonicalJsonRules = strictCanonicalJsonRules;
 
 const canonicalIdentifierPattern = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,255}$/;
 const canonicalScopedIdPattern = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,191}$/;
@@ -360,23 +359,7 @@ export const assertIsolatedRestoreControlIngressByteLength = (
   return byteLengthArg;
 };
 
-const deepFreeze = <T>(valueArg: T, seenArg = new WeakSet<object>()): T => {
-  if (!valueArg || typeof valueArg !== 'object') {
-    return valueArg;
-  }
-  const object = valueArg as object;
-  if (ArrayBuffer.isView(object) || seenArg.has(object)) {
-    return valueArg;
-  }
-  seenArg.add(object);
-  for (const key of Reflect.ownKeys(object)) {
-    const descriptor = Object.getOwnPropertyDescriptor(object, key);
-    if (descriptor && Object.hasOwn(descriptor, 'value')) {
-      deepFreeze(descriptor.value, seenArg);
-    }
-  }
-  return Object.freeze(valueArg);
-};
+const deepFreeze = deepFreezeValue;
 
 const verifiedIsolatedRestoreGrantCompacts = new WeakMap<object, string>();
 const verifiedIsolatedRestoreWriteBindings = new WeakSet<object>();
@@ -1419,64 +1402,7 @@ export const normalizeIsolatedRestoreControlStatusRequest = (
 };
 
 const canonicalizeJson = (valueArg: unknown): string => {
-  const ancestors = new Set<object>();
-
-  const visit = (currentValueArg: unknown, fieldNameArg: string): string => {
-    if (currentValueArg === null) {
-      return 'null';
-    }
-    if (typeof currentValueArg === 'boolean') {
-      return currentValueArg ? 'true' : 'false';
-    }
-    if (typeof currentValueArg === 'string') {
-      assertUnicodeScalarString(currentValueArg, fieldNameArg);
-      return JSON.stringify(currentValueArg);
-    }
-    if (typeof currentValueArg === 'number') {
-      if (
-        !Number.isSafeInteger(currentValueArg) ||
-        Object.is(currentValueArg, -0)
-      ) {
-        return fail(`${fieldNameArg} must contain safe integers only`);
-      }
-      return String(currentValueArg);
-    }
-    if (typeof currentValueArg !== 'object') {
-      return fail(`${fieldNameArg} contains a non-JSON value`);
-    }
-    if (ancestors.has(currentValueArg)) {
-      return fail(`${fieldNameArg} contains a cycle`);
-    }
-
-    ancestors.add(currentValueArg);
-    try {
-      if (Array.isArray(currentValueArg)) {
-        return `[${currentValueArg
-          .map((entryArg, indexArg) =>
-            visit(entryArg, `${fieldNameArg}[${indexArg}]`),
-          )
-          .join(',')}]`;
-      }
-
-      const record = readRecord(currentValueArg, fieldNameArg);
-      const keys = Object.keys(record).sort((leftArg, rightArg) => {
-        return leftArg < rightArg ? -1 : leftArg > rightArg ? 1 : 0;
-      });
-      return `{${keys
-        .map((keyArg) => {
-          assertUnicodeScalarString(keyArg, `${fieldNameArg} key`);
-          return `${JSON.stringify(keyArg)}:${visit(
-            record[keyArg],
-            `${fieldNameArg}.${keyArg}`,
-          )}`;
-        })
-        .join(',')}}`;
-    } finally {
-      ancestors.delete(currentValueArg);
-    }
-  };
-
-  return visit(valueArg, 'canonical JSON input');
+  return canonicalizeStrictJson(valueArg, fail);
 };
 
 export const canonicalizeIsolatedRestoreResourceMappings = (
@@ -1618,20 +1544,13 @@ export const canonicalizeIsolatedRestoreAuthorityProjection = (
 };
 
 const createSha256 = async (contentsArg: Uint8Array): Promise<string> => {
-  const subtle = globalThis.crypto?.subtle;
-  if (!subtle) {
-    return fail('Web Crypto SHA-256 is unavailable in this runtime');
-  }
-  const digest = await subtle.digest('SHA-256', new Uint8Array(contentsArg));
-  return Array.from(new Uint8Array(digest), (byteArg) =>
-    byteArg.toString(16).padStart(2, '0'),
-  ).join('');
+  return createSha256Hex(contentsArg, fail);
 };
 
 const createCanonicalJsonSha256 = async (
   canonicalJsonArg: string,
 ): Promise<string> => {
-  return createSha256(new TextEncoder().encode(canonicalJsonArg));
+  return createCanonicalJsonSha256Hex(canonicalJsonArg, fail);
 };
 
 export const createIsolatedRestoreBytesSha256 = async (