@serve.zone/appstore 32.27.0 → 33.1.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,75 @@
 # Changelog
 
+## 2026-10-08 - 33.1.0
+
+### Features
+
+- publish the Cloudly 1.28.0 template for Cloudly 33.18.0 (cloudly)
+  - Add Cloudly app version 1.28.0, pinned to the Cloudly 33.18.0 multi-platform image index `code.foss.global/serve.zone/cloudly@sha256:b28e53772c0148470df3a4bf57a4fcd2bcee273f002e3faa8eb71957ffd580a5` (tag `v33.18.0`), record it in `catalog.lock.json`, qualify it in `test/test.cloudlytemplates.node.ts` and mark it as Cloudly's latest version. It is the first Cloudly template shipped through the runtime catalog alone, with no Onebox or Cloudly release.
+  - Cloudly 33.18.0 loads the signed App Store catalog at runtime from the registries of its new `appStoreCatalogRegistries` setting (empty means the npm registry), keeps the last verified catalog and refuses App Store install details, upgrade preview and upgrade with `APPSTORE_CATALOG_UNAVAILABLE` while none is active, snapshots the template of every App Store service, and removes the bundled App Store snapshot and the `APPSTORE_URL` remote source, which it now ignores. It also binds its test fixtures to OS-assigned ports and builds with tsbuild 6 (TypeScript 7).
+  - Keep the 1.27.0 runtime contract: 1.28.0 differs from 1.27.0 only in its image and changelog, and no template variable names a catalog source. Cloudly 33.18.0 adds no data step, keeps the data version 0.30.0 and changes neither the Dockerfile nor a `qenv.yml` requirement, and the Onebox minimum stays 33.8.0. The template stays breaking, migration-required, backup-before-upgrade and manual-review: hosts read the flags from the target version alone, every upgrade from 1.26.0 or earlier still runs the forward-only 0.28.0 to 0.30.0 steps (and the earlier ones before them), every Cloudly before 33.17.3 refuses the 0.30.0 data, and an `APPSTORE_URL` an operator set is no longer read.
+
+### Maintenance
+
+- Release tooling: `@git.zone/tsbuild` 6.0.0 → 6.0.2. `@types/node` stays at 26.6.3 until 26.6.4 is seven days old (2026-10-08 22:39 UTC); pnpm stays at 12.8.2.
+
+## 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

package/dist_catalog/catalog.digest

@@ -0,0 +1 @@
+sha256:68b6818d24f6414f4b249d54f3724e9e16bab7d32eda212ece60d41a0b88061b