@serve.zone/appstore 1.4.0 → 1.4.2

package/ts_client/classes.appstoreresolver.ts

@@ -1,4 +1,5 @@
 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 {
@@ -34,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 = {}) {
@@ -43,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());
   }
 
@@ -70,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(
@@ -122,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) {
@@ -343,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(
@@ -395,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,
@@ -460,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,
@@ -480,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];
@@ -490,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> {
@@ -509,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> {
@@ -535,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) {
@@ -575,10 +698,14 @@ 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 {
@@ -754,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

@@ -34,10 +34,11 @@ 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.1.0",
+      "latestVersion": "1.1.1",
       "versions": [
         "1.0.0",
-        "1.1.0"
+        "1.1.0",
+        "1.1.1"
       ],
       "maintainer": "serve.zone",
       "links": {
@@ -295,6 +296,131 @@ export const appStorePackageData: IAppStorePackageData = {
       },
       "minOneboxVersion": "2.2.0"
     },
+    "apps/cloudly/versions/1.1.1/config.json": {
+      "image": "code.foss.global/serve.zone/cloudly@sha256:510b3edb65eed00d3edce4d482f90c864b26b759e3c8f7605109516791fb47f9",
+      "targetPorts": [
+        {
+          "name": "web",
+          "port": 3000,
+          "protocol": "http",
+          "default": true
+        }
+      ],
+      "envVars": [
+        {
+          "key": "SERVEZONE_ENVIRONMENT",
+          "value": "production",
+          "description": "Cloudly runtime environment.",
+          "required": true
+        },
+        {
+          "key": "SERVEZONE_PUBLIC_ORIGIN",
+          "value": "https://${SERVICE_DOMAIN}",
+          "description": "Canonical public Cloudly origin including protocol and optional public port.",
+          "required": true
+        },
+        {
+          "key": "SERVEZONE_LISTENPORT",
+          "value": "3000",
+          "description": "Internal Cloudly HTTP port inside the container.",
+          "required": true
+        },
+        {
+          "key": "SERVEZONE_SSLMODE",
+          "value": "external",
+          "description": "Use external TLS termination through Onebox or dcrouter.",
+          "required": true
+        },
+        {
+          "key": "MONGODB_URL",
+          "value": "${MONGODB_URI}",
+          "description": "Authenticated MongoDB connection URL provisioned by Onebox.",
+          "required": true
+        },
+        {
+          "key": "MONGODB_NAME",
+          "value": "${MONGODB_DATABASE}",
+          "description": "MongoDB database name provisioned by Onebox.",
+          "required": true
+        },
+        {
+          "key": "MONGODB_USER",
+          "value": "${MONGODB_USERNAME}",
+          "description": "MongoDB username provisioned by Onebox.",
+          "required": true
+        },
+        {
+          "key": "MONGODB_PASS",
+          "value": "${MONGODB_PASSWORD}",
+          "description": "MongoDB password provisioned by Onebox.",
+          "required": true
+        },
+        {
+          "key": "S3_ENDPOINT",
+          "value": "onebox-minio",
+          "description": "S3 endpoint host for the MinIO service provisioned by Onebox.",
+          "required": true
+        },
+        {
+          "key": "S3_PORT",
+          "value": "9000",
+          "description": "S3 endpoint port for the MinIO service provisioned by Onebox.",
+          "required": true
+        },
+        {
+          "key": "S3_USESSL",
+          "value": "false",
+          "description": "Use plain HTTP for internal MinIO traffic on the Onebox network.",
+          "required": true
+        },
+        {
+          "key": "S3_BUCKET",
+          "value": "${S3_BUCKET}",
+          "description": "S3 bucket provisioned by Onebox for Cloudly's registry.",
+          "required": true
+        },
+        {
+          "key": "S3_ACCESSKEY",
+          "value": "${S3_ACCESS_KEY}",
+          "description": "S3 access key provisioned by Onebox.",
+          "required": true
+        },
+        {
+          "key": "S3_SECRETKEY",
+          "value": "${S3_SECRET_KEY}",
+          "description": "S3 secret key provisioned by Onebox.",
+          "required": true
+        }
+      ],
+      "platformRequirements": {
+        "mongodb": true,
+        "s3": true
+      },
+      "platformOidc": {
+        "redirectPath": "/auth/oidc/callback",
+        "roles": [
+          {
+            "id": "admin",
+            "label": "Administrator",
+            "description": "Full Cloudly administration for this hosted instance."
+          },
+          {
+            "id": "user",
+            "label": "User",
+            "description": "Standard authenticated Cloudly access for this hosted instance."
+          }
+        ],
+        "environmentVariables": {
+          "issuerUrl": "SERVEZONE_PLATFORM_OIDC_ISSUER",
+          "clientId": "SERVEZONE_PLATFORM_OIDC_CLIENT_ID",
+          "clientSecret": "SERVEZONE_PLATFORM_OIDC_CLIENT_SECRET",
+          "redirectUri": "SERVEZONE_PLATFORM_OIDC_REDIRECT_URI",
+          "audience": "SERVEZONE_PLATFORM_OIDC_AUDIENCE"
+        },
+        "clientAuthenticationMethod": "client_secret_basic"
+      },
+      "minOneboxVersion": "2.2.0"
+    },
     "apps/ghost/app.json": {
       "id": "ghost",
       "name": "Ghost",
@@ -1118,7 +1244,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 +1452,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.1",
           "tags": [
             "serve.zone",
             "control-plane",

package/ts_client/readme.md

@@ -32,10 +32,11 @@ const resolver = new AppStoreResolver({
   source: 'remote',
   baseUrl: 'https://example.com/appstore',
   fetch,
+  requestTimeoutMs: 30_000,
 });
 ```
 
-Providing `baseUrl` or `fetch` without an explicit `source` also selects remote mode. The default remote base URL is exported as `appStoreDefaultRemoteBaseUrl`.
+Providing `baseUrl` or `fetch` without an explicit `source` also selects remote mode. The default remote base URL is exported as `appStoreDefaultRemoteBaseUrl`. `requestTimeoutMs` bounds each remote catalog, manifest, registry, and response-body operation; it defaults to `30000` and must be a positive integer.
 
 ## Exports
 
@@ -44,6 +45,8 @@ Providing `baseUrl` or `fetch` without an explicit `source` also selects remote
 - `appStoreDefaultRemoteBaseUrl` exposes the default remote base URL for explicit remote consumers.
 - `IAppStoreResolverOptions`, `IAppStoreSourceInfo`, and the `TAppStore*` types describe resolver inputs and returned App Store data shapes.
 
+The resolver rejects inconsistent catalogs before returning them: index and app metadata IDs/latest versions must agree, metadata `latestVersion` must occur in `versions`, and an all-semver list must name its highest semantic value as latest. A repo manifest with multiple non-semver versions must declare explicit latest or channel intent.
+
 ## License and Legal Information
 
 This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

package/ts_client/types.ts

@@ -54,6 +54,7 @@ export interface IAppStoreResolverOptions {
   baseUrl?: string;
   fetch?: TAppStoreFetch;
   resolveDockerDigests?: boolean;
+  requestTimeoutMs?: number;
   now?: () => Date;
 }