@openlfcp/storage 0.1.4 → 0.2.0-beta.1

package/README.md

@@ -12,9 +12,9 @@ ESM only; Node.js 24 or later (browsers and Electron for every package except `@
 
 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.
 
 ## Links
 

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 /** Name of this package. */
 export declare const PACKAGE = "@openlfcp/storage";
+export { LOCAL_STATE_SCHEME, type LocalStateCipher, type LocalStateDiagnostics, type LocalStateEvent, LocalStateKeyring, type LocalStateMeta, localStateAad, localStateKeyRef, type OpenedLocal, type ResealRow, reseal, } from "./local-state.js";
 export { InMemoryLfcpStorage } from "./memory.js";
 export { dekSecretRef, InMemorySecretStore, isSecretRef, principalKeySecretRef, type SecretKind, type SecretRef, type SecretStore, secretRef, } from "./secrets.js";
 export { type ActorSequenceReservation, InMemoryActorSequenceReservation, nextActorSequence, SequenceReuseGuard, } from "./sequence.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 /** Name of this package. */
 export const PACKAGE = "@openlfcp/storage";
+export { LOCAL_STATE_SCHEME, LocalStateKeyring, localStateAad, localStateKeyRef, reseal, } from "./local-state.js";
 export { InMemoryLfcpStorage } from "./memory.js";
 export { dekSecretRef, InMemorySecretStore, isSecretRef, principalKeySecretRef, secretRef, } from "./secrets.js";
 export { InMemoryActorSequenceReservation, nextActorSequence, SequenceReuseGuard, } from "./sequence.js";

package/dist/local-state.d.ts

@@ -0,0 +1,145 @@
+import { type SecretRef, type SecretStore } from "./secrets.js";
+/**
+ * Local state encrypted at rest (LFCP-02-098; .github
+ * docs/devel/design/local-state-encryption.md).
+ *
+ * A storage adapter opened with a SecretStore seals the rows that hold
+ * profile text (ProfileCheckpoint.state) with the install's local state key
+ * before they reach the disk, as `lse1` envelopes. The
+ * key lives only in the SecretStore, under
+ * `lfcp-secret:local-state-key:<install id>.<generation>`; the adapter's
+ * metadata records the scheme, the install ID and the current generation,
+ * never key bytes.
+ *
+ * The keyring decides what to do when an adapter opens:
+ * - a new install, or a database from before the scheme: create the key
+ *   (secret first, then the metadata), then seal every plaintext row
+ *   (`migrating`);
+ * - a migration or rotation left half done: continue it;
+ * - a missing key: never a crash and never a silent deletion. The next
+ *   generation's key is created, rows sealed under the lost one read as
+ *   unreadable (a checkpoint as absent: the profile state is rebuilt from
+ *   the stored units), and they are replaced as they are rewritten.
+ * Rotation is explicit: the next generation's key is written, every row is
+ * sealed again, then the old key is removed.
+ *
+ * This package does no cryptography (it may not depend on @openlfcp/crypto,
+ * LFCP-014): the application passes the cipher, `localStateCipher` of
+ * @openlfcp/crypto, which keeps the key bytes inside that package.
+ */
+/**
+ * The envelope cipher: `localStateCipher` of @openlfcp/crypto
+ * (XChaCha20-Poly1305, `lse1` envelopes). Keys are opaque here.
+ */
+export interface LocalStateCipher<K = unknown> {
+    generateKey(): K;
+    importKey(bytes: Uint8Array): K;
+    /** A copy of the key bytes, for the SecretStore only. */
+    exportKey(key: K): Uint8Array;
+    seal(key: K, generation: number, aad: Uint8Array, plaintext: Uint8Array): Uint8Array;
+    /** Throws on a wrong key, AAD or generation, or tampered bytes. */
+    open(key: K, aad: Uint8Array, envelope: Uint8Array): Uint8Array;
+    isSealed(bytes: Uint8Array): boolean;
+    generationOf(bytes: Uint8Array): number | undefined;
+}
+/** The scheme an adapter records in its metadata. */
+export declare const LOCAL_STATE_SCHEME = "lse-v1";
+/** Something that happened to the local state key, for diagnostics. */
+export interface LocalStateEvent {
+    readonly kind: "created" | "migrated" | "key-lost" | "rotated";
+    /** RFC 3339. */
+    readonly at: string;
+}
+/** The adapter's record of local encryption. It never holds key bytes. */
+export interface LocalStateMeta {
+    readonly scheme: typeof LOCAL_STATE_SCHEME;
+    /** A random public name of this install, in every row's AAD and key reference. */
+    readonly installId: string;
+    /** The generation rows are sealed with. */
+    readonly generation: number;
+    /** `ready`, or a migration or rotation to continue on the next open. */
+    readonly phase: "migrating" | "rotating" | "ready";
+    /** While rotating: the generation being replaced. */
+    readonly previous: number | null;
+    readonly lastEvent: LocalStateEvent | null;
+}
+/** What an adapter's `localStateDiagnostics` reports: never key bytes, envelopes or plaintext. */
+export interface LocalStateDiagnostics {
+    readonly scheme: string;
+    readonly generation: number;
+    readonly keyPresent: boolean;
+    readonly phase: LocalStateMeta["phase"];
+    /** Rows sealed under a held key, in plaintext, and sealed under a lost key. */
+    readonly rows: {
+        readonly sealed: number;
+        readonly plaintext: number;
+        readonly unreadable: number;
+    };
+    readonly lastEvent: LocalStateEvent | null;
+}
+/** A row's bytes as read: plaintext from before the scheme, opened, or unreadable. */
+export type OpenedLocal = {
+    readonly kind: "plain";
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: "opened";
+    readonly bytes: Uint8Array;
+    readonly generation: number;
+} | {
+    readonly kind: "unreadable";
+    readonly reason: "missing-key" | "authentication";
+};
+/** The SecretStore reference of an install's key of one generation. */
+export declare const localStateKeyRef: (installId: string, generation: number) => SecretRef;
+/**
+ * The AAD of a row: the label, the install ID, the store and the row's
+ * primary key, each length-prefixed, so a row cannot be swapped with
+ * another one or moved to another install.
+ */
+export declare function localStateAad(installId: string, store: string, key: string): Uint8Array;
+/** An install's local state keys and metadata, held by an open adapter. */
+export declare class LocalStateKeyring {
+    #private;
+    readonly meta: LocalStateMeta;
+    private constructor();
+    /**
+     * The keyring for an adapter opening with `stored` metadata (undefined: a
+     * new install or a database from before the scheme). Writes any new key
+     * to `secrets` before it returns; the caller then records `meta` and runs
+     * `reseal` while `meta.phase` is not `ready`.
+     */
+    static prepare(cipher: LocalStateCipher, secrets: SecretStore, stored: LocalStateMeta | undefined, now: string): Promise<LocalStateKeyring>;
+    /**
+     * Begins a rotation: writes the next generation's key to `secrets` and
+     * returns the keyring to record (phase `rotating`) before `reseal` runs.
+     */
+    rotate(secrets: SecretStore, now: string): Promise<LocalStateKeyring>;
+    /** The keyring once `reseal` has finished: phase `ready`. */
+    finished(now: string): LocalStateKeyring;
+    /** Whether the current generation's key is held. */
+    get keyPresent(): boolean;
+    /** The envelope of a row's `plaintext`, under the current key. */
+    seal(store: string, key: string, plaintext: Uint8Array): Uint8Array;
+    /** A row's bytes as stored: plaintext, opened, or unreadable (never a throw). */
+    open(store: string, key: string, bytes: Uint8Array): OpenedLocal;
+    /** Whether a stored row needs sealing again: plaintext, or sealed under a readable older generation. */
+    needsReseal(bytes: Uint8Array): boolean;
+    /** The SecretStore reference of the key a finished rotation replaced, to remove. */
+    get retired(): SecretRef | null;
+    toJSON(): string;
+}
+/** One row to seal again, as an adapter scans it. */
+export interface ResealRow {
+    readonly store: string;
+    readonly key: string;
+    readonly bytes: Uint8Array;
+}
+/**
+ * Seals every row that needs it, in batches: `scan` returns up to `limit`
+ * rows after `after` (null: from the start) in key order; `write` stores the
+ * sealed rows atomically. Resumable: a row already sealed under the current
+ * generation is skipped, so a crash between batches continues on the next
+ * open. A row whose key is lost is left as it is.
+ */
+export declare function reseal(keyring: LocalStateKeyring, scan: (after: string | null, limit: number) => Promise<readonly ResealRow[]>, write: (rows: readonly ResealRow[]) => Promise<void>, limit?: number): Promise<number>;
+//# sourceMappingURL=local-state.d.ts.map

package/dist/local-state.js

@@ -0,0 +1,214 @@
+import { LfcpError, toHex } from "@openlfcp/core";
+import { secretRef } from "./secrets.js";
+/** The scheme an adapter records in its metadata. */
+export const LOCAL_STATE_SCHEME = "lse-v1";
+/** The SecretStore reference of an install's key of one generation. */
+export const localStateKeyRef = (installId, generation) => secretRef("local-state-key", `${installId}.${generation}`);
+const LABEL = "openlfcp-local-v1";
+// WHATWG TextEncoder and Web Crypto's getRandomValues, which browsers,
+// Node.js and editors all provide; declared here so the package needs no DOM
+// or Node type library.
+const g = globalThis;
+const utf8 = (text) => new g.TextEncoder().encode(text);
+/**
+ * The AAD of a row: the label, the install ID, the store and the row's
+ * primary key, each length-prefixed, so a row cannot be swapped with
+ * another one or moved to another install.
+ */
+export function localStateAad(installId, store, key) {
+    const parts = [utf8(LABEL), utf8(installId), utf8(store), utf8(key)];
+    const out = new Uint8Array(parts.reduce((n, p) => n + 4 + p.length, 0));
+    const view = new DataView(out.buffer);
+    let at = 0;
+    for (const p of parts) {
+        view.setUint32(at, p.length);
+        out.set(p, at + 4);
+        at += 4 + p.length;
+    }
+    return out;
+}
+const randomInstallId = () => toHex(g.crypto.getRandomValues(new Uint8Array(16)));
+async function loadKey(cipher, secrets, installId, generation) {
+    const bytes = await secrets.get(localStateKeyRef(installId, generation));
+    // An empty value marks a deleted secret where the store has no delete.
+    if (bytes === undefined || bytes.length === 0)
+        return undefined;
+    try {
+        return cipher.importKey(bytes);
+    }
+    finally {
+        bytes.fill(0);
+    }
+}
+async function storeKey(cipher, secrets, installId, generation) {
+    const key = cipher.generateKey();
+    const bytes = cipher.exportKey(key);
+    try {
+        await secrets.put(localStateKeyRef(installId, generation), bytes);
+    }
+    finally {
+        bytes.fill(0);
+    }
+    return key;
+}
+/** An install's local state keys and metadata, held by an open adapter. */
+export class LocalStateKeyring {
+    #cipher;
+    #keys;
+    meta;
+    constructor(cipher, meta, keys) {
+        this.#cipher = cipher;
+        this.meta = Object.freeze({ ...meta });
+        this.#keys = keys;
+    }
+    /**
+     * The keyring for an adapter opening with `stored` metadata (undefined: a
+     * new install or a database from before the scheme). Writes any new key
+     * to `secrets` before it returns; the caller then records `meta` and runs
+     * `reseal` while `meta.phase` is not `ready`.
+     */
+    static async prepare(cipher, secrets, stored, now) {
+        if (stored === undefined) {
+            const installId = randomInstallId();
+            const key = await storeKey(cipher, secrets, installId, 1);
+            return new LocalStateKeyring(cipher, {
+                scheme: LOCAL_STATE_SCHEME,
+                installId,
+                generation: 1,
+                phase: "migrating",
+                previous: null,
+                lastEvent: { kind: "created", at: now },
+            }, new Map([[1, key]]));
+        }
+        if (stored.scheme !== LOCAL_STATE_SCHEME)
+            throw new LfcpError("UNSUPPORTED_VALUE", `unknown local state scheme ${stored.scheme}`);
+        const keys = new Map();
+        const current = await loadKey(cipher, secrets, stored.installId, stored.generation);
+        if (stored.previous !== null) {
+            const previous = await loadKey(cipher, secrets, stored.installId, stored.previous);
+            if (previous !== undefined)
+                keys.set(stored.previous, previous);
+        }
+        if (current !== undefined) {
+            keys.set(stored.generation, current);
+            return new LocalStateKeyring(cipher, stored, keys);
+        }
+        // The current key is lost: start the next generation. Rows sealed under
+        // the lost key stay unreadable until they are rewritten.
+        const generation = stored.generation + 1;
+        keys.set(generation, await storeKey(cipher, secrets, stored.installId, generation));
+        return new LocalStateKeyring(cipher, {
+            ...stored,
+            generation,
+            phase: stored.phase === "rotating" ? "rotating" : stored.phase,
+            lastEvent: { kind: "key-lost", at: now },
+        }, keys);
+    }
+    /**
+     * Begins a rotation: writes the next generation's key to `secrets` and
+     * returns the keyring to record (phase `rotating`) before `reseal` runs.
+     */
+    async rotate(secrets, now) {
+        if (this.meta.phase !== "ready")
+            throw new LfcpError("UNSUPPORTED_VALUE", `the local state is ${this.meta.phase}`);
+        const generation = this.meta.generation + 1;
+        const keys = new Map(this.#keys);
+        keys.set(generation, await storeKey(this.#cipher, secrets, this.meta.installId, generation));
+        return new LocalStateKeyring(this.#cipher, {
+            ...this.meta,
+            generation,
+            phase: "rotating",
+            previous: this.meta.generation,
+            lastEvent: { kind: "rotated", at: now },
+        }, keys);
+    }
+    /** The keyring once `reseal` has finished: phase `ready`. */
+    finished(now) {
+        const migrated = this.meta.phase === "migrating";
+        const keys = new Map([...this.#keys].filter(([g]) => g === this.meta.generation));
+        return new LocalStateKeyring(this.#cipher, {
+            ...this.meta,
+            phase: "ready",
+            previous: null,
+            lastEvent: migrated ? { kind: "migrated", at: now } : this.meta.lastEvent,
+        }, keys);
+    }
+    /** Whether the current generation's key is held. */
+    get keyPresent() {
+        return this.#keys.has(this.meta.generation);
+    }
+    /** The envelope of a row's `plaintext`, under the current key. */
+    seal(store, key, plaintext) {
+        const k = this.#keys.get(this.meta.generation);
+        if (k === undefined)
+            throw new LfcpError("CRYPTO_FAILURE", "the local state key is missing");
+        return this.#cipher.seal(k, this.meta.generation, localStateAad(this.meta.installId, store, key), plaintext);
+    }
+    /** A row's bytes as stored: plaintext, opened, or unreadable (never a throw). */
+    open(store, key, bytes) {
+        if (!this.#cipher.isSealed(bytes))
+            return { kind: "plain", bytes };
+        const generation = this.#cipher.generationOf(bytes);
+        const k = this.#keys.get(generation);
+        if (k === undefined)
+            return { kind: "unreadable", reason: "missing-key" };
+        try {
+            return {
+                kind: "opened",
+                bytes: this.#cipher.open(k, localStateAad(this.meta.installId, store, key), bytes),
+                generation,
+            };
+        }
+        catch {
+            return { kind: "unreadable", reason: "authentication" };
+        }
+    }
+    /** Whether a stored row needs sealing again: plaintext, or sealed under a readable older generation. */
+    needsReseal(bytes) {
+        if (!this.#cipher.isSealed(bytes))
+            return true;
+        const generation = this.#cipher.generationOf(bytes);
+        return generation !== this.meta.generation && this.#keys.has(generation);
+    }
+    /** The SecretStore reference of the key a finished rotation replaced, to remove. */
+    get retired() {
+        return this.meta.previous === null
+            ? null
+            : localStateKeyRef(this.meta.installId, this.meta.previous);
+    }
+    toJSON() {
+        return "[LocalStateKeyring]";
+    }
+}
+/**
+ * Seals every row that needs it, in batches: `scan` returns up to `limit`
+ * rows after `after` (null: from the start) in key order; `write` stores the
+ * sealed rows atomically. Resumable: a row already sealed under the current
+ * generation is skipped, so a crash between batches continues on the next
+ * open. A row whose key is lost is left as it is.
+ */
+export async function reseal(keyring, scan, write, limit = 64) {
+    let after = null;
+    let count = 0;
+    for (;;) {
+        const rows = await scan(after, limit);
+        if (rows.length === 0)
+            return count;
+        const sealed = [];
+        for (const row of rows) {
+            if (!keyring.needsReseal(row.bytes))
+                continue;
+            const opened = keyring.open(row.store, row.key, row.bytes);
+            if (opened.kind === "unreadable")
+                continue;
+            sealed.push({ ...row, bytes: keyring.seal(row.store, row.key, opened.bytes) });
+        }
+        if (sealed.length > 0)
+            await write(sealed);
+        count += sealed.length;
+        after = rows.at(-1).key;
+        if (rows.length < limit)
+            return count;
+    }
+}
+//# sourceMappingURL=local-state.js.map

package/dist/secrets.d.ts

@@ -1,7 +1,8 @@
 import { type DataEpoch, type PrincipalId, type ResourceId } from "@openlfcp/core";
 /**
- * Client secret material (LFCP-034): Principal private keys, Resource DEKs
- * and invitation secrets live only in a SecretStore. Public storage rows
+ * Client secret material (LFCP-034): Principal private keys, Resource DEKs,
+ * invitation secrets and local state keys (LFCP-02-098) live only in a
+ * SecretStore. Public storage rows
  * hold a SecretRef, a name that reveals nothing about the value.
  *
  * A SecretStore cannot be enumerated: there is no list operation, so no
@@ -14,7 +15,7 @@ import { type DataEpoch, type PrincipalId, type ResourceId } from "@openlfcp/cor
  * first, then commit the row that references it. A reference without a
  * value is a recoverable gap; a value without a reference is harmless.
  */
-export type SecretKind = "principal-signing-key" | "principal-agreement-key" | "resource-dek" | "invitation-secret";
+export type SecretKind = "principal-signing-key" | "principal-agreement-key" | "resource-dek" | "invitation-secret" | "local-state-key";
 /** The name of a secret: "lfcp-secret:<kind>:<id>". It never contains secret material. */
 export type SecretRef = string & {
     readonly __secretRef: true;

package/dist/secrets.js

@@ -4,6 +4,7 @@ const KINDS = new Set([
     "principal-agreement-key",
     "resource-dek",
     "invitation-secret",
+    "local-state-key",
 ]);
 const ID = /^[A-Za-z0-9._-]{1,200}$/;
 /** A secret reference; `id` is a public name such as hex IDs joined with ".". */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/storage",
-  "version": "0.1.4",
+  "version": "0.2.0-beta.1",
   "description": "Storage interfaces for LFCP clients (no adapters).",
   "keywords": [
     "openlfcp",
@@ -42,9 +42,9 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "latest"
+    "tag": "beta"
   },
   "dependencies": {
-    "@openlfcp/core": "^0.1.4"
+    "@openlfcp/core": "^0.2.0-beta.1"
   }
 }