Markdown

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

StackPackageVerified byNot 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 SDKs10 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, rollbackA 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 APIInside a real RN / Capacitor / NativeScript app
Electron@stacklift/sdk-electron (packages/sdk-electron)15 tests: fake Electron APIs, real HTTP serverInside a running Electron app
iOS, macOS (Swift)Swift package Stacklift (packages/sdk-swift): client, scripts, server-driven UIswift test, 37 tests on macOS; scripts, layouts and code push run in demo apps on the iOS simulatorA physical device
Flutter / Dart — Android, iOS, web, Windows, macOS, Linuxstacklift (packages/sdk-dart): client, scripts and layouts lifecycledart test, 80 tests on the Dart VMWeb target
Flutter widgetsstacklift_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 simulatorAndroid, a physical device
.NET — WPF, WinForms, WinUI, MAUI, UnityStacklift.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 SDK28 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 emulatorR8 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-jsUnit tests + e2e—
Kotlin Multiplatform (androidMain, jvmMain)packages/sdk-kotlinUntested. Never compiled — no Kotlin toolchain hereEverything. It wraps the Java SDK in coroutines
Tauri / Rustpackages/sdk-tauriUntested. Never compiled — no Rust toolchain hereEverything. Prefer @stacklift/sdk-js from the frontend first
Qt / C++, GTK, Win32, Go, othersnone—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.

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).

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/<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)

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.

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

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 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)

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 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:

  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 <dest>.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: <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

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": "<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:

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.