✨(mobile) add self-hosted OTA update chain

Store review cycles make shipping web-layer fixes through the stores
too slow, so the apps update their JS bundle over the air. The chain is
fully self-hosted to keep sovereignty: bundles and channel manifests
live on an anonymous-read S3 bucket (create_bucket --public / the
create-ota-bucket script) and the Capgo plugin is driven entirely from
JS against that manifest (autoUpdate off — no Capgo server involved).
Bundles are RSA-signed at publish time and verified against the
per-instance public key baked in at cap sync, so a tampered zip on the
public bucket is rejected.
Versions use a git-derived <count>-<sha> id stamped into the builtin
bundle so a fresh install does not re-download its own commit, and
channels (dev/staging/prod) are fully independent because
NEXT_PUBLIC_* vars are inlined at build time.
Also ships docs/mobile.md.

Author: jbpenrath

Makefile

@@ -185,6 +185,31 @@ shell-objectstorage: ## open a shell in the objectstorage container
 	@$(COMPOSE) run --rm --build objectstorage bash
 .PHONY: shell-objectstorage
 
+# Generate a per-instance OTA signing key pair. Prints the base64 PEMs to stdout:
+# MOBILE_OTA_SIGNING_PUBLIC_KEY_B64 (baked into the app) + MOBILE_OTA_SIGNING_PRIVATE_KEY_B64
+# (publish secret). Each deployment runs it once; the private half is a CI secret,
+# never committed. No object storage needed — pure key generation.
+mobile-ota-keygen: ## generate a per-instance OTA signing key pair (base64 PEMs)
+	@$(COMPOSE_RUN) --no-deps frontend-mobile npm run --silent mobile:ota:keygen
+.PHONY: mobile-ota-keygen
+
+mobile-ota-bucket: ## create the public mobile OTA bucket in objectstorage
+	@$(COMPOSE) up -d objectstorage --wait
+	@$(COMPOSE_RUN) frontend-mobile npm run mobile:ota:bucket
+.PHONY: mobile-ota-bucket
+
+# Build the web bundle in the env-aware container (dist lands on the host via the
+# bind mount), then zip + upload it and the channel manifest to the public
+# bucket. Both steps run in the frontend toolchain: the OTA release is a
+# frontend artifact, Django is not involved. VERSION defaults to the git-derived
+# MOBILE_OTA_BUILD_ID (the hybrid <count>-<sha> id); override it to pin a specific
+# release. CHANNEL defaults to the MOBILE_OTA_CHANNEL env var (frontend env files).
+ota-publish: VERSION ?= $(MOBILE_OTA_BUILD_ID)
+ota-publish: ## build and publish a mobile OTA bundle (VERSION defaults to <count>-<sha>, CHANNEL to MOBILE_OTA_CHANNEL)
+	@$(COMPOSE) up -d objectstorage --wait
+	@$(COMPOSE_RUN) frontend-mobile sh -c "npm run build && npm run mobile:ota:publish -- --version $(VERSION)$(if $(CHANNEL), --channel $(CHANNEL))"
+.PHONY: ota-publish
+
 # -- Linters
 
 lint: ## run all linters
@@ -609,17 +634,25 @@ build-front: ## build the frontend locally
 	@$(COMPOSE) run --rm --build frontend-tools npm run build
 .PHONY: build-front
 
+# Hybrid OTA/build version: a monotonic commit count (for ordering — enables a
+# future downgrade check) plus the short SHA (for traceability). Computed on the
+# HOST (git is not in the container) and injected; CI may override it.
+MOBILE_OTA_BUILD_ID ?= $(shell git rev-list --count HEAD)-$(shell git rev-parse --short HEAD)
+
 # Mobile (Capacitor). The web bundle is built in a container (frontend-mobile,
 # which carries the env_file so the NEXT_PUBLIC_* vars are inlined) and synced
 # into the native projects. The sync (not a bare copy) also regenerates the
 # gitignored capacitor-cordova-android-plugins/ scaffolding that Gradle needs,
 # so always run `make mobile-build` after a fresh checkout. The native compile /
 # IDE / device steps are macOS- and SDK-bound, so they stay on the host.
+# MOBILE_OTA_BUILD_ID is passed so `cap sync` stamps it as the builtin bundle version
+# (capacitor.config.ts), letting the OTA freshness check match a same-commit
+# manifest instead of re-downloading on first launch.
 #
 # Hot reload: MOBILE_DEV_SERVER_URL (frontend env files, set by default in dev)
 # is baked as the WebView's server.url at `cap sync` — see docs/mobile.md.
 mobile-build: ## build the web bundle and sync it + native plugins into the projects (container, env-aware)
-	@$(COMPOSE) run --rm --build frontend-mobile npm run mobile:build
+	@$(COMPOSE) run --rm --build -e MOBILE_OTA_BUILD_ID=$(MOBILE_OTA_BUILD_ID) frontend-mobile npm run mobile:build
 .PHONY: mobile-build
 
 # Regenerate the native app icons and splashscreens from src/frontend/assets/
@@ -646,8 +679,8 @@ mobile-ios: mobile-build ## build the bundle (container) then open the iOS proje
 # here), so this Makefile is the single source of truth for the port list and
 # the gradle task.
 # Ports the in-app WebView reaches through the device→host adb tunnel:
-# 8900 dev frontend, 8901 backend, 8902 Keycloak.
-ANDROID_REVERSE_PORTS = 8900 8901 8902
+# 8900 dev frontend, 8901 backend, 8902 Keycloak, 8906 object storage (OTA).
+ANDROID_REVERSE_PORTS = 8900 8901 8902 8906
 ANDROID_DEBUG_APK = src/frontend/android/app/build/outputs/apk/debug/app-debug.apk
 
 mobile-android-reverse: ## (host) map device ports to the dev stack via adb reverse

docs/env.md

@@ -176,6 +176,42 @@ blob stays in PG.
 | `MESSAGES_BLOBS_ENCRYPT_KEYS` | `{}` | JSON dict mapping `key_id` → entry. Each entry must be `{"algo": "aes-gcm", "secret": "<32+ chars>", "active": <bool>}`. Add `"active": true` to exactly one entry to make it the key new blobs are encrypted with; entries without `active` (or with `active=false`) stay readable for legacy ciphertext. The secret is SHA-256'd to a 32-byte AEAD key, so its strength is whatever entropy the operator supplied — use `openssl rand -base64 32` (or equivalent). Startup emits a warning when a secret is shorter than 32 characters; that floor is a length check only, not an entropy measurement. | Optional |
 | `MESSAGES_BLOBS_VERIFY_HASH` | `False` | When True, `Blob.get_content()` re-hashes plaintext and rejects mismatches. One SHA-256 over the plaintext per read; main value is for `key_id=0` blobs (encrypted blobs are already AAD-bound). | Optional |
 
+### Mobile OTA Bundles
+
+Public (anonymous read) bucket holding the mobile OTA artifacts, one
+self-contained folder per release channel (`channels/<channel>/manifest.json` +
+`channels/<channel>/bundles/<version>.zip`). Created with `make mobile-ota-bucket`;
+bundles are published with `make ota-publish [CHANNEL=…]`. Channels are fully
+independent: `NEXT_PUBLIC_*` vars are inlined into the bundle at build time, so
+each channel ships its own build — never copy a bundle across channels.
+
+Except for `MOBILE_OTA_MANIFEST_URL` (a **backend** setting served to the apps
+through the `/config` endpoint), these are **frontend-toolchain / publish-time**
+variables (read by `src/frontend/scripts/*-ota*.mjs`, not by Django). They live
+in the frontend env files; in CI they come from secrets.
+
+> **Opt-in in dev**: they ship **commented out** in
+> `env.d/development/frontend.defaults` (the values below are the working
+> dev-stack ones) — uncomment them, along with `MOBILE_OTA_MANIFEST_URL` in
+> `backend.local`, to exercise the OTA chain locally.
+> Hot reload (`MOBILE_DEV_SERVER_URL`, on by default in dev) skips the startup
+> OTA check; disable it to test OTA end to end.
+
+| Variable | Default | Description | Required |
+|----------|---------|-------------|----------|
+| `MOBILE_OTA_S3_ENDPOINT` | `http://objectstorage:9000` | S3 endpoint the script **writes** to (compose network in dev; target S3 in CI) | Optional |
+| `MOBILE_OTA_S3_BUCKET` | `messages-ota` | S3 bucket name for OTA bundles | Optional |
+| `MOBILE_OTA_S3_ACCESS_KEY` | `st-messages` | S3 access key | Optional |
+| `MOBILE_OTA_S3_SECRET_KEY` | `password` | S3 secret key | Optional |
+| `MOBILE_OTA_S3_REGION` | `us-east-1` | S3 region | Optional |
+| `MOBILE_OTA_S3_KEY_PREFIX` | `` (empty) | Object key prefix; empty for a dedicated bucket root, `messages/mobileapp/` for a shared bucket. Must stay consistent with `MOBILE_OTA_PUBLIC_BASE_URL` | Optional |
+| `MOBILE_OTA_CHANNEL` | `dev` (dev env) | Release channel `mobile:ota:publish` targets (`channels/<channel>/…`); overridable per run with `--channel` / `make ota-publish CHANNEL=…`. The deploy pipeline uses `staging` and `prod`, each publishing its own build. Must match the channel segment of the `MOBILE_OTA_MANIFEST_URL` served by the backend this deployment's apps talk to | Optional |
+| `MOBILE_OTA_MANIFEST_URL` | None (**backend** env) | OTA channel manifest URL the apps poll at startup, served through the `/config` endpoint — so the followed channel can change without shipping a new native build. Must point to the channel this deployment publishes to. Unset disables OTA | Optional |
+| `MOBILE_OTA_PUBLIC_BASE_URL` | `http://localhost:8906/messages-ota` | Device-reachable **read** base URL written into the manifest | Optional |
+| `MOBILE_OTA_SIGNING_PRIVATE_KEY_B64` | None | Base64-encoded (single-line) RSA private-key PEM signing/encrypting each bundle at publish time (`publish-ota.mjs`). CI secret only — never commit. Unset ⇒ publish fails. See [mobile.md](./mobile.md#generating-the-signing-key-pair) | Optional |
+| `MOBILE_OTA_SIGNING_PUBLIC_KEY_B64` | None | Base64-encoded (single-line) RSA public-key PEM baked into the app at `cap sync` time (`capacitor.config.ts`, native verification) **and** inlined by Vite into the JS bundle (`ota.ts` refuses a server-provided manifest URL on a key-less build). Read by the builds, not the publish scripts — an OTA-enabled build can never apply an unsigned bundle | Required if OTA enabled |
+| `MOBILE_OTA_BUILD_ID` | `<count>-<sha>` (git-derived) | Hybrid release id stamped into the builtin bundle version at `cap sync` (`capacitor.config.ts`) and used as the default OTA `VERSION`. Computed by the Makefile from git; override in CI to pin a build. See [mobile.md](./mobile.md#bundle-versioning) | Optional |
+
 ### Static Files
 
 | Variable | Default | Description | Required |
@@ -242,6 +278,7 @@ _Those settings are deprecated and will be removed in the future._
 |----------|---------|-------------|----------|
 | `MOBILE_APP_ID` | `local.suitenumerique.messages` | Store/OS bundle identifier of the native app. The repo ships a neutral placeholder; an organisation publishing to the App Store / Play Store overrides it with its own signed id. Read by `cap sync` (container) **and** the native builds — gradle `applicationId`, iOS `PRODUCT_BUNDLE_IDENTIFIER` — so it must be exported in **both** the container env and the host/CI env. Independent of the auth callback scheme (`stmessages`). | Optional |
 | `MOBILE_DEV_SERVER_URL` | `http://localhost:8900` (dev env, `frontend.defaults`) | **Dev only.** URL of the Vite dev server baked as Capacitor `server.url` at `cap sync` (`capacitor.config.ts`): the WebView then loads the app from Vite with hot reload instead of the embedded bundle. To disable (embedded bundle / OTA testing), set it **empty** in `frontend.local` and rerun `make mobile-build`. Must never be set for a release build — a gradle guard fails Android release builds carrying it. See [mobile.md](./mobile.md#hot-reload-on-by-default-in-dev) | Optional |
+| `MOBILE_ALLOW_CLEARTEXT_FOR_DEV` | `1` (dev env, `frontend.defaults`) | **Dev only.** Baked as Capacitor `server.cleartext` at `cap sync` (`capacitor.config.ts`), i.e. `android:usesCleartextTraffic` in the Android manifest: allows plain HTTP for the whole app — the WebView reaching the Vite dev server and the native fetch/OTA layer reaching the `http://localhost:8901` backend and the RustFS OTA bucket (needed even with hot reload disabled). Must never be set for a release build — the manifest then stays cleartext-free. iOS equivalent: `NSAllowsLocalNetworking` (`Info.plist`, manual). | Optional |
 
 > **Note**: overriding `MOBILE_APP_ID` only changes the app identity; it does **not** touch the OIDC deep-link scheme (`stmessages`), which is fixed and declared in the iOS `Info.plist` (`CFBundleURLTypes`) and the Android manifest.
 
@@ -339,6 +376,7 @@ The following build-time variables are **deprecated**: they only act as fallback
 | `NEXT_PUBLIC_LAGAUFRE_WIDGET_PATH` | `FRONTEND_LAGAUFRE_WIDGET_CONFIG` (`path` key) |
 | `NEXT_PUBLIC_SENTRY_DSN` | `SENTRY_DSN` |
 | `NEXT_PUBLIC_SENTRY_ENVIRONMENT` | `ENVIRONMENT` (backend environment) |
+| `NEXT_PUBLIC_MOBILE_OTA_MANIFEST_URL` | `MOBILE_OTA_MANIFEST_URL` |
 
 ## Development Tools