@openlfcp/storage 0.1.5 → 0.2.0-beta.10

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/contract.js

@@ -1,4 +1,5 @@
 import { actorSequence, bytesEqual, controlRecordId, dataEpoch, dataUnitId, hash32, LfcpError, principalId, resourceId, toHex, } from "@openlfcp/core";
+import { deleteUnsentResource } from "./delete-resource.js";
 import { dekSecretRef, isSecretRef, principalKeySecretRef } from "./secrets.js";
 // ---------------------------------------------------------------------------
 // assertions (no test framework)
@@ -508,6 +509,144 @@ export function runStorageContract(t, name, open) {
             if (!bytesEqual(record(0, null).bytes, (await r.control.records(R))[0]?.bytes ?? new Uint8Array()))
                 throw new Error("exact bytes");
         });
+        /** Everything a client stores of R before sending it, and another Resource R2. */
+        const unsent = () => [
+            { op: "put-resource", row: resourceRow },
+            { op: "put-route", resourceId: R, route },
+            { op: "put-control-records", records: [record(0, null), record(1, 0)] },
+            {
+                op: "set-control-head",
+                resourceId: R,
+                expected: null,
+                head: { head: record(1, 0).recordId, controlSeq: 1n },
+            },
+            { op: "set-control-conflict", resourceId: R, conflict: { heads: [record(1, 0).recordId] } },
+            ...epochRows.map((epoch) => ({ op: "put-epoch", resourceId: R, epoch })),
+            { op: "put-data-unit", unit: unit(1, 1n), status: "merged", accepted: true },
+            { op: "put-key-package", row: keyPackage(1) },
+            { op: "put-snapshot", row: snapshot },
+            {
+                op: "enqueue",
+                item: {
+                    itemId: hash32(id(160)),
+                    resourceId: R,
+                    kind: "control-record",
+                    bytes: Uint8Array.of(1),
+                    attempts: 0,
+                    lastAttempt: null,
+                    nextAttempt: null,
+                    blocked: null,
+                },
+            },
+            { op: "put-profile-checkpoint", checkpoint },
+            { op: "put-sync-state", row: { resourceId: R, recentlyAcked: [], ackedDurability: null } },
+            { op: "put-resource", row: { ...resourceRow, resourceId: R2 } },
+            {
+                op: "enqueue",
+                item: {
+                    itemId: hash32(id(161)),
+                    resourceId: R2,
+                    kind: "control-record",
+                    bytes: Uint8Array.of(2),
+                    attempts: 3,
+                    lastAttempt: "2026-10-05T12:00:00Z",
+                    nextAttempt: null,
+                    blocked: null,
+                },
+            },
+            { op: "put-local-mark", key: "apply:x", value: "1" },
+        ];
+        test("deletes a Resource never sent, every row of it at once; others, marks and counters stay", async ({ storage: s, }) => {
+            const reserved = await s.actorSequences.reserveNext(R, ALICE);
+            await ok(s, unsent(), "stored");
+            await ok(s, [{ op: "delete-resource", resourceId: R }], "deleted");
+            eq(await s.resources.get(R), undefined, "resource");
+            eq(await s.resources.route(R), undefined, "route");
+            eq(await s.control.records(R), [], "records");
+            eq(await s.control.head(R), undefined, "head");
+            eq(await s.control.conflict(R), undefined, "conflict");
+            eq(await s.control.epochs(R), [], "epochs");
+            eq(await s.dataUnits.get(unit(1, 1n).unitId), undefined, "unit");
+            eq(await s.dataUnits.withStatus(R, "merged"), [], "units by status");
+            eq(await s.keyPackages.list(R), [], "key packages");
+            eq(await s.snapshots.list(R), [], "snapshots");
+            eq(await s.outbound.list(R), [], "outbound");
+            eq(await s.profileState.checkpoint(R), undefined, "checkpoint");
+            eq(await s.syncState.get(R), undefined, "sync state");
+            eq((await s.resources.list()).map((r) => r.resourceId), [R2], "the other Resource");
+            eq((await s.outbound.list(R2)).length, 1, "its outbound item");
+            eq(await s.localMarks.get("apply:x"), "1", "local marks");
+            const next = await s.actorSequences.reserveNext(R, ALICE);
+            if (next <= reserved)
+                throw new Error(`actor sequence reused: ${next} after ${reserved}`);
+            await ok(s, [{ op: "delete-resource", resourceId: R }], "deleting again is harmless");
+        });
+        test("refuses to delete a Resource that may have been sent, writing nothing of the batch", async ({ storage: s, }) => {
+            await ok(s, unsent(), "stored");
+            const cases = [
+                [
+                    {
+                        op: "update-outbound",
+                        itemId: hash32(id(160)),
+                        attempts: 1,
+                        lastAttempt: "2026-10-05T12:00:00Z",
+                    },
+                    "attempted",
+                ],
+                [
+                    {
+                        op: "put-sync-state",
+                        row: { resourceId: R, recentlyAcked: [hash32(id(160))], ackedDurability: 1n },
+                    },
+                    "acked",
+                ],
+                [
+                    { op: "put-data-unit", unit: unit(2, 1n, BOB), status: "merged", accepted: true },
+                    "received",
+                ],
+            ];
+            for (const [shown, detail] of cases) {
+                const h = await s.commit([shown]);
+                eq(h, { ok: true }, `stored: ${detail}`);
+                const refused = await s.commit([
+                    { op: "put-local-mark", key: "batch", value: "written" },
+                    { op: "delete-resource", resourceId: R },
+                ]);
+                eq(refused, { ok: false, reason: "RESOURCE_SENT", resourceId: R, detail }, detail);
+                eq(await s.localMarks.get("batch"), undefined, `nothing of the batch: ${detail}`);
+                eq((await s.resources.get(R))?.resourceId, R, `still stored: ${detail}`);
+                // Undone for the next case (a unit cannot be removed: it comes last).
+                if (detail === "attempted")
+                    await ok(s, [{ op: "update-outbound", itemId: hash32(id(160)), attempts: 0, lastAttempt: null }], "undone");
+                if (detail === "acked")
+                    await ok(s, [
+                        {
+                            op: "put-sync-state",
+                            row: { resourceId: R, recentlyAcked: [], ackedDurability: null },
+                        },
+                    ], "undone");
+            }
+        });
+        test("deleteUnsentResource deletes the Resource's keys, never the Principal's", async ({ storage: s, secrets, }) => {
+            await ok(s, unsent(), "stored");
+            const keys = [
+                dekSecretRef(R, E0),
+                dekSecretRef(R, E1),
+                principalKeySecretRef(ALICE, "signing"),
+            ];
+            for (const k of keys)
+                await secrets.put(k, Uint8Array.of(42));
+            eq(await deleteUnsentResource(s, secrets, R), { ok: true }, "deleted");
+            eq(await secrets.get(dekSecretRef(R, E0)), undefined, "epoch 0 key");
+            eq(await secrets.get(dekSecretRef(R, E1)), undefined, "epoch 1 key");
+            eq(await secrets.get(principalKeySecretRef(ALICE, "signing")), Uint8Array.of(42), "Principal key");
+            // A Resource that may have been sent: refused, its keys kept.
+            await ok(s, unsent(), "stored again");
+            await ok(s, [{ op: "put-data-unit", unit: unit(2, 1n, BOB), status: "merged", accepted: true }], "received");
+            await secrets.put(dekSecretRef(R, E1), Uint8Array.of(7));
+            eq(await deleteUnsentResource(s, secrets, R), { ok: false, reason: "RESOURCE_SENT", resourceId: R, detail: "received" }, "refused");
+            eq(await secrets.get(dekSecretRef(R, E1)), Uint8Array.of(7), "key kept");
+        });
     });
 }
 //# sourceMappingURL=contract.js.map

package/dist/delete-resource.d.ts

@@ -0,0 +1,14 @@
+import type { ResourceId } from "@openlfcp/core";
+import { type SecretStore } from "./secrets.js";
+import type { CommitResult, LfcpStorage } from "./store.js";
+/**
+ * Forgets a Resource this client made and never sent (a share given up
+ * before it was hosted): every stored row of it in one atomic commit
+ * (delete-resource), then the secrets only it used, its Data Epoch keys.
+ * The local Principal's keys are kept: other Resources use them. Refused,
+ * with nothing deleted, when the Resource may have been sent
+ * (RESOURCE_SENT). The rows go first: a crash before the keys are deleted
+ * leaves keys nothing refers to, never a Resource without its keys.
+ */
+export declare function deleteUnsentResource(storage: LfcpStorage, secrets: SecretStore, resource: ResourceId): Promise<CommitResult>;
+//# sourceMappingURL=delete-resource.d.ts.map

package/dist/delete-resource.js

@@ -0,0 +1,21 @@
+import { dekSecretRef } from "./secrets.js";
+/**
+ * Forgets a Resource this client made and never sent (a share given up
+ * before it was hosted): every stored row of it in one atomic commit
+ * (delete-resource), then the secrets only it used, its Data Epoch keys.
+ * The local Principal's keys are kept: other Resources use them. Refused,
+ * with nothing deleted, when the Resource may have been sent
+ * (RESOURCE_SENT). The rows go first: a crash before the keys are deleted
+ * leaves keys nothing refers to, never a Resource without its keys.
+ */
+export async function deleteUnsentResource(storage, secrets, resource) {
+    const epochs = await storage.control.epochs(resource);
+    const refs = new Set(epochs.map((e) => e.dekRef ?? dekSecretRef(resource, e.epoch)));
+    const result = await storage.commit([{ op: "delete-resource", resourceId: resource }]);
+    if (!result.ok)
+        return result;
+    for (const ref of refs)
+        await secrets.delete(ref);
+    return result;
+}
+//# sourceMappingURL=delete-resource.js.map

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 /** Name of this package. */
 export declare const PACKAGE = "@openlfcp/storage";
+export { deleteUnsentResource } from "./delete-resource.js";
+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";
 export { InMemorySnapshotSequenceReservation, SnapshotSequenceGuard, type SnapshotSequenceReservation, } from "./snapshot-sequence.js";
-export type { CommitResult, ControlConflictRow, ControlHeadRow, ControlReader, ControlRecordRow, DataUnitReader, DataUnitRow, DataUnitStatus, EpochRow, KeyPackageReader, KeyPackageRow, LfcpStorage, LocalMarkReader, OutboundBlock, OutboundItem, OutboundKind, OutboundReader, ProfileCheckpoint, ProfileStateReader, ResourceReader, ResourceRow, RouteRow, SeenRecord, SnapshotReader, SnapshotRow, StorageWrite, StoredDataUnit, SyncStateReader, SyncStateRow, } from "./store.js";
+export type { CommitResult, ControlConflictRow, ControlHeadRow, ControlReader, ControlRecordRow, DataUnitReader, DataUnitRow, DataUnitStatus, EpochRow, KeyPackageReader, KeyPackageRow, LfcpStorage, LocalMarkReader, OutboundBlock, OutboundItem, OutboundKind, OutboundReader, ProfileCheckpoint, ProfileStateReader, ResourceReader, ResourceRow, ResourceSentDetail, RouteRow, SeenRecord, SnapshotReader, SnapshotRow, StorageWrite, StoredDataUnit, SyncStateReader, SyncStateRow, } from "./store.js";
+export { resourceSent } from "./store.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,7 +1,10 @@
 /** Name of this package. */
 export const PACKAGE = "@openlfcp/storage";
+export { deleteUnsentResource } from "./delete-resource.js";
+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";
 export { InMemorySnapshotSequenceReservation, SnapshotSequenceGuard, } from "./snapshot-sequence.js";
+export { resourceSent } from "./store.js";
 //# sourceMappingURL=index.js.map

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/memory.d.ts

@@ -1,7 +1,7 @@
 import { type ActorSequence, type ControlRecordId, type DataEpoch, type DataUnitId, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
 import { type ActorSequenceReservation } from "./sequence.js";
 import { type SnapshotSequenceReservation } from "./snapshot-sequence.js";
-import type { CommitResult, ControlConflictRow, ControlHeadRow, ControlRecordRow, DataUnitRow, DataUnitStatus, EpochRow, KeyPackageRow, LfcpStorage, OutboundItem, ProfileCheckpoint, ResourceRow, RouteRow, SeenRecord, SnapshotRow, StorageWrite, StoredDataUnit, SyncStateRow } from "./store.js";
+import { 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 StorageWrite, type StoredDataUnit, type SyncStateRow } from "./store.js";
 /**
  * FOR TESTS AND DEVELOPMENT ONLY: an LfcpStorage in process memory, lost on
  * restart, with the same semantic contracts as a durable adapter (exact

package/dist/memory.js

@@ -1,6 +1,7 @@
 import { bytesEqual, LfcpError, toHex, } from "@openlfcp/core";
 import { InMemoryActorSequenceReservation } from "./sequence.js";
 import { InMemorySnapshotSequenceReservation, } from "./snapshot-sequence.js";
+import { resourceSent, } from "./store.js";
 /** A deep copy: every Uint8Array copied, everything frozen. Nothing stored aliases a caller's buffer. */
 function own(value) {
     if (value instanceof Uint8Array)
@@ -156,6 +157,25 @@ function apply(s, w) {
             else
                 s.marks.set(w.key, w.value);
             return;
+        case "delete-resource": {
+            const r = hex(w.resourceId);
+            const of = (row) => hex(row.resourceId) === r;
+            for (const map of [s.records, s.units, s.keyPackages, s.snapshots, s.outbound])
+                for (const [k, v] of map)
+                    if (of(v))
+                        map.delete(k);
+            for (const map of [
+                s.heads,
+                s.conflicts,
+                s.epochs,
+                s.resources,
+                s.routes,
+                s.checkpoints,
+                s.syncStates,
+            ])
+                map.delete(r);
+            return;
+        }
     }
 }
 const pickUnit = (u) => ({
@@ -230,6 +250,32 @@ export class InMemoryLfcpStorage {
                     current: current === null ? null : own(current),
                 }));
         }
+        for (const w of writes) {
+            if (w.op !== "delete-resource")
+                continue;
+            const r = hex(w.resourceId);
+            const detail = resourceSent({
+                local: next.resources.get(r)?.localPrincipal?.principalId ?? null,
+                outbound: [...next.outbound.values()].filter((o) => hex(o.resourceId) === r),
+                syncState: next.syncStates.get(r),
+                actors: [
+                    ...[...next.units.values()].filter((u) => hex(u.resourceId) === r).map((u) => u.actor),
+                    ...[...next.keyPackages.values()]
+                        .filter((k) => hex(k.resourceId) === r)
+                        .map((k) => k.sender),
+                    ...[...next.snapshots.values()]
+                        .filter((x) => hex(x.resourceId) === r)
+                        .map((x) => x.publisher),
+                ],
+            });
+            if (detail !== null)
+                return Promise.resolve(Object.freeze({
+                    ok: false,
+                    reason: "RESOURCE_SENT",
+                    resourceId: own(w.resourceId),
+                    detail,
+                }));
+        }
         for (const w of writes) {
             if (w.op !== "expect-previous-unit")
                 continue;

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/dist/store.d.ts

@@ -1,4 +1,4 @@
-import type { ActorSequence, ControlRecordId, DataEpoch, DataUnitId, Hash32, PrincipalId, ResourceId } from "@openlfcp/core";
+import { type ActorSequence, type ControlRecordId, type DataEpoch, type DataUnitId, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
 import type { SecretRef } from "./secrets.js";
 import type { ActorSequenceReservation } from "./sequence.js";
 import type { SnapshotSequenceReservation } from "./snapshot-sequence.js";
@@ -321,6 +321,20 @@ export type StorageWrite = {
     readonly op: "put-local-mark";
     readonly key: string;
     readonly value: string | null;
+} | {
+    /**
+     * Forgets a Resource this client made and never sent: its row, route,
+     * Control Records, head and conflict, epochs, Data Units, Key
+     * Packages, Snapshots, outbound items, profile checkpoint and sync
+     * state. Fails the batch (RESOURCE_SENT) when anything of it may have
+     * left this device or come from elsewhere: an outbound item attempted,
+     * an ACK recorded, or a Data Unit, Key Package or Snapshot of another
+     * Principal stored. The actor and Snapshot sequence counters are kept
+     * (a number is never reused). Secrets are the caller's
+     * (deleteUnsentResource deletes the Resource's DEKs).
+     */
+    readonly op: "delete-resource";
+    readonly resourceId: ResourceId;
 };
 export type CommitResult = {
     readonly ok: true;
@@ -339,7 +353,29 @@ export type CommitResult = {
     readonly resourceId: ResourceId;
     readonly actor: PrincipalId;
     readonly current: DataUnitId | null;
+}
+/** Nothing was written: the Resource to delete may have been sent (delete-resource). */
+ | {
+    readonly ok: false;
+    readonly reason: "RESOURCE_SENT";
+    readonly resourceId: ResourceId;
+    /** What shows it: "attempted", "acked" or "received". */
+    readonly detail: ResourceSentDetail;
 };
+/** Why a Resource counts as sent (delete-resource). */
+export type ResourceSentDetail = "attempted" | "acked" | "received";
+/**
+ * Why `resource` counts as sent, from what is stored of it, or null: an
+ * outbound item attempted, an ACK recorded, or a Data Unit, Key Package or
+ * Snapshot of a Principal other than its local one. Shared by the adapters
+ * (delete-resource).
+ */
+export declare function resourceSent(stored: {
+    readonly local: PrincipalId | null;
+    readonly outbound: readonly OutboundItem[];
+    readonly syncState: SyncStateRow | undefined;
+    readonly actors: readonly PrincipalId[];
+}): ResourceSentDetail | null;
 export interface ControlReader {
     record(recordId: ControlRecordId): Promise<ControlRecordRow | undefined>;
     /** Every stored record of the Resource, by (controlSeq, recordId bytes). */

package/dist/store.js

@@ -1,2 +1,19 @@
-export {};
+import { bytesEqual, } from "@openlfcp/core";
+/**
+ * Why `resource` counts as sent, from what is stored of it, or null: an
+ * outbound item attempted, an ACK recorded, or a Data Unit, Key Package or
+ * Snapshot of a Principal other than its local one. Shared by the adapters
+ * (delete-resource).
+ */
+export function resourceSent(stored) {
+    if (stored.outbound.some((o) => o.attempts > 0 || o.lastAttempt !== null))
+        return "attempted";
+    const s = stored.syncState;
+    if (s !== undefined && (s.recentlyAcked.length > 0 || s.ackedDurability !== null))
+        return "acked";
+    const local = stored.local;
+    if (stored.actors.some((a) => local === null || !bytesEqual(a, local)))
+        return "received";
+    return null;
+}
 //# sourceMappingURL=store.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/storage",
-  "version": "0.1.5",
+  "version": "0.2.0-beta.10",
   "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.5"
+    "@openlfcp/core": "^0.2.0-beta.10"
   }
 }