amber-backend/docs/auto-update-contract.md

Auto-update — contract (issue #16)

The app checks for a newer build and installs it, receiving the adult or clean variant according to its account's admin-set nsfwEnabled flag.

Server pieces (this repo):

• pb_migrations/1786500000_releases.js — the releases collection.
• pb_hooks/update.pb.js — the GET /api/update/manifest route.
• scripts/publish-release.sh — uploads a built artifact as a superuser.

Client pieces (amber-app): lib/data/update/update_service.dart (version check + manifest fetch), the desktop swap-installer, and the Android APK install channel.

releases collection

Field	Type	Notes
platform	select	windows | linux | android.
variant	select	clean | adult.
version	text	Human semver shown to the user, e.g. 1.0.1.
buildNumber	number	Monotonic int; the comparator the updater actually uses.
file	file	The artifact: windows = .exe installer, linux = .zip of the release bundle, android = .apk. Protected (see rules).
sha256	text	Lowercase hex SHA-256 of the artifact; verified before install.
size	number	Bytes.
notes	text	Optional release notes (shown in the update prompt).
created/updated	autodate

Unique index on (platform, variant, buildNumber).

Access rules. Read is gated: @request.auth.id != '' && (variant = 'clean' || @request.auth.nsfwEnabled = true) — any signed-in account reads clean rows; only an nsfwEnabled account reads adult rows. The file field is protected: true, which is what gates the bytes: a protected file is served only with a short-lived file token (POST /api/files/token) whose grant re-checks the view rule above — so a non-flagged account can't download an adult artifact (and without the flag the file URL would be public regardless of the view rule). create/update/delete are superuser-only (null rules); publishing goes through the admin API.

Endpoint

GET /api/update/manifest?platform=windows|linux|android (auth: users)

Returns the latest build for the caller's platform. The variant is chosen server-side from nsfwEnabled — the client cannot request adult.

• No release for that platform/variant → { "available": false }.
• Otherwise:

  {
    "available": true,
    "platform": "linux",
    "variant": "clean",
    "version": "1.0.1",
    "buildNumber": 2,
    "notes": "…",
    "sha256": "<64 hex>",
    "size": 12345678,
    "filename": "amber-linux-clean.zip",
    "downloadPath": "/api/files/releases/<recordId>/<filename>"
  }
  

Download. The app mints a file token (POST /api/files/token, its user auth) and GETs {base}{downloadPath}?token=<fileToken>, then verifies sha256 before installing.

Publishing a build

Build the artifact, then (on the build machine):

PB_ADMIN_TOKEN=<superuser token> ./scripts/publish-release.sh \
  --platform linux --variant clean --version 1.0.1 --build 2 \
  --file build/amber-linux-clean.zip --notes "What changed"

PB_ADMIN_EMAIL + PB_ADMIN_PASSWORD work instead of a token. The script computes the SHA-256 + size and uploads via the superuser REST API. Re-publishing the same (platform, variant, buildNumber) is rejected by the unique index — bump buildNumber for each release.

Windows publishes the installer, amber-setup-<variant>-<version>.exe, not the zip. One artifact serves both jobs: people download and run it, and the app's updater runs the same file with /SILENT, which is why DesktopInstaller dispatches on the extension. The zip release_windows.ps1 still builds beside it is for the flavour check and for unpacking by hand — do not publish it.

check-flavor.py cannot read a .exe (Inno compresses the payload) and refuses rather than passing it. The Windows flavour gate is Assert-Flavor in release_windows.ps1, which reads the staged folder before either artifact is made from it; run it there, not here.

Gating summary

nsfwEnabled (admin-set on the users record) is the single source of truth: the manifest hook reads it to pick the variant, and the collection rules enforce it independently at read/download time. A no-flag account only ever sees and downloads clean builds.