@serve.zone/appstore 32.26.0 → 33.0.0

package/ts_client/loader.ts

@@ -0,0 +1,414 @@
+import * as plugins from './plugins.js';
+import {
+  appStoreCatalogEnvelopePackagePath,
+  appStoreCatalogPackageName,
+} from './catalog.js';
+import type {
+  IAppStoreCatalogActivation,
+  IAppStoreCatalogFailure,
+  IAppStoreCatalogLoadOptions,
+  IAppStoreCatalogLoaderOptions,
+  IAppStoreCatalogRefused,
+  IAppStoreCatalogRegistryReport,
+  IAppStoreCatalogStoredRecord,
+  TAppStoreCatalogJudgement,
+  TAppStoreCatalogLoadResult,
+  TAppStoreCatalogRestoreResult,
+} from './types.js';
+
+type TEnvelope = plugins.servezoneInterfaces.appstore.IAppStoreCatalogEnvelope;
+type TTrustedKey = plugins.servezoneInterfaces.appstore.IAppStoreCatalogTrustedKey;
+type TOrigin = plugins.servezoneInterfaces.appstore.TAppStoreCatalogOrigin;
+type TRefusal = plugins.servezoneInterfaces.appstore.IAppStoreCatalogRefusal;
+
+const defaultRequestTimeoutMs = 30_000;
+const defaultMaximumTarballBytes = 32 * 1024 * 1024;
+const maximumManifestBytes = 1024 * 1024;
+const maximumEnvelopeBytes = 16 * 1024 * 1024;
+const defaultMaximumUnpackedBytes = 256 * 1024 * 1024;
+const envelopeTarballEntryName = `package/${appStoreCatalogEnvelopePackagePath}`;
+
+/** A failure of the transport, the integrity check or the package layout: no candidate was read. */
+class AppStoreCatalogTransportError extends Error {}
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const isPositiveSafeInteger = (valueArg: number): boolean => Number.isSafeInteger(valueArg) && valueArg > 0;
+
+const toBase64 = (bytesArg: Uint8Array): string => {
+  let binary = '';
+  for (const byte of bytesArg) binary += String.fromCharCode(byte);
+  return btoa(binary);
+};
+
+/** The `sha512-<base64>` values of an npm `dist.integrity` (Subresource Integrity syntax). */
+const readSha512Integrity = (integrityArg: string): string[] =>
+  integrityArg.split(/\s+/)
+    .filter((entryArg) => entryArg.startsWith('sha512-'))
+    .map((entryArg) => entryArg.slice('sha512-'.length).replace(/\?.*$/, ''));
+
+/**
+ * Loads the signed App Store catalog from npm registries and judges it against the consumer's
+ * active catalog. It holds the consumer's options only: no timer, no schedule, no catalog.
+ *
+ * One load asks every configured registry for the package its `latest` dist-tag names, downloads
+ * the tarball, checks it against the registry's `dist.integrity`, extracts the envelope, verifies
+ * it against the trusted keys (`verifyAppStoreCatalogEnvelope`) and judges its succession
+ * (`judgeAppStoreCatalogSuccession`). The first registry whose catalog activates ends the load;
+ * otherwise the result is the first `unchanged`, else the first `refused`, else `failed`, and
+ * `registries` reports what each registry answered.
+ *
+ * The loader holds no state, runs no schedule and persists nothing: the consumer's catalog runtime
+ * owns the one refresh schedule of its process, passes its active envelope in, stores an activated
+ * one as its last-known-good catalog and restores it with `restoreEnvelopeText` at start. Every
+ * request is bounded in time and size; a transport, integrity or packaging failure and every
+ * refusal are results, never thrown. Aborting `signal` (the consumer stopping) ends the load at
+ * once and rejects it with the signal's reason; no attempt is reported for it.
+ */
+export class AppStoreCatalogLoader {
+  private readonly trustedKeys: readonly TTrustedKey[];
+  private readonly supportedFeatureIds: readonly string[];
+  private readonly registries: readonly string[];
+  private readonly fetchFunction: typeof fetch;
+  private readonly now: () => Date;
+  private readonly requestTimeoutMs: number;
+  private readonly maximumTarballBytes: number;
+  private readonly maximumUnpackedBytes: number;
+
+  constructor(optionsArg: IAppStoreCatalogLoaderOptions) {
+    if (optionsArg.trustedKeys.length === 0) {
+      throw new Error('App Store catalog loader needs at least one trusted key');
+    }
+    this.trustedKeys = optionsArg.trustedKeys.map((keyArg) => ({ ...keyArg }));
+    this.supportedFeatureIds = [...new Set(optionsArg.supportedFeatureIds)].sort();
+    this.registries = plugins.servezoneInterfaces.appstore.resolveAppStoreCatalogRegistries(optionsArg.registries);
+    this.fetchFunction = optionsArg.fetch ?? ((inputArg, initArg) => fetch(inputArg, initArg));
+    this.now = optionsArg.now ?? (() => new Date());
+    this.requestTimeoutMs = optionsArg.requestTimeoutMs ?? defaultRequestTimeoutMs;
+    this.maximumTarballBytes = optionsArg.maximumTarballBytes ?? defaultMaximumTarballBytes;
+    this.maximumUnpackedBytes = optionsArg.maximumUnpackedBytes ?? defaultMaximumUnpackedBytes;
+    if (!isPositiveSafeInteger(this.requestTimeoutMs)) {
+      throw new Error('App Store catalog requestTimeoutMs must be a positive integer');
+    }
+    if (!isPositiveSafeInteger(this.maximumTarballBytes)) {
+      throw new Error('App Store catalog maximumTarballBytes must be a positive integer');
+    }
+    if (!isPositiveSafeInteger(this.maximumUnpackedBytes)) {
+      throw new Error('App Store catalog maximumUnpackedBytes must be a positive integer');
+    }
+  }
+
+  /** One load from the configured registries; see the class description. */
+  public async loadFromRegistries(
+    activeArg: TEnvelope | null,
+    optionsArg: IAppStoreCatalogLoadOptions = {},
+  ): Promise<TAppStoreCatalogLoadResult> {
+    const { signal } = optionsArg;
+    const reports: IAppStoreCatalogRegistryReport[] = [];
+    const judgements: TAppStoreCatalogJudgement[] = [];
+    for (const registry of this.registries) {
+      signal?.throwIfAborted();
+      try {
+        const { packageVersion, envelopeText } = await this.fetchEnvelopeText(registry, signal);
+        const judgement = await this.judgeText(envelopeText, activeArg, 'registry');
+        judgements.push(judgement);
+        reports.push({
+          registry,
+          outcome: judgement.outcome,
+          packageVersion,
+          ...(judgement.outcome === 'refused' ? { message: judgement.refused.message } : {}),
+        });
+        if (judgement.outcome === 'activated') break;
+      } catch (error) {
+        signal?.throwIfAborted();
+        if (!(error instanceof AppStoreCatalogTransportError)) throw error;
+        reports.push({ registry, outcome: 'failed', message: error.message });
+      }
+    }
+    signal?.throwIfAborted();
+    const chosen = judgements.find((judgementArg) => judgementArg.outcome === 'activated')
+      ?? judgements.find((judgementArg) => judgementArg.outcome === 'unchanged')
+      ?? judgements.find((judgementArg) => judgementArg.outcome === 'refused');
+    if (chosen !== undefined) return { ...chosen, registries: reports };
+    const message = reports.map((reportArg) => `${reportArg.registry}: ${reportArg.message ?? reportArg.outcome}`).join('; ');
+    const failure: IAppStoreCatalogFailure = {
+      outcome: 'failed',
+      message,
+      attempt: { at: this.now().toISOString(), outcome: 'failed', message },
+    };
+    return { ...failure, registries: reports };
+  }
+
+  /**
+   * Judges an envelope an operator imported (an offline signed bundle, or the envelope a package
+   * carries at `./catalog.envelope.json`) exactly as a fetched one: authentication, contract,
+   * schema, digests, then succession against the active catalog.
+   */
+  public async judgeImportedEnvelope(candidateArg: unknown, activeArg: TEnvelope | null): Promise<TAppStoreCatalogJudgement> {
+    return await this.judge(candidateArg, activeArg, 'operatorImport');
+  }
+
+  /** An envelope read as text: bytes that are not JSON are refused as `schemaInvalid`. */
+  public async judgeImportedEnvelopeText(textArg: string, activeArg: TEnvelope | null): Promise<TAppStoreCatalogJudgement> {
+    return await this.judgeText(textArg, activeArg, 'operatorImport');
+  }
+
+  /**
+   * Restores the last-known-good catalog a consumer stored, at start: the stored envelope text is
+   * verified again against today's trusted keys and supported features, exactly as a fetched one,
+   * and answers the status `active` member it activates (`origin` and `loadedAt` as stored, the
+   * verifying key as verified now) or the refusal that keeps it inactive, e.g. `signatureInvalid`
+   * once its key is no longer trusted.
+   */
+  public async restoreEnvelopeText(
+    textArg: string,
+    recordArg: IAppStoreCatalogStoredRecord,
+  ): Promise<TAppStoreCatalogRestoreResult> {
+    const candidate = this.parseEnvelopeText(textArg);
+    const verified = candidate.parsed
+      ? await this.verify(candidate.value, recordArg.origin)
+      : refuseCandidate(undefined, this.now().toISOString(), candidate.refusal);
+    if (verified.outcome === 'refused') return verified;
+    return {
+      outcome: 'restored',
+      envelope: verified.envelope,
+      active: { ...verified.active, loadedAt: recordArg.loadedAt },
+    };
+  }
+
+  private async judgeText(textArg: string, activeArg: TEnvelope | null, originArg: TOrigin): Promise<TAppStoreCatalogJudgement> {
+    const candidate = this.parseEnvelopeText(textArg);
+    return candidate.parsed
+      ? await this.judge(candidate.value, activeArg, originArg)
+      : refuseCandidate(undefined, this.now().toISOString(), candidate.refusal);
+  }
+
+  /** Envelope text as a value; bytes that are not JSON are a `schemaInvalid` refusal. */
+  private parseEnvelopeText(textArg: string): { parsed: true; value: unknown } | { parsed: false; refusal: TRefusal } {
+    try {
+      return { parsed: true, value: JSON.parse(textArg) };
+    } catch {
+      return { parsed: false, refusal: { reason: 'schemaInvalid', message: 'envelope is not JSON' } };
+    }
+  }
+
+  private async judge(candidateArg: unknown, activeArg: TEnvelope | null, originArg: TOrigin): Promise<TAppStoreCatalogJudgement> {
+    const verified = await this.verify(candidateArg, originArg);
+    if (verified.outcome === 'refused') return verified;
+    const succession = plugins.servezoneInterfaces.appstore.judgeAppStoreCatalogSuccession(activeArg, verified.envelope);
+    if (succession.outcome === 'refused') return refuseCandidate(candidateArg, verified.attempt.at, succession.refusal);
+    if (succession.outcome === 'unchanged') {
+      return { outcome: 'unchanged', attempt: { at: verified.attempt.at, outcome: 'unchanged' } };
+    }
+    return verified;
+  }
+
+  /**
+   * Authenticates and reads a candidate (`verifyAppStoreCatalogEnvelope`), before and without
+   * succession. The verifier answers every refusal as a result; should it throw, the candidate is
+   * refused as `schemaInvalid` with the cause, so a load never fails on an input it could not read.
+   */
+  private async verify(candidateArg: unknown, originArg: TOrigin): Promise<IAppStoreCatalogActivation | IAppStoreCatalogRefused> {
+    const at = this.now().toISOString();
+    let verification: plugins.servezoneInterfacesRuntime.TAppStoreCatalogVerification;
+    try {
+      verification = await plugins.servezoneInterfacesRuntime.verifyAppStoreCatalogEnvelope(candidateArg, {
+        trustedKeys: this.trustedKeys,
+        supportedFeatureIds: this.supportedFeatureIds,
+      });
+    } catch (error) {
+      return refuseCandidate(candidateArg, at, {
+        reason: 'schemaInvalid',
+        message: `envelope could not be verified: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+    if (!verification.accepted) return refuseCandidate(candidateArg, at, verification.refusal);
+    const { envelope, keyId } = verification;
+    const { catalog, catalogDigest } = envelope;
+    return {
+      outcome: 'activated',
+      envelope,
+      active: {
+        contract: { ...catalog.contract },
+        revision: catalog.revision,
+        catalogDigest,
+        publishedAt: catalog.publishedAt,
+        sourceRevision: catalog.sourceRevision,
+        loadedAt: at,
+        keyId,
+        origin: originArg,
+      },
+      attempt: { at, outcome: 'activated' },
+    };
+  }
+
+  /** The envelope text the package the registry's `latest` dist-tag names carries. */
+  private async fetchEnvelopeText(
+    registryArg: string,
+    signalArg: AbortSignal | undefined,
+  ): Promise<{ packageVersion: string; envelopeText: string }> {
+    const manifestUrl = `${registryArg}/${appStoreCatalogPackageName.replace('/', '%2f')}/latest`;
+    const manifestBytes = await this.fetchBytes(manifestUrl, maximumManifestBytes, signalArg);
+    let manifest: unknown;
+    try {
+      manifest = JSON.parse(new TextDecoder().decode(manifestBytes));
+    } catch {
+      throw new AppStoreCatalogTransportError(`${manifestUrl} did not answer JSON`);
+    }
+    const dist = isRecord(manifest) ? manifest.dist : undefined;
+    if (!isRecord(manifest) || manifest.name !== appStoreCatalogPackageName || typeof manifest.version !== 'string'
+      || !isRecord(dist) || typeof dist.tarball !== 'string' || typeof dist.integrity !== 'string') {
+      throw new AppStoreCatalogTransportError(`${manifestUrl} is not the ${appStoreCatalogPackageName} version manifest`);
+    }
+    const packageVersion = manifest.version;
+    const expectedSha512 = readSha512Integrity(dist.integrity);
+    if (expectedSha512.length === 0) {
+      throw new AppStoreCatalogTransportError(`${appStoreCatalogPackageName}@${packageVersion} has no sha512 dist.integrity`);
+    }
+    let tarballUrl: URL;
+    try {
+      tarballUrl = new URL(dist.tarball);
+    } catch {
+      throw new AppStoreCatalogTransportError(`${appStoreCatalogPackageName}@${packageVersion} names no tarball URL`);
+    }
+    if (tarballUrl.protocol !== 'https:' || tarballUrl.username !== '' || tarballUrl.password !== '') {
+      throw new AppStoreCatalogTransportError(`${appStoreCatalogPackageName}@${packageVersion} tarball URL must be https without credentials`);
+    }
+    const tarball = await this.fetchBytes(tarballUrl.toString(), this.maximumTarballBytes, signalArg);
+    const actualSha512 = toBase64(new Uint8Array(await crypto.subtle.digest('SHA-512', tarball)));
+    if (!expectedSha512.includes(actualSha512)) {
+      throw new AppStoreCatalogTransportError(
+        `${appStoreCatalogPackageName}@${packageVersion} tarball does not match its dist.integrity`,
+      );
+    }
+    const envelopeText = await readTarballEntry(tarball, envelopeTarballEntryName, packageVersion, this.maximumUnpackedBytes);
+    return { packageVersion, envelopeText };
+  }
+
+  /**
+   * GET with the request bound covering the response body and a byte bound on the body. The
+   * caller's `signalArg` aborts it too; that abort is rethrown as the signal's reason. A redirect is
+   * never followed: a registry that answers with one fails, so a request never leaves https.
+   */
+  private async fetchBytes(
+    urlArg: string,
+    maximumBytesArg: number,
+    signalArg: AbortSignal | undefined,
+  ): Promise<Uint8Array<ArrayBuffer>> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+    const signal = signalArg === undefined ? controller.signal : AbortSignal.any([controller.signal, signalArg]);
+    try {
+      const response = await this.fetchFunction(urlArg, {
+        signal,
+        redirect: 'error',
+        headers: { accept: 'application/json, application/octet-stream' },
+      });
+      if (!response.ok) {
+        await response.body?.cancel();
+        throw new AppStoreCatalogTransportError(`HTTP ${response.status} for ${urlArg}`);
+      }
+      const declaredLength = Number(response.headers.get('content-length') ?? '0');
+      if (declaredLength > maximumBytesArg) {
+        await response.body?.cancel();
+        throw new AppStoreCatalogTransportError(`${urlArg} exceeds ${maximumBytesArg} bytes`);
+      }
+      if (response.body === null) throw new AppStoreCatalogTransportError(`${urlArg} answered no body`);
+      return await readBounded(response.body, maximumBytesArg, urlArg);
+    } catch (error) {
+      signalArg?.throwIfAborted();
+      if (controller.signal.aborted) {
+        throw new AppStoreCatalogTransportError(`${urlArg} timed out after ${this.requestTimeoutMs} ms`);
+      }
+      if (error instanceof AppStoreCatalogTransportError) throw error;
+      throw new AppStoreCatalogTransportError(
+        `${urlArg} failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/** The refusal record and attempt of a candidate, with its revision when it can be read. */
+const refuseCandidate = (candidateArg: unknown, atArg: string, refusalArg: TRefusal): IAppStoreCatalogRefused => {
+  const revision = readCandidateRevision(candidateArg);
+  return {
+    outcome: 'refused',
+    refused: { ...refusalArg, at: atArg, ...(revision === undefined ? {} : { revision }) },
+    attempt: { at: atArg, outcome: 'refused', message: `${refusalArg.reason}: ${refusalArg.message}` },
+  };
+};
+
+const readCandidateRevision = (candidateArg: unknown): number | undefined => {
+  const catalog = isRecord(candidateArg) ? candidateArg.catalog : undefined;
+  const revision = isRecord(catalog) ? catalog.revision : undefined;
+  return typeof revision === 'number' && Number.isSafeInteger(revision) ? revision : undefined;
+};
+
+const readBounded = async (
+  streamArg: ReadableStream<Uint8Array>,
+  maximumBytesArg: number,
+  labelArg: string,
+): Promise<Uint8Array<ArrayBuffer>> => {
+  const reader = streamArg.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maximumBytesArg) {
+        await reader.cancel();
+        throw new AppStoreCatalogTransportError(`${labelArg} exceeds ${maximumBytesArg} bytes`);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+};
+
+/**
+ * The text of one regular file in a gzip-compressed npm tarball. The archive is decompressed in
+ * full (bounded) before it is decoded: decoding straight from the decompression stream stalls on
+ * entries larger than one stream chunk.
+ */
+const readTarballEntry = async (
+  tarballArg: Uint8Array<ArrayBuffer>,
+  entryNameArg: string,
+  packageVersionArg: string,
+  maximumUnpackedBytesArg: number,
+): Promise<string> => {
+  const label = `${appStoreCatalogPackageName}@${packageVersionArg}`;
+  try {
+    const archive = await readBounded(
+      new Blob([tarballArg]).stream().pipeThrough(new DecompressionStream('gzip')),
+      maximumUnpackedBytesArg,
+      `${label} unpacked tarball`,
+    );
+    const entry = (await plugins.modernTar.unpackTar(archive, { strict: true }))
+      .find((entryArg) => entryArg.header.name === entryNameArg && (entryArg.header.type ?? 'file') === 'file');
+    if (entry?.data === undefined) {
+      throw new AppStoreCatalogTransportError(`${label} carries no ${appStoreCatalogEnvelopePackagePath}`);
+    }
+    if (entry.data.byteLength > maximumEnvelopeBytes) {
+      throw new AppStoreCatalogTransportError(`${label} ${appStoreCatalogEnvelopePackagePath} exceeds ${maximumEnvelopeBytes} bytes`);
+    }
+    return new TextDecoder().decode(entry.data);
+  } catch (error) {
+    if (error instanceof AppStoreCatalogTransportError) throw error;
+    throw new AppStoreCatalogTransportError(
+      `${label} tarball could not be read: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+};

package/ts_client/plugins.ts

@@ -0,0 +1,10 @@
+// @serve.zone scope
+import * as servezoneInterfaces from '@serve.zone/interfaces';
+import * as servezoneInterfacesRuntime from '@serve.zone/interfaces/runtime';
+
+export { servezoneInterfaces, servezoneInterfacesRuntime };
+
+// third party
+import * as modernTar from 'modern-tar';
+
+export { modernTar };

package/ts_client/projection.ts

@@ -0,0 +1,148 @@
+import * as plugins from './plugins.js';
+
+type TCatalog = plugins.servezoneInterfaces.appstore.IAppStoreCatalog;
+type TCatalogApp = plugins.servezoneInterfaces.appstore.IAppStoreCatalogApp;
+type TAppStoreApp = plugins.servezoneInterfaces.appstore.IAppStoreApp;
+type TAppStoreAppMeta = plugins.servezoneInterfaces.appstore.IAppStoreAppMeta;
+
+type TVersionState = plugins.servezoneInterfaces.appstore.IAppStoreAppVersionState;
+
+/** The consumer a projection is for: the feature ids it fulfils, and which host release it is. */
+export interface IAppStoreCatalogProjectionOptions {
+  /** The `requiresFeatures` ids this consumer fulfils, e.g. `appStoreStorageFeatureIds` values. */
+  supportedFeatureIds: Iterable<string>;
+  /** The host and its release, judged against each version's `minOneboxVersion` / `minCloudlyVersion`. */
+  consumer: plugins.servezoneInterfaces.appstore.IAppStoreCatalogConsumer;
+}
+
+/** The App Store shapes Onebox and Cloudly carry in their views and requests for one app. */
+export interface IAppStoreCatalogAppDisplay {
+  /** The listing entry (`getAppStoreTemplates`). */
+  app: TAppStoreApp;
+  /** The app metadata (`getAppStoreConfig`, the upgrade preview). */
+  meta: TAppStoreAppMeta;
+}
+
+/** One catalog app as a consumer with its supported feature ids sees it. */
+export interface IAppStoreCatalogAppProjection {
+  appId: string;
+  /** The catalog's `latestVersion`, the publisher's latest, whether or not this consumer may install it. */
+  catalogLatestVersion: string;
+  /**
+   * Every listed version in catalog order, withdrawn, feature-gated and newer-release-gated ones
+   * included, each with `installRefusal` as `appstore.judgeAppStoreCatalogInstallTarget` answers it.
+   */
+  versions: TVersionState[];
+  /**
+   * The newest version this consumer may install, or `null` when none is: every version withdrawn,
+   * gated on a feature it does not fulfil or requiring a newer release of it. Under `semver` the highest install target; under
+   * `branch` the catalog's `latestVersion` when it is one, since branch tokens have no order.
+   */
+  latestInstallableVersion: string | null;
+  /**
+   * The display shapes, or `null` when `latestInstallableVersion` is: their `versions` list only
+   * install targets and their `latestVersion` names `latestInstallableVersion`, so a version
+   * picker built from them never offers a version the consumer refuses; their `versionStates`
+   * state every listed version with its refusal.
+   */
+  display: IAppStoreCatalogAppDisplay | null;
+}
+
+const selectLatestInstallableVersion = (appArg: TCatalogApp, installableArg: readonly string[]): string | null => {
+  if (appArg.upgradeStrategy === 'branch') {
+    return installableArg.includes(appArg.latestVersion) ? appArg.latestVersion : null;
+  }
+  const { data } = plugins.servezoneInterfaces;
+  let latest: { version: string; parsed: plugins.servezoneInterfaces.data.IReleaseVersion } | null = null;
+  for (const version of installableArg) {
+    const parsed = data.parseReleaseVersion(version);
+    if (parsed === null) {
+      throw new Error(`App Store catalog app '${appArg.info.id}' lists '${version}', which is not a release version`);
+    }
+    if (latest === null || data.compareReleaseVersions(parsed, latest.parsed) > 0) latest = { version, parsed };
+  }
+  return latest === null ? null : latest.version;
+};
+
+/**
+ * Projects one catalog app for a consumer: every listed version with its install refusal, the
+ * newest install target for this consumer, and the `IAppStoreApp` / `IAppStoreAppMeta` shapes its App Store views
+ * show. Pure: it reads the catalog app and never changes it.
+ */
+export const projectAppStoreCatalogApp = (
+  appArg: TCatalogApp,
+  optionsArg: IAppStoreCatalogProjectionOptions,
+): IAppStoreCatalogAppProjection => {
+  const supportedFeatureIds = [...optionsArg.supportedFeatureIds];
+  const versions = appArg.versions.map((versionArg): TVersionState => ({
+    version: versionArg.version,
+    installRefusal: plugins.servezoneInterfaces.appstore.judgeAppStoreCatalogInstallTarget(
+      versionArg,
+      supportedFeatureIds,
+      optionsArg.consumer,
+    ),
+  }));
+  const installable = versions
+    .filter((versionArg) => versionArg.installRefusal === null)
+    .map((versionArg) => versionArg.version);
+  const latestInstallableVersion = selectLatestInstallableVersion(appArg, installable);
+  const { info } = appArg;
+  const display: IAppStoreCatalogAppDisplay | null = latestInstallableVersion === null
+    ? null
+    : {
+      app: {
+        id: info.id,
+        name: info.name,
+        description: info.description,
+        category: info.category,
+        ...(info.iconName === undefined ? {} : { iconName: info.iconName }),
+        ...(info.iconUrl === undefined ? {} : { iconUrl: info.iconUrl }),
+        latestVersion: latestInstallableVersion,
+        versions: [...installable],
+        versionStates: structuredClone(versions),
+        ...(info.tags === undefined ? {} : { tags: [...info.tags] }),
+        ...(appArg.upgradeStrategy === undefined ? {} : { upgradeStrategy: appArg.upgradeStrategy }),
+      },
+      meta: {
+        id: info.id,
+        name: info.name,
+        description: info.description,
+        category: info.category,
+        ...(info.iconName === undefined ? {} : { iconName: info.iconName }),
+        latestVersion: latestInstallableVersion,
+        versions: [...installable],
+        versionStates: structuredClone(versions),
+        ...(info.maintainer === undefined ? {} : { maintainer: info.maintainer }),
+        ...(info.links === undefined ? {} : { links: { ...info.links } }),
+        ...(info.tags === undefined ? {} : { tags: [...info.tags] }),
+      },
+    };
+  return {
+    appId: info.id,
+    catalogLatestVersion: appArg.latestVersion,
+    versions,
+    latestInstallableVersion,
+    display,
+  };
+};
+
+/** Projects every catalog app, in catalog order (by id). */
+export const projectAppStoreCatalog = (
+  catalogArg: TCatalog,
+  optionsArg: IAppStoreCatalogProjectionOptions,
+): IAppStoreCatalogAppProjection[] => {
+  const options = { supportedFeatureIds: [...optionsArg.supportedFeatureIds], consumer: optionsArg.consumer };
+  return catalogArg.apps.map((appArg) => projectAppStoreCatalogApp(appArg, options));
+};
+
+/**
+ * The App Store listing a consumer serves (`getAppStoreTemplates`): one `IAppStoreApp` per app
+ * that has an install target for it, in catalog order. An app without one is left out of the
+ * listing; its projection (`projectAppStoreCatalogApp`) still states why.
+ */
+export const getAppStoreCatalogListing = (
+  catalogArg: TCatalog,
+  optionsArg: IAppStoreCatalogProjectionOptions,
+): TAppStoreApp[] =>
+  projectAppStoreCatalog(catalogArg, optionsArg).flatMap((projectionArg) =>
+    projectionArg.display === null ? [] : [projectionArg.display.app]);

package/ts_client/readme.md

@@ -1,6 +1,6 @@
 # @serve.zone/appstore Client
 
-This module exports the TypeScript resolver client for the serve.zone App Store. It reads the App Store data bundled into the published `@serve.zone/appstore` package by default and can use an explicit remote source for tests or controlled runtime integrations.
+This module exports the consumer side of the serve.zone App Store runtime catalog: `AppStoreCatalogLoader`, which loads the signed catalog from npm registries and judges it against the consumer's active catalog, the catalog lookups, and the storage handoff a fulfillment adapter receives for a version config. It bundles no App Store data.
 
 ## Issue Reporting and Security
 
@@ -15,37 +15,27 @@ pnpm add @serve.zone/appstore
 ## Usage
 
 ```ts
-import { AppStoreResolver } from '@serve.zone/appstore';
-
-const resolver = new AppStoreResolver();
-const appStore = await resolver.getAppStoreIndex();
-const apps = await resolver.getApps();
-const cloudlyMeta = await resolver.getAppMeta('cloudly');
-const cloudlyConfig = await resolver.getAppVersionConfig('cloudly', cloudlyMeta.latestVersion);
-const sourceInfo = resolver.getSourceInfo();
+import { AppStoreCatalogLoader, findAppStoreCatalogVersion } from '@serve.zone/appstore';
+
+const loader = new AppStoreCatalogLoader({ trustedKeys, supportedFeatureIds });
+const restored = await loader.restoreEnvelopeText(storedText, storedRecord); // at start
+const result = await loader.loadFromRegistries(activeEnvelope ?? null, { signal }); // on the consumer's schedule
+if (result.outcome === 'activated') {
+  // store result.envelope as the last-known-good catalog
+}
 ```
 
-## Remote Source
-
-```ts
-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`. `requestTimeoutMs` bounds each remote catalog, manifest, registry, and response-body operation; it defaults to `30000` and must be a positive integer.
-
 ## Exports
 
-- `AppStoreResolver` resolves App Store indexes, app metadata, version configs, repo manifests, and Docker digest-tracked sources.
-- `appStorePackageMetadata` exposes the package name and version embedded into the generated package data.
-- `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.
+- `AppStoreCatalogLoader` loads the catalog package from the registry list `appstore.resolveAppStoreCatalogRegistries` (`@serve.zone/interfaces`) answers, npmjs by default, checks the tarball's `dist.integrity`, verifies the envelope against the consumer's trusted keys and supported feature ids, and judges its succession; `signal` aborts a load. `restoreEnvelopeText` verifies a stored last-known-good envelope again at start. `judgeImportedEnvelope` and `judgeImportedEnvelopeText` judge an operator-imported envelope the same way as a fetched one. It holds no state, runs no timer and persists nothing; every request is bounded.
+- `findAppStoreCatalogApp` and `findAppStoreCatalogVersion` look up the active catalog; withdrawn versions stay listed (`appstore.judgeAppStoreCatalogInstallTarget` refuses them as targets).
+- `projectAppStoreCatalogApp`, `projectAppStoreCatalog` and `getAppStoreCatalogListing` project the active catalog for one consumer (its supported feature ids, kind and release): every listed version with its install refusal (`versionWithdrawn`, `featuresUnsupported` or `consumerVersionTooOld`), the newest install target, and the `IAppStoreApp` / `IAppStoreAppMeta` shapes the App Store views carry, listing install targets in `versions` and every version in `versionStates`.
+- `normalizeAppStoreStorageConfig` and `normalizeAppStoreVolumes` produce the storage handoff of a catalog version config after the interfaces contract judged its storage.
+- `appStoreCatalogPackageName` and `appStoreCatalogEnvelopePackagePath` name where the catalog is published.
+
+Test fixtures for consumers live in the separate entry `@serve.zone/appstore/testing`.
 
-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.
+Validation of catalogs, version configs and registry lists is owned by `@serve.zone/interfaces` (`appstore.validateAppStoreCatalog`, `appstore.validateAppStoreVersionConfig`, `appstore.validateAppStoreCatalogRegistries`).
 
 ## License and Legal Information