@serve.zone/appstore 1.3.0 → 1.4.0

package/dist_ts_client/types.d.ts

@@ -9,6 +9,37 @@ export type TAppStoreDockerImageSource = interfaces.appstore.IAppStoreDockerImag
 export type TAppStoreRepoManifestSource = interfaces.appstore.IAppStoreRepoManifestSource;
 export type TAppStoreResolvedSource = interfaces.appstore.IAppStoreResolvedSource;
 export type TServezoneAppStoreManifest = interfaces.appstore.IServezoneAppStoreManifest;
+export type TAppStoreStorageRequest = interfaces.appstore.TAppStoreStorageRequest;
+export type TAppStoreStorageClass = interfaces.appstore.IAppStoreStorageClass;
+export type TAppStoreStorageFeatureId = interfaces.appstore.TAppStoreStorageFeatureId;
+export type TAppStoreStorageRequestOrigin = 'explicit' | 'legacyVolume' | 'legacyS3';
+export interface IAppStoreStorageLegacyCompatibility {
+    /**
+     * Downstream adapters preserve the existing S3/AWS environment aliases for
+     * this request. New named bindings use their explicit delivery declaration.
+     */
+    objectStorage?: {
+        requestId: 'legacy-s3';
+        deliveryProfile: 'servezone-platform-s3-v1';
+        /** Legacy binding values replace same-key template env values. */
+        environmentOwnership: 'bindingOverridesTemplate';
+    };
+}
+export interface INormalizedAppStoreStorageConfig {
+    schemaVersion: 1;
+    storageClasses: Record<string, TAppStoreStorageClass>;
+    storageRequests: TAppStoreStorageRequest[];
+    requestOrigins: Record<string, TAppStoreStorageRequestOrigin>;
+    requiredFeatureIds: TAppStoreStorageFeatureId[];
+    legacyCompatibility?: IAppStoreStorageLegacyCompatibility;
+}
+export interface IAppStoreStorageNormalizationOptions {
+    /**
+     * Portable storage features advertised by the fulfillment adapter.
+     * Explicit storage requests fail closed when any required feature is absent.
+     */
+    supportedFeatures: Iterable<string>;
+}
 export interface IAppStoreResolverOptions {
     source?: TAppStoreSourceMode;
     baseUrl?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/appstore",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "private": false,
   "description": "serve.zone App Store metadata, parser, and resolver client.",
   "type": "module",
@@ -10,7 +10,7 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "dependencies": {
-    "@serve.zone/interfaces": "^18.1.0"
+    "@serve.zone/interfaces": "18.1.0"
   },
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",

package/readme.md

@@ -57,7 +57,7 @@ Some templates ask Onebox to provision local platform services and inject connec
 
 | App ID | Requirements | Notes |
 | --- | --- | --- |
-| `cloudly` | MongoDB, S3 | Requires Onebox `2.2.0` or newer. Uses provisioned MongoDB and MinIO/S3 values for Cloudly state and registry storage, and reports initial admin credentials through hosted-app lifecycle. |
+| `cloudly` | MongoDB, S3 | Requires Onebox `2.2.0` or newer. Uses provisioned MongoDB and managed S3-compatible storage for Cloudly state and registry storage, and reports initial admin credentials through hosted-app lifecycle. |
 | `ghost` | MariaDB | Uses MySQL-style `database__connection__*` environment variables. |
 | `gitea` | MariaDB | Uses Gitea database environment variables with `${MARIADB_*}` placeholders. |
 | `nextcloud` | MariaDB, Valkey | Uses MySQL-compatible database variables. Valkey is declared as a platform requirement. |
@@ -94,6 +94,144 @@ Version configs use a small, pragmatic schema understood by serve.zone runtimes:
 }
 ```
 
+`platformRequirements.s3: true` and `volumes` are legacy inputs. The resolver
+normalizes them deterministically for existing templates, but new templates use
+portable, template-local `storageClasses` and stable named `storageRequests`.
+Legacy `platformRequirements.s3: true` cannot coexist with an explicit
+`objectStorage` request. Legacy volume objects may retain `name`, `mountPath`,
+`readOnly`, and `backup`; `source`, `driver`, and `options` fail validation
+because they cannot be normalized portably.
+
+## Portable Storage Requests
+
+Filesystem mounts and managed object-storage resources are different request
+kinds in the same portable contract. An app can request both, including more
+than one isolated object-storage binding:
+
+```jsonc
+{
+  "storageClasses": {
+    "databaseFast": {
+      "kind": "filesystem",
+      "purpose": "database",
+      "required": {
+        "performanceTier": "highIops",
+        "durability": "persistent",
+        "hardQuota": true,
+        "snapshots": "native",
+        "backup": true,
+        "encryptedInTransit": true
+      }
+    },
+    "backupCapacity": {
+      "kind": "objectStorage",
+      "purpose": "backup",
+      "required": {
+        "performanceTier": "capacity",
+        "durability": "persistent",
+        "hardQuota": true,
+        "backup": true,
+        "encryptedInTransit": true
+      }
+    }
+  },
+  "storageRequests": [
+    {
+      "id": "database-data",
+      "kind": "filesystem",
+      "storageClass": "databaseFast",
+      "mountPath": "/var/lib/example",
+      "accessMode": "ReadWriteOnce",
+      "capacity": { "request": "20GiB", "limit": "40GiB" },
+      "reclaimPolicy": "retain",
+      "protection": {
+        "backup": "required",
+        "snapshots": "native",
+        "consistency": "crashConsistent"
+      }
+    },
+    {
+      "id": "backup-archive",
+      "kind": "objectStorage",
+      "storageClass": "backupCapacity",
+      "accessMode": "readWrite",
+      "capacity": { "request": "100GiB", "limit": "1TiB" },
+      "reclaimPolicy": "retain",
+      "delivery": {
+        "type": "secretFile",
+        "targetPath": "/run/secrets/backup-archive.json",
+        "format": "servezone-object-storage-v1"
+      },
+      "protection": {
+        "backup": "required",
+        "versioning": "required",
+        "retentionDays": 30
+      }
+    },
+    {
+      "id": "registry-capacity",
+      "kind": "objectStorage",
+      "storageClass": "backupCapacity",
+      "accessMode": "readWrite",
+      "reclaimPolicy": "retain",
+      "delivery": {
+        "type": "environment",
+        "keys": {
+          "endpoint": "REGISTRY_S3_ENDPOINT",
+          "bucket": "REGISTRY_S3_BUCKET",
+          "region": "REGISTRY_S3_REGION",
+          "accessKeyId": "REGISTRY_S3_ACCESS_KEY_ID",
+          "secretAccessKey": "REGISTRY_S3_SECRET_ACCESS_KEY"
+        }
+      }
+    }
+  ],
+  "requiresFeatures": [
+    "storage.bindings.v1",
+    "storage.filesystem.v1",
+    "storage.object-storage.v1",
+    "storage.object-storage.secret-file.v1"
+  ]
+}
+```
+
+Capacity values are positive integers followed by `KiB`, `MiB`, `GiB`, or
+`TiB`. A `limit` requires `storageClass.required.hardQuota: true`. For explicit
+requests, delivery environment keys and secret-file paths must be unique across
+the app config; provider credential values never belong in an App Store manifest.
+
+The full version config and every storage object are exact-key validated.
+Classes express portable policy only. Provider addresses, protocols,
+identities, host paths, drivers, and driver options are rejected instead of
+being passed through. Unknown `storage.*` feature IDs also fail closed. Request
+IDs are stable across upgrades, restores, and migrations.
+
+Before provisioning, a runtime must advertise its supported feature IDs and
+call the resolver's fail-closed normalization entry point:
+
+```ts
+const normalizedStorage = resolver.normalizeStorageConfig(config, {
+  supportedFeatures: capabilityAdvertisement.featureIds,
+});
+```
+
+The package also exports the pure `validateAppStoreStorageConfig()` and
+`normalizeAppStoreStorageConfig()` functions, `parseStorageCapacityQuantity()`,
+and the normalized storage handoff types. Structural validation is useful for
+catalog ingestion; only normalization with a target's `supportedFeatures` is a
+valid pre-fulfillment gate.
+
+The result contains canonical `storageClasses`, `storageRequests`,
+`requestOrigins`, and `requiredFeatureIds`. `requestOrigins` marks explicit,
+legacy-volume, and legacy-S3 requests so fulfillment adapters can preserve old
+delivery behavior without weakening the new contract. Legacy S3 normalization
+uses the versioned `servezone-platform-s3-v1` delivery profile; adapters keep
+the established S3/AWS environment aliases for that profile. Those
+binding-provided values deterministically replace same-key legacy template
+environment values. Legacy inputs do not claim new feature support, while every
+explicit request fails before provisioning if a derived storage feature is
+unavailable.
+
 Environment variable keys must start with a letter or underscore and may contain letters, numbers, and underscores. Mixed-case keys are supported because some upstream images, including Ghost and Gitea, require lowercase nested configuration segments such as `database__connection__host` or `GITEA__database__HOST`.
 
 Linked app manifests use the same runtime schema and let the upstream app repo own its install and upgrade metadata:
@@ -150,6 +288,8 @@ Only include keys that are actually needed by a template. For example, `nginx` i
 - Prefer package-published App Store data for runtime consumers. Use `source.type=repoManifest` only when the linked manifest is intentionally reachable from the runtime environment, or pre-resolve it before publishing an App Store package.
 - Prefer explicit environment variable descriptions because Onebox surfaces them to users during installation.
 - Use platform placeholders such as `${MARIADB_HOST}`, `${MARIADB_PORT}`, `${MARIADB_DATABASE}`, `${MARIADB_USER}`, `${MARIADB_PASSWORD}`, `${MONGODB_URI}`, `${S3_BUCKET}`, `${S3_ACCESS_KEY}`, and `${S3_SECRET_KEY}` only when the matching platform service is declared.
+- Use named `objectStorage` requests instead of `platformRequirements.s3` in new templates, with a distinct delivery destination for every binding.
+- Use named `filesystem` requests instead of `volumes` in new templates. Never put provider, host-mount, protocol, identity, driver, or driver-option details in portable manifests.
 - Keep template images boring and operationally safe unless there is a reason to pin a more specific upstream tag.
 - Validate non-trivial templates by installing them through Onebox instead of only checking JSON syntax.
 

package/ts_client/classes.appstoreresolver.ts

@@ -1,9 +1,15 @@
 import * as interfaces from '@serve.zone/interfaces';
 import packageJson from '../package.json' with { type: 'json' };
 import { appStorePackageData } from './data.generated.js';
+import {
+  normalizeAppStoreStorageConfig,
+  validateAppStoreStorageConfig,
+} from './storage.js';
 import type {
   IAppStoreResolverOptions,
   IAppStoreSourceInfo,
+  IAppStoreStorageNormalizationOptions,
+  INormalizedAppStoreStorageConfig,
   IParsedDockerImageReference,
   IResolvedAppStoreApp,
   TAppStoreApp,
@@ -252,14 +258,7 @@ export class AppStoreResolver {
       }
     }
 
-    const normalizedVolumes = this.normalizeVolumes(configArg.volumes);
-    const secretFileErrors = interfaces.data.validateServiceSecretFiles(
-      configArg.secretFiles,
-      normalizedVolumes.map((volumeArg) => volumeArg.mountPath),
-    );
-    if (secretFileErrors.length > 0) {
-      throw new Error(`Invalid ${labelArg}: ${secretFileErrors.join('; ')}`);
-    }
+    validateAppStoreStorageConfig(configArg, labelArg);
     for (const secretFile of configArg.secretFiles || []) {
       if (!secretEnvVarKeys.has(secretFile.sourceKey)) {
         throw new Error(
@@ -274,6 +273,20 @@ export class AppStoreResolver {
     this.validatePublishedPorts(configArg.publishedPorts || [], labelArg);
   }
 
+  /**
+   * Produces the canonical storage handoff only after target feature
+   * negotiation. Fulfillment adapters should use this method before creating
+   * or mutating any storage resource.
+   */
+  public normalizeStorageConfig(
+    configArg: TAppStoreVersionConfig,
+    optionsArg: IAppStoreStorageNormalizationOptions,
+    labelArg = 'appstore config',
+  ): INormalizedAppStoreStorageConfig {
+    this.validateAppStoreVersionConfig(configArg, labelArg);
+    return normalizeAppStoreStorageConfig(configArg, optionsArg, labelArg);
+  }
+
   public normalizeVolumes(
     volumesArg: TAppStoreVersionConfig['volumes'] = [],
   ): interfaces.appstore.IAppStoreVolume[] {
@@ -569,14 +582,31 @@ export class AppStoreResolver {
   }
 
   private validateVolume(volumeArg: interfaces.appstore.IAppStoreVolume, labelArg: string): void {
-    if (!volumeArg.mountPath || !volumeArg.mountPath.startsWith('/')) {
-      throw new Error(`Invalid ${labelArg}: mountPath must be an absolute path`);
-    }
-    if (volumeArg.mountPath.includes(':')) {
-      throw new Error(`Invalid ${labelArg}: mountPath must not contain ':'`);
-    }
-    if ((volumeArg.source || volumeArg.name)?.includes(':')) {
-      throw new Error(`Invalid ${labelArg}: source/name must not contain ':'`);
+    const unknownKeys = Object.keys(volumeArg).filter((keyArg) => ![
+      'name',
+      'source',
+      'mountPath',
+      'driver',
+      'readOnly',
+      'backup',
+      'options',
+    ].includes(keyArg));
+    if (unknownKeys.length > 0) {
+      throw new Error(`Invalid ${labelArg}: unknown field(s) ${unknownKeys.sort().join(', ')}`);
+    }
+    if (!volumeArg.mountPath
+      || interfaces.data.normalizeServiceAbsolutePath(volumeArg.mountPath) !== volumeArg.mountPath
+      || volumeArg.mountPath === '/') {
+      throw new Error(`Invalid ${labelArg}: mountPath must be a canonical non-root absolute path`);
+    }
+    if (volumeArg.source !== undefined
+      || volumeArg.driver !== undefined
+      || volumeArg.options !== undefined) {
+      throw new Error(`Invalid ${labelArg}: physical source, driver, and options fields are not portable`);
+    }
+    if (volumeArg.name !== undefined
+      && !/^[a-z][a-z0-9-]{0,62}$/.test(volumeArg.name)) {
+      throw new Error(`Invalid ${labelArg}: name must be a stable lowercase identifier`);
     }
   }
 

package/ts_client/index.ts

@@ -1,2 +1,3 @@
 export * from './classes.appstoreresolver.js';
+export * from './storage.js';
 export * from './types.js';