@shipvo/capacitor 0.0.1 → 0.0.2

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/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@shipvo/capacitor",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "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.6"
   },
   "devDependencies": {
     "@types/node": "^22.8.0",
@@ -31,6 +31,8 @@
   },
   "files": [
     "dist",
+    "android/build.gradle",
+    "android/src/main",
     "README.md"
   ],
   "publishConfig": {