@openlfcp/storage 0.2.0-beta.5 → 0.2.0-beta.7

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,9 +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,8 +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/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/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.2.0-beta.5",
+  "version": "0.2.0-beta.7",
   "description": "Storage interfaces for LFCP clients (no adapters).",
   "keywords": [
     "openlfcp",
@@ -45,6 +45,6 @@
     "tag": "beta"
   },
   "dependencies": {
-    "@openlfcp/core": "^0.2.0-beta.5"
+    "@openlfcp/core": "^0.2.0-beta.7"
   }
 }