@openlfcp/storage-idb 0.1.4 → 0.2.0-beta.1

package/README.md

@@ -22,9 +22,9 @@ installs must never share sequence counters.
 
 Part of the OpenLFCP TypeScript SDK, which implements the OpenLFCP MVP 0.1
 subset of [LFCP-WIRE-01](https://github.com/openlfcp/spec/blob/main/wire/LFCP-WIRE-01.md)
-at `mvp-0.1-baseline.10`, not every deferred WIRE-01 feature. It does not
+at `mvp-0.1-baseline.9`, not every deferred WIRE-01 feature. It does not
 claim full LFCP-WIRE-01 conformance. This is the MVP 0.1 release
-(`0.1.4`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
+(`0.1.3`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
 
 ## Guarantees
 

package/dist/idb.d.ts

@@ -1,5 +1,33 @@
 import { type ActorSequence, type ControlRecordId, type DataEpoch, type DataUnitId, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
-import { type ActorSequenceReservation, type CommitResult, type ControlConflictRow, type ControlHeadRow, type ControlRecordRow, type DataUnitRow, type DataUnitStatus, type EpochRow, type KeyPackageRow, type LfcpStorage, type OutboundItem, type ProfileCheckpoint, type ResourceRow, type RouteRow, type SeenRecord, type SnapshotRow, type SnapshotSequenceReservation, type StorageWrite, type StoredDataUnit, type SyncStateRow } from "@openlfcp/storage";
+import { type ActorSequenceReservation, type CommitResult, type ControlConflictRow, type ControlHeadRow, type ControlRecordRow, type DataUnitRow, type DataUnitStatus, type EpochRow, type KeyPackageRow, type LfcpStorage, type LocalStateCipher, type LocalStateDiagnostics, type OutboundItem, type ProfileCheckpoint, type ResourceRow, type RouteRow, type SecretStore, type SeenRecord, type SnapshotRow, type SnapshotSequenceReservation, type StorageWrite, type StoredDataUnit, type SyncStateRow } from "@openlfcp/storage";
+/**
+ * LfcpStorage on IndexedDB (LFCP-059): one database per client install,
+ * named by the caller. Portable: browsers, Electron, mobile WebViews.
+ *
+ * - Atomicity: one commit() is one readwrite transaction over every object
+ *   store; the Control Head compare-and-set is read inside it, and any
+ *   failure aborts the whole transaction.
+ * - Durability: every readwrite transaction asks for durability "strict"
+ *   (Chromium's default is relaxed), and a promise resolves only on the
+ *   transaction's complete event.
+ * - Sequences: a reservation reads the counter, checks it against this
+ *   Principal's own stored objects (fail closed, SEQUENCE_REUSE) and writes
+ *   it in one strict transaction, then calls onReserved before returning.
+ * - Exact bytes: signed objects are stored as their exact bytes; other
+ *   fields are indexes. Values are structured clones, so nothing returned
+ *   aliases a stored buffer or a caller's.
+ *
+ * A transaction only awaits IndexedDB requests (never other promises), so it
+ * cannot auto-commit half way.
+ */
+/**
+ * The database version (LFCP-02-029). 1: the LFCP-059 stores (0.1.x).
+ * 2: the same stores; checkpoints may be sealed (LFCP-02-098) and 0.2
+ * records live in local marks. Nothing is converted from 1 to 2: the
+ * version only makes a 0.1.x client, which opens version 1, refuse the
+ * database (VersionError) instead of reading sealed rows as plaintext.
+ */
+export declare const IDB_VERSION = 2;
 /** A reservation that is durable and about to be returned. */
 export interface ReservedSequence {
     readonly kind: "actor" | "snapshot";
@@ -16,12 +44,34 @@ export interface IdbStorageOptions {
      * fails and its value is abandoned, never reissued.
      */
     readonly onReserved?: (reserved: ReservedSequence) => void;
+    /**
+     * Local state encrypted at rest (LFCP-02-098): the SecretStore that holds
+     * the install's local state key, and the cipher (`localStateCipher` of
+     * @openlfcp/crypto). Profile checkpoints are then stored as `lse1`
+     * envelopes. A database that seals its local state cannot be opened
+     * without it.
+     */
+    readonly localState?: IdbLocalState;
+}
+export interface IdbLocalState {
+    readonly secrets: SecretStore;
+    readonly cipher: LocalStateCipher;
+    /** The clock of the diagnostics' events (default: the system clock). */
+    readonly now?: () => Date;
 }
 export declare class IdbLfcpStorage implements LfcpStorage {
     #private;
     private constructor();
     /** Opens (creating or upgrading) the database `name`. */
     static open(name: string, options?: IdbStorageOptions): Promise<IdbLfcpStorage>;
+    /**
+     * Rotates the local state key (LFCP-02-098 §8): writes the next
+     * generation's key, seals every checkpoint again, then removes the old
+     * key. Resumed on the next open after a crash.
+     */
+    rotateLocalStateKey(): Promise<void>;
+    /** The local state encryption status, or null when the database was opened without it. */
+    localStateDiagnostics(): Promise<LocalStateDiagnostics | null>;
     /** Closes the connection; later calls fail. */
     close(): void;
     commit(writes: readonly StorageWrite[]): Promise<CommitResult>;

package/dist/idb.js

@@ -1,6 +1,6 @@
 /// <reference lib="dom" />
 import { bytesEqual, LfcpError, toHex, UINT64_MAX, } from "@openlfcp/core";
-import { nextActorSequence, } from "@openlfcp/storage";
+import { LocalStateKeyring, nextActorSequence, reseal, } from "@openlfcp/storage";
 /**
  * LfcpStorage on IndexedDB (LFCP-059): one database per client install,
  * named by the caller. Portable: browsers, Electron, mobile WebViews.
@@ -21,7 +21,14 @@ import { nextActorSequence, } from "@openlfcp/storage";
  * A transaction only awaits IndexedDB requests (never other promises), so it
  * cannot auto-commit half way.
  */
-const VERSION = 1;
+/**
+ * The database version (LFCP-02-029). 1: the LFCP-059 stores (0.1.x).
+ * 2: the same stores; checkpoints may be sealed (LFCP-02-098) and 0.2
+ * records live in local marks. Nothing is converted from 1 to 2: the
+ * version only makes a 0.1.x client, which opens version 1, refuse the
+ * database (VersionError) instead of reading sealed rows as plaintext.
+ */
+export const IDB_VERSION = 2;
 const STORES = [
     "records",
     "heads",
@@ -38,6 +45,9 @@ const STORES = [
     "counters",
     "meta",
 ];
+/** The meta key of the local state encryption metadata; the store name of checkpoints in their AAD. */
+const LOCAL_STATE = "local-state";
+const CHECKPOINTS = "checkpoints";
 const hex = toHex;
 /** uint64 as a fixed-width decimal string, so key order is numeric order. */
 const pad = (n) => n.toString().padStart(20, "0");
@@ -94,7 +104,11 @@ class HeadMismatch {
         this.result = result;
     }
 }
-function upgrade(db) {
+/** Brings a database from version `from` to IDB_VERSION, in the version change transaction. */
+function upgrade(db, from) {
+    // 1 → 2 adds no store: the stores of version 1 are kept as they are.
+    if (from >= 1)
+        return;
     const plain = (name) => db.createObjectStore(name);
     db.createObjectStore("records").createIndex("r", "r");
     plain("heads");
@@ -118,23 +132,134 @@ function upgrade(db) {
 export class IdbLfcpStorage {
     #db;
     #onReserved;
+    #localState;
+    #keyring = null;
     constructor(db, options) {
         this.#db = db;
         this.#onReserved = options.onReserved;
+        this.#localState = options.localState;
     }
     /** Opens (creating or upgrading) the database `name`. */
     static async open(name, options = {}) {
         const factory = options.indexedDB ?? globalThis.indexedDB;
         if (factory === undefined)
             throw new LfcpError("UNSUPPORTED_VALUE", "IndexedDB is not available in this runtime");
-        const open = factory.open(name, VERSION);
-        open.onupgradeneeded = () => upgrade(open.result);
+        const open = factory.open(name, IDB_VERSION);
+        open.onupgradeneeded = (event) => upgrade(open.result, event.oldVersion);
         const db = await new Promise((resolve, reject) => {
             open.onsuccess = () => resolve(open.result);
-            open.onerror = () => reject(open.error);
+            open.onerror = () => reject(open.error?.name === "VersionError"
+                ? new LfcpError("UNSUPPORTED_VALUE", `IndexedDB ${name} was written by a newer client than this one (version ${IDB_VERSION}); it is left as it is`)
+                : open.error);
             open.onblocked = () => reject(new LfcpError("UNSUPPORTED_VALUE", `IndexedDB ${name} is blocked by another connection`));
         });
-        return new IdbLfcpStorage(db, options);
+        const storage = new IdbLfcpStorage(db, options);
+        try {
+            await storage.#startLocalState();
+        }
+        catch (e) {
+            db.close();
+            throw e;
+        }
+        return storage;
+    }
+    #now() {
+        return (this.#localState?.now?.() ?? new Date()).toISOString();
+    }
+    /**
+     * LFCP-02-098: with `localState`, prepares the keyring (the key goes to the
+     * SecretStore before the metadata that names it), then migrates, or
+     * continues a half-done migration or rotation. Without it, a database that
+     * seals its local state is refused.
+     */
+    async #startLocalState() {
+        const stored = (await this.meta.get(LOCAL_STATE));
+        const local = this.#localState;
+        if (local === undefined) {
+            if (stored !== undefined)
+                throw new LfcpError("UNSUPPORTED_VALUE", "this database seals its local state: open it with the localState option");
+            return;
+        }
+        const keyring = await LocalStateKeyring.prepare(local.cipher, local.secrets, stored, this.#now());
+        if (JSON.stringify(keyring.meta) !== JSON.stringify(stored))
+            await this.meta.put(LOCAL_STATE, keyring.meta);
+        this.#keyring = keyring;
+        if (keyring.meta.phase !== "ready")
+            await this.#finishPhase();
+    }
+    /**
+     * Seals every checkpoint the current phase needs, in resumable batches,
+     * then records the phase as ready and removes a key a rotation retired. A
+     * batch writes a row only if it still holds the bytes it read, so a
+     * checkpoint committed meanwhile is never overwritten.
+     */
+    async #finishPhase() {
+        const keyring = this.#keyring;
+        const read = new Map();
+        const scan = (after, limit) => this.#tx(["checkpoints"], "readonly", async (tx) => {
+            const range = after === null ? undefined : IDBKeyRange.lowerBound(after, true);
+            const values = (await req(tx.objectStore("checkpoints").getAll(range, limit)));
+            return values.map((c) => {
+                const key = hex(c.resourceId);
+                read.set(key, c.state);
+                return { store: CHECKPOINTS, key, bytes: Uint8Array.from(c.state) };
+            });
+        });
+        const write = (rows) => this.#tx(["checkpoints"], "readwrite", async (tx) => {
+            const store = tx.objectStore("checkpoints");
+            for (const r of rows) {
+                const now = (await req(store.get(r.key)));
+                const before = read.get(r.key);
+                if (now === undefined || before === undefined || !bytesEqual(now.state, before))
+                    continue;
+                await req(store.put({ ...now, state: r.bytes }, r.key));
+            }
+        });
+        await reseal(keyring, scan, write);
+        const retired = keyring.retired;
+        const finished = keyring.finished(this.#now());
+        await this.meta.put(LOCAL_STATE, finished.meta);
+        this.#keyring = finished;
+        // The old key goes last: a crash before this line leaves it, harmlessly.
+        if (retired !== null)
+            await this.#localState.secrets.delete(retired);
+    }
+    /**
+     * Rotates the local state key (LFCP-02-098 §8): writes the next
+     * generation's key, seals every checkpoint again, then removes the old
+     * key. Resumed on the next open after a crash.
+     */
+    async rotateLocalStateKey() {
+        if (this.#keyring === null || this.#localState === undefined)
+            throw new LfcpError("UNSUPPORTED_VALUE", "this database was not opened with localState");
+        this.#keyring = await this.#keyring.rotate(this.#localState.secrets, this.#now());
+        await this.meta.put(LOCAL_STATE, this.#keyring.meta);
+        await this.#finishPhase();
+    }
+    /** The local state encryption status, or null when the database was opened without it. */
+    async localStateDiagnostics() {
+        const keyring = this.#keyring;
+        if (keyring === null)
+            return null;
+        const values = await this.#tx(["checkpoints"], "readonly", async (tx) => (await req(tx.objectStore("checkpoints").getAll())));
+        const rows = { sealed: 0, plaintext: 0, unreadable: 0 };
+        for (const c of values) {
+            const opened = keyring.open(CHECKPOINTS, hex(c.resourceId), c.state);
+            if (opened.kind === "plain")
+                rows.plaintext++;
+            else if (opened.kind === "opened")
+                rows.sealed++;
+            else
+                rows.unreadable++;
+        }
+        return Object.freeze({
+            scheme: keyring.meta.scheme,
+            generation: keyring.meta.generation,
+            keyPresent: keyring.keyPresent,
+            phase: keyring.meta.phase,
+            rows: Object.freeze(rows),
+            lastEvent: keyring.meta.lastEvent,
+        });
     }
     /** Closes the connection; later calls fail. */
     close() {
@@ -342,9 +467,14 @@ export class IdbLfcpStorage {
             case "dequeue":
                 await req(s("outbound").delete(hex(w.itemId)));
                 return;
-            case "put-profile-checkpoint":
-                await req(s("checkpoints").put(w.checkpoint, hex(w.checkpoint.resourceId)));
+            case "put-profile-checkpoint": {
+                const key = hex(w.checkpoint.resourceId);
+                const state = this.#keyring === null
+                    ? w.checkpoint.state
+                    : this.#keyring.seal(CHECKPOINTS, key, w.checkpoint.state);
+                await req(s("checkpoints").put({ ...w.checkpoint, state }, key));
                 return;
+            }
             case "put-sync-state":
                 await req(s("syncStates").put(w.row, hex(w.row.resourceId)));
                 return;
@@ -517,7 +647,16 @@ export class IdbLfcpStorage {
         get: (id) => this.#get("outbound", hex(id)).then((v) => v?.row),
     };
     profileState = {
-        checkpoint: (resource) => this.#get("checkpoints", hex(resource)),
+        checkpoint: async (resource) => {
+            const row = await this.#get("checkpoints", hex(resource));
+            if (row === undefined || this.#keyring === null)
+                return row;
+            const opened = this.#keyring.open(CHECKPOINTS, hex(resource), row.state);
+            // Sealed under a lost key: absent, rebuilt from the stored units.
+            if (opened.kind === "unreadable")
+                return undefined;
+            return Object.freeze({ ...row, state: opened.bytes });
+        },
     };
     syncState = {
         get: (resource) => this.#get("syncStates", hex(resource)),

package/dist/index.d.ts

@@ -5,5 +5,5 @@
  * SecretStore.
  */
 export declare const PACKAGE = "@openlfcp/storage-idb";
-export { IdbLfcpStorage, type IdbStorageOptions, type ReservedSequence } from "./idb.js";
+export { IDB_VERSION, IdbLfcpStorage, type IdbLocalState, type IdbStorageOptions, type ReservedSequence, } from "./idb.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -5,5 +5,5 @@
  * SecretStore.
  */
 export const PACKAGE = "@openlfcp/storage-idb";
-export { IdbLfcpStorage } from "./idb.js";
+export { IDB_VERSION, IdbLfcpStorage, } from "./idb.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/storage-idb",
-  "version": "0.1.4",
+  "version": "0.2.0-beta.1",
   "description": "Durable portable storage for LFCP clients on IndexedDB (browsers, Electron, mobile WebViews).",
   "keywords": [
     "openlfcp",
@@ -39,11 +39,11 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "latest"
+    "tag": "beta"
   },
   "dependencies": {
-    "@openlfcp/core": "^0.1.4",
-    "@openlfcp/storage": "^0.1.4"
+    "@openlfcp/core": "^0.2.0-beta.1",
+    "@openlfcp/storage": "^0.2.0-beta.1"
   },
   "devDependencies": {
     "fake-indexeddb": "6.2.5"