@serve.zone/interfaces 22.0.0 → 23.0.1

package/ts/platform/storagemigration.ts

@@ -11,12 +11,11 @@ import {
 import type {
   IResolvedObjectStorageBinding,
   IResolvedStoragePolicyRef,
-  IStorageObjectCredentialsRef,
   IStorageGrantedCapabilities,
 } from './storage.js';
 
 export const storageMigrationContractLimits = Object.freeze({
-  version: 1 as const,
+  version: 2 as const,
   maximumControlJsonBytes: 256 * 1024,
   maximumConfiguredStringBytes: 2048,
   maximumIssueMessageBytes: 4096,
@@ -50,7 +49,7 @@ export interface IStorageBindingMigrationOwner {
 }
 
 export interface IUnfencedObjectStorageBindingControlSnapshot {
-  schemaVersion: 1;
+  schemaVersion: 2;
   binding: TActiveObjectStorageBinding;
   recordRevision: number;
   snapshotDigest: string;
@@ -59,7 +58,7 @@ export interface IUnfencedObjectStorageBindingControlSnapshot {
 }
 
 export interface IFencedObjectStorageBindingControlSnapshot {
-  schemaVersion: 1;
+  schemaVersion: 2;
   binding: TActiveObjectStorageBinding;
   recordRevision: number;
   snapshotDigest: string;
@@ -81,11 +80,11 @@ export interface IObjectStorageMigrationTarget {
   policy: IResolvedStoragePolicyRef;
   storageClass: IAppStoreStorageClass & { kind: 'objectStorage' };
   request: IAppStoreObjectStorageRequest;
-  credentials: IStorageObjectCredentialsRef;
+  credentialManagementScope: IResolvedObjectStorageBinding['credentialManagementScope'];
 }
 
 export interface IObjectStorageMigrationPrepareRequest {
-  schemaVersion: 1;
+  schemaVersion: 2;
   migrationId: string;
   sourceControlSnapshot: IUnfencedObjectStorageBindingControlSnapshot;
   workloadGeneration: number;
@@ -128,7 +127,7 @@ extends IStorageMigrationIssueBase {
 }
 
 export interface IStorageMigrationMutationFence {
-  schemaVersion: 1;
+  schemaVersion: 2;
   migrationId: string;
   migrationDigest: string;
   expectedMigrationRevision: number;
@@ -194,7 +193,7 @@ export interface IObjectStorageMigrationCleanupRequest
 extends IStorageMigrationMutationFence {}
 
 export interface IStorageMigrationStatusBase {
-  schemaVersion: 1;
+  schemaVersion: 2;
   migrationId: string;
   migrationDigest: string;
   migrationRevision: number;
@@ -894,7 +893,7 @@ const normalizeDelivery = (
   fieldNameArg: string,
 ): IResolvedObjectStorageBinding['delivery'] => {
   const value = readRecord(valueArg, fieldNameArg);
-  if (value.type === 'environment') {
+  if (value.type === 'launcher-environment') {
     assertExactKeys(value, ['type', 'keys'], fieldNameArg);
     const keys = readRecord(value.keys, `${fieldNameArg}.keys`);
     assertKeys(
@@ -933,10 +932,10 @@ const normalizeDelivery = (
     ) {
       return fail(`${fieldNameArg}.keys values must be distinct`);
     }
-    return { type: 'environment', keys: normalizedKeys };
+    return { type: 'launcher-environment', keys: normalizedKeys };
   }
-  if (value.type === 'secretFile') {
-    assertExactKeys(value, ['type', 'targetPath', 'format'], fieldNameArg);
+  if (value.type === 'file') {
+    assertExactKeys(value, ['type', 'targetPath', 'format', 'uid', 'gid', 'mode'], fieldNameArg);
     const targetPath = readString(
       value.targetPath,
       `${fieldNameArg}.targetPath`,
@@ -957,56 +956,28 @@ const normalizeDelivery = (
       return fail(`${fieldNameArg}.format is unsupported`);
     }
     return {
-      type: 'secretFile',
+      type: 'file',
       targetPath,
       format: 'servezone-object-storage-v1',
+      uid: readSafeInteger(value.uid, `${fieldNameArg}.uid`, 0, 2_147_483_647),
+      gid: readSafeInteger(value.gid, `${fieldNameArg}.gid`, 0, 2_147_483_647),
+      mode: value.mode === 0o400 || value.mode === 0o440
+        ? value.mode
+        : fail(`${fieldNameArg}.mode must be 0400 or 0440`),
     };
   }
   return fail(`${fieldNameArg}.type is unsupported`);
 };
 
-const normalizeCredentials = (
+const normalizeCredentialManagementScope = (
   valueArg: unknown,
   fieldNameArg: string,
-): IStorageObjectCredentialsRef => {
-  const value = readRecord(valueArg, fieldNameArg);
-  assertKeys(
-    value,
-    ['secretBundleId', 'accessKeyIdKey', 'secretAccessKeyKey'],
-    ['sessionTokenKey'],
-    fieldNameArg,
-  );
-  const result: IStorageObjectCredentialsRef = {
-    secretBundleId: readIdentifier(
-      value.secretBundleId,
-      `${fieldNameArg}.secretBundleId`,
-    ),
-    accessKeyIdKey: readIdentifier(
-      value.accessKeyIdKey,
-      `${fieldNameArg}.accessKeyIdKey`,
-    ),
-    secretAccessKeyKey: readIdentifier(
-      value.secretAccessKeyKey,
-      `${fieldNameArg}.secretAccessKeyKey`,
-    ),
-    ...(Object.hasOwn(value, 'sessionTokenKey')
-      ? {
-          sessionTokenKey: readIdentifier(
-            value.sessionTokenKey,
-            `${fieldNameArg}.sessionTokenKey`,
-          ),
-        }
-      : {}),
-  };
-  const keyNames = [
-    result.accessKeyIdKey,
-    result.secretAccessKeyKey,
-    ...(result.sessionTokenKey ? [result.sessionTokenKey] : []),
-  ];
-  if (new Set(keyNames).size !== keyNames.length) {
-    return fail(`${fieldNameArg} credential key references must be distinct`);
+): IResolvedObjectStorageBinding['credentialManagementScope'] => {
+  const value = readString(valueArg, fieldNameArg);
+  if (!/^platform:[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(value)) {
+    return fail(`${fieldNameArg} must be a canonical platform management scope`);
   }
-  return result;
+  return value as IResolvedObjectStorageBinding['credentialManagementScope'];
 };
 
 const normalizeObjectStorageProtection = (
@@ -1193,15 +1164,15 @@ const normalizeObjectStorageBinding = (
       'resourceRef',
       'accessMode',
       'connection',
-      'credentials',
+      'credentialManagementScope',
       'delivery',
       'versioning',
     ],
     ['capacity', 'createdAt', 'updatedAt', 'retentionDays'],
     fieldNameArg,
   );
-  if (value.schemaVersion !== 1) {
-    return fail(`${fieldNameArg}.schemaVersion must be 1`);
+  if (value.schemaVersion !== 2) {
+    return fail(`${fieldNameArg}.schemaVersion must be 2`);
   }
   if (value.kind !== 'objectStorage') {
     return fail(`${fieldNameArg}.kind must be objectStorage`);
@@ -1235,7 +1206,7 @@ const normalizeObjectStorageBinding = (
     return fail(`${fieldNameArg}.updatedAt must not precede createdAt`);
   }
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     id: readIdentifier(value.id, `${fieldNameArg}.id`),
     serviceId: readIdentifier(value.serviceId, `${fieldNameArg}.serviceId`),
     requestId: readIdentifier(value.requestId, `${fieldNameArg}.requestId`),
@@ -1273,9 +1244,9 @@ const normalizeObjectStorageBinding = (
       value.connection,
       `${fieldNameArg}.connection`,
     ),
-    credentials: normalizeCredentials(
-      value.credentials,
-      `${fieldNameArg}.credentials`,
+    credentialManagementScope: normalizeCredentialManagementScope(
+      value.credentialManagementScope,
+      `${fieldNameArg}.credentialManagementScope`,
     ),
     delivery: normalizeDelivery(value.delivery, `${fieldNameArg}.delivery`),
     versioning: readBoolean(value.versioning, `${fieldNameArg}.versioning`),
@@ -1301,7 +1272,7 @@ const normalizeTarget = (
   const value = readRecord(valueArg, fieldNameArg);
   assertExactKeys(
     value,
-    ['policy', 'storageClass', 'request', 'credentials'],
+    ['policy', 'storageClass', 'request', 'credentialManagementScope'],
     fieldNameArg,
   );
   return {
@@ -1314,9 +1285,9 @@ const normalizeTarget = (
       value.request,
       `${fieldNameArg}.request`,
     ),
-    credentials: normalizeCredentials(
-      value.credentials,
-      `${fieldNameArg}.credentials`,
+    credentialManagementScope: normalizeCredentialManagementScope(
+      value.credentialManagementScope,
+      `${fieldNameArg}.credentialManagementScope`,
     ),
   };
 };
@@ -1364,11 +1335,11 @@ const normalizeUnfencedSnapshotShape = (
     ],
     fieldNameArg,
   );
-  if (value.schemaVersion !== 1) {
-    return fail(`${fieldNameArg}.schemaVersion must be 1`);
+  if (value.schemaVersion !== 2) {
+    return fail(`${fieldNameArg}.schemaVersion must be 2`);
   }
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     binding: normalizeObjectStorageBinding(
       value.binding,
       'ready',
@@ -1408,11 +1379,11 @@ const normalizeFencedSnapshotShape = (
     ],
     fieldNameArg,
   );
-  if (value.schemaVersion !== 1) {
-    return fail(`${fieldNameArg}.schemaVersion must be 1`);
+  if (value.schemaVersion !== 2) {
+    return fail(`${fieldNameArg}.schemaVersion must be 2`);
   }
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     binding: normalizeObjectStorageBinding(
       value.binding,
       'ready',
@@ -1442,7 +1413,7 @@ const normalizeFencedSnapshotShape = (
 const createUnfencedSnapshotDigestPayload = (
   snapshotArg: IUnfencedObjectStorageBindingControlSnapshot,
 ): TUnfencedObjectStorageBindingControlSnapshotDigestPayload => ({
-  schemaVersion: 1,
+  schemaVersion: 2,
   binding: snapshotArg.binding,
   recordRevision: snapshotArg.recordRevision,
   capturedAt: snapshotArg.capturedAt,
@@ -1451,7 +1422,7 @@ const createUnfencedSnapshotDigestPayload = (
 const createFencedSnapshotDigestPayload = (
   snapshotArg: IFencedObjectStorageBindingControlSnapshot,
 ): TFencedObjectStorageBindingControlSnapshotDigestPayload => ({
-  schemaVersion: 1,
+  schemaVersion: 2,
   binding: snapshotArg.binding,
   recordRevision: snapshotArg.recordRevision,
   capturedAt: snapshotArg.capturedAt,
@@ -1676,11 +1647,11 @@ const normalizePrepareRequestShape = (
     ],
     'object-storage migration prepare request',
   );
-  if (value.schemaVersion !== 1) {
-    return fail('object-storage migration prepare request.schemaVersion must be 1');
+  if (value.schemaVersion !== 2) {
+    return fail('object-storage migration prepare request.schemaVersion must be 2');
   }
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     migrationId: readIdentifier(
       value.migrationId,
       'object-storage migration prepare request.migrationId',
@@ -1874,11 +1845,11 @@ const normalizeMutationFence = (
   valueArg: Record<string, unknown>,
   fieldNameArg: string,
 ): IStorageMigrationMutationFence => {
-  if (valueArg.schemaVersion !== 1) {
-    return fail(`${fieldNameArg}.schemaVersion must be 1`);
+  if (valueArg.schemaVersion !== 2) {
+    return fail(`${fieldNameArg}.schemaVersion must be 2`);
   }
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     migrationId: readIdentifier(
       valueArg.migrationId,
       `${fieldNameArg}.migrationId`,
@@ -1981,7 +1952,7 @@ const normalizeQuiesceRequestShape = (
 const createPersistedStagingDigestPayload = (
   requestArg: IObjectStorageMigrationConsumerQuiesceRequest,
 ): TObjectStorageMigrationPersistedStagingDigestPayload => ({
-  schemaVersion: 1,
+  schemaVersion: 2,
   migrationId: requestArg.migrationId,
   migrationDigest: requestArg.migrationDigest,
   expectedMigrationRevision: requestArg.expectedMigrationRevision,
@@ -2097,7 +2068,7 @@ const normalizeActivationRequestShape = (
 const createPersistedActivationDigestPayload = (
   requestArg: IObjectStorageMigrationConsumerActivationRequest,
 ): TObjectStorageMigrationPersistedActivationDigestPayload => ({
-  schemaVersion: 1,
+  schemaVersion: 2,
   migrationId: requestArg.migrationId,
   migrationDigest: requestArg.migrationDigest,
   expectedMigrationRevision: requestArg.expectedMigrationRevision,
@@ -2368,8 +2339,7 @@ const assertCandidateIdentity = async (
   }
   if (
     canonicalize(candidateArg.policy) !== canonicalize(targetArg.policy) ||
-    canonicalize(candidateArg.credentials) !==
-      canonicalize(targetArg.credentials) ||
+    candidateArg.credentialManagementScope !== targetArg.credentialManagementScope ||
     canonicalize(candidateArg.delivery) !==
       canonicalize(targetArg.request.delivery)
   ) {
@@ -2425,7 +2395,7 @@ const assertActiveMatchesCandidate = (
   candidateArg: TStagedObjectStorageBinding,
   fieldNameArg: string,
 ): void => {
-  const immutableKeys: readonly (keyof IResolvedObjectStorageBinding)[] = [
+  const immutableKeys: readonly (keyof TActiveObjectStorageBinding)[] = [
     'schemaVersion',
     'id',
     'serviceId',
@@ -2439,7 +2409,7 @@ const assertActiveMatchesCandidate = (
     'capacity',
     'accessMode',
     'connection',
-    'credentials',
+    'credentialManagementScope',
     'delivery',
     'versioning',
     'retentionDays',
@@ -2624,8 +2594,8 @@ export const normalizeObjectStorageMigrationStatus = async (
     phaseOptional,
     fieldName,
   );
-  if (value.schemaVersion !== 1) {
-    return fail(`${fieldName}.schemaVersion must be 1`);
+  if (value.schemaVersion !== 2) {
+    return fail(`${fieldName}.schemaVersion must be 2`);
   }
 
   const migrationId = readIdentifier(value.migrationId, `${fieldName}.migrationId`);
@@ -2663,7 +2633,7 @@ export const normalizeObjectStorageMigrationStatus = async (
   }
   await assertTargetIdentity(target, sourceBinding, `${fieldName}.target`);
   const recomputedMigrationDigest = await createObjectStorageMigrationSha256({
-    schemaVersion: 1,
+    schemaVersion: 2,
     migrationId,
     sourceControlSnapshot: source.preparationSnapshot,
     workloadGeneration,
@@ -2870,7 +2840,7 @@ export const normalizeObjectStorageMigrationStatus = async (
   }
 
   const normalized = {
-    schemaVersion: 1 as const,
+    schemaVersion: 2 as const,
     migrationId,
     migrationDigest,
     migrationRevision,

package/ts/platform/types.ts

@@ -1,3 +1,5 @@
+import type { TSecretManagementScope } from '../data/secret.js';
+
 export type TPlatformCapability =
   | 'email'
   | 'sms'
@@ -24,14 +26,6 @@ export type TPlatformEndpointProtocol =
   | 'mongodb'
   | 'sip';
 
-export type TPlatformConfigValue =
-  | string
-  | number
-  | boolean
-  | null
-  | TPlatformConfigValue[]
-  | { [key: string]: TPlatformConfigValue };
-
 export interface IPlatformCapability {
   id: TPlatformCapability;
   title: string;
@@ -46,15 +40,8 @@ export interface IPlatformProviderConfig {
   providerType: string;
   name: string;
   enabled: boolean;
-  config?: { [key: string]: TPlatformConfigValue };
-  secretBundleId?: string;
-}
-
-export interface IPlatformCredentialRef {
-  secretBundleId?: string;
-  secretGroupIds?: string[];
-  dockerSecretName?: string;
-  env?: { [key: string]: string };
+  /** Value-free owner scope; provider-specific operational config stays adapter-internal. */
+  credentialManagementScope?: Extract<TSecretManagementScope, `platform:${string}`>;
 }
 
 export interface IPlatformServiceEndpoint {
@@ -74,9 +61,9 @@ export interface IPlatformBinding {
   desiredState: TPlatformDesiredState;
   status: TPlatformBindingStatus;
   providerConfigId?: string;
-  config?: { [key: string]: TPlatformConfigValue };
   endpoints?: IPlatformServiceEndpoint[];
-  credentials?: IPlatformCredentialRef[];
+  /** Value-free reconciliation scope for service-owned credentials. */
+  credentialManagementScope?: Extract<TSecretManagementScope, `platform:${string}`>;
   createdAt?: number;
   updatedAt?: number;
 }

package/ts/plugins.ts

@@ -6,9 +6,11 @@ export {
 }
 
 // @push.rocks scope
+import * as smartcrypto from '@push.rocks/smartcrypto';
 import * as smartlogInterfaces from '@push.rocks/smartlog-interfaces';
 
 export {
+  smartcrypto,
   smartlogInterfaces,
 }
 

package/ts/requests/hostedapp.ts

@@ -1,11 +1,10 @@
 import * as plugins from '../plugins.js';
-import type { IIdentity } from '../data/user.js';
+import type { IIdentity, IIdentityCredential } from '../data/user.js';
 import type {
   IHostedAppBootstrapAction,
   IHostedAppBootstrapActionRequest,
   IHostedAppLifecycleReport,
   IHostedAppLifecycleState,
-  IHostedAppRuntimeIdentity,
   IHostedAppUpgradeState,
 } from '../data/hostedapp.js';
 
@@ -15,7 +14,7 @@ export interface IReq_HostedApp_ReportLifecycleState extends plugins.typedreques
 > {
   method: 'hostedAppReportLifecycleState';
   request: {
-    identity: IHostedAppRuntimeIdentity;
+    identity: IIdentityCredential;
     report: IHostedAppLifecycleReport;
   };
   response: {
@@ -29,7 +28,7 @@ export interface IReq_HostedApp_GetLifecycleState extends plugins.typedrequestIn
 > {
   method: 'hostedAppGetLifecycleState';
   request: {
-    identity: IHostedAppRuntimeIdentity;
+    identity: IIdentityCredential;
   };
   response: {
     state: IHostedAppLifecycleState;
@@ -42,7 +41,7 @@ export interface IReq_HostedApp_RequestBootstrapAction extends plugins.typedrequ
 > {
   method: 'hostedAppRequestBootstrapAction';
   request: {
-    identity: IHostedAppRuntimeIdentity;
+    identity: IIdentityCredential;
     action: IHostedAppBootstrapActionRequest;
   };
   response: {
@@ -57,8 +56,10 @@ export interface IReq_HostedApp_CompleteBootstrapAction extends plugins.typedreq
 > {
   method: 'hostedAppCompleteBootstrapAction';
   request: {
-    identity: IHostedAppRuntimeIdentity;
-    actionId?: string;
+    identity: IIdentityCredential;
+    actionId: string;
+    expectedActionRevision: number;
+    expectedActionStatus: 'ready';
     message?: string;
   };
   response: {
@@ -66,13 +67,53 @@ export interface IReq_HostedApp_CompleteBootstrapAction extends plugins.typedreq
   };
 }
 
+export const validateHostedAppCompleteBootstrapActionRequest = (
+  requestArg: unknown,
+): string[] => {
+  if (!requestArg || typeof requestArg !== 'object' || Array.isArray(requestArg)) {
+    return ['hosted app bootstrap completion must be an object'];
+  }
+  const request = requestArg as Record<string, unknown>;
+  const errors: string[] = [];
+  const allowedKeys = new Set([
+    'identity',
+    'actionId',
+    'expectedActionRevision',
+    'expectedActionStatus',
+    'message',
+  ]);
+  if (Object.keys(request).some((keyArg) => !allowedKeys.has(keyArg))) {
+    errors.push('hosted app bootstrap completion contains fields outside its schema');
+  }
+  if (!request.identity || typeof request.identity !== 'object'
+    || typeof (request.identity as Record<string, unknown>).jwt !== 'string') {
+    errors.push('hosted app bootstrap completion requires a JWT identity');
+  }
+  if (typeof request.actionId !== 'string'
+    || !/^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(request.actionId)) {
+    errors.push('hosted app bootstrap completion actionId must be canonical');
+  }
+  if (!Number.isSafeInteger(request.expectedActionRevision)
+    || (request.expectedActionRevision as number) < 1) {
+    errors.push('hosted app bootstrap completion revision must be positive');
+  }
+  if (request.expectedActionStatus !== 'ready') {
+    errors.push('hosted app bootstrap completion must fence ready status');
+  }
+  if (request.message !== undefined
+    && (typeof request.message !== 'string' || request.message.length > 4000)) {
+    errors.push('hosted app bootstrap completion message must be bounded');
+  }
+  return errors;
+};
+
 export interface IReq_HostedApp_StartManagedUpgrade extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_HostedApp_StartManagedUpgrade
 > {
   method: 'hostedAppStartManagedUpgrade';
   request: {
-    identity: IHostedAppRuntimeIdentity;
+    identity: IIdentityCredential;
     targetVersion?: string;
   };
   response: {
@@ -87,7 +128,7 @@ export interface IReq_HostedApp_GetManagedUpgradeStatus extends plugins.typedreq
 > {
   method: 'hostedAppGetManagedUpgradeStatus';
   request: {
-    identity: IHostedAppRuntimeIdentity;
+    identity: IIdentityCredential;
   };
   response: {
     upgradeState: IHostedAppUpgradeState;

package/ts/requests/index.ts

@@ -27,8 +27,6 @@ import * as nodeRequests from './node.js';
 import * as platformRequests from './platform.js';
 import * as routingRequests from './routing.js';
 import * as secretRequests from './secret.js';
-import * as secretBundleRequests from './secretbundle.js';
-import * as secretGroupRequests from './secretgroup.js'; 
 import * as serverRequests from './server.js';
 import * as serviceRequests from './service.js';
 import * as settingsRequests from './settings.js';
@@ -65,8 +63,6 @@ export {
   platformRequests as platform,
   routingRequests as routing,
   secretRequests as secret,
-  secretBundleRequests as secretbundle,
-  secretGroupRequests as secretgroup,
   serverRequests as server,
   serviceRequests as service,
   settingsRequests as settings,

package/ts/requests/platform.ts

@@ -124,7 +124,6 @@ extends plugins.typedrequestInterfaces.implementsTR<
     bindingId: string;
     status: TPlatformBindingStatus;
     endpoints?: IPlatformBinding['endpoints'];
-    credentials?: IPlatformBinding['credentials'];
     errorText?: string;
   };
   response: {