Files
craft-launcher/docs/hosted-catalog.md
Dylan M. Taylor f6409da7f7 Load signed hosted launcher catalog with offline fallback (#1115)
* Load and verify the signed website catalog with bundled fallback

* Preserve signed fixture bytes across platforms and fix web lint

* Document the opt-in live catalog integration check
2026-11-11 06:45:32 -05:00

78 lines
4.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Signed hosted catalog
The launcher bundles `crates/core/catalog.toml`, containing the website's
`launcher-catalog.toml` data from storytold/artcraft-services#205 with the latest
compiled display order. The signed website fixture is kept separately under
`crates/core/tests/fixtures/` with byte-preserving Git attributes for Windows. The core build script
generates the existing static app/details types from it, keeping first launch
and offline operation independent of the website.
On the first release check of each process, desktop and web fetch:
- `https://getartcraft.com/launcher-catalog.toml`
- `https://getartcraft.com/launcher-catalog.toml.sig`
The signature is base64 encoding of a 64-byte Ed25519 signature over the exact
TOML bytes, with optional surrounding whitespace. Verification uses the SPKI
PEM public key in `crates/core/assets/launcher-catalog-public-key.pem` before
parsing. The corresponding private key belongs only in the website's Cloudflare
build secret `LAUNCHER_CATALOG_SIGNING_KEY`. It is never read or bundled by the
launcher. The checked-in signature fixture is public test data, not a secret.
Desktop stores the TOML and signature together in an atomic
`launcher-catalog.json` beside the release-feed cache. Web uses the browser's
local storage (`artcraft-launcher.signed-catalog.v1`). Every cache read verifies
the signature again. Network failures, missing signatures, invalid signatures,
invalid documents or unavailable storage preserve the verified cache, then the
bundled list. The bundled list is visible while the background check runs.
The active catalog is immutable for the process lifetime. Existing install jobs
keep their static handles; restarting refreshes the catalog again. Only one
bounded snapshot is interned per process. This avoids accumulating leaked strings
on repeated checks. Missing bundled apps are appended to the hosted list so an
installed copy remains manageable after the hosted entry disappears.
The signed file updates app copy, colors, details, desktop categories, window
class, icons and display order. Invalid rows are skipped, unknown fields ignored,
and a document with no valid rows is rejected. New official apps can be added
without a launcher release, within the existing source policy: a lowercase safe
ID, its matching `storytold/<id>` repository, ArtCraft publisher/team, default
bundle ID and no legacy aliases. Existing app names, aliases, bundle IDs,
repositories, publishers and macOS signing teams stay pinned to the bundled
entry. A signature cannot add an unapproved community app or change an existing
install identity. Community onboarding and identity changes still require
maintainer review and a launcher release.
Icons must use the website's app-ID/hash filenames and pass SHA-256 and PNG
size/dimension checks before decoding. Desktop caches them by hash; web uses
its HTTP cache. Missing icons do not block a valid catalog. Screenshots remain
JPEGs at the launcher's pinned assets tag, with existing byte/pixel checks.
The currently supported installer code still derives package/binary IDs from
app IDs; arbitrary installer identities in unknown manifest fields do not
change installation behavior.
Limits: 1 MiB catalog, 128-byte encoded signature, 64 hosted apps, 16 features
and screenshots per app, 256 KiB/512×512 PNG icons. Desktop HTTP uses its existing
bounded reader and timeouts. Browser catalog/icon requests stream with actual
byte limits and a 20-second abort signal; redirects are refused on both platforms.
This is a single pinned key. Rotation requires a launcher update; there is no
manifest-authorized next key, signed expiry or rollback counter in this schema.
The signature authenticates content, not freshness. The existing package checksum
and macOS/Windows publisher checks continue to apply to installations.
Validation includes a real signed website-format fixture, wrong-key/tampering
rejection, malformed rows, install-identity restrictions, new official app policy,
icon hashes/dimensions, and reverified cache fallback. The private signing key is
not required to run any test.
To validate the published catalog through the desktop HTTP/cache/activation path
without installing any app:
```sh
cargo test -p artcraft-launcher-native live_catalog_is_verified_cached_and_activated -- --ignored
```
This opt-in network test uses temporary storage and checks the pinned signature,
all accepted entries, activation and icon hashes. Normal CI stays offline.