app

Local-first trade for farms and co-ops
git clone https://radroots.dev/git/app.git
Log | Files | Refs | README | LICENSE

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:
Aweb/src/lib/config/deployment-inbox-operators.ts | 19+++++++++++++++++++
Aweb/src/lib/config/inbox-operators.ts | 151++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aweb/tests/unit/inbox-operators.test.ts | 309+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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); + }); +});