inbox-operators.ts (5184B)
1 import { exactLocalFields } from '../contracts/local-records.ts'; 2 import { safeUnsignedInteger } from '../nostr/envelope-bounds.ts'; 3 import { 4 canonicalRelayOrigin, 5 readRelayPolicy, 6 validateRelayPolicy, 7 type RelayPolicy 8 } from './relays.ts'; 9 import { RELAY_BUDGETS } from './budgets.ts'; 10 11 export type InboxOperatorDeclaration = Readonly<{ 12 origin: string; 13 auth: 'not_required' | 'explicit_required' | 'unsupported'; 14 recipientRead: 'supported' | 'unsupported'; 15 namedArchiveAck: 'supported' | 'unsupported'; 16 exactReadback: 'supported' | 'unsupported'; 17 retention: 'operator_defined' | 'unsupported'; 18 }>; 19 export type InboxOperatorManifest = Readonly<{ 20 schemaVersion: 1; 21 revision: number; 22 authority: 'unconfigured' | 'source_fixture' | 'operator'; 23 policyWire: string; 24 evidenceSha256: string | null; 25 relays: readonly InboxOperatorDeclaration[]; 26 }>; 27 declare const operatorBrand: unique symbol; 28 export type InboxOperatorQualification = Readonly<{ 29 [operatorBrand]: true; 30 }>; 31 const declarations = new WeakMap<InboxOperatorQualification, string>(); 32 const supported = (value: unknown) => 33 value === 'supported' || value === 'unsupported'; 34 35 // Source-owned declarations only. Admission authenticates no operator action, 36 // grants no socket/signer/publication permission and never supplies readiness. 37 // Production consumes the checked-in deployment owner; fixtures retain their 38 // separate authority label. Actual access facts and Q evidence remain required. 39 export function validateInboxOperatorQualification( 40 raw: unknown 41 ): InboxOperatorQualification | undefined { 42 if ( 43 typeof raw !== 'string' || 44 raw.length > 65536 || 45 !raw.isWellFormed() || 46 new TextEncoder().encode(raw).length > 65536 47 ) 48 return undefined; 49 try { 50 const row: unknown = JSON.parse(raw); 51 // Config has one exact canonical representation. Unlike stored protocol 52 // wires, it needs no whitespace compatibility. Duplicate fields, escaped 53 // aliases and ambiguous number spellings cannot survive this comparison. 54 if ( 55 JSON.stringify(row) !== raw || 56 !exactLocalFields(row, [ 57 'schemaVersion', 58 'revision', 59 'authority', 60 'policyWire', 61 'evidenceSha256', 62 'relays' 63 ]) || 64 row.schemaVersion !== 1 || 65 safeUnsignedInteger(row.revision) === undefined || 66 (row.revision as number) < 1 || 67 !['unconfigured', 'source_fixture', 'operator'].includes( 68 row.authority as string 69 ) || 70 typeof row.policyWire !== 'string' || 71 !Array.isArray(row.relays) || 72 row.relays.length > RELAY_BUDGETS.inbox 73 ) 74 return undefined; 75 const policy = validateRelayPolicy(row.policyWire); 76 if (!policy) return undefined; 77 const manifest = readRelayPolicy(policy); 78 if (JSON.stringify(manifest) !== row.policyWire) return undefined; 79 if ( 80 row.authority === 'unconfigured' 81 ? row.relays.length !== 0 || row.evidenceSha256 !== null 82 : row.relays.length === 0 || 83 typeof row.evidenceSha256 !== 'string' || 84 !/^[0-9a-f]{64}$/.test(row.evidenceSha256) 85 ) 86 return undefined; 87 for (const entry of row.relays as unknown[]) { 88 if ( 89 !exactLocalFields(entry, [ 90 'origin', 91 'auth', 92 'recipientRead', 93 'namedArchiveAck', 94 'exactReadback', 95 'retention' 96 ]) || 97 typeof entry.origin !== 'string' || 98 canonicalRelayOrigin(entry.origin) !== entry.origin || 99 !manifest.inbox.some(({ origin }) => origin === entry.origin) || 100 !['not_required', 'explicit_required', 'unsupported'].includes( 101 entry.auth as string 102 ) || 103 !supported(entry.recipientRead) || 104 !supported(entry.namedArchiveAck) || 105 !supported(entry.exactReadback) || 106 (entry.retention !== 'operator_defined' && 107 entry.retention !== 'unsupported') 108 ) 109 return undefined; 110 } 111 if ( 112 new Set( 113 (row.relays as InboxOperatorDeclaration[]).map(({ origin }) => origin) 114 ).size !== row.relays.length 115 ) 116 return undefined; 117 const token = Object.freeze({}) as InboxOperatorQualification; 118 declarations.set(token, raw); 119 return token; 120 } catch { 121 return undefined; 122 } 123 } 124 125 // A detached view is public routing/qualification metadata, never a capability. 126 export function inboxOperatorQualificationSnapshot( 127 token: InboxOperatorQualification 128 ): InboxOperatorManifest | undefined { 129 const raw = declarations.get(token); 130 return raw === undefined 131 ? undefined 132 : (JSON.parse(raw) as InboxOperatorManifest); 133 } 134 135 // The complete original config, including evidence, version and every origin, 136 // is the frozen binding. A policy's detached view cannot change that binding. 137 export function inboxOperatorQualificationWire( 138 token: InboxOperatorQualification, 139 policy: RelayPolicy 140 ): string | undefined { 141 try { 142 const raw = declarations.get(token); 143 return raw !== undefined && 144 (JSON.parse(raw) as InboxOperatorManifest).policyWire === 145 JSON.stringify(readRelayPolicy(policy)) 146 ? raw 147 : undefined; 148 } catch { 149 return undefined; 150 } 151 }