@serve.zone/interfaces 19.8.0 → 20.1.0

package/ts/data/secretbundle.ts

@@ -1,3 +1,7 @@
+/**
+ * @deprecated Compatibility-only persisted shape. Service-owned Secrets and
+ * explicit same-organization SecretSets replace this model.
+ */
 export interface ISecretBundle {
   id: string;
   data: {

package/ts/data/secretgroup.ts

@@ -1,3 +1,7 @@
+/**
+ * @deprecated Compatibility-only persisted shape. Migrate to ISecretMetadata
+ * and immutable SecretVersion records; do not create new SecretGroups.
+ */
 export interface ISecretGroup {
   /**
    * the insatnce id. This should be a random id, except for default

package/ts/data/service.ts

@@ -13,6 +13,10 @@ import type {
   IServicePublicPortMapping,
   IServiceTargetPort,
 } from './serviceports.js';
+import type {
+  IServiceSecretConfiguration,
+  IServiceSecretDeploymentPlan,
+} from './secret.js';
 
 export interface IServiceVolume {
   /** Stable Docker volume name. If omitted, Coreflow derives one from service id and mount path. */
@@ -258,14 +262,22 @@ export interface IService {
     reconciliationStatus?: IServiceReconciliationStatus;
     environment: { [key: string]: string };
     /**
-     * the main secret bundle id, exclusive to the service
+     * Legacy main SecretBundle ID. New services use secretConfiguration and
+     * the server-managed secretDeployment manifest pointer.
+     *
+     * @deprecated Compatibility-only until the versioned SecretBundle migration completes.
      */
-    secretBundleId: string;
+    secretBundleId?: string;
     /**
-     * those secret bundle ids do not belong to the service itself
-     * and thus live past the service lifecycle
+     * Legacy additional SecretBundle IDs.
+     *
+     * @deprecated Use explicit same-organization SecretSet attachments.
      */
     additionalSecretBundleIds?: string[];
+    /** Value-free, caller-managed SecretSet attachment configuration. */
+    secretConfiguration?: IServiceSecretConfiguration;
+    /** Server-managed immutable manifest authority pointer. */
+    secretDeployment?: IServiceSecretDeploymentPlan;
     /** Exact OCI/Docker argument vector appended after the image entrypoint. */
     containerArgs?: string[];
     /** Secret keys mounted as files and excluded from Env and secret.json. */
@@ -338,10 +350,18 @@ export interface IService {
   };
 }
 
-/** Caller-writable service data. Immutable policy and rollout fields are server-managed. */
+/**
+ * Caller-writable service data. Immutable rollout state and SecretSet
+ * attachments are changed only through their dedicated fenced APIs.
+ */
 export type TServiceWritableData = Omit<
   IService['data'],
-  'organizationId' | 'immutableImageRequired' | 'imageDeployment' | 'imageRolloutStatus'
+  | 'organizationId'
+  | 'immutableImageRequired'
+  | 'imageDeployment'
+  | 'imageRolloutStatus'
+  | 'secretConfiguration'
+  | 'secretDeployment'
 >;
 
 /** Caller-writable update data. Null explicitly removes an existing argument vector. */

package/ts/platform/index.ts

@@ -9,6 +9,7 @@ import * as pushnotification from './pushnotification.js';
 import * as sip from './sip.js';
 import * as sms from './sms.js';
 import * as storage from './storage.js';
+import * as storagemigration from './storagemigration.js';
 import * as types from './types.js';
 
 export {
@@ -23,8 +24,10 @@ export {
   sip,
   sms,
   storage,
+  storagemigration,
   types,
 };
 
 export * from './storage.js';
+export * from './storagemigration.js';
 export * from './types.js';

package/ts/platform/storagemigration.golden.ts

@@ -0,0 +1,241 @@
+import { deepFreezeValue } from '../private/canonicaljson.js';
+import type {
+  IObjectStorageMigrationPrepareRequest,
+  IUnfencedObjectStorageBindingControlSnapshot,
+  TActiveObjectStorageBinding,
+  TStagedObjectStorageBinding,
+  TUnfencedObjectStorageBindingControlSnapshotDigestPayload,
+} from './storagemigration.js';
+
+export interface IStorageMigrationCanonicalDigestGoldenVector<TInput> {
+  input: TInput;
+  canonicalJson: string;
+  sha256: string;
+}
+
+const capabilities = {
+  performanceTier: 'capacity',
+  durability: 'persistent',
+  topology: 'singleNode',
+  hardQuota: true,
+  snapshots: 'none',
+  backup: true,
+  encryptedInTransit: true,
+} as const;
+
+const delivery = {
+  type: 'environment',
+  keys: {
+    endpoint: 'APP_S3_ENDPOINT',
+    bucket: 'APP_S3_BUCKET',
+    region: 'APP_S3_REGION',
+    accessKeyId: 'APP_S3_ACCESS_KEY',
+    secretAccessKey: 'APP_S3_SECRET_KEY',
+  },
+} as const;
+
+const credentials = {
+  secretBundleId: 'service-storage',
+  accessKeyIdKey: 'object.accessKeyId',
+  secretAccessKeyKey: 'object.secretAccessKey',
+};
+
+const sourceBinding: TActiveObjectStorageBinding = {
+  schemaVersion: 1,
+  id: 'binding-object',
+  serviceId: 'service-app',
+  requestId: 'object-data',
+  requestDigest:
+    '1111111111111111111111111111111111111111111111111111111111111111',
+  kind: 'objectStorage',
+  generation: 3,
+  observedGeneration: 3,
+  status: 'ready',
+  policy: {
+    classId: 'source-object',
+    revision: '1',
+  },
+  capabilities,
+  resourceRef: 'source-resource',
+  accessMode: 'readWrite',
+  connection: {
+    endpoint: 'https://source.example.test',
+    bucket: 'source-bucket',
+    region: 'local',
+  },
+  credentials,
+  delivery,
+  versioning: false,
+  createdAt: 1_700_000_000_000,
+  updatedAt: 1_700_000_000_001,
+};
+
+const target = {
+  policy: {
+    classId: 'capacity-object',
+    revision: '4',
+  },
+  storageClass: {
+    kind: 'objectStorage',
+    purpose: 'backup',
+    required: {
+      performanceTier: 'capacity',
+      durability: 'persistent',
+      backup: true,
+    },
+  },
+  request: {
+    id: 'object-data',
+    kind: 'objectStorage',
+    storageClass: 'backupCapacity',
+    capacity: {
+      request: '500GiB',
+      limit: '1TiB',
+    },
+    reclaimPolicy: 'retain',
+    accessMode: 'readWrite',
+    delivery,
+  },
+  credentials,
+} as const;
+
+const preparationSnapshotPayload:
+TUnfencedObjectStorageBindingControlSnapshotDigestPayload = {
+  schemaVersion: 1,
+  binding: sourceBinding,
+  recordRevision: 12,
+  capturedAt: 1_700_000_000_010,
+};
+
+const preparationSnapshot: IUnfencedObjectStorageBindingControlSnapshot = {
+  ...preparationSnapshotPayload,
+  snapshotDigest:
+    '35870a0c3ca7f2ee70d0ae7f83109bec23a8ce59bf8efef1c94221a496210439',
+};
+
+const prepareRequest: IObjectStorageMigrationPrepareRequest = {
+  schemaVersion: 1,
+  migrationId: 'migration-object-capacity',
+  sourceControlSnapshot: preparationSnapshot,
+  workloadGeneration: 8,
+  target,
+};
+
+const candidateBinding: TStagedObjectStorageBinding = {
+  ...sourceBinding,
+  requestDigest:
+    '2096dfa1f6db50d670cbb4d6436f38c2eec383435c99346e31d0d1a9e0b1beba',
+  generation: 4,
+  observedGeneration: 3,
+  status: 'provisioning',
+  policy: target.policy,
+  resourceRef: 'destination-resource',
+  capacity: {
+    requested: '500GiB',
+    granted: '500GiB',
+    limit: '1TiB',
+  },
+  connection: {
+    endpoint: 'https://destination.example.test',
+    bucket: 'destination-bucket',
+    region: 'local',
+  },
+  updatedAt: 1_700_000_000_020,
+};
+
+export const storageMigrationCanonicalDigestGoldenVectors = deepFreezeValue({
+  version: 1 as const,
+  targetRequest: {
+    input: target.request,
+    canonicalJson:
+      '{"accessMode":"readWrite","capacity":{"limit":"1TiB","request":"500GiB"},' +
+      '"delivery":{"keys":{"accessKeyId":"APP_S3_ACCESS_KEY","bucket":"APP_S3_BUCKET",' +
+      '"endpoint":"APP_S3_ENDPOINT","region":"APP_S3_REGION",' +
+      '"secretAccessKey":"APP_S3_SECRET_KEY"},"type":"environment"},' +
+      '"id":"object-data","kind":"objectStorage","reclaimPolicy":"retain",' +
+      '"storageClass":"backupCapacity"}',
+    sha256:
+      '2096dfa1f6db50d670cbb4d6436f38c2eec383435c99346e31d0d1a9e0b1beba',
+  },
+  preparationSnapshot: {
+    input: preparationSnapshotPayload,
+    canonicalJson:
+      '{"binding":{"accessMode":"readWrite","capabilities":{"backup":true,' +
+      '"durability":"persistent","encryptedInTransit":true,"hardQuota":true,' +
+      '"performanceTier":"capacity","snapshots":"none","topology":"singleNode"},' +
+      '"connection":{"bucket":"source-bucket","endpoint":"https://source.example.test",' +
+      '"region":"local"},"createdAt":1700000000000,"credentials":' +
+      '{"accessKeyIdKey":"object.accessKeyId","secretAccessKeyKey":"object.secretAccessKey",' +
+      '"secretBundleId":"service-storage"},"delivery":{"keys":' +
+      '{"accessKeyId":"APP_S3_ACCESS_KEY","bucket":"APP_S3_BUCKET",' +
+      '"endpoint":"APP_S3_ENDPOINT","region":"APP_S3_REGION",' +
+      '"secretAccessKey":"APP_S3_SECRET_KEY"},"type":"environment"},' +
+      '"generation":3,"id":"binding-object","kind":"objectStorage",' +
+      '"observedGeneration":3,"policy":{"classId":"source-object","revision":"1"},' +
+      '"requestDigest":"1111111111111111111111111111111111111111111111111111111111111111",' +
+      '"requestId":"object-data","resourceRef":"source-resource","schemaVersion":1,' +
+      '"serviceId":"service-app","status":"ready","updatedAt":1700000000001,' +
+      '"versioning":false},"capturedAt":1700000000010,"recordRevision":12,"schemaVersion":1}',
+    sha256:
+      '35870a0c3ca7f2ee70d0ae7f83109bec23a8ce59bf8efef1c94221a496210439',
+  },
+  prepareRequest: {
+    input: prepareRequest,
+    canonicalJson:
+      '{"migrationId":"migration-object-capacity","schemaVersion":1,' +
+      '"sourceControlSnapshot":{"binding":{"accessMode":"readWrite",' +
+      '"capabilities":{"backup":true,"durability":"persistent",' +
+      '"encryptedInTransit":true,"hardQuota":true,"performanceTier":"capacity",' +
+      '"snapshots":"none","topology":"singleNode"},"connection":' +
+      '{"bucket":"source-bucket","endpoint":"https://source.example.test","region":"local"},' +
+      '"createdAt":1700000000000,"credentials":{"accessKeyIdKey":"object.accessKeyId",' +
+      '"secretAccessKeyKey":"object.secretAccessKey","secretBundleId":"service-storage"},' +
+      '"delivery":{"keys":{"accessKeyId":"APP_S3_ACCESS_KEY","bucket":"APP_S3_BUCKET",' +
+      '"endpoint":"APP_S3_ENDPOINT","region":"APP_S3_REGION",' +
+      '"secretAccessKey":"APP_S3_SECRET_KEY"},"type":"environment"},' +
+      '"generation":3,"id":"binding-object","kind":"objectStorage",' +
+      '"observedGeneration":3,"policy":{"classId":"source-object","revision":"1"},' +
+      '"requestDigest":"1111111111111111111111111111111111111111111111111111111111111111",' +
+      '"requestId":"object-data","resourceRef":"source-resource","schemaVersion":1,' +
+      '"serviceId":"service-app","status":"ready","updatedAt":1700000000001,' +
+      '"versioning":false},"capturedAt":1700000000010,"recordRevision":12,' +
+      '"schemaVersion":1,"snapshotDigest":' +
+      '"35870a0c3ca7f2ee70d0ae7f83109bec23a8ce59bf8efef1c94221a496210439"},' +
+      '"target":{"credentials":{"accessKeyIdKey":"object.accessKeyId",' +
+      '"secretAccessKeyKey":"object.secretAccessKey","secretBundleId":"service-storage"},' +
+      '"policy":{"classId":"capacity-object","revision":"4"},"request":' +
+      '{"accessMode":"readWrite","capacity":{"limit":"1TiB","request":"500GiB"},' +
+      '"delivery":{"keys":{"accessKeyId":"APP_S3_ACCESS_KEY","bucket":"APP_S3_BUCKET",' +
+      '"endpoint":"APP_S3_ENDPOINT","region":"APP_S3_REGION",' +
+      '"secretAccessKey":"APP_S3_SECRET_KEY"},"type":"environment"},' +
+      '"id":"object-data","kind":"objectStorage","reclaimPolicy":"retain",' +
+      '"storageClass":"backupCapacity"},"storageClass":{"kind":"objectStorage",' +
+      '"purpose":"backup","required":{"backup":true,"durability":"persistent",' +
+      '"performanceTier":"capacity"}}},"workloadGeneration":8}',
+    sha256:
+      'ecbb40ec9bfa20b9f4372eb0d00eaf79c3e84dd3132c5bde7e65ba3fec55e595',
+  },
+  candidateBinding: {
+    input: candidateBinding,
+    canonicalJson:
+      '{"accessMode":"readWrite","capabilities":{"backup":true,' +
+      '"durability":"persistent","encryptedInTransit":true,"hardQuota":true,' +
+      '"performanceTier":"capacity","snapshots":"none","topology":"singleNode"},' +
+      '"capacity":{"granted":"500GiB","limit":"1TiB","requested":"500GiB"},' +
+      '"connection":{"bucket":"destination-bucket",' +
+      '"endpoint":"https://destination.example.test","region":"local"},' +
+      '"createdAt":1700000000000,"credentials":{"accessKeyIdKey":"object.accessKeyId",' +
+      '"secretAccessKeyKey":"object.secretAccessKey","secretBundleId":"service-storage"},' +
+      '"delivery":{"keys":{"accessKeyId":"APP_S3_ACCESS_KEY","bucket":"APP_S3_BUCKET",' +
+      '"endpoint":"APP_S3_ENDPOINT","region":"APP_S3_REGION",' +
+      '"secretAccessKey":"APP_S3_SECRET_KEY"},"type":"environment"},' +
+      '"generation":4,"id":"binding-object","kind":"objectStorage",' +
+      '"observedGeneration":3,"policy":{"classId":"capacity-object","revision":"4"},' +
+      '"requestDigest":"2096dfa1f6db50d670cbb4d6436f38c2eec383435c99346e31d0d1a9e0b1beba",' +
+      '"requestId":"object-data","resourceRef":"destination-resource",' +
+      '"schemaVersion":1,"serviceId":"service-app","status":"provisioning",' +
+      '"updatedAt":1700000000020,"versioning":false}',
+    sha256:
+      'b49017f41cd86626ccb05ffa5fb591994a5e20fad9856182b1a1d4c964c6177c',
+  },
+});