commit 234c19d6ffe9c5a484d052b3fcdf3f74691e08df
parent 0c1d9f424b32953869eed96da19ce4cf1f809088
Author: triesap <tyson@radroots.org>
Date: Wed, 14 Oct 2026 05:22:14 +0000
harvestcircle_web: Bind source-owned inbox operator declarations
- Admit bounded canonical configuration with exact policy and origin bindings.
- Retain qualification version, evidence and capabilities as immutable metadata.
- Keep deployment unconfigured and fixture claims distinct from operator facts.
- Verify hostile configuration boundaries and 152 affected unit scenarios.
Diffstat:
3 files changed, 479 insertions(+), 0 deletions(-)
diff --git a/web/src/lib/config/deployment-inbox-operators.ts b/web/src/lib/config/deployment-inbox-operators.ts
@@ -0,0 +1,19 @@
+import { deploymentRelayPolicy } from './deployment-relays.ts';
+import { readRelayPolicy } from './relays.ts';
+import { validateInboxOperatorQualification } from './inbox-operators.ts';
+
+// No operator capability evidence has been supplied for production. Keep this
+// source-owned input unconfigured; controlled relay fixtures do not qualify it.
+const qualification = validateInboxOperatorQualification(
+ JSON.stringify({
+ schemaVersion: 1,
+ revision: 1,
+ authority: 'unconfigured',
+ policyWire: JSON.stringify(readRelayPolicy(deploymentRelayPolicy)),
+ evidenceSha256: null,
+ relays: []
+ })
+);
+if (!qualification) throw new Error('inbox_operator_configuration_invalid');
+
+export const deploymentInboxOperatorQualification = qualification;
diff --git a/web/src/lib/config/inbox-operators.ts b/web/src/lib/config/inbox-operators.ts
@@ -0,0 +1,151 @@
+import { exactLocalFields } from '../contracts/local-records.ts';
+import { safeUnsignedInteger } from '../nostr/envelope-bounds.ts';
+import {
+ canonicalRelayOrigin,
+ readRelayPolicy,
+ validateRelayPolicy,
+ type RelayPolicy
+} from './relays.ts';
+import { RELAY_BUDGETS } from './budgets.ts';
+
+export type InboxOperatorDeclaration = Readonly<{
+ origin: string;
+ auth: 'not_required' | 'explicit_required' | 'unsupported';
+ recipientRead: 'supported' | 'unsupported';
+ namedArchiveAck: 'supported' | 'unsupported';
+ exactReadback: 'supported' | 'unsupported';
+ retention: 'operator_defined' | 'unsupported';
+}>;
+export type InboxOperatorManifest = Readonly<{
+ schemaVersion: 1;
+ revision: number;
+ authority: 'unconfigured' | 'source_fixture' | 'operator';
+ policyWire: string;
+ evidenceSha256: string | null;
+ relays: readonly InboxOperatorDeclaration[];
+}>;
+declare const operatorBrand: unique symbol;
+export type InboxOperatorQualification = Readonly<{
+ [operatorBrand]: true;
+}>;
+const declarations = new WeakMap<InboxOperatorQualification, string>();
+const supported = (value: unknown) =>
+ value === 'supported' || value === 'unsupported';
+
+// Source-owned declarations only. Admission authenticates no operator action,
+// grants no socket/signer/publication permission and never supplies readiness.
+// Production consumes the checked-in deployment owner; fixtures retain their
+// separate authority label. Actual access facts and Q evidence remain required.
+export function validateInboxOperatorQualification(
+ raw: unknown
+): InboxOperatorQualification | undefined {
+ if (
+ typeof raw !== 'string' ||
+ raw.length > 65536 ||
+ !raw.isWellFormed() ||
+ new TextEncoder().encode(raw).length > 65536
+ )
+ return undefined;
+ try {
+ const row: unknown = JSON.parse(raw);
+ // Config has one exact canonical representation. Unlike stored protocol
+ // wires, it needs no whitespace compatibility. Duplicate fields, escaped
+ // aliases and ambiguous number spellings cannot survive this comparison.
+ if (
+ JSON.stringify(row) !== raw ||
+ !exactLocalFields(row, [
+ 'schemaVersion',
+ 'revision',
+ 'authority',
+ 'policyWire',
+ 'evidenceSha256',
+ 'relays'
+ ]) ||
+ row.schemaVersion !== 1 ||
+ safeUnsignedInteger(row.revision) === undefined ||
+ (row.revision as number) < 1 ||
+ !['unconfigured', 'source_fixture', 'operator'].includes(
+ row.authority as string
+ ) ||
+ typeof row.policyWire !== 'string' ||
+ !Array.isArray(row.relays) ||
+ row.relays.length > RELAY_BUDGETS.inbox
+ )
+ return undefined;
+ const policy = validateRelayPolicy(row.policyWire);
+ if (!policy) return undefined;
+ const manifest = readRelayPolicy(policy);
+ if (JSON.stringify(manifest) !== row.policyWire) return undefined;
+ if (
+ row.authority === 'unconfigured'
+ ? row.relays.length !== 0 || row.evidenceSha256 !== null
+ : row.relays.length === 0 ||
+ typeof row.evidenceSha256 !== 'string' ||
+ !/^[0-9a-f]{64}$/.test(row.evidenceSha256)
+ )
+ return undefined;
+ for (const entry of row.relays as unknown[]) {
+ if (
+ !exactLocalFields(entry, [
+ 'origin',
+ 'auth',
+ 'recipientRead',
+ 'namedArchiveAck',
+ 'exactReadback',
+ 'retention'
+ ]) ||
+ typeof entry.origin !== 'string' ||
+ canonicalRelayOrigin(entry.origin) !== entry.origin ||
+ !manifest.inbox.some(({ origin }) => origin === entry.origin) ||
+ !['not_required', 'explicit_required', 'unsupported'].includes(
+ entry.auth as string
+ ) ||
+ !supported(entry.recipientRead) ||
+ !supported(entry.namedArchiveAck) ||
+ !supported(entry.exactReadback) ||
+ (entry.retention !== 'operator_defined' &&
+ entry.retention !== 'unsupported')
+ )
+ return undefined;
+ }
+ if (
+ new Set(
+ (row.relays as InboxOperatorDeclaration[]).map(({ origin }) => origin)
+ ).size !== row.relays.length
+ )
+ return undefined;
+ const token = Object.freeze({}) as InboxOperatorQualification;
+ declarations.set(token, raw);
+ return token;
+ } catch {
+ return undefined;
+ }
+}
+
+// A detached view is public routing/qualification metadata, never a capability.
+export function inboxOperatorQualificationSnapshot(
+ token: InboxOperatorQualification
+): InboxOperatorManifest | undefined {
+ const raw = declarations.get(token);
+ return raw === undefined
+ ? undefined
+ : (JSON.parse(raw) as InboxOperatorManifest);
+}
+
+// The complete original config, including evidence, version and every origin,
+// is the frozen binding. A policy's detached view cannot change that binding.
+export function inboxOperatorQualificationWire(
+ token: InboxOperatorQualification,
+ policy: RelayPolicy
+): string | undefined {
+ try {
+ const raw = declarations.get(token);
+ return raw !== undefined &&
+ (JSON.parse(raw) as InboxOperatorManifest).policyWire ===
+ JSON.stringify(readRelayPolicy(policy))
+ ? raw
+ : undefined;
+ } catch {
+ return undefined;
+ }
+}
diff --git a/web/tests/unit/inbox-operators.test.ts b/web/tests/unit/inbox-operators.test.ts
@@ -0,0 +1,309 @@
+import { describe, expect, it } from 'vitest';
+import {
+ inboxOperatorQualificationSnapshot,
+ inboxOperatorQualificationWire,
+ validateInboxOperatorQualification,
+ type InboxOperatorQualification
+} from '../../src/lib/config/inbox-operators.ts';
+import { deploymentInboxOperatorQualification } from '../../src/lib/config/deployment-inbox-operators.ts';
+import { deploymentRelayPolicy } from '../../src/lib/config/deployment-relays.ts';
+import {
+ readRelayPolicy,
+ validateRelayPolicy,
+ type RelayPolicy
+} from '../../src/lib/config/relays.ts';
+
+function policyInput() {
+ return {
+ schemaVersion: 1,
+ public: [
+ {
+ origin: 'wss://public.example.org',
+ read: true,
+ write: false,
+ nip50: false
+ }
+ ],
+ inbox: [{ origin: 'wss://inbox.example.org', read: true, write: true }],
+ postingEnabled: false,
+ messagingEnabled: true,
+ operatorDenylist: []
+ };
+}
+function input() {
+ return {
+ schemaVersion: 1,
+ revision: 1,
+ authority: 'source_fixture',
+ policyWire: JSON.stringify(policyInput()),
+ evidenceSha256: 'a'.repeat(64),
+ relays: [
+ {
+ origin: 'wss://inbox.example.org',
+ auth: 'not_required',
+ recipientRead: 'supported',
+ namedArchiveAck: 'supported',
+ exactReadback: 'supported',
+ retention: 'operator_defined'
+ }
+ ]
+ };
+}
+const admit = (value: unknown) =>
+ validateInboxOperatorQualification(JSON.stringify(value));
+const genuinePolicy = () => validateRelayPolicy(JSON.stringify(policyInput()))!;
+
+describe('CR008 S1 source-owned operator declaration boundaries', () => {
+ it('keeps deployment unconfigured and bound to the original disabled policy', () => {
+ expect(
+ inboxOperatorQualificationSnapshot(deploymentInboxOperatorQualification)
+ ).toEqual({
+ schemaVersion: 1,
+ revision: 1,
+ authority: 'unconfigured',
+ policyWire: JSON.stringify(readRelayPolicy(deploymentRelayPolicy)),
+ evidenceSha256: null,
+ relays: []
+ });
+ expect(
+ inboxOperatorQualificationWire(
+ deploymentInboxOperatorQualification,
+ deploymentRelayPolicy
+ )
+ ).toBeDefined();
+ expect(
+ inboxOperatorQualificationWire(
+ deploymentInboxOperatorQualification,
+ genuinePolicy()
+ )
+ ).toBeUndefined();
+ });
+ it('retains the exact full declaration and separate fixture/operator authority, without readiness', () => {
+ for (const authority of ['source_fixture', 'operator']) {
+ const value = { ...input(), authority },
+ token = admit(value)!;
+ expect(inboxOperatorQualificationSnapshot(token)).toEqual(value);
+ expect(inboxOperatorQualificationWire(token, genuinePolicy())).toBe(
+ JSON.stringify(value)
+ );
+ expect(Object.isFrozen(token)).toBe(true);
+ expect(Object.keys(token)).toEqual([]);
+ expect(inboxOperatorQualificationSnapshot(token)).not.toHaveProperty(
+ 'readiness'
+ );
+ }
+ expect(admit({ ...input(), readiness: true })).toBeUndefined();
+ });
+ it('retains unsupported declarations and explicit AUTH requirements as metadata', () => {
+ for (const auth of ['not_required', 'explicit_required', 'unsupported']) {
+ const value = input();
+ value.relays[0] = {
+ ...value.relays[0],
+ auth,
+ recipientRead: 'unsupported',
+ namedArchiveAck: 'unsupported',
+ exactReadback: 'unsupported',
+ retention: 'unsupported'
+ };
+ expect(inboxOperatorQualificationSnapshot(admit(value)!)).toEqual(value);
+ }
+ });
+ it('cannot mutate retained origins, capabilities, evidence or authority using detached views', () => {
+ const value = input(),
+ token = admit(value)!,
+ original = JSON.stringify(value);
+ value.relays[0].origin = 'wss://outside.example.org';
+ value.evidenceSha256 = 'b'.repeat(64);
+ const view = inboxOperatorQualificationSnapshot(
+ token
+ )! as unknown as ReturnType<typeof input>;
+ view.authority = 'operator';
+ view.relays[0].auth = 'unsupported';
+ view.relays.push({
+ ...view.relays[0],
+ origin: 'wss://outside.example.org'
+ });
+ view.policyWire = '{}';
+ expect(inboxOperatorQualificationWire(token, genuinePolicy())).toBe(
+ original
+ );
+ expect(inboxOperatorQualificationSnapshot(token)?.authority).toBe(
+ 'source_fixture'
+ );
+ expect(inboxOperatorQualificationSnapshot(token)?.relays).toHaveLength(1);
+ const forged = { ...token } as InboxOperatorQualification;
+ expect(inboxOperatorQualificationSnapshot(forged)).toBeUndefined();
+ expect(
+ inboxOperatorQualificationWire(forged, genuinePolicy())
+ ).toBeUndefined();
+ expect(
+ inboxOperatorQualificationWire(token, {} as RelayPolicy)
+ ).toBeUndefined();
+ });
+ it('invalidates binding for every changed policy dimension, even when the selected origin survives', () => {
+ const token = admit(input())!;
+ for (const patch of [
+ { messagingEnabled: false },
+ { postingEnabled: true },
+ { inbox: [{ ...policyInput().inbox[0], write: false }] },
+ { public: [{ ...policyInput().public[0], write: true }] },
+ {
+ operatorDenylist: [
+ '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'
+ ]
+ }
+ ]) {
+ const changed = validateRelayPolicy(
+ JSON.stringify({ ...policyInput(), ...patch })
+ )!;
+ expect(changed).toBeDefined();
+ expect(inboxOperatorQualificationWire(token, changed)).toBeUndefined();
+ }
+ });
+ it('retains at most three unique approved canonical inbox origins and never public-only hints', () => {
+ const value = input(),
+ origins = [1, 2, 3].map((n) => `wss://inbox${n}.example.org`);
+ value.policyWire = JSON.stringify({
+ ...policyInput(),
+ inbox: origins.map((origin) => ({ origin, read: true, write: true }))
+ });
+ value.relays = origins.map((origin) => ({ ...value.relays[0], origin }));
+ expect(admit(value)).toBeDefined();
+ expect(
+ admit({ ...value, relays: [...value.relays, value.relays[0]] })
+ ).toBeUndefined();
+ expect(
+ admit({ ...value, relays: [value.relays[0], value.relays[0]] })
+ ).toBeUndefined();
+ for (const origin of [
+ 'wss://public.example.org',
+ 'wss://outside.example.org',
+ 'wss://inbox.example.org/',
+ 'wss://inbox.example.org:443',
+ 'ws://inbox.example.org',
+ 'wss://127.0.0.1',
+ 'wss://user@inbox.example.org'
+ ])
+ expect(
+ admit({ ...input(), relays: [{ ...input().relays[0], origin }] })
+ ).toBeUndefined();
+ });
+ it('rejects missing/unknown root and relay fields, false booleans and malformed evidence without coercion', () => {
+ const value = input();
+ for (const patch of [
+ { schemaVersion: 2 },
+ { revision: 0 },
+ { revision: -1 },
+ { revision: 1.1 },
+ { revision: Number.MAX_SAFE_INTEGER + 1 },
+ { authority: 'approved' },
+ { authority: true },
+ { evidenceSha256: null },
+ { evidenceSha256: 'A'.repeat(64) },
+ { evidenceSha256: 'a'.repeat(63) },
+ { evidenceSha256: true },
+ { relays: [] },
+ { relays: {} },
+ { policyWire: {} },
+ { policyWire: '{}' },
+ { privateKey: 'SECRET_SENTINEL' }
+ ])
+ expect(admit({ ...value, ...patch })).toBeUndefined();
+ for (const patch of [
+ { auth: true },
+ { recipientRead: true },
+ { namedArchiveAck: false },
+ { exactReadback: 'ready' },
+ { retention: 'unlimited' },
+ { credential: 'SECRET_SENTINEL' }
+ ])
+ expect(
+ admit({ ...value, relays: [{ ...value.relays[0], ...patch }] })
+ ).toBeUndefined();
+ for (const key of Object.keys(value)) {
+ const broken: Record<string, unknown> = { ...value };
+ delete broken[key];
+ expect(admit(broken)).toBeUndefined();
+ }
+ for (const key of Object.keys(value.relays[0])) {
+ const broken: Record<string, unknown> = { ...value.relays[0] };
+ delete broken[key];
+ expect(admit({ ...value, relays: [broken] })).toBeUndefined();
+ }
+ expect(
+ admit({
+ ...value,
+ authority: 'unconfigured',
+ relays: [],
+ evidenceSha256: null
+ })
+ ).toBeDefined();
+ expect(
+ admit({ ...value, authority: 'unconfigured', evidenceSha256: null })
+ ).toBeUndefined();
+ expect(
+ admit({ ...value, authority: 'unconfigured', relays: [] })
+ ).toBeUndefined();
+ });
+ it('rejects duplicate/escaped keys, whitespace and altered canonical numeric spelling in either JSON layer', () => {
+ const raw = JSON.stringify(input());
+ for (const malformed of [
+ raw.replace('"revision":1', '"revision":2,"revision":1'),
+ raw.replace('"authority":', '"\\u0061uthority":'),
+ raw.replace(
+ '"auth":"not_required"',
+ '"auth":"unsupported","auth":"not_required"'
+ ),
+ raw.replace('"revision":1', '"revision":1e0'),
+ raw + '\n',
+ JSON.stringify(input(), null, 2)
+ ])
+ expect(validateInboxOperatorQualification(malformed)).toBeUndefined();
+ for (const policyWire of [
+ JSON.stringify(policyInput()).replace(
+ '"messagingEnabled":true',
+ '"messagingEnabled":false,"messagingEnabled":true'
+ ),
+ JSON.stringify(policyInput()).replace(
+ '"schemaVersion"',
+ '"\\u0073chemaVersion"'
+ ),
+ JSON.stringify(policyInput(), null, 2)
+ ])
+ expect(admit({ ...input(), policyWire })).toBeUndefined();
+ });
+ it('bounds raw UTF8 before parsing and does not execute caller getters or coercions', () => {
+ for (const raw of [
+ '{',
+ 'null',
+ '[]',
+ 'false',
+ ' '.repeat(65537),
+ JSON.stringify({ extra: 'é'.repeat(33000) }),
+ '"\ud800"'
+ ])
+ expect(validateInboxOperatorQualification(raw)).toBeUndefined();
+ let reads = 0;
+ const hostile = {
+ get relays() {
+ reads++;
+ throw Error('getter executed');
+ },
+ toString() {
+ reads++;
+ return JSON.stringify(input());
+ }
+ };
+ expect(validateInboxOperatorQualification(hostile)).toBeUndefined();
+ expect(
+ validateInboxOperatorQualification(Object.create(input()))
+ ).toBeUndefined();
+ expect(
+ validateInboxOperatorQualification({
+ ...input(),
+ [Symbol('secret')]: true
+ })
+ ).toBeUndefined();
+ expect(reads).toBe(0);
+ });
+});