@serve.zone/appstore 1.3.0 → 1.4.1

package/dist_ts_client/types.d.ts

@@ -9,11 +9,43 @@ 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;
     fetch?: TAppStoreFetch;
     resolveDockerDigests?: boolean;
+    requestTimeoutMs?: number;
     now?: () => Date;
 }
 export interface IAppStorePackageData {

package/package.json

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

package/readme.md

@@ -26,7 +26,7 @@ Changes are reviewed by reading the JSON data, running the client tests, and tes
 
 ## Current App Store
 
-The App Store currently lists 20 app templates.
+The App Store currently lists 21 app templates.
 
 | App ID | Name | App Store category | Image | Port |
 | --- | --- | --- | --- | --- |
@@ -41,6 +41,7 @@ The App Store currently lists 20 app templates.
 | `n8n` | N8N | Automation | `n8nio/n8n:latest` | `5678` |
 | `nextcloud` | Nextcloud | Storage | `nextcloud:latest` | `80` |
 | `nginx` | Nginx | Web Server | `nginx:alpine` | `80` |
+| `openbao` | OpenBao | Security | `openbao/openbao:2.6.0` | `8200` |
 | `plausible` | Plausible Analytics | Analytics | `plausible/analytics:latest` | `8000` |
 | `portainer` | Portainer | Dev Tools | `portainer/portainer-ce:latest` | `9000` |
 | `postgres` | PostgreSQL | Database | `postgres:16-alpine` | `5432` |
@@ -57,7 +58,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 +95,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:
@@ -133,7 +272,9 @@ const cloudly = await resolver.getAppMeta('cloudly');
 const config = await resolver.getAppVersionConfig('cloudly', cloudly.latestVersion);
 ```
 
-The resolver defaults to the App Store data bundled in the published `@serve.zone/appstore` package. Tests and explicit remote consumers can inject a custom `fetch` implementation and base URL.
+The resolver defaults to the App Store data bundled in the published `@serve.zone/appstore` package. Tests and explicit remote consumers can inject a custom `fetch` implementation and base URL. Remote operations default to a 30-second timeout, configurable with a positive-integer `requestTimeoutMs`.
+
+Catalog resolution fails closed when index and app metadata IDs or latest versions disagree, when metadata latest is absent from its version list, or when an all-semver list does not select its highest semantic value. Repo manifests with multiple non-semver versions require explicit latest or channel intent; array position never determines latest.
 
 Only include keys that are actually needed by a template. For example, `nginx` is currently just:
 
@@ -150,6 +291,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,16 @@
 import * as interfaces from '@serve.zone/interfaces';
+import { SmartVersion } from '@push.rocks/smartversion';
 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,
@@ -28,8 +35,10 @@ export class AppStoreResolver {
   private readonly fetchRef: typeof fetch;
   private readonly source: TAppStoreSourceMode;
   private readonly resolveDockerDigests: boolean;
+  private readonly requestTimeoutMs: number;
   private readonly now: () => Date;
   private appStoreCache: TAppStoreIndex | null = null;
+  private inlineAppMetaCache = new Map<string, interfaces.appstore.IAppStoreAppMeta>();
   private sourceAppCache = new Map<string, IResolvedAppStoreApp>();
 
   constructor(optionsArg: IAppStoreResolverOptions = {}) {
@@ -37,6 +46,10 @@ export class AppStoreResolver {
     this.baseUrl = optionsArg.baseUrl || appStoreDefaultRemoteBaseUrl;
     this.fetchRef = optionsArg.fetch || fetch;
     this.resolveDockerDigests = optionsArg.resolveDockerDigests ?? true;
+    this.requestTimeoutMs = optionsArg.requestTimeoutMs ?? 30_000;
+    if (!Number.isSafeInteger(this.requestTimeoutMs) || this.requestTimeoutMs < 1) {
+      throw new Error('App Store requestTimeoutMs must be a positive integer');
+    }
     this.now = optionsArg.now || (() => new Date());
   }
 
@@ -64,13 +77,20 @@ export class AppStoreResolver {
 
   public async getAppMeta(appIdArg: string): Promise<interfaces.appstore.IAppStoreAppMeta> {
     const app = await this.getAppStoreApp(appIdArg);
+    if (!app) {
+      throw new Error(`App Store app '${appIdArg}' is not present in the resolved index`);
+    }
     if (app?.source?.type === 'repoManifest') {
       return (await this.resolveRepoManifestSource(app.source, app)).appMeta;
     }
     if (app?.source?.type === 'dockerImage') {
       return this.createAppMetaFromAppStoreApp(app);
     }
-    return await this.fetchJson(`apps/${appIdArg}/app.json`) as interfaces.appstore.IAppStoreAppMeta;
+    const appMeta = this.inlineAppMetaCache.get(appIdArg);
+    if (!appMeta) {
+      throw new Error(`App Store metadata for '${appIdArg}' is unavailable`);
+    }
+    return structuredClone(appMeta);
   }
 
   public async getAppVersionConfig(
@@ -116,6 +136,7 @@ export class AppStoreResolver {
   public async resolveAppStore(appStoreArg: unknown): Promise<TAppStoreIndex> {
     const appStore = parseAppStoreIndex(appStoreArg);
     this.sourceAppCache.clear();
+    this.inlineAppMetaCache.clear();
     const apps: TAppStoreApp[] = [];
 
     for (const app of appStore.apps) {
@@ -252,14 +273,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 +288,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[] {
@@ -330,7 +358,10 @@ export class AppStoreResolver {
       };
     }
 
-    return appArg;
+    const appMeta = await this.fetchJson(
+      `apps/${appArg.id}/app.json`,
+    ) as interfaces.appstore.IAppStoreAppMeta;
+    return this.validateInlineAppMetadata(appArg, appMeta);
   }
 
   private async resolveServezoneAppStoreManifest(
@@ -382,9 +413,17 @@ export class AppStoreResolver {
 
     const selectedChannel = manifestArg.policy?.defaultChannel || manifestArg.channel || 'stable';
     const channelVersion = manifestArg.channels?.[selectedChannel];
-    const declaredLatestVersion = manifestArg.latestVersion || channelVersion || versions[versions.length - 1];
-    const latestVersion = sourceVersionToResolvedVersion.get(declaredLatestVersion) || declaredLatestVersion;
     const uniqueVersions = uniqueStrings(versions);
+    const declaredLatestVersion = manifestArg.latestVersion
+      || channelVersion
+      || selectImplicitLatestVersion(uniqueVersions, `Appstore manifest '${manifestArg.app.id}'`);
+    const latestVersion = sourceVersionToResolvedVersion.get(declaredLatestVersion)
+      || declaredLatestVersion;
+    if (!configsByVersion.has(latestVersion)) {
+      throw new Error(
+        `Appstore manifest '${manifestArg.app.id}' latestVersion '${declaredLatestVersion}' has no runtime config`,
+      );
+    }
 
     const appStoreApp: TAppStoreApp = {
       id: manifestArg.app.id,
@@ -447,6 +486,50 @@ export class AppStoreResolver {
     return configArg;
   }
 
+  private validateInlineAppMetadata(
+    appArg: TAppStoreApp,
+    appMetaArg: interfaces.appstore.IAppStoreAppMeta,
+  ): TAppStoreApp {
+    if (appMetaArg.id !== appArg.id) {
+      throw new Error(
+        `App Store metadata ID '${appMetaArg.id}' does not match index app '${appArg.id}'`,
+      );
+    }
+    if (!appMetaArg.latestVersion) {
+      throw new Error(`App Store metadata for '${appArg.id}' has no latestVersion`);
+    }
+    const versions = uniqueStrings(
+      appMetaArg.versions?.length ? appMetaArg.versions : [appMetaArg.latestVersion],
+    );
+    if (!versions.includes(appMetaArg.latestVersion)) {
+      throw new Error(
+        `App Store metadata for '${appArg.id}' latestVersion '${appMetaArg.latestVersion}' is not declared in versions`,
+      );
+    }
+    const semverLatest = selectHighestSemanticVersion(versions);
+    if (semverLatest && semverLatest !== appMetaArg.latestVersion) {
+      throw new Error(
+        `App Store metadata for '${appArg.id}' declares latestVersion '${appMetaArg.latestVersion}' but highest semantic version is '${semverLatest}'`,
+      );
+    }
+    const resolvedLatestVersion = semverLatest || appMetaArg.latestVersion;
+    if (appArg.latestVersion !== resolvedLatestVersion) {
+      throw new Error(
+        `App Store index for '${appArg.id}' declares latestVersion '${appArg.latestVersion}' but app metadata resolves '${resolvedLatestVersion}'`,
+      );
+    }
+    this.inlineAppMetaCache.set(appArg.id, {
+      ...appMetaArg,
+      latestVersion: resolvedLatestVersion,
+      versions,
+    });
+    return {
+      ...appArg,
+      latestVersion: resolvedLatestVersion,
+      versions,
+    };
+  }
+
   private createAppMetaFromAppStoreApp(appArg: TAppStoreApp): interfaces.appstore.IAppStoreAppMeta {
     return {
       id: appArg.id,
@@ -467,6 +550,56 @@ export class AppStoreResolver {
     return appStore.apps.find((appArg) => appArg.id === appIdArg);
   }
 
+  private async withRemoteResponse<T>(
+    urlArg: string,
+    initArg: RequestInit,
+    consumeArg: (responseArg: Response) => Promise<T> | T,
+  ): Promise<T> {
+    const controller = new AbortController();
+    const upstreamSignal = initArg.signal;
+    const forwardAbort = (): void => {
+      controller.abort(upstreamSignal?.reason);
+    };
+    if (upstreamSignal?.aborted) {
+      forwardAbort();
+    } else {
+      upstreamSignal?.addEventListener('abort', forwardAbort, { once: true });
+    }
+    const timeout = setTimeout(() => {
+      controller.abort(new Error(`App Store request timed out after ${this.requestTimeoutMs}ms: ${urlArg}`));
+    }, this.requestTimeoutMs);
+    let response: Response | undefined;
+    try {
+      response = await this.fetchRef(urlArg, {
+        ...initArg,
+        signal: controller.signal,
+      });
+      return await consumeArg(response);
+    } catch (error) {
+      if (controller.signal.aborted && controller.signal.reason instanceof Error) {
+        throw controller.signal.reason;
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+      upstreamSignal?.removeEventListener('abort', forwardAbort);
+      if (response?.body && !response.bodyUsed) {
+        void response.body.cancel().catch(() => {});
+      }
+    }
+  }
+
+  private async fetchRemoteHeaders(
+    urlArg: string,
+    initArg: RequestInit = {},
+  ): Promise<{ status: number; ok: boolean; headers: Headers }> {
+    return await this.withRemoteResponse(urlArg, initArg, (responseArg) => ({
+      status: responseArg.status,
+      ok: responseArg.ok,
+      headers: new Headers(responseArg.headers),
+    }));
+  }
+
   private async fetchJson(pathArg: string): Promise<unknown> {
     if (this.source === 'package') {
       const value = appStorePackageData.jsonFiles[pathArg];
@@ -477,11 +610,12 @@ export class AppStoreResolver {
     }
 
     const url = `${this.baseUrl}/${pathArg}`;
-    const response = await this.fetchRef(url);
-    if (!response.ok) {
-      throw new Error(`HTTP ${response.status} for ${url}`);
-    }
-    return response.json();
+    return await this.withRemoteResponse(url, {}, async (responseArg) => {
+      if (!responseArg.ok) {
+        throw new Error(`HTTP ${responseArg.status} for ${url}`);
+      }
+      return await responseArg.json();
+    });
   }
 
   public async fetchText(pathArg: string): Promise<string> {
@@ -496,19 +630,21 @@ export class AppStoreResolver {
     }
 
     const url = `${this.baseUrl}/${pathArg}`;
-    const response = await this.fetchRef(url);
-    if (!response.ok) {
-      throw new Error(`HTTP ${response.status} for ${url}`);
-    }
-    return response.text();
+    return await this.withRemoteResponse(url, {}, async (responseArg) => {
+      if (!responseArg.ok) {
+        throw new Error(`HTTP ${responseArg.status} for ${url}`);
+      }
+      return await responseArg.text();
+    });
   }
 
   private async fetchTextFromUrl(urlArg: string): Promise<string> {
-    const response = await this.fetchRef(urlArg);
-    if (!response.ok) {
-      throw new Error(`HTTP ${response.status} for ${urlArg}`);
-    }
-    return response.text();
+    return await this.withRemoteResponse(urlArg, {}, async (responseArg) => {
+      if (!responseArg.ok) {
+        throw new Error(`HTTP ${responseArg.status} for ${urlArg}`);
+      }
+      return await responseArg.text();
+    });
   }
 
   private async fetchDockerManifestDigest(imageArg: IParsedDockerImageReference): Promise<string | null> {
@@ -522,18 +658,18 @@ export class AppStoreResolver {
       ].join(', '),
     });
 
-    let response = await this.fetchRef(manifestUrl, { method: 'HEAD', headers });
+    let response = await this.fetchRemoteHeaders(manifestUrl, { method: 'HEAD', headers });
     if (response.status === 401) {
       const authHeader = response.headers.get('www-authenticate');
       const token = authHeader ? await this.fetchDockerRegistryToken(authHeader, imageArg.repository) : null;
       if (token) {
         headers.set('Authorization', `Bearer ${token}`);
-        response = await this.fetchRef(manifestUrl, { method: 'HEAD', headers });
+        response = await this.fetchRemoteHeaders(manifestUrl, { method: 'HEAD', headers });
       }
     }
 
     if (!response.ok || !response.headers.get('docker-content-digest')) {
-      response = await this.fetchRef(manifestUrl, { method: 'GET', headers });
+      response = await this.fetchRemoteHeaders(manifestUrl, { method: 'GET', headers });
     }
 
     if (!response.ok) {
@@ -562,21 +698,42 @@ export class AppStoreResolver {
     if (service) tokenUrl.searchParams.set('service', service);
     tokenUrl.searchParams.set('scope', scope);
 
-    const response = await this.fetchRef(tokenUrl.toString());
-    if (!response.ok) return null;
-    const tokenResponse = await response.json() as { token?: string; access_token?: string };
-    return tokenResponse.token || tokenResponse.access_token || null;
+    const tokenResponse = await this.withRemoteResponse<{
+      token?: string;
+      access_token?: string;
+    } | null>(tokenUrl.toString(), {}, async (responseArg) => {
+      if (!responseArg.ok) return null;
+      return await responseArg.json() as { token?: string; access_token?: string };
+    });
+    return tokenResponse?.token || tokenResponse?.access_token || null;
   }
 
   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`);
     }
   }
 
@@ -724,6 +881,39 @@ async function createSha256Hex(inputArg: string): Promise<string> {
     .join('');
 }
 
+function selectHighestSemanticVersion(versionsArg: string[]): string | null {
+  if (versionsArg.length === 0) return null;
+  const parsedVersions: SmartVersion[] = [];
+  for (const versionArg of versionsArg) {
+    try {
+      parsedVersions.push(new SmartVersion(versionArg));
+    } catch {
+      return null;
+    }
+  }
+  let highestIndex = 0;
+  for (let index = 1; index < parsedVersions.length; index++) {
+    if (parsedVersions[index].greaterThan(parsedVersions[highestIndex])) {
+      highestIndex = index;
+    }
+  }
+  return versionsArg[highestIndex];
+}
+
+function selectImplicitLatestVersion(versionsArg: string[], labelArg: string): string {
+  if (versionsArg.length === 0) {
+    throw new Error(`${labelArg} defines no versions`);
+  }
+  if (versionsArg.length === 1) return versionsArg[0];
+  const semverLatest = selectHighestSemanticVersion(versionsArg);
+  if (!semverLatest) {
+    throw new Error(
+      `${labelArg} must declare latestVersion or a channel when multiple non-semver versions exist`,
+    );
+  }
+  return semverLatest;
+}
+
 function uniqueStrings(valuesArg: string[]): string[] {
   return Array.from(new Set(valuesArg.filter(Boolean)));
 }

package/ts_client/data.generated.ts

@@ -1118,7 +1118,7 @@ export const appStorePackageData: IAppStorePackageData = {
     },
     "appstore.json": {
       "schemaVersion": 1,
-      "updatedAt": "2026-07-21T00:00:00Z",
+      "updatedAt": "2026-07-25T00:00:00Z",
       "apps": [
         {
           "id": "nginx",
@@ -1326,7 +1326,7 @@ export const appStorePackageData: IAppStorePackageData = {
           "description": "Multi-node serve.zone control plane for clusters, workload services, domains, and deployments.",
           "category": "Dev Tools",
           "iconName": "server",
-          "latestVersion": "1.0.0",
+          "latestVersion": "1.1.0",
           "tags": [
             "serve.zone",
             "control-plane",