app

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

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 }