@serve.zone/appstore 1.3.0 → 1.4.0

package/ts_client/storage.ts

@@ -0,0 +1,831 @@
+import * as interfaces from '@serve.zone/interfaces';
+import type {
+  IAppStoreStorageNormalizationOptions,
+  INormalizedAppStoreStorageConfig,
+  TAppStoreStorageFeatureId,
+  TAppStoreStorageRequestOrigin,
+  TAppStoreVersionConfig,
+} from './types.js';
+
+const storageFeatureIds = interfaces.appstore.appStoreStorageFeatureIds;
+const knownStorageFeatureIds = new Set<string>(Object.values(storageFeatureIds));
+const storageClassKeyPattern = /^[A-Za-z][A-Za-z0-9-]{0,62}$/;
+const storageRequestIdPattern = /^[a-z][a-z0-9-]{0,62}$/;
+const environmentKeyPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const capacityPattern = /^([1-9][0-9]*)(KiB|MiB|GiB|TiB)$/;
+const capacityMultipliers = {
+  KiB: 1024n,
+  MiB: 1024n ** 2n,
+  GiB: 1024n ** 3n,
+  TiB: 1024n ** 4n,
+} as const;
+const legacyFilesystemClassKey = 'legacyFilesystem';
+const legacyObjectStorageClassKey = 'legacyObjectStorage';
+const legacyObjectStorageRequestId = 'legacy-s3';
+const appStoreVersionConfigKeys = [
+  'image',
+  'port',
+  'containerArgs',
+  'secretFiles',
+  'targetPorts',
+  'domains',
+  'publicPortMappings',
+  'envVars',
+  'volumes',
+  'storageClasses',
+  'storageRequests',
+  'publishedPorts',
+  'platformRequirements',
+  'platformOidc',
+  'minOneboxVersion',
+  'minCloudlyVersion',
+  'appStoreVersion',
+  'upgradeStrategy',
+  'source',
+  'resolvedSource',
+  'resolvedImageDigest',
+  'changelog',
+  'breaking',
+  'requiresManualReview',
+  'migrationRequired',
+  'backupBeforeUpgrade',
+  'requiresFeatures',
+  'healthCheck',
+] as const;
+
+type TPlainRecord = Record<string, unknown>;
+
+export function parseStorageCapacityQuantity(
+  quantityArg: unknown,
+  labelArg = 'storage capacity',
+): bigint {
+  if (typeof quantityArg !== 'string' || quantityArg.length > 64) {
+    throw new Error(
+      `Invalid ${labelArg}: expected a positive integer followed by KiB, MiB, GiB, or TiB`,
+    );
+  }
+  const match = quantityArg.match(capacityPattern);
+  if (!match) {
+    throw new Error(
+      `Invalid ${labelArg} '${quantityArg}': expected a positive integer followed by KiB, MiB, GiB, or TiB`,
+    );
+  }
+  return BigInt(match[1]) * capacityMultipliers[match[2] as keyof typeof capacityMultipliers];
+}
+
+/**
+ * Strict structural validation plus deterministic legacy normalization. This
+ * does not claim that a runtime can fulfill explicit requests; installers must
+ * call normalizeAppStoreStorageConfig with an advertised feature set.
+ */
+export function validateAppStoreStorageConfig(
+  configArg: TAppStoreVersionConfig,
+  labelArg = 'appstore config',
+): INormalizedAppStoreStorageConfig {
+  return validateAndNormalizeStorageConfig(configArg, labelArg);
+}
+
+/**
+ * Canonical pre-fulfillment handoff. Explicit storage contracts fail closed
+ * unless every derived storage feature is advertised by the target runtime.
+ */
+export function normalizeAppStoreStorageConfig(
+  configArg: TAppStoreVersionConfig,
+  optionsArg: IAppStoreStorageNormalizationOptions,
+  labelArg = 'appstore config',
+): INormalizedAppStoreStorageConfig {
+  const normalized = validateAndNormalizeStorageConfig(configArg, labelArg);
+  if (!optionsArg || optionsArg.supportedFeatures === undefined) {
+    throw new Error(`Invalid ${labelArg}: supportedFeatures is required for storage feature negotiation`);
+  }
+
+  let supportedFeatures: Set<string>;
+  try {
+    supportedFeatures = new Set(optionsArg.supportedFeatures);
+  } catch {
+    throw new Error(`Invalid ${labelArg}: supportedFeatures must be iterable`);
+  }
+  const unsupportedFeatures = normalized.requiredFeatureIds.filter(
+    (featureIdArg) => !supportedFeatures.has(featureIdArg),
+  );
+  if (unsupportedFeatures.length > 0) {
+    throw new Error(
+      `Unsupported ${labelArg} storage features: ${unsupportedFeatures.join(', ')}`,
+    );
+  }
+  return normalized;
+}
+
+function validateAndNormalizeStorageConfig(
+  configArg: TAppStoreVersionConfig,
+  labelArg: string,
+): INormalizedAppStoreStorageConfig {
+  assertExactKeys(
+    assertPlainRecord(configArg, labelArg),
+    appStoreVersionConfigKeys,
+    labelArg,
+  );
+  validatePlatformRequirements(configArg.platformRequirements, labelArg);
+  const explicitClassInput = configArg.storageClasses;
+  const explicitRequestInput = configArg.storageRequests;
+  const hasExplicitClasses = explicitClassInput !== undefined;
+  const hasExplicitRequests = explicitRequestInput !== undefined;
+  if (hasExplicitClasses !== hasExplicitRequests) {
+    throw new Error(
+      `Invalid ${labelArg}: storageClasses and storageRequests must be declared together`,
+    );
+  }
+
+  const storageClasses = validateStorageClasses(explicitClassInput, labelArg);
+  const explicitRequests = validateExplicitStorageRequests(
+    explicitRequestInput,
+    storageClasses,
+    configArg,
+    labelArg,
+  );
+  const requiredFeatureIds = validateFeatureDeclaration(configArg, explicitRequests, labelArg);
+
+  if (configArg.platformRequirements?.s3 && explicitRequests.some(
+    (requestArg) => requestArg.kind === 'objectStorage',
+  )) {
+    throw new Error(
+      `Invalid ${labelArg}: platformRequirements.s3 cannot coexist with explicit objectStorage requests`,
+    );
+  }
+
+  const storageRequests = [...explicitRequests];
+  const requestOriginEntries: Array<[string, TAppStoreStorageRequestOrigin]> = explicitRequests.map(
+    (requestArg) => [requestArg.id, 'explicit'],
+  );
+  const requestIds = new Set(explicitRequests.map((requestArg) => requestArg.id));
+  const mountPaths = explicitRequests
+    .filter((requestArg): requestArg is interfaces.appstore.IAppStoreFilesystemStorageRequest => (
+      requestArg.kind === 'filesystem'
+    ))
+    .map((requestArg) => requestArg.mountPath);
+
+  const legacyVolumes = normalizeLegacyVolumes(configArg.volumes, labelArg);
+  if (legacyVolumes.length > 0) {
+    if (Object.hasOwn(storageClasses, legacyFilesystemClassKey)) {
+      throw new Error(
+        `Invalid ${labelArg}: storageClasses key '${legacyFilesystemClassKey}' is reserved for legacy volume normalization`,
+      );
+    }
+    storageClasses[legacyFilesystemClassKey] = {
+      kind: 'filesystem',
+      purpose: 'runtime',
+      required: {
+        durability: 'persistent',
+        ...(legacyVolumes.some((volumeArg) => volumeArg.backup !== false)
+          ? { backup: true as const }
+          : {}),
+      },
+    };
+  }
+
+  for (const [indexArg, volumeArg] of legacyVolumes.entries()) {
+    const requestId = createLegacyVolumeRequestId(volumeArg, indexArg, labelArg);
+    if (requestIds.has(requestId)) {
+      throw new Error(`Invalid ${labelArg}: storage request id '${requestId}' is duplicated`);
+    }
+    assertNoPathCollision(volumeArg.mountPath, mountPaths, `${labelArg} legacy volume ${indexArg + 1}`);
+    requestIds.add(requestId);
+    mountPaths.push(volumeArg.mountPath);
+    storageRequests.push({
+      id: requestId,
+      kind: 'filesystem',
+      storageClass: legacyFilesystemClassKey,
+      mountPath: volumeArg.mountPath,
+      accessMode: volumeArg.readOnly ? 'ReadOnlyMany' : 'ReadWriteOnce',
+      reclaimPolicy: 'retain',
+      ...(volumeArg.backup === false ? {} : { protection: { backup: 'required' as const } }),
+    });
+    requestOriginEntries.push([requestId, 'legacyVolume']);
+  }
+
+  let legacyCompatibility: INormalizedAppStoreStorageConfig['legacyCompatibility'];
+  if (configArg.platformRequirements?.s3) {
+    if (Object.hasOwn(storageClasses, legacyObjectStorageClassKey)) {
+      throw new Error(
+        `Invalid ${labelArg}: storageClasses key '${legacyObjectStorageClassKey}' is reserved for legacy S3 normalization`,
+      );
+    }
+    if (requestIds.has(legacyObjectStorageRequestId)) {
+      throw new Error(
+        `Invalid ${labelArg}: storage request id '${legacyObjectStorageRequestId}' is reserved for legacy S3 normalization`,
+      );
+    }
+    storageClasses[legacyObjectStorageClassKey] = {
+      kind: 'objectStorage',
+      purpose: 'runtime',
+      required: { durability: 'persistent' },
+    };
+    storageRequests.push({
+      id: legacyObjectStorageRequestId,
+      kind: 'objectStorage',
+      storageClass: legacyObjectStorageClassKey,
+      accessMode: 'readWrite',
+      reclaimPolicy: 'retain',
+      delivery: {
+        type: 'environment',
+        keys: {
+          endpoint: 'S3_ENDPOINT',
+          bucket: 'S3_BUCKET',
+          region: 'S3_REGION',
+          accessKeyId: 'S3_ACCESS_KEY',
+          secretAccessKey: 'S3_SECRET_KEY',
+        },
+      },
+    });
+    requestOriginEntries.push([legacyObjectStorageRequestId, 'legacyS3']);
+    legacyCompatibility = {
+      objectStorage: {
+        requestId: legacyObjectStorageRequestId,
+        deliveryProfile: 'servezone-platform-s3-v1',
+        environmentOwnership: 'bindingOverridesTemplate',
+      },
+    };
+  }
+
+  validateAllFilesystemMountsAndSecretTargets(storageRequests, configArg, labelArg);
+
+  return {
+    schemaVersion: 1,
+    storageClasses,
+    storageRequests,
+    requestOrigins: Object.fromEntries(requestOriginEntries),
+    requiredFeatureIds,
+    ...(legacyCompatibility ? { legacyCompatibility } : {}),
+  };
+}
+
+function validateStorageClasses(
+  classesArg: TAppStoreVersionConfig['storageClasses'],
+  labelArg: string,
+): Record<string, interfaces.appstore.IAppStoreStorageClass> {
+  if (classesArg === undefined) return {};
+  const classesRecord = assertPlainRecord(classesArg, `${labelArg} storageClasses`);
+  const entries = Object.entries(classesRecord);
+  if (entries.length === 0 || entries.length > 64) {
+    throw new Error(`Invalid ${labelArg}: storageClasses must contain between 1 and 64 entries`);
+  }
+
+  const normalizedEntries = entries.map(([classKeyArg, candidateArg]) => {
+    if (!storageClassKeyPattern.test(classKeyArg)) {
+      throw new Error(`Invalid ${labelArg}: storage class key '${classKeyArg}' is not stable`);
+    }
+    const classLabel = `${labelArg} storageClasses.${classKeyArg}`;
+    const candidate = assertPlainRecord(candidateArg, classLabel);
+    assertExactKeys(candidate, ['kind', 'purpose', 'required', 'preferred'], classLabel);
+    if (!['filesystem', 'objectStorage'].includes(candidate.kind as string)) {
+      throw new Error(`Invalid ${classLabel}: kind must be filesystem or objectStorage`);
+    }
+    if (!['runtime', 'database', 'registry', 'backup'].includes(candidate.purpose as string)) {
+      throw new Error(`Invalid ${classLabel}: purpose is not supported`);
+    }
+    const required = validateClassRequirement(candidate.required, `${classLabel}.required`);
+    const preferred = validateClassRequirement(candidate.preferred, `${classLabel}.preferred`);
+    if (required && preferred) {
+      for (const requirementKey of Object.keys(required) as Array<keyof typeof required>) {
+        if (preferred[requirementKey] !== undefined
+          && preferred[requirementKey] !== required[requirementKey]) {
+          throw new Error(
+            `Invalid ${classLabel}: preferred.${requirementKey} conflicts with required.${requirementKey}`,
+          );
+        }
+      }
+    }
+    const normalized: interfaces.appstore.IAppStoreStorageClass = {
+      kind: candidate.kind as interfaces.platform.TStorageResourceKind,
+      purpose: candidate.purpose as interfaces.appstore.TAppStoreStoragePurpose,
+      ...(required ? { required } : {}),
+      ...(preferred ? { preferred } : {}),
+    };
+    return [classKeyArg, normalized] as const;
+  });
+
+  return Object.fromEntries(normalizedEntries);
+}
+
+function validateClassRequirement(
+  requirementArg: unknown,
+  labelArg: string,
+): interfaces.platform.IStorageClassRequirement | undefined {
+  if (requirementArg === undefined) return undefined;
+  const requirement = assertPlainRecord(requirementArg, labelArg);
+  assertExactKeys(requirement, [
+    'performanceTier',
+    'durability',
+    'topology',
+    'hardQuota',
+    'snapshots',
+    'backup',
+    'encryptedInTransit',
+  ], labelArg);
+  assertOptionalMember(
+    requirement.performanceTier,
+    ['standard', 'highIops', 'capacity'],
+    `${labelArg}.performanceTier`,
+  );
+  assertOptionalMember(
+    requirement.durability,
+    ['ephemeral', 'persistent'],
+    `${labelArg}.durability`,
+  );
+  assertOptionalMember(
+    requirement.topology,
+    ['singleNode', 'multiNode'],
+    `${labelArg}.topology`,
+  );
+  assertOptionalMember(requirement.snapshots, ['portable', 'native'], `${labelArg}.snapshots`);
+  for (const booleanKey of ['hardQuota', 'backup', 'encryptedInTransit'] as const) {
+    if (requirement[booleanKey] !== undefined && requirement[booleanKey] !== true) {
+      throw new Error(`Invalid ${labelArg}.${booleanKey}: only true may be declared`);
+    }
+  }
+  return { ...requirement } as interfaces.platform.IStorageClassRequirement;
+}
+
+function validateExplicitStorageRequests(
+  requestsArg: TAppStoreVersionConfig['storageRequests'],
+  classesArg: Record<string, interfaces.appstore.IAppStoreStorageClass>,
+  configArg: TAppStoreVersionConfig,
+  labelArg: string,
+): interfaces.appstore.TAppStoreStorageRequest[] {
+  if (requestsArg === undefined) return [];
+  if (!Array.isArray(requestsArg) || requestsArg.length === 0 || requestsArg.length > 64) {
+    throw new Error(`Invalid ${labelArg}: storageRequests must contain between 1 and 64 entries`);
+  }
+
+  const requestIds = new Set<string>();
+  const usedClassKeys = new Set<string>();
+  const deliveryEnvironmentKeys = new Set<string>();
+  const declaredEnvironmentKeys = new Set<string>();
+  for (const envVar of configArg.envVars || []) {
+    declaredEnvironmentKeys.add(envVar.key);
+  }
+  for (const secretFile of configArg.secretFiles || []) {
+    declaredEnvironmentKeys.add(secretFile.sourceKey);
+  }
+  for (const oidcEnvironmentKey of Object.values(
+    configArg.platformOidc?.environmentVariables || {},
+  )) {
+    declaredEnvironmentKeys.add(oidcEnvironmentKey);
+  }
+  const deliverySecretPaths = new Set<string>();
+  const declaredSecretPaths = new Set((configArg.secretFiles || []).map(
+    (entryArg) => entryArg.targetPath,
+  ));
+
+  const requests = requestsArg.map((candidateArg, indexArg) => {
+    const requestLabel = `${labelArg} storageRequests[${indexArg}]`;
+    const candidate = assertPlainRecord(candidateArg, requestLabel);
+    if (candidate.kind === 'filesystem') {
+      assertExactKeys(candidate, [
+        'id', 'kind', 'storageClass', 'capacity', 'reclaimPolicy',
+        'mountPath', 'accessMode', 'protection',
+      ], requestLabel);
+    } else if (candidate.kind === 'objectStorage') {
+      assertExactKeys(candidate, [
+        'id', 'kind', 'storageClass', 'capacity', 'reclaimPolicy',
+        'accessMode', 'delivery', 'protection',
+      ], requestLabel);
+    } else {
+      throw new Error(`Invalid ${requestLabel}: kind must be filesystem or objectStorage`);
+    }
+    if (typeof candidate.id !== 'string' || !storageRequestIdPattern.test(candidate.id)) {
+      throw new Error(`Invalid ${requestLabel}: id must be a stable lowercase identifier`);
+    }
+    if (requestIds.has(candidate.id)) {
+      throw new Error(`Invalid ${labelArg}: storage request id '${candidate.id}' is duplicated`);
+    }
+    requestIds.add(candidate.id);
+    if (typeof candidate.storageClass !== 'string'
+      || !Object.hasOwn(classesArg, candidate.storageClass)) {
+      throw new Error(`Invalid ${requestLabel}: storageClass '${candidate.storageClass}' is not declared`);
+    }
+    const storageClass = classesArg[candidate.storageClass];
+    if (storageClass.kind !== candidate.kind) {
+      throw new Error(`Invalid ${requestLabel}: storageClass kind does not match request kind`);
+    }
+    usedClassKeys.add(candidate.storageClass);
+    if (!['retain', 'delete'].includes(candidate.reclaimPolicy as string)) {
+      throw new Error(`Invalid ${requestLabel}: reclaimPolicy must be retain or delete`);
+    }
+    const capacity = validateCapacity(candidate.capacity, `${requestLabel}.capacity`);
+    if (capacity?.limit && storageClass.required?.hardQuota !== true) {
+      throw new Error(`Invalid ${requestLabel}: capacity.limit requires storageClass.required.hardQuota`);
+    }
+
+    if (candidate.kind === 'filesystem') {
+      if (typeof candidate.mountPath !== 'string'
+        || interfaces.data.normalizeServiceAbsolutePath(candidate.mountPath) !== candidate.mountPath
+        || candidate.mountPath === '/'
+        || pathsOverlap(candidate.mountPath, '/run/secrets')) {
+        throw new Error(`Invalid ${requestLabel}: mountPath must be a canonical non-root path outside /run/secrets`);
+      }
+      assertOptionalMember(
+        candidate.accessMode,
+        ['ReadWriteOnce', 'ReadOnlyMany', 'ReadWriteMany'],
+        `${requestLabel}.accessMode`,
+        false,
+      );
+      const protection = validateFilesystemProtection(
+        candidate.protection,
+        `${requestLabel}.protection`,
+      );
+      if (protection?.backup === 'required' && storageClass.required?.backup !== true) {
+        throw new Error(`Invalid ${requestLabel}: required backup must be declared by the storage class`);
+      }
+      if (protection?.snapshots && storageClass.required?.snapshots !== protection.snapshots) {
+        throw new Error(`Invalid ${requestLabel}: required snapshots must be declared by the storage class`);
+      }
+      return {
+        id: candidate.id,
+        kind: 'filesystem',
+        storageClass: candidate.storageClass,
+        ...(capacity ? { capacity } : {}),
+        reclaimPolicy: candidate.reclaimPolicy as interfaces.platform.TStorageReclaimPolicy,
+        mountPath: candidate.mountPath,
+        accessMode: candidate.accessMode as interfaces.platform.TFilesystemStorageAccessMode,
+        ...(protection ? { protection } : {}),
+      } satisfies interfaces.appstore.IAppStoreFilesystemStorageRequest;
+    }
+
+    assertOptionalMember(
+      candidate.accessMode,
+      ['readOnly', 'readWrite'],
+      `${requestLabel}.accessMode`,
+      false,
+    );
+    const delivery = validateObjectStorageDelivery(
+      candidate.delivery,
+      requestLabel,
+      declaredEnvironmentKeys,
+      deliveryEnvironmentKeys,
+      declaredSecretPaths,
+      deliverySecretPaths,
+    );
+    const protection = validateObjectStorageProtection(
+      candidate.protection,
+      `${requestLabel}.protection`,
+    );
+    if (protection?.backup === 'required' && storageClass.required?.backup !== true) {
+      throw new Error(`Invalid ${requestLabel}: required backup must be declared by the storage class`);
+    }
+    return {
+      id: candidate.id,
+      kind: 'objectStorage',
+      storageClass: candidate.storageClass,
+      ...(capacity ? { capacity } : {}),
+      reclaimPolicy: candidate.reclaimPolicy as interfaces.platform.TStorageReclaimPolicy,
+      accessMode: candidate.accessMode as interfaces.platform.TObjectStorageAccessMode,
+      delivery,
+      ...(protection ? { protection } : {}),
+    } satisfies interfaces.appstore.IAppStoreObjectStorageRequest;
+  });
+
+  for (const classKeyArg of Object.keys(classesArg)) {
+    if (!usedClassKeys.has(classKeyArg)) {
+      throw new Error(`Invalid ${labelArg}: storage class '${classKeyArg}' is not used by a request`);
+    }
+  }
+  return requests;
+}
+
+function validateCapacity(
+  capacityArg: unknown,
+  labelArg: string,
+): interfaces.platform.IStorageCapacityRequest | undefined {
+  if (capacityArg === undefined) return undefined;
+  const capacity = assertPlainRecord(capacityArg, labelArg);
+  assertExactKeys(capacity, ['request', 'limit'], labelArg);
+  const requestedBytes = parseStorageCapacityQuantity(capacity.request, `${labelArg}.request`);
+  const limitBytes = capacity.limit === undefined
+    ? undefined
+    : parseStorageCapacityQuantity(capacity.limit, `${labelArg}.limit`);
+  if (limitBytes !== undefined && limitBytes < requestedBytes) {
+    throw new Error(`Invalid ${labelArg}: limit must be greater than or equal to request`);
+  }
+  return {
+    request: capacity.request as string,
+    ...(capacity.limit === undefined ? {} : { limit: capacity.limit as string }),
+  };
+}
+
+function validateFilesystemProtection(
+  protectionArg: unknown,
+  labelArg: string,
+): interfaces.appstore.IAppStoreFilesystemProtection | undefined {
+  if (protectionArg === undefined) return undefined;
+  const protection = assertPlainRecord(protectionArg, labelArg);
+  assertExactKeys(protection, ['backup', 'snapshots', 'consistency'], labelArg);
+  assertOptionalMember(protection.backup, ['required'], `${labelArg}.backup`);
+  assertOptionalMember(protection.snapshots, ['portable', 'native'], `${labelArg}.snapshots`);
+  assertOptionalMember(
+    protection.consistency,
+    ['crashConsistent', 'applicationConsistent'],
+    `${labelArg}.consistency`,
+  );
+  return { ...protection } as interfaces.appstore.IAppStoreFilesystemProtection;
+}
+
+function validateObjectStorageProtection(
+  protectionArg: unknown,
+  labelArg: string,
+): interfaces.appstore.IAppStoreObjectStorageProtection | undefined {
+  if (protectionArg === undefined) return undefined;
+  const protection = assertPlainRecord(protectionArg, labelArg);
+  assertExactKeys(protection, ['backup', 'versioning', 'retentionDays'], labelArg);
+  assertOptionalMember(protection.backup, ['required'], `${labelArg}.backup`);
+  assertOptionalMember(protection.versioning, ['required'], `${labelArg}.versioning`);
+  if (protection.retentionDays !== undefined
+    && (!Number.isInteger(protection.retentionDays)
+      || (protection.retentionDays as number) < 1
+      || (protection.retentionDays as number) > 36500)) {
+    throw new Error(`Invalid ${labelArg}.retentionDays: expected an integer between 1 and 36500`);
+  }
+  return { ...protection } as interfaces.appstore.IAppStoreObjectStorageProtection;
+}
+
+function validateObjectStorageDelivery(
+  deliveryArg: unknown,
+  requestLabelArg: string,
+  declaredEnvironmentKeysArg: Set<string>,
+  deliveryEnvironmentKeysArg: Set<string>,
+  declaredSecretPathsArg: Set<string>,
+  deliverySecretPathsArg: Set<string>,
+): interfaces.platform.TObjectStorageDelivery {
+  const deliveryLabel = `${requestLabelArg}.delivery`;
+  const delivery = assertPlainRecord(deliveryArg, deliveryLabel);
+  if (delivery.type === 'environment') {
+    assertExactKeys(delivery, ['type', 'keys'], deliveryLabel);
+    const keys = assertPlainRecord(delivery.keys, `${deliveryLabel}.keys`);
+    assertExactKeys(keys, [
+      'endpoint', 'bucket', 'region', 'accessKeyId', 'secretAccessKey', 'sessionToken',
+    ], `${deliveryLabel}.keys`);
+    for (const requiredKey of ['endpoint', 'bucket', 'region', 'accessKeyId', 'secretAccessKey']) {
+      if (typeof keys[requiredKey] !== 'string') {
+        throw new Error(`Invalid ${deliveryLabel}.keys: '${requiredKey}' is required`);
+      }
+    }
+    const targetKeys = Object.values(keys);
+    const localKeys = new Set<string>();
+    for (const targetKeyArg of targetKeys) {
+      if (typeof targetKeyArg !== 'string' || !environmentKeyPattern.test(targetKeyArg)) {
+        throw new Error(`Invalid ${deliveryLabel}: environment delivery keys must be canonical`);
+      }
+      if (localKeys.has(targetKeyArg)) {
+        throw new Error(`Invalid ${deliveryLabel}: environment key '${targetKeyArg}' is duplicated`);
+      }
+      if (declaredEnvironmentKeysArg.has(targetKeyArg)) {
+        throw new Error(
+          `Invalid ${deliveryLabel}: environment key '${targetKeyArg}' collides with an app runtime input`,
+        );
+      }
+      if (deliveryEnvironmentKeysArg.has(targetKeyArg)) {
+        throw new Error(`Invalid ${deliveryLabel}: environment key '${targetKeyArg}' is used by another storage request`);
+      }
+      localKeys.add(targetKeyArg);
+      deliveryEnvironmentKeysArg.add(targetKeyArg);
+    }
+    return {
+      type: 'environment',
+      keys: { ...keys },
+    } as interfaces.platform.IObjectStorageEnvironmentDelivery;
+  }
+
+  if (delivery.type === 'secretFile') {
+    assertExactKeys(delivery, ['type', 'targetPath', 'format'], deliveryLabel);
+    if (delivery.format !== 'servezone-object-storage-v1') {
+      throw new Error(`Invalid ${deliveryLabel}: secret file format is not supported`);
+    }
+    if (typeof delivery.targetPath !== 'string'
+      || interfaces.data.normalizeServiceAbsolutePath(delivery.targetPath) !== delivery.targetPath
+      || !/^\/run\/secrets\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(delivery.targetPath)
+      || delivery.targetPath === '/run/secrets/secret.json') {
+      throw new Error(`Invalid ${deliveryLabel}: targetPath must be a unique canonical file below /run/secrets`);
+    }
+    if (declaredSecretPathsArg.has(delivery.targetPath)) {
+      throw new Error(`Invalid ${deliveryLabel}: targetPath collides with secretFiles`);
+    }
+    if (deliverySecretPathsArg.has(delivery.targetPath)) {
+      throw new Error(`Invalid ${deliveryLabel}: targetPath is used by another storage request`);
+    }
+    deliverySecretPathsArg.add(delivery.targetPath);
+    return {
+      type: 'secretFile',
+      targetPath: delivery.targetPath,
+      format: 'servezone-object-storage-v1',
+    };
+  }
+
+  throw new Error(`Invalid ${deliveryLabel}: type must be environment or secretFile`);
+}
+
+function validateFeatureDeclaration(
+  configArg: TAppStoreVersionConfig,
+  explicitRequestsArg: interfaces.appstore.TAppStoreStorageRequest[],
+  labelArg: string,
+): TAppStoreStorageFeatureId[] {
+  const requiredFeatures = new Set<TAppStoreStorageFeatureId>();
+  if (explicitRequestsArg.length > 0) {
+    requiredFeatures.add(storageFeatureIds.bindingsV1);
+  }
+  if (explicitRequestsArg.some((requestArg) => requestArg.kind === 'filesystem')) {
+    requiredFeatures.add(storageFeatureIds.filesystemV1);
+  }
+  if (explicitRequestsArg.some((requestArg) => requestArg.kind === 'objectStorage')) {
+    requiredFeatures.add(storageFeatureIds.objectStorageV1);
+  }
+  if (explicitRequestsArg.some((requestArg) => (
+    requestArg.kind === 'objectStorage' && requestArg.delivery.type === 'secretFile'
+  ))) {
+    requiredFeatures.add(storageFeatureIds.objectStorageSecretFileV1);
+  }
+
+  const declaredFeatures = configArg.requiresFeatures || [];
+  if (!Array.isArray(declaredFeatures)
+    || declaredFeatures.some((entryArg) => typeof entryArg !== 'string')) {
+    throw new Error(`Invalid ${labelArg}: requiresFeatures must be an array of strings`);
+  }
+  if (new Set(declaredFeatures).size !== declaredFeatures.length) {
+    throw new Error(`Invalid ${labelArg}: requiresFeatures must not contain duplicates`);
+  }
+  for (const requiredFeature of requiredFeatures) {
+    if (!declaredFeatures.includes(requiredFeature)) {
+      throw new Error(`Invalid ${labelArg}: requiresFeatures is missing '${requiredFeature}'`);
+    }
+  }
+  for (const declaredFeature of declaredFeatures) {
+    if (declaredFeature.startsWith('storage.') && !knownStorageFeatureIds.has(declaredFeature)) {
+      throw new Error(`Invalid ${labelArg}: unknown storage feature '${declaredFeature}'`);
+    }
+    if (knownStorageFeatureIds.has(declaredFeature)
+      && !requiredFeatures.has(declaredFeature as TAppStoreStorageFeatureId)) {
+      throw new Error(`Invalid ${labelArg}: storage feature '${declaredFeature}' is not used`);
+    }
+  }
+  return Array.from(requiredFeatures);
+}
+
+function validatePlatformRequirements(
+  requirementsArg: TAppStoreVersionConfig['platformRequirements'],
+  labelArg: string,
+): void {
+  if (requirementsArg === undefined) return;
+  const requirements = assertPlainRecord(requirementsArg, `${labelArg} platformRequirements`);
+  assertExactKeys(
+    requirements,
+    ['mongodb', 's3', 'clickhouse', 'valkey', 'mariadb'],
+    `${labelArg} platformRequirements`,
+  );
+  for (const [keyArg, valueArg] of Object.entries(requirements)) {
+    if (typeof valueArg !== 'boolean') {
+      throw new Error(`Invalid ${labelArg} platformRequirements.${keyArg}: expected a boolean`);
+    }
+  }
+}
+
+function normalizeLegacyVolumes(
+  volumesArg: TAppStoreVersionConfig['volumes'],
+  labelArg: string,
+): interfaces.appstore.IAppStoreVolume[] {
+  if (volumesArg === undefined) return [];
+  if (!Array.isArray(volumesArg) || volumesArg.length > 64) {
+    throw new Error(`Invalid ${labelArg}: volumes must be an array with at most 64 entries`);
+  }
+  return volumesArg.map((volumeArg, indexArg) => {
+    const volumeLabel = `${labelArg} volumes[${indexArg}]`;
+    const normalized = typeof volumeArg === 'string'
+      ? { mountPath: volumeArg }
+      : assertPlainRecord(volumeArg, volumeLabel);
+    assertExactKeys(
+      normalized,
+      ['name', 'source', 'mountPath', 'driver', 'readOnly', 'backup', 'options'],
+      volumeLabel,
+    );
+    for (const forbiddenKey of ['source', 'driver', 'options']) {
+      if (normalized[forbiddenKey] !== undefined) {
+        throw new Error(`Invalid ${volumeLabel}: physical field '${forbiddenKey}' cannot be normalized portably`);
+      }
+    }
+    if (typeof normalized.mountPath !== 'string'
+      || interfaces.data.normalizeServiceAbsolutePath(normalized.mountPath) !== normalized.mountPath
+      || normalized.mountPath === '/'
+      || pathsOverlap(normalized.mountPath, '/run/secrets')) {
+      throw new Error(`Invalid ${volumeLabel}: mountPath must be a canonical non-root path outside /run/secrets`);
+    }
+    if (normalized.name !== undefined
+      && (typeof normalized.name !== 'string' || !storageRequestIdPattern.test(normalized.name))) {
+      throw new Error(`Invalid ${volumeLabel}: name must be a stable lowercase identifier`);
+    }
+    for (const booleanKey of ['readOnly', 'backup']) {
+      if (normalized[booleanKey] !== undefined && typeof normalized[booleanKey] !== 'boolean') {
+        throw new Error(`Invalid ${volumeLabel}.${booleanKey}: expected a boolean`);
+      }
+    }
+    return {
+      ...(normalized.name === undefined ? {} : { name: normalized.name as string }),
+      mountPath: normalized.mountPath,
+      ...(normalized.readOnly === undefined ? {} : { readOnly: normalized.readOnly as boolean }),
+      ...(normalized.backup === undefined ? {} : { backup: normalized.backup as boolean }),
+    };
+  });
+}
+
+function createLegacyVolumeRequestId(
+  volumeArg: interfaces.appstore.IAppStoreVolume,
+  indexArg: number,
+  labelArg: string,
+): string {
+  const stablePart = volumeArg.name || volumeArg.mountPath
+    .toLowerCase()
+    .split('/')
+    .filter(Boolean)
+    .join('-')
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  const requestId = `legacy-volume-${stablePart}`;
+  if (!stablePart || !storageRequestIdPattern.test(requestId)) {
+    throw new Error(
+      `Invalid ${labelArg} volumes[${indexArg}]: cannot derive a stable request id; declare a shorter lowercase name`,
+    );
+  }
+  return requestId;
+}
+
+function validateAllFilesystemMountsAndSecretTargets(
+  requestsArg: interfaces.appstore.TAppStoreStorageRequest[],
+  configArg: TAppStoreVersionConfig,
+  labelArg: string,
+): void {
+  const mountPaths: string[] = [];
+  const objectSecretPaths: string[] = [];
+  for (const requestArg of requestsArg) {
+    if (requestArg.kind === 'filesystem') {
+      assertNoPathCollision(requestArg.mountPath, mountPaths, `${labelArg} request '${requestArg.id}'`);
+      mountPaths.push(requestArg.mountPath);
+    } else if (requestArg.delivery.type === 'secretFile') {
+      objectSecretPaths.push(requestArg.delivery.targetPath);
+    }
+  }
+  for (const secretPathArg of objectSecretPaths) {
+    if (mountPaths.some((mountPathArg) => pathsOverlap(secretPathArg, mountPathArg))) {
+      throw new Error(`Invalid ${labelArg}: object-storage secret target '${secretPathArg}' overlaps a filesystem mount`);
+    }
+  }
+  const secretFileErrors = interfaces.data.validateServiceSecretFiles(
+    configArg.secretFiles,
+    mountPaths,
+  );
+  if (secretFileErrors.length > 0) {
+    throw new Error(`Invalid ${labelArg}: ${secretFileErrors.join('; ')}`);
+  }
+}
+
+function assertNoPathCollision(pathArg: string, pathsArg: string[], labelArg: string): void {
+  const collision = pathsArg.find((existingPathArg) => pathsOverlap(pathArg, existingPathArg));
+  if (collision) {
+    throw new Error(`Invalid ${labelArg}: path '${pathArg}' overlaps '${collision}'`);
+  }
+}
+
+function pathsOverlap(leftArg: string, rightArg: string): boolean {
+  const left = interfaces.data.normalizeServiceAbsolutePath(leftArg);
+  const right = interfaces.data.normalizeServiceAbsolutePath(rightArg);
+  if (!left || !right) return false;
+  if (left === '/' || right === '/') return true;
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+function assertPlainRecord(valueArg: unknown, labelArg: string): TPlainRecord {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new Error(`Invalid ${labelArg}: expected an object`);
+  }
+  return valueArg as TPlainRecord;
+}
+
+function assertExactKeys(
+  recordArg: TPlainRecord,
+  allowedKeysArg: readonly string[],
+  labelArg: string,
+): void {
+  const allowedKeys = new Set(allowedKeysArg);
+  const unknownKeys = Object.keys(recordArg).filter((keyArg) => !allowedKeys.has(keyArg));
+  if (unknownKeys.length > 0) {
+    throw new Error(`Invalid ${labelArg}: unknown field(s) ${unknownKeys.sort().join(', ')}`);
+  }
+}
+
+function assertOptionalMember(
+  valueArg: unknown,
+  allowedValuesArg: readonly string[],
+  labelArg: string,
+  optionalArg = true,
+): void {
+  if (valueArg === undefined && optionalArg) return;
+  if (typeof valueArg !== 'string' || !allowedValuesArg.includes(valueArg)) {
+    throw new Error(`Invalid ${labelArg}: expected one of ${allowedValuesArg.join(', ')}`);
+  }
+}