commit 1e432732c75af10c9e2b516c3f8f3ff6a9dc9e54
parent 09ac054ab1f75258fedc7a8cb4cfaa9b2171f2bb
Author: triesap <tyson@radroots.org>
Date: Tue, 6 Oct 2026 08:11:07 +0000
web: Own the anonymous HarvestCircle relay pool
- Pin inspected Applesauce relay exports and preserve fixed public origins
- Keep SSR inert and unsolicited AUTH outside signing capabilities
- Close reentrant subscriptions and permit failed cleanup retries
- Test lifecycle behavior and align isolated browser fixture dependencies
Diffstat:
6 files changed, 529 insertions(+), 1 deletion(-)
diff --git a/web/package.json b/web/package.json
@@ -24,7 +24,8 @@
"dependencies": {
"@noble/curves": "1.2.0",
"@scure/base": "1.1.1",
- "applesauce-core": "6.2.0"
+ "applesauce-core": "6.2.0",
+ "applesauce-relay": "6.2.1"
},
"devDependencies": {
"@eslint/js": "10.0.1",
diff --git a/web/pnpm-lock.yaml b/web/pnpm-lock.yaml
@@ -216,6 +216,9 @@ importers:
applesauce-core:
specifier: 6.2.0
version: 6.2.0(typescript@6.0.3)
+ applesauce-relay:
+ specifier: 6.2.1
+ version: 6.2.1(typescript@6.0.3)
devDependencies:
'@eslint/js':
specifier: 10.0.1
@@ -467,6 +470,13 @@ packages:
}
engines: { node: '>= 16' }
+ '@noble/hashes@2.4.0':
+ resolution:
+ {
+ integrity: sha512-X5XaVWZIBCT7HHZGm5I7ZQXDwLG+bGXuSrMQAW+7Zvl87h1kmc1ZB1VSRJcpUfoUrGQp4Fkoxm5kZ+Ms+aW+eA==
+ }
+ engines: { node: '>= 20.19.0' }
+
'@opentelemetry/api@1.9.1':
resolution:
{
@@ -896,6 +906,12 @@ packages:
integrity: sha512-O6AlVyzqcuIhTOIuexm6UWmx7mRIa2D98gJP7K7vFGf90YdtvSH78AsKQWZXJ0Pk/K14at+9zkwfCkFr7ghgNw==
}
+ applesauce-relay@6.2.1:
+ resolution:
+ {
+ integrity: sha512-YIUHEtL2Fl5FZjeKYe/IuwL3OnMUNP2j4ydSr3iZDeHEZSEda4d1PoChefiNhtjE/U/F5OBHEbAX1zCHRZoxpg==
+ }
+
aria-query@5.3.1:
resolution:
{
@@ -2158,6 +2174,8 @@ snapshots:
'@noble/hashes@1.3.2': {}
+ '@noble/hashes@2.4.0': {}
+
'@opentelemetry/api@1.9.1': {}
'@oxc-project/types@0.152.0': {}
@@ -2414,6 +2432,17 @@ snapshots:
- supports-color
- typescript
+ applesauce-relay@6.2.1(typescript@6.0.3):
+ dependencies:
+ '@noble/hashes': 2.4.0
+ applesauce-core: 6.2.0(typescript@6.0.3)
+ nanoid: 5.1.16
+ nostr-tools: 2.19.4(typescript@6.0.3)
+ rxjs: 7.8.2
+ transitivePeerDependencies:
+ - supports-color
+ - typescript
+
aria-query@5.3.1: {}
assertion-error@2.0.1: {}
diff --git a/web/src/lib/nostr/exports.ts b/web/src/lib/nostr/exports.ts
@@ -0,0 +1,3 @@
+// Type-only adapter vocabulary; the SDK pool stays inside its lifecycle owner.
+export type { Filter as PublicFilter } from 'applesauce-core/helpers/filter';
+export type { GroupReqMessage as PublicPoolMessage } from 'applesauce-relay/types';
diff --git a/web/src/lib/nostr/public-pool.ts b/web/src/lib/nostr/public-pool.ts
@@ -0,0 +1,142 @@
+import { RelayPool } from 'applesauce-relay/pool';
+import { deploymentRelayPolicy } from '../config/deployment-relays.ts';
+import {
+ publicRelayTargets,
+ readRelayPolicy,
+ type RelayPolicy
+} from '../config/relays.ts';
+import type { PublicFilter, PublicPoolMessage } from './exports.ts';
+
+declare const ownedPool: unique symbol;
+export type PublicPool = Readonly<{ readonly [ownedPool]: true }>;
+interface Owner {
+ readonly policy: RelayPolicy;
+ readonly token: PublicPool;
+ readonly origins: readonly string[];
+ readonly closed: () => boolean;
+ readonly subscribe: (
+ filters: readonly PublicFilter[],
+ onMessage: (message: PublicPoolMessage) => void
+ ) => () => void;
+ readonly close: () => void;
+}
+const owners = new WeakMap<PublicPool, Owner>();
+let lifetime: Owner | undefined;
+
+// Anonymous state exists only after browser acquisition. No socket, information
+// fetch, identity or extension operation occurs during import or SSR.
+export function getPublicPool(
+ policy: RelayPolicy = deploymentRelayPolicy
+): PublicPool | undefined {
+ if (typeof window === 'undefined') return undefined;
+ readRelayPolicy(policy);
+ if (lifetime) {
+ if (lifetime.closed()) throw new Error('public_pool_closed');
+ if (lifetime.policy !== policy)
+ throw new Error('public_pool_policy_changed');
+ return lifetime.token;
+ }
+ const token = Object.freeze({}) as PublicPool;
+ const origins = publicRelayTargets(policy, 'read');
+ const sdk = new RelayPool({
+ keepAlive: 0,
+ enablePing: false,
+ requestReconnect: 0,
+ subscriptionReconnect: 0
+ });
+ const active = new Map<() => void, true>();
+ let closed = false;
+ let cleanupComplete = false;
+ const owner: Owner = {
+ policy,
+ token,
+ origins,
+ closed: () => closed,
+ subscribe(filters, onMessage) {
+ if (closed) throw new Error('public_pool_closed');
+ let release = () => {};
+ const subscription = sdk
+ .req([...origins], [...filters], {
+ waitForAuth: false,
+ reconnect: false,
+ resubscribe: false
+ })
+ .subscribe({
+ next: (message) => {
+ if (!closed) onMessage(message);
+ },
+ complete: () => release(),
+ error: () => release()
+ });
+ const stop = () => {
+ try {
+ subscription.unsubscribe();
+ } finally {
+ active.delete(stop);
+ }
+ };
+ release = stop;
+ if (closed) stop();
+ else if (!subscription.closed) active.set(stop, true);
+ return stop;
+ },
+ close() {
+ if (cleanupComplete) return;
+ closed = true;
+ let failed = false;
+ for (const stop of active.keys()) {
+ try {
+ stop();
+ } catch {
+ failed = true;
+ }
+ }
+ try {
+ sdk.close();
+ } catch {
+ failed = true;
+ }
+ cleanupComplete = !failed;
+ if (failed) throw new Error('public_pool_close_failed');
+ }
+ };
+ owners.set(token, owner);
+ lifetime = owner;
+ return token;
+}
+
+function ownerOf(token: PublicPool): Owner {
+ const owner = owners.get(token);
+ if (!owner) throw new Error('public_pool_invalid');
+ return owner;
+}
+export function publicPoolOrigins(token: PublicPool): readonly string[] {
+ return [...ownerOf(token).origins];
+}
+
+// Filter construction and event verification/work budgets have separate owners.
+// Accept no SDK filter callback (which would expose a raw relay), arbitrary
+// destination, AUTH method, information fetch or retry option through this API.
+export function subscribePublicPool(
+ token: PublicPool,
+ filters: readonly PublicFilter[],
+ onMessage: (message: PublicPoolMessage) => void
+): () => void {
+ const owner = ownerOf(token);
+ if (owner.closed()) throw new Error('public_pool_closed');
+ if (
+ !Array.isArray(filters) ||
+ filters.length === 0 ||
+ filters.some(
+ (filter) => !filter || typeof filter !== 'object' || Array.isArray(filter)
+ )
+ )
+ throw new Error('public_pool_filters_invalid');
+ return owner.subscribe(filters, onMessage);
+}
+
+// Terminal browser-lifetime shutdown: cancel request controls before closing the
+// SDK sockets and its keepalive/reconnect watchers. Routes cannot recreate it.
+export function closePublicPool(token: PublicPool): void {
+ ownerOf(token).close();
+}
diff --git a/web/tests/e2e/search-form.spec.ts b/web/tests/e2e/search-form.spec.ts
@@ -32,6 +32,8 @@ test.beforeAll(async () => {
checkout
]);
for (const relative of [
+ 'web/package.json',
+ 'web/pnpm-lock.yaml',
'web/src',
'web/tools/source-boundaries.mjs',
'web/src/lib/components/AppShell.svelte',
diff --git a/web/tests/integration/public-pool.test.ts b/web/tests/integration/public-pool.test.ts
@@ -0,0 +1,351 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import WebSocket, { WebSocketServer } from 'ws';
+import { RelayPool } from 'applesauce-relay/pool';
+import { validateRelayPolicy } from '../../src/lib/config/relays.ts';
+import {
+ getPublicPool,
+ publicPoolOrigins,
+ subscribePublicPool,
+ closePublicPool
+} from '../../src/lib/nostr/public-pool.ts';
+
+// HC_TEST_ONLY_RELAY: SDK constructor mapping is confined to this test.
+await test('anonymous public pool owns one browser lifetime', async (t) => {
+ const origins = ['wss://relay.example.org', 'wss://relay-two.example.org'];
+ const policy = validateRelayPolicy(
+ JSON.stringify({
+ schemaVersion: 1,
+ public: origins.map((origin) => ({
+ origin,
+ read: true,
+ write: true,
+ nip50: false
+ })),
+ inbox: [],
+ postingEnabled: false,
+ messagingEnabled: false,
+ operatorDenylist: []
+ })
+ );
+ assert.ok(policy);
+ const windowDescriptor = Object.getOwnPropertyDescriptor(
+ globalThis,
+ 'window'
+ );
+ const originalSocket = globalThis.WebSocket;
+ const originalFetch = globalThis.fetch;
+ assert.equal(windowDescriptor, undefined);
+ await t.test(
+ 'SSR import and acquisition perform no browser or socket work',
+ () => {
+ assert.equal(getPublicPool(policy), undefined);
+ }
+ );
+ const server = new WebSocketServer({
+ host: '127.0.0.1',
+ port: 0,
+ maxPayload: 4096
+ });
+ const frames: unknown[][] = [];
+ const sockets: WebSocket[] = [];
+ server.on('connection', (socket) => {
+ sockets.push(socket);
+ socket.send(JSON.stringify(['AUTH', 'unsolicited-test-challenge']));
+ socket.on('message', (bytes) => {
+ const buffer = Array.isArray(bytes)
+ ? Buffer.concat(bytes)
+ : Buffer.isBuffer(bytes)
+ ? bytes
+ : Buffer.from(bytes);
+ const frame: unknown = JSON.parse(buffer.toString('utf8'));
+ assert.ok(Array.isArray(frame));
+ frames.push(frame);
+ if (frame[0] === 'REQ') socket.send(JSON.stringify(['EOSE', frame[1]]));
+ });
+ });
+ await once(server, 'listening');
+ const address = server.address();
+ assert.ok(address && typeof address !== 'string');
+ const fixturePort = address.port;
+ let constructed = 0;
+ let extensionCalls = 0;
+ class FixtureSocket extends WebSocket {
+ constructor(url: string | URL) {
+ assert.ok(origins.includes(String(url).replace(/\/$/, '')));
+ constructed++;
+ super(`ws://127.0.0.1:${fixturePort}`);
+ }
+ }
+ Object.defineProperty(globalThis, 'window', {
+ configurable: true,
+ value: {
+ nostr: {
+ getPublicKey() {
+ extensionCalls++;
+ throw new Error('Unexpected identity');
+ },
+ signEvent() {
+ extensionCalls++;
+ throw new Error('Unexpected signing');
+ }
+ }
+ }
+ });
+ globalThis.WebSocket =
+ FixtureSocket as unknown as typeof globalThis.WebSocket;
+ globalThis.fetch = () =>
+ Promise.reject(new Error('Unexpected relay information fetch'));
+ let pool: NonNullable<ReturnType<typeof getPublicPool>> | undefined;
+ const stops: Array<() => void> = [];
+ try {
+ await t.test(
+ 'repeated acquisition shares an opaque fixed-origin pool',
+ () => {
+ pool = getPublicPool(policy);
+ assert.ok(pool);
+ assert.equal(getPublicPool(policy), pool);
+ assert.deepEqual(Object.keys(pool), []);
+ assert.ok(Object.isFrozen(pool));
+ assert.deepEqual(publicPoolOrigins(pool), origins);
+ assert.equal(constructed, 0);
+ const detached = publicPoolOrigins(pool) as string[];
+ detached.push('wss://unapproved.example.org');
+ assert.deepEqual(publicPoolOrigins(pool), origins);
+ }
+ );
+ assert.ok(pool);
+ await t.test(
+ 'two scopes reuse sockets and unsolicited AUTH never signs',
+ async () => {
+ const eose = () =>
+ new Promise<void>((resolve, reject) => {
+ const seen = new Set<string>();
+ stops.push(
+ subscribePublicPool(
+ pool!,
+ [{ kinds: [30402], limit: 1 }],
+ (message) => {
+ if (message.type === 'ERROR')
+ reject(
+ message.error instanceof Error
+ ? message.error
+ : new Error('Fixture relay request failed')
+ );
+ if (message.type === 'EOSE') {
+ seen.add(message.from);
+ if (seen.size === origins.length) resolve();
+ }
+ }
+ )
+ );
+ });
+ await eose();
+ await eose();
+ assert.equal(constructed, 2);
+ assert.equal(server.clients.size, 2);
+ assert.equal(extensionCalls, 0);
+ assert.equal(frames.filter((frame) => frame[0] === 'REQ').length, 4);
+ assert.ok(
+ frames.every((frame) => frame[0] !== 'AUTH' && frame[0] !== 'EVENT')
+ );
+ assert.throws(
+ () => subscribePublicPool(pool!, (() => []) as never, () => {}),
+ /public_pool_filters_invalid/
+ );
+ assert.throws(
+ () => publicPoolOrigins({} as never),
+ /public_pool_invalid/
+ );
+ }
+ );
+ await t.test(
+ 'terminal shutdown closes owned sockets and rejects stale use',
+ async () => {
+ const closed = sockets.map((socket) => once(socket, 'close'));
+ closePublicPool(pool!);
+ await Promise.all(closed);
+ assert.equal(server.clients.size, 0);
+ assert.ok(
+ sockets.every((socket) => socket.readyState === WebSocket.CLOSED)
+ );
+ for (const stop of stops) stop();
+ closePublicPool(pool!);
+ assert.throws(() => getPublicPool(policy), /public_pool_closed/);
+ assert.throws(
+ () => subscribePublicPool(pool!, [{}], () => {}),
+ /public_pool_closed/
+ );
+ assert.equal(constructed, 2);
+ assert.equal(extensionCalls, 0);
+ }
+ );
+ } finally {
+ if (pool) closePublicPool(pool);
+ for (const socket of server.clients) socket.terminate();
+ await new Promise<void>((resolve, reject) =>
+ server.close((error) => (error ? reject(error) : resolve()))
+ );
+ globalThis.WebSocket = originalSocket;
+ globalThis.fetch = originalFetch;
+ Reflect.deleteProperty(globalThis, 'window');
+ }
+});
+
+// Actual SDK lifecycle with an inert socket, not real relay qualification.
+await test('callback and failed-close cleanup preserve pool ownership', async (t) => {
+ const originalSocket = globalThis.WebSocket;
+ const policy = validateRelayPolicy(
+ JSON.stringify({
+ schemaVersion: 1,
+ public: [
+ {
+ origin: 'wss://relay.example.org',
+ read: true,
+ write: false,
+ nip50: false
+ }
+ ],
+ inbox: [],
+ postingEnabled: false,
+ messagingEnabled: false,
+ operatorDenylist: []
+ })
+ );
+ assert.ok(policy);
+ class InertSocket {
+ static OPEN = 1;
+ static CLOSED = 3;
+ readyState = 0;
+ onopen?: () => void;
+ onclose?: (event: { wasClean: boolean }) => void;
+ readonly timer: ReturnType<typeof setTimeout>;
+ constructor(url: string) {
+ assert.equal(new URL(url).origin, 'wss://relay.example.org');
+ this.timer = setTimeout(() => {
+ this.readyState = 1;
+ this.onopen?.();
+ }, 0);
+ }
+ send() {}
+ close() {
+ clearTimeout(this.timer);
+ this.readyState = 3;
+ this.onclose?.({ wasClean: true });
+ }
+ }
+ Object.defineProperty(globalThis, 'window', {
+ configurable: true,
+ value: {}
+ });
+ globalThis.WebSocket = InertSocket as unknown as typeof globalThis.WebSocket;
+ try {
+ await t.test(
+ 'synchronous OPEN shutdown retains no group subscriber',
+ async () => {
+ const adapter = (await import(
+ new URL('../../src/lib/nostr/public-pool.ts', import.meta.url).href +
+ '?hcp028-reentrant'
+ )) as typeof import('../../src/lib/nostr/public-pool.ts');
+ const groups: ReturnType<RelayPool['group']>[] = [];
+ const group = Reflect.get<RelayPool, 'group'>(
+ RelayPool.prototype,
+ 'group'
+ );
+ RelayPool.prototype.group = function (
+ this: RelayPool,
+ ...args: Parameters<RelayPool['group']>
+ ) {
+ const value = group.apply(this, args);
+ groups.push(value);
+ return value;
+ };
+ let stop: (() => void) | undefined;
+ try {
+ const pool = adapter.getPublicPool(policy);
+ assert.ok(pool);
+ let opens = 0;
+ stop = adapter.subscribePublicPool(
+ pool,
+ [{ limit: 1 }],
+ (message) => {
+ if (message.type === 'OPEN') {
+ opens++;
+ adapter.closePublicPool(pool);
+ }
+ }
+ );
+ assert.equal(opens, 1);
+ assert.equal(groups.length, 1);
+ // Test-only inspection of the actual SDK's retained subscription.
+ const stream = (groups[0] as unknown as { readonly relays$: unknown })
+ .relays$;
+ assert.ok(
+ stream &&
+ typeof stream === 'object' &&
+ 'observers' in stream &&
+ Array.isArray(stream.observers)
+ );
+ assert.equal(stream.observers.length, 0);
+ } finally {
+ stop?.();
+ RelayPool.prototype.group = group;
+ }
+ }
+ );
+ await t.test(
+ 'failed SDK shutdown stays closed to traffic and can retry cleanup',
+ async () => {
+ const adapter = (await import(
+ new URL('../../src/lib/nostr/public-pool.ts', import.meta.url).href +
+ '?hcp028-close-retry'
+ )) as typeof import('../../src/lib/nostr/public-pool.ts');
+ const close = Reflect.get<RelayPool, 'close'>(
+ RelayPool.prototype,
+ 'close'
+ );
+ let calls = 0;
+ const instances: RelayPool[] = [];
+ RelayPool.prototype.close = function (this: RelayPool) {
+ instances.push(this);
+ calls++;
+ if (calls === 1) throw new Error('HC_TEST_ONLY_SDK_CLOSE_FAILURE');
+ close.call(this);
+ };
+ try {
+ const pool = adapter.getPublicPool(policy);
+ assert.ok(pool);
+ const stop = adapter.subscribePublicPool(
+ pool,
+ [{ limit: 1 }],
+ () => {}
+ );
+ assert.throws(
+ () => adapter.closePublicPool(pool),
+ /public_pool_close_failed/
+ );
+ assert.throws(
+ () => adapter.getPublicPool(policy),
+ /public_pool_closed/
+ );
+ assert.throws(
+ () => adapter.subscribePublicPool(pool, [{}], () => {}),
+ /public_pool_closed/
+ );
+ adapter.closePublicPool(pool);
+ stop();
+ assert.equal(calls, 2);
+ assert.equal(instances[0]?.relays.size, 0);
+ assert.equal(instances[1], instances[0]);
+ } finally {
+ RelayPool.prototype.close = close;
+ if (instances[0]) close.call(instances[0]);
+ }
+ }
+ );
+ } finally {
+ globalThis.WebSocket = originalSocket;
+ Reflect.deleteProperty(globalThis, 'window');
+ }
+});