Signing and the path into the catalog

A release freezes the version, manifest, and bytes of an app and moves through the channels up to stable. This page covers what belongs to a release, how a version enters the catalog as a signed artifact, the rules of the channels, and the calls and commands with which platform operations manages the catalog.

Each version comes into being exactly once: CI builds it from its tag as a signed, immutable artifact <appId>-<version>.szapp with the manifest, the bundles for the display software and the editor, images and texts for the store, and the release notes, and every environment fetches this one artifact from the registry. The same version therefore has the same bytes in every environment.

What belongs to a release#

In object storage, a version lives under platform/apps/<appId>/<version>/:

The release additionally carries sizeBytes and sha256 (64 lowercase hexadecimal characters) of the stored bytes and the provenance: source (registry for an artifact from the registry, seed-placeholder for a row without bytes that the seed created without access to the registry), under artifact the hash of the index, the release key whose signature has been verified, the signature itself, and the digest in the registry, plus importedAt and importedById. Manifest and bytes are immutable after fetching, and the only fields that can be changed afterward are the notes. They live under notes per audience, namely customer (“New in this version”), operator, and developer, and per language (de-DE, en-US, …), as the artifact’s index brings them. In addition, every release still has the one older note, releaseNotes (max. 2000 characters): the text for operations in de-DE, otherwise the one for customers.

Devices and clients reach a version through four routes. Manifest and bundle require a device’s certificate or a session, and only the unpacked runtime is free of sign-in. The specification lists the same credentials under security, with the names from the Credential column:

The two catalogs across all apps#

Besides the individual version, the API delivers two overviews of the whole catalog. Both take, for each app, the version that applies in the stable channel, the one that entered it most recently and not the one with the highest number, and break down its manifest: one into widget definitions, the other into resource types. The widget catalog additionally lists the six built-in building blocks (text, image, video, shape, graphic, document). They belong to no app and therefore have the reserved identifier core. What exists only in canary or beta appears in neither, and both answer regardless of what an organization has installed: they describe the offering, not the installed base.

Both require a credential but no permission of their own: a valid sign-in suffices, and an API key reaches them regardless of which permissions are in its scope.

curl -sS "$SZENERA_API/v1/widget-catalog" \
  -H "Authorization: Bearer $SZENERA_API_KEY"

Both responses are flat: a list in which an entry carries the definition and also says which version of which app it comes from.

{
  "entries": [
    {
      "appId": "pharmacies-on-duty",
      "version": "2.0.1",
      "definition": { "id": "pharmacies-on-duty-display", "name": "Notdienst-Anzeige", "…": "…" }
    }
  ]
}

Signature: the statement about the version#

Signing happens in CI, never on a server: CI signs the statement “this app, this version, this manifest, this index” with the Ed25519 release key of each world (app-release-staging for development and staging, app-release-prod for production). When fetching, the API checks the signature of its own world against that world’s public key. Without a valid signature of its world, no version enters the catalog, and there is no fallback to the sha256 alone. Whoever fetches a release signs nothing.

On the device, remote maintenance checks every artifact before it unpacks anything: the sha256 value of the downloaded archive must match the one on the release, then it checks the signed statement against the anchor app-release-<world> in the image, after that the manifest and every file against the index, and it unpacks only runtime/, safeguarded against paths that lead out of the target folder. If the anchor is missing, it rejects every artifact. An archive without an index is not an artifact, and remote maintenance does not accept it. The signing entry in the manifest changes nothing about this and remains only because it appears in the manifests of published versions.

Fetch a release#

A release comes into being by importing an artifact from the registry. CI reports every version it has stored, to staging and production. The API does not list the versions of the registry: whoever fetches a version by hand names its version themselves.

POST /v1/platform/app-catalog/imports with the body { "appId": "…", "version": "…" } fetches the version. Optionally, digest names the digest of the OCI manifest (sha256:…) that the caller expects, and CI always sends it. The API checks manifest and layer in the registry, then the archive: every file against its checksum in the index, the manifest against the schema and its hash, identifier and version, and the signature of its world. Only then does it store the bytes and create the release in the canary channel.

curl -X POST "$SZENERA_API/v1/platform/app-catalog/imports" \
  -H "Authorization: Bearer $SZENERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "appId": "pharmacies-on-duty", "version": "1.3.0" }'

The response is { "release": …, "created": true } with 201 if the version is new in the catalog. If it was already there with the same artifact, the call answers with 200 and created: false, so the call can be repeated. The import fills a placeholder without bytes that has the same manifest, while the row’s channel and the releases already made into channels remain. It replaces the seed’s note, which only describes the placeholder, with the notes from the index, unless someone has changed it.

In doing so, the import backfills the notes: if a version that it already finds in the catalog lacks an audience or language that its artifact’s index carries, it adds it and records that as notes-updated with its actor. That way, a version that entered the catalog before per-audience notes gets the texts for customers and developers. Existing texts remain, and the import does not touch notes that have been changed once. The API reads the index of a version in the catalog from its own object storage, so the version no longer has to be in the registry for that.

What can fail while fetching names the exact reason in details.reason:

The channels#

A new release always starts in canary, and nobody chooses the starting channel. Each promotion moves exactly one step, and a jump is not possible. No single person promotes to stable: one person requests, a second confirms, also when restoring. The version that entered stable most recently is the one that applies there, not the one with the highest number.

Promoting to beta, promoting or requesting stable, and confirming a request each require a checklist with no blocking items: “New in this version” (notes.customer['de-DE']) is present, and no text for customers contains a semicolon or a blocked word. Otherwise the API answers AppRelease.ReviewBlocked (HTTP 409) and names the blocking items in details.blocks. The checklist does not block restoring and retiring.

The retirement period is a choice, not a keyword in the reason: a reason that contains security shortens nothing. For new installations, a retired release can no longer be chosen immediately. Installations on exactly this version get the successor as their target: if it requires nothing new, the platform adopts it immediately, otherwise the installation moves to Update waiting with the end of the retirement period as the deadline. When the period is over, the platform switches installations and scenes to the successor, even without consent, and notifies the organization. If there is no successor, everything stays on the version, and the version’s history records it (no-successor). With immediate, both happen in the same call. If the successor reaches stable only after the period has ended, the version gets a period of seven days (entry grace-extended with a reason), in which a successor that requires consent waits for the organization. After that, the platform switches.

All calls under /v1/platform/app-catalog/… carry the note “Operators only”. Reading requires platform.app-catalog.list, fetching requires platform.app-catalog.import (also with an operator key, which is how CI reports), promoting, requesting, restoring, and demoting require platform.app-catalog.promote (confirming and rejecting a request require platform.ops.release.approve), deleting and cleaning up require platform.app-catalog.delete, retiring and periods require platform.app-catalog.retire, and notes require platform.app-catalog.update.

The history of an app#

Every movement of a release is recorded as an entry in the history of its app: creation, fetching from the registry, every release into a channel, demoting, restoring, retiring, retirement periods, changed notes, and every step of a request to a second person (promotion-requested, promotion-approved, promotion-withdrawn, promotion-expired). If a second person confirmed, that person is the actor, and requestedById names the person who requested. Each entry names the channel from and to, the time, and the actor: a person in operations (operator with identifier), CI (ci), an environment’s seed (seed), the platform itself (auto), the zero hour (zero-hour), or legacy for what happened before the history and is reconstructed from the releases’ timestamps.

As CLI commands#

The CLI maps the lifecycle after fetching in nine commands. It does not know fetching itself: the environment syncs with the registry every ten minutes, and CI speeds it up with the call above. The requests to a second person are run by the group approval (list, approve, withdraw).

szenera-ops --profile=dev-operator app-release promote arl_01K… --app=weather --channel=beta
szenera-ops --profile=dev-operator app-release promote arl_01K… --app=weather --channel=stable --reason="Drei Tage in beta ohne Meldung"
szenera-ops --profile=dev-operator approval approve rap_01K…
szenera-ops --profile=dev-operator app-release retire arl_01K… --app=weather --reason="Nachfolger da" --grace=regular

All of them belong to the platform operations tool szenera-ops and require an operator credential. The commands with a release position require --app, while list uses it as an optional filter. The release is the positional argument id (identifier arl_…). The complete register is at Commands for platform operations.

What the organization sees from this#

• New stable version without new permissions and without changed terms: Existing installations adopt it automatically, and the earlier decisions in the app’s Update tab show the entry adopted silently.
• New stable version with new permissions or changed terms: The installation moves to Update waiting, and the app’s widgets cannot be inserted in the scene editor until the organization accepts in the Update tab (see Data access, permissions, and terms).
• Publishing a scene: If a widget pins a version that does not exist, that is retired and whose retirement period is over, or if it belongs to an app that the organization has not installed, the platform rejects publishing and states the reason in one sentence. A retired version within an ongoing period is a notice.
• Retired release: No longer selectable for new installations. Whoever has installed exactly this version gets the successor, the lowest stable version above it. If it requires nothing new and the organization has not declined it, the platform adopts it immediately. Otherwise the installation moves to Update waiting, with the end of the retirement period as the deadline, and after that the platform switches. Without a successor, the app keeps running unchanged until the end of the period.

What does not exist today#

The catalog is purely curated: CI builds and signs every version, and platform operations fetches it into the catalog and steers its lifecycle. There is no developer submission, no review queue, and no statement about review times or criteria. The 26 bundled apps are created in the platform’s source tree, built from their tag, signed as an artifact, and fetched into every environment. Anyone preparing an app does so with platform operations, and the pages of this area describe the contract it is written against.

Related#

• What is an app, and how does it get onto a display? — the lifecycle in a picture.
• The manifest — signing and the other fields.
• Commands for platform operations — app-release and app-status in the szenera-ops tool.