@shipvo/capacitor 0.0.1 → 0.0.3

package/Package.swift

@@ -0,0 +1,19 @@
+// swift-tools-version:5.9
+// Entry point for Capacitor's Swift Package Manager integration (`cap sync ios` links this package).
+// The sources live in ios/Sources; ios/Package.swift runs the same ShipvoBundle target's tests.
+import PackageDescription
+
+let package = Package(
+  name: "ShipvoCapacitor",
+  platforms: [.iOS(.v15)],
+  products: [.library(name: "ShipvoCapacitor", targets: ["ShipvoCapacitor"])],
+  dependencies: [.package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")],
+  targets: [
+    .target(name: "ShipvoBundle", path: "ios/Sources/ShipvoBundle"),
+    .target(
+      name: "ShipvoCapacitor",
+      dependencies: [.product(name: "Capacitor", package: "capacitor-swift-pm"), "ShipvoBundle"],
+      path: "ios/Sources/ShipvoCapacitor"
+    ),
+  ]
+)

package/README.md

@@ -2,7 +2,40 @@
 
 Signed over-the-air updates for the web bundle of a Capacitor app. It makes the same release decisions and keeps the same trust model as `@shipvo/runtime` (see `docs/adapters.md`).
 
-This is the core, in TypeScript. It does not yet apply a bundle on a device. The native layer (next slice) backs two small interfaces, `KeyValueStore` and `BundleFiles`, and calls `boot()` when the web view loads.
+The core is TypeScript and makes every decision: it verifies the signature and the hash, stages, promotes and rolls back. The native layer only stores bytes and switches the web view.
+
+| Platform | Native layer |
+|---|---|
+| Android | `android/`: stores the verified bundle zip in app-private files and the state in SharedPreferences; switches the web view with `Bridge.setServerBasePath` to the unpacked bundle |
+| iOS | Next slice, tracked in its own issue. It will use the same JavaScript core and the same `boot` and `bootAndServe` calls as Android. |
+
+## Android
+
+`android/` is a Capacitor plugin named `Shipvo`. It backs `KeyValueStore` with SharedPreferences and `BundleFiles` with the app-private files directory, and points the web view at the staged bundle. A web bundle is a zip of your web assets with an `index.html` at its root.
+
+1. Register it in `MainActivity` with `registerPlugin(ShipvoPlugin.class)` before `super.onCreate`.
+2. Include the module in `settings.gradle` and add `implementation project(':shipvo-capacitor')` (see `apps/capacitor-sample/android`).
+3. When the page loads, call `bootAndServe`. It runs `boot()` (rollback included) and tells native to serve the chosen file. Native checks the sha-256 the core verified once more before it unpacks, and refuses zip entries that leave the directory.
+
+```ts
+import { registerPlugin } from "@capacitor/core";
+import { ShipvoCapacitor, NativeStore, NativeFiles, bootAndServe, bootAndSwitch } from "@shipvo/capacitor";
+import type { ShipvoNativePlugin } from "@shipvo/capacitor";
+
+const native = registerPlugin<ShipvoNativePlugin>("Shipvo");
+const shipvo: ShipvoCapacitor = new ShipvoCapacitor({
+  appId: "tide", shellMajor: 1, shellVersion: "1.2.0", platform: "android",
+  publicKey: "<base64 Ed25519 key>", baseUrl: "https://cp.example.com",
+  store: new NativeStore(native), files: new NativeFiles(native),
+  onReload: async () => { await bootAndSwitch(shipvo, native); },
+});
+await bootAndServe(shipvo, native);
+await shipvo.markHealthy();
+```
+
+Each launch starts on the embedded bundle, then `bootAndServe` switches to the pending or current release. The page of a served bundle runs the same code; it resumes the release `boot()` already chose and does not count another trial boot.
+
+Tests: `pnpm --filter @shipvo/capacitor test` runs the stage, apply, crash and rollback sequence through the native bridge. The plugin's JVM tests run with `./gradlew :shipvo-capacitor:testDebugUnitTest` in `apps/capacitor-sample/android` (after `pnpm --filter capacitor-sample sync`).
 
 ## Install
 
@@ -19,7 +52,7 @@ const shipvo = new ShipvoCapacitor({
   appId: "tide", shellMajor: 1, shellVersion: "1.2.0", platform: "android",
   publicKey: "<base64 Ed25519 key baked into the shell>",
   baseUrl: "https://cp.example.com",
-  store: new MemoryStore(), files: new MemoryFiles(), // the native layer provides real ones
+  store: new MemoryStore(), files: new MemoryFiles(), // Android: NativeStore and NativeFiles
 });
 
 const { release, file } = await shipvo.boot();      // which bundle to serve

package/android/build.gradle

@@ -0,0 +1,18 @@
+apply plugin: 'com.android.library'
+
+android {
+    namespace = "dev.shipvo.capacitor"
+    compileSdk = rootProject.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdkVersion rootProject.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+dependencies {
+    implementation project(':capacitor-android')
+    testImplementation "junit:junit:4.13.2"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/dev/shipvo/capacitor/BundleStore.java

@@ -0,0 +1,116 @@
+package dev.shipvo.capacitor;
+
+import java.io.ByteArrayOutputStream;
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.security.MessageDigest;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.zip.ZipEntry;
+import java.util.zip.ZipInputStream;
+
+/**
+ * Bundle files in a private directory. No Android classes, so it runs in a plain JVM test.
+ * It never decides anything: the TypeScript core verifies the signature and hash; this class
+ * only stores bytes and re-checks the hash it is given before it unpacks.
+ */
+public final class BundleStore {
+    private final File dir;
+    private final File served;
+
+    public BundleStore(File root) {
+        this.dir = new File(root, "bundles");
+        this.served = new File(root, "served");
+        dir.mkdirs();
+    }
+
+    private File file(String name) throws IOException {
+        if (name == null || !name.matches("[A-Za-z0-9._-]{1,128}") || name.contains("..")) {
+            throw new IOException("bad file name");
+        }
+        return new File(dir, name);
+    }
+
+    public void write(String name, byte[] bytes) throws IOException {
+        File f = file(name);
+        File tmp = new File(dir, name + ".tmp");
+        try (FileOutputStream o = new FileOutputStream(tmp)) { o.write(bytes); o.getFD().sync(); }
+        try { java.nio.file.Files.move(tmp.toPath(), f.toPath(), java.nio.file.StandardCopyOption.REPLACE_EXISTING); }
+        catch (IOException e) { tmp.delete(); throw new IOException("could not write " + name); }
+    }
+
+    public byte[] read(String name) throws IOException { 
+        try (InputStream in = new FileInputStream(file(name))) {
+            ByteArrayOutputStream out = new ByteArrayOutputStream();
+            copy(in, out);
+            return out.toByteArray();
+        }
+    }
+
+    private static void copy(InputStream in, OutputStream out) throws IOException {
+        byte[] buf = new byte[8192];
+        for (int n; (n = in.read(buf)) > 0; ) out.write(buf, 0, n);
+    }
+
+    public void remove(String name) throws IOException { file(name).delete(); }
+
+    public List<String> list() {
+        String[] names = dir.list();
+        List<String> out = new ArrayList<>();
+        if (names != null) { Arrays.sort(names); for (String n : names) if (!n.endsWith(".tmp")) out.add(n); }
+        return out;
+    }
+
+    public void clear() {
+        String[] names = dir.list();
+        if (names != null) for (String n : names) new File(dir, n).delete();
+        deleteTree(served);
+    }
+
+    public static String sha256Hex(byte[] bytes) throws IOException {
+        try {
+            byte[] d = MessageDigest.getInstance("SHA-256").digest(bytes);
+            StringBuilder sb = new StringBuilder();
+            for (byte b : d) sb.append(String.format("%02x", b));
+            return sb.toString();
+        } catch (java.security.NoSuchAlgorithmException e) { throw new IOException(e); }
+    }
+
+    /**
+     * Unpacks a stored zip into a fresh directory, but only if its sha-256 equals the hash the
+     * core verified against the signed pointer. Entries that escape the directory are refused.
+     */
+    public File unpack(String name, String expectedSha256) throws IOException {
+        byte[] bytes = read(name);
+        if (expectedSha256 == null || !sha256Hex(bytes).equalsIgnoreCase(expectedSha256)) {
+            throw new IOException("bundle hash does not match");
+        }
+        deleteTree(served);
+        File target = new File(served, name);
+        target.mkdirs();
+        String root = target.getCanonicalPath() + File.separator;
+        try (ZipInputStream z = new ZipInputStream(new java.io.ByteArrayInputStream(bytes))) {
+            ZipEntry e;
+            while ((e = z.getNextEntry()) != null) {
+                File out = new File(target, e.getName());
+                if (!out.getCanonicalPath().startsWith(root)) { deleteTree(served); throw new IOException("bad entry in bundle"); }
+                if (e.isDirectory()) { out.mkdirs(); continue; }
+                out.getParentFile().mkdirs();
+                try (OutputStream o = new FileOutputStream(out)) { copy(z, o); }
+            }
+        }
+        if (!new File(target, "index.html").isFile()) { deleteTree(served); throw new IOException("bundle has no index.html"); }
+        return target;
+    }
+
+    private static void deleteTree(File f) {
+        File[] kids = f.listFiles();
+        if (kids != null) for (File k : kids) deleteTree(k);
+        f.delete();
+    }
+}

package/android/src/main/java/dev/shipvo/capacitor/ShipvoPlugin.java

@@ -0,0 +1,107 @@
+package dev.shipvo.capacitor;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.util.Base64;
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import java.io.File;
+
+/**
+ * The native half of @shipvo/capacitor. It backs the core's KeyValueStore (SharedPreferences)
+ * and BundleFiles (app-private files), and points the web view at an unpacked bundle.
+ * It makes no release decisions and verifies no signatures: the TypeScript core does both.
+ */
+@CapacitorPlugin(name = "Shipvo")
+public class ShipvoPlugin extends Plugin {
+    private static final String PREFS = "shipvo";
+    // An instance field: a Plugin lives as long as its Bridge, and the web view's base path belongs to the Bridge.
+    // A new Bridge (Activity recreated in the same process) starts on the embedded assets, so it must boot again.
+    private volatile String serving;
+    private volatile String servingPath;
+    private BundleStore store;
+
+    private BundleStore store() {
+        if (store == null) store = new BundleStore(getContext().getFilesDir());
+        return store;
+    }
+
+    private SharedPreferences prefs() { return getContext().getSharedPreferences(PREFS, Context.MODE_PRIVATE); }
+
+    @PluginMethod
+    public void kvGet(PluginCall call) {
+        String key = call.getString("key");
+        JSObject r = new JSObject();
+        if (key != null && prefs().contains(key)) r.put("value", prefs().getString(key, null));
+        call.resolve(r);
+    }
+
+    @PluginMethod
+    public void kvSet(PluginCall call) {
+        String key = call.getString("key"), value = call.getString("value");
+        if (key == null || value == null) { call.reject("key and value are required"); return; }
+        // commit(), not apply(): the boot counter must be on disk before the page runs.
+        if (!prefs().edit().putString(key, value).commit()) { call.reject("could not save"); return; }
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void fileWrite(PluginCall call) {
+        try {
+            store().write(call.getString("name"), Base64.decode(call.getString("data", ""), Base64.NO_WRAP));
+            call.resolve();
+        } catch (Exception e) { call.reject(e.getMessage()); }
+    }
+
+    @PluginMethod
+    public void fileRead(PluginCall call) {
+        try {
+            JSObject r = new JSObject();
+            r.put("data", Base64.encodeToString(store().read(call.getString("name")), Base64.NO_WRAP));
+            call.resolve(r);
+        } catch (Exception e) { call.reject(e.getMessage()); }
+    }
+
+    @PluginMethod
+    public void fileRemove(PluginCall call) {
+        try { store().remove(call.getString("name")); call.resolve(); } catch (Exception e) { call.reject(e.getMessage()); }
+    }
+
+    @PluginMethod
+    public void fileList(PluginCall call) {
+        JSObject r = new JSObject();
+        r.put("names", new JSArray(store().list()));
+        call.resolve(r);
+    }
+
+    @PluginMethod
+    public void fileClear(PluginCall call) {
+        store().clear(); serving = null; servingPath = null; call.resolve();
+    }
+
+    /** Serve a stored bundle. `sha256` is the hash the core verified; it is checked again before unpacking. */
+    @PluginMethod
+    public void serve(PluginCall call) {
+        try {
+            String name = call.getString("name");
+            File dir = store().unpack(name, call.getString("sha256"));
+            getBridge().setServerBasePath(dir.getAbsolutePath());
+            serving = name;
+            servingPath = dir.getAbsolutePath();
+            call.resolve();
+        } catch (Exception e) { call.reject(e.getMessage()); }
+    }
+
+    /** Which bundle this process is already serving, so the page it loads does not boot again. */
+    @PluginMethod
+    public void status(PluginCall call) {
+        JSObject r = new JSObject();
+        // Report serving only while this Bridge still points at the unpacked directory.
+        if (serving != null && servingPath != null && servingPath.equals(getBridge().getServerBasePath())) r.put("serving", serving);
+        call.resolve(r);
+    }
+}

package/dist/engine.d.ts

@@ -48,6 +48,14 @@ export declare class ShipvoCapacitor implements ShipvoCapacitorPlugin {
         release: number;
         file?: string;
     }>;
+    /** sha-256 of a stored release's archive, as checked against the signed pointer when it was staged. The native layer re-checks it before it serves the file. */
+    bundleHash(release: number): Promise<string | undefined>;
+    /**
+     * The web view loaded a page of a release that `boot()` already chose in this process
+     * (the native layer switched bundles and the new page starts the core again). Sets the running
+     * release without counting another trial boot. Ignored unless it is the pending or current release.
+     */
+    resume(release: number): Promise<void>;
     /** The app stayed up long enough (the native layer decides how long). Clears the boot counter. */
     markStable(): Promise<void>;
     getState(): Promise<RuntimeState>;

package/dist/engine.js

@@ -107,6 +107,18 @@ export class ShipvoCapacitor {
         await this.save();
         return { release: s.current, file: s.current ? bundleName(s.current) : undefined };
     }
+    /** sha-256 of a stored release's archive, as checked against the signed pointer when it was staged. The native layer re-checks it before it serves the file. */
+    async bundleHash(release) { return (await this.load()).hashes[String(release)]; }
+    /**
+     * The web view loaded a page of a release that `boot()` already chose in this process
+     * (the native layer switched bundles and the new page starts the core again). Sets the running
+     * release without counting another trial boot. Ignored unless it is the pending or current release.
+     */
+    async resume(release) {
+        const s = await this.load();
+        if (release && (release === s.pending || release === s.current))
+            this.running = release;
+    }
     /** The app stayed up long enough (the native layer decides how long). Clears the boot counter. */
     async markStable() { const s = await this.load(); s.bootTimes = []; await this.save(); }
     async getState() {

package/dist/index.d.ts

@@ -3,3 +3,5 @@ export { ShipvoCapacitor, bundleName, MAX_BOOTS, WINDOW_MS } from "./engine.js";
 export type { ShipvoConfig } from "./engine.js";
 export { MemoryStore, MemoryFiles } from "./memory.js";
 export { verifyEd25519, sha256Hex, semverLess } from "./verify.js";
+export { NativeStore, NativeFiles, bootAndServe, bootAndSwitch } from "./native.js";
+export type { ShipvoNativePlugin } from "./native.js";

package/dist/index.js

@@ -2,3 +2,4 @@ export * from "./types.js";
 export { ShipvoCapacitor, bundleName, MAX_BOOTS, WINDOW_MS } from "./engine.js";
 export { MemoryStore, MemoryFiles } from "./memory.js";
 export { verifyEd25519, sha256Hex, semverLess } from "./verify.js";
+export { NativeStore, NativeFiles, bootAndServe, bootAndSwitch } from "./native.js";

package/dist/native.d.ts

@@ -0,0 +1,72 @@
+import type { ShipvoCapacitor } from "./engine.js";
+import type { BundleFiles, KeyValueStore } from "./types.js";
+/** The methods the Android plugin (`android/`, plugin name `Shipvo`) exposes through the Capacitor bridge. Binary data travels as base64. */
+export interface ShipvoNativePlugin {
+    kvGet(o: {
+        key: string;
+    }): Promise<{
+        value?: string;
+    }>;
+    kvSet(o: {
+        key: string;
+        value: string;
+    }): Promise<void>;
+    fileWrite(o: {
+        name: string;
+        data: string;
+    }): Promise<void>;
+    fileRead(o: {
+        name: string;
+    }): Promise<{
+        data: string;
+    }>;
+    fileRemove(o: {
+        name: string;
+    }): Promise<void>;
+    fileList(): Promise<{
+        names: string[];
+    }>;
+    fileClear(): Promise<void>;
+    /** Unpack the stored bundle and point the web view at it. Native re-checks `sha256` first. */
+    serve(o: {
+        name: string;
+        sha256: string;
+    }): Promise<void>;
+    /** The bundle this process already serves, if any. */
+    status(): Promise<{
+        serving?: string;
+    }>;
+}
+/** `KeyValueStore` backed by the native plugin (SharedPreferences on Android). */
+export declare class NativeStore implements KeyValueStore {
+    private n;
+    constructor(n: ShipvoNativePlugin);
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string): Promise<void>;
+}
+/** `BundleFiles` backed by the native plugin (the app-private files directory on Android). */
+export declare class NativeFiles implements BundleFiles {
+    private n;
+    constructor(n: ShipvoNativePlugin);
+    write(name: string, bytes: Uint8Array): Promise<void>;
+    read(name: string): Promise<Uint8Array<ArrayBuffer>>;
+    remove(name: string): Promise<void>;
+    list(): Promise<string[]>;
+    clear(): Promise<void>;
+}
+/**
+ * Run this first when the page loads. It asks the core which release to serve (`boot()`, which also
+ * decides rollback) and tells the native layer to serve that file. Native never picks a bundle on its own.
+ * Returns `served: true` when the web view is on a staged bundle.
+ */
+export declare function bootAndServe(shipvo: ShipvoCapacitor, native: ShipvoNativePlugin): Promise<{
+    release: number;
+    served: boolean;
+    error?: string;
+}>;
+/** Run `boot()` and serve its choice now. Use it as `onReload` so `checkForUpdate({ apply: true })` switches the web view. */
+export declare function bootAndSwitch(shipvo: ShipvoCapacitor, native: ShipvoNativePlugin): Promise<{
+    release: number;
+    served: boolean;
+    error?: string;
+}>;

package/dist/native.js

@@ -0,0 +1,55 @@
+const toB64 = (u) => { let s = ""; for (let i = 0; i < u.length; i += 0x8000)
+    s += String.fromCharCode(...u.subarray(i, i + 0x8000)); return btoa(s); };
+const fromB64 = (b) => Uint8Array.from(atob(b), (c) => c.charCodeAt(0));
+/** `KeyValueStore` backed by the native plugin (SharedPreferences on Android). */
+export class NativeStore {
+    n;
+    constructor(n) {
+        this.n = n;
+    }
+    async get(key) { return (await this.n.kvGet({ key })).value; }
+    async set(key, value) { await this.n.kvSet({ key, value }); }
+}
+/** `BundleFiles` backed by the native plugin (the app-private files directory on Android). */
+export class NativeFiles {
+    n;
+    constructor(n) {
+        this.n = n;
+    }
+    async write(name, bytes) { await this.n.fileWrite({ name, data: toB64(bytes) }); }
+    async read(name) { return fromB64((await this.n.fileRead({ name })).data); }
+    async remove(name) { await this.n.fileRemove({ name }); }
+    async list() { return (await this.n.fileList()).names; }
+    async clear() { await this.n.fileClear(); }
+}
+/**
+ * Run this first when the page loads. It asks the core which release to serve (`boot()`, which also
+ * decides rollback) and tells the native layer to serve that file. Native never picks a bundle on its own.
+ * Returns `served: true` when the web view is on a staged bundle.
+ */
+export async function bootAndServe(shipvo, native) {
+    const { serving } = await native.status();
+    if (serving) {
+        // This page was loaded by an earlier `serve` in this process: `boot()` already ran.
+        const release = Number(/^release-(\d+)\.bundle$/.exec(serving)?.[1] ?? 0);
+        await shipvo.resume(release);
+        return { release, served: true };
+    }
+    return bootAndSwitch(shipvo, native);
+}
+/** Run `boot()` and serve its choice now. Use it as `onReload` so `checkForUpdate({ apply: true })` switches the web view. */
+export async function bootAndSwitch(shipvo, native) {
+    const { release, file } = await shipvo.boot();
+    if (!file)
+        return { release: 0, served: false };
+    const sha256 = await shipvo.bundleHash(release);
+    if (!sha256)
+        return { release, served: false, error: "no verified hash for the stored bundle" };
+    try {
+        await native.serve({ name: file, sha256 });
+    }
+    catch (e) {
+        return { release, served: false, error: String(e?.message ?? e) };
+    }
+    return { release, served: true };
+}

package/ios/Sources/ShipvoBundle/Bundle.swift

@@ -0,0 +1,71 @@
+#if canImport(CryptoKit)
+import CryptoKit
+#else
+import Crypto
+#endif
+import Foundation
+
+public enum BundleError: Error, Equatable {
+  case badSignature, badPointer, badHash, badStorage, shellTooOld
+  /// Same codes as `expect` in test-vectors/bundle.json.
+  public var code: String {
+    switch self {
+    case .badSignature: return "bad_signature"
+    case .badPointer: return "bad_pointer"
+    case .badHash: return "bad_hash"
+    case .badStorage: return "bad_storage"
+    case .shellTooOld: return "shell_too_old"
+    }
+  }
+}
+
+/// Fields of a signed web release pointer that the bundle check reads.
+struct Pointer: Decodable {
+  struct Core: Decodable { let sha256: String; let size: Int }
+  let kind: String, platform: String?, app_id: String, shell_major: Int, band: String, release: Int, min_shell_version: String, core: Core
+}
+
+public struct Identity {
+  public var appId: String, shellMajor: Int, band: String
+  /// Installed app version, x.y.z.
+  public var shellVersion: String
+  /// Ed25519 public key (base64) built into the app. Never read from the network.
+  public var publicKey: String
+  public init(appId: String, shellMajor: Int, band: String, shellVersion: String, publicKey: String) {
+    self.appId = appId; self.shellMajor = shellMajor; self.band = band; self.shellVersion = shellVersion; self.publicKey = publicKey
+  }
+}
+
+/// a < b for x.y.z. Pre-release tags are ignored. Same as `semverLess` in the TypeScript core.
+func semverLess(_ a: String, _ b: String) -> Bool {
+  func parts(_ v: String) -> [Int] { String(v.split(separator: "-", omittingEmptySubsequences: false).first ?? "").split(separator: ".", omittingEmptySubsequences: false).map { Int($0) ?? 0 } }
+  let pa = parts(a), pb = parts(b)
+  for i in 0..<3 {
+    let x = i < pa.count ? pa[i] : 0, y = i < pb.count ? pb[i] : 0
+    if x != y { return x < y }
+  }
+  return false
+}
+
+public enum BundleVerify {
+  public static func sha256Hex(_ data: Data) -> String { SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined() }
+
+  static func signatureOK(body: String, signature: String, publicKey: String) -> Bool {
+    guard let sig = Data(base64Encoded: signature), let raw = Data(base64Encoded: publicKey),
+          let key = try? Curve25519.Signing.PublicKey(rawRepresentation: raw) else { return false }
+    return key.isValidSignature(sig, for: Data(body.utf8))
+  }
+
+  /// Same order as the TypeScript core: signature over the exact body bytes first, then the body, then the minimum shell version, then size and sha-256.
+  /// Returns the release number. Any failure throws and nothing is stored.
+  public static func check(body: String, signature: String, archive: Data, identity: Identity) throws -> Int {
+    guard signatureOK(body: body, signature: signature, publicKey: identity.publicKey) else { throw BundleError.badSignature }
+    guard let p = try? JSONDecoder().decode(Pointer.self, from: Data(body.utf8)),
+          p.kind == "web", (p.platform ?? "android") == "ios", p.app_id == identity.appId,
+          p.shell_major == identity.shellMajor, p.band == identity.band, p.release > 0 else { throw BundleError.badPointer }
+    // Rule 5: minimum shell version.
+    if semverLess(identity.shellVersion, p.min_shell_version) { throw BundleError.shellTooOld }
+    guard archive.count == p.core.size, sha256Hex(archive) == p.core.sha256 else { throw BundleError.badHash }
+    return p.release
+  }
+}

package/ios/Sources/ShipvoBundle/BundleStore.swift

@@ -0,0 +1,120 @@
+import Foundation
+
+/// Bundles under `<root>/bundles/release-<n>/bundle.zip` and release state in `<root>/state.json`.
+/// Same release rules as the TypeScript core (10, 11, 12, 14): three trial boots for a pending release,
+/// more than three boots in a minute reverts the current one, rollback blocks it.
+public final class BundleStore {
+  public static let maxBoots = 3
+  public static let windowMs = 60_000
+
+  struct State: Codable {
+    var current = 0, pending = 0, previous = 0, blocked = 0, pendingBoots = 0
+    var bootTimes: [Int] = []
+    var hashes: [String: String] = [:]
+  }
+
+  private let root: URL
+  private let identity: Identity
+  private let now: () -> Int
+  private var s: State
+
+  public init(root: URL, identity: Identity, now: @escaping () -> Int = { Int(Date().timeIntervalSince1970 * 1000) }) throws {
+    self.root = root; self.identity = identity; self.now = now
+    do { try FileManager.default.createDirectory(at: root.appendingPathComponent("bundles"), withIntermediateDirectories: true) }
+    catch { throw BundleError.badStorage }
+    // A state file that cannot be read starts clean: no release is trusted without a verified record.
+    if let d = try? Data(contentsOf: root.appendingPathComponent("state.json")), let st = try? JSONDecoder().decode(State.self, from: d) { s = st }
+    else { s = State() }
+  }
+
+  public var current: Int { s.current }
+  public var pending: Int { s.pending }
+  public var previous: Int { s.previous }
+  public var blocked: Int { s.blocked }
+
+  public func directory(for release: Int) -> URL { root.appendingPathComponent("bundles/release-\(release)") }
+  public func archiveURL(for release: Int) -> URL { directory(for: release).appendingPathComponent("bundle.zip") }
+
+  /// Verifies, then stores the archive and makes it the pending release. A refused bundle changes nothing.
+  @discardableResult
+  public func stage(body: String, signature: String, archive: Data) throws -> Int {
+    let release: Int
+    do { release = try BundleVerify.check(body: body, signature: signature, archive: archive, identity: identity) }
+    catch BundleError.badHash {
+      // Like the TypeScript core: a release whose size or sha-256 does not match is blocked, so it is not tried again.
+      // The signature was valid, so the release number is trusted.
+      if let r = signedRelease(body: body, signature: signature) { s.blocked = max(s.blocked, r); try save() }
+      throw BundleError.badHash
+    }
+    if release <= max(s.current, s.pending, s.blocked) { throw BundleError.badPointer }
+    let dir = directory(for: release)
+    do {
+      try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+      try archive.write(to: archiveURL(for: release), options: .atomic)
+    } catch { throw BundleError.badStorage }
+    let old = s.pending
+    s.hashes[String(release)] = BundleVerify.sha256Hex(archive)
+    s.pending = release; s.pendingBoots = 0
+    if old != 0 && old != release { drop(old) }
+    try save()
+    return release
+  }
+
+  /// The release number of a pointer whose signature is valid, else nil.
+  private func signedRelease(body: String, signature: String) -> Int? {
+    struct R: Decodable { let release: Int }
+    guard BundleVerify.signatureOK(body: body, signature: signature, publicKey: identity.publicKey),
+          let r = try? JSONDecoder().decode(R.self, from: Data(body.utf8)) else { return nil }
+    return r.release
+  }
+
+  /// The release to serve now, or 0 for the embedded bundle. The stored hash is re-checked before a file is chosen.
+  public func boot() throws -> Int {
+    let t = now()
+    if s.pending != 0 {
+      if s.pendingBoots >= Self.maxBoots {
+        blockAndDrop(s.pending); s.pending = 0; s.pendingBoots = 0
+      } else if intact(s.pending) {
+        s.pendingBoots += 1; try save(); return s.pending
+      } else { blockAndDrop(s.pending); s.pending = 0; s.pendingBoots = 0 }
+    }
+    if s.current != 0 {
+      s.bootTimes = s.bootTimes.filter { t - $0 < Self.windowMs } + [t]
+      if s.bootTimes.count > Self.maxBoots || !intact(s.current) {
+        blockAndDrop(s.current); s.current = s.previous; s.previous = 0; s.bootTimes = []
+      }
+    }
+    try save()
+    return s.current
+  }
+
+  /// Rule 12: the pending release that is running becomes current.
+  public func markHealthy(running: Int) throws {
+    guard s.pending != 0, s.pending == running else { return }
+    if s.previous != 0 { drop(s.previous) }
+    s.previous = s.current; s.current = s.pending; s.pending = 0; s.pendingBoots = 0; s.bootTimes = []
+    try save()
+  }
+
+  /// Rule 14: drop pending, block the current release, go back to the previous one.
+  public func rollback() throws {
+    if s.pending != 0 { drop(s.pending); s.pending = 0; s.pendingBoots = 0 }
+    if s.current != 0 { blockAndDrop(s.current) }
+    s.current = s.previous; s.previous = 0; s.bootTimes = []
+    try save()
+  }
+
+  private func intact(_ release: Int) -> Bool {
+    guard let d = try? Data(contentsOf: archiveURL(for: release)) else { return false }
+    return BundleVerify.sha256Hex(d) == s.hashes[String(release)]
+  }
+  private func blockAndDrop(_ release: Int) { s.blocked = max(s.blocked, release); drop(release) }
+  private func drop(_ release: Int) {
+    s.hashes[String(release)] = nil
+    try? FileManager.default.removeItem(at: directory(for: release))
+  }
+  private func save() throws {
+    do { try JSONEncoder().encode(s).write(to: root.appendingPathComponent("state.json"), options: .atomic) }
+    catch { throw BundleError.badStorage }
+  }
+}

package/ios/Sources/ShipvoCapacitor/ShipvoPlugin.swift

@@ -0,0 +1,116 @@
+import Capacitor
+import Foundation
+import ShipvoBundle
+
+/// The native half of @shipvo/capacitor on iOS. Same plugin name (`Shipvo`), methods and results as the Android plugin
+/// (`ShipvoNativePlugin` in src/native.ts). It backs the core's key-value store and bundle files, and points the web view
+/// at an unpacked bundle. It makes no release decisions: the TypeScript core verifies the signature and hash, and this
+/// class checks the hash it is given again before it unpacks.
+@objc(ShipvoPlugin)
+public class ShipvoPlugin: CAPPlugin, CAPBridgedPlugin {
+  public let identifier = "ShipvoPlugin"
+  public let jsName = "Shipvo"
+  public let pluginMethods: [CAPPluginMethod] = [
+    CAPPluginMethod(name: "kvGet", returnType: CAPPluginReturnPromise),
+    CAPPluginMethod(name: "kvSet", returnType: CAPPluginReturnPromise),
+    CAPPluginMethod(name: "fileWrite", returnType: CAPPluginReturnPromise),
+    CAPPluginMethod(name: "fileRead", returnType: CAPPluginReturnPromise),
+    CAPPluginMethod(name: "fileRemove", returnType: CAPPluginReturnPromise),
+    CAPPluginMethod(name: "fileList", returnType: CAPPluginReturnPromise),
+    CAPPluginMethod(name: "fileClear", returnType: CAPPluginReturnPromise),
+    CAPPluginMethod(name: "serve", returnType: CAPPluginReturnPromise),
+    CAPPluginMethod(name: "status", returnType: CAPPluginReturnPromise),
+  ]
+
+  private let defaults = UserDefaults(suiteName: "shipvo") ?? .standard
+  // Instance state, like the Android plugin: it lasts as long as the bridge, and a new bridge starts on the embedded assets.
+  private var serving: String?
+  private var servingPath: String?
+
+  private lazy var root: URL = {
+    let base = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0].appendingPathComponent("shipvo")
+    try? FileManager.default.createDirectory(at: base.appendingPathComponent("bundles"), withIntermediateDirectories: true)
+    return base
+  }()
+  private var bundles: URL { root.appendingPathComponent("bundles") }
+  private var served: URL { root.appendingPathComponent("served") }
+
+  private func file(_ name: String?) throws -> URL {
+    guard let n = name, n.range(of: "^[A-Za-z0-9._-]{1,128}$", options: .regularExpression) != nil, !n.contains("..") else {
+      throw Unzip.Failure(message: "bad file name")
+    }
+    return bundles.appendingPathComponent(n)
+  }
+
+  @objc func kvGet(_ call: CAPPluginCall) {
+    guard let key = call.getString("key"), let v = defaults.string(forKey: key) else { call.resolve([:]); return }
+    call.resolve(["value": v])
+  }
+
+  @objc func kvSet(_ call: CAPPluginCall) {
+    guard let key = call.getString("key"), let value = call.getString("value") else { call.reject("key and value are required"); return }
+    defaults.set(value, forKey: key)
+    // The boot counter must be on disk before the page runs.
+    defaults.synchronize()
+    call.resolve()
+  }
+
+  @objc func fileWrite(_ call: CAPPluginCall) {
+    do {
+      guard let data = Data(base64Encoded: call.getString("data") ?? "") else { throw Unzip.Failure(message: "bad data") }
+      try data.write(to: try file(call.getString("name")), options: .atomic)
+      call.resolve()
+    } catch { call.reject("could not write: \(error.localizedDescription)") }
+  }
+
+  @objc func fileRead(_ call: CAPPluginCall) {
+    do { call.resolve(["data": try Data(contentsOf: try file(call.getString("name"))).base64EncodedString()]) }
+    catch { call.reject(error.localizedDescription) }
+  }
+
+  @objc func fileRemove(_ call: CAPPluginCall) {
+    do { try? FileManager.default.removeItem(at: try file(call.getString("name"))); call.resolve() }
+    catch { call.reject(error.localizedDescription) }
+  }
+
+  @objc func fileList(_ call: CAPPluginCall) {
+    let names = ((try? FileManager.default.contentsOfDirectory(atPath: bundles.path)) ?? []).filter { !$0.hasSuffix(".tmp") }.sorted()
+    call.resolve(["names": names])
+  }
+
+  @objc func fileClear(_ call: CAPPluginCall) {
+    for n in (try? FileManager.default.contentsOfDirectory(atPath: bundles.path)) ?? [] { try? FileManager.default.removeItem(at: bundles.appendingPathComponent(n)) }
+    try? FileManager.default.removeItem(at: served)
+    serving = nil; servingPath = nil
+    call.resolve()
+  }
+
+  /// Serve a stored bundle. `sha256` is the hash the core verified; it is checked again before unpacking.
+  @objc func serve(_ call: CAPPluginCall) {
+    do {
+      let name = call.getString("name")
+      let zip = try Data(contentsOf: try file(name))
+      guard let want = call.getString("sha256"), BundleVerify.sha256Hex(zip).lowercased() == want.lowercased() else {
+        throw Unzip.Failure(message: "bundle hash does not match")
+      }
+      try? FileManager.default.removeItem(at: served)
+      let target = served.appendingPathComponent(name!)
+      try FileManager.default.createDirectory(at: target, withIntermediateDirectories: true)
+      do {
+        try Unzip.extract(zip, to: target)
+        guard FileManager.default.fileExists(atPath: target.appendingPathComponent("index.html").path) else { throw Unzip.Failure(message: "bundle has no index.html") }
+      } catch { try? FileManager.default.removeItem(at: served); throw error }
+      DispatchQueue.main.async {
+        guard let vc = self.bridge?.viewController as? CAPBridgeViewController else { call.reject("no web view to point at the bundle"); return }
+        vc.setServerBasePath(path: target.path)
+        self.serving = name; self.servingPath = target.path
+        call.resolve()
+      }
+    } catch { call.reject(error.localizedDescription) }
+  }
+
+  /// Which bundle this process is already serving, so the page it loads does not boot again.
+  @objc func status(_ call: CAPPluginCall) {
+    if let s = serving, servingPath != nil { call.resolve(["serving": s]) } else { call.resolve([:]) }
+  }
+}

package/ios/Sources/ShipvoCapacitor/Unzip.swift

@@ -0,0 +1,50 @@
+import Compression
+import Foundation
+
+/// Reads a zip archive held in memory (stored and deflate entries). Entries that would leave the target directory are refused.
+enum Unzip {
+  struct Failure: Error, LocalizedError { let message: String; var errorDescription: String? { message } }
+  static let maxEntryBytes = 256 * 1024 * 1024
+
+  static func extract(_ zip: Data, to target: URL) throws {
+    let b = [UInt8](zip)
+    func u16(_ o: Int) -> Int { Int(b[o]) | Int(b[o + 1]) << 8 }
+    func u32(_ o: Int) -> Int { u16(o) | u16(o + 2) << 16 }
+    guard b.count >= 22 else { throw Failure(message: "bad entry in bundle") }
+    // End of central directory record: the last 22+ bytes, signature 0x06054b50.
+    var eocd = -1
+    var i = b.count - 22
+    while i >= max(0, b.count - 22 - 65_535) { if u32(i) == 0x0605_4b50 { eocd = i; break }; i -= 1 }
+    guard eocd >= 0 else { throw Failure(message: "bad entry in bundle") }
+    let count = u16(eocd + 10)
+    var p = u32(eocd + 16)
+    let root = target.standardizedFileURL.path + "/"
+    let fm = FileManager.default
+    for _ in 0..<count {
+      guard p + 46 <= b.count, u32(p) == 0x0201_4b50 else { throw Failure(message: "bad entry in bundle") }
+      let method = u16(p + 10), csize = u32(p + 20), usize = u32(p + 24)
+      let nlen = u16(p + 28), elen = u16(p + 30), clen = u16(p + 32), local = u32(p + 42)
+      guard p + 46 + nlen <= b.count, local + 30 <= b.count, u32(local) == 0x0403_4b50, usize <= maxEntryBytes else { throw Failure(message: "bad entry in bundle") }
+      let name = String(decoding: b[(p + 46)..<(p + 46 + nlen)], as: UTF8.self)
+      p += 46 + nlen + elen + clen
+      let out = target.appendingPathComponent(name).standardizedFileURL
+      guard out.path.hasPrefix(root) else { throw Failure(message: "bad entry in bundle") }
+      if name.hasSuffix("/") { try fm.createDirectory(at: out, withIntermediateDirectories: true); continue }
+      let start = local + 30 + u16(local + 26) + u16(local + 28)
+      guard start + csize <= b.count else { throw Failure(message: "bad entry in bundle") }
+      let raw = Data(b[start..<(start + csize)])
+      var data: Data
+      if method == 0 { data = raw }
+      else if method == 8 {
+        var dst = [UInt8](repeating: 0, count: max(usize, 1))
+        let n = raw.withUnsafeBytes { src in
+          compression_decode_buffer(&dst, dst.count, src.bindMemory(to: UInt8.self).baseAddress!, raw.count, nil, COMPRESSION_ZLIB)
+        }
+        guard n == usize else { throw Failure(message: "bad entry in bundle") }
+        data = Data(dst.prefix(n))
+      } else { throw Failure(message: "bad entry in bundle") }
+      try fm.createDirectory(at: out.deletingLastPathComponent(), withIntermediateDirectories: true)
+      try data.write(to: out)
+    }
+  }
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@shipvo/capacitor",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Signed over-the-air updates for Capacitor web bundles: the same release decisions and trust model as the Shipvo React Native runtime.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@shipvo/schema": "^0.0.5"
+    "@shipvo/schema": "^0.0.7"
   },
   "devDependencies": {
     "@types/node": "^22.8.0",
@@ -31,6 +31,10 @@
   },
   "files": [
     "dist",
+    "android/build.gradle",
+    "android/src/main",
+    "Package.swift",
+    "ios/Sources",
     "README.md"
   ],
   "publishConfig": {
@@ -40,6 +44,11 @@
   "engines": {
     "node": ">=20"
   },
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "vitest run"