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

package/README.md

@@ -18,9 +18,9 @@ on it. The Obsidian plugin does not use it: Obsidian has its own adapter
 
 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.
 
 ## SQLite
 

package/dist/index.d.ts

@@ -7,5 +7,5 @@
 export declare const PACKAGE = "@openlfcp/storage-node";
 export { MIGRATIONS, migrate, SCHEMA_VERSION, schemaVersion } from "./schema.js";
 export { FileSecretStore } from "./secrets.js";
-export { SqliteLfcpStorage, type SqliteStorageOptions } from "./sqlite.js";
+export { SqliteLfcpStorage, type SqliteLocalState, type SqliteStorageOptions, } from "./sqlite.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -7,5 +7,5 @@
 export const PACKAGE = "@openlfcp/storage-node";
 export { MIGRATIONS, migrate, SCHEMA_VERSION, schemaVersion } from "./schema.js";
 export { FileSecretStore } from "./secrets.js";
-export { SqliteLfcpStorage } from "./sqlite.js";
+export { SqliteLfcpStorage, } from "./sqlite.js";
 //# sourceMappingURL=index.js.map

package/dist/schema.d.ts

@@ -2,7 +2,8 @@ import type Database from "better-sqlite3";
 /**
  * The SQLite schema and its migrations. Version 1 is the LFCP-034 storage
  * model; version 2 adds outbound retry state and sync state (LFCP-036);
- * version 3 adds local marks (the crash-loop breaker's apply markers).
+ * version 3 adds local marks (the crash-loop breaker's apply markers);
+ * version 4 adds the local state encryption metadata (LFCP-02-098).
  * A database at a newer version than this code knows is refused:
  * it is never downgraded or "repaired".
  *

package/dist/schema.js

@@ -2,7 +2,8 @@ import { LfcpError } from "@openlfcp/core";
 /**
  * The SQLite schema and its migrations. Version 1 is the LFCP-034 storage
  * model; version 2 adds outbound retry state and sync state (LFCP-036);
- * version 3 adds local marks (the crash-loop breaker's apply markers).
+ * version 3 adds local marks (the crash-loop breaker's apply markers);
+ * version 4 adds the local state encryption metadata (LFCP-02-098).
  * A database at a newer version than this code knows is refused:
  * it is never downgraded or "repaired".
  *
@@ -156,6 +157,17 @@ CREATE TABLE local_marks (
   key    TEXT PRIMARY KEY,
   value  TEXT NOT NULL
 ) WITHOUT ROWID;
+`,
+    ],
+    [
+        // LFCP-02-098: the local state encryption metadata (scheme, install ID,
+        // generation, phase); never key bytes.
+        4,
+        `
+CREATE TABLE local_state (
+  id    INTEGER PRIMARY KEY CHECK (id = 1),
+  meta  TEXT NOT NULL
+);
 `,
     ],
 ];

package/dist/sqlite.d.ts

@@ -1,8 +1,19 @@
-import { type ActorSequenceReservation, type CommitResult, type ControlReader, type DataUnitReader, type KeyPackageReader, type LfcpStorage, type LocalMarkReader, type OutboundReader, type ProfileStateReader, type ResourceReader, type SnapshotReader, type SnapshotSequenceReservation, type StorageWrite, type SyncStateReader } from "@openlfcp/storage";
+import { type ActorSequenceReservation, type CommitResult, type ControlReader, type DataUnitReader, type KeyPackageReader, type LfcpStorage, type LocalMarkReader, type LocalStateCipher, type LocalStateDiagnostics, type OutboundReader, type ProfileStateReader, type ResourceReader, type SecretStore, type SnapshotReader, type SnapshotSequenceReservation, type StorageWrite, type SyncStateReader } from "@openlfcp/storage";
 export interface SqliteStorageOptions {
     /** Milliseconds to wait for another process's write lock (default 5000). */
     readonly busyTimeoutMs?: number;
 }
+/**
+ * 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).
+ */
+export interface SqliteLocalState {
+    readonly secrets: SecretStore;
+    readonly cipher: LocalStateCipher;
+    /** The clock of the diagnostics' events (default: the system clock). */
+    readonly now?: () => Date;
+}
 export declare class SqliteLfcpStorage implements LfcpStorage {
     #private;
     /** The schema version after migration. */
@@ -13,6 +24,25 @@ export declare class SqliteLfcpStorage implements LfcpStorage {
      * current schema and sets the durability pragmas.
      */
     static open(path: string, options?: SqliteStorageOptions): SqliteLfcpStorage;
+    /**
+     * Opens the database at `path` with its local state sealed at rest
+     * (LFCP-02-098): profile checkpoints are stored as `lse1` envelopes under
+     * the install's local state key, which lives only in `localState.secrets`.
+     * A database from before the scheme is migrated, in resumable batches; a
+     * half-done migration or rotation continues. A lost key is no failure: the
+     * next generation starts, and checkpoints sealed under the lost key read
+     * as absent until they are rewritten (the client rebuilds them from the
+     * stored units).
+     */
+    static openSealed(path: string, localState: SqliteLocalState, options?: SqliteStorageOptions): Promise<SqliteLfcpStorage>;
+    /**
+     * 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(): LocalStateDiagnostics | null;
     close(): void;
     commit(writes: readonly StorageWrite[]): Promise<CommitResult>;
     readonly control: ControlReader;

package/dist/sqlite.js

@@ -1,5 +1,5 @@
 import { actorSequence, bytesEqual, dataEpoch, LfcpError, toHex, UINT64_MAX, } from "@openlfcp/core";
-import { nextActorSequence, } from "@openlfcp/storage";
+import { LocalStateKeyring, nextActorSequence, reseal, } from "@openlfcp/storage";
 import Database from "better-sqlite3";
 import { migrate } from "./schema.js";
 /** uint64 as 20-digit zero-padded TEXT (sorts numerically, never overflows). */
@@ -118,10 +118,14 @@ const checkpointRow = (r) => ({
         ref,
     })),
 });
+/** The store name and primary key of a checkpoint in its AAD. */
+const CHECKPOINTS = "checkpoints";
 export class SqliteLfcpStorage {
     #db;
     /** The schema version after migration. */
     schemaVersion;
+    #keyring = null;
+    #localState = null;
     constructor(db, version) {
         this.#db = db;
         this.schemaVersion = version;
@@ -131,6 +135,46 @@ export class SqliteLfcpStorage {
      * current schema and sets the durability pragmas.
      */
     static open(path, options = {}) {
+        const storage = SqliteLfcpStorage.#open(path, options);
+        if (storage.#storedMeta() !== undefined) {
+            storage.close();
+            throw new LfcpError("UNSUPPORTED_VALUE", "this database seals its local state: open it with SqliteLfcpStorage.openSealed");
+        }
+        return storage;
+    }
+    /**
+     * Opens the database at `path` with its local state sealed at rest
+     * (LFCP-02-098): profile checkpoints are stored as `lse1` envelopes under
+     * the install's local state key, which lives only in `localState.secrets`.
+     * A database from before the scheme is migrated, in resumable batches; a
+     * half-done migration or rotation continues. A lost key is no failure: the
+     * next generation starts, and checkpoints sealed under the lost key read
+     * as absent until they are rewritten (the client rebuilds them from the
+     * stored units).
+     */
+    static async openSealed(path, localState, options = {}) {
+        const storage = SqliteLfcpStorage.#open(path, options);
+        try {
+            // Freed pages are overwritten with zeros, so an old row's bytes do not
+            // linger in the file once replaced.
+            storage.#db.pragma("secure_delete = ON");
+            storage.#localState = localState;
+            const stored = storage.#storedMeta();
+            const keyring = await LocalStateKeyring.prepare(localState.cipher, localState.secrets, stored, storage.#now());
+            // The key is in the SecretStore; now the metadata that names it.
+            if (JSON.stringify(keyring.meta) !== JSON.stringify(stored))
+                storage.#writeMeta(keyring.meta);
+            storage.#keyring = keyring;
+            if (keyring.meta.phase !== "ready")
+                await storage.#finishPhase();
+            return storage;
+        }
+        catch (e) {
+            storage.close();
+            throw e;
+        }
+    }
+    static #open(path, options) {
         const db = new Database(path);
         try {
             db.pragma("journal_mode = WAL");
@@ -144,6 +188,94 @@ export class SqliteLfcpStorage {
             throw e;
         }
     }
+    #now() {
+        return (this.#localState?.now?.() ?? new Date()).toISOString();
+    }
+    #storedMeta() {
+        const row = this.#get("SELECT meta FROM local_state WHERE id = 1");
+        return row === undefined ? undefined : JSON.parse(row.meta);
+    }
+    #writeMeta(meta) {
+        this.#db
+            .prepare("INSERT INTO local_state (id, meta) VALUES (1, ?) ON CONFLICT (id) DO UPDATE SET meta = excluded.meta")
+            .run(JSON.stringify(meta));
+    }
+    /**
+     * 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 is still the bytes it read, so a
+     * checkpoint committed meanwhile is never overwritten.
+     */
+    async #finishPhase() {
+        const keyring = this.#keyring;
+        const read = new Map();
+        const scan = async (after, limit) => {
+            const rows = after === null
+                ? this.#all("SELECT resource_id, state FROM profile_checkpoints ORDER BY resource_id LIMIT ?", limit)
+                : this.#all("SELECT resource_id, state FROM profile_checkpoints WHERE resource_id > ? ORDER BY resource_id LIMIT ?", Buffer.from(after, "hex"), limit);
+            return rows.map((r) => {
+                const key = toHex(bytes(r.resource_id));
+                read.set(key, r.state);
+                return { store: CHECKPOINTS, key, bytes: bytes(r.state) };
+            });
+        };
+        const write = (rows) => this.#tx(() => {
+            const update = this.#db.prepare("UPDATE profile_checkpoints SET state = ? WHERE resource_id = ? AND state = ?");
+            for (const r of rows)
+                update.run(blob(r.bytes), Buffer.from(r.key, "hex"), read.get(r.key));
+        });
+        await reseal(keyring, scan, write);
+        const retired = keyring.retired;
+        const finished = keyring.finished(this.#now());
+        this.#writeMeta(finished.meta);
+        this.#keyring = finished;
+        if (keyring.meta.phase === "migrating") {
+            // Plaintext from before the scheme may linger in pages freed before
+            // secure_delete and in the WAL: rewrite the file and truncate the WAL.
+            this.#db.pragma("wal_checkpoint(TRUNCATE)");
+            this.#db.exec("VACUUM");
+            this.#db.pragma("wal_checkpoint(TRUNCATE)");
+        }
+        // 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 === null)
+            throw new LfcpError("UNSUPPORTED_VALUE", "this database was not opened with openSealed");
+        this.#keyring = await this.#keyring.rotate(this.#localState.secrets, this.#now());
+        this.#writeMeta(this.#keyring.meta);
+        await this.#finishPhase();
+    }
+    /** The local state encryption status, or null when the database was opened without it. */
+    localStateDiagnostics() {
+        const keyring = this.#keyring;
+        if (keyring === null)
+            return null;
+        const rows = { sealed: 0, plaintext: 0, unreadable: 0 };
+        for (const r of this.#all("SELECT resource_id, state FROM profile_checkpoints")) {
+            const opened = keyring.open(CHECKPOINTS, toHex(bytes(r.resource_id)), bytes(r.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,
+        });
+    }
     close() {
         if (this.#db.open)
             this.#db.close();
@@ -376,7 +508,9 @@ export class SqliteLfcpStorage {
             case "put-profile-checkpoint": {
                 const c = w.checkpoint;
                 db.prepare(`INSERT INTO profile_checkpoints (resource_id, data_profile, state, actor_seq, units) VALUES (?, ?, ?, ?, ?)
-           ON CONFLICT (resource_id) DO UPDATE SET data_profile = excluded.data_profile, state = excluded.state, actor_seq = excluded.actor_seq, units = excluded.units`).run(blob(c.resourceId), c.dataProfile, blob(c.state), c.actorSeq, JSON.stringify(c.units.map((u) => [toHex(u.unitId), u.ref])));
+           ON CONFLICT (resource_id) DO UPDATE SET data_profile = excluded.data_profile, state = excluded.state, actor_seq = excluded.actor_seq, units = excluded.units`).run(blob(c.resourceId), c.dataProfile, blob(this.#keyring === null
+                    ? c.state
+                    : this.#keyring.seal(CHECKPOINTS, toHex(c.resourceId), c.state)), c.actorSeq, JSON.stringify(c.units.map((u) => [toHex(u.unitId), u.ref])));
                 return;
             }
         }
@@ -482,7 +616,16 @@ export class SqliteLfcpStorage {
     profileState = {
         checkpoint: (res) => this.#read(() => {
             const r = this.#get("SELECT * FROM profile_checkpoints WHERE resource_id = ?", blob(res));
-            return r === undefined ? undefined : checkpointRow(r);
+            if (r === undefined)
+                return undefined;
+            const row = checkpointRow(r);
+            if (this.#keyring === null)
+                return row;
+            const opened = this.#keyring.open(CHECKPOINTS, toHex(res), row.state);
+            // Sealed under a lost key: absent, rebuilt from the stored units.
+            if (opened.kind === "unreadable")
+                return undefined;
+            return { ...row, state: opened.bytes };
         }),
     };
     syncState = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/storage-node",
-  "version": "0.1.4",
+  "version": "0.2.0-beta.1",
   "description": "Durable Node.js storage for LFCP clients: SQLite (better-sqlite3) and a file secret store. Node only.",
   "keywords": [
     "openlfcp",
@@ -39,12 +39,12 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "latest"
+    "tag": "beta"
   },
   "dependencies": {
     "better-sqlite3": "13.0.3",
-    "@openlfcp/storage": "^0.1.4",
-    "@openlfcp/core": "^0.1.4"
+    "@openlfcp/core": "^0.2.0-beta.1",
+    "@openlfcp/storage": "^0.2.0-beta.1"
   },
   "devDependencies": {
     "@types/better-sqlite3": "9.6.0",