commit f414e7b0a737514e45ba47f50a96d0a87977f45c
parent 59c3147b98db4b05a2849a39b1427ec22db7cf73
Author: triesap <tyson@radroots.org>
Date: Fri, 9 Oct 2026 08:15:29 +0000
messages: start scoped inbox live retrieval before backfill (HCP-095)
- Open one scoped SDK live lane before bounded history on the private pool
- Require the original owner generation, unlock, visibility and exercised inbox access
- Retain ciphertext across both lanes with honest limits and disposal
- Verify startup gaps, final tails, duplicates, owner changes and actual cleanup
Diffstat:
8 files changed, 1267 insertions(+), 3 deletions(-)
diff --git a/web/src/lib/config/budgets.ts b/web/src/lib/config/budgets.ts
@@ -105,3 +105,11 @@ export const PUBLIC_PUBLICATION_BUDGETS = Object.freeze({
attemptsPerTargetAction: 3,
networkActionMilliseconds: 45000
});
+
+// Foreground live inbox only; rolling source window charged before dedup.
+// Logical post-SDK-parse limits, not browser preallocation guarantees.
+export const PRIVATE_LIVE_BUDGETS = Object.freeze({
+ deliveries: 120,
+ processedBytes: 2097152,
+ windowMilliseconds: 60000
+});
diff --git a/web/src/lib/messaging/inbox-sync.ts b/web/src/lib/messaging/inbox-sync.ts
@@ -0,0 +1,392 @@
+import {
+ unlockedSessionOwnership,
+ subscribeUnlockedSessionClose,
+ type UnlockedSession
+} from './unlocked-session.ts';
+import {
+ getPrivateVisibilityScope,
+ privateVisibilitySnapshot,
+ closePrivateVisibilityScope
+} from '../runtime/dispose.ts';
+import {
+ readRelayPolicy,
+ inboxRelayTargets,
+ publicRelayTargets,
+ type RelayPolicy
+} from '../config/relays.ts';
+import { PRIVATE_TRANSPORT_BUDGETS } from '../config/budgets.ts';
+import { inboxPreferenceSnapshot } from '../nostr/inbox-preferences.ts';
+import {
+ inboxResolutionSnapshot,
+ inboxResolverCurrentAfterSample,
+ type InboxResolver
+} from '../messaging/resolve-inbox.ts';
+import type { ObserveInboxAccess } from '../messaging/readiness.ts';
+import {
+ privateSessionOwnership,
+ subscribePrivateSessionClose,
+ type PrivateSession
+} from '../runtime/private-session.ts';
+import {
+ getPrivatePool,
+ subscribePrivatePage,
+ subscribePrivateLive,
+ type PrivatePageMessage,
+ closePrivatePool
+} from '../nostr/private-pool.ts';
+import {
+ admitInboxEnvelope,
+ retainInboxEnvelope
+} from '../persistence/inbox-envelope-repository.ts';
+import type { PrivateStorageRepository } from '../persistence/private-storage.ts';
+declare const ingressBrand: unique symbol;
+export type InboxSync = Readonly<{ [ingressBrand]: true }>;
+type State = 'ready' | 'running' | 'live' | 'stopped' | 'needs_action';
+type Snapshot = Readonly<{
+ owner: string;
+ state: State;
+ candidates: number;
+ bytes: number;
+ retained: number;
+ duplicates: number;
+ rejected: number;
+ reason: string | null;
+ pending: number;
+ cleanupRequired: boolean;
+ backfill: string;
+ historyComplete: false;
+ foregroundOnly: true;
+}>;
+type Controller = {
+ start(review: unknown): boolean;
+ stop(): void;
+ snapshot(): Snapshot;
+};
+const ingress = new WeakMap<InboxSync, Controller>();
+const sessions = new WeakMap<PrivateSession, InboxSync>();
+// Explicit foreground live-before-finite receive admission. A remembered key, allowlist or EOSE alone
+// is not exercised own inbox access. No production observation port is supplied
+// here; controlled fixtures do not qualify real operator relay/AUTH access.
+// No closed-tab notification, unattended decrypt or complete-inbox promise.
+export function captureInboxSync(
+ repository: PrivateStorageRepository,
+ session: PrivateSession,
+ policy: RelayPolicy,
+ own: InboxResolver,
+ unlocked: UnlockedSession,
+ observeAccess: ObserveInboxAccess | undefined,
+ review: unknown
+): InboxSync | undefined {
+ if (
+ typeof window === 'undefined' ||
+ review !== 'reviewed_foreground_inbox' ||
+ !observeAccess
+ )
+ return undefined;
+ try {
+ const previous = sessions.get(session);
+ if (previous && ingress.get(previous)?.snapshot().state !== 'stopped')
+ return undefined;
+ const observedOwnership = privateSessionOwnership(session),
+ manifest = readRelayPolicy(policy),
+ resolution = inboxResolutionSnapshot(own);
+ if (
+ !observedOwnership?.current() ||
+ !manifest.messagingEnabled ||
+ resolution.author !== observedOwnership.owner ||
+ resolution.status !== 'ready' ||
+ resolution.coverage !== 'bounded-eose' ||
+ !resolution.head ||
+ !resolution.knownBase
+ )
+ return undefined;
+ const ownership = observedOwnership;
+ const preference = inboxPreferenceSnapshot(resolution.head),
+ discovery = publicRelayTargets(policy, 'read');
+ if (
+ !preference ||
+ preference.status !== 'supported' ||
+ preference.author !== ownership.owner ||
+ preference.id !== resolution.knownBase.id ||
+ !discovery.length ||
+ discovery.length !== resolution.sources.length ||
+ !discovery.every((origin) =>
+ resolution.sources.some(
+ (source) => source.source === origin && source.state === 'eose'
+ )
+ )
+ )
+ return undefined;
+ const targets = inboxRelayTargets(policy, preference.relays, 'read'),
+ archive = inboxRelayTargets(policy, preference.relays, 'write');
+ if (!targets.length || !archive.length) return undefined;
+ const access = observeAccess({
+ owner: ownership.owner,
+ session: ownership.session,
+ preferenceId: preference.id,
+ readTargets: targets.slice(),
+ archiveTargets: archive.slice()
+ });
+ if (
+ !access ||
+ access.owner !== ownership.owner ||
+ access.session !== ownership.session ||
+ access.preferenceId !== preference.id ||
+ access.receive !== 'qualified_exercised' ||
+ access.archive !== 'qualified_exercised' ||
+ JSON.stringify(access.readTargets) !== JSON.stringify(targets) ||
+ JSON.stringify(access.archiveTargets) !== JSON.stringify(archive)
+ )
+ return undefined;
+ const cache = unlockedSessionOwnership(unlocked);
+ if (
+ !cache?.current() ||
+ cache.owner !== ownership.owner ||
+ cache.session !== ownership.session
+ )
+ return undefined;
+ const observedVisibility = getPrivateVisibilityScope(session);
+ if (!observedVisibility) return undefined;
+ const visibility = observedVisibility;
+ const current = () => {
+ const latest = inboxResolutionSnapshot(own);
+ return (
+ privateVisibilitySnapshot(visibility).active &&
+ unlockedSessionOwnership(unlocked)?.session === ownership.session &&
+ !!unlockedSessionOwnership(unlocked)?.current() &&
+ latest.status === 'ready' &&
+ latest.coverage === 'bounded-eose' &&
+ latest.author === ownership.owner &&
+ latest.knownBase?.id === preference.id &&
+ access.current() &&
+ ownership.current() &&
+ inboxResolverCurrentAfterSample(own)
+ );
+ };
+ if (!current()) return undefined;
+ const pool = getPrivatePool(session, policy, targets);
+ if (!pool) return undefined;
+ const token = Object.freeze({}) as InboxSync;
+ let state: State = 'ready',
+ candidates = 0,
+ bytes = 0,
+ retained = 0,
+ duplicates = 0,
+ rejected = 0,
+ pending = 0,
+ reason: string | null = null,
+ consumed = false,
+ stopped = false,
+ backfill = 'not_started',
+ pendingBytes = 0,
+ failed = false,
+ cleaned = false,
+ cleanupRequired = false;
+ let release = () => {},
+ releaseLive = () => {},
+ offUnlock = () => {},
+ off = () => {};
+ let queue = Promise.resolve();
+ function releaseOwners() {
+ let failure = false;
+ for (const cleanup of [
+ release,
+ releaseLive,
+ () => closePrivatePool(pool!)
+ ]) {
+ try {
+ cleanup();
+ } catch {
+ failure = true;
+ }
+ }
+ cleanupRequired = failure;
+ if (failure) throw Error('private_inbox_cleanup_required');
+ }
+ function stop() {
+ if (cleaned) return;
+ stopped = true;
+ state = 'stopped';
+ off();
+ offUnlock();
+ let failure = false;
+ try {
+ releaseOwners();
+ } catch {
+ failure = true;
+ }
+ try {
+ if (!closePrivateVisibilityScope(visibility)) failure = true;
+ } catch {
+ failure = true;
+ }
+ cleanupRequired = failure;
+ if (!failure) cleaned = true;
+ else throw Error('private_inbox_cleanup_required');
+ }
+ function pause(why: string) {
+ if (stopped || failed) return;
+ failed = true;
+ state = 'needs_action';
+ reason = why;
+ try {
+ releaseOwners();
+ } catch {
+ cleanupRequired = true;
+ }
+ }
+ function receive(message: PrivatePageMessage) {
+ if (stopped || failed) return;
+ if (!current()) {
+ stop();
+ return;
+ }
+ if (message.type === 'end') {
+ backfill = message.reason;
+ if (message.reason !== 'complete') pause(message.reason);
+ return;
+ }
+ candidates++;
+ const size = new TextEncoder().encode(message.wire).length;
+ bytes += size;
+ // Bound outstanding ciphertext work across both lanes before queuing.
+ if (
+ pending >= PRIVATE_TRANSPORT_BUDGETS.deliveries ||
+ pendingBytes + size > PRIVATE_TRANSPORT_BUDGETS.processedBytes
+ ) {
+ pause('budget');
+ return;
+ }
+ const origin = message.from.endsWith('/')
+ ? message.from.slice(0, -1)
+ : message.from;
+ if (!targets.includes(origin)) {
+ rejected++;
+ return;
+ }
+ const envelope = admitInboxEnvelope(
+ message.wire,
+ ownership.owner,
+ origin,
+ Date.now()
+ );
+ if (!envelope) {
+ rejected++;
+ return;
+ }
+ pending++;
+ pendingBytes += size;
+ queue = queue
+ .then(async () => {
+ if (stopped || failed) return;
+ if (!current()) {
+ stop();
+ return;
+ }
+ const result = await retainInboxEnvelope(
+ repository,
+ session,
+ envelope
+ );
+ if (stopped || failed || !current()) {
+ if (!stopped && !failed) stop();
+ return;
+ }
+ if (result.status === 'retained') retained++;
+ else if (result.status === 'duplicate') duplicates++;
+ else pause(result.status);
+ })
+ .catch(() => pause('unknown_completion'))
+ .finally(() => {
+ pending--;
+ pendingBytes -= size;
+ });
+ }
+ ingress.set(token, {
+ snapshot: () => ({
+ owner: ownership.owner,
+ state,
+ candidates,
+ bytes,
+ retained,
+ duplicates,
+ rejected,
+ reason,
+ pending,
+ cleanupRequired,
+ backfill,
+ historyComplete: false,
+ foregroundOnly: true
+ }),
+ stop,
+ start(reviewed) {
+ if (
+ reviewed !== 'reviewed_foreground_inbox' ||
+ consumed ||
+ stopped ||
+ !current()
+ )
+ return false;
+ consumed = true;
+ state = 'running';
+ try {
+ releaseLive = subscribePrivateLive(pool, (message) => {
+ if (stopped || failed) return;
+ if (!current()) {
+ stop();
+ return;
+ }
+ if (message.type === 'open') {
+ // Actual SDK OPEN follows its REQ send. Defer so synchronous cached
+ // connections cannot begin backfill before the live release binds.
+ if (backfill !== 'not_started') return;
+ backfill = 'running';
+ queueMicrotask(() => {
+ if (stopped || failed) return;
+ if (!current()) {
+ stop();
+ return;
+ }
+ state = 'live';
+ try {
+ release = subscribePrivatePage(
+ pool,
+ PRIVATE_TRANSPORT_BUDGETS.requestedPerRelay,
+ receive
+ );
+ } catch {
+ pause('backfill_unavailable');
+ }
+ });
+ } else if (message.type === 'end') pause(message.reason);
+ else receive(message);
+ });
+ } catch {
+ state = 'needs_action';
+ reason = 'live_unavailable';
+ return false;
+ }
+ return true;
+ }
+ });
+ sessions.set(session, token);
+ off = subscribePrivateSessionClose(session, stop);
+ offUnlock = subscribeUnlockedSessionClose(unlocked, stop);
+ if (!current()) {
+ stop();
+ return undefined;
+ }
+ return token;
+ } catch {
+ return undefined;
+ }
+}
+export function startInboxSync(token: InboxSync, review: unknown): boolean {
+ return ingress.get(token)?.start(review) ?? false;
+}
+export function stopInboxSync(token: InboxSync): void {
+ ingress.get(token)?.stop();
+}
+export function inboxSyncSnapshot(token: InboxSync): Snapshot | undefined {
+ return ingress.get(token)?.snapshot();
+}
diff --git a/web/src/lib/messaging/unlocked-session.ts b/web/src/lib/messaging/unlocked-session.ts
@@ -35,6 +35,7 @@ type Controller = {
snapshot(): Snapshot;
close(): void;
};
+const closeObservers = new WeakMap<UnlockedSession, Map<() => void, true>>();
const controllers = new WeakMap<UnlockedSession, Controller>(),
sessions = new WeakMap<PrivateSession, UnlockedSession>();
// Explicit owner-generation memory scope only. No decryption, shared SDK
@@ -66,6 +67,16 @@ export function captureUnlockedSession(
function close() {
if (closed) return;
closed = true;
+ const callbacks = closeObservers.get(token);
+ closeObservers.delete(token);
+ if (callbacks)
+ for (const callback of callbacks.keys()) {
+ try {
+ callback();
+ } catch {
+ /* Continue original cache disposal. */
+ }
+ }
entries.clear();
bytes = 0;
clearPrivateCacheScope(cache);
@@ -204,3 +215,24 @@ export function unlockedConversationCurrent(
): boolean {
return controllers.get(scope)?.contains(room) ?? false;
}
+
+// Original opaque controller lifetime only, not a copied snapshot capability.
+export function subscribeUnlockedSessionClose(
+ scope: UnlockedSession,
+ callback: () => void
+): () => void {
+ if (!controllers.get(scope)?.current()) {
+ callback();
+ return () => {};
+ }
+ let observers = closeObservers.get(scope);
+ if (!observers) {
+ observers = new Map();
+ closeObservers.set(scope, observers);
+ }
+ observers.set(callback, true);
+ const captured = observers;
+ return () => {
+ captured.delete(callback);
+ };
+}
diff --git a/web/src/lib/nostr/inbox-queries.ts b/web/src/lib/nostr/inbox-queries.ts
@@ -1,5 +1,8 @@
import { canonicalPublicKey } from '../contracts/public-key.ts';
-import { PUBLIC_QUERY_BUDGETS } from '../config/budgets.ts';
+import {
+ PRIVATE_TRANSPORT_BUDGETS,
+ PUBLIC_QUERY_BUDGETS
+} from '../config/budgets.ts';
import type { PublicFilter } from './exports.ts';
export function inboxPreferenceQueries(
@@ -15,3 +18,21 @@ export function inboxPreferenceQueries(
}
];
}
+
+// No inner-time cursor or throttle; live limit0 excludes initial history, not
+// future backdated messages. Actual relay semantics require separate Q.
+export function privateInboxQueries(
+ owner: unknown,
+ mode: 'live' | 'backfill'
+): readonly PublicFilter[] {
+ const key = canonicalPublicKey(owner);
+ if (!key) throw Error('inbox_owner_invalid');
+ if (mode !== 'live' && mode !== 'backfill') throw Error('inbox_mode_invalid');
+ return [
+ {
+ kinds: [1059],
+ '#p': [key],
+ limit: mode === 'live' ? 0 : PRIVATE_TRANSPORT_BUDGETS.requestedPerRelay
+ }
+ ];
+}
diff --git a/web/src/lib/nostr/private-pool.ts b/web/src/lib/nostr/private-pool.ts
@@ -1,3 +1,4 @@
+import { privateInboxQueries } from './inbox-queries.ts';
import { createScopedRelayPool } from './pool-factory.ts';
import { NEVER } from 'rxjs';
import {
@@ -20,6 +21,7 @@ import {
import { readRelayPolicy, type RelayPolicy } from '../config/relays.ts';
import {
PRIVATE_TRANSPORT_BUDGETS,
+ PRIVATE_LIVE_BUDGETS,
PRIVATE_AUTH_BUDGETS,
PRIVATE_PUBLICATION_BUDGETS,
RELAY_BUDGETS
@@ -75,6 +77,8 @@ export type PrivatePageMessage =
| 'elapsed'
| 'stopped';
}>;
+export type PrivateLiveMessage =
+ PrivatePageMessage | Readonly<{ type: 'open' }>;
type Owner = {
session: PrivateSession;
policy: RelayPolicy;
@@ -94,6 +98,7 @@ type Owner = {
limit: number,
listener: (message: PrivatePageMessage) => void
): () => void;
+ subscribeLive(listener: (message: PrivateLiveMessage) => void): () => void;
close(): void;
};
declare const connectionBrand: unique symbol;
@@ -176,6 +181,9 @@ export function getPrivatePool(
busy = false,
cleanupRequired = false;
let active = () => {};
+ let liveActive = () => {},
+ liveBusy = false,
+ liveCleanupRequired = false;
let off = () => {};
const authCleanup = new Map<string, () => void>();
const publicationStops = new Map<() => void, true>();
@@ -606,6 +614,147 @@ export function getPrivatePool(
}
return token;
},
+ subscribeLive(listener) {
+ if (!readOrigins.length) throw Error('private_read_origins_unavailable');
+ if (closed || !capture.current()) throw Error('private_pool_closed');
+ if (liveBusy || liveCleanupRequired) throw Error('private_live_busy');
+ liveBusy = true;
+ let ended = false,
+ release = () => {},
+ serial = 0;
+ const opened = new Map<string, true>(),
+ meters = new Map<string, Map<number, { at: number; bytes: number }>>();
+ function emit(message: PrivateLiveMessage) {
+ try {
+ listener(message);
+ } catch {
+ /* Keep cleanup owned even when a consumer throws. */
+ }
+ }
+ function finish(
+ reason: Extract<PrivatePageMessage, { type: 'end' }>['reason'],
+ propagate = false
+ ) {
+ if (ended) {
+ if (liveCleanupRequired && propagate) {
+ release();
+ liveCleanupRequired = false;
+ liveBusy = false;
+ }
+ return;
+ }
+ ended = true;
+ let failure: unknown;
+ try {
+ release();
+ liveCleanupRequired = false;
+ liveBusy = false;
+ } catch (error) {
+ failure = error;
+ liveCleanupRequired = true;
+ }
+ meters.clear();
+ opened.clear();
+ emit({ type: 'end', reason: liveCleanupRequired ? 'error' : reason });
+ if (liveCleanupRequired && propagate) throw failure;
+ }
+ liveActive = () => {
+ finish('closed', true);
+ release();
+ };
+ void recheckPrivateSession(session)
+ .then((fresh) => {
+ if (ended) return;
+ if (!fresh || closed || !capture.current()) {
+ finish('stale');
+ return;
+ }
+ const subscription = sdk
+ .req(
+ [...readOrigins],
+ [...privateInboxQueries(capture.owner, 'live')],
+ {
+ waitForAuth: false,
+ reconnect: false,
+ resubscribe: false
+ }
+ )
+ .subscribe({
+ next(message) {
+ if (ended) return;
+ if (closed || !capture.current()) {
+ finish('stale');
+ return;
+ }
+ const origin = message.from.endsWith('/')
+ ? message.from.slice(0, -1)
+ : message.from;
+ if (!readOrigins.includes(origin)) {
+ finish('error');
+ return;
+ }
+ if (message.type === 'OPEN') {
+ opened.set(origin, true);
+ if (opened.size === readOrigins.length)
+ emit({ type: 'open' });
+ } else if (message.type === 'EVENT') {
+ const now = performance.now();
+ let meter = meters.get(origin);
+ if (!meter) {
+ meter = new Map();
+ meters.set(origin, meter);
+ }
+ let bytes = 0;
+ for (const [key, item] of meter) {
+ if (
+ now - item.at >=
+ PRIVATE_LIVE_BUDGETS.windowMilliseconds
+ )
+ meter.delete(key);
+ else bytes += item.bytes;
+ }
+ // Count every actual delivery, including invalid envelopes/duplicates.
+ if (meter.size >= PRIVATE_LIVE_BUDGETS.deliveries) {
+ finish('budget');
+ return;
+ }
+ const wire = JSON.stringify(message.event);
+ if (
+ typeof wire !== 'string' ||
+ !boundedUtf8(
+ wire,
+ PRIVATE_LIVE_BUDGETS.processedBytes - bytes
+ )
+ ) {
+ finish('budget');
+ return;
+ }
+ meter.set(++serial, {
+ at: now,
+ bytes: new TextEncoder().encode(wire).length
+ });
+ if (
+ boundedUtf8(wire, PRIVATE_TRANSPORT_BUDGETS.envelopeBytes)
+ )
+ emit({ type: 'candidate', from: origin, wire });
+ } else if (message.type === 'CLOSED') finish('closed');
+ else if (message.type === 'ERROR') finish('error');
+ // EOSE ends retained history only; the unthrottled live owner remains.
+ },
+ error: () => finish('error'),
+ complete: () => finish('closed')
+ });
+ release = () => subscription.unsubscribe();
+ if (ended || closed || !capture.current()) {
+ release();
+ if (!ended) finish('stale');
+ }
+ })
+ .catch(() => {
+ if (!ended) finish('error');
+ });
+ return () => finish('stopped', true);
+ },
subscribe(limit, listener) {
if (readOrigins.length === 0)
throw new Error('private_read_origins_unavailable');
@@ -679,7 +828,10 @@ export function getPrivatePool(
const subscription = sdk
.req(
[...readOrigins],
- [{ kinds: [1059], '#p': [capture.owner], limit }],
+ privateInboxQueries(capture.owner, 'backfill').map((filter) => ({
+ ...filter,
+ limit
+ })),
{
waitForAuth: false,
reconnect: false,
@@ -733,7 +885,8 @@ export function getPrivatePool(
);
if (accepted)
emit({ type: 'candidate', from: message.from, wire });
- } else if (message.type === 'ERROR') finish('error');
+ } else if (message.type === 'CLOSED') finish('closed');
+ else if (message.type === 'ERROR') finish('error');
},
complete: () => finish('complete'),
error: () => finish('error')
@@ -761,6 +914,11 @@ export function getPrivatePool(
closed = true;
let failed = false;
try {
+ liveActive();
+ } catch {
+ failed = true;
+ }
+ try {
active();
} catch {
failed = true;
@@ -880,3 +1038,11 @@ export function invalidatePrivateAuthGeneration(
): boolean {
return authConnections.get(connection)?.invalidate(proof) ?? false;
}
+
+// One foreground live lane per selected private relay on the original pool.
+export function subscribePrivateLive(
+ pool: PrivatePool,
+ listener: (message: PrivateLiveMessage) => void
+): () => void {
+ return ownerOf(pool).subscribeLive(listener);
+}
diff --git a/web/tests/e2e/harness/inbox-sync.ts b/web/tests/e2e/harness/inbox-sync.ts
@@ -0,0 +1,198 @@
+import {
+ captureUnlockedSession,
+ closeUnlockedSession
+} from '../../../src/lib/messaging/unlocked-session.ts';
+import { identitySessionSnapshot } from '../../../src/lib/runtime/identity-session.ts';
+import {
+ browserExtensionScheduler,
+ extensionSchedulerSnapshot
+} from '../../../src/lib/nostr/extension-scheduler.ts';
+import { makeFixture as makeRecoveryFixture } from './resume-preparation.ts';
+import {
+ validateRelayPolicy,
+ readRelayPolicy
+} from '../../../src/lib/config/relays.ts';
+import {
+ createPrivateSession,
+ closePrivateSession,
+ privateSessionOwnership
+} from '../../../src/lib/runtime/private-session.ts';
+import {
+ captureInboxSync,
+ startInboxSync,
+ stopInboxSync,
+ inboxSyncSnapshot,
+ type InboxSync
+} from '../../../src/lib/messaging/inbox-sync.ts';
+import { loadPrivateRecord } from '../../../src/lib/persistence/private-storage.ts';
+import { privateRecordSnapshot } from '../../../src/lib/persistence/private-records.ts';
+import {
+ getPublicStore,
+ publicStoreEnvelope
+} from '../../../src/lib/nostr/public-store.ts';
+export async function makeFixture() {
+ const f = await makeRecoveryFixture();
+ const policy = validateRelayPolicy(
+ JSON.stringify({
+ ...readRelayPolicy(f.context.policy),
+ messagingEnabled: true
+ })
+ );
+ if (!policy) throw Error('fixture policy unavailable');
+ const session = await createPrivateSession(
+ f.identity,
+ 'reviewed_private_session'
+ );
+ if (!session) throw Error('missing genuine session');
+ const capture = privateSessionOwnership(session)!;
+ const unlocked = captureUnlockedSession(session, 'reviewed_messages_unlock');
+ if (!unlocked) throw Error('missing genuine unlock');
+ const publicStore = getPublicStore()!;
+ const self = (await f.row())!.record.self;
+ let ingress: InboxSync | undefined;
+ let authorized = true;
+ let restoreFault = () => {};
+ let releaseKey: (() => void) | undefined;
+ let restoreKey = () => {};
+ return {
+ ...f,
+ outer: self.wire,
+ outerId: self.eventId,
+ capture(access = true, review: unknown = 'reviewed_foreground_inbox') {
+ const candidate = captureInboxSync(
+ f.repository,
+ session,
+ policy,
+ f.context.own,
+ unlocked,
+ access
+ ? (context) => ({
+ ...context,
+ receive: 'qualified_exercised',
+ archive: 'qualified_exercised',
+ current: () => authorized && capture.current()
+ })
+ : undefined,
+ review
+ );
+ if (candidate) ingress = candidate;
+ return !!candidate;
+ },
+ start(review: unknown = 'reviewed_foreground_inbox') {
+ if (!ingress) return false;
+ return startInboxSync(ingress, review);
+ },
+ stop() {
+ if (ingress) stopInboxSync(ingress);
+ },
+ snapshot: () => ingress && inboxSyncSnapshot(ingress),
+ async stored(id = self.eventId) {
+ const row = await loadPrivateRecord(
+ f.repository,
+ 'received_envelopes',
+ id
+ );
+ return row.ok ? privateRecordSnapshot(row.value, f.owner, id) : undefined;
+ },
+ publicContains: (id = self.eventId) =>
+ !!publicStoreEnvelope(publicStore, id),
+ countsValue: () => f.counts(),
+ closeUnlock() {
+ closeUnlockedSession(unlocked);
+ },
+ navigateAway() {
+ if (ingress) stopInboxSync(ingress);
+ },
+ changeKey() {
+ f.mode('changed_key');
+ },
+ holdNextKey() {
+ const provider = window.nostr as
+ { getPublicKey: () => Promise<string> } | undefined;
+ if (!provider) throw Error('missing genuine fixture provider');
+ const original = provider.getPublicKey;
+ provider.getPublicKey = async () => {
+ const owner = await original.call(provider);
+ return await new Promise<string>((resolve) => {
+ releaseKey = () => resolve(owner);
+ });
+ };
+ restoreKey = () => {
+ provider.getPublicKey = original;
+ };
+ },
+ pendingKey: () => !!releaseKey,
+ keyJobOccupied() {
+ const scheduler = browserExtensionScheduler();
+ const slot = scheduler && extensionSchedulerSnapshot(scheduler);
+ return slot?.state === 'active' && slot.pending === 'key';
+ },
+ identityState: () => identitySessionSnapshot(f.identity).state,
+ settleKey() {
+ const release = releaseKey;
+ releaseKey = undefined;
+ restoreKey();
+ release?.();
+ },
+ revokeAccess() {
+ authorized = false;
+ },
+ logout() {
+ closePrivateSession(session);
+ },
+ logoutIdentity() {
+ f.disconnect();
+ closePrivateSession(session);
+ },
+ restoreFault() {
+ restoreFault();
+ },
+ faultRetention(kind: 'abort' | 'readback') {
+ const put = Reflect.get<IDBObjectStore, 'put'>(
+ IDBObjectStore.prototype,
+ 'put'
+ );
+ const cursor = Reflect.get<IDBIndex, 'openCursor'>(
+ IDBIndex.prototype,
+ 'openCursor'
+ );
+ let written = false;
+ IDBObjectStore.prototype.put = function (
+ ...args: Parameters<IDBObjectStore['put']>
+ ) {
+ const request = put.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 (
+ kind === 'readback' &&
+ written &&
+ this.objectStore.name === 'received_envelopes' &&
+ this.objectStore.transaction.mode === 'readonly'
+ )
+ throw Error('actual post-put inbox readback failure');
+ return cursor.apply(this, args);
+ };
+ restoreFault = () => {
+ IDBObjectStore.prototype.put = put;
+ IDBIndex.prototype.openCursor = cursor;
+ };
+ },
+ close() {
+ const release = releaseKey;
+ releaseKey = undefined;
+ restoreKey();
+ release?.();
+ restoreFault();
+ if (ingress) stopInboxSync(ingress);
+ closePrivateSession(session);
+ f.close();
+ }
+ };
+}
diff --git a/web/tests/e2e/inbox-sync.spec.ts b/web/tests/e2e/inbox-sync.spec.ts
@@ -0,0 +1,425 @@
+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-sync.ts';
+declare global {
+ interface Window {
+ hcp095: typeof Fixture;
+ hcp095Fixture: 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>(),
+ frames: Record<string, unknown>[] = [];
+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) =>
+ 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] === '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]));
+ for (const event of frames)
+ socket.send(JSON.stringify(['EVENT', frame[1], event]));
+ socket.send(JSON.stringify(['EOSE', frame[1]]));
+ } else {
+ for (const event of frames)
+ 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-sync.ts', import.meta.url)
+ ),
+ name: 'hcp095',
+ formats: ['iife']
+ }
+ }
+ });
+ const output = Array.isArray(result) ? result[0] : result;
+ if (!('output' in output)) throw Error('bundle unavailable');
+ 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>((resolve) => sockets.close(() => resolve()));
+ await server.close();
+});
+test.beforeEach(async ({ page }) => {
+ requests = [];
+ closes = [];
+ frames = [];
+ live = new Map();
+ 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('unapproved receive destination');
+ super(endpoint, protocols);
+ }
+ };
+ },
+ { endpoint }
+ );
+ await page.goto(server.url + '/search');
+ await page.addScriptTag({ content: bundle });
+ await page.evaluate(async () => {
+ window.hcp095Fixture = await window.hcp095.makeFixture();
+ });
+});
+test.afterEach(async ({ page }) => {
+ if (!page.isClosed())
+ await page.evaluate(() => window.hcp095Fixture?.close());
+});
+const eventFrom = (wire: string) => JSON.parse(wire) as Record<string, unknown>;
+function deliver(event: Record<string, unknown>) {
+ for (const [socket, id] of live)
+ socket.send(JSON.stringify(['EVENT', id, event]));
+}
+test('closing original unlock after live start sends actual CLOSE and prevents resurrection', async ({
+ page
+}) => {
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ f.capture();
+ f.start();
+ });
+ await expect.poll(() => requests.length).toBe(2);
+ await page.evaluate(() => window.hcp095Fixture.closeUnlock());
+ await expect.poll(() => closes.length).toBeGreaterThanOrEqual(2);
+ expect(
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ return { snapshot: f.snapshot(), start: f.start(), capture: f.capture() };
+ })
+ ).toMatchObject({
+ snapshot: { state: 'stopped' },
+ start: false,
+ capture: false
+ });
+ expect(requests).toHaveLength(2);
+});
+test('second capture cannot replace the original admitted foreground owner', async ({
+ page
+}) => {
+ expect(
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ return [f.capture(), f.capture(), f.start()];
+ })
+ ).toEqual([true, false, true]);
+ await expect.poll(() => requests.length).toBe(2);
+ expect(
+ requests.filter((r) => (r[2] as { limit: number }).limit === 0)
+ ).toHaveLength(1);
+});
+test('logout during actual held fresh-key job fences its settled continuation and no REQ opens', async ({
+ page
+}) => {
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ f.capture();
+ f.holdNextKey();
+ f.start();
+ });
+ await expect
+ .poll(() => page.evaluate(() => window.hcp095Fixture.pendingKey()))
+ .toBe(true);
+ expect(await page.evaluate(() => window.hcp095Fixture.identityState())).toBe(
+ 'pending'
+ );
+ expect(requests).toEqual([]);
+ expect(await page.evaluate(() => window.hcp095Fixture.keyJobOccupied())).toBe(
+ true
+ );
+ await page.evaluate(() => window.hcp095Fixture.logoutIdentity());
+ expect(
+ await page.evaluate(() => window.hcp095Fixture.snapshot())
+ ).toMatchObject({ state: 'stopped', retained: 0, candidates: 0 });
+ expect(await page.evaluate(() => window.hcp095Fixture.pendingKey())).toBe(
+ true
+ );
+ await page.evaluate(() => window.hcp095Fixture.settleKey());
+ await expect
+ .poll(() => page.evaluate(() => window.hcp095Fixture.keyJobOccupied()))
+ .toBe(false);
+ expect(await page.evaluate(() => window.hcp095Fixture.identityState())).toBe(
+ 'guest'
+ );
+ expect(
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ return { snapshot: f.snapshot(), start: f.start(), capture: f.capture() };
+ })
+ ).toMatchObject({
+ snapshot: { state: 'stopped', retained: 0, candidates: 0 },
+ start: false,
+ capture: false
+ });
+ expect(requests).toEqual([]);
+});
+test('reviewed capture is inert and wrong review or absent exercised access cannot start', async ({
+ page
+}) => {
+ expect(
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ return {
+ wrong: f.capture(true, 'unreviewed'),
+ without: f.capture(false),
+ ready: f.capture(),
+ snapshot: f.snapshot()
+ };
+ })
+ ).toMatchObject({
+ wrong: false,
+ without: false,
+ ready: true,
+ snapshot: { state: 'ready' }
+ });
+ expect(requests).toEqual([]);
+});
+test('actual live REQ precedes bounded backfill and gap delivery is retained once across both', async ({
+ page
+}) => {
+ frames = [eventFrom(await page.evaluate(() => window.hcp095Fixture.outer))];
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ f.capture();
+ f.start();
+ });
+ await expect
+ .poll(() =>
+ page.evaluate(() => window.hcp095Fixture.snapshot()?.duplicates)
+ )
+ .toBe(1);
+ const owner = await page.evaluate(() => window.hcp095Fixture.owner);
+ expect(requests).toHaveLength(2);
+ expect(requests.map((r) => (r[2] as { limit: number }).limit)).toEqual([
+ 0, 200
+ ]);
+ expect(requests[0][2]).toEqual({ kinds: [1059], '#p': [owner], limit: 0 });
+ expect(requests[1][2]).toEqual({ kinds: [1059], '#p': [owner], limit: 200 });
+ expect(
+ await page.evaluate(() => window.hcp095Fixture.snapshot())
+ ).toMatchObject({
+ state: 'live',
+ retained: 1,
+ duplicates: 1,
+ backfill: 'complete',
+ historyComplete: false
+ });
+ expect(await page.evaluate(() => window.hcp095Fixture.publicContains())).toBe(
+ false
+ );
+});
+test('single no-later-event live tail arrives after both EOSE without decrypt or throttle', async ({
+ page
+}) => {
+ const before = await page.evaluate(() => window.hcp095Fixture.countsValue());
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ f.capture();
+ f.start();
+ });
+ await expect.poll(() => requests.length).toBe(2);
+ await expect
+ .poll(() => page.evaluate(() => window.hcp095Fixture.snapshot()?.backfill))
+ .toBe('complete');
+ deliver(eventFrom(await page.evaluate(() => window.hcp095Fixture.outer)));
+ await expect
+ .poll(() =>
+ page.evaluate(async () => !!(await window.hcp095Fixture.stored()))
+ )
+ .toBe(true);
+ expect(
+ await page.evaluate(() => window.hcp095Fixture.snapshot())
+ ).toMatchObject({ state: 'live', retained: 1, historyComplete: false });
+ const after = await page.evaluate(() => window.hcp095Fixture.countsValue());
+ expect(after.decrypts).toBe(before.decrypts);
+ expect(after.encrypts).toBe(before.encrypts);
+ expect(after.signs).toBe(before.signs);
+});
+test('repeated start never allocates a second live subscription', async ({
+ page
+}) => {
+ expect(
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ f.capture();
+ return [f.start(), f.start()];
+ })
+ ).toEqual([true, false]);
+ await expect.poll(() => requests.length).toBe(2);
+ expect(
+ requests.filter((r) => (r[2] as { limit: number }).limit === 0)
+ ).toHaveLength(1);
+});
+test('route disposal closes actual live request and suspends original Messages lifetime', async ({
+ page
+}) => {
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ f.capture();
+ f.start();
+ });
+ await expect.poll(() => requests.length).toBe(2);
+ await page.evaluate(() => window.hcp095Fixture.navigateAway());
+ await expect.poll(() => closes.length).toBeGreaterThanOrEqual(2);
+ expect(
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ return { snapshot: f.snapshot(), start: f.start(), capture: f.capture() };
+ })
+ ).toMatchObject({
+ snapshot: {
+ state: 'stopped',
+ foregroundOnly: true,
+ historyComplete: false
+ },
+ start: false,
+ capture: false
+ });
+ expect(requests).toHaveLength(2);
+});
+test('closed original unlocked cache refuses foreground receive without sockets', async ({
+ page
+}) => {
+ expect(
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ f.closeUnlock();
+ return f.capture();
+ })
+ ).toBe(false);
+ expect(requests).toEqual([]);
+});
+test('revoked actual access after capture fences start', async ({ page }) => {
+ expect(
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ f.capture();
+ f.revokeAccess();
+ return f.start();
+ })
+ ).toBe(false);
+ expect(requests).toEqual([]);
+});
+test('fresh extension owner changed before transport prevents live or history REQ', async ({
+ page
+}) => {
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ f.capture();
+ f.changeKey();
+ f.start();
+ });
+ await expect
+ .poll(() => page.evaluate(() => window.hcp095Fixture.snapshot()?.state))
+ .toBe('stopped');
+ expect(requests).toEqual([]);
+});
+test('logout closes captured scope and never revives hidden retrieval', async ({
+ page
+}) => {
+ expect(
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ f.capture();
+ f.logout();
+ return { start: f.start(), capture: f.capture(), snapshot: f.snapshot() };
+ })
+ ).toMatchObject({
+ start: false,
+ capture: false,
+ snapshot: { state: 'stopped' }
+ });
+ expect(requests).toEqual([]);
+});
+test('121 duplicate live deliveries charge before dedup and pause the source', async ({
+ page
+}) => {
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ f.capture();
+ f.start();
+ });
+ await expect.poll(() => requests.length).toBe(2);
+ const e = eventFrom(await page.evaluate(() => window.hcp095Fixture.outer));
+ for (let i = 0; i < 121; i++) deliver(e);
+ await expect
+ .poll(() => page.evaluate(() => window.hcp095Fixture.snapshot()?.state))
+ .toBe('needs_action');
+ expect(
+ await page.evaluate(() => window.hcp095Fixture.snapshot())
+ ).toMatchObject({ reason: 'budget', historyComplete: false });
+ await expect.poll(() => closes.length).toBeGreaterThanOrEqual(2);
+ expect(await page.evaluate(() => window.hcp095Fixture.publicContains())).toBe(
+ false
+ );
+});
+test('actual native retention abort pauses both subscriptions without durable credit', async ({
+ page
+}) => {
+ frames = [eventFrom(await page.evaluate(() => window.hcp095Fixture.outer))];
+ await page.evaluate(() => {
+ const f = window.hcp095Fixture;
+ f.faultRetention('abort');
+ f.capture();
+ f.start();
+ });
+ await expect
+ .poll(() => page.evaluate(() => window.hcp095Fixture.snapshot()?.state))
+ .toBe('needs_action');
+ expect(
+ await page.evaluate(async () => {
+ const f = window.hcp095Fixture;
+ f.restoreFault();
+ return { snapshot: f.snapshot(), stored: await f.stored() };
+ })
+ ).toMatchObject({
+ snapshot: { retained: 0, reason: 'aborted' },
+ stored: undefined
+ });
+});
diff --git a/web/tests/unit/inbox-sync.test.ts b/web/tests/unit/inbox-sync.test.ts
@@ -0,0 +1,22 @@
+import { test, expect } from 'vitest';
+import { privateInboxQueries } from '../../src/lib/nostr/inbox-queries.ts';
+const owner = 'a'.repeat(64);
+test('live filter requests no retained history and admits future backdated outer events', () =>
+ expect(privateInboxQueries(owner, 'live')).toEqual([
+ { kinds: [1059], '#p': [owner], limit: 0 }
+ ]));
+test('finite backfill requests the bounded existing 200 without inner time cursor', () =>
+ expect(privateInboxQueries(owner, 'backfill')).toEqual([
+ { kinds: [1059], '#p': [owner], limit: 200 }
+ ]));
+test('noncanonical owner cannot construct a private query', () =>
+ expect(() => privateInboxQueries('not a key', 'live')).toThrow());
+test('unknown mode cannot silently make a live or history request', () =>
+ expect(() => privateInboxQueries(owner, 'unreviewed' as 'live')).toThrow());
+test('query result mutation cannot alter later private filter scope', () => {
+ const a = privateInboxQueries(owner, 'live');
+ a[0].kinds!.push(14);
+ expect(privateInboxQueries(owner, 'live')).toEqual([
+ { kinds: [1059], '#p': [owner], limit: 0 }
+ ]);
+});