<!-- Stacklift documentation: "SDK". Source: https://stacklift.joynul.com/docs/sdk · All pages for LLMs: https://stacklift.joynul.com/llms-full.txt -->

> About Stacklift: 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.
>
> This page: Check, download and verify updates from your app, in every language.

# 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/<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](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 `<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.
