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 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 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), 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.
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-valuesbefore first use (Hermes has no secure random). The default RNfetchhas 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
StackliftErrorwith a stablecode(see error codes).
Electron
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 signalThe installer is streamed to userData/updates/<version>/<name>.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)
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 installerURLURLSession 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.
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.
Dart / Flutter
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 and OTA for every stack.
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)
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)
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 and OTA for every stack. 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:
- Signature before bytes. The manifest's signature is verified *before* the artifact URL is requested. A forged manifest never causes a download.
- Pinned key. If a key is pinned and the manifest carries a different one:
key_mismatch. - 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).
- SHA-256. Hashed incrementally; compared to the signed value.
- Nothing partial survives. Files are written to
<dest>.partand 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: <PUBLIC project key> and content-type: application/json. The official SDKs also send x-stacklift-sdk: <platform>/<version> mark=<hex>, a diagnostic header. Your own client does not need it and is never rejected for leaving it out.
Check — POST /v1/updates/check
{ "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:
{ "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": "<base64>", "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:<hex>
size:<bytes>
release:<release.id>
version:<release.version>
platform:<release.platform>
runtime:<release.runtimeVersion>
kind:<release.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:
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.shTo add a language, make it pass every case and add its suite to CI.