commit 3393cea8fea012be30906959fe44a1d6f6061a10
parent 096b0b11a5f0586cd9b469f294bfb7a1ad1caac4
Author: triesap <tyson@radroots.org>
Date: Thu, 8 Oct 2026 22:04:34 +0000
messages: commit the self recovery envelope before peer preparation (HCP-081)
- Require genuine self ciphertext and owner-bound durable readback.
- Serialize crypto and save without nested owner locks.
- Preserve acknowledged local facts and revoke closed workflow permission.
- Verify actual failure recovery and retain source-only qualification boundaries.
Diffstat:
5 files changed, 1330 insertions(+), 0 deletions(-)
diff --git a/web/src/lib/messaging/prepare-send.ts b/web/src/lib/messaging/prepare-send.ts
@@ -0,0 +1,298 @@
+import {
+ identityMessagingOwnership,
+ subscribeIdentityInvalidation,
+ type IdentitySession
+} from '../runtime/identity-session.ts';
+import {
+ reservedSendSnapshot,
+ type ReservedSendIdentity
+} from './send-identity.ts';
+import {
+ captureEnvelopePreparation,
+ prepareEnvelopeRole,
+ preparedEnvelopeProof,
+ envelopePreparationSnapshot,
+ closeEnvelopePreparation,
+ type EnvelopePreparation
+} from './envelope-preparation.ts';
+import { privateRecordSnapshot } from '../persistence/private-records.ts';
+import {
+ type PrivateStorageRepository,
+ type PrivateStorageFailure
+} from '../persistence/private-storage.ts';
+import {
+ readSelfRecoveryBase,
+ commitSelfRecovery,
+ selfRecoveryAcknowledgementSnapshot,
+ verifySelfRecoveryAcknowledgement,
+ type SelfRecoveryAcknowledgement
+} from '../persistence/private-sends.ts';
+
+declare const preparationBrand: unique symbol;
+export type SelfRecoveryPreparation = Readonly<{ [preparationBrand]: true }>;
+export type SelfRecoveryPreparationResult = Readonly<{
+ status:
+ | PrivateStorageFailure
+ | 'invalid'
+ | 'stopped'
+ | 'busy'
+ | 'saved'
+ | 'existing'
+ | 'reconciled'
+ | 'recovery_required'
+ | 'refused'
+ | 'mismatch'
+ | 'out_of_order';
+}>;
+type Phase =
+ 'unsaved' | 'preparing' | 'saved' | 'unknown_completion' | 'needs_action';
+type Snapshot = Readonly<{
+ state: Phase;
+ busy: boolean;
+ owner: string;
+ command: string;
+ copy: string;
+}>;
+type Controller = {
+ run(review: unknown): Promise<SelfRecoveryPreparationResult>;
+ snapshot(): Snapshot | undefined;
+ receipt(): SelfRecoveryAcknowledgement | undefined;
+ peer(
+ receipt: SelfRecoveryAcknowledgement
+ ): Promise<EnvelopePreparation | undefined>;
+ stop(): void;
+};
+const preparations = new WeakMap<SelfRecoveryPreparation, Controller>();
+
+// This workflow owns durable self-first admission. Lower crypto factories stay
+// memory-only foundations; their output alone cannot advance this workflow.
+export function captureSelfRecoveryPreparation(
+ repository: PrivateStorageRepository,
+ session: IdentitySession,
+ reserved: ReservedSendIdentity,
+ review: unknown
+): SelfRecoveryPreparation | undefined {
+ if (typeof window === 'undefined' || review !== 'reviewed_self_recovery')
+ return undefined;
+ const recordInput = reservedSendSnapshot(reserved),
+ ownershipInput = identityMessagingOwnership(session);
+ if (
+ !recordInput ||
+ !ownershipInput?.current() ||
+ ownershipInput.owner !== recordInput.owner
+ )
+ return undefined;
+ const pairInput = captureEnvelopePreparation(
+ session,
+ reserved,
+ 'reviewed_envelope_pair'
+ );
+ if (!pairInput) return undefined;
+ const record = recordInput,
+ ownership = ownershipInput,
+ pair = pairInput;
+ let active = true,
+ generation = 0,
+ busy = false,
+ phase: Phase = 'unsaved',
+ acknowledgement: SelfRecoveryAcknowledgement | undefined,
+ unsubscribe = () => {};
+ function stop() {
+ if (!active) return;
+ active = false;
+ generation++;
+ acknowledgement = undefined;
+ closeEnvelopePreparation(pair);
+ unsubscribe();
+ unsubscribe = () => {};
+ }
+ function current() {
+ const observed = reservedSendSnapshot(reserved);
+ if (
+ !active ||
+ !ownership.current() ||
+ !envelopePreparationSnapshot(pair) ||
+ !observed ||
+ observed.owner !== record.owner ||
+ observed.id !== record.id ||
+ observed.peer !== record.peer ||
+ observed.rumorHash !== record.rumorHash ||
+ observed.createdAt !== record.createdAt
+ ) {
+ stop();
+ return false;
+ }
+ return true;
+ }
+ function receipt() {
+ return current() &&
+ acknowledgement &&
+ selfRecoveryAcknowledgementSnapshot(acknowledgement)
+ ? acknowledgement
+ : undefined;
+ }
+ function snapshot(): Snapshot | undefined {
+ if (!current()) return undefined;
+ return {
+ state: phase,
+ busy,
+ owner: record.owner,
+ command: record.id,
+ copy:
+ phase === 'saved' && receipt()
+ ? 'Saved encrypted in this browser'
+ : phase === 'preparing'
+ ? 'Preparing encryption'
+ : phase === 'unknown_completion'
+ ? 'Encrypted save could not be confirmed. Review before continuing.'
+ : phase === 'needs_action'
+ ? 'Private text has no acknowledged encrypted save in this browser.'
+ : 'Private text is unsaved memory.'
+ };
+ }
+ async function peer(expected: SelfRecoveryAcknowledgement) {
+ if (!current() || busy || acknowledgement !== expected || !receipt())
+ return undefined;
+ const attempt = generation;
+ const verified = await verifySelfRecoveryAcknowledgement(
+ repository,
+ expected
+ );
+ return verified &&
+ current() &&
+ generation === attempt &&
+ acknowledgement === expected
+ ? pair
+ : undefined;
+ }
+ async function run(
+ reviewed: unknown
+ ): Promise<SelfRecoveryPreparationResult> {
+ if (reviewed !== 'reviewed_self_recovery') return { status: 'invalid' };
+ if (!current()) return { status: 'stopped' };
+ if (busy) return { status: 'busy' };
+ if (typeof window === 'undefined' || !navigator.locks?.request)
+ return { status: 'unavailable' };
+ busy = true;
+ const attempt = generation,
+ admitted = () => current() && attempt === generation;
+ try {
+ return await (async (): Promise<SelfRecoveryPreparationResult> => {
+ if (!admitted()) return { status: 'stopped' };
+ const base = await readSelfRecoveryBase(repository, reserved);
+ if (!admitted()) return { status: 'stopped' };
+ if (!base.ok) {
+ phase = 'needs_action';
+ return { status: base.reason };
+ }
+ if (acknowledgement) {
+ const valid = await verifySelfRecoveryAcknowledgement(
+ repository,
+ acknowledgement
+ );
+ if (!admitted()) return { status: 'stopped' };
+ if (valid) {
+ phase = 'saved';
+ return { status: 'saved' };
+ }
+ acknowledgement = undefined;
+ phase = 'needs_action';
+ return { status: 'conflict' };
+ }
+ const stored = privateRecordSnapshot(
+ base.value,
+ record.owner,
+ record.id
+ );
+ if (!stored) return { status: 'invalid_record' };
+ if (
+ stored.family === 'private_send_operation' &&
+ !preparedEnvelopeProof(pair, 'self')
+ ) {
+ phase = 'needs_action';
+ return { status: 'recovery_required' };
+ }
+ phase = 'preparing';
+ const prepared = await prepareEnvelopeRole(
+ pair,
+ 'self',
+ 'reviewed_pair_role'
+ );
+ if (!admitted()) return { status: 'stopped' };
+ if (prepared.status !== 'prepared' && prepared.status !== 'complete') {
+ phase = 'needs_action';
+ return { status: prepared.status };
+ }
+ const proof = preparedEnvelopeProof(pair, 'self');
+ if (!proof) {
+ phase = 'needs_action';
+ return { status: 'mismatch' };
+ }
+ // The lower crypto owner acquires this lock itself. Acquire it again
+ // only after crypto settles, then revalidate and CAS the stored base.
+ const saved = await navigator.locks.request(
+ 'harvestcircle:owner:' + record.owner,
+ { mode: 'exclusive', ifAvailable: true },
+ async (lock) => {
+ if (!lock) return { status: 'busy' as const };
+ if (!admitted()) return { status: 'stopped' as const };
+ return await commitSelfRecovery(
+ repository,
+ session,
+ reserved,
+ proof,
+ 'reviewed_self_commit'
+ );
+ }
+ );
+ if (!admitted()) return { status: 'stopped' };
+ if ('receipt' in saved) {
+ acknowledgement = saved.receipt;
+ phase = 'saved';
+ } else
+ phase =
+ saved.status === 'unknown_completion'
+ ? 'unknown_completion'
+ : 'needs_action';
+ return { status: saved.status };
+ })();
+ } catch {
+ phase = 'needs_action';
+ return { status: admitted() ? 'unavailable' : 'stopped' };
+ } finally {
+ busy = false;
+ }
+ }
+ const token = Object.freeze({}) as SelfRecoveryPreparation;
+ preparations.set(token, { run, snapshot, receipt, peer, stop });
+ unsubscribe = subscribeIdentityInvalidation(session, stop);
+ return current() ? token : undefined;
+}
+export function prepareSelfRecovery(
+ token: SelfRecoveryPreparation,
+ review: unknown
+): Promise<SelfRecoveryPreparationResult> {
+ return (
+ preparations.get(token)?.run(review) ??
+ Promise.resolve({ status: 'invalid' })
+ );
+}
+export function selfRecoveryPreparationSnapshot(
+ token: SelfRecoveryPreparation
+) {
+ return preparations.get(token)?.snapshot();
+}
+export function preparedSelfRecovery(token: SelfRecoveryPreparation) {
+ return preparations.get(token)?.receipt();
+}
+export function selfRecoveryPeerPreparation(
+ token: SelfRecoveryPreparation,
+ receipt: SelfRecoveryAcknowledgement
+): Promise<EnvelopePreparation | undefined> {
+ return preparations.get(token)?.peer(receipt) ?? Promise.resolve(undefined);
+}
+export function stopSelfRecoveryPreparation(
+ token: SelfRecoveryPreparation
+): void {
+ preparations.get(token)?.stop();
+}
diff --git a/web/src/lib/persistence/private-sends.ts b/web/src/lib/persistence/private-sends.ts
@@ -0,0 +1,283 @@
+import {
+ identityMessagingOwnership,
+ type IdentitySession
+} from '../runtime/identity-session.ts';
+import {
+ reservedSendSnapshot,
+ type ReservedSendIdentity
+} from '../messaging/send-identity.ts';
+import {
+ verifiedOutboundSnapshot,
+ type VerifiedOutboundEnvelope
+} from '../nostr/verify-outbound-envelope.ts';
+import {
+ verifyEnvelope,
+ verifiedEnvelopeSnapshot
+} from '../nostr/verified-envelope.ts';
+import {
+ decodePrivateRecord,
+ privateRecordSnapshot,
+ privateRecordWire,
+ type PrivateRecordHandle,
+ type PrivateSendReservation
+} from './private-records.ts';
+import {
+ loadPrivateRecord,
+ commitPrivateRecord,
+ type PrivateStorageRepository,
+ type PrivateStorageFailure,
+ type PrivateStorageResult
+} from './private-storage.ts';
+
+declare const acknowledgementBrand: unique symbol;
+export type SelfRecoveryAcknowledgement = Readonly<{
+ [acknowledgementBrand]: true;
+}>;
+type Saved = Readonly<{
+ record: PrivateSendReservation;
+ revision: number;
+ wire: string;
+ self: Readonly<{ eventId: string; wire: string }>;
+ current(): boolean;
+}>;
+const acknowledgements = new WeakMap<SelfRecoveryAcknowledgement, Saved>();
+export type SelfRecoveryCommitResult =
+ | Readonly<{
+ status: 'saved' | 'existing' | 'reconciled';
+ receipt: SelfRecoveryAcknowledgement;
+ }>
+ | Readonly<{ status: PrivateStorageFailure | 'invalid' | 'stopped' }>;
+
+// A namespace read is not a crypto proof or acknowledgement. Defensive owner,
+// command and immutable-rumor matching precedes any future SDK preparation.
+export async function readSelfRecoveryBase(
+ repository: PrivateStorageRepository,
+ reserved: ReservedSendIdentity
+): Promise<PrivateStorageResult<PrivateRecordHandle>> {
+ const record = reservedSendSnapshot(reserved);
+ if (!record) return { ok: false, reason: 'invalid_record' };
+ const loaded = await loadPrivateRecord(
+ repository,
+ 'private_sends',
+ record.id
+ );
+ if (!loaded.ok)
+ return {
+ ok: false,
+ reason: loaded.reason === 'invalid_scope' ? 'unavailable' : loaded.reason
+ };
+ const row = privateRecordSnapshot(loaded.value, record.owner, record.id);
+ if (
+ !row ||
+ row.family === 'received_envelope' ||
+ row.peer !== record.peer ||
+ row.rumorHash !== record.rumorHash ||
+ row.createdAt !== record.createdAt
+ )
+ return { ok: false, reason: 'invalid_record' };
+ if (!reservedSendSnapshot(reserved))
+ return { ok: false, reason: 'invalid_record' };
+ return loaded;
+}
+
+function input(
+ session: IdentitySession,
+ reserved: ReservedSendIdentity,
+ proof: VerifiedOutboundEnvelope
+) {
+ const record = reservedSendSnapshot(reserved),
+ ownership = identityMessagingOwnership(session),
+ observed = verifiedOutboundSnapshot(proof);
+ if (
+ !record ||
+ !ownership?.current() ||
+ !observed ||
+ ownership.owner !== record.owner ||
+ observed.role !== 'self' ||
+ observed.destination !== record.owner ||
+ observed.command !== record.id ||
+ observed.owner !== record.owner ||
+ observed.peer !== record.peer ||
+ observed.rumorHash !== record.rumorHash
+ )
+ return undefined;
+ const verified = verifyEnvelope(observed.wire),
+ event = verified.ok && verifiedEnvelopeSnapshot(verified.value);
+ if (!event || event.kind !== 1059) return undefined;
+ const current = () => {
+ const original = reservedSendSnapshot(reserved),
+ outer = verifiedOutboundSnapshot(proof);
+ return (
+ ownership.current() &&
+ original?.owner === record.owner &&
+ original.id === record.id &&
+ original.peer === record.peer &&
+ original.rumorHash === record.rumorHash &&
+ original.createdAt === record.createdAt &&
+ outer?.role === 'self' &&
+ outer.destination === record.owner &&
+ outer.wire === observed.wire
+ );
+ };
+ return current()
+ ? {
+ record,
+ current,
+ ownerCurrent: () => ownership.current(),
+ self: { eventId: event.id, wire: observed.wire }
+ }
+ : undefined;
+}
+
+// No signer/network await occurs in an IDB transaction. Only genuine current
+// factory association plus acknowledged exact ciphertext readback mints this
+// local fact. It grants no relay readiness, pair plan or transmission permission.
+export async function commitSelfRecovery(
+ repository: PrivateStorageRepository,
+ session: IdentitySession,
+ reserved: ReservedSendIdentity,
+ proof: VerifiedOutboundEnvelope,
+ review: unknown
+): Promise<SelfRecoveryCommitResult> {
+ if (typeof window === 'undefined' || review !== 'reviewed_self_commit')
+ return { status: 'invalid' };
+ const captured = input(session, reserved, proof);
+ if (!captured) return { status: 'invalid' };
+ try {
+ const loaded = await readSelfRecoveryBase(repository, reserved);
+ if (!captured.current()) return { status: 'stopped' };
+ if (!loaded.ok) return { status: loaded.reason };
+ const base = privateRecordSnapshot(
+ loaded.value,
+ captured.record.owner,
+ captured.record.id
+ );
+ if (!base || base.family === 'received_envelope')
+ return { status: 'invalid_record' };
+ let expected: PrivateRecordHandle,
+ status: 'saved' | 'existing' | 'reconciled';
+ if (base.family === 'private_send_operation') {
+ if (
+ base.self.eventId !== captured.self.eventId ||
+ base.self.wire !== captured.self.wire
+ )
+ return { status: 'conflict' };
+ expected = loaded.value;
+ status = 'existing';
+ } else {
+ const raw = JSON.stringify({
+ schema: 1,
+ family: 'private_send_operation',
+ owner: base.owner,
+ id: base.id,
+ revision: base.revision + 1,
+ peer: base.peer,
+ rumorHash: base.rumorHash,
+ createdAt: base.createdAt,
+ self: { eventId: captured.self.eventId, wire: captured.self.wire },
+ peerArtifact: null
+ });
+ const decoded = decodePrivateRecord(raw, base.owner, base.id);
+ if (!decoded.ok) return { status: 'invalid_record' };
+ expected = decoded.value;
+ if (!captured.current()) return { status: 'stopped' };
+ const committed = await commitPrivateRecord(
+ repository,
+ expected,
+ loaded.value
+ );
+ if (!captured.current()) return { status: 'stopped' };
+ if (!committed.ok && committed.reason !== 'unknown_completion')
+ return { status: committed.reason };
+ status = !committed.ok
+ ? 'reconciled'
+ : committed.value.state === 'existing'
+ ? 'existing'
+ : 'saved';
+ }
+ const expectedWire = privateRecordWire(
+ expected,
+ captured.record.owner,
+ captured.record.id
+ );
+ const readback = await loadPrivateRecord(
+ repository,
+ 'private_sends',
+ captured.record.id
+ );
+ if (!captured.current()) return { status: 'stopped' };
+ if (!readback.ok) return { status: 'unknown_completion' };
+ const wire = privateRecordWire(
+ readback.value,
+ captured.record.owner,
+ captured.record.id
+ ),
+ record = privateRecordSnapshot(
+ readback.value,
+ captured.record.owner,
+ captured.record.id
+ );
+ if (
+ !wire ||
+ wire !== expectedWire ||
+ !record ||
+ record.family !== 'private_send_operation' ||
+ record.self.eventId !== captured.self.eventId ||
+ record.self.wire !== captured.self.wire
+ )
+ return { status: 'conflict' };
+ const receipt = Object.freeze({}) as SelfRecoveryAcknowledgement;
+ acknowledgements.set(receipt, {
+ record: captured.record,
+ revision: record.revision,
+ wire,
+ self: captured.self,
+ // The acknowledged local fact survives clearing the crypto preparation.
+ // Effect permission remains separately gated by the live workflow.
+ current: captured.ownerCurrent
+ });
+ return { status, receipt };
+ } catch {
+ return { status: captured.current() ? 'unavailable' : 'stopped' };
+ }
+}
+
+export function selfRecoveryAcknowledgementSnapshot(
+ receipt: SelfRecoveryAcknowledgement
+) {
+ const saved = acknowledgements.get(receipt);
+ return saved?.current()
+ ? {
+ owner: saved.record.owner,
+ id: saved.record.id,
+ peer: saved.record.peer,
+ rumorHash: saved.record.rumorHash,
+ createdAt: saved.record.createdAt,
+ revision: saved.revision,
+ self: { eventId: saved.self.eventId, wire: saved.self.wire },
+ copy: 'Saved encrypted in this browser' as const,
+ fact: 'acknowledged_local_ciphertext_only' as const
+ }
+ : undefined;
+}
+
+// Recheck exact local evidence before a workflow advances. This does not
+// promise retention after the read; clearing/eviction and later CAS remain real.
+export async function verifySelfRecoveryAcknowledgement(
+ repository: PrivateStorageRepository,
+ receipt: SelfRecoveryAcknowledgement
+): Promise<boolean> {
+ const saved = acknowledgements.get(receipt);
+ if (!saved?.current()) return false;
+ const loaded = await loadPrivateRecord(
+ repository,
+ 'private_sends',
+ saved.record.id
+ );
+ return (
+ saved.current() &&
+ loaded.ok &&
+ privateRecordWire(loaded.value, saved.record.owner, saved.record.id) ===
+ saved.wire
+ );
+}
diff --git a/web/tests/e2e/harness/self-recovery.ts b/web/tests/e2e/harness/self-recovery.ts
@@ -0,0 +1,205 @@
+import { makeFixture as makeCryptoFixture } from './giftwrap-builder.ts';
+import {
+ openBrowserDatabase,
+ closeBrowserDatabase,
+ browserDatabaseTransaction
+} from '../../../src/lib/persistence/database.ts';
+import { createPrivateStorageRepository } from '../../../src/lib/persistence/private-storage.ts';
+import { reservedSendSnapshot } from '../../../src/lib/messaging/send-identity.ts';
+import {
+ captureEnvelopePreparation,
+ prepareEnvelopeRole,
+ preparedEnvelopeProof,
+ closeEnvelopePreparation
+} from '../../../src/lib/messaging/envelope-preparation.ts';
+import {
+ commitSelfRecovery,
+ selfRecoveryAcknowledgementSnapshot
+} from '../../../src/lib/persistence/private-sends.ts';
+import {
+ captureSelfRecoveryPreparation,
+ prepareSelfRecovery,
+ selfRecoveryPreparationSnapshot,
+ preparedSelfRecovery,
+ selfRecoveryPeerPreparation,
+ stopSelfRecoveryPreparation
+} from '../../../src/lib/messaging/prepare-send.ts';
+export {
+ commitSelfRecovery,
+ selfRecoveryAcknowledgementSnapshot,
+ captureSelfRecoveryPreparation,
+ prepareSelfRecovery,
+ selfRecoveryPreparationSnapshot,
+ preparedSelfRecovery,
+ selfRecoveryPeerPreparation,
+ stopSelfRecoveryPreparation
+};
+// Source-only genuine stock SDK plus actual Chromium IDB/Web Locks. Neither
+// this disposable provider nor these synthetic faults qualify an operator.
+export async function makeFixture() {
+ const marker = 'HCP081_PRIVATE_TEXT_MEMORY_ONLY_SENTINEL';
+ const cryptoFixture = await makeCryptoFixture(marker);
+ const opened = await openBrowserDatabase();
+ if (opened.state !== 'ready') throw Error('self storage unavailable');
+ const database = opened.owner,
+ repository = createPrivateStorageRepository(database, cryptoFixture.owner),
+ foreignRepository = createPrivateStorageRepository(
+ database,
+ cryptoFixture.peer
+ );
+ if (!repository || !foreignRepository)
+ throw Error('self storage namespace missing');
+ const preparation = captureSelfRecoveryPreparation(
+ repository,
+ cryptoFixture.identity,
+ cryptoFixture.reserved,
+ 'reviewed_self_recovery'
+ );
+ if (!preparation) throw Error('self preparation missing');
+ let restore = () => {},
+ releaseLock: (() => void) | undefined;
+ const pairs = new Set<ReturnType<typeof captureEnvelopePreparation>>();
+ async function proof(role: 'self' | 'peer') {
+ const pair = captureEnvelopePreparation(
+ cryptoFixture.identity,
+ cryptoFixture.reserved,
+ 'reviewed_envelope_pair'
+ );
+ if (!pair) throw Error('crypto pair missing');
+ pairs.add(pair);
+ if (
+ (await prepareEnvelopeRole(pair, 'self', 'reviewed_pair_role')).status !==
+ 'prepared' ||
+ (role === 'peer' &&
+ (await prepareEnvelopeRole(pair, 'peer', 'reviewed_pair_role'))
+ .status !== 'complete')
+ )
+ throw Error('role proof missing');
+ const proof = preparedEnvelopeProof(pair, role);
+ if (!proof) throw Error('peer proof missing');
+ return proof;
+ }
+ // The queued write and transaction are real. In unknown mode the fixture
+ // loses its acknowledgement after the actual put, then makes abort fail;
+ // actual completion/readback determine whether the original ciphertext exists.
+ function fault(mode: 'abort' | 'unknown') {
+ restore();
+ const put = Reflect.get<IDBObjectStore, 'put'>(
+ IDBObjectStore.prototype,
+ 'put'
+ ),
+ abort = Reflect.get<IDBTransaction, 'abort'>(
+ IDBTransaction.prototype,
+ 'abort'
+ );
+ let hits = 0;
+ const affected = new WeakSet<IDBTransaction>();
+ IDBObjectStore.prototype.put = function (
+ value: unknown,
+ key?: IDBValidKey
+ ) {
+ const request =
+ key === undefined ? put.call(this, value) : put.call(this, value, key);
+ if (this.name === 'private_sends' && hits === 0) {
+ hits++;
+ if (mode === 'abort') abort.call(this.transaction);
+ else {
+ affected.add(this.transaction);
+ throw Error('controlled lost acknowledgement');
+ }
+ }
+ return request;
+ };
+ IDBTransaction.prototype.abort = function () {
+ if (affected.has(this)) throw Error('controlled abort unavailable');
+ return abort.call(this);
+ };
+ restore = () => {
+ IDBObjectStore.prototype.put = put;
+ IDBTransaction.prototype.abort = abort;
+ };
+ return () => hits;
+ }
+ async function holdOwner() {
+ let entered: (() => void) | undefined;
+ const ready = new Promise<void>((resolve) => {
+ entered = resolve;
+ });
+ const held = navigator.locks.request(
+ 'harvestcircle:owner:' + cryptoFixture.owner,
+ async () => {
+ entered?.();
+ await new Promise<void>((resolve) => {
+ releaseLock = resolve;
+ });
+ }
+ );
+ await ready;
+ return () => {
+ releaseLock?.();
+ return held;
+ };
+ }
+ async function publicDraftRows() {
+ const tx = browserDatabaseTransaction(
+ database,
+ ['public_drafts'],
+ 'readonly'
+ ),
+ request = tx.objectStore('public_drafts').getAll();
+ return new Promise<string>((resolve, reject) => {
+ tx.addEventListener('complete', () =>
+ resolve(JSON.stringify(request.result))
+ );
+ tx.addEventListener('abort', () => reject(Error('inspection aborted')));
+ });
+ }
+ async function corruptReservation() {
+ const record = reservedSendSnapshot(cryptoFixture.reserved);
+ if (!record) throw Error('missing original reservation');
+ const tx = browserDatabaseTransaction(
+ database,
+ ['private_sends'],
+ 'readwrite'
+ );
+ tx.objectStore('private_sends').put({
+ owner: record.owner,
+ id: record.id,
+ wire: '{"schema":999}'
+ });
+ await new Promise<void>((resolve, reject) => {
+ tx.addEventListener('complete', () => resolve());
+ tx.addEventListener('abort', () =>
+ reject(Error('fixture write aborted'))
+ );
+ });
+ }
+ return {
+ ...cryptoFixture,
+ marker,
+ database,
+ repository,
+ foreignRepository,
+ preparation,
+ fault,
+ peerProof: () => proof('peer'),
+ selfProof: () => proof('self'),
+ holdOwner,
+ publicDraftRows,
+ corruptReservation,
+ closePeerPreparation: closeEnvelopePreparation,
+ pendingEncryption: () => {
+ const slot = cryptoFixture.slot();
+ return slot?.state === 'active' && slot.pending === 'encrypt';
+ },
+ closeStorage: () => closeBrowserDatabase(database),
+ close() {
+ restore();
+ releaseLock?.();
+ stopSelfRecoveryPreparation(preparation);
+ for (const pair of pairs) if (pair) closeEnvelopePreparation(pair);
+ closeBrowserDatabase(database);
+ cryptoFixture.close();
+ }
+ };
+}
diff --git a/web/tests/e2e/self-recovery.spec.ts b/web/tests/e2e/self-recovery.spec.ts
@@ -0,0 +1,460 @@
+import { expect, test, type Page } from '@playwright/test';
+import { build } from 'vite';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { createStaticHarness } from '../integration/harness/static.ts';
+import type * as Recovery from './harness/self-recovery.ts';
+declare global {
+ interface Window {
+ hcp081: typeof Recovery;
+ hcp081Fixture: Awaited<ReturnType<typeof Recovery.makeFixture>>;
+ }
+}
+let server: Awaited<ReturnType<typeof createStaticHarness>>, bundle: string;
+test.beforeAll(async () => {
+ server = await createStaticHarness();
+ const built = await build({
+ configFile: false,
+ logLevel: 'silent',
+ build: {
+ write: false,
+ minify: false,
+ lib: {
+ entry: fileURLToPath(
+ new URL('./harness/self-recovery.ts', import.meta.url)
+ ),
+ name: 'hcp081',
+ formats: ['iife']
+ }
+ }
+ });
+ const output = Array.isArray(built) ? built[0] : built;
+ if (!('output' in output)) throw Error('missing recovery bundle');
+ const chunks = output.output.filter((entry) => entry.type === 'chunk');
+ expect(chunks).toHaveLength(1);
+ bundle = chunks[0].code;
+ console.log(
+ JSON.stringify({
+ fixture: 'HCP081_REAL_SELF_IDB_ACKNOWLEDGEMENT',
+ bundleSha256: createHash('sha256').update(bundle).digest('hex'),
+ moduleIds: Object.keys(chunks[0].modules),
+ qualification:
+ 'Source-only genuine SDK/IDB/WebLocks; synthetic fault boundaries, no actual operator Q'
+ })
+ );
+});
+test.afterAll(async () => server.close());
+async function load(page: Page) {
+ await page.goto(server.url + '/search');
+ await page.addScriptTag({ content: bundle });
+ await page.evaluate(async () => {
+ window.hcp081Fixture = await window.hcp081.makeFixture();
+ });
+}
+test('self ciphertext is acknowledged before workflow peer permission, with no plaintext in either store', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async () => {
+ const f = window.hcp081Fixture,
+ s = window.hcp081;
+ try {
+ const before = s.selfRecoveryPreparationSnapshot(f.preparation),
+ base = f.counts();
+ const early = await s.selfRecoveryPeerPreparation(
+ f.preparation,
+ {} as Parameters<typeof s.selfRecoveryPeerPreparation>[1]
+ );
+ const saved = await s.prepareSelfRecovery(
+ f.preparation,
+ 'reviewed_self_recovery'
+ );
+ const receipt = s.preparedSelfRecovery(f.preparation),
+ ack = receipt && s.selfRecoveryAcknowledgementSnapshot(receipt),
+ rows = await f.stored(),
+ publicRows = await f.publicDraftRows();
+ const storedRows = JSON.parse(rows) as { wire: string }[];
+ return {
+ before: before?.state,
+ early: Boolean(early),
+ status: saved.status,
+ acknowledged: Boolean(ack),
+ copy: ack?.copy,
+ peerReady: Boolean(
+ receipt &&
+ (await s.selfRecoveryPeerPreparation(f.preparation, receipt))
+ ),
+ plaintext: rows.includes(f.marker) || publicRows.includes(f.marker),
+ selfOnly: storedRows[0].wire.includes('"peerArtifact":null'),
+ encrypts: f.counts().encrypts - base.encrypts,
+ signs: f.counts().signs - base.signs
+ };
+ } finally {
+ f.close();
+ }
+ });
+ expect(result).toEqual({
+ before: 'unsaved',
+ early: false,
+ status: 'saved',
+ acknowledged: true,
+ copy: 'Saved encrypted in this browser',
+ peerReady: true,
+ plaintext: false,
+ selfOnly: true,
+ encrypts: 1,
+ signs: 1
+ });
+});
+test('same-command retry reuses the exact self ciphertext without any additional SDK work', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async () => {
+ const f = window.hcp081Fixture,
+ s = window.hcp081;
+ try {
+ await s.prepareSelfRecovery(f.preparation, 'reviewed_self_recovery');
+ const first = await f.stored(),
+ before = f.counts(),
+ receipt = s.preparedSelfRecovery(f.preparation);
+ const retry = await s.prepareSelfRecovery(
+ f.preparation,
+ 'reviewed_self_recovery'
+ );
+ return {
+ status: retry.status,
+ equal: first === (await f.stored()),
+ sameReceipt: receipt === s.preparedSelfRecovery(f.preparation),
+ counts: JSON.stringify(before) === JSON.stringify(f.counts())
+ };
+ } finally {
+ f.close();
+ }
+ });
+ expect(result).toEqual({
+ status: 'saved',
+ equal: true,
+ sameReceipt: true,
+ counts: true
+ });
+});
+test('closed storage refuses acknowledgement and peer permission without a plaintext fallback', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async () => {
+ const f = window.hcp081Fixture,
+ s = window.hcp081;
+ try {
+ f.closeStorage();
+ const before = f.counts(),
+ result = await s.prepareSelfRecovery(
+ f.preparation,
+ 'reviewed_self_recovery'
+ );
+ return {
+ status: result.status,
+ receipt: Boolean(s.preparedSelfRecovery(f.preparation)),
+ counts: JSON.stringify(before) === JSON.stringify(f.counts()),
+ plaintext: (await f.stored()).includes(f.marker)
+ };
+ } finally {
+ f.close();
+ }
+ });
+ expect(result).toEqual({
+ status: 'unavailable',
+ receipt: false,
+ counts: true,
+ plaintext: false
+ });
+});
+test('actual aborted self write never grants local acknowledgement or peer permission', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async () => {
+ const f = window.hcp081Fixture,
+ s = window.hcp081;
+ try {
+ const prior = await f.stored(),
+ hits = f.fault('abort'),
+ result = await s.prepareSelfRecovery(
+ f.preparation,
+ 'reviewed_self_recovery'
+ );
+ return {
+ status: result.status,
+ hits: hits(),
+ receipt: Boolean(s.preparedSelfRecovery(f.preparation)),
+ unchanged: prior === (await f.stored())
+ };
+ } finally {
+ f.close();
+ }
+ });
+ expect(result).toEqual({
+ status: 'aborted',
+ hits: 1,
+ receipt: false,
+ unchanged: true
+ });
+});
+test('unknown write completion is reconciled by exact original ciphertext readback, never by regenerated crypto', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async () => {
+ const f = window.hcp081Fixture,
+ s = window.hcp081;
+ try {
+ const before = f.counts(),
+ hits = f.fault('unknown'),
+ result = await s.prepareSelfRecovery(
+ f.preparation,
+ 'reviewed_self_recovery'
+ );
+ const receipt = s.preparedSelfRecovery(f.preparation),
+ ack = receipt && s.selfRecoveryAcknowledgementSnapshot(receipt);
+ const rows = JSON.parse(await f.stored()) as { wire: string }[],
+ stored = JSON.parse(rows[0].wire) as { self: { wire: string } };
+ return {
+ status: result.status,
+ hits: hits(),
+ ack: Boolean(ack),
+ exact: Boolean(ack && stored.self.wire === ack.self.wire),
+ encrypts: f.counts().encrypts - before.encrypts,
+ signs: f.counts().signs - before.signs
+ };
+ } finally {
+ f.close();
+ }
+ });
+ expect(result).toEqual({
+ status: 'reconciled',
+ hits: 1,
+ ack: true,
+ exact: true,
+ encrypts: 1,
+ signs: 1
+ });
+});
+test('late encryption after actual Disconnect grants no receipt and cannot queue peer work', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async () => {
+ const f = window.hcp081Fixture,
+ s = window.hcp081;
+ try {
+ f.mode('hold_encrypt');
+ const pending = s.prepareSelfRecovery(
+ f.preparation,
+ 'reviewed_self_recovery'
+ );
+ for (let i = 0; i < 1800 && !f.pendingEncryption(); i++)
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ if (!f.pendingEncryption()) throw Error('encryption did not enter');
+ const repeated = await s.prepareSelfRecovery(
+ f.preparation,
+ 'reviewed_self_recovery'
+ );
+ f.disconnect();
+ f.settle();
+ const late = await pending;
+ const rows = JSON.parse(await f.stored()) as { wire: string }[],
+ stored = JSON.parse(rows[0].wire) as { family: string };
+ return {
+ repeated: repeated.status,
+ late: late.status,
+ receipt: Boolean(s.preparedSelfRecovery(f.preparation)),
+ plaintext: (await f.stored()).includes(f.marker),
+ family: stored.family
+ };
+ } finally {
+ f.settle();
+ f.close();
+ }
+ });
+ expect(result).toEqual({
+ repeated: 'busy',
+ late: 'stopped',
+ receipt: false,
+ plaintext: false,
+ family: 'private_send_reservation'
+ });
+});
+test('a competing owner lock refuses preparation without prompts and permits only explicit later retry', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async () => {
+ const f = window.hcp081Fixture,
+ s = window.hcp081;
+ let release: (() => Promise<void>) | undefined;
+ try {
+ release = await f.holdOwner();
+ const before = f.counts(),
+ refused = await s.prepareSelfRecovery(
+ f.preparation,
+ 'reviewed_self_recovery'
+ ),
+ unchanged = JSON.stringify(before) === JSON.stringify(f.counts());
+ await release();
+ release = undefined;
+ const later = await s.prepareSelfRecovery(
+ f.preparation,
+ 'reviewed_self_recovery'
+ );
+ return { refused: refused.status, unchanged, later: later.status };
+ } finally {
+ await release?.();
+ f.close();
+ }
+ });
+ expect(result).toEqual({ refused: 'busy', unchanged: true, later: 'saved' });
+});
+test('a new controller with existing self evidence requires explicit recovery instead of regenerating a wrapper', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async () => {
+ const f = window.hcp081Fixture,
+ s = window.hcp081;
+ try {
+ await s.prepareSelfRecovery(f.preparation, 'reviewed_self_recovery');
+ const second = s.captureSelfRecoveryPreparation(
+ f.repository,
+ f.identity,
+ f.reserved,
+ 'reviewed_self_recovery'
+ );
+ if (!second) throw Error('missing second controller');
+ const before = f.counts(),
+ bytes = await f.stored(),
+ result = await s.prepareSelfRecovery(second, 'reviewed_self_recovery');
+ s.stopSelfRecoveryPreparation(second);
+ return {
+ status: result.status,
+ unchanged: JSON.stringify(before) === JSON.stringify(f.counts()),
+ bytes: bytes === (await f.stored())
+ };
+ } finally {
+ f.close();
+ }
+ });
+ expect(result).toEqual({
+ status: 'recovery_required',
+ unchanged: true,
+ bytes: true
+ });
+});
+test('a genuine peer envelope or foreign namespace cannot acknowledge a self recovery record', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async () => {
+ const f = window.hcp081Fixture,
+ s = window.hcp081;
+ try {
+ const peer = await f.peerProof(),
+ prior = await f.stored();
+ const denied = await s.commitSelfRecovery(
+ f.repository,
+ f.identity,
+ f.reserved,
+ peer,
+ 'reviewed_self_commit'
+ );
+ const self = await f.selfProof();
+ const foreign = await s.commitSelfRecovery(
+ f.foreignRepository,
+ f.identity,
+ f.reserved,
+ self,
+ 'reviewed_self_commit'
+ );
+ return {
+ denied: denied.status,
+ foreignAcknowledged: 'receipt' in foreign,
+ unchanged: prior === (await f.stored()),
+ ack: Boolean(s.preparedSelfRecovery(f.preparation))
+ };
+ } finally {
+ f.close();
+ }
+ });
+ expect(result).toEqual({
+ denied: 'invalid',
+ foreignAcknowledged: false,
+ unchanged: true,
+ ack: false
+ });
+});
+test('unrecognized stored evidence is preserved and refuses crypto, reset and local acknowledgement', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async () => {
+ const f = window.hcp081Fixture,
+ s = window.hcp081;
+ try {
+ await f.corruptReservation();
+ const prior = await f.stored(),
+ before = f.counts(),
+ result = await s.prepareSelfRecovery(
+ f.preparation,
+ 'reviewed_self_recovery'
+ );
+ return {
+ status: result.status,
+ unchanged: prior === (await f.stored()),
+ counts: JSON.stringify(before) === JSON.stringify(f.counts()),
+ receipt: Boolean(s.preparedSelfRecovery(f.preparation))
+ };
+ } finally {
+ f.close();
+ }
+ });
+ expect(result).toEqual({
+ status: 'corrupt_record',
+ unchanged: true,
+ counts: true,
+ receipt: false
+ });
+});
+test('ending crypto preparation preserves the acknowledged local fact and revokes workflow peer permission', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async () => {
+ const f = window.hcp081Fixture,
+ s = window.hcp081;
+ try {
+ await s.prepareSelfRecovery(f.preparation, 'reviewed_self_recovery');
+ const receipt = s.preparedSelfRecovery(f.preparation);
+ if (!receipt) throw Error('missing actual receipt');
+ const pair = await s.selfRecoveryPeerPreparation(f.preparation, receipt);
+ if (!pair) throw Error('missing acknowledged permission');
+ const before = await f.stored();
+ f.closePeerPreparation(pair);
+ return {
+ savedFact: Boolean(s.selfRecoveryAcknowledgementSnapshot(receipt)),
+ workflow: Boolean(s.selfRecoveryPreparationSnapshot(f.preparation)),
+ peer: Boolean(
+ await s.selfRecoveryPeerPreparation(f.preparation, receipt)
+ ),
+ unchanged: before === (await f.stored())
+ };
+ } finally {
+ f.close();
+ }
+ });
+ expect(result).toEqual({
+ savedFact: true,
+ workflow: false,
+ peer: false,
+ unchanged: true
+ });
+});
diff --git a/web/tests/unit/self-recovery.test.ts b/web/tests/unit/self-recovery.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import type { IdentitySession } from '../../src/lib/runtime/identity-session.ts';
+import type { ReservedSendIdentity } from '../../src/lib/messaging/send-identity.ts';
+import type { VerifiedOutboundEnvelope } from '../../src/lib/nostr/verify-outbound-envelope.ts';
+import type { PrivateStorageRepository } from '../../src/lib/persistence/private-storage.ts';
+import {
+ commitSelfRecovery,
+ selfRecoveryAcknowledgementSnapshot,
+ type SelfRecoveryAcknowledgement
+} from '../../src/lib/persistence/private-sends.ts';
+import {
+ captureSelfRecoveryPreparation,
+ prepareSelfRecovery,
+ selfRecoveryPreparationSnapshot,
+ preparedSelfRecovery,
+ selfRecoveryPeerPreparation,
+ stopSelfRecoveryPreparation,
+ type SelfRecoveryPreparation
+} from '../../src/lib/messaging/prepare-send.ts';
+
+describe('self recovery is an explicit current-owner local acknowledgement', () => {
+ it('SSR and forged namespaces/identities cannot start crypto or persistence', () => {
+ expect(
+ captureSelfRecoveryPreparation(
+ {} as PrivateStorageRepository,
+ {} as IdentitySession,
+ {} as ReservedSendIdentity,
+ 'reviewed_self_recovery'
+ )
+ ).toBeUndefined();
+ });
+ it('forged preparation and receipt objects grant no acknowledgement or peer permission', async () => {
+ const preparation = {} as SelfRecoveryPreparation,
+ receipt = {} as SelfRecoveryAcknowledgement;
+ expect(
+ await prepareSelfRecovery(preparation, 'reviewed_self_recovery')
+ ).toEqual({ status: 'invalid' });
+ expect(selfRecoveryPreparationSnapshot(preparation)).toBeUndefined();
+ expect(preparedSelfRecovery(preparation)).toBeUndefined();
+ expect(
+ await selfRecoveryPeerPreparation(preparation, receipt)
+ ).toBeUndefined();
+ expect(selfRecoveryAcknowledgementSnapshot(receipt)).toBeUndefined();
+ expect(() => stopSelfRecoveryPreparation(preparation)).not.toThrow();
+ });
+ it('detached factory data cannot produce a durable receipt', async () => {
+ expect(
+ await commitSelfRecovery(
+ {} as PrivateStorageRepository,
+ {} as IdentitySession,
+ {} as ReservedSendIdentity,
+ {} as VerifiedOutboundEnvelope,
+ 'reviewed_self_commit'
+ )
+ ).toEqual({ status: 'invalid' });
+ });
+ it('unreviewed values are rejected without coercion or provider callbacks', async () => {
+ let conversions = 0;
+ const review = {
+ toString() {
+ conversions++;
+ return 'reviewed_self_commit';
+ }
+ };
+ expect(
+ await commitSelfRecovery(
+ {} as PrivateStorageRepository,
+ {} as IdentitySession,
+ {} as ReservedSendIdentity,
+ {} as VerifiedOutboundEnvelope,
+ review
+ )
+ ).toEqual({ status: 'invalid' });
+ expect(
+ captureSelfRecoveryPreparation(
+ {} as PrivateStorageRepository,
+ {} as IdentitySession,
+ {} as ReservedSendIdentity,
+ review
+ )
+ ).toBeUndefined();
+ expect(conversions).toBe(0);
+ });
+});