commit f011fa8879ec777bc1ba870fc47428df408dfd0d
parent 3b445b6868e71abed555650dbd9e1e42979b3f56
Author: triesap <tyson@radroots.org>
Date: Wed, 7 Oct 2026 05:52:43 +0000
messages: parse and preserve inbox preference events (HCP-061)
- Verify kind10050 preferences against their intended canonical author.
- Preserve exact bounded original data behind opaque preference handles.
- Keep unsupported verified heads distinct from unrelated or invalid events.
- Test signed preferences, unknown data, bounds and detached profile ownership.
Diffstat:
4 files changed, 383 insertions(+), 0 deletions(-)
diff --git a/web/src/lib/messaging/inbox-profile.ts b/web/src/lib/messaging/inbox-profile.ts
@@ -0,0 +1,27 @@
+import {
+ inboxPreferenceSnapshot,
+ type InboxPreference
+} from '../nostr/inbox-preferences.ts';
+
+// Detached public preference presentation only. No missing/ready conclusion,
+// guessed destination, connection, provider, persistence or setup effect.
+export function inboxProfileSnapshot(preference: InboxPreference):
+ | Readonly<{
+ author: string;
+ id: string;
+ createdAt: number;
+ status: 'compatible' | 'unsupported';
+ advertised: string[];
+ }>
+ | undefined {
+ const saved = inboxPreferenceSnapshot(preference);
+ return (
+ saved && {
+ author: saved.author,
+ id: saved.id,
+ createdAt: saved.createdAt,
+ status: saved.status === 'supported' ? 'compatible' : 'unsupported',
+ advertised: saved.relays
+ }
+ );
+}
diff --git a/web/src/lib/nostr/inbox-preferences.ts b/web/src/lib/nostr/inbox-preferences.ts
@@ -0,0 +1,99 @@
+import { canonicalPublicKey } from '../contracts/public-key.ts';
+import { canonicalRelayOrigin } from '../config/relays.ts';
+import {
+ verifyEnvelope,
+ verifiedEnvelopeSnapshot
+} from './verified-envelope.ts';
+
+declare const preferenceBrand: unique symbol;
+export type InboxPreference = Readonly<{ [preferenceBrand]: true }>;
+type Status = 'supported' | 'unsupported';
+type Saved = Readonly<{
+ wire: string;
+ author: string;
+ id: string;
+ createdAt: number;
+ status: Status;
+ relays: readonly string[];
+}>;
+export type InboxPreferenceResult =
+ | Readonly<{
+ status: 'rejected';
+ reason: 'invalid_owner' | 'invalid_envelope' | 'wrong_author';
+ }>
+ | Readonly<{ status: 'unrelated' }>
+ | Readonly<{ status: Status; value: InboxPreference }>;
+const preferences = new WeakMap<InboxPreference, Saved>();
+
+// Parse only. A compatible advertised list proves neither current discovery
+// completeness nor allowlist intersection, access, readiness or consent to write.
+// Generic ingress bounds and SDK hashing/signature checks remain authoritative.
+export function readInboxPreference(
+ raw: unknown,
+ intendedAuthor: unknown
+): InboxPreferenceResult {
+ const author = canonicalPublicKey(intendedAuthor);
+ if (!author) return { status: 'rejected', reason: 'invalid_owner' };
+ if (typeof raw !== 'string')
+ return { status: 'rejected', reason: 'invalid_envelope' };
+ const proof = verifyEnvelope(raw);
+ if (!proof.ok) return { status: 'rejected', reason: 'invalid_envelope' };
+ const event = verifiedEnvelopeSnapshot(proof.value);
+ if (!event) return { status: 'rejected', reason: 'invalid_envelope' };
+ if (event.pubkey !== author)
+ return { status: 'rejected', reason: 'wrong_author' };
+ if (event.kind !== 10050) return { status: 'unrelated' };
+ const relays: string[] = [];
+ function appendRelay(origin: string) {
+ relays.push(origin);
+ }
+ let compatible = true;
+ for (const tag of event.tags) {
+ if (tag[0] !== 'relay') continue;
+ const origin = tag.length === 2 ? canonicalRelayOrigin(tag[1]) : undefined;
+ if (!origin) compatible = false;
+ else if (!relays.includes(origin)) appendRelay(origin);
+ }
+ const status =
+ compatible && relays.length !== 0 ? 'supported' : 'unsupported';
+ const token = Object.freeze({}) as InboxPreference;
+ preferences.set(token, {
+ wire: raw,
+ author,
+ id: event.id,
+ createdAt: event.created_at,
+ status,
+ relays: status === 'supported' ? relays : []
+ });
+ // A verified unsupported head survives for the later latest-head resolver.
+ // Never turn malformed/newer data into absence or silently use a partial list.
+ return { status, value: token };
+}
+export function inboxPreferenceSnapshot(token: InboxPreference):
+ | Readonly<{
+ author: string;
+ id: string;
+ createdAt: number;
+ status: Status;
+ relays: string[];
+ }>
+ | undefined {
+ const saved = preferences.get(token);
+ return (
+ saved && {
+ author: saved.author,
+ id: saved.id,
+ createdAt: saved.createdAt,
+ status: saved.status,
+ relays: saved.relays.slice()
+ }
+ );
+}
+// Exact original, including whitespace, duplicate/unknown tags, content and
+// bounded extra fields. Extra root fields are preserved data, not signed claims.
+// Later explicit review owns any update/removal; this adapter never rewrites it.
+export function inboxPreferenceWire(
+ token: InboxPreference
+): string | undefined {
+ return preferences.get(token)?.wire;
+}
diff --git a/web/tests/conformance/inbox-preferences.test.ts b/web/tests/conformance/inbox-preferences.test.ts
@@ -0,0 +1,209 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { finalizeEvent } from 'applesauce-core/helpers';
+import {
+ readInboxPreference,
+ inboxPreferenceSnapshot,
+ inboxPreferenceWire
+} from '../../src/lib/nostr/inbox-preferences.ts';
+import { inboxProfileSnapshot } from '../../src/lib/messaging/inbox-profile.ts';
+const origin = 'wss://one.example.org';
+// Test-only ephemeral SDK signing; no literal secret, persistence, logs or product import.
+function fixture(
+ tags: string[][] = [['relay', origin]],
+ kind = 10050,
+ created_at = 100,
+ content = ''
+) {
+ const key = crypto.getRandomValues(new Uint8Array(32));
+ try {
+ const event = finalizeEvent({ kind, created_at, tags, content }, key);
+ return { event, wire: JSON.stringify(event) };
+ } finally {
+ key.fill(0);
+ }
+}
+void test('10050 relay is independently signed preference, distinct from10002/r and Food', () => {
+ const f = fixture();
+ const result = readInboxPreference(f.wire, f.event.pubkey);
+ assert.equal(result.status, 'supported');
+ if (result.status !== 'supported') throw new Error('not admitted');
+ assert.deepEqual(inboxPreferenceSnapshot(result.value), {
+ author: f.event.pubkey,
+ id: f.event.id,
+ createdAt: 100,
+ status: 'supported',
+ relays: [origin]
+ });
+ assert.deepEqual(inboxProfileSnapshot(result.value), {
+ author: f.event.pubkey,
+ id: f.event.id,
+ createdAt: 100,
+ status: 'compatible',
+ advertised: [origin]
+ });
+ for (const kind of [10002, 30402, 0, 1059]) {
+ const other = fixture([['r', origin]], kind);
+ assert.equal(
+ readInboxPreference(other.wire, other.event.pubkey).status,
+ 'unrelated'
+ );
+ }
+});
+void test('exact raw original includes unknown entries, content and unauthenticated extra fields without truncation', () => {
+ const f = fixture(
+ [
+ ['relay', origin],
+ ['unknown', 'extra', 'values'],
+ ['r', 'wss://other.example.org'],
+ ['relay', origin]
+ ],
+ 10050,
+ 100,
+ 'preserved content'
+ );
+ const wire = JSON.stringify(
+ {
+ ...f.event,
+ extension: { kind: 1.0, created_at: 2, items: ['preserve'] },
+ note: 'untrusted raw extension'
+ },
+ null,
+ 2
+ );
+ const result = readInboxPreference(wire, f.event.pubkey);
+ assert.equal(result.status, 'supported');
+ if (result.status !== 'supported') throw new Error('not admitted');
+ assert.equal(inboxPreferenceWire(result.value), wire);
+ const preserved: unknown = JSON.parse(inboxPreferenceWire(result.value)!);
+ assert.ok(preserved && typeof preserved === 'object' && 'tags' in preserved);
+ assert.deepEqual(preserved.tags, f.event.tags);
+ assert.deepEqual(inboxPreferenceSnapshot(result.value)?.relays, [origin]);
+});
+void test('more than three advertised relays remain intact; no routing or allowlist selection is inferred', () => {
+ const relays = ['one', 'two', 'three', 'four'].map(
+ (n) => `wss://${n}.example.org`
+ );
+ const f = fixture(relays.map((r) => ['relay', r]));
+ const result = readInboxPreference(f.wire, f.event.pubkey);
+ assert.equal(result.status, 'supported');
+ if (result.status !== 'supported') throw new Error('not admitted');
+ assert.deepEqual(inboxPreferenceSnapshot(result.value)?.relays, relays);
+ assert.equal(inboxPreferenceWire(result.value), f.wire);
+});
+for (const tags of [
+ [],
+ [['r', origin]],
+ [['relay']],
+ [['relay', 'ws://one.example.org']],
+ [['relay', origin, 'read']],
+ [['relay', 'wss://127.0.0.1']],
+ [['relay', origin + '/path']],
+ [
+ ['relay', origin],
+ ['relay', 'not a relay']
+ ]
+]) {
+ void test(
+ 'signed malformed/unsupported preference is a retained head, never absence: ' +
+ JSON.stringify(tags),
+ () => {
+ const f = fixture(tags, 10050, 200);
+ const result = readInboxPreference(f.wire, f.event.pubkey);
+ assert.equal(result.status, 'unsupported');
+ if (result.status !== 'unsupported') throw new Error('not unsupported');
+ const saved = inboxPreferenceSnapshot(result.value)!;
+ assert.equal(saved.id, f.event.id);
+ assert.equal(saved.createdAt, 200);
+ assert.equal(saved.author, f.event.pubkey);
+ assert.deepEqual(saved.relays, []);
+ assert.equal(inboxPreferenceWire(result.value), f.wire);
+ assert.equal(inboxProfileSnapshot(result.value)?.status, 'unsupported');
+ }
+ );
+}
+void test('invalid intended keys and mismatched authenticated author reject without preference authority', () => {
+ const f = fixture();
+ for (const owner of [
+ '',
+ 'f'.repeat(64),
+ f.event.pubkey.toUpperCase(),
+ 1,
+ null
+ ])
+ assert.equal(readInboxPreference(f.wire, owner).status, 'rejected');
+ const another = fixture();
+ assert.notEqual(another.event.pubkey, f.event.pubkey);
+ assert.equal(
+ readInboxPreference(f.wire, another.event.pubkey).status,
+ 'rejected'
+ );
+});
+void test('invalid id, signature, key and altered signed fields cannot supply a newer supported or unsupported head', () => {
+ const f = fixture();
+ for (const altered of [
+ { ...f.event, id: '0'.repeat(64) },
+ { ...f.event, sig: '0'.repeat(128) },
+ { ...f.event, pubkey: 'f'.repeat(64) },
+ { ...f.event, created_at: 201 },
+ { ...f.event, tags: [['relay']] }
+ ])
+ assert.equal(
+ readInboxPreference(JSON.stringify(altered), f.event.pubkey).status,
+ 'rejected'
+ );
+});
+void test('bounded raw envelope, generic tags and unknown field budgets reject before preference admission', () => {
+ const f = fixture();
+ assert.equal(
+ readInboxPreference(f.wire + ' '.repeat(262145), f.event.pubkey).status,
+ 'rejected'
+ );
+ const tooMany = fixture(Array.from({ length: 1025 }, () => ['unknown', 'x']));
+ assert.equal(
+ readInboxPreference(tooMany.wire, tooMany.event.pubkey).status,
+ 'rejected'
+ );
+ const extra: Record<string, unknown> = { ...f.event };
+ for (let i = 0; i < 65; i++) extra['extra' + i] = i;
+ assert.equal(
+ readInboxPreference(JSON.stringify(extra), f.event.pubkey).status,
+ 'rejected'
+ );
+ assert.equal(
+ readInboxPreference(
+ JSON.stringify({ ...f.event, extra: 'x'.repeat(65537) }),
+ f.event.pubkey
+ ).status,
+ 'rejected'
+ );
+ const oversizedTag = fixture([
+ ['relay', origin],
+ ['unknown', 'x'.repeat(4097)]
+ ]);
+ assert.equal(
+ readInboxPreference(oversizedTag.wire, oversizedTag.event.pubkey).status,
+ 'rejected'
+ );
+});
+void test('numeric spelling, object/getter/cache authority and invalid JSON cannot bypass fresh SDK verification', () => {
+ const f = fixture();
+ assert.equal(
+ readInboxPreference(
+ f.wire.replace('"kind":10050', '"kind":10050.0'),
+ f.event.pubkey
+ ).status,
+ 'rejected'
+ );
+ let reads = 0;
+ const hostile = {
+ get content() {
+ reads++;
+ throw new Error('must not run');
+ }
+ };
+ assert.equal(readInboxPreference(hostile, f.event.pubkey).status, 'rejected');
+ assert.equal(reads, 0);
+ assert.equal(readInboxPreference('{', f.event.pubkey).status, 'rejected');
+ assert.equal(readInboxPreference(f.event, f.event.pubkey).status, 'rejected');
+});
diff --git a/web/tests/unit/inbox-profile.test.ts b/web/tests/unit/inbox-profile.test.ts
@@ -0,0 +1,48 @@
+import { expect, it } from 'vitest';
+import { finalizeEvent } from 'applesauce-core/helpers';
+import {
+ readInboxPreference,
+ inboxPreferenceSnapshot,
+ inboxPreferenceWire,
+ type InboxPreference
+} from '../../src/lib/nostr/inbox-preferences.ts';
+import { inboxProfileSnapshot } from '../../src/lib/messaging/inbox-profile.ts';
+
+it('forged preference handles grant no profile, wire, provider or SSR authority', () => {
+ expect(typeof window).toBe('undefined');
+ const forged = {} as InboxPreference;
+ expect(inboxPreferenceSnapshot(forged)).toBeUndefined();
+ expect(inboxPreferenceWire(forged)).toBeUndefined();
+ expect(inboxProfileSnapshot(forged)).toBeUndefined();
+ expect(readInboxPreference({}, 'not-a-key').status).toBe('rejected');
+});
+it('detached profile mutation never changes proof-owned original or advertised entries', () => {
+ const key = crypto.getRandomValues(new Uint8Array(32));
+ try {
+ const event = finalizeEvent(
+ {
+ kind: 10050,
+ created_at: 100,
+ tags: [
+ ['relay', 'wss://one.example.org'],
+ ['unknown', 'keep']
+ ],
+ content: ''
+ },
+ key
+ );
+ const wire = JSON.stringify(event);
+ const parsed = readInboxPreference(wire, event.pubkey);
+ expect(parsed.status).toBe('supported');
+ if (parsed.status !== 'supported') throw new Error('fixture not admitted');
+ const view = inboxProfileSnapshot(parsed.value)!;
+ view.advertised.length = 0;
+ expect(inboxProfileSnapshot(parsed.value)?.advertised).toEqual([
+ 'wss://one.example.org'
+ ]);
+ expect(inboxPreferenceWire(parsed.value)).toBe(wire);
+ expect(Object.isFrozen(parsed.value)).toBe(true);
+ } finally {
+ key.fill(0);
+ }
+});