commit 72aca8414f66e5cf2e44558273ce7d5fd986afe1
parent 9b6e3f0c99a0358bd17b72f7f5b179bbcba5922c
Author: triesap <tyson@radroots.org>
Date: Fri, 9 Oct 2026 11:52:06 +0000
messages: enforce finite refresh live-rate and ciphertext retention limits (HCP-099)
- Expose explicit recovery choices for existing finite and live budget pauses
- Require original owner generation and two reviewed steps for local-copy cleanup
- Delete selected received ciphertext atomically and verify actual absence
- Preserve outbox, foreign copies and honest abort or readback outcomes
Diffstat:
7 files changed, 1138 insertions(+), 8 deletions(-)
diff --git a/web/src/lib/messaging/inbox-budget.ts b/web/src/lib/messaging/inbox-budget.ts
@@ -0,0 +1,51 @@
+import {
+ PRIVATE_TRANSPORT_BUDGETS,
+ PRIVATE_LIVE_BUDGETS,
+ LOCAL_PERSISTENCE_BUDGETS
+} from '../config/budgets.ts';
+// Detached display/recovery metadata only. Original transport/repositories own
+// actual admission; these choices never reset a meter, delete or resume work.
+export function inboxBudgetSnapshot() {
+ return {
+ finite: {
+ deliveries: PRIVATE_TRANSPORT_BUDGETS.deliveries,
+ bytes: PRIVATE_TRANSPORT_BUDGETS.processedBytes,
+ milliseconds: PRIVATE_TRANSPORT_BUDGETS.pageMilliseconds
+ },
+ live: {
+ deliveries: PRIVATE_LIVE_BUDGETS.deliveries,
+ bytes: PRIVATE_LIVE_BUDGETS.processedBytes,
+ milliseconds: PRIVATE_LIVE_BUDGETS.windowMilliseconds
+ },
+ received: {
+ records: LOCAL_PERSISTENCE_BUDGETS.receivedEnvelopes,
+ bytes: LOCAL_PERSISTENCE_BUDGETS.receivedCiphertextBytes
+ },
+ outbox: {
+ records: LOCAL_PERSISTENCE_BUDGETS.unfinishedPrivateSends,
+ bytes: LOCAL_PERSISTENCE_BUDGETS.privateSendBytes
+ }
+ };
+}
+export function inboxRecoveryChoices(reason: unknown): readonly string[] {
+ if (typeof reason !== 'string') return [];
+ if (reason === 'capacity')
+ return ['review_local_received_copies', 'review_relay_recovery'];
+ if (reason === 'budget' || reason === 'timeout' || reason === 'elapsed')
+ return [
+ 'wait_then_review_refresh',
+ 'review_history_scope',
+ 'review_local_received_copies'
+ ];
+ if (
+ [
+ 'aborted',
+ 'unknown_completion',
+ 'conflict',
+ 'corrupt_record',
+ 'unavailable'
+ ].includes(reason)
+ )
+ return ['review_storage_recovery'];
+ return [];
+}
diff --git a/web/src/lib/messaging/inbox-sync.ts b/web/src/lib/messaging/inbox-sync.ts
@@ -1,3 +1,4 @@
+import { inboxRecoveryChoices } from './inbox-budget.ts';
import { outerHistoryPlan } from './history-cursor.ts';
import {
unlockedSessionOwnership,
@@ -57,6 +58,7 @@ type Snapshot = Readonly<{
backfill: string;
historyComplete: false;
foregroundOnly: true;
+ recoveryChoices: readonly string[];
}>;
export type InboxHistoryOwnership = Readonly<{
session: PrivateSession;
@@ -340,7 +342,8 @@ export function captureInboxSync(
cleanupRequired,
backfill,
historyComplete: false,
- foregroundOnly: true
+ foregroundOnly: true,
+ recoveryChoices: inboxRecoveryChoices(reason)
}),
stop,
start(reviewed) {
diff --git a/web/src/lib/persistence/inbox-retention.ts b/web/src/lib/persistence/inbox-retention.ts
@@ -0,0 +1,203 @@
+import { LOCAL_PERSISTENCE_BUDGETS } from '../config/budgets.ts';
+import {
+ privateSessionOwnership,
+ subscribePrivateSessionClose,
+ type PrivateSession
+} from '../runtime/private-session.ts';
+import {
+ privateRecordIdentity,
+ privateRecordWire,
+ type PrivateRecordHandle
+} from './private-records.ts';
+import {
+ listPrivateReceivedRecords,
+ removePrivateReceivedRecords,
+ type PrivateStorageRepository,
+ type PrivateStorageFailure
+} from './private-storage.ts';
+declare const cleanupBrand: unique symbol;
+export type ReceivedCleanup = Readonly<{ [cleanupBrand]: true }>;
+type Result = Readonly<{
+ status: 'removed' | 'invalid' | 'busy' | 'stopped' | PrivateStorageFailure;
+ removed?: number;
+}>;
+type Snapshot = Readonly<{
+ owner: string;
+ state: 'review' | 'running' | 'removed' | 'needs_action' | 'stopped';
+ selected: number;
+ bytes: number;
+ ids: readonly string[];
+ localCopyLoss: true;
+ relayRecovery: 'not_guaranteed';
+ outbox: 'unchanged';
+ reason: string | null;
+}>;
+type Controller = {
+ run(review: unknown): Promise<Result>;
+ snapshot(): Snapshot;
+ stop(): void;
+};
+const actions = new WeakMap<ReceivedCleanup, Controller>();
+// Complete bounded selection, copied before admission. IDs alone are not
+// effect authority and no malformed tail is silently truncated.
+export function selectReceivedCleanupIds(value: unknown): string[] | undefined {
+ try {
+ if (
+ !Array.isArray(value) ||
+ !value.length ||
+ value.length > LOCAL_PERSISTENCE_BUDGETS.receivedEnvelopes
+ )
+ return undefined;
+ const copy: Array<unknown> = Array.from(value);
+ if (!copy.every((x) => typeof x === 'string' && /^[0-9a-f]{64}$/.test(x)))
+ return undefined;
+ return [...new Set(copy as string[])];
+ } catch {
+ return undefined;
+ }
+}
+// Explicit local-copy loss preview only, no delete/SDK/network operation.
+// Genuine installed original private generation owns this opaque action;
+// remembered owner strings and copied previews cannot grant deletion.
+export async function captureReceivedCleanup(
+ repository: PrivateStorageRepository,
+ session: PrivateSession,
+ selection: unknown,
+ review: unknown
+): Promise<ReceivedCleanup | undefined> {
+ if (
+ typeof window === 'undefined' ||
+ review !== 'reviewed_received_cleanup_selection' ||
+ !navigator.locks?.request
+ )
+ return undefined;
+ const ids = selectReceivedCleanupIds(selection),
+ observed = privateSessionOwnership(session);
+ if (!ids || !observed?.current()) return undefined;
+ const ownership = observed;
+ try {
+ const scan = await listPrivateReceivedRecords(repository);
+ if (!scan.ok || !ownership.current()) return undefined;
+ let selected = Array.from<PrivateRecordHandle>([]),
+ bytes = 0;
+ for (const id of ids) {
+ const row = scan.value.find((h) => privateRecordIdentity(h)?.id === id),
+ identity = row && privateRecordIdentity(row),
+ wire = row && privateRecordWire(row, ownership.owner, id);
+ if (!row || identity?.owner !== ownership.owner || !wire)
+ return undefined;
+ selected = selected.concat(row);
+ bytes += new TextEncoder().encode(
+ JSON.stringify({ owner: ownership.owner, id, wire })
+ ).length;
+ }
+ const token = Object.freeze({}) as ReceivedCleanup;
+ const cancellation = new AbortController();
+ let state: Snapshot['state'] = 'review',
+ reason: string | null = null,
+ used = false,
+ stopped = false;
+ let off = () => {};
+ function stop() {
+ if (stopped) return;
+ stopped = true;
+ cancellation.abort();
+ state = 'stopped';
+ selected = [];
+ off();
+ }
+ actions.set(token, {
+ snapshot: () => ({
+ owner: ownership.owner,
+ state,
+ selected: ids.length,
+ bytes,
+ ids: ids.slice(),
+ localCopyLoss: true,
+ relayRecovery: 'not_guaranteed',
+ outbox: 'unchanged',
+ reason
+ }),
+ stop,
+ async run(reviewed) {
+ if (stopped || !ownership.current()) return { status: 'stopped' };
+ if (reviewed !== 'reviewed_delete_local_received_copies' || used)
+ return { status: 'invalid' };
+ used = true;
+ state = 'running';
+ const original = selected.slice();
+ let result: Result;
+ try {
+ result = await navigator.locks.request(
+ 'harvestcircle:owner:' + ownership.owner,
+ { mode: 'exclusive', ifAvailable: true },
+ async (lock): Promise<Result> => {
+ if (!lock) return { status: 'busy' };
+ if (stopped || !ownership.current()) return { status: 'stopped' };
+ const committed = await removePrivateReceivedRecords(
+ repository,
+ session,
+ original,
+ 'reviewed_delete_local_received_copies',
+ cancellation.signal
+ );
+ if (!committed.ok)
+ return {
+ status:
+ committed.reason === 'invalid_scope' &&
+ (stopped || !ownership.current())
+ ? 'stopped'
+ : committed.reason
+ };
+ // Native complete precedes this fresh strict RO absence verification.
+ // A failed readback or owner loss cannot establish definite no deletion.
+ const readback = await listPrivateReceivedRecords(repository);
+ if (
+ !readback.ok ||
+ stopped ||
+ !ownership.current() ||
+ readback.value.some((h) =>
+ ids.includes(privateRecordIdentity(h)?.id ?? '')
+ )
+ )
+ return { status: 'unknown_completion' };
+ return { status: 'removed', removed: committed.value.removed };
+ }
+ );
+ } catch {
+ result = { status: 'unknown_completion' };
+ }
+ reason = result.status === 'removed' ? null : result.status;
+ if (!stopped)
+ state = result.status === 'removed' ? 'removed' : 'needs_action';
+ selected = [];
+ off();
+ return result;
+ }
+ });
+ off = subscribePrivateSessionClose(session, stop);
+ if (!ownership.current()) {
+ stop();
+ return undefined;
+ }
+ return token;
+ } catch {
+ return undefined;
+ }
+}
+export function receivedCleanupSnapshot(
+ token: ReceivedCleanup
+): Snapshot | undefined {
+ return actions.get(token)?.snapshot();
+}
+export function deleteReviewedReceivedCopies(
+ token: ReceivedCleanup,
+ review: unknown
+): Promise<Result> {
+ return (
+ actions.get(token)?.run(review) ?? Promise.resolve({ status: 'invalid' })
+ );
+}
+export function stopReceivedCleanup(token: ReceivedCleanup): void {
+ actions.get(token)?.stop();
+}
diff --git a/web/src/lib/persistence/private-storage.ts b/web/src/lib/persistence/private-storage.ts
@@ -1,3 +1,8 @@
+import {
+ privateSessionOwnership,
+ subscribePrivateSessionClose,
+ type PrivateSession
+} from '../runtime/private-session.ts';
import { canonicalPublicKey } from '../contracts/public-key.ts';
import { exactLocalFields } from '../contracts/local-records.ts';
import { LOCAL_PERSISTENCE_BUDGETS } from '../config/budgets.ts';
@@ -104,7 +109,8 @@ function transaction<T>(
rows: readonly Row[],
tx: IDBTransaction,
refuse: (reason: PrivateStorageFailure) => void
- ) => PrivateStorageResult<T> | undefined
+ ) => PrivateStorageResult<T> | undefined,
+ watch?: (refuse: (reason: PrivateStorageFailure) => void) => () => void
): Promise<PrivateStorageResult<T>> {
let tx: IDBTransaction;
try {
@@ -125,6 +131,7 @@ function transaction<T>(
bytes = 0;
let rows = Array.from<Row>([]);
function refuse(reason: PrivateStorageFailure) {
+ if (result && !result.ok) return;
result = failed(reason);
try {
tx.abort();
@@ -132,12 +139,28 @@ function transaction<T>(
result = failed('unknown_completion');
}
}
- tx.addEventListener('complete', () =>
- resolve(result ?? failed('unknown_completion'))
- );
- tx.addEventListener('abort', () =>
- resolve(result && !result.ok ? result : failed('aborted'))
- );
+ let off = () => {};
+ tx.addEventListener('complete', () => {
+ off();
+ resolve(result ?? failed('unknown_completion'));
+ });
+ tx.addEventListener('abort', () => {
+ off();
+ // Actual native abort confirms rollback even if another abort call raced.
+ resolve(
+ result && !result.ok && result.reason !== 'unknown_completion'
+ ? result
+ : failed('aborted')
+ );
+ });
+ if (watch) {
+ try {
+ off = watch(refuse);
+ } catch {
+ refuse('unavailable');
+ return;
+ }
+ }
try {
const cursorRequest = tx
.objectStore(store)
@@ -369,3 +392,84 @@ export function listPrivateReceivedRecords(
}
);
}
+
+// Explicit original-owner local received-copy loss only. Immutable selected
+// whole wires CAS before any delete; independent outbox is never opened.
+// Actual close aborts an admitted transaction where still possible. Native
+// complete is necessary, and caller must separately verify readonly absence.
+export function removePrivateReceivedRecords(
+ repository: PrivateStorageRepository,
+ session: PrivateSession,
+ handles: readonly PrivateRecordHandle[],
+ review: unknown,
+ cancellation?: AbortSignal
+): Promise<PrivateStorageResult<Readonly<{ removed: number }>>> {
+ const scope = scopeOf(repository),
+ ownership = privateSessionOwnership(session);
+ if (
+ review !== 'reviewed_delete_local_received_copies' ||
+ !scope ||
+ cancellation?.aborted ||
+ !ownership?.current() ||
+ scope.owner !== ownership.owner
+ )
+ return Promise.resolve(failed('invalid_scope'));
+ if (
+ !Array.isArray(handles) ||
+ !handles.length ||
+ handles.length > LOCAL_PERSISTENCE_BUDGETS.receivedEnvelopes
+ )
+ return Promise.resolve(failed('invalid_record'));
+ const selected = handles.map((handle: PrivateRecordHandle) => {
+ const identity = privateRecordIdentity(handle);
+ const record =
+ identity && privateRecordSnapshot(handle, scope.owner, identity.id),
+ wire = identity && privateRecordWire(handle, scope.owner, identity.id);
+ return identity && record?.family === 'received_envelope' && wire
+ ? { id: identity.id, wire }
+ : undefined;
+ });
+ if (
+ selected.some((x) => !x) ||
+ new Set(selected.map((x) => x?.id)).size !== selected.length
+ )
+ return Promise.resolve(failed('invalid_record'));
+ return transaction<Readonly<{ removed: number }>>(
+ scope,
+ 'received_envelopes',
+ 'readwrite',
+ (rows, tx, refuse) => {
+ if (!ownership.current() || cancellation?.aborted) {
+ refuse('invalid_scope');
+ return;
+ }
+ for (const item of selected) {
+ if (
+ !item ||
+ rows.find((row) => row.record.id === item.id)?.wire !== item.wire
+ ) {
+ refuse('conflict');
+ return;
+ }
+ }
+ if (!ownership.current() || cancellation?.aborted) {
+ refuse('invalid_scope');
+ return;
+ }
+ for (const item of selected)
+ if (item)
+ tx.objectStore('received_envelopes').delete([scope.owner, item.id]);
+ return { ok: true, value: { removed: selected.length } };
+ },
+ (refuse) => {
+ const abort = () => refuse('invalid_scope');
+ const off = subscribePrivateSessionClose(session, abort);
+ cancellation?.addEventListener('abort', abort, { once: true });
+ if (cancellation?.aborted) abort();
+ return () => {
+ off();
+ cancellation?.removeEventListener('abort', abort);
+ };
+ }
+ );
+}
diff --git a/web/tests/e2e/harness/inbox-retention.ts b/web/tests/e2e/harness/inbox-retention.ts
@@ -0,0 +1,326 @@
+import { makeFixture as makeRecoveryFixture } from './resume-preparation.ts';
+import {
+ createPrivateSession,
+ closePrivateSession,
+ privateSessionOwnership
+} from '../../../src/lib/runtime/private-session.ts';
+import { captureUnlockedSession } from '../../../src/lib/messaging/unlocked-session.ts';
+import {
+ captureInboxSync,
+ startInboxSync,
+ stopInboxSync,
+ inboxSyncSnapshot,
+ type InboxSync
+} from '../../../src/lib/messaging/inbox-sync.ts';
+import {
+ validateRelayPolicy,
+ readRelayPolicy
+} from '../../../src/lib/config/relays.ts';
+import {
+ captureReceivedCleanup,
+ deleteReviewedReceivedCopies,
+ receivedCleanupSnapshot,
+ stopReceivedCleanup,
+ type ReceivedCleanup
+} from '../../../src/lib/persistence/inbox-retention.ts';
+import {
+ admitInboxEnvelope,
+ retainInboxEnvelope
+} from '../../../src/lib/persistence/inbox-envelope-repository.ts';
+import {
+ listPrivateReceivedRecords,
+ commitPrivateRecord,
+ createPrivateStorageRepository
+} from '../../../src/lib/persistence/private-storage.ts';
+import {
+ decodePrivateRecord,
+ privateRecordIdentity,
+ privateRecordWire,
+ privateRecordSnapshot
+} from '../../../src/lib/persistence/private-records.ts';
+import {
+ openBrowserDatabase,
+ closeBrowserDatabase
+} from '../../../src/lib/persistence/database.ts';
+import { finalizeEvent, getPublicKey } from 'applesauce-core/helpers';
+import { nip44 } from 'applesauce-core/helpers/encryption';
+export async function makeFixture() {
+ const f = await makeRecoveryFixture();
+ const session = await createPrivateSession(
+ f.identity,
+ 'reviewed_private_session'
+ );
+ if (!session) throw Error('genuine session absent');
+ const unlocked = captureUnlockedSession(session, 'reviewed_messages_unlock');
+ if (!unlocked) throw Error('genuine unlock absent');
+ const policy = validateRelayPolicy(
+ JSON.stringify({
+ ...readRelayPolicy(f.context.policy),
+ messagingEnabled: true
+ })
+ );
+ if (!policy) throw Error('policy absent');
+ const initial = (await f.row())!;
+ const originalOutbox = JSON.stringify(initial.record);
+ const ownerSecret = new Uint8Array(32).fill(83),
+ outerSecret = new Uint8Array(32).fill(86),
+ otherSecret = new Uint8Array(32).fill(85),
+ otherOwner = getPublicKey(otherSecret);
+ const ids: string[] = [];
+ let outer: string = '',
+ foreignWire: string = '';
+ const opened = await openBrowserDatabase();
+ if (opened.state !== 'ready') throw Error('native database absent');
+ const foreignRepo = createPrivateStorageRepository(opened.owner, otherOwner);
+ if (!foreignRepo) throw Error('foreign namespace absent');
+ try {
+ const original = JSON.parse(initial.record.self.wire) as {
+ pubkey: string;
+ content: string;
+ };
+ const key = nip44.v2.utils.getConversationKey(ownerSecret, original.pubkey);
+ let seal: string;
+ try {
+ seal = nip44.v2.decrypt(original.content, key);
+ } finally {
+ key.fill(0);
+ }
+ function wrap(target: string, n: number) {
+ const k = nip44.v2.utils.getConversationKey(outerSecret, target);
+ try {
+ return finalizeEvent(
+ {
+ kind: 1059,
+ created_at: 1700000000 + n,
+ tags: [['p', target]],
+ content: nip44.v2.encrypt(seal, k)
+ },
+ outerSecret
+ );
+ } finally {
+ k.fill(0);
+ }
+ }
+ for (let i = 0; i < 3; i++) {
+ const event = wrap(f.owner, i);
+ const wire = JSON.stringify(event),
+ admitted = admitInboxEnvelope(
+ wire,
+ f.owner,
+ 'wss://archive.example.org',
+ 100 + i
+ );
+ if (
+ !admitted ||
+ (await retainInboxEnvelope(f.repository, session, admitted)).status !==
+ 'retained'
+ )
+ throw Error('real retention absent');
+ ids.push(event.id);
+ if (!i) outer = wire;
+ }
+ const event = wrap(otherOwner, 4),
+ decoded = decodePrivateRecord(
+ JSON.stringify({
+ schema: 1,
+ family: 'received_envelope',
+ owner: otherOwner,
+ id: event.id,
+ revision: 0,
+ outer: JSON.stringify(event),
+ observedAtMilliseconds: 100,
+ sources: ['wss://archive.example.org'],
+ read: null
+ }),
+ otherOwner,
+ event.id
+ );
+ if (!decoded.ok) throw Error('foreign structural record absent');
+ if (!(await commitPrivateRecord(foreignRepo, decoded.value, null)).ok)
+ throw Error('foreign native row absent');
+ foreignWire = privateRecordWire(decoded.value, otherOwner, event.id)!;
+ } finally {
+ ownerSecret.fill(0);
+ outerSecret.fill(0);
+ otherSecret.fill(0);
+ }
+ let cleanup: ReceivedCleanup | undefined, sync: InboxSync | undefined;
+ let restore = () => {};
+ const baseline = f.counts();
+ async function rows() {
+ const result = await listPrivateReceivedRecords(f.repository);
+ if (!result.ok) throw Error('native scan failed');
+ return result.value.map((h) => ({
+ id: privateRecordIdentity(h)!.id,
+ wire: privateRecordWire(h, f.owner, privateRecordIdentity(h)!.id)!
+ }));
+ }
+ return {
+ ...f,
+ outer,
+ ids,
+ async select(
+ selected: unknown = ids.slice(0, 2),
+ review: unknown = 'reviewed_received_cleanup_selection'
+ ) {
+ cleanup = await captureReceivedCleanup(
+ f.repository,
+ session,
+ selected,
+ review
+ );
+ return !!cleanup;
+ },
+ snapshot: () => cleanup && receivedCleanupSnapshot(cleanup),
+ purge: (review: unknown = 'reviewed_delete_local_received_copies') =>
+ cleanup
+ ? deleteReviewedReceivedCopies(cleanup, review)
+ : Promise.resolve({ status: 'invalid' }),
+ copied: () =>
+ deleteReviewedReceivedCopies(
+ {} as ReceivedCleanup,
+ 'reviewed_delete_local_received_copies'
+ ),
+ rows,
+ async preserved() {
+ const rows = await listPrivateReceivedRecords(foreignRepo);
+ return (
+ JSON.stringify((await f.row())!.record) === originalOutbox &&
+ rows.ok &&
+ rows.value.length === 1 &&
+ privateRecordWire(
+ rows.value[0],
+ otherOwner,
+ privateRecordIdentity(rows.value[0])!.id
+ ) === foreignWire
+ );
+ },
+ delta: () => ({
+ decrypts: f.counts().decrypts - baseline.decrypts,
+ encrypts: f.counts().encrypts - baseline.encrypts,
+ signs: f.counts().signs - baseline.signs
+ }),
+ logout() {
+ closePrivateSession(session);
+ },
+ async revise() {
+ const scan = await listPrivateReceivedRecords(f.repository);
+ if (!scan.ok) throw Error('scan absent');
+ const base = scan.value.find(
+ (h) => privateRecordIdentity(h)?.id === ids[0]
+ )!;
+ const row = privateRecordSnapshot(base, f.owner, ids[0])!;
+ if (row.family !== 'received_envelope')
+ throw Error('received row absent');
+ const next = decodePrivateRecord(
+ JSON.stringify({
+ ...row,
+ revision: row.revision + 1,
+ sources: [...row.sources, 'wss://other.example.org']
+ }),
+ f.owner,
+ ids[0]
+ );
+ if (
+ !next.ok ||
+ !(await commitPrivateRecord(f.repository, next.value, base)).ok
+ )
+ throw Error('actual CAS revision failed');
+ },
+ fault(kind: 'abort' | 'readback' | 'logout_cursor' | 'stop_cursor') {
+ const remove = Reflect.get<IDBObjectStore, 'delete'>(
+ IDBObjectStore.prototype,
+ 'delete'
+ ),
+ cursor = Reflect.get<IDBIndex, 'openCursor'>(
+ IDBIndex.prototype,
+ 'openCursor'
+ );
+ let written = false;
+ IDBObjectStore.prototype.delete = function (
+ ...args: Parameters<IDBObjectStore['delete']>
+ ) {
+ const request = remove.apply(this, args);
+ if (this.name === 'received_envelopes') {
+ written = true;
+ if (kind === 'abort') this.transaction.abort();
+ }
+ return request;
+ };
+ IDBIndex.prototype.openCursor = function (
+ ...args: Parameters<IDBIndex['openCursor']>
+ ) {
+ if (this.objectStore.name === 'received_envelopes') {
+ if (
+ kind === 'stop_cursor' &&
+ this.objectStore.transaction.mode === 'readwrite' &&
+ cleanup
+ )
+ stopReceivedCleanup(cleanup);
+ if (
+ kind === 'readback' &&
+ written &&
+ this.objectStore.transaction.mode === 'readonly'
+ )
+ throw Error('actual post-delete readback failure');
+ if (
+ kind === 'logout_cursor' &&
+ this.objectStore.transaction.mode === 'readwrite'
+ )
+ closePrivateSession(session);
+ }
+ return cursor.apply(this, args);
+ };
+ restore = () => {
+ IDBObjectStore.prototype.delete = remove;
+ IDBIndex.prototype.openCursor = cursor;
+ };
+ },
+ restore() {
+ restore();
+ },
+ start() {
+ const ownership = privateSessionOwnership(session)!;
+ sync = captureInboxSync(
+ f.repository,
+ session,
+ policy,
+ f.context.own,
+ unlocked,
+ (c) => ({
+ ...c,
+ receive: 'qualified_exercised',
+ archive: 'qualified_exercised',
+ current: ownership.current
+ }),
+ 'reviewed_foreground_inbox'
+ );
+ return !!sync && startInboxSync(sync, 'reviewed_foreground_inbox');
+ },
+ sync: () => sync && inboxSyncSnapshot(sync),
+ storm(contentBytes = 16) {
+ const secret = new Uint8Array(32).fill(87);
+ try {
+ return finalizeEvent(
+ {
+ kind: 1059,
+ created_at: 1700000000,
+ tags: [['p', f.owner]],
+ content: 'x'.repeat(contentBytes)
+ },
+ secret
+ );
+ } finally {
+ secret.fill(0);
+ }
+ },
+ close() {
+ restore();
+ if (cleanup) stopReceivedCleanup(cleanup);
+ if (sync) stopInboxSync(sync);
+ closePrivateSession(session);
+ closeBrowserDatabase(opened.owner);
+ f.close();
+ }
+ };
+}
diff --git a/web/tests/e2e/inbox-retention.spec.ts b/web/tests/e2e/inbox-retention.spec.ts
@@ -0,0 +1,352 @@
+let finiteSilent = false;
+import { test, expect } from '@playwright/test';
+import { build } from 'vite';
+import { fileURLToPath } from 'node:url';
+import { once } from 'node:events';
+import { WebSocketServer, type WebSocket } from 'ws';
+import { createStaticHarness } from '../integration/harness/static.ts';
+import type * as Fixture from './harness/inbox-retention.ts';
+declare global {
+ interface Window {
+ hcp099: typeof Fixture;
+ hcp099Fixture: Awaited<ReturnType<typeof Fixture.makeFixture>>;
+ }
+}
+let server: Awaited<ReturnType<typeof createStaticHarness>>,
+ sockets: WebSocketServer,
+ endpoint: string,
+ bundle: string;
+let requests: unknown[][] = [],
+ closes: unknown[][] = [],
+ live = new Map<WebSocket, string>(),
+ finite: Record<string, unknown>[] = [];
+test.beforeAll(async () => {
+ server = await createStaticHarness();
+ sockets = new WebSocketServer({
+ host: '127.0.0.1',
+ port: 0,
+ maxPayload: 262144
+ });
+ await once(sockets, 'listening');
+ const a = sockets.address();
+ if (!a || typeof a === 'string') throw Error('loopback absent');
+ endpoint = 'ws://127.0.0.1:' + a.port;
+ sockets.on('connection', (socket) =>
+ socket.on('message', (bytes) => {
+ const raw = Buffer.isBuffer(bytes)
+ ? bytes
+ : Array.isArray(bytes)
+ ? Buffer.concat(bytes)
+ : Buffer.from(bytes);
+ const frame = JSON.parse(raw.toString()) as unknown[];
+ if (frame[0] === 'CLOSE') {
+ closes.push(frame);
+ return;
+ }
+ if (frame[0] !== 'REQ') return;
+ requests.push(frame);
+ const filter = frame[2] as { limit: number };
+ if (filter.limit === 0) live.set(socket, String(frame[1]));
+ else if (finiteSilent) return;
+ else
+ for (const event of finite)
+ socket.send(JSON.stringify(['EVENT', frame[1], event]));
+ socket.send(JSON.stringify(['EOSE', frame[1]]));
+ })
+ );
+ const result = await build({
+ configFile: false,
+ logLevel: 'silent',
+ build: {
+ write: false,
+ minify: false,
+ lib: {
+ entry: fileURLToPath(
+ new URL('./harness/inbox-retention.ts', import.meta.url)
+ ),
+ name: 'HCP099',
+ formats: ['iife']
+ }
+ }
+ });
+ const output = (Array.isArray(result) ? result : [result])
+ .flatMap((r) => ('output' in r ? r.output : []))
+ .find((x) => x.type === 'chunk');
+ if (!output || output.type !== 'chunk') throw Error('bundle absent');
+ bundle = output.code + '\nwindow.hcp099=HCP099;';
+});
+test.beforeEach(async ({ page }) => {
+ requests = [];
+ finiteSilent = false;
+ closes = [];
+ live = new Map();
+ finite = [];
+ await page.addInitScript(
+ ({ endpoint }) => {
+ const Native = window.WebSocket;
+ window.WebSocket = class extends Native {
+ constructor(url: string | URL, protocols?: string | string[]) {
+ if (new URL(String(url)).origin !== 'wss://archive.example.org')
+ throw Error('egress refused');
+ super(endpoint, protocols);
+ }
+ };
+ },
+ { endpoint }
+ );
+ await page.goto(server.url + '/messages');
+ await page.addScriptTag({ content: bundle });
+ await page.evaluate(async () => {
+ window.hcp099Fixture = await window.hcp099.makeFixture();
+ });
+});
+test.afterEach(async ({ page }) => {
+ if (!page.isClosed())
+ await page.evaluate(() => window.hcp099Fixture?.close());
+});
+test.afterAll(async () => {
+ for (const s of sockets.clients) s.terminate();
+ await new Promise<void>((r) => sockets.close(() => r()));
+ await server?.close();
+});
+function deliver(event: unknown, count: number) {
+ for (const [socket, id] of live)
+ for (let i = 0; i < count; i++)
+ socket.send(JSON.stringify(['EVENT', id, event]));
+}
+test('explicit Stop during actual queued native cursor aborts selected-copy deletion', async ({
+ page
+}) => {
+ await page.evaluate(() => window.hcp099Fixture.select());
+ await page.evaluate(() => window.hcp099Fixture.fault('stop_cursor'));
+ expect(await page.evaluate(() => window.hcp099Fixture.purge())).toMatchObject(
+ { status: 'stopped' }
+ );
+ await page.evaluate(() => window.hcp099Fixture.restore());
+ expect(await page.evaluate(() => window.hcp099Fixture.rows())).toHaveLength(
+ 3
+ );
+ expect(await page.evaluate(() => window.hcp099Fixture.preserved())).toBe(
+ true
+ );
+});
+test('only two reviewed local received copies delete; third foreign owner and unresolved outbox remain', async ({
+ page
+}) => {
+ expect(await page.evaluate(() => window.hcp099Fixture.select())).toBe(true);
+ expect(
+ await page.evaluate(() => window.hcp099Fixture.snapshot())
+ ).toMatchObject({
+ state: 'review',
+ selected: 2,
+ localCopyLoss: true,
+ relayRecovery: 'not_guaranteed'
+ });
+ expect(await page.evaluate(() => window.hcp099Fixture.purge())).toMatchObject(
+ { status: 'removed', removed: 2 }
+ );
+ expect(await page.evaluate(() => window.hcp099Fixture.rows())).toHaveLength(
+ 1
+ );
+ expect(await page.evaluate(() => window.hcp099Fixture.preserved())).toBe(
+ true
+ );
+ expect(await page.evaluate(() => window.hcp099Fixture.delta())).toEqual({
+ decrypts: 0,
+ encrypts: 0,
+ signs: 0
+ });
+ expect(requests).toEqual([]);
+});
+test('capture is inert and wrong review or copied token cannot delete', async ({
+ page
+}) => {
+ expect(
+ await page.evaluate(() => window.hcp099Fixture.select(undefined, 'wrong'))
+ ).toBe(false);
+ expect(await page.evaluate(() => window.hcp099Fixture.select())).toBe(true);
+ expect(
+ await page.evaluate(() => window.hcp099Fixture.purge('wrong'))
+ ).toEqual({ status: 'invalid' });
+ expect(await page.evaluate(() => window.hcp099Fixture.copied())).toEqual({
+ status: 'invalid'
+ });
+ expect(await page.evaluate(() => window.hcp099Fixture.rows())).toHaveLength(
+ 3
+ );
+ expect(await page.evaluate(() => window.hcp099Fixture.preserved())).toBe(
+ true
+ );
+});
+test('native whole-wire revision conflict aborts all selected copies', async ({
+ page
+}) => {
+ await page.evaluate(() => window.hcp099Fixture.select());
+ await page.evaluate(() => window.hcp099Fixture.revise());
+ expect(await page.evaluate(() => window.hcp099Fixture.purge())).toMatchObject(
+ { status: 'conflict' }
+ );
+ expect(await page.evaluate(() => window.hcp099Fixture.rows())).toHaveLength(
+ 3
+ );
+ expect(await page.evaluate(() => window.hcp099Fixture.preserved())).toBe(
+ true
+ );
+});
+test('actual native delete abort rolls back every selected row without success', async ({
+ page
+}) => {
+ await page.evaluate(() => window.hcp099Fixture.select());
+ await page.evaluate(() => window.hcp099Fixture.fault('abort'));
+ expect(await page.evaluate(() => window.hcp099Fixture.purge())).toMatchObject(
+ { status: 'aborted' }
+ );
+ await page.evaluate(() => window.hcp099Fixture.restore());
+ expect(await page.evaluate(() => window.hcp099Fixture.rows())).toHaveLength(
+ 3
+ );
+ expect(await page.evaluate(() => window.hcp099Fixture.preserved())).toBe(
+ true
+ );
+});
+test('actual post-delete readback failure is unknown completion and not definite no deletion', async ({
+ page
+}) => {
+ await page.evaluate(() => window.hcp099Fixture.select());
+ await page.evaluate(() => window.hcp099Fixture.fault('readback'));
+ expect(await page.evaluate(() => window.hcp099Fixture.purge())).toMatchObject(
+ { status: 'unknown_completion' }
+ );
+ await page.evaluate(() => window.hcp099Fixture.restore());
+ expect(await page.evaluate(() => window.hcp099Fixture.rows())).toHaveLength(
+ 1
+ );
+ expect(await page.evaluate(() => window.hcp099Fixture.preserved())).toBe(
+ true
+ );
+});
+test('logout after selected review refuses local deletion in original namespace', async ({
+ page
+}) => {
+ await page.evaluate(() => window.hcp099Fixture.select());
+ await page.evaluate(() => window.hcp099Fixture.logout());
+ expect(await page.evaluate(() => window.hcp099Fixture.purge())).toMatchObject(
+ { status: 'stopped' }
+ );
+ expect(await page.evaluate(() => window.hcp099Fixture.rows())).toHaveLength(
+ 3
+ );
+});
+test('owner loss during actual queued native cursor prevents deletion before finish', async ({
+ page
+}) => {
+ await page.evaluate(() => window.hcp099Fixture.select());
+ await page.evaluate(() => window.hcp099Fixture.fault('logout_cursor'));
+ expect(await page.evaluate(() => window.hcp099Fixture.purge())).toMatchObject(
+ { status: 'stopped' }
+ );
+ await page.evaluate(() => window.hcp099Fixture.restore());
+ expect(await page.evaluate(() => window.hcp099Fixture.rows())).toHaveLength(
+ 3
+ );
+});
+test('501 repeated finite ciphertext deliveries consume budget before dedup and pause', async ({
+ page
+}) => {
+ const event = JSON.parse(
+ await page.evaluate(() => window.hcp099Fixture.outer)
+ ) as Record<string, unknown>;
+ finite = Array.from({ length: 501 }, () => event);
+ expect(await page.evaluate(() => window.hcp099Fixture.start())).toBe(true);
+ await expect
+ .poll(() => page.evaluate(() => window.hcp099Fixture.sync()?.state))
+ .toBe('needs_action');
+ expect(await page.evaluate(() => window.hcp099Fixture.sync())).toMatchObject({
+ reason: 'budget',
+ historyComplete: false,
+ recoveryChoices: [
+ 'wait_then_review_refresh',
+ 'review_history_scope',
+ 'review_local_received_copies'
+ ]
+ });
+ await expect.poll(() => closes.length).toBeGreaterThanOrEqual(2);
+ expect(await page.evaluate(() => window.hcp099Fixture.preserved())).toBe(
+ true
+ );
+});
+test('121 malformed live deliveries count before rejection and pause instead of spinning', async ({
+ page
+}) => {
+ await page.evaluate(() => window.hcp099Fixture.start());
+ await expect.poll(() => requests.length).toBe(3);
+ await expect
+ .poll(() => page.evaluate(() => window.hcp099Fixture.sync()?.backfill))
+ .toBe('complete');
+ deliver(await page.evaluate(() => window.hcp099Fixture.storm()), 121);
+ await expect
+ .poll(() => page.evaluate(() => window.hcp099Fixture.sync()?.state))
+ .toBe('needs_action');
+ expect(await page.evaluate(() => window.hcp099Fixture.sync())).toMatchObject({
+ reason: 'budget',
+ historyComplete: false
+ });
+ await expect.poll(() => closes.length).toBeGreaterThanOrEqual(2);
+ expect(await page.evaluate(() => window.hcp099Fixture.preserved())).toBe(
+ true
+ );
+ expect(requests).toHaveLength(3);
+});
+test('oversized malformed live payloads consume two MiB before count cap and preserve outbox', async ({
+ page
+}) => {
+ await page.evaluate(() => window.hcp099Fixture.start());
+ await expect.poll(() => requests.length).toBe(3);
+ await expect
+ .poll(() => page.evaluate(() => window.hcp099Fixture.sync()?.backfill))
+ .toBe('complete');
+ deliver(await page.evaluate(() => window.hcp099Fixture.storm(34000)), 63);
+ await expect
+ .poll(() => page.evaluate(() => window.hcp099Fixture.sync()?.state))
+ .toBe('needs_action');
+ expect(await page.evaluate(() => window.hcp099Fixture.sync())).toMatchObject({
+ reason: 'budget',
+ retained: 0,
+ historyComplete: false
+ });
+ expect(await page.evaluate(() => window.hcp099Fixture.preserved())).toBe(
+ true
+ );
+ expect(await page.evaluate(() => window.hcp099Fixture.rows())).toHaveLength(
+ 3
+ );
+ expect(requests).toHaveLength(3);
+});
+
+test('actual fifteen-second finite elapsed pause exposes reviewed recovery and no automatic second window', async ({
+ page
+}) => {
+ finiteSilent = true;
+ expect(await page.evaluate(() => window.hcp099Fixture.start())).toBe(true);
+ await expect.poll(() => requests.length).toBe(2);
+ await expect
+ .poll(() => page.evaluate(() => window.hcp099Fixture.sync()?.state))
+ .toBe('needs_action');
+ expect(await page.evaluate(() => window.hcp099Fixture.sync())).toMatchObject({
+ reason: 'elapsed',
+ historyComplete: false,
+ recoveryChoices: [
+ 'wait_then_review_refresh',
+ 'review_history_scope',
+ 'review_local_received_copies'
+ ]
+ });
+ await expect.poll(() => closes.length).toBeGreaterThanOrEqual(2);
+ expect(requests).toHaveLength(2);
+ expect(await page.evaluate(() => window.hcp099Fixture.preserved())).toBe(
+ true
+ );
+ expect(await page.evaluate(() => window.hcp099Fixture.rows())).toHaveLength(
+ 3
+ );
+});
diff --git a/web/tests/unit/inbox-budget.test.ts b/web/tests/unit/inbox-budget.test.ts
@@ -0,0 +1,91 @@
+import { beforeAll, test, expect } from 'vitest';
+import * as Budget from '../../src/lib/messaging/inbox-budget.ts';
+import * as Cleanup from '../../src/lib/persistence/inbox-retention.ts';
+import type { PrivateSession } from '../../src/lib/runtime/private-session.ts';
+import type { PrivateStorageRepository } from '../../src/lib/persistence/private-storage.ts';
+const id = (n: number) => n.toString(16).padStart(64, '0');
+beforeAll(() => {
+ expect(Budget.inboxBudgetSnapshot).toBeTypeOf('function');
+ expect(Cleanup.selectReceivedCleanupIds).toBeTypeOf('function');
+ expect(Cleanup.captureReceivedCleanup).toBeTypeOf('function');
+});
+test('finite live retention and independent unresolved outbox caps remain exact', () =>
+ expect(Budget.inboxBudgetSnapshot()).toEqual({
+ finite: { deliveries: 500, bytes: 8388608, milliseconds: 15000 },
+ live: { deliveries: 120, bytes: 2097152, milliseconds: 60000 },
+ received: { records: 2000, bytes: 50331648 },
+ outbox: { records: 100, bytes: 8388608 }
+ }));
+test('review selection deduplicates only exact outer IDs preserving order', () =>
+ expect(Cleanup.selectReceivedCleanupIds([id(2), id(1), id(2)])).toEqual([
+ id(2),
+ id(1)
+ ]));
+test('reviewed ID selection and budget snapshots are detached copies', () => {
+ const input = [id(1)];
+ const selected = Cleanup.selectReceivedCleanupIds(input)!;
+ input[0] = id(2);
+ expect(selected).toEqual([id(1)]);
+ const view: { received: { records: number } } = Budget.inboxBudgetSnapshot();
+ view.received.records = 1;
+ expect(Budget.inboxBudgetSnapshot().received.records).toBe(2000);
+});
+test('malformed tail never silently truncates reviewed cleanup selection', () =>
+ expect(
+ Cleanup.selectReceivedCleanupIds([
+ ...Array.from({ length: 20 }, (_, n) => id(n)),
+ 'not-an-event-id'
+ ])
+ ).toBeUndefined());
+test('empty oversized uppercase and nonarray review selections refuse without reset', () => {
+ for (const value of [
+ [],
+ Array.from({ length: 2001 }, (_, n) => id(n)),
+ ['A'.repeat(64)],
+ {},
+ null
+ ])
+ expect(Cleanup.selectReceivedCleanupIds(value)).toBeUndefined();
+ expect(
+ Cleanup.selectReceivedCleanupIds(
+ Array.from({ length: 2000 }, (_, n) => id(n))
+ )?.length
+ ).toBe(2000);
+});
+test('ciphertext capacity exposes explicit local-copy review and never automatic eviction', () =>
+ expect(Budget.inboxRecoveryChoices('capacity')).toEqual([
+ 'review_local_received_copies',
+ 'review_relay_recovery'
+ ]));
+test('transport exhaustion exposes reviewed recovery while unrelated states grant no action', () => {
+ expect(Budget.inboxRecoveryChoices('budget')).toEqual([
+ 'wait_then_review_refresh',
+ 'review_history_scope',
+ 'review_local_received_copies'
+ ]);
+ expect(Budget.inboxRecoveryChoices(null)).toEqual([]);
+ expect(Budget.inboxRecoveryChoices('complete')).toEqual([]);
+});
+test('SSR copied cleanup authority cannot admit or delete any local copy', async () => {
+ expect(
+ await Cleanup.captureReceivedCleanup(
+ {} as PrivateStorageRepository,
+ {} as PrivateSession,
+ [id(1)],
+ 'reviewed_received_cleanup_selection'
+ )
+ ).toBeUndefined();
+ expect(
+ await Cleanup.deleteReviewedReceivedCopies(
+ {} as Cleanup.ReceivedCleanup,
+ 'reviewed_delete_local_received_copies'
+ )
+ ).toEqual({ status: 'invalid' });
+});
+
+test('actual finite elapsed reason exposes reviewed transport recovery without deadline widening', () =>
+ expect(Budget.inboxRecoveryChoices('elapsed')).toEqual([
+ 'wait_then_review_refresh',
+ 'review_history_scope',
+ 'review_local_received_copies'
+ ]));