@serve.zone/appstore 32.27.0 → 33.0.0

package/readme.md

@@ -1,6 +1,8 @@
 # @serve.zone/appstore
 
-This repository is the curated App Store index consumed by serve.zone runtimes. It publishes `@serve.zone/appstore`, a small TypeScript client that parses and resolves App Store metadata, linked `servezone.appstore.json` manifests, and Docker digest-tracked image sources.
+The serve.zone App Store: the curated app templates, the publisher that turns them into one signed runtime catalog, and the client Onebox and Cloudly use to load that catalog at runtime.
+
+A consumer never bundles App Store data. It loads the signed catalog from an npm registry in the background, verifies it against the signing keys its own release trusts, keeps the last verified catalog as its last-known-good copy, and picks up new apps and versions without a release of its own. The App Store is never a startup blocker: while no verified catalog is active, only App Store install, upgrade and upgrade-preview are refused.
 
 ## Issue Reporting and Security
 
@@ -18,41 +20,43 @@ The client speaks the `@serve.zone/interfaces` 32 App Store contracts. The stora
 
 | File or directory | Purpose |
 | --- | --- |
-| `appstore.json` | Top-level App Store index with app IDs, display names, descriptions, categories, icons, latest versions, and tags. |
-| `apps/<app>/app.json` | App-specific metadata, maintained version list, and optional links. |
-| `apps/<app>/versions/<version>/config.json` | Deployable version definition: image, internal port, environment variables, platform requirements, and compatibility metadata. |
-| `ts_client/` | Published `@serve.zone/appstore` parser and resolver client. |
-| `source.type=repoManifest` | Optional link to a `servezone.appstore.json` file owned by the upstream app repo. |
+| `apps/<app>/app.json` | The app's catalog `info` (`id`, `name`, `description`, `category`, optional `iconName`, `iconUrl`, `tags`, `maintainer`, `links`), its `latestVersion` and the `versions` it publishes, in order. |
+| `apps/<app>/versions/<version>/config.json` | The version config: digest-pinned image, ports, environment, storage, platform requirements, compatibility minimums and upgrade flags. |
+| `apps/<app>/versions/<version>/withdrawn.json` | Present once a version is withdrawn: `{ "at", "reason" }`. A withdrawal is final. |
+| `catalog.lock.json` | The publication record: every published `app@version` with its config digest and withdrawal. It only grows. |
+| `ts_publisher/` | The catalog publisher (not published): builds `dist_catalog/`, signs it, maintains the lock. |
+| `ts_client/` | The published `@serve.zone/appstore` client: the catalog loader, catalog lookups and the storage handoff. |
+| `dist_catalog/` | Build output, published with the package: `catalog.json`, `catalog.digest` and, in a release, the signed `catalog.envelope.json`. |
 
-Changes are reviewed by reading the JSON data, running the client tests, and testing affected templates in Onebox or Cloudly.
+Nothing else may sit in an app or version folder; the publisher refuses any other file.
 
 ## Current App Store
 
-The App Store currently lists 21 app templates.
-
-| App ID | Name | App Store category | Image | Port |
-| --- | --- | --- | --- | --- |
-| `adminer` | Adminer | Dev Tools | `adminer:latest` | `8080` |
-| `cloudly` | Cloudly | Dev Tools | `code.foss.global/serve.zone/cloudly@sha256:700bb723fef408a6bf8079f643f9990247bffe6541403fd421d064ba8128a447` | `3000` |
-| `ghost` | Ghost | CMS | `ghost:latest` | `2368` |
-| `gitea` | Gitea | Dev Tools | `gitea/gitea:latest` | `3000` |
-| `gitops` | GitOps | Dev Tools | `code.foss.global/serve.zone/gitops:2.13.0` | `3000` |
-| `grafana` | Grafana | Monitoring | `grafana/grafana:latest` | `3000` |
-| `mariadb` | MariaDB | Database | `mariadb:latest` | `3306` |
-| `mattermost` | Mattermost | Communication | `mattermost/mattermost-team-edition:latest` | `8065` |
-| `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` |
-| `valkey` | Valkey | Database | `valkey/valkey:9.1.0-alpine` | `6379` |
-| `rustdesk-server` | RustDesk Server | Remote Access | `rustdesk/rustdesk-server-s6:latest` | `21116` |
-| `siprouter` | SIP Router | Communication | `code.foss.global/serve.zone/siprouter:1.28.0` | `3060` |
-| `uptime-kuma` | Uptime Kuma | Monitoring | `louislam/uptime-kuma:latest` | `3001` |
-| `vaultwarden` | Vaultwarden | Security | `vaultwarden/server:latest` | `80` |
-| `wordpress` | WordPress | CMS | `wordpress:latest` | `80` |
+The catalog lists 19 apps. Every image is pinned to the digest of its multi-platform index.
+
+| App ID | Name | App Store category | Latest | Image | Port |
+| --- | --- | --- | --- | --- | --- |
+| `adminer` | Adminer | Dev Tools | `1.0.0` | `adminer@sha256:74f29c416e148b98305e84446a18db7cd2c1038264dec464359d36774ef080ce` | `8080` |
+| `cloudly` | Cloudly | Dev Tools | `1.27.0` | `code.foss.global/serve.zone/cloudly@sha256:700bb723fef408a6bf8079f643f9990247bffe6541403fd421d064ba8128a447` | `3000` |
+| `ghost` | Ghost | CMS | `1.0.0` | `ghost@sha256:9482099b1c8700764dc3d38c293e09c16d70f8bacc14af589c47d90b4bebd017` | `2368` |
+| `gitea` | Gitea | Dev Tools | `1.0.0` | `gitea/gitea@sha256:a9dc25679ebdd33356242d2e0667cc220043745e8339922879f187c20329a42e` | `3000` |
+| `grafana` | Grafana | Monitoring | `1.0.0` | `grafana/grafana@sha256:b28bae15e219c998fb0e0424ed724930cc61b1f61fb404d47c862f9a23f9e572` | `3000` |
+| `mariadb` | MariaDB | Database | `1.0.0` | `mariadb@sha256:f1bba652ba57bea3099ca2fe1af692af537c27d96e0bcde39dce29e2ba1ec4f3` | `3306` |
+| `mattermost` | Mattermost | Communication | `1.0.0` | `mattermost/mattermost-team-edition@sha256:6ad5912b45875ef2fafc41886b5a70a3ec1b6c17ec706e0492566e8a2fd8aa85` | `8065` |
+| `n8n` | N8N | Automation | `1.0.0` | `n8nio/n8n@sha256:240eaa2a3d491adac5817aa4c3f1c521bb18ec79f6e448517158d5220ee0f37b` | `5678` |
+| `nextcloud` | Nextcloud | Storage | `1.0.0` | `nextcloud@sha256:4ba2af4695e1801b5f66ed4df863c0fa0f236f632ffd04b2fdc32ee0c2fefe42` | `80` |
+| `nginx` | Nginx | Web Server | `1.0.0` | `nginx@sha256:df221db836e1754089190208cee7eeda94f233197056426eda74a43ab1abeac2` | `80` |
+| `openbao` | OpenBao | Security | `1.0.0` | `openbao/openbao@sha256:900bb64d0671cd1d82b693c56206f7263b582445f3a3bb6ba6e5213f524a6653` | `8200` |
+| `plausible` | Plausible Analytics | Analytics | `1.0.0` | `plausible/analytics@sha256:cd5f75e1399073669b13b4151cc603332a825324d0b8f13dfc9de9112a3c68a1` | `8000` |
+| `portainer` | Portainer | Dev Tools | `1.0.0` | `portainer/portainer-ce@sha256:4d616db18cfeb5dd41a69c0958bc825c84483ea9cde1106eb82a5d26f3bd8b0e` | `9000` |
+| `postgres` | PostgreSQL | Database | `1.0.0` | `postgres@sha256:721873c34ceb9f8d8fc265984940dc982404c105f19ad51be9fdc5970a6080ea` | `5432` |
+| `rustdesk-server` | RustDesk Server | Remote Access | `1.0.0` | `rustdesk/rustdesk-server-s6@sha256:5974cd791a5aca6fbf01a167b37e7427db1d136e95b2710c33a34fdc9fea724c` | `21116` |
+| `uptime-kuma` | Uptime Kuma | Monitoring | `1.0.0` | `louislam/uptime-kuma@sha256:70233f4acb5163fd2a59a49909cf01e44415cecff13dba69e3a86647a2919f83` | `3001` |
+| `valkey` | Valkey | Database | `1.0.0` | `valkey/valkey@sha256:c9b77919daeba2c02ad954d0c844cc4e7142069d177b89c5fd771f405daf9e02` | `6379` |
+| `vaultwarden` | Vaultwarden | Security | `1.0.0` | `vaultwarden/server@sha256:efb3cde962015fcc036b2ea625242248611943b27212ebf4392841fb30fad055` | `80` |
+| `wordpress` | WordPress | CMS | `1.0.0` | `wordpress@sha256:736761c95c327cb21602ab9175ee4dba6e779b00f3f4895536a3e1af5ac4fe4c` | `80` |
+
+Cloudly `1.0.0` and `1.1.0` are withdrawn: they were floating-tag templates (`cloudly:latest`) and stay listed, pinned to the image that tag served when the catalog was created, only so that services installed from them keep reading their config. Install `1.21.0` or later.
 
 ## Platform Requirements
 
@@ -69,7 +73,6 @@ Some templates ask Onebox to provision local platform services and inject connec
 | `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. |
 | `plausible` | ClickHouse | Declares ClickHouse as a platform requirement. |
-| `siprouter` | MongoDB, S3 | Uses SmartData state and object storage for telephony-related runtime data. |
 | `wordpress` | MariaDB | Uses standard WordPress database environment variables. |
 
 Standalone templates such as `nginx`, `adminer`, `valkey`, `portainer`, `mattermost`, `n8n`, `uptime-kuma`, and `vaultwarden` currently define only image and port unless their version config adds explicit environment variables. `rustdesk-server` uses the official all-in-one s6 image and requires `RELAY` to advertise the public relay endpoint; RustDesk clients also require firewall access to TCP `21115`, TCP/UDP `21116`, TCP `21117`, and optional web-client TCP `21118`/`21119`.
@@ -80,7 +83,7 @@ Version configs use a small, pragmatic schema understood by serve.zone runtimes:
 
 ```jsonc
 {
-  "image": "container/image:tag",
+  "image": "container/image@sha256:<64 lower-case hex>",
   "port": 8080,
   "envVars": [
     {
@@ -125,8 +128,12 @@ Secret declarations never contain values. Each declares exactly one `file` or
 required by upstream images; secret and platform-owned environment identities
 remain uppercase canonical keys.
 
-`platformRequirements.s3: true` and `volumes` are legacy inputs. The resolver
-normalizes them deterministically for existing templates, but new templates use
+Every image is digest-pinned (`name@sha256:…`); the catalog contract refuses a
+tag-only image.
+
+`platformRequirements.s3: true` and `volumes` are legacy inputs.
+`normalizeAppStoreStorageConfig` 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`,
@@ -253,21 +260,20 @@ 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:
+Every version config is judged by the catalog contract of `@serve.zone/interfaces`
+(`appstore.validateAppStoreCatalog`, which applies `appstore.validateAppStoreVersionConfig`
+to every config); this package has no validator of its own. Before provisioning, a
+runtime advertises its supported feature IDs and calls the fail-closed normalization
+entry point:
 
 ```ts
-const normalizedStorage = resolver.normalizeStorageConfig(config, {
+import { normalizeAppStoreStorageConfig } from '@serve.zone/appstore';
+
+const normalizedStorage = normalizeAppStoreStorageConfig(catalogVersion.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
@@ -281,79 +287,142 @@ 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:
+## The Runtime Catalog
 
-```jsonc
-{
-  "app": {
-    "id": "cloudly",
-    "name": "Cloudly",
-    "description": "Multi-node serve.zone control plane.",
-    "category": "Dev Tools"
-  },
-  "latestVersion": "latest",
-  "source": {
-    "type": "dockerImage",
-    "image": "code.foss.global/serve.zone/cloudly:latest",
-    "tracking": "digest"
-  },
-  "runtime": {
-    "image": "code.foss.global/serve.zone/cloudly:latest",
-    "port": 3000
-  }
-}
-```
+The catalog is one document, `IAppStoreCatalog` of the `@serve.zone/interfaces` App Store catalog contract: every app, every published version and every version's full config with its `configDigest`, plus `contract`, `revision`, `publishedAt` and `sourceRevision`. A release ships it as an `IAppStoreCatalogEnvelope`: the catalog, its `catalogDigest` and one or more Ed25519 signatures.
+
+- `revision` is `major × 10¹² + minor × 10⁶ + patch` of the package version (`33.0.0` → `33000000000000`). Package versions only grow, so every release's catalog has a greater revision than the one before, and a consumer refuses any catalog whose revision is not greater than its active one (`revisionRegressed`). A prerelease version is refused. A catalog published from an older release line therefore never replaces a newer one.
+- `sourceRevision` is the commit the catalog was built from and `publishedAt` that commit's committer time, so the same commit always builds the same catalog.
+- Apps are ordered by id; versions in the order `app.json` lists them.
+- A published `app@version` never changes and never disappears. A version is retired by withdrawing it (`withdrawn.json`); it stays listed with its config and is refused as an install or upgrade target. `catalog.lock.json` records every published version, and the build and the test suite refuse a catalog that removes, rewrites or reinstates one. Consumers apply the same rules between two catalogs (`publishedVersionRemoved`, `publishedVersionMutated`, `publishedWithdrawalChanged`).
+
+## Publishing A Catalog
+
+| Command | What it does |
+| --- | --- |
+| `pnpm build` | Compiles, then writes `dist_catalog/catalog.json` and `dist_catalog/catalog.digest`. Signs as well when `SERVEZONE_APPSTORE_CATALOG_SIGNING_KEY_FILE` is set. |
+| `pnpm run build:release` | The release build (`.smartconfig.json` `release.preflight.buildCommand`). Refuses a dirty working tree, any version `catalog.lock.json` does not record, and a missing signing key; writes the signed `dist_catalog/catalog.envelope.json`. |
+| `pnpm run catalog:lock` | Records every new version (and every new withdrawal) in `catalog.lock.json`; refuses a catalog that violates it. Run it, and commit the lock, with every new version or withdrawal. |
+| `pnpm run catalog:trustedkey` | Prints the `{ keyId, publicKey }` record consumers ship for the configured signing key. |
+
+`SERVEZONE_APPSTORE_CATALOG_SIGNING_KEY_FILE` names a file holding the PKCS#8 PEM of an Ed25519 private key (`openssl genpkey -algorithm ed25519`); the key itself never appears in arguments or logs. A release refuses to ship without it twice: `build:release` fails, and the package exports `./catalog.envelope.json`, so gitzone's entry-point check refuses a tarball that does not carry the envelope.
+
+### Signing Key And Rotation
+
+A release signs with exactly one key: the one `SERVEZONE_APPSTORE_CATALOG_SIGNING_KEY_FILE` names. Consumers ship the trusted keys (`IAppStoreCatalogTrustedKey`, printed by `pnpm run catalog:trustedkey`) with their own release, and an envelope verifies when one of its signatures is by a key the consumer trusts. Rotating the key is therefore trust first, switch second:
 
-When `tracking` is `digest`, Onebox resolves the Docker manifest digest and treats digest changes as App Store upgrades while keeping the image reference simple for deployment.
+1. Generate the new key and print its trusted-key record.
+2. Release Onebox and Cloudly trusting both the current and the new key. Catalogs signed with the current key keep activating everywhere.
+3. Once every running consumer trusts the new key, point the variable at the new key file for the next App Store release. A consumer that still trusts only the old key refuses that catalog (`signatureInvalid`, no signature by a trusted key) and keeps its last-known-good catalog until it is upgraded.
+4. Release Onebox and Cloudly without the old key.
 
-Neither the index nor a linked manifest states a schema version. Published documents that still carry a `schemaVersion` member are read unchanged — the readers ignore it — so a catalog can be republished without the member at any time.
+A compromised key follows the same steps, with step 2 dropping the compromised key at once: consumers then refuse every catalog until the first one signed with the new key is published. The contract allows up to eight signatures per envelope, but this publisher signs with one key; signing with two keys at once is not supported.
 
-## Client Usage
+### Signing Key Custody
+
+The signing key is a key file on the release machine, outside every repository, held by the release operator; nothing in this repository, its CI or its logs carries it. A release runs with `SERVEZONE_APPSTORE_CATALOG_SIGNING_KEY_FILE` naming that file:
+
+- gitzone passes its environment to the release build, which it runs as `pnpm run build:release` in a clean checkout of the release commit; the publisher reads the file (`importAppStoreCatalogSigningKeyPem` of `@serve.zone/interfaces/runtime`), signs the catalog, verifies the envelope against the key's own trusted-key record and writes `dist_catalog/catalog.envelope.json` into the package gitzone publishes. It logs the key id and public key only.
+- The Gitea tag workflow (`.gitea/workflows/release.yml`) has no key: it builds the unsigned catalog of the tag and attaches `catalog.json` and `catalog.digest`, whose digest equals the published envelope's `catalogDigest`.
+- Generate a key with `openssl genpkey -algorithm ed25519 -out <key file>` on the release machine and keep the file readable by the release user only; `pnpm run catalog:trustedkey` with the variable set prints the record Onebox and Cloudly ship. Losing the file means rotating to a new key as above.
+
+## Loading The Catalog
 
 ```ts
-import { AppStoreResolver } from '@serve.zone/appstore';
+import { AppStoreCatalogLoader } from '@serve.zone/appstore';
+
+const loader = new AppStoreCatalogLoader({
+  trustedKeys,                        // IAppStoreCatalogTrustedKey[] shipped with this release
+  supportedFeatureIds,                // the requiresFeatures ids this consumer fulfils
+  registries: configuredRegistries,   // empty or absent: the default, npmjs
+  requestTimeoutMs: 30_000,           // per request, body included; the default
+});
 
-const resolver = new AppStoreResolver();
-const appStore = await resolver.getAppStoreIndex();
-const cloudly = await resolver.getAppMeta('cloudly');
-const config = await resolver.getAppVersionConfig('cloudly', cloudly.latestVersion);
+// At start: the stored last-known-good envelope, verified again against today's trust.
+const restored = await loader.restoreEnvelopeText(storedText, { origin: storedOrigin, loadedAt: storedLoadedAt });
+// 'restored'  activate restored.envelope; status.active = restored.active
+// 'refused'   no active catalog: status unavailable, cause 'refused', refused = restored.refused
+
+// On the consumer's schedule, never awaited by startup or a request:
+const result = await loader.loadFromRegistries(activeEnvelope ?? null, { signal: stopController.signal });
+// 'activated'  store result.envelope as last-known-good; status.active = result.active
+// 'unchanged'  nothing to store
+// 'refused'    keep the active catalog; status.refused = result.refused
+// 'failed'     keep the active catalog; retry with backoff
+// Always: status.lastAttempt = result.attempt; result.registries reports each registry's answer.
+// An aborted signal rejects the load with its reason: the consumer is stopping, nothing is recorded.
 ```
 
-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`.
+One load asks every configured registry for the package its `latest` dist-tag names, downloads the tarball (bounded in time and size, its unpacked size bounded too), checks it against the registry's `dist.integrity`, extracts `dist_catalog/catalog.envelope.json`, verifies it with `verifyAppStoreCatalogEnvelope` (shape, digest, a signature by a trusted key, contract, schema with the consumer's `supportedFeatureIds`, every config digest) and judges it against the active catalog with `judgeAppStoreCatalogSuccession`. The first registry whose catalog activates ends the load; otherwise the result is the first `unchanged`, else the first `refused`, else `failed`. Transport, integrity and packaging failures and every refusal are results, never exceptions; an envelope the verifier cannot read is refused as `schemaInvalid`.
 
-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.
+The registry list follows the one rule of `@serve.zone/interfaces`: `appstore.validateAppStoreCatalogRegistries` (`https:` base URLs without credentials, query or fragment, each registry once) and `appstore.resolveAppStoreCatalogRegistries` (an empty list means `appStoreCatalogDefaultRegistries`). A consumer validates an operator's setting with the same function before it stores it.
 
-Only include keys that are actually needed by a template. For example, `nginx` is currently just:
+The loader holds the consumer's options and nothing else: no catalog, no timer, no schedule, no persistence. The consumer's catalog runtime owns the one schedule of its process. The cadence Onebox and Cloudly follow, as guidance:
 
-```json
-{
-  "image": "nginx:alpine",
-  "port": 80
-}
+- restore the stored envelope at start and start the first load in the background, without waiting for it;
+- load every 15 minutes while the last attempt activated or answered `unchanged` or `refused`;
+- after a `failed` attempt, retry after 1 minute, doubling to at most 30 minutes, and return to 15 minutes after the next success;
+- run one load at a time, abort it with the signal on stop, and answer an administrator's refresh with one load now.
+
+An operator-imported envelope (an offline signed bundle, or the envelope a package carries at `@serve.zone/appstore/catalog.envelope.json`) is judged the same way with `judgeImportedEnvelope(value, active)` or `judgeImportedEnvelopeText(text, active)`; its activation reports `origin: 'operatorImport'`.
+
+### Showing The Catalog
+
+```ts
+import { getAppStoreCatalogListing, projectAppStoreCatalogApp } from '@serve.zone/appstore';
+
+const consumer = { supportedFeatureIds, consumer: { kind: 'onebox', version: oneboxVersion } };
+const apps = getAppStoreCatalogListing(activeCatalog, consumer); // IAppStoreApp[] for getAppStoreTemplates
+const projection = projectAppStoreCatalogApp(catalogApp, consumer);
+// projection.versions:                every listed version, each with installRefusal (null, versionWithdrawn,
+//                                     featuresUnsupported or consumerVersionTooOld)
+// projection.latestInstallableVersion the newest version this consumer may install, or null
+// projection.display                  { app: IAppStoreApp, meta: IAppStoreAppMeta }, or null without an install target
 ```
 
+The display shapes list only the versions this consumer may install in `versions` and name the newest of them as `latestVersion`, so a version picker built from them never offers a withdrawn version, one gated on a feature the consumer lacks or one that needs a newer consumer release; `versionStates` states every listed version with its refusal. Under `semver` the newest install target is the highest one; under `branch` it is the catalog's `latestVersion` when that is an install target, and otherwise the app has none.
+
+### Testing A Consumer
+
+`@serve.zone/appstore/testing` serves a consumer's tests, never its runtime: `createAppStoreTestSigningKey` makes a throwaway key and its trusted-key record, `createAppStoreTestCatalog` and `createAppStoreTestVersionConfig` a catalog the contract accepts, `signAppStoreTestCatalog` its envelope, `createAppStoreTestPackageTarball` the package tarball carrying it, `createAppStoreTestRegistry` a registry stub and `createAppStoreTestFetch` the `fetch` a loader under test is given.
+
+The published Cloudly templates are qualified here (`test/test.cloudlytemplates.node.ts`: pinned image, Onebox minimum, upgrade flags and platform OIDC of every template), so a template release needs no host test change.
+
+## Migrating From 32.x
+
+- `AppStoreResolver` and its `package` and `remote` source modes are gone, with the bundled `data.generated.ts`, `appStorePackageMetadata`, `appStoreDefaultRemoteBaseUrl` and `getSourceInfo()`. Load the signed catalog with `AppStoreCatalogLoader`, keep the last verified envelope in your database (restore it with `restoreEnvelopeText`), and read apps and versions from it (`findAppStoreCatalogApp`, `findAppStoreCatalogVersion`). Snapshot a service's version config and `configDigest` at install and upgrade; runtime paths read that snapshot, not the catalog.
+- Linked `servezone.appstore.json` manifests (`source.type=repoManifest`), `dockerImage` sources and digest tracking (`upgradeStrategy: 'dockerDigest'`) are gone: every version is a catalog entry with a digest-pinned image. `parseAppStoreIndex`, `parseServezoneAppStoreManifest`, `parseDockerImageReference` and `createAppStoreVersionForDockerSource` are removed.
+- `resolver.getApps()` is `getAppStoreCatalogListing(catalog, { supportedFeatureIds, consumer })` and `resolver.getAppMeta(appId)` is `projectAppStoreCatalogApp(app, { supportedFeatureIds, consumer }).display?.meta`; `resolver.getAppVersionConfig(appId, version)` is `findAppStoreCatalogVersion(catalog, appId, version)?.config`.
+- Executable `migrate-from-*.ts` scripts are no longer supported; a version folder holds only `config.json` and `withdrawn.json`.
+- Validation is owned by `@serve.zone/interfaces`: use `appstore.validateAppStoreVersionConfig` instead of `resolver.validateAppStoreVersionConfig`, and the storage contract instead of `validateAppStoreStorageConfig` and `parseStorageCapacityQuantity`.
+- `resolver.normalizeStorageConfig(config, options, label)` is `normalizeAppStoreStorageConfig(config, options, label)`, and `resolver.normalizeVolumes(volumes)` is `normalizeAppStoreVolumes(config, label)`; both read the catalog version config shape (`appstore.TAppStoreCatalogVersionConfig`).
+- The package no longer ships `apps/`, `appstore.json` or `appstore.resolved.json`; `appstore.json` is folded into each `app.json`.
+
 ## Working With Templates
 
-- Keep `appstore.json`, `apps/<app>/app.json`, and each version config in sync when adding or changing an app.
-- 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.
+- A new version is a new `apps/<app>/versions/<version>/config.json`, listed in `app.json` `versions` (and `latestVersion` when it is the highest). Never edit a published version: publish a new one, and withdraw the old one with `withdrawn.json` when it must not be installed any more.
+- Pin every image to the digest of its multi-platform index (`name@sha256:…`) and record the tag and digest in the changelog.
+- Run `pnpm run catalog:lock` and commit `catalog.lock.json` with every new version or withdrawal; the test suite fails on an unlocked or changed version.
+- Gate a version that uses a config member newer than the catalog contract's minor on a feature id in `requiresFeatures`, so older consumers keep loading the rest of the catalog.
 - 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}`, `${S3_SECRET_KEY}`, `${MAIL_FROM}`, `${SMTP_HOST}`, `${SMTP_PORT}`, `${SMTP_USERNAME}`, and `${SMTP_PASSWORD}` 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.
 
 ## Project Map
 
 ```text
 appstore/
-├── appstore.json
-├── ts_client/
-└── apps/
-    ├── cloudly/
-    │   ├── app.json
-    │   └── versions/<version>/config.json
-    └── ...
+├── apps/
+│   ├── cloudly/
+│   │   ├── app.json
+│   │   └── versions/<version>/config.json (+ withdrawn.json)
+│   └── ...
+├── catalog.lock.json
+├── ts_publisher/   catalog builder, signing, lock (not published)
+├── ts_client/      AppStoreCatalogLoader, catalog lookups, storage handoff
+└── dist_catalog/   build output: catalog.json, catalog.digest, catalog.envelope.json
 ```
 
 ## License and Legal Information

package/ts_client/catalog.ts

@@ -0,0 +1,26 @@
+import type * as plugins from './plugins.js';
+
+type TCatalog = plugins.servezoneInterfaces.appstore.IAppStoreCatalog;
+type TCatalogApp = plugins.servezoneInterfaces.appstore.IAppStoreCatalogApp;
+type TCatalogVersion = plugins.servezoneInterfaces.appstore.IAppStoreCatalogVersion;
+
+/** The npm package that carries the signed App Store catalog. */
+export const appStoreCatalogPackageName = '@serve.zone/appstore';
+
+/** Where the signed envelope sits inside the published package (and its `./catalog.envelope.json` export). */
+export const appStoreCatalogEnvelopePackagePath = 'dist_catalog/catalog.envelope.json';
+
+/** The app a catalog lists under `appIdArg`. */
+export const findAppStoreCatalogApp = (catalogArg: TCatalog, appIdArg: string): TCatalogApp | undefined =>
+  catalogArg.apps.find((appArg) => appArg.info.id === appIdArg);
+
+/**
+ * The listed `app@version`, withdrawn ones included: an installed service keeps reading its
+ * version. Whether it is an install or upgrade target is `appstore.judgeAppStoreCatalogInstallTarget`.
+ */
+export const findAppStoreCatalogVersion = (
+  catalogArg: TCatalog,
+  appIdArg: string,
+  versionArg: string,
+): TCatalogVersion | undefined =>
+  findAppStoreCatalogApp(catalogArg, appIdArg)?.versions.find((entryArg) => entryArg.version === versionArg);

package/ts_client/index.ts

@@ -1,3 +1,5 @@
-export * from './classes.appstoreresolver.js';
+export * from './catalog.js';
+export * from './loader.js';
+export * from './projection.js';
 export * from './storage.js';
 export * from './types.js';