# Stacklift documentation (all pages) > Stacklift is a hosted platform with source-available SDKs for shipping app releases and over-the-air updates. It works for mobile (React Native, Expo, Flutter, native iOS and Android, Kotlin Multiplatform, .NET MAUI, Unity), web, desktop (Electron, .NET, Java) and backend apps. Developers create releases with the `stacklift` CLI or the dashboard; the server verifies and signs every artifact (SHA-256 + Ed25519), deploys releases to channels with staged rollouts and rollback, and app SDKs check, download and verify updates. Native apps can change screens over the air with server-driven UI layouts and logic with sandboxed scripts, within App Store and Google Play rules. Apps never depend on Stacklift to keep working: everything has a built-in fallback and an exit path. Source: https://stacklift.joynul.com/docs · Index: https://stacklift.joynul.com/llms.txt --- # Quickstart Ship a first release in about ten minutes. You need an account, the CLI, and a built artifact. ## 1. Install the CLI ```bash npm install -g stacklift stacklift --version ``` > The CLI is not on npm yet. Until the first release, install the build you were given for early access. ## 2. Sign in ```bash stacklift login ``` This asks for your email and password once, creates a revocable personal access token named after your machine, stores it in `~/.config/stacklift/credentials.json` (mode `0600`) and discards the password. In CI, set `STACKLIFT_TOKEN` instead. Using GitHub or Google sign-in? Create a token under **API Keys → Personal access tokens** and run `stacklift login --token slp_…`. ## 3. Connect your app ```bash cd my-app stacklift init ``` `init` looks at your files, detects the stack (for example React Native from `package.json`), tells you how mature support for that stack is, creates a project (or links an existing one) and writes [`stacklift.yaml`](https://stacklift.joynul.com/docs/stacklift-yaml.md). The project's **public key** and **CI secret key** are printed once. Store them. ## 4. Create a release ```bash stacklift release create \ --version 1.0.0 \ --runtime-version 1.0.0 \ --artifact android:js-bundle:./dist/android.zip \ --channel staging ``` What happens: 1. Every artifact is hashed locally (streamed — files are never loaded fully into memory). 2. The release is created as a draft. 3. Each artifact is declared (size + SHA-256) and uploaded **directly to object storage** through a short-lived signed URL. 4. The server re-reads the stored bytes, recomputes the checksum, signs the artifact with your project's Ed25519 key and marks it verified. A mismatch fails the release. 5. Once every platform has a verified artifact the release becomes **Ready**, and `--channel` deploys it. ## 5. Roll out gradually ```bash stacklift release promote 1.0.0 --to production --percentage 5 stacklift status stacklift rollout advance --channel production stacklift rollout set 50 --channel production ``` Percentages only go up. Nothing expands automatically unless you opt in with `--auto-expand --interval `. ## 6. Roll back ```bash stacklift release rollback --channel production --to 0.9.0 --reason "crash on launch" ``` The CLI (and the API) refuse a rollback to a release that devices can't run: different runtime version, missing platform, unverified artifact, or an artifact kind that can't be reverted through Stacklift. ## 7. Wire the SDK into your app See the [SDK guide](https://stacklift.joynul.com/docs/sdk.md). The app embeds the **public key** and pins your project's signing public key. --- # Concepts ## Organizations, workspaces, projects An **organization** is the tenant boundary: members, roles, billing and audit log live there. **Workspaces** group projects inside it. A **project** is one application. Roles are Owner, Admin, Developer and Viewer. A *project membership* can raise a person's role for one project (never lower it). ## Runtime version The runtime version is the compatibility key between a release and an installed binary. You set it; Stacklift enforces it: - a device only receives a release whose `runtimeVersion` equals the one it reports; - a rollback is refused across runtime versions; - bump it whenever native code, native modules, permissions or the JS engine change. ## Releases A release is a version plus verified artifacts. Statuses: | Status | Meaning | | --- | --- | | Draft | Created, no artifacts yet | | Uploading | Waiting for artifacts | | Processing | The server is verifying bytes and signing | | Ready | Every platform has a verified, signed artifact. Deployable | | Deploying | A deployment or staged rollout is in progress | | Active | A channel is actually serving it | | Failed | Verification failed | | Rolled back | Was served, then replaced by a rollback | | Archived | Retired; read-only | A release can carry more than one artifact per platform, as long as the kinds differ: for example a `script-bundle` (rules in JavaScript) and a `ui-layout` (a server-driven screen layout) together. Each SDK asks for the kind it handles. Transitions are enforced in one place (`@stacklift/shared`), with row-level locks so concurrent operations can't interleave. ## Channels and environments Channels (`production`, `staging`, `development`, `beta`, or your own) are what devices subscribe to. A channel points at exactly one release at a time. Environments label where a build is meant to run and can be attached to channels and releases. > A channel serves **one** release. If you deploy a release with a different runtime version, devices on the old runtime stop receiving updates from that channel. The dashboard and CLI warn before you do it. ## Deployments, rollouts, rollbacks - A **deployment** records the intent to point a channel at a release. It starts `Pending` and only becomes `Succeeded` when the engine has switched the channel in a transaction. - A **rollout** is a deployment below 100%. Devices are bucketed by `sha256(rolloutId : deviceId) mod 100`; a device is in the cohort when its bucket is below the percentage. Raising the percentage only adds devices. Cancelling returns the cohort to the baseline release. - A **rollback** points the channel back at an earlier compatible release, cancels any in-flight rollout on it and records the reason. ## Update checks The delivery plane answers one question: *which release should this device run?* It considers the channel, the active rollout cohort, the runtime version, the platform, the artifact kind the SDK asks for (optional) and whether a verified deliverable artifact exists. Native binaries (`native-binary`, i.e. store builds) and container image references are never offered as updates — store builds are *recorded* by the CLI without being uploaded, see [Store releases](https://stacklift.joynul.com/docs/store-releases.md); desktop installers (`desktop-installer`) are, because the installer is the update mechanism on desktop — see [Desktop apps](https://stacklift.joynul.com/docs/desktop.md). --- # Use Stacklift with an LLM You can hand these docs to ChatGPT, Claude, Cursor, Copilot or any other assistant and let it set up and run Stacklift with you: write `stacklift.yaml`, wire the SDK into your app, write a CI job, or build a server-driven layout. ## Copy a page or all of them - **Copy for LLM**, at the top of every docs page, copies that page as Markdown. The copy starts with a short description of Stacklift and the page's purpose, and every link is a full address, so the assistant understands it without the rest of the site. - **Copy all docs for LLM**, on the [documentation home](https://stacklift.joynul.com/docs), copies every page in one go. Use it for broad questions ("how do I ship my Flutter app with Stacklift?"). It is long, so prefer single pages when your assistant has a small context window. - **Markdown**, next to the copy button, opens the page as plain Markdown in the browser. ## Addresses for tools that read the web | Address | What it is | | --- | --- | | `/llms.txt` | An index following the [llms.txt](https://llmstxt.org) convention: what Stacklift is, and every page with a one-line summary | | `/llms-full.txt` | Every page in one file | | `/docs/.md` | One page as Markdown, for example `/docs/cli.md` | | `/api/openapi.json` | The OpenAPI document: every REST endpoint with its request and response schema (`/api/docs` is the same, browsable) | Give an agent the first address and it can find the rest. The pages carry a `text/markdown` alternate link in their HTML head as well. ## Prompts that work Paste the page (or pages), then ask. Name your stack and what you already have. - "Using these Stacklift docs, write a `stacklift.yaml` and a GitHub Actions job that creates a release for my Expo app on every push to main and deploys it to `staging` at 10%." (paste: CLI, stacklift.yaml, CI/CD) - "Add Stacklift update checks to my SwiftUI app. Pin the signing key and only check on launch." (paste: SDK) - "Turn this SwiftUI screen into a stacklift-ui/1 layout, keep my current view as the fallback, and give me the JSON and the Swift code to wrap it." (paste: Server-driven UI) - "Which of these can I update over the air in a native Android app, and which need a Play Store release?" (paste: OTA for every stack, Stack adapters) ## Check what it gives you - **Commands and flags:** the [CLI reference](https://stacklift.joynul.com/docs/cli.md) is complete. If the assistant uses a flag that is not there, it made it up. - **Layouts:** run `stacklift ui validate ` before publishing. It runs the same checks as the server and names the exact problem. - **Limits:** the docs say plainly what is not built (for example, the iPhone widget renderer, Expo and Capacitor code push, or Flutter code push). If an answer depends on one of those, it will not work yet. - **Secrets:** never paste secret keys (`slk_…`), tokens or private keys into a chat. The docs never need them; use placeholders. ## Writing docs that stay LLM-friendly For contributors. Every page in `docs/` is read by people and by assistants, so: - Start with one sentence saying what the page is for, and register it in `apps/web/src/lib/docs.ts` with a one-line summary (used by `/llms.txt`). - Make sections stand alone: name the thing again instead of "the above" or "as mentioned". - Give exact, copyable commands, flags, file names and endpoints, with real values in examples. - Link other pages as `/docs/`; the exports turn these into full addresses. - Say what is not built or not verified, in the page where it matters. --- # CLI reference ```text stacklift [--json] [--api-url ] [--org ] [--project ] ``` Global flags work on every command and override `stacklift.yaml`. | Variable | Purpose | | --- | --- | | `STACKLIFT_TOKEN` | Personal access token (`slp_…`) or project secret key (`slk_…`) — the CI way to authenticate | | `STACKLIFT_API_URL` | API base URL. The published CLI defaults to the hosted Stacklift API; a build from source defaults to `http://localhost:4000` | | `NO_COLOR` | Disable colours | ## Output and exit codes With `--json`, **only** the result goes to stdout; progress is written to stderr. Errors are `{ "ok": false, "error": { "message", "hint" } }`. | Code | Meaning | | --- | --- | | 0 | Success | | 1 | Error | | 2 | Usage or configuration problem | | 3 | Not authenticated | | 4 | Network error | | 5 | Timed out waiting | | 6 | Release or deployment failed | | 7 | Refused (for example an unsafe rollback) | ## Authentication - `stacklift login [--token ] [--email ] [--api-url ]` - `stacklift logout` — revokes the stored token and deletes it locally - `stacklift whoami` ## Projects - `stacklift init [--org] [--project] [--stack] [--channel] [--runtime-version] [--yes] [--force]` — detect the stack and write `stacklift.yaml` - `stacklift project list` - `stacklift project create --name --stack --platforms android,ios --app-id com.acme.app` ## Releases - `stacklift release create [--version ] [--build-number ] [--runtime-version ] [--artifact …] [--native …] [--store-status ] [--channel |--deploy] [--percentage n] [--auto-expand --interval m] [--max-failure-rate 0.05] [--resume] [--timeout s] [-m notes]` — version, build number and app id are **read from the project** when not given. `--artifact` uploads and verifies a hosted artifact; `--native` (or an `--artifact` of kind `native-binary`) **records a store build without uploading it**. See [Store releases](https://stacklift.joynul.com/docs/store-releases.md). - `stacklift release list [--status READY] [--limit n]` - `stacklift release show ` — artifacts with checksums, where it is served, install numbers (checks, downloads, installs, failures, devices) and recent deployments - `stacklift release compare ` — runtime compatibility, which artifacts changed, and whether one can safely replace the other - `stacklift release archive ` — hide a release you no longer need (refused while a channel serves it) - `stacklift release promote --to [--percentage n]` - `stacklift release rollback --channel --to --reason [--dry-run]` `--resume` makes `release create` safe to re-run in CI: an existing release with the same version is reused and already-verified artifacts are skipped. When an `--artifact` is a `ui-layout`, the CLI runs the layout checks before uploading anything, so a broken layout fails on your machine instead of on the server. ## Server-driven UI - `stacklift ui validate ` — the same checks the server runs before signing a layout: the format, every component and property, https-only links, bindings, and the size and depth limits. Errors exit non-zero; warnings (usually typos in property names) do not. - `stacklift ui list` — published layouts, newest first, with the channels serving each. - `stacklift ui pull [-o ]` — download a published layout to edit it locally (`id` is the short id from `ui list`). - `stacklift ui export --screen --to swiftui|flutter [--name ] [-o ]` — eject one screen to ordinary SwiftUI or Flutter source with no Stacklift dependency. Without `-o` the code is printed. Publish a layout like any artifact: `stacklift release create --artifact ios:ui-layout:./home.json`. See [Server-driven UI](https://stacklift.joynul.com/docs/server-driven-ui.md). ## Keys, tokens and webhooks - `stacklift key list` / `create --type public|secret [--scope s]… [--expires-in-days n]` / `rotate [--grace-hours n]` / `revoke ` — project API keys. Public keys go inside your app and can only check for and report updates; secret keys are for CI. A new key is printed **once**. `` is the short id from `key list`. - `stacklift token list` / `create [--expires-in-days n]` / `revoke ` — your personal access tokens. Create one and set it as `STACKLIFT_TOKEN` in CI. - `stacklift webhook list` / `create [--event e]…` / `enable ` / `disable ` / `test ` / `deliveries ` / `delete ` — signed HTTP callbacks (see [Webhooks](https://stacklift.joynul.com/docs/webhooks.md)). The signing secret is printed once. - `stacklift audit [--action a] [--limit n]` — who did what in the organization. Everything here is also available in the dashboard and the API: the CLI is a convenience, not a requirement. ## Store listings and status - `stacklift store link ` / `stacklift store unlink ` — the store listing link (https, on the store's own host). - `stacklift store status [--build-number n] [--url u]` — where a build is in its store journey. Stacklift has no store API access: this is what you tell it. - `stacklift store show` — links (with derived ones flagged) and the store state of recent releases. ## Channels, deploy, rollouts, status - `stacklift channel list` / `stacklift channel create [--name]` - `stacklift deploy [version] [--channel] [--percentage] [--wait]` — without a version, deploys the latest ready release - `stacklift rollout pause|resume|cancel|advance [rolloutId] [--channel]` - `stacklift rollout set [rolloutId] [--channel]` - `stacklift status` — what each channel serves, in-flight rollouts, recent deployments ## Diagnostics - `stacklift doctor` — Node version, config validity, adapter checks, credentials, API reachability, project access, artifact paths - `stacklift upgrade` — checks npm for a newer CLI - `stacklift version` --- # stacklift.yaml The project configuration file. The CLI finds it by walking up from the working directory, like git finds `.git`. It is validated with the same zod schema the CLI ships. ```yaml version: 1 project: org: acme # organization slug project: acme-mobile stack: react-native # adapter id appIdentifier: com.acme.mobile platforms: [android, ios] runtimeVersion: 1.0.0 defaultChannel: staging stores: # optional; synced on `release create` ios: https://apps.apple.com/us/app/my-app/id1234567890 android: https://play.google.com/store/apps/details?id=com.acme.app build: command: npm run bundle # informational; Stacklift does not run it artifacts: - { platform: android, kind: js-bundle, path: dist/android.zip } - { platform: ios, kind: js-bundle, path: dist/ios.zip } rollout: percentage: 100 autoExpand: false # explicit opt-in only steps: [5, 25, 50, 100] intervalMinutes: 120 maxFailureRate: 0.05 ``` | Field | Notes | | --- | --- | | `version` | Always `1` | | `project.org`, `project.project` | Slugs or ids. `--org` / `--project` override them | | `stack` | One of the adapter ids from `GET /api/v1/adapters` | | `platforms` | Must be supported by the stack | | `runtimeVersion` | Compatibility key; required to create a release (here or via flag) | | `defaultChannel` | Used by `deploy` and `release create --deploy` | | `stores.*` | Store listing links per platform (`ios`, `android`, `macos`, `windows`, `linux`). https and the store's own host only. Synced to the project on `release create` (needs `project:update`; skipped otherwise) | | `build.artifacts` | Used by `release create` when no `--artifact` is passed. Paths are relative to the file | | `rollout.*` | Defaults for staged rollouts. `autoExpand` needs `intervalMinutes` | Run `stacklift doctor` to validate the file against the adapter. --- # SDKs Every Stacklift client does the same three things: **check** the delivery plane, **download** the artifact, and **verify** it (SHA-256 + Ed25519) before anything touches it. *Applying* the update — swapping a JS bundle, running a desktop installer — is your app's job; see each stack's [adapter](https://stacklift.joynul.com/docs/adapters.md) for what exists today. ## Which SDK for which stack | Stack | Package | Verified by | Not verified | | --- | --- | --- | --- | | React Native (code push, server-driven screens) | `@stacklift/react-native` (`packages/sdk-react-native`): JavaScript API, `StackliftScreen`, native modules on top of the Swift and Android SDKs | 10 renderer and recovery tests; the demo app (release builds) on the iOS simulator, an Android 17 emulator and a physical HONOR ELI-NX9 phone (Android 16) against a live server: update, crash recovery, rollback | A physical iPhone; not published to npm | | Expo, Capacitor / Ionic, NativeScript, browsers, Electron renderer (check and verify only) | `@stacklift/sdk-js` (`packages/sdk-js`) | 31 unit tests + an end-to-end test against the real API | Inside a real RN / Capacitor / NativeScript app | | Electron | `@stacklift/sdk-electron` (`packages/sdk-electron`) | 15 tests: fake Electron APIs, real HTTP server | Inside a running Electron app | | iOS, macOS (Swift) | Swift package `Stacklift` (`packages/sdk-swift`): client, scripts, server-driven UI | `swift test`, 37 tests on macOS; scripts, layouts and code push run in demo apps on the iOS simulator | A physical device | | Flutter / Dart — Android, iOS, web, Windows, macOS, Linux | `stacklift` (`packages/sdk-dart`): client, scripts and layouts lifecycle | `dart test`, 80 tests on the Dart VM | Web target | | Flutter widgets | `stacklift_flutter_scripts` (`packages/sdk-flutter-scripts`), `stacklift_flutter_ui` (`packages/sdk-flutter-ui`) | `flutter test`: 14 (real JS interpreter) and 9 (real rendering); both run in a demo app on the iOS simulator | Android, a physical device | | .NET — WPF, WinForms, WinUI, MAUI, Unity | `Stacklift.Sdk`, `netstandard2.0` (`packages/sdk-dotnet`) | `dotnet test`, 39 tests on .NET 10 | .NET Framework, MAUI platform heads, Unity | | Android (Kotlin, Jetpack Compose) | `packages/sdk-android`: Compose screens, QuickJS scripts, update lifecycle, on top of the Java SDK | 28 JVM tests; 15 device tests on an Android 17 emulator and a physical HONOR phone (Android 16); a demo app against a live server on both; a shrunk (R8) release build of the demo on the emulator | R8 build on a phone | | Android (Java), JVM desktop (JavaFX, Compose Desktop, Swing) | Java `dev.stacklift` (`packages/sdk-java`) | JUnit 5, 43 tests on JDK 21, real sockets | — | | Node (CLI, CI, servers) | The `stacklift` CLI embeds the Node client; in your own Node code use `@stacklift/sdk-js` | Unit tests + e2e | — | | Kotlin Multiplatform (`androidMain`, `jvmMain`) | `packages/sdk-kotlin` | **Untested.** Never compiled — no Kotlin toolchain here | Everything. It wraps the Java SDK in coroutines | | Tauri / Rust | `packages/sdk-tauri` | **Untested.** Never compiled — no Rust toolchain here | Everything. Prefer `@stacklift/sdk-js` from the frontend first | | Qt / C++, GTK, Win32, Go, others | none | — | Implement the [contract](#the-contract) below | None of these are published to a package registry yet; use them from this repository (path / workspace dependencies). The four tested non-TypeScript SDKs (Swift, Dart, .NET, Java) and `sdk-js` all pass the **same 14 conformance vectors** (see [Conformance](#conformance)), which were generated by the control plane's own signing code. That is what makes "the Swift SDK and the server agree" a tested statement instead of a hope. ## Pin the key Pass the project's Ed25519 public key (Project → Integration) to every client as `pinnedPublicKey`. Without it the client trusts the key delivered in the same response as the signature, which only protects against corruption — not against a compromised server. With it, a manifest signed by any other key is rejected (`key_mismatch`). ## Quick starts ### JavaScript / TypeScript (`@stacklift/sdk-js`) No Node built-ins: pure-JS Ed25519 and SHA-256, `fetch` and storage are injected. Works wherever `fetch` does. ```ts import { StackliftClient, getOrCreateDeviceId } from '@stacklift/sdk-js'; const client = new StackliftClient({ baseUrl: 'https://delivery.example.com', apiKey: 'slk_…', pinnedPublicKey: PINNED_PEM }); const deviceId = await getOrCreateDeviceId(AsyncStorage); // any {getItem,setItem}; random, not hardware-derived const manifest = await client.check({ channel: 'production', platform: 'ios', runtimeVersion: '2.3.0', currentVersion: '2.3.1', deviceId }); if (manifest.updateAvailable) { const { bytes } = await client.downloadToMemory(manifest); // small bundles; stream to a sink for big files // …apply the bundle with your runtime… await client.report({ type: 'INSTALL_SUCCESS', releaseId: manifest.release!.id, channel: 'production', platform: 'ios', deviceId }); } ``` - **React Native:** install `react-native-get-random-values` before first use (Hermes has no secure random). The default RN `fetch` has no streaming body, so downloads are buffered in one chunk — fine for JS bundles, not for 1 GB files. - **Large files:** implement `ArtifactSink { write, close, abort }`. `close()` runs only after every check passed; `abort()` on any failure. - Errors are `StackliftError` with a stable `code` (see [error codes](#error-codes)). ### Electron ```ts import { app, shell } from 'electron'; import { StackliftElectronUpdater } from '@stacklift/sdk-electron'; const updater = new StackliftElectronUpdater({ app, shell, baseUrl, apiKey, channel: 'stable', pinnedPublicKey: PINNED_PEM }); const update = await updater.check(); // null if nothing to install if (update) { const file = await updater.download(update); await updater.installAndQuit(file); } // on the next launch of the new version: await updater.reportInstalled(previousVersion, releaseId); // the real success signal ``` The installer is streamed to `userData/updates//.part` and renamed only after verification. The installer's file name comes from the server **unsigned**, so it is stripped to a base name and must carry an extension allowed for the OS — a manifest naming `payload.bat` is refused. `installAndQuit` reports nothing itself: handing a file to the OS says nothing about whether the install worked. ### Swift (iOS, macOS) ```swift let client = StackliftClient(StackliftOptions(baseURL: URL(string: "https://delivery.example.com")!, apiKey: "slk_…", pinnedPublicKey: pem)) let manifest = try await client.check(CheckRequest(channel: "stable", runtimeVersion: "2.3.0", currentVersion: "2.3.1", deviceId: DeviceIdentity.getOrCreate())) if manifest.updateAvailable { try await client.download(manifest, to: installerURL) } // verified before it appears at installerURL ``` URLSession downloads to a temporary file first, so an oversized response is rejected before it is hashed or moved (the early abort the other SDKs do mid-stream isn't possible here). Apple's rules for downloaded code on iOS (Guideline 3.3.2) still apply: Stacklift never offers executable-code updates for native iOS apps. **Scripted logic updates (`StackliftScripts`).** For native apps that cannot push compiled code, the Swift package (and, for Flutter, `packages/sdk-dart` with `packages/sdk-flutter-scripts`) can also stage, apply on the next launch, confirm and roll back signed JavaScript run in JavaScriptCore with only the functions your app registers. See [OTA for every stack](https://stacklift.joynul.com/docs/ota-layers.md). **Server-driven UI (`StackliftLayouts`, `StackliftScreen`).** Wrap a SwiftUI screen once, keep your current screen as the fallback, and change its text, order, lists, tables and buttons by publishing a layout. Same next-launch apply and rollback as scripts. See [Server-driven UI](https://stacklift.joynul.com/docs/server-driven-ui.md). ### Dart / Flutter ```dart import 'package:stacklift/stacklift_io.dart'; // 'package:stacklift/stacklift.dart' is the web-safe core final client = StackliftClient(baseUrl: Uri.parse('https://delivery.example.com'), apiKey: 'slk_…', pinnedPublicKey: pem); final m = await client.check(CheckRequest(channel: 'stable', platform: currentStackliftPlatform(), runtimeVersion: '2.3.0', deviceId: await DeviceId.getOrCreate(store))); if (m.updateAvailable) await client.downloadToFile(m, File('${dir.path}/update.msix')); ``` Scripts and server-driven screens for Flutter: `StackliftScripts` and `StackliftLayouts` live in this package (plain Dart), the `StackliftScreen` widget in `packages/sdk-flutter-ui` and the JavaScript runtime in `packages/sdk-flutter-scripts`. See [Server-driven UI](https://stacklift.joynul.com/docs/server-driven-ui.md) and [OTA for every stack](https://stacklift.joynul.com/docs/ota-layers.md). Wrap `shared_preferences` as a `KeyValueStore`. Dart OTA ("code push") for Android/iOS is **not** provided — it needs a patched Flutter engine. ### .NET (WPF, WinForms, MAUI, Unity) ```csharp var client = new StackliftClient(new StackliftOptions { BaseUrl = new Uri("https://delivery.example.com"), ApiKey = key, PinnedPublicKey = pem }); var m = await client.CheckAsync(new CheckRequest { Channel = "stable", Platform = StackliftPlatform.Desktop(), RuntimeVersion = "2.3.0", DeviceId = await DeviceId.GetOrCreateAsync(store) }); if (m.UpdateAvailable) await client.DownloadToFileAsync(m, installerPath); ``` Ed25519 comes from BouncyCastle (`BouncyCastle.Cryptography`); .NET has no built-in verifier. `netstandard2.0` can't tell Android from iOS, so pass `"android"` / `"ios"` yourself under MAUI. ### Java (Android, JVM desktop) ```java StackliftClient client = new StackliftClient("https://delivery.example.com", "slk_…", PINNED_PEM); // blocking: call off the UI thread UpdateManifest m = client.check(new CheckRequest("stable", StackliftPlatform.current(), "2.3.0", "2.3.1", deviceId, null)); if (m.updateAvailable) client.downloadToFile(m, new File(cacheDir, "update.bin"), null); ``` No dependencies. Ed25519 uses the JCA: JDK 15+, **Android API 33+**; on older Android register BouncyCastle or Conscrypt as a provider first. Run its tests with `packages/sdk-java/scripts/test.sh`. `CheckRequest` takes an optional `kind` (for example `ui-layout`) as its last argument. ### Android (Kotlin, Jetpack Compose) `packages/sdk-android` adds what native Android apps need on top of the Java SDK: `StackliftScreen` (server-driven screens in Compose), `StackliftScripts` (scripted logic in QuickJS) and the launch-safe lifecycle (apply on the next launch, confirm, roll back). See [Server-driven UI](https://stacklift.joynul.com/docs/server-driven-ui.md) and [OTA for every stack](https://stacklift.joynul.com/docs/ota-layers.md). While developing against a local server on an emulator, use `adb reverse tcp:4100 tcp:4100` and `http://localhost:4100`: apps that target Android 17 cannot reach private addresses such as `10.0.2.2` without the `ACCESS_LOCAL_NETWORK` permission. ## Guarantees All SDKs, in this order: 1. **Signature before bytes.** The manifest's signature is verified *before* the artifact URL is requested. A forged manifest never causes a download. 2. **Pinned key.** If a key is pinned and the manifest carries a different one: `key_mismatch`. 3. **Exact size.** Reading stops as soon as the server sends more than the signed size (Swift: checked after the temporary download, because URLSession cannot stop mid-stream). 4. **SHA-256.** Hashed incrementally; compared to the signed value. 5. **Nothing partial survives.** Files are written to `.part` and renamed only after 3 and 4 passed; any failure deletes the partial file. The signature covers `sha256`, `size`, `releaseId`, `version`, `platform`, `runtimeVersion` and `kind`. It does **not** cover `artifact.filename`, `url`, `expiresAt` or `description` — treat those as untrusted. Download URLs are short-lived (15 minutes); with the S3 driver they point at the bucket/CDN and the API never proxies artifacts. `deviceId` is hashed with the project id before storage; raw ids aren't kept. ## The contract For any language without an SDK. All requests carry `x-stacklift-key: ` and `content-type: application/json`. The official SDKs also send `x-stacklift-sdk: / mark=`, a diagnostic header. Your own client does not need it and is never rejected for leaving it out. **Check** — `POST /v1/updates/check` ```json { "channel": "stable", "platform": "windows", "runtimeVersion": "2.4.0", "currentVersion": "2.3.0", "deviceId": "device-0123456789", "environment": "production" } ``` `currentVersion` and `environment` are optional; `deviceId` is 8–128 chars. Response either `{"updateAvailable": false, "reason": "…"}` or: ```json { "updateAvailable": true, "release": { "id": "rel_…", "version": "2.4.1", "runtimeVersion": "2.4.0", "description": null, "kind": "desktop-installer", "platform": "windows", "artifact": { "url": "https://…", "filename": "App-2.4.1.msi", "sha256": "…", "size": 338, "signature": "", "expiresAt": "…" } }, "publicKey": "-----BEGIN PUBLIC KEY-----…" } ``` Reasons: `up_to_date`, `runtime_mismatch`, `platform_not_supported`, `nothing_deployed`, `channel_not_found`, `no_deliverable_artifact`, `project_not_found`. **Report** — `POST /v1/updates/events` with `{ "type": "DOWNLOAD" | "INSTALL_SUCCESS" | "INSTALL_FAILURE", "releaseId", "channel", "platform", "deviceId", "fromVersion"?, "errorCode"?, "errorMessage"? }`. Telemetry must never block an update: ignore failures. **Verify** — the signed text is these lines joined with `\n` (no trailing newline), encoded as UTF-8: ``` stacklift-artifact-v1 sha256: size: release: version: platform: runtime: kind: ``` The signature is Ed25519 over those bytes, base64-encoded (64 bytes raw). The public key is a PEM `PUBLIC KEY` (SubjectPublicKeyInfo): a fixed 12-byte DER prefix `302a300506032b6570032100` followed by the 32-byte key. Compare the downloaded size in **bytes** (not characters) and the SHA-256 of the raw bytes. ### Error codes `signature_invalid`, `key_mismatch`, `checksum_mismatch`, `size_mismatch`, `no_key`, `no_update`, `http_error`, `bad_response`, `network_error`, `aborted`, `unsupported`. ## Conformance `packages/sdk-conformance/vectors.json` holds the vectors: a valid artifact (with a multibyte character so byte-vs-character length bugs show up), the same artifact with each signed field tampered after signing, a different signing key, a pinned-key mismatch, a garbage signature / key, and served bytes that are modified or truncated. Each case names the error code an SDK must report. It is generated with the control plane's real signing code: The vectors are generated by Stacklift's real signing code and regenerated by the maintainers; every SDK in this repository must pass them unchanged. Run every SDK's suite: ```bash pnpm --filter @stacklift/sdk-js test && pnpm --filter @stacklift/sdk-electron test (cd packages/sdk-swift && swift test) (cd packages/sdk-dart && dart pub get && dart test) (cd packages/sdk-dotnet && dotnet test tests) packages/sdk-java/scripts/test.sh ``` To add a language, make it pass every case and add its suite to CI. --- # API Interactive OpenAPI documentation is served by the API itself: - Swagger UI: `/api/docs` - Raw spec: `/api/openapi.json` Request bodies in the spec are generated from the same zod schemas used for validation, so they can't drift. ## Conventions - Base: `/api/v1`. JSON in, JSON out. `Authorization: Bearer `. - Tokens: user access JWT, personal access token (`slp_…`), project secret key (`slk_…`, project-scoped). - Organizations and projects are addressed by **slug or id**: `/orgs/{org}/projects/{project}/…`. - Errors: `{ "statusCode": 400, "message": "Validation failed", "issues": [{ "path": "email", "message": "…" }] }`. A refused rollback adds `reasons: string[]`. - Pagination: cursor based (`limit`, `cursor` → `nextCursor`). - Idempotency: `Idempotency-Key` on deploy/promote. - Rate limits: 429 with standard headers. - Real time: `GET /orgs/{org}/events` (Server-Sent Events, bearer-authenticated; use `fetch` streaming rather than `EventSource`). ## Main resources | Area | Endpoints | | --- | --- | | Auth | `POST /auth/register|login|refresh|logout|forgot-password|reset-password|verify-email`, `GET /auth/providers`, `POST /auth/firebase` (Google or GitHub sign-in with a Firebase ID token) | | Me | `GET/PATCH /me`, `POST /me/password`, `GET/POST/DELETE /me/tokens` | | Orgs | `POST /orgs`, `GET/PATCH/DELETE /orgs/{org}`, workspaces, members, invitations, `GET /orgs/{org}/audit-logs` | | Projects | `GET/POST /orgs/{org}/projects`, `GET/PATCH/DELETE …/{project}`, `…/integration`, members, environments, channels | | Releases | `GET/POST …/releases`, `GET/PATCH …/releases/{id}`, `…/releases/compare`, `POST …/archive` | | Artifacts | `POST …/releases/{id}/artifacts` (declare → signed URL), `POST …/artifacts/{aid}/complete` | | Layouts | `GET …/projects/{project}/layouts` (verified `ui-layout` artifacts, newest first, with the channels serving each), `GET …/layouts/{artifactId}` (that layout's JSON). Read-only, `release:read`; publishing goes through releases | | Deployments | `POST …/releases/{id}/deployments`, `…/promote`, `GET /orgs/{org}/deployments` | | Rollouts | `GET /orgs/{org}/rollouts`, `GET …/rollouts/{id}`, `POST …/rollouts/{id}/actions` | | Rollbacks | `GET …/rollbacks/preview`, `POST …/rollbacks`, `GET …/rollbacks` | | Analytics | `GET /orgs/{org}/dashboard`, `/analytics/overview|timeline|versions|platforms|errors|releases` | | API keys | `GET/POST …/api-keys`, `POST …/{id}/rotate`, `DELETE …/{id}` | | Integrations | `GET …/integrations/catalog`, webhook CRUD, `…/test`, `…/deliveries` | | Adapters | `GET /adapters`, `GET /adapters/{id}` (public) | Delivery plane (separate port): `POST /v1/updates/check`, `POST /v1/updates/events`, `GET /v1/artifacts/download` (local driver only). `POST /v1/updates/check` takes an optional `kind` (for example `ui-layout` or `script-bundle`). A release can carry several artifacts for one platform; with `kind` the device gets that artifact, without it the first deliverable one (what older SDKs expect). A release with nothing of that kind answers `updateAvailable: false` with `reason: "no_deliverable_artifact"`. ## Upload flow ```text POST …/releases/{id}/artifacts { platform, kind, filename, size, sha256 } → { artifact, upload: { url, method: "PUT", headers, expiresAt } } PUT (file bytes — directly to storage) POST …/artifacts/{artifactId}/complete → artifact is verified asynchronously; poll GET …/releases/{id} until READY or FAILED ``` Send the bytes with any `Content-Type` (the dashboard sends `application/json` for a layout); the upload receiver never parses the body. During verification a `ui-layout` is also run through the layout checks, and a failure names the exact place, for example `Invalid layout: screens.home.body.children[0].type: unknown component "carousel"`. A failed artifact can be uploaded again into the same release. --- # Stack adapters Stacklift does not assume every stack can be updated the same way. Each ecosystem is an **adapter** that declares what is technically and contractually possible, and the control plane enforces it. An adapter describes: - **Capabilities** — for each update mechanism (`ota`, `web-deploy`, `backend-deploy`, `native-release`, `desktop-update`, `config-assets`): a support level (`supported`, `partial`, `planned`, `unsupported`), platforms, whether clients verify signatures, platform **restrictions** and Stacklift's own **limitations**. - **Artifacts** — accepted kinds, file extensions, size caps and platforms. - **Rollbackable kinds** — which artifact kinds can be reverted by repointing a channel. Native binaries and desktop installers never can. - **Detection** — how `stacklift init` recognises the stack from a file listing. - **Validation** — project configuration and artifact checks (`validateProjectConfig`, `validateArtifact`). - **Integration guide** — Markdown shown in the dashboard and docs. - **Client runtime** — whether anything exists on the device side to *apply* updates. ```ts interface StackAdapter { id: string; displayName: string; language: string; ecosystem: 'mobile' | 'desktop' | 'web' | 'backend'; maturity: 'beta' | 'alpha' | 'planned'; clientRuntime: { status: 'available' | 'partial' | 'planned' | 'not-applicable'; notes: string }; platforms: Platform[]; capabilities: AdapterCapability[]; artifacts: ArtifactSpec[]; rollbackableKinds: ArtifactKind[]; detect(probe: FileProbe): DetectionResult; validateProjectConfig(config): ValidationIssue[]; validateArtifact(input): ValidationIssue[]; integrationGuide(): string; } ``` Register a new adapter with `registry.register(adapter)` from `@stacklift/adapters`. Everything else — the API, CLI validation, dashboard capability panel and this page — reads from the registry. ## Capability matrix Generated from the registry by `pnpm docs:adapters` (CI fails if it is stale). Legend: **supported** = implemented end to end; *partial* = usable with the restrictions listed in the adapter; *planned* = designed, **not implemented**; *never* = technically or contractually impossible and never offered; *n/a* = not a capability of this stack. ### Mobile (and cross-platform) | Stack | Maturity | Platforms | OTA | Server UI | Scripts | Native release | Desktop installer | Config & assets | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `flutter` Flutter | planned | android, ios, web, windows, macos, linux | planned | partial | partial | partial | partial | partial | | `react-native` React Native | alpha | android, ios | partial | partial | n/a | partial | n/a | partial | | `expo` Expo | alpha | android, ios | partial | n/a | n/a | partial | n/a | partial | | `android` Android (Kotlin) | alpha | android | never | partial | partial | partial | n/a | partial | | `ios` iOS (Swift) | alpha | ios | never | partial | partial | partial | n/a | partial | | `kmp` Kotlin Multiplatform / Compose Multiplatform | alpha | android, ios, windows, macos, linux | never | partial | partial | partial | partial | partial | | `capacitor` Capacitor / Ionic | alpha | android, ios, web | partial | n/a | n/a | partial | n/a | partial | | `nativescript` NativeScript | alpha | android, ios | partial | n/a | n/a | partial | n/a | partial | | `maui` .NET MAUI | alpha | android, ios, windows, macos | never | partial | partial | partial | partial | partial | | `unity` Unity | alpha | android, ios, windows, macos, linux | never | partial | partial | partial | partial | partial | **Client runtime** (what exists on the device to apply updates): - **Flutter** — *partial*. The Dart SDK (packages/sdk-dart) checks, downloads and verifies config/asset bundles, web builds and desktop installers, and with packages/sdk-flutter-scripts runs signed script bundles (scripted logic updates). Dart code OTA on Android/iOS ("code push") needs a patched Flutter engine and a patch toolchain Stacklift does NOT ship. - **React Native** — *partial*. @stacklift/react-native (packages/sdk-react-native) loads a new JS bundle on the next launch, confirms it, and rolls back to the last good or built-in bundle when a launch never confirms or crashes first. Its native side is the Swift SDK (iOS) and the Android SDK, which verify every bundle (SHA-256 + Ed25519). It also renders server-driven screens. Verified on the iOS simulator, an Android emulator and a physical Android 16 phone; not published to npm yet. - **Expo** — *partial*. @stacklift/sdk-js performs check → download → verification in JS. Activating the bundle needs a native loader or an implementation of the Expo Updates protocol; Stacklift ships neither, so Expo apps do not use expo-updates against Stacklift yet. - **Android (Kotlin)** — *not-applicable*. Binaries are distributed by the platform store. Remote config/asset bundles can be fetched and verified with the Android SDK (packages/sdk-android: Compose screens, QuickJS scripts, update lifecycle; built on the Java SDK in packages/sdk-java; tested on an Android 17 emulator and a physical Android 16 phone; Ed25519 needs Android API 33+, or register BouncyCastle/Conscrypt). - **iOS (Swift)** — *not-applicable*. Binaries are distributed by the platform store. Remote config/asset bundles can be fetched and verified with the Swift package (packages/sdk-swift, tested with swift test on macOS). - **Kotlin Multiplatform / Compose Multiplatform** — *partial*. On Android and JVM desktop use the Java SDK (packages/sdk-java, tested on JDK 21). packages/sdk-kotlin is a coroutine wrapper over it for androidMain/jvmMain; it has NOT been compiled or tested (no Kotlin toolchain in Stacklift CI yet). There is no Kotlin iOS implementation: call the Swift package (packages/sdk-swift) from iOS code. - **Capacitor / Ionic** — *partial*. @stacklift/sdk-js checks, downloads and verifies the web bundle. Unpacking it and pointing the WebView at it needs a native Capacitor plugin that Stacklift does not ship yet. - **NativeScript** — *partial*. @stacklift/sdk-js checks, downloads and verifies the bundle. Activating it on-device is not implemented. - **.NET MAUI** — *partial*. Stacklift.Sdk (netstandard2.0, tested on .NET 10) checks, downloads and verifies. MAUI platform projects were not built here. - **Unity** — *partial*. Stacklift.Sdk (netstandard2.0) can be used from Unity for check, download and verification; it needs the BouncyCastle assembly. Not run inside Unity here. Stacklift does not implement the Addressables remote-catalog protocol. ### Desktop | Stack | Maturity | Platforms | Desktop installer | Native release | OTA | Config & assets | | --- | --- | --- | --- | --- | --- | --- | | `electron` Electron | alpha | windows, macos, linux | partial | partial | planned | partial | | `tauri` Tauri | planned | windows, macos, linux | partial | partial | planned | partial | | `dotnet-desktop` .NET desktop (WPF / WinForms / WinUI) | alpha | windows | partial | partial | never | partial | | `macos` macOS (Swift / AppKit) | alpha | macos | partial | partial | never | partial | | `jvm-desktop` JVM desktop (JavaFX / Compose / Swing) | alpha | windows, macos, linux | partial | partial | never | partial | | `qt` Qt / C++ | alpha | windows, macos, linux | partial | partial | never | partial | | `native-desktop` Other native desktop | alpha | windows, macos, linux | partial | partial | never | partial | **Client runtime** (what exists on the device to apply updates): - **Electron** — *partial*. @stacklift/sdk-electron checks, downloads and verifies the installer in the main process and hands it to the OS. It is unit-tested with fakes for the Electron APIs, not inside a running Electron app. No in-place asar patching. - **Tauri** — *planned*. A Rust plugin is provided as source in packages/sdk-tauri. It has NOT been compiled or tested (no Rust toolchain in Stacklift CI yet). From the web frontend you can use @stacklift/sdk-js for check and verification. - **.NET desktop (WPF / WinForms / WinUI)** — *partial*. Stacklift.Sdk (netstandard2.0, tested on .NET 10) checks, downloads and verifies. Launching the MSI/MSIX/EXE is done by your app. - **macOS (Swift / AppKit)** — *partial*. The Stacklift Swift package (CryptoKit, tested with swift test on macOS) checks, downloads and verifies. Opening the DMG/PKG is done by your app. Sparkle can still be used for the install step. - **JVM desktop (JavaFX / Compose / Swing)** — *partial*. The Java SDK (JDK 17+, no dependencies, tested on JDK 21) checks, downloads and verifies. Running the installer is done by your app. - **Qt / C++** — *planned*. No C++ SDK is shipped. The delivery API is plain HTTPS + JSON and the signature is Ed25519 over a documented text payload, so any language can verify it (see docs/sdk.md). - **Other native desktop** — *planned*. Choose this for any toolkit without its own adapter (GTK, wxWidgets, Win32, Go, Rust ...). No client SDK is shipped for it; the HTTP API and signature format are documented in docs/sdk.md. ### Web | Stack | Maturity | Platforms | Web deploy | Config & assets | | --- | --- | --- | --- | --- | | `react` React (SPA) | beta | web | **supported** | **supported** | | `nextjs` Next.js | alpha | web | **supported** | **supported** | | `vue` Vue | alpha | web | **supported** | **supported** | | `nuxt` Nuxt | alpha | web | **supported** | **supported** | | `angular` Angular | alpha | web | **supported** | **supported** | | `svelte` Svelte | alpha | web | **supported** | **supported** | | `sveltekit` SvelteKit | alpha | web | **supported** | **supported** | **Client runtime** (what exists on the device to apply updates): - **React (SPA)** — *partial*. Stacklift versions, signs and serves the build. Serving it to users is up to your host/edge/CDN: fetch the verified artifact in your deploy pipeline with the delivery API (docs/sdk.md) or @stacklift/sdk-core (Node) / @stacklift/sdk-js. No hosting is provided. - **Next.js** — *partial*. Stacklift versions, signs and serves the build. Serving it to users is up to your host/edge/CDN: fetch the verified artifact in your deploy pipeline with the delivery API (docs/sdk.md) or @stacklift/sdk-core (Node) / @stacklift/sdk-js. No hosting is provided. - **Vue** — *partial*. Stacklift versions, signs and serves the build. Serving it to users is up to your host/edge/CDN: fetch the verified artifact in your deploy pipeline with the delivery API (docs/sdk.md) or @stacklift/sdk-core (Node) / @stacklift/sdk-js. No hosting is provided. - **Nuxt** — *partial*. Stacklift versions, signs and serves the build. Serving it to users is up to your host/edge/CDN: fetch the verified artifact in your deploy pipeline with the delivery API (docs/sdk.md) or @stacklift/sdk-core (Node) / @stacklift/sdk-js. No hosting is provided. - **Angular** — *partial*. Stacklift versions, signs and serves the build. Serving it to users is up to your host/edge/CDN: fetch the verified artifact in your deploy pipeline with the delivery API (docs/sdk.md) or @stacklift/sdk-core (Node) / @stacklift/sdk-js. No hosting is provided. - **Svelte** — *partial*. Stacklift versions, signs and serves the build. Serving it to users is up to your host/edge/CDN: fetch the verified artifact in your deploy pipeline with the delivery API (docs/sdk.md) or @stacklift/sdk-core (Node) / @stacklift/sdk-js. No hosting is provided. - **SvelteKit** — *partial*. Stacklift versions, signs and serves the build. Serving it to users is up to your host/edge/CDN: fetch the verified artifact in your deploy pipeline with the delivery API (docs/sdk.md) or @stacklift/sdk-core (Node) / @stacklift/sdk-js. No hosting is provided. ### Backend | Stack | Maturity | Platforms | Backend deploy | Config & assets | | --- | --- | --- | --- | --- | | `node` Node.js | alpha | server | partial | **supported** | | `python` Python | alpha | server | partial | **supported** | | `go` Go | alpha | server | partial | **supported** | | `java` Java / JVM | alpha | server | partial | **supported** | | `dotnet` .NET | alpha | server | partial | **supported** | **Client runtime** (what exists on the device to apply updates): - **Node.js** — *partial*. Stacklift stores signed server bundles or container image references and tracks which release each channel points to. Your CD system (fetching and verifying the artifact through the delivery API or an SDK) performs the actual rollout to servers/orchestrators — Stacklift does not run your infrastructure. - **Python** — *partial*. Stacklift stores signed server bundles or container image references and tracks which release each channel points to. Your CD system (fetching and verifying the artifact through the delivery API or an SDK) performs the actual rollout to servers/orchestrators — Stacklift does not run your infrastructure. - **Go** — *partial*. Stacklift stores signed server bundles or container image references and tracks which release each channel points to. Your CD system (fetching and verifying the artifact through the delivery API or an SDK) performs the actual rollout to servers/orchestrators — Stacklift does not run your infrastructure. - **Java / JVM** — *partial*. Stacklift stores signed server bundles or container image references and tracks which release each channel points to. Your CD system (fetching and verifying the artifact through the delivery API or an SDK) performs the actual rollout to servers/orchestrators — Stacklift does not run your infrastructure. - **.NET** — *partial*. Stacklift stores signed server bundles or container image references and tracks which release each channel points to. Your CD system (fetching and verifying the artifact through the delivery API or an SDK) performs the actual rollout to servers/orchestrators — Stacklift does not run your infrastructure. ## Honest limits - **Native iOS/Android** binaries can only ship through the stores. Stacklift tracks them; it cannot update them. - **iOS** (App Store Review Guideline 3.3.2) and **Android** (Google Play policy) restrict downloaded code to interpreted code that doesn't change the app's primary purpose. Compliance is the developer's responsibility. - **Desktop** apps update by installing a new signed build (`desktop-installer`). Stacklift delivers and verifies it; your app runs it. OS code signing/notarization is yours, installers can't be rolled back, there are no delta updates, and store builds must update through their store. See [Desktop apps](https://stacklift.joynul.com/docs/desktop.md). - **Expo, Capacitor, NativeScript** can change their JS/web layer over the air within store rules; the on-device loader that applies it is **not shipped** (partial). - **Kotlin Multiplatform and Tauri** SDKs are untested source (no Kotlin/Rust toolchain in CI). See [SDKs](https://stacklift.joynul.com/docs/sdk.md). - **Flutter** Dart OTA is **planned**: it needs a patched engine and a patch toolchain Stacklift doesn't ship. - **React Native** JS-bundle OTA is **partial**: control plane, signing, rollout and delivery work; the on-device bundle loader isn't shipped yet. - **Web and backend** stacks use deployments: Stacklift versions, signs and serves artifacts, and repoints a channel. Hosting is yours. --- # Server-driven UI Change what a screen looks like (its text, order, sections, tables, lists, buttons) without a store release. Your app ships the building blocks once; Stacklift sends a layout that arranges them. The layout is data, not code, so it works for native SwiftUI, Jetpack Compose, Flutter and React Native apps without breaking App Store or Google Play rules. What you can change over the air: - Text and titles, including values from your data (`"Hi {{user.name}}"`) - The order of sections and components - Lists and tables: which data they show, their columns, how each row looks - Show or hide anything with a condition (`"visible": "{{user.isPro}}"`) - Buttons: their label, style and what they do (open a screen, open a link, or send an event your code handles) - Your own components (`ProductCard`, ...), placed and configured by the layout What still needs a store release: a brand-new kind of component, a new native capability (camera, a new permission, a new SDK), or new logic (use [scripts](https://stacklift.joynul.com/docs/ota-layers.md) for rules). After that one release, the new piece can be arranged over the air like everything else. ## How it works 1. You wrap a screen once and keep your current screen as the fallback. 2. A layout ships inside the app, so the first launch and offline launches look right. 3. You publish a new layout with the CLI. The server validates it before signing it. 4. The app downloads it in the background, verifies the signature, and applies it **the next time it opens** (never mid-session). 5. If a launch with the new layout never reaches `confirmLaunch()` twice in a row, the app rolls back to the last good layout. A layout the installed app cannot draw (for example one using a component from a newer format) is never applied. ```bash stacklift ui validate home.json # the same checks the server runs stacklift release create --version 1.1.0 --runtime-version 1 --artifact ios:ui-layout:./home.json --channel production ``` A release can carry a layout and a script for the same platform; each SDK asks for its own kind. ## The dashboard editor Open a project and choose **Screens** (shown for stacks that support server-driven UI). The editor opens the layout a channel serves now, or the newest one you published. - **Outline**: the screen's components as a tree. Drag to reorder or to move something into a column, row, section or card. ⌥↑/⌥↓ move, ⌘D duplicates, ⌫ deletes, ⌘Z/⇧⌘Z undo and redo. - **Preview**: the screen in a phone frame, light or dark, drawn with the same resolver as the apps. Click anything to select it. Buttons show what they would do. The app's own fonts, colours and custom components appear only on a device. - **Properties**: a form for the selected component (text, style, list binding, table columns, button action, visibility). With nothing selected: the screen's title and ID. - **Sample data**: example values for the preview. *Fill in missing values* creates them from the bindings the screen uses. Sample data is never published. - **JSON**: the whole document as text, for anything the forms do not cover. - **Checks**: the same validation the server runs before signing. Publishing is disabled while there are errors; click an issue to jump to the component. **Publish** creates a release with the layout for the platforms you choose. The server validates and signs it like any artifact, and nothing reaches apps until you deploy the release to a channel. Unpublished edits are kept in your browser (only there) until you publish or discard them. **JSON** downloads the document and **Export code** ejects the current screen to SwiftUI or Flutter source, the same output as `stacklift ui export`. The editor uses only the public endpoints (`GET /projects/:project/layouts` and `GET /projects/:project/layouts/:artifact`) and the normal release API. ## The layout format (stacklift-ui/1) ```json { "format": "stacklift-ui/1", "screens": { "home": { "body": { "type": "column", "children": [ { "type": "text", "text": "Hi {{user.name}}", "style": "title" }, { "type": "list", "items": "{{products}}", "item": { "type": "card", "children": [{ "type": "text", "text": "{{item.name}}: ${{item.price}}" }] } }, { "type": "button", "title": "Upgrade", "action": { "type": "navigate", "to": "/upgrade" } } ] } } } } ``` Components: `column`, `row`, `section`, `card`, `text`, `image`, `button`, `list`, `table`, `divider`, `spacer`, `custom`. Bindings are `{{path.to.value}}`; a string that is exactly one binding keeps its type (a list, a number), anywhere else it becomes text. Inside a list, `item` and `index` are available. Limits: 32 levels deep, 2000 components, 500 list items, 512 KB. The format is open and documented: the JSON Schema is in [`packages/ui-schema/schema/stacklift-ui-1.schema.json`](https://github.com/Joynul-Abedin/stacklift/blob/main/packages/ui-schema/schema/stacklift-ui-1.schema.json) and the reference resolver is in `packages/ui-schema`. The TypeScript, Swift and Dart resolvers are all checked against the same fixtures, so a layout looks the same everywhere. ## SwiftUI ```swift import Stacklift let layouts = StackliftLayouts(client: client, options: .init(runtimeVersion: "1", currentVersion: appVersion), bundled: bundledLayoutData) layouts.prepareLaunch() // early in launch StackliftScreen("home", layouts: layouts, data: try JSONValue.from(model), components: ["ProductCard": { props in AnyView(ProductCard(props)) }], onAction: { action in router.handle(action) }) { HomeView() // your current screen: shown whenever the layout cannot be drawn } layouts.confirmLaunch() // once the app is healthy Task { _ = try? await layouts.stage(); await layouts.flushEvents() } // background: download for the next launch ``` ## Flutter ```dart import 'package:stacklift_flutter_ui/stacklift_flutter_ui.dart'; final layouts = StackliftLayouts(client: client, directory: dir, runtimeVersion: '1', deviceId: deviceId, platform: currentStackliftPlatform(), bundled: await rootBundle.loadString('assets/home-layout.json')); layouts.prepareLaunch(); StackliftScreen( screen: 'home', layouts: layouts, data: {'user': user.toJson(), 'products': [for (final p in products) p.toJson()]}, components: {'ProductCard': (props) => ProductCard.fromJson(props)}, onAction: (action) => router.handle(action), fallback: (context) => const HomeScreen(), // your current screen ); ``` `packages/sdk-dart` holds the format, verification and lifecycle (plain Dart); `packages/sdk-flutter-ui` holds the Flutter widget. The Flutter renderer is the same code on Android: `examples/flutter-scripts` was verified on an Android 17 emulator too (see its README for two Android build settings). ## Jetpack Compose (Android) ```kotlin import dev.stacklift.android.* val layouts = StackliftLayouts(client, StackliftAndroid.options(context, "layouts", runtimeVersion = "1"), bundled = assets.open("home-layout.json").use { it.readBytes().toString(Charsets.UTF_8) }) layouts.prepareLaunch() // early in launch setContent { StackliftScreen("home", layouts, data = mapOf("user" to mapOf("name" to user.name)), components = mapOf("ProductCard" to { props -> ProductCard(props) }), onAction = { action -> router.handle(action) }) { HomeScreen() // your current screen } } layouts.confirmLaunch() // once the app is healthy lifecycleScope.launch { layouts.stage(); layouts.flushEvents() } // background: download for the next launch ``` `packages/sdk-android` draws with Material 3 and your `MaterialTheme`. Text styles map to Material type (largeTitle → headlineLarge, title → headlineMedium, headline → titleMedium, body → bodyLarge, caption → bodySmall); colours map to the colour scheme (accent → primary, secondary → onSurfaceVariant, danger → error). Rows follow the same rule as SwiftUI and Flutter: with a flexible spacer, what follows it sits at the trailing edge. `StackliftLayouts.offline(bundled)` and `use(json)` work without Stacklift, as on the other platforms. See [the SDK README](https://github.com/Joynul-Abedin/stacklift/tree/main/packages/sdk-android) for requirements: signature checks need Android 13 (API 33) or a registered Ed25519 provider. ## Home Screen widgets (WidgetKit) **Not built yet.** `StackliftScreen` is made for app screens; widgets need their own renderer. This section says what will and will not be possible, so you can plan for it. Possible over the air once the widget renderer exists: - **Edit a widget's design**: its text, order, which information shows, sizes and colours from your palette. - **Remove a design.** Widgets already placed on someone's Home Screen fall back to a design built into the app. - **Add a new design built from pieces the app already has** (text, rows, your own custom views). If the app has one widget whose "Widget Type" is chosen in Edit Widget, that list can come from downloaded data, so a new design appears as a new choice without a store release. Still needs a store release: - A new entry in the Add Widget gallery, a new size family or a new configuration screen. Apple compiles these into the widget extension. - Data the widget does not read today (a new permission or API). A layout only shows data the app already provides. - New widget buttons. Interactive widgets run App Intents compiled into the app; a layout can place existing ones, not create new ones. - A visual element the app does not have yet. Ship the view once, and layouts can use it from then on. How it will work: the app downloads and verifies the layout, saves it in the App Group shared with the widget extension, and asks WidgetKit to reload. The widget never goes online itself. A new design therefore shows after the app next opens or gets background time, not instantly. The renderer has to draw a static snapshot: no scrolling, no images loaded from the web, buttons only as App Intents, and the Lock Screen and StandBy rendering modes. ## Troubleshooting - **Publish is disabled in the editor.** Checks found an error. Click it in the Checks list to jump to the component. - **The app still shows the old screen.** Layouts apply on the next launch: open the app once (it downloads), close it, open it again. Also check the release is deployed to the channel the app uses, with the app's runtime version, and that the app asks for `kind: ui-layout` (the SDK's `StackliftLayouts` does). - **The app shows the fallback screen.** The layout uses something the installed app cannot draw (a component from a newer format, or a `custom` component the app did not register), or the screen ID does not match the one the app asks for. The SDK's `onError` callback says which. - **The app went back to an older layout.** Two launches with the new layout never reached `confirmLaunch()`, so the SDK rolled back and will not retry that release. Fix the cause and publish a new version. - **The preview looks a little different from the device.** The preview uses the same layout rules but the browser's drawing; your app's fonts, colours and custom components appear only on a device. - **Android: update checks time out against a local server.** Apps that target Android 17 (API 37) cannot reach private addresses such as the emulator's `10.0.2.2` without the `ACCESS_LOCAL_NETWORK` permission. Use `adb reverse tcp:4100 tcp:4100` and `http://localhost:4100` while developing; a production server on the internet is not affected. - **Upload failed with "Size mismatch: declared …, stored 0".** Fixed in the API: the upload receiver no longer parses request bodies. Update your Stacklift server. ## React Native ```tsx import { StackliftScreen } from '@stacklift/react-native'; }} onAction={(a) => router.handle(a)} fallback={} /> ``` The React Native renderer uses the reference resolver itself (`@stacklift/ui-schema`), so it cannot drift from the other platforms. The layout is delivered and applied on the next launch by the same native code that handles code push (see [OTA for every stack](https://stacklift.joynul.com/docs/ota-layers.md)), and `Stacklift.confirmLaunch()` confirms both. Default colours follow iOS system colours and the phone's light or dark mode; pass `colorScheme="light"` if your app is light-only, `theme` to use your own colours, and `images` for images that ship in the app. React Native apps can also change any JavaScript with code push, so use layouts for what non-developers should change from the dashboard editor, and code push for everything else. ## Leaving Stacklift (no lock-in) - **Your app keeps working.** Every screen has your own fallback, and the layout bundled in the app renders without any server. If Stacklift is unreachable, removed, or the account is closed, nothing breaks. - **Host layouts anywhere.** `StackliftLayouts(bundled:)` (Swift) or `StackliftLayouts.offline()` (Dart) plus `use(...)` renders a layout you fetch from your own server or CDN. `StackliftScreen` also takes a plain `document`. - **Eject to code.** Turn any screen into ordinary SwiftUI or Flutter source with no Stacklift dependency: ```bash stacklift ui export home.json --screen home --to swiftui -o HomeScreen.swift stacklift ui export home.json --screen home --to flutter -o home_screen.dart ``` The generated file includes the few helper functions the bindings need. Replace the `data` lookups with your own model properties and remove the SDK. A test renders the ejected Flutter widget next to the live renderer and checks they show exactly the same text. ## Staying within the store rules Apple App Review Guideline 2.5.2 and Google Play policy forbid downloading code that adds or changes functionality. A layout contains no code: it arranges components your reviewed app already has. Use it to change how existing features look and are arranged, not to switch on hidden features after review. ## Status Built and tested: the format, validator and reference resolver; server validation before signing; the CLI (`ui validate`, `ui export`, releases); SwiftUI, Jetpack Compose, Flutter and React Native renderers; next-launch apply, rollback and reporting; eject to SwiftUI and Flutter; the dashboard editor (outline, live preview, properties, sample data, JSON, checks, publish, export). Both demo apps (`examples/swift-scripts`, `examples/flutter-scripts`) changed their home screen over the air on the iOS 26 simulator against a live server. On a Pixel 6 Pro emulator (Android 17), `examples/android-scripts` (Compose) and `examples/flutter-scripts` did the same, and the Compose demo also ran on a physical HONOR ELI-NX9 (Android 16), and the Compose renderer has 6 rendering tests on the emulator plus the 17 shared conformance cases. The editor was checked in a browser: edit, validate, publish, deploy, reopen. Not yet: a widget (WidgetKit) renderer, .NET MAUI and Unity renderers, eject to Compose or React Native code (`ui export` writes SwiftUI or Flutter), and a run on a physical iPhone. Drafts live in one browser, so two people cannot share an unpublished draft. --- # Over-the-air updates for every mobile stack Stacklift can update most of an app without a store release, but not by replacing compiled code. Apple and Google both forbid that for native apps. What they allow is data, and code that runs inside an interpreter the OS provides. Stacklift offers four layers, from safest to most powerful. Use the lowest layer that does the job. | Layer | What changes | Where it works | Status | | --- | --- | --- | --- | | 1. Config, flags, assets | JSON settings, feature flags, images, content packs | Every stack | Built | | 2. Server-driven UI | Screens described as data: text, order, sections, lists, tables, buttons | SwiftUI, Jetpack Compose, Flutter | Built ([guide](https://stacklift.joynul.com/docs/server-driven-ui.md)); React Native, MAUI and Unity renderers not yet | | 3. Scripted logic | Signed JavaScript run in the OS interpreter, called from hooks you write | Native iOS and Android, Flutter, KMP, MAUI, Unity | Server, Swift, Android (Kotlin) and Flutter runtimes built; C# runtime not yet | | 4. Code push | The app's own JavaScript or web code | React Native, Expo, Capacitor, NativeScript | React Native built ([below](#layer-4-code-push-for-react-native)); Expo, Capacitor and NativeScript loaders not yet | | (Flutter code push) | Compiled Dart code | Flutter | Not built. Needs a patched Flutter engine | ## Why compiled code cannot be pushed - **iOS:** the Apple Developer Program License Agreement (3.3.2) only allows downloaded *interpreted* code, and only if it does not change the app's primary purpose, does not create a store for other code, and does not bypass signing or the sandbox. - **Android:** Google Play's Device and Network Abuse policy forbids downloading executable code (dex, JAR, `.so`) from outside Play, except code that runs in a virtual machine or interpreter with only indirect access to Android APIs. Any tool that claims to replace compiled Swift, Kotlin, C# or Dart on a store build is outside those rules, or relies on a patched runtime such as Shorebird's Flutter engine. Stacklift does not do that for native apps. ## Layer 3: scripted logic You write the parts of your app that change often (pricing rules, ranking, validation, feature logic) as small JavaScript functions, and the app calls them through hooks. The script ships through Stacklift like any release: signed, checksummed, rolled out in stages, and rolled back from the dashboard if needed. What the script can do is what the interpreter and your registered functions allow. It has no network, files, timers, modules or native objects. Everything it can reach, you registered explicitly. ### Release it ```bash stacklift release create --version 1.4.1 --runtime-version 1 \ --artifact ios:script-bundle:./rules.js --channel production --deploy ``` A `script-bundle` is a single `.js` file up to 2 MB for `ios` or `android`. Updates only reach apps with the same `--runtime-version`, so bump it when the hooks your app exposes change. ### Use it from Swift A runnable SwiftUI example with a walkthrough is in [`examples/swift-scripts`](https://github.com/Joynul-Abedin/stacklift/tree/main/examples/swift-scripts). ```swift import Stacklift let client = StackliftClient(StackliftOptions(baseURL: deliveryURL, apiKey: publicKey, pinnedPublicKey: pinnedPEM)) let scripts = StackliftScripts(client: client, options: .init(runtimeVersion: "1", currentVersion: appVersion)) scripts.register("flag") { json in /* the only functions the script can call: host.flag(...) */ "true" } // 1. Early in launch: apply a staged script, or roll back one that never confirmed. scripts.prepareLaunch() // 2. Where the app needs the logic. Returns nil when no script is active, so your built-in code is the fallback. let discount: Double = (try? scripts.call("rules.discount", cart)) ?? defaultDiscount(cart) // 3. Once the app is healthy (for example after the first screen appears). scripts.confirmLaunch() // 4. In the background: check, download, verify and stage. It takes effect on the NEXT launch. Task { _ = try? await scripts.stage(); await scripts.flushEvents() } ``` How it behaves: - **Apply on next launch.** A downloaded script is never swapped in mid-session. - **Verified first.** The Ed25519 signature is checked before anything is downloaded, then the size and SHA-256 of the bytes. Pin the project's public key in the app; without it a compromised server could vouch for its own script. - **Syntax-checked before staging.** A script that does not parse is refused and never retried. - **Automatic rollback.** If a launch never reaches `confirmLaunch()` twice in a row (a crash, a hang), the script is discarded and the last confirmed one, or your built-in behaviour, takes over. A script that throws while loading is discarded immediately. A discarded release is never staged again on that device. - **Reported.** Downloads, successful installs and rollbacks are sent to Stacklift, so the dashboard shows adoption and failure rates and can pause a bad rollout. ### Use it from Android (Kotlin) `packages/sdk-android` runs scripts in QuickJS (Android has no interpreter built in) with the same lifecycle and the same `host` bridge: ```kotlin val scripts = StackliftScripts(client, StackliftAndroid.options(context, "scripts", runtimeVersion = "1")) scripts.register("appName") { "\"My App\"" } // scripts call host.appName(); JSON in, JSON out scripts.prepareLaunch() // early in launch val discount = scripts.call("rules.discount", mapOf("total" to cart.total)) as? Number ?: builtInDiscount(cart) scripts.confirmLaunch() // once healthy lifecycleScope.launch { scripts.stage(); scripts.flushEvents() } ``` Memory is capped (32 MB) and every call has a time limit (2 s); a script that hangs is abandoned and rolled back. There is no `setTimeout`, `fetch`, `require` or file access, which tests on the emulator check. ### Use it from Flutter Two packages: `stacklift` (`packages/sdk-dart`, the state machine and verification, no interpreter) and `stacklift_scripts_flutter` (`packages/sdk-flutter-scripts`, the interpreter: JavaScriptCore on iOS and macOS, QuickJS on Android, Windows and Linux, through `flutter_js`). Neither is published yet; add them as path or git dependencies. Android builds: `flutter_js` compiles Kotlin for JVM 1.8 and Java for 11, which Android Gradle Plugin 9 refuses by default. Add `kotlin.jvm.target.validation.mode=warning` to `android/gradle.properties` until the plugin is updated (the code runs fine; verified on an Android 17 emulator). ```dart import 'package:stacklift/stacklift_io.dart'; import 'package:stacklift_scripts_flutter/stacklift_scripts_flutter.dart'; final scripts = StackliftScripts( client: StackliftClient(baseUrl: deliveryUri, apiKey: publicKey, pinnedPublicKey: pinnedPem), engine: const FlutterJsEngine(), directory: Directory('${(await getApplicationSupportDirectory()).path}/stacklift-scripts'), // path_provider runtimeVersion: '1', deviceId: await DeviceId.getOrCreate(myKeyValueStore), platform: currentStackliftPlatform(), currentVersion: appVersion, ); scripts.register('flag', (json) => 'true'); // the only functions a script can call: host.flag(...) scripts.prepareLaunch(); // early in main(): apply a staged script or roll one back final discount = scripts.call('rules.discount', cart) ?? defaultDiscount(cart); // null: use your built-in Dart code WidgetsBinding.instance.addPostFrameCallback((_) => scripts.confirmLaunch()); // the first frame drew: this launch is healthy unawaited(scripts.stage().then((_) => scripts.flushEvents())); // background: stage for the next launch ``` A runnable example with a walkthrough is in [`examples/flutter-scripts`](https://github.com/Joynul-Abedin/stacklift/tree/main/examples/flutter-scripts). Behaviour is identical to the Swift runtime: verified before anything is downloaded, syntax-checked, applied only on the next launch, rolled back after two launches that never confirm, and reported to the dashboard. Calls are synchronous, so scripts must be synchronous too: promises and timers are not available (`setTimeout` and friends are removed from the sandbox). What the Flutter adapter removes from the interpreter, because a script must not reach it: `setTimeout`, `setInterval`, `fetch`, `XMLHttpRequest`, `require`, `process`, `WebAssembly`, the raw `sendMessage` bridge and the package's internal helpers. A test runs a real interpreter and checks each one is `undefined`. ### Rules for staying within the stores' policies You are responsible for compliance. In practice: - Scripts may change *how a feature you already shipped behaves*, not add features or change the app's purpose. - Do not register a host function that gives a script raw platform access (reflection, file system, arbitrary network, running other code). - Do not use scripts to build a store or runtime for third-party code. - Describe it truthfully in your App Review notes if asked. ### Limits you should know about - **Hooks first.** Only logic that sits behind a hook can change. Everything else needs a store release. - **No time limit on iOS.** JavaScriptCore cannot interrupt a script that loops forever, so keep scripts small and call them off the main thread. A hang counts as an unconfirmed launch and rolls back, but the user still sees the hang once. On Android each call has a time limit (2 s by default): a script that exceeds it is abandoned and rolled back at once. - **Swift, Android and Flutter.** The runtime exists for Swift (`packages/sdk-swift`), native Android (`packages/sdk-android`: 14 JVM tests plus 9 tests with real QuickJS on an emulator) and Flutter (`packages/sdk-dart`, plus 14 tests with the real interpreter in `packages/sdk-flutter-scripts`). The C# runtime (MAUI, Unity) is not built; the server side and signing already work for it. - **Tested in real apps on simulators, an emulator and one physical Android phone.** On a physical HONOR ELI-NX9 (Android 16), `examples/android-scripts` downloaded a script and a layout, applied them on the next launch and rolled back a script that never confirmed, and the 15 SDK device tests (real QuickJS and Compose) pass. On a Pixel 6 Pro emulator (Android 17), `examples/android-scripts` (Compose) and `examples/flutter-scripts` downloaded a script and a layout from one release and applied them on the next launch, and the native app rolled back a script that never confirmed after two launches (the server counted 1 download and 1 failure). On iOS: `examples/flutter-scripts` (Flutter) and `examples/swift-scripts` (SwiftUI, Swift 6) each ran as a debug build on the iOS simulator against a live Stacklift server: download, apply on next launch, upgrade, automatic rollback after two unconfirmed launches, and a bad release never re-staged. The Swift app also checked its saved state at every launch (active, pending, last good, bad releases) and the server's counts (3 downloads, 2 installs, 1 failure). A physical iPhone and release builds have not been run. - **Script syntax check.** Flutter checks syntax by parsing the script as a function body (so nothing runs). A script that is only valid as a top-level script, for example one with a top-level `return`, would parse differently; it fails at load and is discarded. ## Layer 4: code push for React Native React Native apps run JavaScript, so the whole app's JavaScript can change over the air, not only logic behind hooks. `@stacklift/react-native` (`packages/sdk-react-native`) does it with the same launch-safe rules as scripts and layouts: 1. A `js-bundle` release (a zip with the bundle at the top and its assets next to it) is downloaded and verified in the background, then unpacked into its own folder. 2. On the **next launch**, the native side hands React Native the new bundle instead of the one built into the app: `bundleURL()` on iOS, `jsBundleFilePath` on Android. Nothing changes mid-session. 3. JavaScript calls `Stacklift.confirmLaunch()` once the first screen is up. That bundle becomes the last good one. 4. If something fails before that, the bundle is discarded, never downloaded again, and the app restarts straight into the last good bundle: - `StackliftErrorBoundary` catches errors while rendering (React Native does not pass those to its global error handler). - `Stacklift.installCrashGuard()` catches other fatal JavaScript errors. - The decision is saved synchronously, before anything else can go wrong. - The restart reloads JavaScript on iOS and starts a new process on Android (where the bundle file is fixed when React Native starts). It waits until React has finished its current work, because reloading mid-commit crashes React Native's renderer. - If even that fails (a native crash, or the app killed), two launches that never confirm roll back automatically. ```bash npx react-native bundle --platform ios --dev false --entry-file index.js --bundle-output dist/ios/main.jsbundle --assets-dest dist/ios (cd dist/ios && zip -qr ../ios.zip .) stacklift release create --version 1.0.1 --runtime-version 1 --artifact ios:js-bundle:dist/ios.zip --channel production ``` See the [package README](https://github.com/Joynul-Abedin/stacklift/tree/main/packages/sdk-react-native) for setup: two native lines, Info.plist or AndroidManifest keys, and the Podfile line. **Verified on the iOS simulator and an Android 17 emulator** (`examples/react-native-demo`, React Native 0.88.1 with the new architecture and Hermes, release builds, against a live server): - A release carrying a new bundle and a new layout was downloaded, and the next launch ran the new JavaScript and drew the new screen, on both platforms. - A bundle that crashed while rendering was discarded on its first failure, and the app restarted itself on the last good bundle without crashing, on both platforms. That release is never downloaded again. - Without the error boundary, the two-unconfirmed-launches rule rolled a crashing bundle back on its own (after two crashes). - The server counted every outcome: each good release installed, each crashing release 1 download and 1 failure. - With code shrinking (R8) on, on the Android emulator: the same update and the same crash recovery worked, and so did scripts in the native Android demo (a script that throws on load was rolled back). No keep rules beyond the SDK's own were needed. Shrunk builds have not been run on a phone. - On a physical HONOR ELI-NX9 phone (Android 16), the same release build was updated over the air (including a fix for a dark-mode bug that only showed on the phone, shipped as a code push update), recovered from a crashing bundle by restarting itself, and the server counted each outcome. A physical iPhone has not been run. **Store rules:** both stores allow this for interpreted JavaScript that does not change the app's purpose. Native code, native modules, permissions and React Native upgrades still need a store release and a new runtime version. ## What to build next 1. A C# runtime and renderer for MAUI and Unity. (The Kotlin runtime and Compose renderer for Android are built.) 2. Layer 4 loaders for Expo and Capacitor (React Native is built). Expo's update protocol is open, so Stacklift can act as an Expo update server with no custom client. 3. Eject to Compose and React Native code (`ui export` writes SwiftUI or Flutter today). 4. Flutter code push, only if Shorebird agrees in writing or Stacklift builds its own engine. --- # Store releases (App Store, Google Play and friends) When your app ships through a store, **the store hosts the binary** — Stacklift doesn't, and you don't upload anything to Stacklift. The CLI records the build; you submit it to the store with whatever you already use. ## The flow ```bash # 1. Build as usual flutter build appbundle && flutter build ipa # 2. Record the build in Stacklift. Version, build number and app id are read from the built files. stacklift release create \ --native android:build/app/outputs/bundle/release/app-release.aab \ --native ios:build/ios/ipa/Runner.ipa # 3. Upload to Google Play / App Store Connect with your usual tool (Fastlane, Xcode, Play Console …) # 4. Tell Stacklift where it is. Optional, but it's what the dashboard shows. stacklift store status 1.4.2 ios in-review stacklift store status 1.4.2 ios released ``` Nothing is uploaded in step 2: the CLI hashes the file locally and sends the name, size, checksum, version, build number, git commit and CI link. The release is `READY` immediately. ## What is read from the built binary For an `.ipa` or `.aab` the CLI opens the finished file and reads the numbers the store will actually see: `Info.plist` inside the IPA (binary or XML), and the compiled `AndroidManifest.xml` inside the AAB (`package`, `versionName`, `versionCode`). Only that one small entry is read — never the whole archive — and nothing in it is executed. This wins over the project files, because the project can change between the build and the release. If the two disagree you get a warning ("The built binary is 1.4.2 but the project files say 9.9.9"); if `--version` contradicts the binary you are told the store will show the binary's version. If both an IPA and an AAB are given and their versions differ, you get a warning and the most common one is used. Build numbers stay per platform. `.apk` and other formats (MSIX, DMG, EXE …) are not opened; for those the project files below are used. ## What is read from your project When there is no readable binary (or for hosted artifacts), the CLI reads the version from the files your build already uses, and says where each came from: | Stack | Version / build number | App id | | --- | --- | --- | | Flutter | `pubspec.yaml` (`version: 1.4.2+37`) | `applicationId` in Gradle, `PRODUCT_BUNDLE_IDENTIFIER` in Xcode | | React Native, Capacitor, NativeScript, KMP | Native files win: Gradle `versionName`/`versionCode`, Xcode `MARKETING_VERSION`/`CURRENT_PROJECT_VERSION`; `package.json` is the fallback | same | | Native Android / iOS / macOS | Gradle / Xcode project | same | | Expo | `app.json` (`expo.version`, `ios.buildNumber`, `android.versionCode`) | `bundleIdentifier`, `package` | | .NET MAUI / WPF / WinUI | `.csproj` (`ApplicationDisplayVersion`, `ApplicationVersion`), `Package.appxmanifest` | `ApplicationId`, MSIX identity | | Unity | `ProjectSettings.asset` | per-platform identifier | | Electron / Tauri / Compose Desktop | `package.json` / `tauri.conf.json` / `packageVersion` | `build.appId` / `identifier` | Only **literal** values are used. A Gradle property or an Xcode `$(MARKETING_VERSION)` is a build-time indirection, so it's reported ("not a literal, so it was not read") instead of guessed. If your iOS and Android versions disagree, you get a warning and the most common one is used; pass `--version` to choose. Build numbers stay per platform, so a Play `versionCode` of 30 and an App Store build of 31 are both kept. Override anything with `--version`, `--build-number` or `--runtime-version`. For a store-only release `runtimeVersion` defaults to the version, since nothing is delivered to a runtime. ## Store links Set them once; they show on the project and on every release. ```bash stacklift store link ios https://apps.apple.com/us/app/glyph/id6740000000 ``` or in `stacklift.yaml` (synced on `release create`, best effort: a CI token without `project:update` just skips it): ```yaml stores: ios: https://apps.apple.com/us/app/glyph/id6740000000 android: https://play.google.com/store/apps/details?id=com.shokal.glyphwidget ``` The **Google Play** link is derived from your package name when you don't set one, and is shown as *derived*: it's where the listing will live, not proof it exists yet. The **App Store** link can't be derived (it needs Apple's numeric id), so add it once. Links must be `https` and on the store's own host (`apps.apple.com`, `play.google.com`, `apps.microsoft.com`, …). Anything else — `javascript:`, `http:`, look-alike hosts, URLs with credentials — is rejected, because these render as hyperlinks. ## Store status `built → submitted → in_review → released` (or `rejected`, `removed`). Stacklift has **no access to the stores**, so this is what you tell it, with `stacklift store status`, the dashboard's selector, or `--store-status` on `release create`. `release create` sets `built` for you and never overwrites a status someone already recorded. ## Devices and installs If your app embeds a Stacklift SDK and calls `check` with its `currentVersion`, Stacklift knows which devices run which build — whatever delivered it: ```swift let manifest = try await client.check(CheckRequest(channel: "production", runtimeVersion: "1.4.2", currentVersion: "1.4.2", deviceId: DeviceIdentity.getOrCreate())) // no OTA deployed? you get { updateAvailable: false, reason: "nothing_deployed" } and the check-in is still counted ``` The release page then shows **active devices on this version in the last 30 days**, per platform: a device counts toward the newest version it last reported, so it leaves the old release's count when it updates. Device ids are random, per install and hashed with the project id; Stacklift keeps no hardware or advertising ids. ## What Stacklift can't do - **Upload to the stores.** Use Fastlane, Xcode, `bundletool`, the Play Console API. - **See store download counts, ratings or review state.** Those need the App Store Connect and Google Play Developer APIs. Integrations for them are **planned, not built**. Until then "downloads" means OTA downloads, and "devices" means devices that checked in through the SDK — a fraction of your store installs if the SDK isn't in every build. - **Verify the store build.** The checksum is whatever your CLI declared; Stacklift never sees the bytes, and labels it that way. - **Deploy a store build to a channel.** Store builds are never delivered to devices, so a release made only of them can't be deployed (the CLI skips `--channel`, the API refuses with an explanation). ## Mixed releases A React Native, Expo or Capacitor release can carry an OTA bundle *and* its store build. The bundle is hosted, verified, signed and deployable; the store build is recorded: ```bash stacklift release create --runtime-version 2.3.0 \ --artifact ios:js-bundle:dist/ios.zip --artifact android:js-bundle:dist/android.zip \ --native ios:build/App.ipa --native android:build/app-release.aab \ --channel staging ``` ## In CI ```yaml - run: flutter build appbundle && flutter build ipa - run: | stacklift release create \ --native android:build/app/outputs/bundle/release/app-release.aab \ --native ios:build/ios/ipa/Runner.ipa env: { STACKLIFT_TOKEN: ${{ secrets.STACKLIFT_TOKEN }} } ``` On GitHub Actions, GitLab CI, CircleCI and Bitrise the release links back to its pipeline run. Only those well-known variables are read — never the rest of the environment. --- # Desktop apps Desktop apps (Electron, Tauri, Flutter desktop, .NET, Qt, JVM, native macOS, Kotlin/Compose Desktop, Unity players …) update differently from mobile apps, and Stacklift models that instead of pretending they're the same. ## How a desktop update works 1. You build a **signed installer** per OS and upload it as a `desktop-installer` artifact. 2. Stacklift verifies the bytes server-side, signs them with the project's Ed25519 key, and serves them to devices on a channel — optionally as a [staged rollout](https://stacklift.joynul.com/docs/concepts.md) with the usual pause and cancel controls. 3. The app's SDK **checks, downloads and verifies** the installer (signature → size → SHA-256). 4. **Your app runs the installer** and relaunches. Stacklift can't do that for you. Unlike mobile `native-binary` records — which are tracked and *never* delivered — `desktop-installer` artifacts are delivered, because for desktop software the OS-level installer is the update mechanism. ```bash stacklift release create --version 3.1.0 \ --artifact windows:desktop-installer:dist/Acme-Setup-3.1.0.msi \ --artifact macos:desktop-installer:dist/Acme-3.1.0.dmg \ --artifact linux:desktop-installer:dist/Acme-3.1.0.AppImage \ --channel staging ``` Installer extensions must match the platform: `.exe` / `.msi` / `.msix` are Windows, `.dmg` / `.pkg` are macOS, `.AppImage` / `.deb` / `.rpm` are Linux; `.zip` and `.tar.gz` fit any. Uploading a `.dmg` as a Windows build is rejected before anything is stored. ## What Stacklift does not do - **No OS code signing or notarization.** Stacklift's Ed25519 signature is independent of Authenticode and Apple's Developer ID + notarization. Unsigned installers trigger SmartScreen / Gatekeeper warnings or are blocked. That's your build pipeline's job. - **No rollback.** Most OS installers refuse downgrades, so `desktop-installer` is never rollbackable through Stacklift. Fix forward with a higher version. (Config and asset bundles can still be rolled back.) - **No delta or silent in-place patching.** Every update is a full installer. - **No store updates.** Builds from the Mac App Store or Microsoft Store must update through that store. Track them with `native-binary` records if you want visibility. - **No hot-swapping app code.** Electron `app.asar` / Tauri frontend swaps are *planned*, not implemented — they interact with ASAR integrity fuses and macOS code-signature validity. ## Choosing an SDK | Stack | Use | Status | | --- | --- | --- | | Electron | `@stacklift/sdk-electron` | Tested with fakes for Electron's APIs; not run inside a real Electron app | | Flutter desktop | `stacklift` (Dart) | Tested on the Dart VM | | .NET WPF / WinForms / WinUI / MAUI | `Stacklift.Sdk` | Tested on .NET 10 | | JavaFX / Compose Desktop / Swing / KMP `jvmMain` | Java SDK | Tested on JDK 21 | | macOS (Swift / AppKit) | Swift package | Tested with `swift test` on macOS | | Tauri | `@stacklift/sdk-js` from the frontend, or `packages/sdk-tauri` | Rust crate **untested** | | Qt / C++, GTK, Win32, Go, Rust | none — implement the [contract](https://stacklift.joynul.com/docs/sdk.md#the-contract) | — | See [SDKs](https://stacklift.joynul.com/docs/sdk.md) for usage and the shared [conformance vectors](https://stacklift.joynul.com/docs/sdk.md#conformance). ## Verification flow in the app ``` check(channel, platform=windows, runtimeVersion=3.0.0) └─ manifest (kind=desktop-installer, sha256, size, signature, filename) verify signature ── fails → key_mismatch / signature_invalid, nothing is downloaded download → .part, hashing as it streams, aborting if it exceeds the signed size size ✓ sha256 ✓ → rename to .msi ── any failure deletes the .part file (your app) open installer, quit, relaunch (new version, first launch) report INSTALL_SUCCESS ── the real success signal ``` The installer's file name arrives from the server **unsigned**. SDKs that write it to disk reduce it to a base name and allow only installer extensions for the OS; do the same if you write your own client. ## Runtime version for desktop `runtimeVersion` is the compatibility line of the installed app. For a desktop app that always ships a complete installer, simply keep it equal to the major version (or any value you only change on a breaking change). A device only receives releases whose `runtimeVersion` equals its own, so bump it when you want to stop offering a new installer to older lines. ## Cross-platform stacks Flutter, Kotlin Multiplatform, .NET MAUI and Unity are listed under **Mobile** and again under **Desktop** in the project wizard because one project can target both: mobile builds are tracked as native releases, desktop builds are delivered as installers. Pick the platforms per release. --- # CI/CD CI authenticates with a **project secret key** (`slk_…`). It is confined to one project and to the scopes you give it (`releases:read`, `releases:write`, `artifacts:write`, `deployments:write`, `channels:read`). It cannot manage members, keys, rollouts or rollbacks. Create one under **API Keys**, store it as a CI secret named `STACKLIFT_TOKEN`, and set `STACKLIFT_API_URL`. > First-party GitHub Action / GitLab component are **planned**. Today every CI system runs the CLI. ## GitHub Actions ```yaml name: release on: push: tags: ['v*'] jobs: stacklift: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: { node-version: 22 } - run: npm ci && npm run bundle - run: npm install -g stacklift - run: stacklift release create --version "${GITHUB_REF_NAME#v}" --resume --channel staging env: STACKLIFT_TOKEN: ${{ secrets.STACKLIFT_TOKEN }} STACKLIFT_API_URL: ${{ vars.STACKLIFT_API_URL }} ``` `--resume` makes reruns safe. Deployments carry an idempotency key, so retrying a job never deploys twice. ## GitLab CI ```yaml stacklift: image: node:22 rules: [{ if: '$CI_COMMIT_TAG' }] script: - npm ci && npm run bundle - npm install -g stacklift - stacklift release create --version "${CI_COMMIT_TAG#v}" --resume --channel staging ``` ## Jenkins ```groovy withCredentials([string(credentialsId: 'stacklift-token', variable: 'STACKLIFT_TOKEN')]) { sh 'stacklift release create --version $VERSION --resume --channel staging' } ``` ## Docker ```bash docker run --rm -e STACKLIFT_TOKEN -e STACKLIFT_API_URL -v "$PWD:/app" -w /app node:22 \ sh -c "npm i -g stacklift && stacklift release create --version 1.4.0 --resume" ``` For backend stacks use the `container-image-ref` artifact kind to record an image digest. Stacklift tracks the reference; it doesn't run your containers. ## Branch / tag triggers Automatic releases from GitHub, GitLab or Bitbucket pushes are **planned** (they need a GitHub App / OAuth app and webhook ingestion). Trigger the CLI from your own pipeline in the meantime. ## Desktop installers Build, sign and (on macOS) notarize the installers in CI first; Stacklift's own signature is separate from OS code signing. Then upload one installer per OS, ideally from the matching runner, into the same release: ```bash stacklift release create --version "$VERSION" --runtime-version 3.0.0 \ --artifact windows:desktop-installer:dist/App-Setup.msi \ --artifact macos:desktop-installer:dist/App.dmg \ --artifact linux:desktop-installer:dist/App.AppImage \ --channel staging ``` A release can only be deployed once **all** the platforms it declares have verified artifacts. Rollbacks of installers are refused; ship a fixed higher version instead. See [Desktop apps](https://stacklift.joynul.com/docs/desktop.md). --- # Webhooks Stacklift sends signed HTTP `POST` requests when things happen. Create endpoints under **Integrations → Webhooks**; the signing secret (`whsec_…`) is shown once. ## Events `release.created`, `release.ready`, `release.failed`, `deployment.succeeded`, `deployment.failed`, `rollout.updated`, `rollback.created`, plus `ping` for tests. ```json { "id": "5a1f…", "event": "deployment.succeeded", "orgId": "…", "projectId": "…", "createdAt": "2026-11-17T10:21:04.000Z", "data": { "deploymentId": "…", "releaseId": "…", "channelId": "…" } } ``` ## Verifying a delivery Headers: `Stacklift-Event`, `Stacklift-Delivery`, `Stacklift-Signature: t=,v1=`. The signature is `HMAC-SHA256(secret, ".")`. Compare in constant time and reject timestamps older than five minutes. ```ts import { createHmac, timingSafeEqual } from 'node:crypto'; export function verify(rawBody: string, header: string, secret: string) { const [t, v1] = header.split(',').map((p) => p.split('=')[1]!); if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'); return timingSafeEqual(Buffer.from(v1), Buffer.from(expected)); } ``` ## Delivery semantics - Delivered at least once; use `Stacklift-Delivery` to de-duplicate. - Non-2xx responses and timeouts (10 s) are retried with exponential backoff, up to 5 attempts. Every attempt appears in the delivery log. - Redirects are not followed. - In production, targets must be `https` and must not resolve to loopback, private or link-local addresses (SSRF guard, re-checked at delivery time). Slack and Discord notifications are **planned**. Until then, point a webhook at a relay (for example a Slack incoming-webhook adapter you host). --- # Architecture ## Shape ```text apps/ web/ Next.js (App Router) dashboard, marketing site, docs portal api/ NestJS: control plane (REST + SSE) and delivery plane (SDK-facing) cli/ `stacklift` command line packages/ shared/ zod schemas, roles/permissions, release state machine, constants database/ Prisma schema, migrations, dev seed adapters/ stack adapter registry + one adapter per ecosystem sdk-core/ Node update client, cohort bucketing, checksum + Ed25519 helpers sdk-js/ sdk-electron/ sdk-swift/ sdk-dart/ sdk-dotnet/ sdk-java/ client SDKs (tested) sdk-react-native/ React Native: code push (native bundle loader on the Swift and Android SDKs), StackliftScreen renderer sdk-android/ Android SDK: Compose renderer, QuickJS scripts, update lifecycle (Gradle; includes sdk-java from source) sdk-kotlin/ sdk-tauri/ client SDKs (untested source) sdk-conformance/ language-neutral signature test vectors every SDK must pass ui-schema/ the open stacklift-ui/1 layout format: JSON Schema, validator, reference resolver, code export, shared fixtures sdk-flutter-scripts/ sdk-flutter-ui/ Flutter packages: JavaScript runtime for scripts, StackliftScreen widget infrastructure/docker/ Postgres, Redis, MinIO (S3) for local development docs/ this documentation (also rendered by the web docs portal) ``` The frontend, API, CLI and SDK share only `packages/*` — there are no imports between apps, and no business logic lives in React components (they render API state and send intents). ## Control plane vs delivery plane | | Control plane | Delivery plane | | --- | --- | --- | | Path | `/api/v1/*` (port 4000) | `/v1/*` (port 4100) | | Callers | Dashboard, CLI, CI | Apps in the field (SDK) | | Auth | User JWT, `slp_` token, `slk_` secret key | `slk_` **public** key | | Writes | Projects, releases, deployments, rollouts… | Telemetry events only | | Scaling | Modest, stateful operations | Read-mostly, stateless, scale out freely | They are two Nest applications built from the same codebase. `PLANE=control|delivery|all` picks which to start, so production can run them as separate deployments. Artifact bytes never flow through either: uploads and downloads use presigned URLs against S3-compatible storage (the `local` driver exists for development only). Object keys are tenant-prefixed and content-addressed (`artifacts/////`), so they are immutable and CDN-cacheable. ## Request pipeline (control plane) `ThrottlerGuard → AuthGuard → AccessGuard → zod pipe → controller → service → Prisma` - **AuthGuard** accepts a JWT, a personal access token, or a project secret key (a machine principal). - **AccessGuard** resolves `:org` (and `:project` *inside* that org), checks membership and the `@Require(permission)`; for machine principals it maps scopes to permissions and confines them to one project. - Controllers are thin. Services own the logic; `@stacklift/shared` owns the rules (permissions, state machine) so API, CLI and UI can't disagree. ## Data model (Prisma / PostgreSQL) Identity: `User`, `OAuthAccount`, `RefreshToken`, `VerificationToken`, `PersonalAccessToken`. Tenancy: `Organization`, `Membership`, `Invitation`, `Workspace`. Delivery domain: `Project` (+ signing key pair), `ProjectMember`, `Environment`, `Channel`, `Release`, `Artifact`, `Deployment`, `Rollout`, `RolloutEvent`, `Rollback`. Credentials & telemetry: `ApiKey`, `UpdateEvent` (append-only), `Integration`, `WebhookDelivery`, `AuditLog`. Principles: - **Tenant isolation:** every org-owned table has `orgId`; the API never queries without it. - **Soft deletion** for users, organizations, projects, releases. History tables (audit log, deployments, rollbacks, events) are never deleted. - **Constraints do real work:** `@@unique([projectId, version])`, `@@unique([releaseId, platform, kind])`, `@@unique([projectId, idempotencyKey])`, `Channel.activeRolloutId @unique` (at most one rollout per channel). - **Indexes** follow the access paths: `(orgId, status)`, `(projectId, occurredAt)`, `(status, nextStepAt)` for the rollout scheduler. - Secrets are stored hashed (`secretHash`) or encrypted (`signingPrivateKeyEnc`, `Integration.secretEnc`). ## The release engine States are defined in `@stacklift/shared` (`RELEASE_TRANSITIONS`) and enforced by `assertTransition` / `syncReleaseStatus`: 1. `requestUpload` creates an artifact row (`PENDING`) and a signed upload URL; release → `UPLOADING`. 2. `complete` checks the object exists, marks it `UPLOADED`, release → `PROCESSING`, enqueues `artifact.process`. 3. `artifact.process` (idempotent job) streams the object, computes real size/SHA-256, compares to the declaration, signs, marks `VERIFIED`. `refreshFromArtifacts` (row-locked) moves the release to `READY` only when every release platform has a verified artifact and nothing is pending — or `FAILED`. 4. `DeploymentsService.request` records a `PENDING` deployment and moves the release to `DEPLOYING`. **It does not touch the channel.** 5. `deployment.execute` (idempotent job) re-validates, then in one transaction (channel + release row locks) either sets `Channel.currentReleaseId` and marks the deployment `SUCCEEDED` (100%), or creates a `Rollout` (<100%). 6. `RolloutsService.act` pauses, resumes, cancels or raises a rollout; reaching 100% completes it with the same switch. A one-minute scheduler evaluates **opt-in** auto-expansion and the failure-rate pause guard. 7. `RollbacksService.create` runs the adapter's compatibility check, then in one transaction cancels any rollout, repoints the channel, records a `ROLLBACK` deployment and the reason. `syncReleaseStatus` derives `ACTIVE` / `DEPLOYING` / `ROLLED_BACK` / `READY` from what channels and rollouts actually say, so a release can never claim to be live when nothing serves it. ## Decisions (ADR summary) | # | Decision | Why | | --- | --- | --- | | 1 | Monorepo with pnpm workspaces; apps share only packages | Independent deployability, single source of truth for rules | | 2 | NestJS modular monolith, two planes from one codebase | Operational simplicity now, split by env var later | | 3 | zod as the contract (validation, OpenAPI bodies, CLI config, forms) | One definition for server, CLI and UI | | 4 | Adapters declare capabilities, restrictions and limitations as data | Product honesty is enforced, not marketing copy | | 5 | Presigned direct-to-storage transfer | Large files never traverse the API; CDN-friendly | | 6 | Server-side checksum + Ed25519 signature bound to release identity | Integrity, and no cross-release replay | | 7 | Rollout cohorts by stable hash | Monotonic, stateless, no per-device storage | | 8 | Deployment ≠ switch: request is `PENDING`, the job flips the channel | A deployment is never reported done before it is | | 9 | Machine principals via scoped project keys | CI gets least privilege without a user account | | 10 | BullMQ with an `inline` mode | Durable retried jobs in prod; deterministic tests, Redis-free dev | | 11 | Access token in memory + `HttpOnly` rotating refresh cookie | Limits XSS blast radius | | 12 | One channel serves one release | Simple, atomic. Trade-off: no per-runtime-version pointers yet (warned in UI) | | 13 | Telemetry in Postgres behind an API | Fine to a large scale; swap for a columnar store later without API change | ## Technical limitations by ecosystem See [Stack adapters](https://stacklift.joynul.com/docs/adapters.md). In short: mobile native binaries are tracked, never OTA-updated; desktop installers are delivered and verified but run by your app (no rollback, no delta updates); Flutter Dart OTA and the React Native/Expo/Capacitor on-device loaders are not implemented; web and backend are artifact/deployment tracking — Stacklift does not host or run your software. See [Desktop apps](https://stacklift.joynul.com/docs/desktop.md) and [SDKs](https://stacklift.joynul.com/docs/sdk.md). ## Infrastructure requirements PostgreSQL 16, Redis 7 (BullMQ + SSE fan-out; optional with `QUEUE_MODE=inline`), S3-compatible object storage + optional CDN, SMTP for mail (dev prints to the console), Node 20+. ## Security risks considered Cross-tenant access, credential theft (public key in apps, CI secrets), artifact tampering/replay, SSRF via webhooks, upload abuse, refresh-token theft, privilege escalation through invitations/role changes. Mitigations are listed in [Security](https://stacklift.joynul.com/docs/security.md) and covered by `apps/api/test/security.e2e.test.ts`. --- # Security model ## Threat model in one paragraph An attacker may: hold a valid account in another tenant, steal a public SDK key from a shipped app, intercept or replay update traffic, tamper with stored artifacts, or compromise a CI secret. Stacklift is designed so that none of these lets them read another tenant's data, publish an update to devices, or deliver an unsigned/altered artifact. ## Authentication - Passwords: scrypt (N=16384) with a per-password salt. Login performs a hash comparison even for unknown accounts and returns an identical error. - Sessions: 15-minute JWT access tokens (kept in memory by the web app) + 30-day **rotating** refresh tokens in an `HttpOnly`, `SameSite=Lax` cookie. Reusing a rotated refresh token revokes the whole token family. - Email verification and password reset tokens are random, stored as SHA-256, single-use (atomic claim) and expire. Resetting a password revokes all sessions. - Google and GitHub sign-in go through Firebase Authentication, which only proves identity. The dashboard sends the Firebase ID token to `POST /auth/firebase`; the API verifies its signature against Google's published keys, its issuer and audience (our Firebase project) and its expiry, and accepts only `google.com` and `github.com` sign-ins (email/password tokens are refused). Accounts are matched by the provider's own account id and linked by email only when the provider vouches the address is verified. Stacklift then issues its own session; the browser signs out of Firebase immediately, so no Firebase session is kept. Inert until `FIREBASE_PROJECT_ID` is set. - Rate limiting: global per-client limit and a stricter limit on credential endpoints. ## Authorization and tenant isolation - Every org-scoped route resolves the organization and the caller's membership in one guard. A non-member gets **404**, so existence isn't disclosed. - Project ids are looked up *inside* the resolved organization. A project, release, channel or rollout id from another tenant can't match, even with a valid org in the URL. - RBAC permissions are defined once in `@stacklift/shared` (`ROLE_PERMISSIONS`). A project membership can only elevate a role. - Ownership rules: only owners grant/alter ownership; an organization always keeps at least one owner; invitations only work for the invited, verified email. - All org-owned tables carry `orgId` (denormalised on purpose) so a query can always be constrained by tenant. ## Credentials | Credential | Format | Storage | Can do | | --- | --- | --- | --- | | Personal access token | `slp__` | SHA-256 of secret | Acts as the user (CLI) | | Project public key | `slk_…` (type PUBLIC) | SHA-256 | `updates:check`, `updates:report` only | | Project secret key | `slk_…` (type SECRET) | SHA-256 | One project, scoped (CI) | Secrets are shown once and never returned again. Keys can be rotated (optionally with a grace period) and revoked; revocation takes effect within 15 seconds on the delivery plane (auth cache TTL) and immediately on the control plane. ## Artifacts and signing - Uploads use signed, expiring, size-bound URLs straight to object storage. Keys are tenant-prefixed and content-addressed. - The control plane **recomputes** SHA-256 and size from the stored object; client-declared values are never trusted. Mismatch → artifact and release fail, the object is deleted. - Each project has an Ed25519 key pair. The private key is encrypted with AES-256-GCM (`KEY_ENCRYPTION_SECRET`) and never leaves the API. The signature covers checksum, size, release id, version, platform, runtime version and kind, so an artifact can't be replayed as another release. - Clients verify size, checksum and signature before applying, and should pin the public key. - Layouts (`ui-layout`) are data, never code, and are validated on the server before signing: known components only, https-only links, at most 512 KB, 32 levels, 2000 components and 500 list items, and bindings that read only the data's own properties (never the prototype chain). Every renderer enforces the same limits again, and a layout it cannot draw is never applied. - Scripts (`script-bundle`) run in an interpreter with no network, file or timer access, and can call only the functions the app registers. - With the local storage driver, uploads go to a receiver authorised by a signed, expiring, size-capped token. Body parsers are disabled on that route, so the bytes are streamed to disk exactly as sent. - Replace `CryptoService` with a KMS-backed implementation to keep key material in an HSM — that boundary is deliberate. ## Webhooks HMAC-SHA256 over `timestamp.body`, replay window enforced by the receiver, SSRF guard on targets, no redirects, secret encrypted at rest. ## Operational - Strict zod validation on every body/query; unknown fields stripped. - `helmet` headers, CORS allow-list, 1 MB JSON limit, uniform error envelope that never leaks internals. - Audit log for membership, project, release, deployment, rollout, rollback, key and integration changes. - Idempotency keys on deployments; BullMQ jobs are retried with exponential backoff and handlers are idempotent. - State changes that must be atomic (deploy execution, rollback, rollout completion) run in a database transaction with row locks. ## Known gaps (tracked in the roadmap) - No SSO/SCIM, no 2FA yet. - Billing/plan limits are not enforced. - The `local` storage driver is for development; use S3-compatible storage + CDN in production. - Telemetry (`UpdateEvent`) lives in Postgres; very large fleets should move it to a columnar store behind the same API. --- # Roadmap and status An honest ledger. **Done** means implemented and covered by tests or verified end to end; **Partial** and **Planned** are exactly that. ## Phase 1 — Product foundation: done Monorepo, Prisma schema + migration, authentication (email/password, email verification, password reset, Google and GitHub sign-in through Firebase), organizations, workspaces, members, invitations, RBAC, audit log, project management, adapter registry with capability matrix, dashboard and the full web app, OpenAPI. ## Phase 2 — Release infrastructure: done Presigned uploads, server-side verification and signing, release state machine, channels, environments, release history and comparison, promotion, rollback with compatibility safeguards. ## Phase 3 — Developer experience: done (CLI) / partial (SDK) `stacklift` CLI with JSON output and CI support (releases, channels, rollouts, store state, project keys, tokens, webhooks, layouts, audit log; the npm release is prepared, not published), `stacklift.yaml`, client SDKs (check, download, verify, report — see Phase 6), CI guides. The SDKs perform delivery and verification; applying updates on-device is stack-specific (see Phase 4). ## Phase 4 — Update engines: started | Adapter | State | | --- | --- | | React Native (JS bundles) | **Code push works** (`packages/sdk-react-native`): new bundle on the next launch, confirm, crash recovery and rollback, plus server-driven screens. Verified on the iOS simulator, an Android emulator and a physical HONOR ELI-NX9 phone (Android 16); not published to npm | | Web / Next.js / Vue / Nuxt / Angular / Svelte / SvelteKit | **Supported** as artifact + channel deployment (Stacklift doesn't host the site) | | Node / Python / Go / Java / .NET | Release + deployment tracking; `container-image-ref` for images. Stacklift doesn't run your servers | | Flutter (Dart OTA) | **Planned** — needs a patched engine and patch builder | | Android / iOS native | Binaries ship through the stores and are tracked. **Over the air:** server-driven screens (SwiftUI, Compose) and scripted logic (JavaScriptCore, QuickJS), verified on the iOS simulator and an Android 17 emulator | | Expo / Capacitor / NativeScript | **Partial**: control plane and delivery work, `sdk-js` verifies; no on-device loader yet (an Expo app with its native folders could use the React Native package, but that is not tested) | | Kotlin Multiplatform, .NET MAUI, Unity | Mobile builds tracked as native releases; desktop builds delivered as installers | | Desktop: Electron, Tauri, Flutter desktop, .NET, macOS, Qt, JVM, other | **Partial** — signed installers are delivered and verified; your app runs them. No rollback, no delta updates, no OS code signing | ## Phase 5 — Production infrastructure: partial Done: staged rollouts with opt-in auto-expansion and failure-rate pause, analytics, live updates (SSE), webhooks with retries, rate limiting, audit. A single-server deployment (Docker, Caddy with automatic HTTPS, a GitHub Actions deploy with health-checked rollback) is written and its pieces are checked, described in the internal deploy guide; it has not been run against a real server yet. Planned or not yet done: CDN URL signing (S3 presigned URLs work today), per-runtime-version channel pointers, billing and plan enforcement, SSO/SCIM, 2FA, notification channels (Slack, Discord), source-control triggers (GitHub/GitLab/Bitbucket apps), first-party CI actions, columnar telemetry store, KMS-backed signing keys, storage lifecycle automation. ## Phase 6 — Client SDKs and desktop: done (tested SDKs) / untested (Kotlin, Rust) 29 adapters across mobile, desktop, web and backend. A new `desktop-installer` artifact kind and `desktop-update` mechanism. SDKs for TypeScript (`sdk-js`, `sdk-electron`), Swift, Dart/Flutter, .NET and Java, each passing the same 14 signature conformance vectors; `sdk-js` is also tested against the real API end to end. **Verified in a real app:** the Swift SDK (in a SwiftUI app) and the Dart/Flutter SDK (in a Flutter app) on the iOS simulator, and the Android SDK (in a Compose app) and the Flutter app on an Android 17 emulator, and the Android SDK and the React Native package on a physical HONOR ELI-NX9 (Android 16), all against a live server: update checks, downloads, scripts, server-driven layouts, code push and rollback. **Not verified:** a physical iPhone, shrunk (R8) Android builds on a phone (they pass on the emulator), a MAUI head, Unity and a running Electron app. Those SDKs are tested as libraries on the host machine. **Untested source:** `packages/sdk-kotlin` (coroutine wrapper over the Java SDK) and `packages/sdk-tauri` (Rust crate + Tauri 2 plugin) have never been compiled — no Kotlin or Rust toolchain was available. Their own tests exist but have never run. **Not built:** an on-device bundle loader for Expo (managed) / Capacitor / NativeScript; Electron `app.asar` and Tauri frontend hot-swaps; C++/Qt SDK; Expo Updates protocol; Addressables hosting for Unity; publishing any SDK to a package registry (the npm release of the CLI, `sdk-js` and `sdk-electron` is prepared, see [Publishing to npm](https://stacklift.joynul.com/docs/publishing.md), but not done). ## Phase 7 — Store releases: done (recording) / planned (store integrations) Done and tested: store builds are **recorded by the CLI without uploading** (`--native`); version, build number and app id are read from the built `.ipa` / `.aab` themselves (Info.plist; protobuf AndroidManifest checked against an `aapt2`-built manifest and three real IPAs), with the project files (Flutter, Gradle, Xcode, Expo, .NET, Unity, Electron, Tauri) as the fallback; store links per project (Google Play derived from the package name, flagged as derived); per-release store status (`stacklift store status` and the dashboard); active devices per version from SDK check-ins; store-only releases can't be deployed. Verified end to end with the real CLI against the API, and in the dashboard. **Not built:** talking to the stores. Stacklift can't see **store download counts, ratings or review state** and doesn't upload to the stores — those need App Store Connect and Google Play Developer API integrations (planned). Store status is whatever you record. Device counts cover only apps that embed an SDK and check in. `.apk`, MSIX, DMG and EXE are not opened for their version. ## Known limitations - A channel serves one release; deploying a different runtime version warns that devices on the previous runtime stop receiving updates from it. - The browser uploader handles files up to 100 MB (WebCrypto cannot stream); use the CLI for larger artifacts. - The local storage driver and its same-origin proxy are for development. - Browser/UI verification so far is by build, typecheck and API-level tests; there are no Playwright tests yet. ## Flutter code push (Dart code over the air) Not built. A spike found it is technically possible as a Shorebird-compatible server, but not cleared: Shorebird's Terms neither forbid nor license using their builds with another server, they say they offer no self-hosting, and the protocol can drift. ## Over-the-air layers for native and Flutter apps Built: the `script-bundle` kind and `script-update` mechanism on the server, the CLI and the dashboard, the Swift runtime (staged scripts, apply on next launch, crash rollback, JavaScriptCore sandbox) and the Flutter runtime (`packages/sdk-dart` state machine, `packages/sdk-flutter-scripts` interpreter adapter) and the Android runtime (`packages/sdk-android`, QuickJS with memory and time limits). Not built: the C# runtime, and on-device loaders for Expo and Capacitor. (React Native code push is built, see Phase 4; remote UI is built, see Server-driven UI below.) See [ota-layers.md](https://stacklift.joynul.com/docs/ota-layers.md). ## Server-driven UI Built: the open stacklift-ui/1 format (JSON Schema, validator, reference resolver, shared fixtures), server validation before signing, `stacklift ui validate` / `ui export` (eject to SwiftUI or Flutter), the `ui-layout` release type with a per-kind update check, SwiftUI, Jetpack Compose, Flutter and React Native renderers with next-launch apply, rollback and fallbacks. Verified on the iOS simulator and an Android 17 emulator in the demo apps, and on a physical Android 16 phone (Compose and React Native demos). Dashboard editor: outline with drag and drop, live phone preview, property forms, sample data, checks, publish as a release, export to code. Not built: a Home Screen widget (WidgetKit) renderer, MAUI and Unity renderers, eject to Compose or React Native code, a run on a physical iPhone, shared drafts. See [server-driven-ui.md](https://stacklift.joynul.com/docs/server-driven-ui.md). --- # Publishing to npm Three packages go on npm. Everything else (`api`, `web`, `database`, the other SDKs) does not. | Package | What it is | Install | | --- | --- | --- | | `stacklift` | The CLI. One bundled file, no runtime dependencies. | `npm i -g stacklift` | | `@stacklift/sdk-js` | Client SDK for JavaScript, React Native, Capacitor, browsers. | `npm i @stacklift/sdk-js` | | `@stacklift/sdk-electron` | Updater for Electron apps (depends on `sdk-js`). | `npm i @stacklift/sdk-electron` | The Swift, Dart, .NET, Java, Kotlin and Rust SDKs use their own registries (SwiftPM, pub.dev, NuGet, Maven Central, crates.io) and are not covered here. ## One-time setup 1. Create an npm account and turn on 2FA. Run `npm login`. 2. The scoped SDKs need the `@stacklift` scope: create an organization named `stacklift` at npmjs.com (free for public packages). If that name is taken, rename the scope in the two SDK `package.json` files and in the code that imports them. 3. Check the CLI name is still free: `npm view stacklift` should say 404. If not, pick another and change `name` in `apps/cli/package.json`. 4. The licence is MIT, copyright "Stacklift contributors" (see `LICENSE`). Change it before the first publish if you want something else; a published version's licence cannot be taken back. ## Check before you publish ```bash pnpm install pnpm db:generate && pnpm build:packages pnpm typecheck && pnpm lint && pnpm test pnpm pack:check # lists exactly which files each package would ship ``` `pack:check` is a dry run. Each tarball should contain only `dist/`, `bin/` (CLI), `README.md`, `LICENSE` and `package.json`. The CLI is a single ~700 kB file. To try the real thing in a clean folder: ```bash mkdir /tmp/try && cd /tmp/try && npm init -y (cd /apps/cli && pnpm pack --pack-destination /tmp/try) npm i ./stacklift-0.1.0.tgz && npx stacklift --version ``` ## Publish by hand (first time) ```bash pnpm --filter @stacklift/sdk-js publish --access public pnpm --filter @stacklift/sdk-electron publish --access public pnpm --filter stacklift publish --access public ``` Publish `sdk-js` before `sdk-electron`, which depends on it. pnpm replaces `workspace:*` with the real version number when it packs. `prepack` rebuilds each package first, so a stale `dist` cannot ship. A published version can never be overwritten; if you made a mistake, bump the version and publish again (`npm deprecate` flags the bad one). ## Releases from CI `.github/workflows/release.yml` publishes all three when you push a version tag: 1. Add an npm automation token as the repository secret `NPM_TOKEN`. 2. Bump `version` in the three `package.json` files, and `CLI_VERSION` in `apps/cli/src/api.ts` (a test fails if they differ). Keep them equal. 3. Commit, then `git tag v0.1.1 && git push --tags`. The workflow refuses to run if the tag and the package versions disagree, runs typecheck, lint and the package tests, and publishes with provenance (npm shows a "built from this commit" badge). It has not been run yet: the first real tag is its first test, so do the first release by hand. ## Which API the published CLI talks to A CLI built from source talks to `http://localhost:4000` unless `STACKLIFT_API_URL` is set. The published one must default to the hosted API, which is fixed when the bundle is built: ```bash STACKLIFT_BUILD_API_URL=https:// pnpm --filter stacklift build ``` The release workflow sets it to `https://stacklift-api.joynul.com` for the build step, so a tagged release talks to the hosted API by default. Users can still override it with `--api-url` or `STACKLIFT_API_URL`. If the API hostname ever changes, update it in `.github/workflows/release.yml` and keep the old hostname working for as long as old CLI versions are in use. ## Why the CLI is bundled `apps/cli` is built with esbuild into one file that contains `@stacklift/shared`, `@stacklift/adapters`, `@stacklift/sdk-core`, `commander`, `yaml` and `zod`. That is why those appear only as `devDependencies`: nothing is installed alongside it, so it cannot break on a mismatched internal package, and those internal packages never need publishing. --- # Spike: Flutter code push on Stacklift **Question.** Can Stacklift be the server and dashboard for Shorebird-style Flutter code push (Dart code updated over the air: downloaded when the app opens, applied on the next launch), without building a Flutter engine fork ourselves? **Verdict: technically yes, but do not build it on Shorebird's engine without their written permission.** The Terms (read in full; see Terms of Service on this page) neither forbid nor license running Shorebird's builds against another server. That is a grey zone, and the engine binaries, the iOS interpreter and the CLI's artifact downloads all come from Shorebird. Not legal advice. How this was done: reading Shorebird's open-source repositories (`shorebirdtech/shorebird`, `shorebirdtech/updater`) and docs. Nothing was executed yet. Facts marked *read* come from source files; *unverified* means not yet read or run. ## What Shorebird is made of | Piece | Open source? | Role | | --- | --- | --- | | Flutter engine/framework fork | Fork of Flutter (BSD) | Contains the updater and, on iOS, an interpreter for patched code | | `updater` (Rust) | Yes, Apache-2.0 or MIT | Runs inside the app: asks the server for a patch, downloads, verifies, applies on next boot | | `shorebird_cli` (Dart) | Yes, Apache-2.0 or MIT | `shorebird release` / `shorebird patch`: builds with the fork, computes the diff, uploads | | Protocol and client packages | Yes | The API contract between CLI/app and server | | Server (api.shorebird.dev) | Not in the repo that was read | The part Stacklift would replace | ## Verified: the server can be replaced All *read* from source: - **App to server (2 endpoints).** `POST {base_url}/api/v1/patches/check` and `POST {base_url}/api/v1/patches/events`. `base_url` is a plain key in the app's `shorebird.yaml`, so each app can point at any server. - Check request: `app_id, channel, release_version, platform, arch, client_id`, plus optional `host_bundle_id, host_version, current_patch_number`. - Check response: `patch_available`, optional `patch {number, hash, download_url, hash_signature?}`, optional `rolled_back_patch_numbers`. - Events: `{"event": {type, app_id, arch, client_id, patch_number, platform, release_version, timestamp, message, ...}}`; only a 2xx matters. - Download: plain `GET` of `download_url` (with `Range` resume). The file is zstd-compressed `bipatch` data; the server only stores and serves it. - **Behaviour matches what you want.** The patch is downloaded in the background, verified, and takes effect when the engine next boots. A patch that fails to start falls back to the last good one. - **CLI to server.** `SHOREBIRD_HOSTED_URL` overrides the API address, and `SHOREBIRD_DOWNLOAD_URL` overrides where engine artifacts come from. - **CLI auth is shimmable.** An API key is sent as `Authorization: Bearer sb_api_…` and "the server validates it on every request", so a server can accept its own keys with that prefix. - **Signing is simple and the server holds no private key.** The developer signs; the server just relays `hash_signature`. Scheme: RSASSA-PKCS1-v1_5 with SHA-256 over the ASCII hex hash string; the public key is base64 DER RSA in `patch_public_key`. This is **RSA, not Ed25519**, so Stacklift's existing signer cannot be reused for patches. ### CLI-facing API a compatible server must implement (about 20 endpoints) `GET /users/me` · `GET/POST /apps`, `GET /apps/{id}` · `GET/POST /apps/{id}/channels` · `POST /apps/{id}/releases`, `GET …/releases`, `PATCH …/releases/{id}` · `POST/GET …/releases/{id}/artifacts` (multipart, then upload to a returned URL, resumable `PUT` in 8 MiB chunks) · `POST /apps/{id}/patches`, `POST …/patches/{id}/artifacts` · `POST /apps/{id}/patches/promote` · `PUT/POST …/patches/{id}/rollout|rollback|rollforward` · `GET /apps/{id}/signing-key`. Organizations, enterprises, billing, service accounts and metrics endpoints exist but are not needed for a first version. ### How it maps onto Stacklift | Shorebird | Stacklift | | --- | --- | | app | Project | | release (`version`, Flutter revision) | Release (`release_version` becomes the runtime-version key) | | release artifacts (aab / ipa / per-arch libapp) | Artifact, hosted (new kind; these are large binaries) | | patch + patch artifacts | **New**: Patch, PatchArtifact (number per release, arch, hash, signature, rollout %) | | channel, promote, rollout %, rollback | Channels, deployments, rollouts, rollbacks (already built) | | patch install events, `client_id` | UpdateEvent, device counts (already built) | The dashboard side (rollouts, rollback, per-version devices, audit) is the part already done. New work: patch models, about 20 endpoints, an `sb_api_` key shim, RSA key handling, large-file storage, and patch pages in the dashboard. Rough estimate: 2 to 3 weeks. ## Terms of Service (read in full) Source: Shorebird Code Push Terms of Service, "Last updated and Effective as of August 15th, 2025" (shorebird.dev/terms). Paraphrased; section letters are theirs. - **There is no clause that bans competing services, self-hosting or reverse engineering of Shorebird.** The only reverse-engineering sentence (D) is a promise by Shorebird not to reverse engineer *your* app. - **But the licence is narrow (E).** You get a licence to access, download, install and use "the Services", *solely during the applicable term of Your use of the Services*, and to distribute apps built with them without distributing the Services themselves. It belongs to an account holder who accepts the Terms and pays (F). - **Everything else is reserved (I).** Shorebird owns the Services, software and materials; you may not copy, modify, distribute or make derivative works of materials accessible on the Service, and any use not expressly permitted is "strictly prohibited". Shorebird's own engine binaries and CLI downloads are served from its hosts, so using them *without* using the hosted Service is not clearly covered. - **They can change or stop it at any time (H),** with or without notice, and terminate an account at their sole discretion (G). All your apps and data are deleted on termination. - **Beta (B).** The Services are described as beta, "a work in progress". - **Other limits that matter for a third party:** no automated systems that send more requests than a human browser would (E); no bypassing restrictions or deciphering transmissions to and from their servers (G); a login may be used by one person only (C). What the Terms do not cover: the open-source repositories carry their own licences (updater and CLI: Apache-2.0 or MIT; the Flutter fork: BSD-3-Clause). Those licences let anyone use that *source*. They do not say anything about Shorebird's prebuilt binaries, and the Terms above apply to those. ### What is and is not open source (read) | Piece | Public? | | --- | --- | | `updater` (Rust), `shorebird` CLI, protocol and client packages | Yes, Apache-2.0 or MIT | | `flutter` fork | Yes, BSD-3-Clause | | `engine` fork | Yes, BSD-3-Clause, but the repository is archived (read-only) | | The server behind api.shorebird.dev | No public repository found | | The iOS interpreter | No public repository found among the roughly 30 of 36 listed; not confirmed either way | | Prebuilt engine artifacts (`download.shorebird.dev`) | Downloadable, but covered by the Terms, not an open-source licence | So a fully independent stack (our own server *and* our own engine builds) would be legal to build from the open-source code, but you would build and host the patched engine for every Flutter version and platform yourself, and the iOS interpreter may not be available as source. ## Blockers (answer these before building) 1. **Permission to use Shorebird's binaries with another server.** Not forbidden, not licensed. Ask in writing (contact@shorebird.dev, the address the Terms give): (a) may customers run Shorebird's CLI and engine builds against a third-party server? (b) may the engine artifacts be mirrored? (c) is the iOS interpreter source available under an open-source licence? A "no" or no answer means: do not build on their binaries. 2. **Protocol drift.** The CLI sends an `x-version` header and the server can answer `426` to force an upgrade, so the contract changes as Shorebird changes it. A compatible server is a permanent catch-up job. The exact JSON of the release and patch models has not been read yet (*unverified*). ## Other risks - **iOS.** Patches run in Shorebird's custom interpreter, only on physical arm64 devices and only in release builds. Stacklift cannot touch that; it all comes from their engine. - **Storage cost.** `shorebird patch` downloads the original release binary to diff against it, so Stacklift must store every release's aab/ipa, unlike the current "record only" store builds. - **Apple and Google policy.** Patches must not change the primary purpose of the app (App Store Guideline 3.3.2). ## Alternatives if blocker 1 is a no - **Own engine fork + updater.** Months of work, re-ported for every Flutter release. The Rust updater is permissively licensed and reusable, but the iOS interpreter is the hard part. - **Config and asset updates only** (already built): no Dart code changes. ## Recommended next step 1. Send the three questions above to Shorebird and wait for an answer in writing. 2. Only if the answer is yes, a throwaway proof on Android only: a minimal fake server (check, events, and the CLI endpoints in memory), install Shorebird's CLI, point it at the fake server with `SHOREBIRD_HOSTED_URL`, run `shorebird release android` and `shorebird patch android` on a Flutter app, install on an emulator, and watch the patch apply on the second launch. This proves the whole chain before any Stacklift schema or UI work. It downloads Shorebird's CLI and its Flutter fork (several GB). Sources: [Code Push Terms of Service (Aug 15, 2025)](https://shorebird.dev/legal/Terms%20of%20Service%20-%20Shorebird%20Code%20Push.pdf), [shorebirdtech repositories](https://github.com/orgs/shorebirdtech/repositories), [shorebirdtech/shorebird](https://github.com/shorebirdtech/shorebird), [shorebirdtech/updater](https://github.com/shorebirdtech/updater), [Shorebird FAQ](https://docs.shorebird.dev/code-push/faq/), [iOS beta announcement](https://shorebird.dev/blog/ios-beta).