commit 29c1681d1d30dfe295efc9efc896a65f54d0144c
parent 518f47c5899d27ed8f5e6a85704a2714c00b0d5f
Author: triesap <tyson@radroots.org>
Date: Wed, 7 Oct 2026 07:02:36 +0000
messages: select role-specific approved inbox intersections (HCP-063)
- Derive peer routes and sender archive independently from admitted preferences.
- Freeze role owners, known source versions and allowlisted destinations.
- Block unavailable evidence and require review when observations change.
- Test empty intersections, forged tokens and immutable routing snapshots.
Diffstat:
4 files changed, 604 insertions(+), 0 deletions(-)
diff --git a/web/src/lib/messaging/inbox-routing.ts b/web/src/lib/messaging/inbox-routing.ts
@@ -0,0 +1,143 @@
+import { canonicalPublicKey } from '../contracts/public-key.ts';
+import {
+ inboxRelayTargets,
+ publicRelayTargets,
+ type RelayPolicy
+} from '../config/relays.ts';
+import { inboxPreferenceSnapshot } from '../nostr/inbox-preferences.ts';
+import {
+ inboxResolutionSnapshot,
+ inboxResolverCurrentAfterSample,
+ type InboxResolver
+} from './resolve-inbox.ts';
+
+declare const routeBrand: unique symbol;
+export type InboxRoutePlan = Readonly<{ readonly [routeBrand]: true }>;
+type Role = 'peer' | 'self_archive';
+type Route = Readonly<{
+ role: Role;
+ author: string;
+ targets: string[];
+ knownBase: Readonly<{ author: string; id: string; createdAt: number }>;
+ sources: {
+ source: string;
+ state: string;
+ head?: Readonly<{ id: string; createdAt: number }>;
+ }[];
+}>;
+export type InboxRouteSnapshot = Readonly<{ peer: Route; archive: Route }>;
+// Only admitted snapshots of genuine discovery and policy owners enter this map.
+// The plan is preparation evidence, never private-effect or access permission.
+const plans = new WeakMap<InboxRoutePlan, string>();
+function route(
+ policy: RelayPolicy,
+ author: string,
+ resolver: InboxResolver,
+ role: Role
+): Route | undefined {
+ const resolution = inboxResolutionSnapshot(resolver);
+ const origins = publicRelayTargets(policy, 'read');
+ if (
+ resolution.author !== author ||
+ resolution.status !== 'ready' ||
+ resolution.coverage !== 'bounded-eose' ||
+ !resolution.head ||
+ !resolution.knownBase ||
+ origins.length === 0 ||
+ resolution.sources.length !== origins.length ||
+ !origins.every((origin) =>
+ resolution.sources.some(
+ (row) => row.source === origin && row.state === 'eose'
+ )
+ )
+ )
+ return undefined;
+ const preference = inboxPreferenceSnapshot(resolution.head);
+ if (
+ !preference ||
+ preference.status !== 'supported' ||
+ preference.author !== author ||
+ preference.id !== resolution.knownBase.id ||
+ preference.createdAt !== resolution.knownBase.createdAt
+ )
+ return undefined;
+ const targets = inboxRelayTargets(policy, preference.relays, 'write').slice();
+ if (targets.length === 0) return undefined;
+ return {
+ role,
+ author,
+ targets,
+ knownBase: { ...resolution.knownBase },
+ sources: resolution.sources.map((row) => ({
+ source: row.source,
+ state: row.state,
+ ...(row.head ? { head: { ...row.head } } : {})
+ }))
+ };
+}
+function capture(
+ policy: RelayPolicy,
+ sender: unknown,
+ peer: unknown,
+ own: InboxResolver,
+ other: InboxResolver
+): InboxRouteSnapshot | undefined {
+ const senderKey = canonicalPublicKey(sender),
+ peerKey = canonicalPublicKey(peer);
+ if (!senderKey || !peerKey || senderKey === peerKey) return undefined;
+ try {
+ const archive = route(policy, senderKey, own, 'self_archive'),
+ recipient = route(policy, peerKey, other, 'peer');
+ if (
+ !archive ||
+ !recipient ||
+ !inboxResolverCurrentAfterSample(own) ||
+ !inboxResolverCurrentAfterSample(other)
+ )
+ return undefined;
+ return { peer: recipient, archive };
+ } catch {
+ return undefined;
+ }
+}
+export function createInboxRoutePlan(
+ policy: RelayPolicy,
+ sender: unknown,
+ peer: unknown,
+ own: InboxResolver,
+ other: InboxResolver
+): InboxRoutePlan | undefined {
+ const snapshot = capture(policy, sender, peer, own, other);
+ if (!snapshot) return undefined;
+ const token = Object.freeze({}) as InboxRoutePlan;
+ plans.set(token, JSON.stringify(snapshot));
+ return token;
+}
+export function inboxRoutePlanSnapshot(
+ token: InboxRoutePlan
+): InboxRouteSnapshot | undefined {
+ const saved = plans.get(token);
+ return saved ? (JSON.parse(saved) as InboxRouteSnapshot) : undefined;
+}
+// Any changed known head, named source version or destination requires explicit
+// later review. The original plan remains immutable; no replay or rerouting.
+export function recheckInboxRoutePlan(
+ token: InboxRoutePlan,
+ policy: RelayPolicy,
+ own: InboxResolver,
+ other: InboxResolver
+): 'unchanged' | 'review_required' | 'unavailable' {
+ const previous = inboxRoutePlanSnapshot(token);
+ if (!previous) return 'unavailable';
+ const current = capture(
+ policy,
+ previous.archive.author,
+ previous.peer.author,
+ own,
+ other
+ );
+ if (!current) return 'unavailable';
+ return JSON.stringify(current) === plans.get(token)
+ ? 'unchanged'
+ : 'review_required';
+}
diff --git a/web/src/lib/messaging/resolve-inbox.ts b/web/src/lib/messaging/resolve-inbox.ts
@@ -13,6 +13,7 @@ import {
publicRequestScopeSnapshot,
publicRunObservations,
publicRunSnapshot,
+ publicRunCurrentAfterSample,
type PublicRun,
type PublicRequest
} from '../nostr/request-scope.ts';
@@ -44,6 +45,7 @@ export type InboxResolution = Readonly<{
interface Owner {
readonly snapshot: () => InboxResolution;
readonly close: () => void;
+ readonly currentAfterSample: () => boolean;
}
const owners = new WeakMap<InboxResolver, Owner>();
function ownerOf(token: InboxResolver): Owner {
@@ -141,6 +143,10 @@ export function createInboxResolver(
wireProvenance: 'decoded-sdk-json'
};
},
+ // The trusted generation observer is a pure owner read, like the production
+ // view port. This final fence deliberately never samples an injected clock.
+ currentAfterSample: () =>
+ !closed && current() && publicRunCurrentAfterSample(run),
close() {
closed = true;
closePublicRequest(request);
@@ -191,3 +197,7 @@ export function inboxResolutionSnapshot(token: InboxResolver): InboxResolution {
export function closeInboxResolver(token: InboxResolver): void {
ownerOf(token).close();
}
+
+export function inboxResolverCurrentAfterSample(token: InboxResolver): boolean {
+ return ownerOf(token).currentAfterSample();
+}
diff --git a/web/src/lib/nostr/request-scope.ts b/web/src/lib/nostr/request-scope.ts
@@ -45,6 +45,7 @@ const browserClock: RequestClock = {
};
interface SchedulerOwner {
readonly now: () => number;
+ readonly sampledNow: () => number;
readonly schedule: RequestClock['schedule'];
readonly available: () => void;
readonly reserve: (token: PublicRequest, close: () => boolean) => void;
@@ -71,6 +72,7 @@ interface RunOwner {
inboxAuthor?: string
) => PublicRequest;
readonly active: () => boolean;
+ readonly currentAfterSample: () => boolean;
readonly snapshot: () => Readonly<{
deadline: number;
active: boolean;
@@ -125,6 +127,7 @@ export function createPublicScheduler(
last = Math.max(last, value);
return last;
},
+ sampledNow: () => last,
schedule: (callback, delay) => clock.schedule(callback, delay),
available() {
if (closed) throw new Error('public_scheduler_closed');
@@ -198,6 +201,12 @@ export function createPublicRun(
if (row.run !== token) throw new Error('public_request_run_changed');
return row.result;
},
+ currentAfterSample: () =>
+ !cancelled &&
+ !disposed &&
+ !shared.snapshot().closed &&
+ shared.sampledNow() < deadline &&
+ !publicIngressStats(ingress).stopped,
active: () =>
!cancelled &&
!disposed &&
@@ -406,6 +415,11 @@ export function closePublicScheduler(scheduler: PublicScheduler): void {
export function publicSchedulerSnapshot(scheduler: PublicScheduler) {
return schedulerOf(scheduler).snapshot();
}
+// Final fence after callers sample their relevant clocks. No external clock
+// call or fresh wall-time promise: cached monotonic sample plus actual owners.
+export function publicRunCurrentAfterSample(run: PublicRun): boolean {
+ return runOf(run).currentAfterSample();
+}
export function publicRunSnapshot(run: PublicRun) {
return runOf(run).snapshot();
}
diff --git a/web/tests/unit/inbox-routing.test.ts b/web/tests/unit/inbox-routing.test.ts
@@ -0,0 +1,437 @@
+import { describe, it, expect } from 'vitest';
+import { finalizeEvent } from 'applesauce-core/helpers';
+import {
+ validateRelayPolicy,
+ type RelayPolicy
+} from '../../src/lib/config/relays.ts';
+import {
+ createPublicScheduler,
+ createPublicRun,
+ openInboxRequest,
+ closePublicScheduler
+} from '../../src/lib/nostr/request-scope.ts';
+import {
+ createInboxResolver,
+ type InboxResolver
+} from '../../src/lib/messaging/resolve-inbox.ts';
+import { inboxPreferenceSnapshot } from '../../src/lib/nostr/inbox-preferences.ts';
+import { inboxResolutionSnapshot } from '../../src/lib/messaging/resolve-inbox.ts';
+import {
+ createInboxRoutePlan,
+ inboxRoutePlanSnapshot,
+ recheckInboxRoutePlan
+} from '../../src/lib/messaging/inbox-routing.ts';
+const discovery = 'wss://discovery.example.org',
+ peerOrigin = 'wss://peer.example.org',
+ archiveOrigin = 'wss://archive.example.org',
+ common = 'wss://common.example.org',
+ unapproved = 'wss://hint.example.org';
+function policy(targets = [peerOrigin, archiveOrigin, common]): RelayPolicy {
+ return validateRelayPolicy(
+ JSON.stringify({
+ schemaVersion: 1,
+ public: [{ origin: discovery, read: true, write: false, nip50: false }],
+ inbox: targets.map((origin) => ({ origin, read: true, write: true })),
+ postingEnabled: false,
+ messagingEnabled: false,
+ operatorDenylist: []
+ })
+ )!;
+}
+function author(relays: string[]) {
+ const key = crypto.getRandomValues(new Uint8Array(32));
+ try {
+ const tags = relays.map((origin) => ['relay', origin]);
+ const original = finalizeEvent(
+ {
+ kind: 10050,
+ created_at: 100,
+ tags: [...tags, ['unknown', 'preserve']],
+ content: ''
+ },
+ key
+ );
+ const removed = finalizeEvent(
+ { kind: 10050, created_at: 200, tags: tags.slice(1), content: '' },
+ key
+ );
+ const changed = finalizeEvent(
+ {
+ kind: 10050,
+ created_at: 201,
+ tags: [...tags, ['unknown', 'changed']],
+ content: ''
+ },
+ key
+ );
+ return { original, removed, changed };
+ } finally {
+ key.fill(0);
+ }
+}
+function resolved(
+ event: ReturnType<typeof author>['original'],
+ complete = true,
+ now: () => number = () => 0
+) {
+ const scheduler = createPublicScheduler({
+ now,
+ schedule: () => () => {}
+ }),
+ run = createPublicRun(scheduler, policy());
+ let current = true;
+ const resolver = createInboxResolver(
+ run,
+ event.pubkey,
+ (next) =>
+ openInboxRequest(
+ run,
+ event.pubkey,
+ (sink) => {
+ sink({ type: 'EVENT', from: discovery, id: 'fixture', event });
+ if (complete) sink({ type: 'EOSE', from: discovery, id: 'fixture' });
+ return () => {};
+ },
+ next
+ ),
+ () => current
+ );
+ return {
+ resolver,
+ close: () => closePublicScheduler(scheduler),
+ stale() {
+ current = false;
+ }
+ };
+}
+function fixture(
+ peerRelays = [peerOrigin, common],
+ selfRelays = [archiveOrigin]
+) {
+ const self = author(selfRelays),
+ peer = author(peerRelays),
+ own = resolved(self.original),
+ other = resolved(peer.original);
+ return {
+ self,
+ peer,
+ own,
+ other,
+ close() {
+ own.close();
+ other.close();
+ }
+ };
+}
+describe('recipient and sender archive routing', () => {
+ it('selects recipient advertised allowed writes and computes sender archive independently', () => {
+ const f = fixture();
+ try {
+ const plan = createInboxRoutePlan(
+ policy(),
+ f.self.original.pubkey,
+ f.peer.original.pubkey,
+ f.own.resolver,
+ f.other.resolver
+ )!;
+ const r = inboxRoutePlanSnapshot(plan)!;
+ expect(r.peer).toMatchObject({
+ role: 'peer',
+ author: f.peer.original.pubkey,
+ targets: [peerOrigin, common],
+ knownBase: { id: f.peer.original.id }
+ });
+ expect(r.archive).toMatchObject({
+ role: 'self_archive',
+ author: f.self.original.pubkey,
+ targets: [archiveOrigin],
+ knownBase: { id: f.self.original.id }
+ });
+ expect(Object.keys(plan)).toEqual([]);
+ expect(Object.isFrozen(plan)).toBe(true);
+ } finally {
+ f.close();
+ }
+ });
+ it('empty peer intersection never falls back to sender archive or public discovery', () => {
+ const f = fixture([unapproved]);
+ try {
+ expect(
+ createInboxRoutePlan(
+ policy(),
+ f.self.original.pubkey,
+ f.peer.original.pubkey,
+ f.own.resolver,
+ f.other.resolver
+ )
+ ).toBeUndefined();
+ } finally {
+ f.close();
+ }
+ });
+ it('empty sender archive never falls back to peer destinations', () => {
+ const f = fixture([peerOrigin], [unapproved]);
+ try {
+ expect(
+ createInboxRoutePlan(
+ policy(),
+ f.self.original.pubkey,
+ f.peer.original.pubkey,
+ f.own.resolver,
+ f.other.resolver
+ )
+ ).toBeUndefined();
+ } finally {
+ f.close();
+ }
+ });
+ it('keeps all advertised preference data while limiting selected routes to the fixed allowlist', () => {
+ const f = fixture([
+ unapproved,
+ peerOrigin,
+ common,
+ archiveOrigin,
+ 'wss://fifth.example.org'
+ ]);
+ try {
+ const before = inboxPreferenceSnapshot(
+ inboxResolutionSnapshot(f.other.resolver).head!
+ )!;
+ expect(before.relays).toHaveLength(5);
+ const plan = createInboxRoutePlan(
+ policy(),
+ f.self.original.pubkey,
+ f.peer.original.pubkey,
+ f.own.resolver,
+ f.other.resolver
+ )!;
+ expect(inboxRoutePlanSnapshot(plan)?.peer.targets).toEqual([
+ peerOrigin,
+ archiveOrigin,
+ common
+ ]);
+ expect(
+ inboxPreferenceSnapshot(inboxResolutionSnapshot(f.other.resolver).head!)
+ ).toEqual(before);
+ } finally {
+ f.close();
+ }
+ });
+ it('rejects forged resolution/policy, invalid identities, swapped authors and self messaging', () => {
+ const f = fixture();
+ try {
+ expect(
+ createInboxRoutePlan(
+ policy(),
+ f.self.original.pubkey,
+ f.peer.original.pubkey,
+ {} as InboxResolver,
+ f.other.resolver
+ )
+ ).toBeUndefined();
+ expect(
+ createInboxRoutePlan(
+ {} as RelayPolicy,
+ f.self.original.pubkey,
+ f.peer.original.pubkey,
+ f.own.resolver,
+ f.other.resolver
+ )
+ ).toBeUndefined();
+ expect(
+ createInboxRoutePlan(
+ policy(),
+ 'f'.repeat(64),
+ f.peer.original.pubkey,
+ f.own.resolver,
+ f.other.resolver
+ )
+ ).toBeUndefined();
+ expect(
+ createInboxRoutePlan(
+ policy(),
+ f.peer.original.pubkey,
+ f.self.original.pubkey,
+ f.own.resolver,
+ f.other.resolver
+ )
+ ).toBeUndefined();
+ expect(
+ createInboxRoutePlan(
+ policy(),
+ f.self.original.pubkey,
+ f.self.original.pubkey,
+ f.own.resolver,
+ f.own.resolver
+ )
+ ).toBeUndefined();
+ expect(
+ inboxRoutePlanSnapshot(
+ {} as NonNullable<ReturnType<typeof createInboxRoutePlan>>
+ )
+ ).toBeUndefined();
+ } finally {
+ f.close();
+ }
+ });
+ it('partial, unsupported or stale preference evidence cannot produce routes', () => {
+ const f = fixture(),
+ partial = resolved(f.peer.original, false);
+ try {
+ expect(
+ createInboxRoutePlan(
+ policy(),
+ f.self.original.pubkey,
+ f.peer.original.pubkey,
+ f.own.resolver,
+ partial.resolver
+ )
+ ).toBeUndefined();
+ f.other.stale();
+ expect(
+ createInboxRoutePlan(
+ policy(),
+ f.self.original.pubkey,
+ f.peer.original.pubkey,
+ f.own.resolver,
+ f.other.resolver
+ )
+ ).toBeUndefined();
+ } finally {
+ f.close();
+ partial.close();
+ }
+ const g = fixture([peerOrigin]),
+ bad = resolved(g.peer.removed);
+ try {
+ expect(
+ createInboxRoutePlan(
+ policy(),
+ g.self.original.pubkey,
+ g.peer.original.pubkey,
+ g.own.resolver,
+ bad.resolver
+ )
+ ).toBeUndefined();
+ } finally {
+ g.close();
+ bad.close();
+ }
+ });
+ it('detached snapshots cannot retarget the opaque plan', () => {
+ const f = fixture();
+ try {
+ const p = createInboxRoutePlan(
+ policy(),
+ f.self.original.pubkey,
+ f.peer.original.pubkey,
+ f.own.resolver,
+ f.other.resolver
+ )!;
+ const r = inboxRoutePlanSnapshot(p)!;
+ r.peer.targets.push(unapproved);
+ r.peer.sources.pop();
+ expect(inboxRoutePlanSnapshot(p)?.peer.targets).toEqual([
+ peerOrigin,
+ common
+ ]);
+ expect(inboxRoutePlanSnapshot(p)?.peer.sources).toHaveLength(1);
+ expect(
+ recheckInboxRoutePlan(p, policy(), f.own.resolver, f.other.resolver)
+ ).toBe('unchanged');
+ } finally {
+ f.close();
+ }
+ });
+ it('removed approved destinations and changed known preference versions require explicit review', () => {
+ const f = fixture(),
+ removed = resolved(f.peer.removed),
+ version = resolved(f.peer.changed);
+ try {
+ const p = createInboxRoutePlan(
+ policy(),
+ f.self.original.pubkey,
+ f.peer.original.pubkey,
+ f.own.resolver,
+ f.other.resolver
+ )!;
+ expect(
+ recheckInboxRoutePlan(
+ p,
+ policy([archiveOrigin, common]),
+ f.own.resolver,
+ f.other.resolver
+ )
+ ).toBe('review_required');
+ expect(
+ recheckInboxRoutePlan(p, policy(), f.own.resolver, removed.resolver)
+ ).toBe('review_required');
+ expect(
+ recheckInboxRoutePlan(p, policy(), f.own.resolver, version.resolver)
+ ).toBe('review_required');
+ expect(inboxRoutePlanSnapshot(p)?.peer.targets).toEqual([
+ peerOrigin,
+ common
+ ]);
+ f.other.stale();
+ expect(
+ recheckInboxRoutePlan(p, policy(), f.own.resolver, f.other.resolver)
+ ).toBe('unavailable');
+ } finally {
+ f.close();
+ removed.close();
+ version.close();
+ }
+ });
+});
+
+it('peer clock reentry cannot admit a stale sender archive captured first', () => {
+ const f = fixture();
+ let armed = false;
+ const peer = resolved(f.peer.original, true, () => {
+ if (armed) f.own.stale();
+ return 0;
+ });
+ try {
+ armed = true;
+ expect(
+ createInboxRoutePlan(
+ policy(),
+ f.self.original.pubkey,
+ f.peer.original.pubkey,
+ f.own.resolver,
+ peer.resolver
+ )
+ ).toBeUndefined();
+ } finally {
+ f.close();
+ peer.close();
+ }
+});
+
+it('peer clock reentry cannot report unchanged after sender scheduler closes', () => {
+ const f = fixture();
+ let armed = false;
+ const peer = resolved(f.peer.original, true, () => {
+ if (armed) f.own.close();
+ return 0;
+ });
+ try {
+ const p = createInboxRoutePlan(
+ policy(),
+ f.self.original.pubkey,
+ f.peer.original.pubkey,
+ f.own.resolver,
+ peer.resolver
+ )!;
+ expect(p).toBeDefined();
+ armed = true;
+ expect(
+ recheckInboxRoutePlan(p, policy(), f.own.resolver, peer.resolver)
+ ).toBe('unavailable');
+ expect(inboxRoutePlanSnapshot(p)?.archive.targets).toEqual([archiveOrigin]);
+ } finally {
+ f.close();
+ peer.close();
+ }
+});