commit 5b8e6b49a4a2d4e26ec587c707008684251cbd83
parent f2fd85be92f048fd964dbc9fe86cce24c829a503
Author: triesap <tyson@radroots.org>
Date: Fri, 9 Oct 2026 03:30:08 +0000
messages: recheck routing on explicit send resumption (HCP-088)
- Review current approved destinations for the same encrypted message
- Fence removed and unavailable inbox routes pending explicit consent
- Preserve ciphertext and earlier relay facts through exact storage readback
- Verify route changes and failed admission with real browser tests
Diffstat:
7 files changed, 1004 insertions(+), 6 deletions(-)
diff --git a/web/src/lib/messaging/resume-routing.ts b/web/src/lib/messaging/resume-routing.ts
@@ -0,0 +1,32 @@
+import {
+ capturePairedRoutingReview,
+ pairedRoutingReviewSnapshot,
+ approvePairedRoutingReview,
+ type PairedRoutingReview,
+ type PairedDeliveryAcknowledgement
+} from '../persistence/private-sends.ts';
+import type { PrivateStorageRepository } from '../persistence/private-storage.ts';
+import type { IdentitySession } from '../runtime/identity-session.ts';
+import type { PairedDeliveryContext } from './prepare-send.ts';
+export type PrivateResumeRouting = PairedRoutingReview;
+// Sample actual current discovery owners and a qualified policy. This review
+// exposes exact destination/head changes and performs no automatic publication.
+// Explicit consent changes only local routes of the same immutable artifacts;
+// the separate bounded retry workflow owns every subsequent network attempt.
+export function capturePrivateResumeRouting(
+ repository: PrivateStorageRepository,
+ session: IdentitySession,
+ receipt: PairedDeliveryAcknowledgement,
+ current: Pick<PairedDeliveryContext, 'policy' | 'own' | 'other'>,
+ review: unknown
+): PrivateResumeRouting | undefined {
+ return capturePairedRoutingReview(
+ repository,
+ session,
+ receipt,
+ current,
+ review
+ );
+}
+export const privateResumeRoutingSnapshot = pairedRoutingReviewSnapshot;
+export const approvePrivateResumeRouting = approvePairedRoutingReview;
diff --git a/web/src/lib/persistence/private-records.ts b/web/src/lib/persistence/private-records.ts
@@ -61,6 +61,9 @@ export type PrivateTargetReceipt = Readonly<{
export type PrivateDeliveryPlan = Readonly<{
state: 'prepared';
routes: InboxRouteSnapshot;
+ // Earlier reviewed destinations retain the scope of immutable old facts.
+ // These local snapshots never qualify an inbox or authorize replay.
+ previousRoutes?: readonly InboxRouteSnapshot[];
}>;
export type ReceivedEnvelopeRecord = Readonly<{
schema: 1;
@@ -181,11 +184,28 @@ function deliveryPlan(
peer: string
): value is PrivateDeliveryPlan {
return (
- exactLocalFields(value, ['state', 'routes']) &&
+ exactLocalFields(value, [
+ 'state',
+ 'routes',
+ ...(typeof value === 'object' &&
+ value !== null &&
+ 'previousRoutes' in value
+ ? ['previousRoutes']
+ : [])
+ ]) &&
value.state === 'prepared' &&
exactLocalFields(value.routes, ['peer', 'archive']) &&
persistedRoute(value.routes.peer, peer, 'peer') &&
- persistedRoute(value.routes.archive, owner, 'self_archive')
+ persistedRoute(value.routes.archive, owner, 'self_archive') &&
+ (value.previousRoutes === undefined ||
+ (Array.isArray(value.previousRoutes) &&
+ value.previousRoutes.length > 0 &&
+ value.previousRoutes.every(
+ (previous) =>
+ exactLocalFields(previous, ['peer', 'archive']) &&
+ persistedRoute(previous.peer, peer, 'peer') &&
+ persistedRoute(previous.archive, owner, 'self_archive')
+ )))
);
}
// JSON.parse keeps only the last duplicate key. Retaining the original outer
@@ -400,7 +420,13 @@ function receipt(
const route = value.role === 'peer' ? plan.routes.peer : plan.routes.archive,
outer = value.role === 'peer' ? peer : self;
return (
- route.targets.includes(value.origin) &&
+ (route.targets.includes(value.origin) ||
+ (plan.previousRoutes ?? []).some((previous) =>
+ (value.role === 'peer'
+ ? previous.peer
+ : previous.archive
+ ).targets.includes(value.origin as string)
+ )) &&
value.eventId === outer.eventId &&
(value.status === 'readback'
? value.readbackWire === outer.wire
diff --git a/web/src/lib/persistence/private-sends.ts b/web/src/lib/persistence/private-sends.ts
@@ -26,6 +26,7 @@ import {
} from './private-records.ts';
import {
inboxRoutePlanSnapshot,
+ createInboxRoutePlan,
recheckInboxRoutePlan,
type InboxRoutePlan
} from '../messaging/inbox-routing.ts';
@@ -319,6 +320,244 @@ const pairedAcknowledgements = new WeakMap<
PairedDeliveryAcknowledgement,
Paired
>();
+declare const routingReviewBrand: unique symbol;
+export type PairedRoutingReview = Readonly<{ [routingReviewBrand]: true }>;
+type RoutingReview = Readonly<{
+ repository: PrivateStorageRepository;
+ session: IdentitySession;
+ receipt: PairedDeliveryAcknowledgement;
+ saved: Paired;
+ context: PairedDeliveryContext;
+ changed: boolean;
+ current(): boolean;
+}>;
+const routingReviewStates = new WeakMap<PairedRoutingReview, RoutingReview>();
+const pendingRoutingReviews = new WeakMap<
+ PairedDeliveryAcknowledgement,
+ PairedRoutingReview
+>();
+// Genuine current discovery is a reviewed destination candidate, not Send.
+// Detection immediately fences previously captured retry/publication custody.
+export function capturePairedRoutingReview(
+ repository: PrivateStorageRepository,
+ session: IdentitySession,
+ receipt: PairedDeliveryAcknowledgement,
+ candidate: Pick<PairedDeliveryContext, 'policy' | 'own' | 'other'>,
+ review: unknown
+): PairedRoutingReview | undefined {
+ if (
+ typeof window === 'undefined' ||
+ review !== 'reviewed_private_route_resolution'
+ )
+ return undefined;
+ const saved = pairedAcknowledgements.get(receipt),
+ ownership = identityMessagingOwnership(session);
+ if (
+ !saved?.current() ||
+ !saved.record.deliveryPlan ||
+ !saved.record.peerArtifact ||
+ !ownership?.current() ||
+ ownership.owner !== saved.record.owner
+ )
+ return undefined;
+ // Unready current resolution must also fence the old destination. No
+ // fallback capability survives merely because there is no new usable plan.
+ const token = Object.freeze({}) as PairedRoutingReview;
+ pendingRoutingReviews.set(receipt, token);
+ const plan = createInboxRoutePlan(
+ candidate.policy,
+ saved.record.owner,
+ saved.record.peer,
+ candidate.own,
+ candidate.other
+ );
+ if (!plan) return undefined;
+ const context = {
+ plan,
+ policy: candidate.policy,
+ own: candidate.own,
+ other: candidate.other
+ };
+ const routes = inboxRoutePlanSnapshot(plan);
+ if (
+ !routes ||
+ routes.peer.author !== saved.record.peer ||
+ routes.archive.author !== saved.record.owner ||
+ recheckInboxRoutePlan(
+ context.plan,
+ context.policy,
+ context.own,
+ context.other
+ ) !== 'unchanged'
+ )
+ return undefined;
+ const current = () =>
+ saved.current() &&
+ ownership.current() &&
+ pendingRoutingReviews.get(receipt) === token &&
+ recheckInboxRoutePlan(
+ context.plan,
+ context.policy,
+ context.own,
+ context.other
+ ) === 'unchanged';
+ routingReviewStates.set(token, {
+ repository,
+ session,
+ receipt,
+ saved,
+ context,
+ changed:
+ JSON.stringify(routes) !==
+ JSON.stringify(saved.record.deliveryPlan.routes),
+ current
+ });
+ return token;
+}
+export function pairedRoutingReviewSnapshot(token: PairedRoutingReview) {
+ const state = routingReviewStates.get(token);
+ if (!state?.current() || !state.saved.record.deliveryPlan) return undefined;
+ const previous = state.saved.record.deliveryPlan.routes,
+ next = inboxRoutePlanSnapshot(state.context.plan);
+ if (!next) return undefined;
+ function changes(role: 'peer' | 'archive') {
+ return {
+ removed: previous[role].targets.filter(
+ (origin) => !next![role].targets.includes(origin)
+ ),
+ added: next![role].targets.filter(
+ (origin) => !previous[role].targets.includes(origin)
+ )
+ };
+ }
+ return {
+ owner: state.saved.record.owner,
+ peer: state.saved.record.peer,
+ command: state.saved.record.id,
+ status: state.changed
+ ? ('review_required' as const)
+ : ('unchanged' as const),
+ previous: JSON.parse(JSON.stringify(previous)) as typeof previous,
+ next,
+ changes: { peer: changes('peer'), archive: changes('archive') },
+ fact: 'destination_review_only' as const
+ };
+}
+export type PairedRoutingResult =
+ | Readonly<{
+ status: 'updated' | 'unchanged';
+ receipt: PairedDeliveryAcknowledgement;
+ }>
+ | Readonly<{ status: PrivateStorageFailure | 'invalid' | 'stopped' }>;
+export async function approvePairedRoutingReview(
+ token: PairedRoutingReview,
+ review: unknown
+): Promise<PairedRoutingResult> {
+ const state = routingReviewStates.get(token);
+ if (
+ !state ||
+ review !== 'reviewed_private_destination_update' ||
+ !navigator.locks?.request
+ )
+ return { status: 'invalid' };
+ if (!state.current()) return { status: 'stopped' };
+ const { repository, session, receipt, saved, context } = state;
+ try {
+ const owner = await recheckIdentityOwner(session);
+ if (
+ owner.state !== 'messaging_capable' ||
+ owner.publicKey !== saved.record.owner ||
+ owner.admission === 'busy' ||
+ !state.current()
+ )
+ return { status: 'stopped' };
+ return await navigator.locks.request(
+ 'harvestcircle:owner:' + saved.record.owner,
+ { mode: 'exclusive', ifAvailable: true },
+ async (lock) => {
+ if (!lock || !state.current()) return { status: 'stopped' as const };
+ const base = await loadPrivateRecord(
+ repository,
+ 'private_sends',
+ saved.record.id
+ );
+ if (!state.current()) return { status: 'stopped' as const };
+ if (!base.ok) return { status: base.reason };
+ if (
+ privateRecordWire(base.value, saved.record.owner, saved.record.id) !==
+ saved.wire
+ )
+ return { status: 'conflict' as const };
+ const routes = inboxRoutePlanSnapshot(context.plan),
+ row = saved.record;
+ if (!routes || !row.deliveryPlan) return { status: 'invalid' as const };
+ let expected = base.value;
+ if (state.changed) {
+ if (row.revision === Number.MAX_SAFE_INTEGER)
+ return { status: 'invalid_record' as const };
+ const decoded = decodePrivateRecord(
+ JSON.stringify({
+ ...row,
+ revision: row.revision + 1,
+ deliveryPlan: {
+ state: 'prepared',
+ routes,
+ previousRoutes: [
+ ...(row.deliveryPlan.previousRoutes ?? []),
+ row.deliveryPlan.routes
+ ]
+ }
+ }),
+ row.owner,
+ row.id
+ );
+ if (!decoded.ok) return { status: 'invalid_record' as const };
+ expected = decoded.value;
+ if (!state.current()) return { status: 'stopped' as const };
+ const committed = await commitPrivateRecord(
+ repository,
+ expected,
+ base.value
+ );
+ if (!state.current())
+ return { status: 'unknown_completion' as const };
+ if (!committed.ok) return { status: committed.reason };
+ }
+ const loaded = await loadPrivateRecord(
+ repository,
+ 'private_sends',
+ row.id
+ );
+ if (!state.current() || !loaded.ok)
+ return { status: 'unknown_completion' as const };
+ const wire = privateRecordWire(loaded.value, row.owner, row.id),
+ next = privateRecordSnapshot(loaded.value, row.owner, row.id);
+ if (
+ !wire ||
+ wire !== privateRecordWire(expected, row.owner, row.id) ||
+ !next ||
+ next.family !== 'private_send_operation' ||
+ JSON.stringify(next.self) !== JSON.stringify(row.self) ||
+ JSON.stringify(next.peerArtifact) !== JSON.stringify(row.peerArtifact)
+ )
+ return { status: 'conflict' as const };
+ pairedAcknowledgements.set(receipt, {
+ record: next,
+ wire,
+ current: saved.current
+ });
+ pendingRoutingReviews.delete(receipt);
+ routingReviewStates.delete(token);
+ return {
+ status: state.changed ? ('updated' as const) : ('unchanged' as const),
+ receipt
+ };
+ }
+ );
+ } catch {
+ return { status: state.current() ? 'unavailable' : 'stopped' };
+ }
+}
// Explicit restart admission authenticates the self recovery copy and verifies
// exact durable pair custody. It does not decrypt or newly authenticate the
// nested peer ciphertext, regenerate either artifact, or perform publication.
@@ -592,6 +831,7 @@ export function pairedDeliveryAcknowledgementSnapshot(
const saved = pairedAcknowledgements.get(receipt);
if (
!saved?.current() ||
+ pendingRoutingReviews.has(receipt) ||
!saved.record.peerArtifact ||
!saved.record.deliveryPlan
)
@@ -617,7 +857,7 @@ export async function verifyPairedDeliveryAcknowledgement(
receipt: PairedDeliveryAcknowledgement
): Promise<boolean> {
const saved = pairedAcknowledgements.get(receipt);
- if (!saved?.current()) return false;
+ if (!saved?.current() || pendingRoutingReviews.has(receipt)) return false;
const loaded = await loadPrivateRecord(
repository,
'private_sends',
@@ -625,6 +865,7 @@ export async function verifyPairedDeliveryAcknowledgement(
);
return (
saved.current() &&
+ !pendingRoutingReviews.has(receipt) &&
loaded.ok &&
privateRecordWire(loaded.value, saved.record.owner, saved.record.id) ===
saved.wire
@@ -640,6 +881,7 @@ export function pairedDeliveryRecordMatches(
const saved = pairedAcknowledgements.get(receipt);
return (
!!saved?.current() &&
+ !pendingRoutingReviews.has(receipt) &&
privateRecordWire(record, saved.record.owner, saved.record.id) ===
saved.wire
);
@@ -655,6 +897,7 @@ export function pairedDeliveryTargetAccepted(
const saved = pairedAcknowledgements.get(receipt);
return (
!!saved?.current() &&
+ !pendingRoutingReviews.has(receipt) &&
(saved.record.receipts ?? []).some(
(fact) =>
fact.role === role &&
@@ -673,7 +916,8 @@ export async function commitPairedDeliveryReceipt(
receiptWire: unknown
): Promise<PrivateReceiptCommitResult> {
const saved = pairedAcknowledgements.get(receipt);
- if (!saved?.current()) return { status: 'invalid' };
+ if (!saved?.current() || pendingRoutingReviews.has(receipt))
+ return { status: 'invalid' };
try {
const loaded = await loadPrivateRecord(
repository,
diff --git a/web/src/lib/persistence/private-storage.ts b/web/src/lib/persistence/private-storage.ts
@@ -212,7 +212,15 @@ function validTransition(
(JSON.stringify(base.self) === JSON.stringify(next.self) &&
(base.deliveryPlan === undefined ||
JSON.stringify(base.deliveryPlan) ===
- JSON.stringify(next.deliveryPlan)) &&
+ JSON.stringify(next.deliveryPlan) ||
+ (!!next.deliveryPlan &&
+ JSON.stringify(base.deliveryPlan.routes) !==
+ JSON.stringify(next.deliveryPlan.routes) &&
+ JSON.stringify(next.deliveryPlan.previousRoutes) ===
+ JSON.stringify([
+ ...(base.deliveryPlan.previousRoutes ?? []),
+ base.deliveryPlan.routes
+ ]))) &&
(base.receipts ?? []).every(
(fact, index) =>
JSON.stringify(fact) === JSON.stringify(next.receipts?.[index])
diff --git a/web/tests/e2e/harness/resume-routing.ts b/web/tests/e2e/harness/resume-routing.ts
@@ -0,0 +1,269 @@
+import { makeFixture as recoveryFixture } from './resume-preparation.ts';
+import { finalizeEvent, getPublicKey } from 'applesauce-core/helpers';
+import {
+ readRelayPolicy,
+ validateRelayPolicy
+} from '../../../src/lib/config/relays.ts';
+import {
+ createPublicScheduler,
+ createPublicRun,
+ openInboxRequest,
+ closePublicScheduler
+} from '../../../src/lib/nostr/request-scope.ts';
+import { createInboxResolver } from '../../../src/lib/messaging/resolve-inbox.ts';
+import { createInboxRoutePlan } from '../../../src/lib/messaging/inbox-routing.ts';
+import {
+ createPrivateSession,
+ closePrivateSession
+} from '../../../src/lib/runtime/private-session.ts';
+import {
+ getPrivatePool,
+ closePrivatePool
+} from '../../../src/lib/nostr/private-pool.ts';
+import {
+ resumeEncryptedPreparation,
+ qualifyRecoveredPrivatePair,
+ stopResumePreparation
+} from '../../../src/lib/messaging/resume-preparation.ts';
+import {
+ capturePrivateRetry,
+ runPrivateRetry,
+ type PrivateRetry
+} from '../../../src/lib/messaging/retry-send.ts';
+import {
+ capturePrivateResumeRouting,
+ privateResumeRoutingSnapshot,
+ approvePrivateResumeRouting,
+ type PrivateResumeRouting
+} from '../../../src/lib/messaging/resume-routing.ts';
+import type { PairedDeliveryAcknowledgement } from '../../../src/lib/persistence/private-sends.ts';
+import type { PairedDeliveryContext } from '../../../src/lib/messaging/prepare-send.ts';
+export async function makeFixture() {
+ const f = await recoveryFixture();
+ const origins = [
+ 'wss://peer.example.org',
+ 'wss://archive.example.org',
+ 'wss://new-peer.example.org'
+ ];
+ const policy = validateRelayPolicy(
+ JSON.stringify({
+ ...readRelayPolicy(f.context.policy),
+ messagingEnabled: true,
+ inbox: origins.map((origin) => ({ origin, read: true, write: true }))
+ })
+ );
+ if (!policy) throw Error('missing qualified fixture policy');
+ const plan = createInboxRoutePlan(
+ policy,
+ f.owner,
+ f.peer,
+ f.context.own,
+ f.context.other
+ );
+ if (!plan) throw Error('missing original route');
+ const original = { ...f.context, policy, plan };
+ const session = await createPrivateSession(
+ f.identity,
+ 'reviewed_private_session'
+ );
+ if (!session) throw Error('missing private session');
+ const pool = getPrivatePool(session, policy, origins);
+ if (!pool) throw Error('missing private pool');
+ const resume = f.capture();
+ await resumeEncryptedPreparation(resume, original, 'reviewed_private_resume');
+ const prepared = await qualifyRecoveredPrivatePair(
+ resume,
+ original,
+ 'reviewed_stored_private_retry'
+ );
+ if (!('receipt' in prepared)) throw Error('missing genuine pair');
+ const receipt: PairedDeliveryAcknowledgement = prepared.receipt;
+ const schedulers: ReturnType<typeof createPublicScheduler>[] = [];
+ let context: PairedDeliveryContext = original,
+ token: PrivateResumeRouting | undefined,
+ heldRetry: PrivateRetry | undefined,
+ current = true;
+ let restore = () => {};
+ function resolve(
+ origin: string,
+ role: 'peer' | 'self_archive',
+ peerSwitch = false,
+ complete = true
+ ) {
+ const key = new Uint8Array(32).fill(
+ role === 'self_archive' ? 83 : peerSwitch ? 85 : 84
+ );
+ let event;
+ try {
+ event = finalizeEvent(
+ {
+ kind: 10050,
+ created_at:
+ origin === 'wss://peer.example.org' ||
+ origin === 'wss://archive.example.org'
+ ? 100
+ : 101,
+ tags: [['relay', origin]],
+ content: ''
+ },
+ key
+ );
+ } finally {
+ key.fill(0);
+ }
+ const scheduler = createPublicScheduler({
+ now: () => 0,
+ schedule: () => () => {}
+ });
+ schedulers.push(scheduler);
+ const run = createPublicRun(scheduler, policy!);
+ return createInboxResolver(
+ run,
+ event.pubkey,
+ (next) =>
+ openInboxRequest(
+ run,
+ event.pubkey,
+ (sink) => {
+ sink({
+ type: 'EVENT',
+ from: 'wss://discovery.example.org',
+ id: 'routing-fixture',
+ event
+ });
+ if (complete)
+ sink({
+ type: 'EOSE',
+ from: 'wss://discovery.example.org',
+ id: 'routing-fixture'
+ });
+ return () => {};
+ },
+ next
+ ),
+ () => current
+ );
+ }
+ return {
+ ...f,
+ capture(
+ destination = 'wss://new-peer.example.org',
+ archive = 'wss://archive.example.org',
+ peerSwitch = false,
+ complete = true
+ ) {
+ const own = resolve(archive, 'self_archive'),
+ other = resolve(destination, 'peer', peerSwitch, complete);
+ const alternate = new Uint8Array(32).fill(85);
+ let intended;
+ try {
+ intended = peerSwitch ? getPublicKey(alternate) : f.peer;
+ } finally {
+ alternate.fill(0);
+ }
+ const next = createInboxRoutePlan(policy, f.owner, intended, own, other);
+ token = capturePrivateResumeRouting(
+ f.repository,
+ f.identity,
+ receipt,
+ { policy, own, other },
+ 'reviewed_private_route_resolution'
+ );
+ // A changed recipient cannot produce a reviewed same-peer update.
+ if (!next) {
+ return false;
+ }
+ context = { policy, plan: next, own, other };
+ return !!token;
+ },
+ snapshot: () => token && privateResumeRoutingSnapshot(token),
+ async approve(review: unknown = 'reviewed_private_destination_update') {
+ if (!token) return { status: 'invalid' as const };
+ try {
+ return await approvePrivateResumeRouting(token, review);
+ } finally {
+ restore();
+ }
+ },
+ async retry(old = false) {
+ const retry = capturePrivateRetry(
+ f.repository,
+ session,
+ receipt,
+ old ? original : context,
+ pool,
+ 'reviewed_private_retry'
+ );
+ return retry
+ ? runPrivateRetry(retry, 'reviewed_private_retry')
+ : { status: 'invalid' as const };
+ },
+ captureHeld() {
+ heldRetry = capturePrivateRetry(
+ f.repository,
+ session,
+ receipt,
+ original,
+ pool,
+ 'reviewed_private_retry'
+ );
+ return !!heldRetry;
+ },
+ runHeld() {
+ return heldRetry
+ ? runPrivateRetry(heldRetry, 'reviewed_private_retry')
+ : Promise.resolve({ status: 'invalid' as const });
+ },
+ stale() {
+ current = false;
+ },
+ fault(kind: 'abort' | 'readback') {
+ const put = Reflect.get<IDBObjectStore, 'put'>(
+ IDBObjectStore.prototype,
+ 'put'
+ ),
+ cursor = Reflect.get<IDBIndex, 'openCursor'>(
+ IDBIndex.prototype,
+ 'openCursor'
+ );
+ let armed = false;
+ IDBObjectStore.prototype.put = function (value, key) {
+ const request =
+ key === undefined
+ ? put.call(this, value)
+ : put.call(this, value, key);
+ if (this.name === 'private_sends') {
+ armed = true;
+ if (kind === 'abort') this.transaction.abort();
+ }
+ return request;
+ };
+ IDBIndex.prototype.openCursor = function (...args) {
+ if (
+ armed &&
+ kind === 'readback' &&
+ this.objectStore.name === 'private_sends' &&
+ this.objectStore.transaction.mode === 'readonly'
+ )
+ throw new DOMException(
+ 'fixture actual post-put readback failure',
+ 'InvalidStateError'
+ );
+ return cursor.apply(this, args);
+ };
+ restore = () => {
+ IDBObjectStore.prototype.put = put;
+ IDBIndex.prototype.openCursor = cursor;
+ };
+ },
+ close() {
+ restore();
+ current = false;
+ for (const s of schedulers) closePublicScheduler(s);
+ stopResumePreparation(resume);
+ closePrivatePool(pool);
+ closePrivateSession(session);
+ f.close();
+ }
+ };
+}
diff --git a/web/tests/e2e/resume-routing.spec.ts b/web/tests/e2e/resume-routing.spec.ts
@@ -0,0 +1,385 @@
+import { test, expect } from '@playwright/test';
+import { build } from 'vite';
+import { fileURLToPath } from 'node:url';
+import { once } from 'node:events';
+import { WebSocketServer } from 'ws';
+import { createStaticHarness } from '../integration/harness/static.ts';
+import type * as Fixture from './harness/resume-routing.ts';
+declare global {
+ interface Window {
+ hcp088: typeof Fixture;
+ hcp088Fixture: Awaited<ReturnType<typeof Fixture.makeFixture>>;
+ }
+}
+let server: Awaited<ReturnType<typeof createStaticHarness>>,
+ sockets: WebSocketServer,
+ endpoint: string,
+ bundle: string;
+let events: { origin: string; wire: string }[] = [];
+test.beforeAll(async () => {
+ server = await createStaticHarness();
+ sockets = new WebSocketServer({
+ host: '127.0.0.1',
+ port: 0,
+ maxPayload: 65536
+ });
+ await once(sockets, 'listening');
+ const address = sockets.address();
+ if (!address || typeof address === 'string')
+ throw Error('loopback unavailable');
+ endpoint = 'ws://127.0.0.1:' + address.port;
+ sockets.on('connection', (socket, request) =>
+ socket.on('message', (bytes) => {
+ const raw = Buffer.isBuffer(bytes)
+ ? bytes
+ : Array.isArray(bytes)
+ ? Buffer.concat(bytes)
+ : Buffer.from(bytes),
+ frame = JSON.parse(raw.toString()) as unknown[];
+ if (frame[0] !== 'EVENT') return;
+ const event = frame[1] as { id: string };
+ events.push({
+ origin: new URL(request.url!, 'http://localhost').searchParams.get(
+ 'origin'
+ )!,
+ wire: JSON.stringify(event)
+ });
+ socket.send(JSON.stringify(['OK', event.id, true, '']));
+ })
+ );
+ const result = await build({
+ configFile: false,
+ logLevel: 'silent',
+ build: {
+ write: false,
+ minify: false,
+ lib: {
+ entry: fileURLToPath(
+ new URL('./harness/resume-routing.ts', import.meta.url)
+ ),
+ name: 'hcp088',
+ formats: ['iife']
+ }
+ }
+ });
+ const output = Array.isArray(result) ? result[0] : result;
+ if (!('output' in output)) throw Error('bundle missing');
+ const chunks = output.output.filter((x) => x.type === 'chunk');
+ expect(chunks).toHaveLength(1);
+ bundle = chunks[0].code;
+});
+test.afterAll(async () => {
+ for (const socket of sockets.clients) socket.terminate();
+ await new Promise<void>((r) => sockets.close(() => r()));
+ await server.close();
+});
+test.beforeEach(async ({ page }) => {
+ events = [];
+ await page.addInitScript(
+ ({ endpoint }) => {
+ const Native = window.WebSocket;
+ window.WebSocket = class extends Native {
+ constructor(url: string | URL, protocols?: string | string[]) {
+ const origin = new URL(String(url)).origin;
+ if (
+ ![
+ 'wss://peer.example.org',
+ 'wss://archive.example.org',
+ 'wss://new-peer.example.org'
+ ].includes(origin)
+ )
+ throw Error('unapproved destination');
+ super(endpoint + '/?origin=' + encodeURIComponent(origin), protocols);
+ }
+ };
+ },
+ { endpoint }
+ );
+ await page.goto(server.url + '/search');
+ await page.addScriptTag({ content: bundle });
+ await page.evaluate(async () => {
+ window.hcp088Fixture = await window.hcp088.makeFixture();
+ });
+});
+test.afterEach(async ({ page }) => {
+ if (!page.isClosed())
+ await page.evaluate(() => window.hcp088Fixture?.close());
+});
+test('removed inbox is previewed exactly and unreviewed resumption has no automatic replay', async ({
+ page
+}) => {
+ const r = await page.evaluate(async () => {
+ const f = window.hcp088Fixture,
+ before = await f.row();
+ return {
+ captured: f.capture(),
+ snapshot: f.snapshot(),
+ result: await f.approve('unreviewed'),
+ before,
+ after: await f.row(),
+ retry: await f.retry(true)
+ };
+ });
+ expect(r.captured).toBe(true);
+ expect(r.snapshot?.changes.peer.removed).toEqual(['wss://peer.example.org']);
+ expect(r.snapshot?.changes.peer.added).toEqual([
+ 'wss://new-peer.example.org'
+ ]);
+ expect(r.result.status).toBe('invalid');
+ expect(r.after).toEqual(r.before);
+ expect(r.retry.status).toBe('invalid');
+ expect(events).toEqual([]);
+});
+test('same original ciphertext reaches only the explicitly approved newly advertised destination and old attempts remain', async ({
+ page
+}) => {
+ const r = await page.evaluate(async () => {
+ const f = window.hcp088Fixture;
+ await f.retry(true);
+ const before = await f.row(),
+ counts = f.counts();
+ f.capture();
+ const updated = await f.approve(),
+ old = await f.retry(true),
+ result = await f.retry();
+ return {
+ before,
+ after: await f.row(),
+ counts,
+ afterCounts: f.counts(),
+ updated,
+ old,
+ result
+ };
+ });
+ expect(r.updated.status).toBe('updated');
+ expect(r.old.status).toBe('invalid');
+ expect(r.result.status).toBe('completed');
+ expect(r.after?.record.self).toEqual(r.before?.record.self);
+ expect(r.after?.record.peerArtifact).toEqual(r.before?.record.peerArtifact);
+ expect(r.after?.record.receipts?.slice(0, 2)).toEqual(
+ r.before?.record.receipts
+ );
+ expect(r.after?.record.receipts).toHaveLength(3);
+ expect(r.afterCounts.encrypts).toBe(r.counts.encrypts);
+ expect(r.afterCounts.signs).toBe(r.counts.signs);
+ expect(events.map((e) => e.origin)).toEqual([
+ 'wss://peer.example.org',
+ 'wss://archive.example.org',
+ 'wss://new-peer.example.org'
+ ]);
+ expect(events[2].wire).toBe(events[0].wire);
+});
+test('new unapproved advertised URL has no route capability or network access', async ({
+ page
+}) => {
+ const r = await page.evaluate(async () => {
+ const f = window.hcp088Fixture,
+ before = await f.row();
+ return {
+ captured: f.capture('wss://unapproved.example.org'),
+ approved: await f.approve(),
+ before,
+ after: await f.row()
+ };
+ });
+ expect(r.captured).toBe(false);
+ expect(r.approved.status).toBe('invalid');
+ expect(r.after).toEqual(r.before);
+ expect(events).toEqual([]);
+});
+test('peer switch requires a new message and cannot retarget existing ciphertext', async ({
+ page
+}) => {
+ const r = await page.evaluate(async () => {
+ const f = window.hcp088Fixture,
+ before = await f.row();
+ return {
+ captured: f.capture(
+ 'wss://new-peer.example.org',
+ 'wss://archive.example.org',
+ true
+ ),
+ approved: await f.approve(),
+ before,
+ after: await f.row()
+ };
+ });
+ expect(r.captured).toBe(false);
+ expect(r.approved.status).toBe('invalid');
+ expect(r.after).toEqual(r.before);
+ expect(events).toEqual([]);
+});
+test('sender archive changes use its own advertised set while preserving the peer artifact', async ({
+ page
+}) => {
+ const r = await page.evaluate(async () => {
+ const f = window.hcp088Fixture,
+ before = await f.row();
+ f.capture('wss://peer.example.org', 'wss://new-peer.example.org');
+ const snapshot = f.snapshot(),
+ updated = await f.approve(),
+ result = await f.retry();
+ return { before, after: await f.row(), snapshot, updated, result };
+ });
+ expect(r.snapshot?.changes.archive.removed).toEqual([
+ 'wss://archive.example.org'
+ ]);
+ expect(r.updated.status).toBe('updated');
+ expect(r.result.status).toBe('completed');
+ expect(events.map((e) => e.origin)).toEqual([
+ 'wss://peer.example.org',
+ 'wss://new-peer.example.org'
+ ]);
+ expect(events[1].wire).toBe(r.before?.record.self.wire);
+ expect(r.after?.record.peerArtifact).toEqual(r.before?.record.peerArtifact);
+});
+test('incomplete current discovery cannot supply route consent', async ({
+ page
+}) => {
+ const r = await page.evaluate(() => {
+ const f = window.hcp088Fixture;
+ return f.capture(
+ 'wss://new-peer.example.org',
+ 'wss://archive.example.org',
+ false,
+ false
+ );
+ });
+ expect(r).toBe(false);
+ expect(events).toEqual([]);
+});
+test('stale discovery after review blocks destination update', async ({
+ page
+}) => {
+ const r = await page.evaluate(async () => {
+ const f = window.hcp088Fixture,
+ before = await f.row();
+ f.capture();
+ f.stale();
+ return { result: await f.approve(), before, after: await f.row() };
+ });
+ expect(r.result.status).toBe('stopped');
+ expect(r.after).toEqual(r.before);
+ expect(events).toEqual([]);
+});
+test('competing whole-wire successor cannot renew route-updated custody', async ({
+ page
+}) => {
+ const r = await page.evaluate(async () => {
+ const f = window.hcp088Fixture;
+ f.capture();
+ await f.write('revision');
+ const before = await f.row();
+ return {
+ result: await f.approve(),
+ before,
+ after: await f.row(),
+ retry: await f.retry()
+ };
+ });
+ expect(r.result.status).toBe('conflict');
+ expect(r.after).toEqual(r.before);
+ expect(r.retry.status).toBe('invalid');
+ expect(events).toEqual([]);
+});
+test('fresh changed owner refuses reviewed destination update without encryption or signing', async ({
+ page
+}) => {
+ const r = await page.evaluate(async () => {
+ const f = window.hcp088Fixture;
+ f.capture();
+ const before = await f.row(),
+ counts = f.counts();
+ f.mode('changed_key');
+ return {
+ result: await f.approve(),
+ before,
+ after: await f.row(),
+ counts,
+ afterCounts: f.counts()
+ };
+ });
+ expect(r.result.status).toBe('stopped');
+ expect(r.after).toEqual(r.before);
+ expect(r.afterCounts.encrypts).toBe(r.counts.encrypts);
+ expect(r.afterCounts.signs).toBe(r.counts.signs);
+ expect(events).toEqual([]);
+});
+test('actual IDB abort and post-put readback loss do not acknowledge route permission', async ({
+ page
+}) => {
+ const r = await page.evaluate(async () => {
+ const f = window.hcp088Fixture;
+ f.capture();
+ const before = await f.row();
+ f.fault('abort');
+ const aborted = await f.approve(),
+ afterAbort = await f.row();
+ f.capture();
+ f.fault('readback');
+ const unknown = await f.approve(),
+ retry = await f.retry();
+ return { before, afterAbort, aborted, unknown, retry };
+ });
+ expect(r.aborted.status).toBe('aborted');
+ expect(r.afterAbort).toEqual(r.before);
+ expect(r.unknown.status).toBe('unknown_completion');
+ expect(r.retry.status).toBe('invalid');
+ expect(events).toEqual([]);
+});
+
+test('unsupported current inbox resolution also fences previously genuine old-route replay', async ({
+ page
+}) => {
+ const r = await page.evaluate(async () => {
+ const f = window.hcp088Fixture,
+ before = await f.row();
+ const captured = f.capture('wss://unapproved.example.org');
+ return {
+ captured,
+ before,
+ result: await f.retry(true),
+ after: await f.row()
+ };
+ });
+ expect(r.captured).toBe(false);
+ expect(r.result.status).toBe('invalid');
+ expect(r.after).toEqual(r.before);
+ expect(events).toEqual([]);
+});
+
+async function assertAlreadyHeldFenced(
+ page: import('@playwright/test').Page,
+ destination: string,
+ reviewReady: boolean
+) {
+ const r = await page.evaluate(async (destination) => {
+ const f = window.hcp088Fixture,
+ held = f.captureHeld(),
+ before = await f.row();
+ const reviewed = f.capture(destination);
+ return {
+ held,
+ reviewed,
+ before,
+ result: await f.runHeld(),
+ after: await f.row()
+ };
+ }, destination);
+ expect(r.held).toBe(true);
+ expect(r.reviewed).toBe(reviewReady);
+ expect(r.result.status).toBe('needs_action');
+ expect(r.after).toEqual(r.before);
+ expect(events).toEqual([]);
+}
+test('already captured genuine retry cannot publish while supported destination review is pending', async ({
+ page
+}) => {
+ await assertAlreadyHeldFenced(page, 'wss://new-peer.example.org', true);
+});
+test('already captured genuine retry cannot replay after current inbox becomes unsupported', async ({
+ page
+}) => {
+ await assertAlreadyHeldFenced(page, 'wss://unapproved.example.org', false);
+});
diff --git a/web/tests/unit/resume-routing.test.ts b/web/tests/unit/resume-routing.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import {
+ approvePrivateResumeRouting,
+ privateResumeRoutingSnapshot,
+ type PrivateResumeRouting
+} from '../../src/lib/messaging/resume-routing.ts';
+describe('private route review is an opaque explicit local operation', () => {
+ it('a forged route review cannot expose a peer or destination', () => {
+ expect(
+ privateResumeRoutingSnapshot({} as PrivateResumeRouting)
+ ).toBeUndefined();
+ });
+ it('a forged reviewed token cannot mutate custody or publish', async () => {
+ expect(
+ await approvePrivateResumeRouting(
+ {} as PrivateResumeRouting,
+ 'reviewed_private_destination_update'
+ )
+ ).toEqual({ status: 'invalid' });
+ });
+ it('caller objects never coerce into consent or a route review', async () => {
+ let called = 0;
+ const value = {
+ toString() {
+ called++;
+ return 'reviewed_private_destination_update';
+ }
+ };
+ expect(
+ await approvePrivateResumeRouting({} as PrivateResumeRouting, value)
+ ).toEqual({ status: 'invalid' });
+ expect(called).toBe(0);
+ });
+});