@serve.zone/appstore 32.26.0 → 33.0.0

package/.smartconfig.json

@@ -6,7 +6,7 @@
       "githost": "code.foss.global",
       "gitscope": "serve.zone",
       "gitrepo": "appstore",
-      "description": "serve.zone App Store metadata, parser, and resolver client.",
+      "description": "serve.zone App Store: the signed runtime catalog and its consumer loader.",
       "npmPackagename": "@serve.zone/appstore",
       "license": "MIT",
       "projectDomain": "serve.zone",
@@ -20,6 +20,9 @@
       ]
     },
     "release": {
+      "preflight": {
+        "buildCommand": "pnpm run build:release"
+      },
       "targets": {
         "git": {
           "enabled": true,

package/changelog.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 2026-10-08 - 33.0.0
+
+### Breaking Changes
+
+- replace the bundled resolver with the signed runtime catalog (catalog)
+  - The package publishes one signed App Store catalog (`@serve.zone/interfaces` catalog contract 1.0) at `dist_catalog/catalog.envelope.json`, exported as `@serve.zone/appstore/catalog.envelope.json`, and no longer ships `apps/`, `appstore.json` or `appstore.resolved.json`.
+  - Removed: `AppStoreResolver` with its `package` (bundled `data.generated.ts`) and raw-branch `remote` source modes, `getSourceInfo()`, `appStorePackageMetadata`, `appStoreDefaultRemoteBaseUrl`, linked `servezone.appstore.json` manifests (`repoManifest`), `dockerImage` sources and live digest resolution, the silent fall-back from `appstore.resolved.json` to `appstore.json`, executable `migrate-from-*.ts` support, `parseAppStoreIndex`, `parseServezoneAppStoreManifest`, `parseDockerImageReference`, `createAppStoreVersionForDockerSource`, `validateAppStoreStorageConfig`, `parseStorageCapacityQuantity`, the bundled data `appStorePackageData` with its type `IAppStorePackageData`, the resolver types `IResolvedAppStoreApp`, `IAppStoreResolverOptions` and `IAppStoreSourceInfo`, `IParsedDockerImageReference`, `TServezoneAppStoreManifest` and the `TAppStore*` type aliases. Catalog and version-config validation is owned by `@serve.zone/interfaces` (`appstore.validateAppStoreCatalog`, `appstore.validateAppStoreVersionConfig`).
+  - Migration for Onebox and Cloudly: replace `new AppStoreResolver(...)` (and Cloudly's `APPSTORE_URL` remote mode) with a background `AppStoreCatalogLoader` that is never awaited by startup; store each activated envelope as the last-known-good catalog in NoSQLDB, restore it at start with `restoreEnvelopeText`, and report `TAppStoreCatalogStatus` (`unavailable` with its reason and cause until a verified catalog is active, refusing only App Store install, upgrade and upgrade preview). Ship the trusted signing keys with the release and pass the supported feature ids and the consumer (`{ kind, version }`). Read apps and versions with `findAppStoreCatalogApp` and `findAppStoreCatalogVersion`, judge targets with `appstore.judgeAppStoreCatalogInstallTarget(version, supportedFeatureIds, consumer)`, and snapshot a service's version config and `configDigest` at install and upgrade (`IService.data.appStoreTemplate`, `appstore.createAppStoreServiceTemplateSnapshot`) instead of re-reading the catalog. The projections take `{ supportedFeatureIds, consumer }` instead of the feature ids alone. `resolver.normalizeStorageConfig(config, options, label)` becomes `normalizeAppStoreStorageConfig(config, options, label)` and `resolver.normalizeVolumes(volumes)` becomes `normalizeAppStoreVolumes(config, label)`, both on the catalog version config shape.
+- pin every image to a digest and fix the published versions (catalog)
+  - Every version's image is now pinned to the digest of the multi-platform index its tag named at catalog creation (2026-10-06 12:54 UTC), so a version installs the same image everywhere. The 20 tag-only references:
+  - adminer@1.0.0: `adminer:latest` → `sha256:74f29c416e148b98305e84446a18db7cd2c1038264dec464359d36774ef080ce` (OCI index, 8 platforms)
+  - cloudly@1.0.0, cloudly@1.1.0: `code.foss.global/serve.zone/cloudly:latest` → `sha256:490b8b153c6adba6eb7abbea1312ecb9db92c840b5330caa625d21f4e93e03f1` (OCI index, 2 platforms)
+  - ghost@1.0.0: `ghost:latest` → `sha256:9482099b1c8700764dc3d38c293e09c16d70f8bacc14af589c47d90b4bebd017` (OCI index, 3 platforms)
+  - gitea@1.0.0: `gitea/gitea:latest` → `sha256:a9dc25679ebdd33356242d2e0667cc220043745e8339922879f187c20329a42e` (OCI index, 3 platforms)
+  - grafana@1.0.0: `grafana/grafana:latest` → `sha256:b28bae15e219c998fb0e0424ed724930cc61b1f61fb404d47c862f9a23f9e572` (Docker manifest list, 3 platforms)
+  - mariadb@1.0.0: `mariadb:latest` → `sha256:f1bba652ba57bea3099ca2fe1af692af537c27d96e0bcde39dce29e2ba1ec4f3` (OCI index, 4 platforms)
+  - mattermost@1.0.0: `mattermost/mattermost-team-edition:latest` → `sha256:6ad5912b45875ef2fafc41886b5a70a3ec1b6c17ec706e0492566e8a2fd8aa85` (OCI index, 1 platform)
+  - n8n@1.0.0: `n8nio/n8n:latest` → `sha256:240eaa2a3d491adac5817aa4c3f1c521bb18ec79f6e448517158d5220ee0f37b` (OCI index, 2 platforms)
+  - nextcloud@1.0.0: `nextcloud:latest` → `sha256:4ba2af4695e1801b5f66ed4df863c0fa0f236f632ffd04b2fdc32ee0c2fefe42` (OCI index, 8 platforms)
+  - nginx@1.0.0: `nginx:alpine` → `sha256:df221db836e1754089190208cee7eeda94f233197056426eda74a43ab1abeac2` (OCI index, 8 platforms)
+  - openbao@1.0.0: `openbao/openbao:2.6.0` → `sha256:900bb64d0671cd1d82b693c56206f7263b582445f3a3bb6ba6e5213f524a6653` (OCI index, 6 platforms)
+  - plausible@1.0.0: `plausible/analytics:latest` → `sha256:cd5f75e1399073669b13b4151cc603332a825324d0b8f13dfc9de9112a3c68a1` (Docker manifest list, 2 platforms)
+  - portainer@1.0.0: `portainer/portainer-ce:latest` → `sha256:4d616db18cfeb5dd41a69c0958bc825c84483ea9cde1106eb82a5d26f3bd8b0e` (OCI index, 7 platforms)
+  - postgres@1.0.0: `postgres:16-alpine` → `sha256:721873c34ceb9f8d8fc265984940dc982404c105f19ad51be9fdc5970a6080ea` (OCI index, 8 platforms)
+  - rustdesk-server@1.0.0: `rustdesk/rustdesk-server-s6:latest` → `sha256:5974cd791a5aca6fbf01a167b37e7427db1d136e95b2710c33a34fdc9fea724c` (OCI index, 4 platforms)
+  - uptime-kuma@1.0.0: `louislam/uptime-kuma:latest` → `sha256:70233f4acb5163fd2a59a49909cf01e44415cecff13dba69e3a86647a2919f83` (OCI index, 3 platforms)
+  - valkey@1.0.0: `valkey/valkey:9.1.0-alpine` → `sha256:c9b77919daeba2c02ad954d0c844cc4e7142069d177b89c5fd771f405daf9e02` (Docker manifest list, 4 platforms)
+  - vaultwarden@1.0.0: `vaultwarden/server:latest` → `sha256:efb3cde962015fcc036b2ea625242248611943b27212ebf4392841fb30fad055` (OCI index, 4 platforms)
+  - wordpress@1.0.0: `wordpress:latest` → `sha256:736761c95c327cb21602ab9175ee4dba6e779b00f3f4895536a3e1af5ac4fe4c` (OCI index, 8 platforms)
+  - gitops 1.0.0 (`code.foss.global/serve.zone/gitops:2.13.0`) and siprouter 1.0.0 (`code.foss.global/serve.zone/siprouter:1.28.0`) are left out of the catalog: neither image exists in the registry (manifest unknown; the gitops repository holds only `32.0.0` to `32.2.1` and `latest`, the siprouter repository no tag), so neither template was installable. Both apps return as new versions once real images are published. Services installed from them keep the snapshot their host takes from this transition release.
+  - Cloudly 1.0.0 and 1.1.0 are withdrawn (`superseded; floating-tag era template pinned at catalog creation — install 1.21.0 or later`): they named `cloudly:latest`, which now serves a build that no Cloudly template was released for. They stay listed so that installed services keep reading their config.
+  - `catalog.lock.json` records every published `app@version` with its config digest and withdrawal; the build and the test suite refuse a catalog that removes, rewrites or reinstates a recorded version, and a release refuses an unrecorded one.
+  - The Cloudly templates 1.22.0 to 1.27.0, published in the bundled releases 32.22.0 to 32.27.0, are carried into the catalog unchanged and recorded in `catalog.lock.json`; 1.27.0 is Cloudly's latest version.
+  - The tag workflow no longer attaches an npm tarball or the `appstore.json` and `apps/` data archive: it builds the unsigned catalog of the tag and attaches `catalog.json`, `catalog.digest` and their `SHA256SUMS.txt` to the Gitea release. The signed envelope ships only in the npm package; the same commit builds the same catalog, so the attached digest is the envelope's `catalogDigest`.
+  - `appstore.json` is folded into each `app.json`: the catalog carries one `info` per app, taking the store listing's name, description, category, icon and tags and the app's maintainer and links. Apps are ordered by id.
+
+### Features
+
+- publish the catalog from the source tree (publisher)
+  - `pnpm build` writes `dist_catalog/catalog.json` and `catalog.digest`; with `SERVEZONE_APPSTORE_CATALOG_SIGNING_KEY_FILE` naming a PKCS#8 Ed25519 key file it also writes the signed envelope. The catalog `revision` is `major × 10¹² + minor × 10⁶ + patch` of the package version (prereleases refused), `sourceRevision` the built commit and `publishedAt` its commit time, so a commit always builds the same catalog and every release's revision is greater than the one before.
+  - `pnpm run build:release`, now the release build (`release.preflight.buildCommand`), refuses a dirty tree, unrecorded versions and a missing signing key, and the `./catalog.envelope.json` export makes gitzone refuse a tarball without the envelope. The key is a key file on the release machine, named by `SERVEZONE_APPSTORE_CATALOG_SIGNING_KEY_FILE` and read with `importAppStoreCatalogSigningKeyPem` of `@serve.zone/interfaces/runtime`; errors name the file, never its content, and nothing in the repository or CI carries the key. A release signs with exactly one key; the readme states the custody and the key rotation (consumers trust the new key first, the publisher switches second).
+  - `pnpm run catalog:lock` records new versions and withdrawals; `pnpm run catalog:trustedkey` prints the trusted-key record consumers ship.
+- load the catalog at runtime (client)
+  - `AppStoreCatalogLoader.loadFromRegistries(active, { signal })` asks each configured registry for the `latest` package, checks the tarball against `dist.integrity`, extracts the envelope, verifies it against the consumer's trusted keys and supported feature ids (`verifyAppStoreCatalogEnvelope`) and judges it against the active catalog (`judgeAppStoreCatalogSuccession`). It answers `activated` (with the status `active` record), `unchanged`, `refused` (with the status `refused` record) or `failed`, plus the attempt and each registry's answer. Requests are bounded in time and size, the tarball's unpacked size too (`maximumTarballBytes`, `maximumUnpackedBytes`), fetch and clock are injectable, and an envelope the verifier cannot read is refused as `schemaInvalid`. Aborting `signal` ends a load at once, requests in flight included, and rejects it with the signal's reason.
+  - `judgeImportedEnvelope` and `judgeImportedEnvelopeText` judge an operator-imported envelope the same way (`origin: 'operatorImport'`), and `restoreEnvelopeText(text, { origin, loadedAt })` verifies a stored last-known-good envelope again at start against today's trusted keys and features, answering the `active` record or the refusal.
+  - The loader holds no catalog, runs no timer and persists nothing: each consumer's catalog runtime owns the one schedule of its process; the readme states the cadence Onebox and Cloudly follow. Registry lists follow `appstore.validateAppStoreCatalogRegistries` and `appstore.resolveAppStoreCatalogRegistries` of `@serve.zone/interfaces`; an empty list means the default, npmjs. A request never follows a redirect: a registry that answers with one fails, so the manifest and the tarball are only ever read over https.
+- project the catalog for the App Store views (client)
+  - `projectAppStoreCatalogApp(app, { supportedFeatureIds, consumer })` and `projectAppStoreCatalog(catalog, { supportedFeatureIds, consumer })` give every listed version with its install refusal (`versionWithdrawn` with the withdrawal, `featuresUnsupported` with the missing feature ids, `consumerVersionTooOld` when the version's `minOneboxVersion` or `minCloudlyVersion` is newer than the consumer's release, `null` for an install target), the catalog's `latestVersion`, the newest version this consumer may install (`latestInstallableVersion`: under `semver` the highest, under `branch` the catalog latest when it is one) and the `IAppStoreApp` and `IAppStoreAppMeta` shapes Onebox and Cloudly show, whose `versions` list only install targets, whose `versionStates` state every listed version with its refusal and whose `latestVersion` is the newest install target, or `null` when the app has none. `consumer` is `{ kind: 'onebox' | 'cloudly', version }`.
+  - `getAppStoreCatalogListing(catalog, { supportedFeatureIds, consumer })` is the `getAppStoreTemplates` listing: every app with an install target for this consumer, in catalog order.
+- test a consumer against fixtures (testing)
+  - `@serve.zone/appstore/testing`, a separate entry outside the runtime one, gives a consumer's tests a throwaway signing key and its trusted-key record (`createAppStoreTestSigningKey`), a catalog the contract accepts (`createAppStoreTestCatalog`, `createAppStoreTestVersionConfig`), its envelope (`signAppStoreTestCatalog`), the package tarball (`createAppStoreTestPackageTarball`), a registry stub (`createAppStoreTestRegistry`) and the `fetch` serving it (`createAppStoreTestFetch`).
+  - Every published Cloudly template is qualified in this repository (pinned image, Onebox minimum, upgrade flags, platform OIDC and the Onebox release gate), so a template release needs no host test change.
+
+### Maintenance
+
+- Dependencies: `@serve.zone/interfaces` 32.53.0 (from 32.42.0); add `modern-tar` 0.8.5 (MIT, no dependencies) to read the package tarball; drop `@push.rocks/smartversion`.
+
+## 2026-10-08 - 32.27.0
+
+### Features
+
+- publish the Cloudly 1.27.0 template for Cloudly 33.17.3 (cloudly)
+  - Add Cloudly app version 1.27.0, pinned to the Cloudly 33.17.3 multi-platform image index `code.foss.global/serve.zone/cloudly@sha256:700bb723fef408a6bf8079f643f9990247bffe6541403fd421d064ba8128a447` (tag `v33.17.3`), and mark it as the latest catalog version.
+  - Cloudly 33.17.3 bounds runtime history and moves the data version from 0.28.0 to 0.30.0 through the forward-only data steps `route-claim-absent-owners` (0.28.0 → 0.29.0, which removes the stored nulls of absent route claim owners) and `bounded-runtime-history` (0.29.0 → 0.30.0, which deletes every archived deployment record). It also stops node requests contending on the controller fence, under a 6 s request budget, consumes Pallet's projection application receipts, refuses a node deletion that races a write bound to the node, and drops the dashboard's archived deployments view. Cloudly 33.17.2 lets a database below data version 0.25.0 that holds a runtime slot start.
+  - Keep the 1.26.0 runtime contract: 1.27.0 differs from 1.26.0 only in its image and changelog. Cloudly 33.17.2 and 33.17.3 change neither `qenv.yml` nor the Dockerfile, and the Onebox minimum stays 33.8.0. Every Cloudly before 33.17.3 refuses the 0.30.0 data; the template stays breaking, migration-required, backup-before-upgrade and manual-review.
+  - The template changelog states the changes of Cloudly 33.17.2 and 33.17.3 and carries the 1.26.0 text as the fix of Cloudly 33.17.1 that applies from 1.25.0 or earlier; the carried data step statements, the full step chain, the rollout order and the upgrade flags statement now include the 0.28.0 to 0.30.0 steps and name Cloudly 33.17.3.
+  - Update the bundled client data, the README guidance and the resolver regression coverage, which now holds 1.26.0 to 1.27.0 apart from the image and changelog.
+
+### Maintenance
+
+- Release tooling: `@git.zone/tsbuild` 5.1.2 → 6.0.0 (TypeScript 7, `7.1.0-dev.20260928.1`; the tsconfig uses none of the options TypeScript 7 removed). `@types/node` stays at 26.6.3 until 26.6.4 is seven days old.
+
 ## 2026-10-07 - 32.26.0
 
 ### Features

package/dist_catalog/catalog.digest

@@ -0,0 +1 @@
+sha256:128fa196b24c3fae408a960195e2587e31639cb55449e8a576ca3b76567f95bb