Source code for fleetmesh_core.wire.validate

"""Shape checks at the door, before any handler sees a message.

Every handler was written to read the fields its protocol names, and a
message that lacked one, or carried a string where an integer belongs, raised
inside the handler. The serve loop caught that and logged `handler failed`,
so the node lived - but a peer could make it log that on every message for
ever, and whatever the handler had done before it raised stayed done. A
message is checked here against the field lists `messages.json` declares and
the types the reference reads. One that fails is dropped with a reason and
counted, and no handler runs.

Nothing here decides anything about a peer. A malformed message is not an
offence, because an offence needs something the peer signed and meant; it is
noise, and the node's only duty is to survive it.
Standard library only.
"""
from __future__ import annotations

import re
from typing import Any, Callable, Iterable, Mapping, Optional

from . import schema_files

from ..peering import coverage

from ..identity import origin as origin_mod
from . import spelling

MESSAGES: Mapping[str, Any] = schema_files.load_messages()['protocols']
PROGRESS_STATES: frozenset[str] = frozenset(schema_files.load_constants()['market']['progress_states'])

MAX_ID: int = 256            # message and thread ids
MAX_NAME: int = 128          # shard names, metric names, actions
MAX_COUNTERS: int = 32       # distinct counters in one receipt
MAX_IDS: int = 20000         # event ids in one have/need
MAX_EVENTS: int = 5000       # events in one deliver
MAX_FRAME_HEX: int = 4 * 1024 * 1024
MAX_BLOB_HAVE: int = 1000
MAX_BLOB_CHUNK_B64: int = 4 * 256 * 1024 // 3 + 8   # blob_wire.MAX_CHUNK_BYTES, base64-grown
STATUSES: tuple[str, ...] = ('accepted', 'divergent', 'final')

_HEX = re.compile(r'^(?:[0-9a-f]{2})*$')
_B64 = re.compile(r'^[A-Za-z0-9+/]*={0,2}$')


[docs]def is_int(v: Any) -> bool: return spelling.is_int(v)
[docs]def is_num(v: Any) -> bool: return is_int(v) or (isinstance(v, float) and v == v)
[docs]def hex64(v: Any) -> bool: return spelling.is_hex(v, 64)
def _short(v: Any, n: int = MAX_NAME) -> bool: return isinstance(v, str) and 0 < len(v) <= n def _hexframe(v: Any) -> bool: return isinstance(v, str) and len(v) <= MAX_FRAME_HEX and bool(_HEX.fullmatch(v)) def _counters(c: Any) -> Optional[str]: if not isinstance(c, dict) or len(c) > MAX_COUNTERS: return 'counters is not a small object' for k, v in c.items(): if not _short(k) or not is_int(v) or v < 0: return 'counter %r is not a non-negative integer' % (k if isinstance(k, str) else '?')[:32] return None def _ids(ids: Any) -> Optional[str]: if not isinstance(ids, list) or len(ids) > MAX_IDS: return 'ids is not a bounded list' if not all(hex64(i) for i in ids): return 'ids holds something that is not an event id' return None # ---- one checker per message this node reads --------------------------------- def _receipt(b: Mapping[str, Any]) -> Optional[str]: if not hex64(b.get('grant')): return 'grant is not an event id' if not is_int(b.get('window')) or int(b['window']) < 0: return 'window is not an epoch' seq = b.get('seq') if not isinstance(seq, int) or isinstance(seq, bool) or seq < 0: return 'seq is not a non-negative integer' if not hex64(b.get('prev')): return 'prev is not a hash' why = _counters(b.get('counters')) if why: return why if not is_int(b.get('at')) or int(b['at']) < 0: return 'at is not a time' sig = b.get('sig') if sig is not None and not spelling.is_hex(sig, 128): return 'sig is not a signature' fwd = b.get('forwarded_for') if fwd is not None and not (isinstance(fwd, list) and all(_short(x, MAX_ID) for x in fwd)): return 'forwarded_for is not a list of DIDs' return None def _close(b: Mapping[str, Any]) -> Optional[str]: if not hex64(b.get('grant')): return 'grant is not an event id' if not is_int(b.get('window')) or int(b['window']) < 0: return 'window is not an epoch' if not hex64(b.get('final_receipt_head')): return 'final_receipt_head is not a hash' return _counters(b.get('counters')) def _receipt_ack(b: Mapping[str, Any]) -> Optional[str]: if not is_int(b.get('seq')): return 'seq is not an integer' if not hex64(b.get('head')): return 'head is not a hash' if b.get('status') not in STATUSES: return 'status is not accepted, divergent or final' return None def _open(b: Mapping[str, Any]) -> Optional[str]: if not _short(b.get('shard')): return 'shard is not a name' if not isinstance(b.get('filter'), dict): return 'filter is not an object' for k in ('since', 'until'): v = b.get(k) if v is not None and (not is_int(v) or int(v) < 0): return '%s is not a time' % k if not _hexframe(b.get('initial_frame')): return 'initial_frame is not a hex frame' return None def _range(b: Mapping[str, Any]) -> Optional[str]: if not _hexframe(b.get('frame')): return 'frame is not a hex frame' return None def _have(b: Mapping[str, Any]) -> Optional[str]: return _ids(b.get('ids')) or _range(b) def _need(b: Mapping[str, Any]) -> Optional[str]: return _ids(b.get('ids')) def _deliver(b: Mapping[str, Any]) -> Optional[str]: ev = b.get('events') if not isinstance(ev, list) or len(ev) > MAX_EVENTS or not all(isinstance(e, dict) for e in ev): return 'events is not a bounded list of events' cnt = b.get('count') if cnt is not None and not is_int(cnt): return 'count is not an integer' return None def _done(b: Mapping[str, Any]) -> Optional[str]: if not _short(b.get('status')): return 'status is not a name' return None def _link_shape(b: Mapping[str, Any]) -> Optional[str]: # Integers through spelling.is_int: `isinstance(x, int)` let a JSON true # through as a count or a timestamp (audit 2026-10-15, B9). if not spelling.is_hex(b.get('from'), 64) or not spelling.is_hex(b.get('to'), 64): return 'from and to are not pubkeys' shard = b.get('shard') if not isinstance(shard, str) or not 0 < len(shard) <= 128: return 'shard is not a name' if not spelling.is_hex(b.get('claim'), 64): return 'claim is not an event id' filt = b.get('filter') if not isinstance(filt, str) or len(filt) > 4 * 1024 * 1024: return 'filter is not text' since = b.get('since') if since is not None and not spelling.is_int(since): return 'since is not an integer' if not spelling.is_int(b.get('until')) or not spelling.is_int(b.get('at')): return 'until and at are not integers' if not spelling.is_hex(b.get('fingerprint'), 32): return 'fingerprint is not a NIP-77 fingerprint' cnt = b.get('count') if not spelling.is_int(cnt) or cnt < 0: return 'count is not a count' if not spelling.is_hex(b.get('sig'), 128): return 'sig is not a signature' return None
[docs]def check_handover_body(b: Mapping[str, Any]) -> Optional[str]: """Why a sync/1.0/handover body has the wrong shape, or None.""" chain = b.get('chain') if not isinstance(chain, list) or not 1 <= len(chain) <= coverage.HANDOVER_MAX_CHAIN: return 'chain is not one to %d links' % coverage.HANDOVER_MAX_CHAIN for link in chain: if not isinstance(link, dict): return 'a chain link is not an object' why = _link_shape(link) if why is not None: return why return None
def _handover(b: Mapping[str, Any]) -> Optional[str]: return check_handover_body(b) def _notice(b: Mapping[str, Any]) -> Optional[str]: w = b.get('window') if not is_int(w) or int(w) < 0: # type: ignore[arg-type] return 'window is not an epoch' if not _short(b.get('metric')): return 'metric is not a name' for k in ('observed', 'claimed', 'limit'): if b.get(k) is not None and not is_num(b[k]): return '%s is not a number' % k grant = b.get('grant') if grant is not None and not hex64(grant): return 'grant is not an event id' return None def _remedy(b: Mapping[str, Any]) -> Optional[str]: if not _short(b.get('action')): return 'action is not a name' return None def _withdraw(b: Mapping[str, Any]) -> Optional[str]: r = b.get('reason') if r is not None and not isinstance(r, str): return 'reason is not text' return None def _ask(b: Mapping[str, Any]) -> Optional[str]: if not _short(b.get('target'), MAX_ID): return 'target is not a DID' return None def _compute_quote(b: Mapping[str, Any]) -> Optional[str]: if not hex64(b.get('ask')): return 'ask is not an event id' p = b.get('price_msat') if not is_int(p) or int(p) < 0: # type: ignore[arg-type] return 'price_msat is not a non-negative integer' inv = b.get('invoice') if not isinstance(inv, str) or not inv: return 'invoice is not a string' if not hex64(b.get('payment_hash')): return 'payment_hash is not a hash' dur = b.get('estimated_duration_s') if dur is not None and (not is_int(dur) or int(dur) < 0): return 'estimated_duration_s is not a non-negative integer' return None def _compute_accept(b: Mapping[str, Any]) -> Optional[str]: if not hex64(b.get('payment_hash')): return 'payment_hash is not a hash' if b.get('held') is not True: return 'held must be true' if not isinstance(b.get('job'), dict): return 'job is not an object' inp = b.get('input_key') if inp is not None and not hex64(inp): return 'input_key is not a 32-byte hex string' return None def _compute_sealed(b: Mapping[str, Any]) -> Optional[str]: c = b.get('ciphertext') if not isinstance(c, str) or not c: return 'ciphertext is not a string' if not hex64(b.get('payment_hash')): return 'payment_hash is not a hash' if not hex64(b.get('result')): return 'result is not a hash' fuel = b.get('fuel_used') if not is_int(fuel) or int(fuel) < 0: # type: ignore[arg-type] return 'fuel_used is not a non-negative integer' v = b.get('verify') if v is not None and not isinstance(v, dict): return 'verify is not an object' return None def _compute_settled(b: Mapping[str, Any]) -> Optional[str]: if not hex64(b.get('payment_preimage')): return 'payment_preimage is not a 32-byte hex string' rec = b.get('receipt_event') if rec is not None and not hex64(rec): return 'receipt_event is not an event id' return None def _compute_refute(b: Mapping[str, Any]) -> Optional[str]: if not hex64(b.get('job_receipt')): return 'job_receipt is not an event id' if b.get('mode') not in ('sample', 'dual', 'proof'): return 'mode is not a valid verify mode' for k in ('claimed_result', 'actual_result', 'wasi_profile_digest'): val = b.get(k) if val is not None and not hex64(val): return '%s is not a hash' % k return None def _compute_stream(b: Mapping[str, Any]) -> Optional[str]: seq = b.get('seq') if not isinstance(seq, int) or isinstance(seq, bool) or seq < 0: return 'seq is not a non-negative integer' if not isinstance(b.get('delta'), str): return 'delta is not a string' if 'is_final' in b and b['is_final'] is not True: return 'is_final must be true when present' if 'counters' in b and not isinstance(b['counters'], dict): return 'counters is not an object' return None def _compute_progress(b: Mapping[str, Any]) -> Optional[str]: if b.get('state') not in PROGRESS_STATES: return 'state is not a progress state' prog = b.get('progress') if prog is not None and not (isinstance(prog, (int, float)) and not isinstance(prog, bool) and 0.0 <= float(prog) <= 1.0): return 'progress is not a number in [0, 1]' elapsed = b.get('elapsed_seconds') if elapsed is not None and (not isinstance(elapsed, int) or isinstance(elapsed, bool) or elapsed < 0): return 'elapsed_seconds is not a non-negative integer' log = b.get('logs_tail') if log is not None and not isinstance(log, str): return 'logs_tail is not a string' return None def _compute_cancel(b: Mapping[str, Any]) -> Optional[str]: r = b.get('reason') if not isinstance(r, str) or not r: return 'reason is not a string' penalty = b.get('penalty_msat') if penalty is not None and (not isinstance(penalty, int) or isinstance(penalty, bool) or penalty < 0): return 'penalty_msat is not a non-negative integer' return None def _blob_have(b: Mapping[str, Any]) -> Optional[str]: hs = b.get('sha256') if not isinstance(hs, list) or len(hs) > MAX_BLOB_HAVE: return 'sha256 is not a bounded list' if not all(hex64(h) for h in hs): return 'sha256 holds something that is not a hash' return None def _blob_offer(b: Mapping[str, Any]) -> Optional[str]: if not hex64(b.get('sha256')): return 'sha256 is not a hash' sz = b.get('size') if not is_int(sz) or int(sz) < 0: # type: ignore[arg-type] return 'size is not a non-negative integer' if not _short(b.get('type')): return 'type is not a short string' cb = b.get('chunk_bytes') if not is_int(cb) or int(cb) <= 0: # type: ignore[arg-type] return 'chunk_bytes is not a positive integer' return None def _blob_pull(b: Mapping[str, Any]) -> Optional[str]: if not hex64(b.get('sha256')): return 'sha256 is not a hash' off = b.get('offset') if not is_int(off) or int(off) < 0: # type: ignore[arg-type] return 'offset is not a non-negative integer' length = b.get('length') if not is_int(length) or int(length) <= 0: # type: ignore[arg-type] return 'length is not a positive integer' return None def _blob_chunk(b: Mapping[str, Any]) -> Optional[str]: if not hex64(b.get('sha256')): return 'sha256 is not a hash' off = b.get('offset') if not is_int(off) or int(off) < 0: # type: ignore[arg-type] return 'offset is not a non-negative integer' d = b.get('data') if not isinstance(d, str) or len(d) > MAX_BLOB_CHUNK_B64 or len(d) % 4 != 0 or not _B64.fullmatch(d): return 'data is not bounded base64' return None def _blob_refuse(b: Mapping[str, Any]) -> Optional[str]: if not hex64(b.get('sha256')): return 'sha256 is not a hash' if not _short(b.get('why'), 256): return 'why is not a short string' return None def _envelope_named(field: str) -> Callable[[Mapping[str, Any]], Optional[str]]: def f(b: Mapping[str, Any]) -> Optional[str]: if not hex64(b.get(field)): return '%s is not an event id' % field return None return f def _gossip_topic(b: Mapping[str, Any]) -> Optional[str]: if not _short(b.get('topic'), 256): return 'topic is not a short string' return None def _gossip_graft(b: Mapping[str, Any]) -> Optional[str]: err = _gossip_topic(b) if err: return err if not hex64(b.get('membership')): return 'membership is not an event id' return None def _gossip_prune(b: Mapping[str, Any]) -> Optional[str]: err = _gossip_topic(b) if err: return err if not _short(b.get('reason'), 128): return 'reason is not a short string' return None def _gossip_ids(b: Mapping[str, Any]) -> Optional[str]: err = _gossip_topic(b) if err: return err ids = b.get('ids') if not isinstance(ids, list) or not ids or not all(hex64(i) for i in ids): return 'ids is not a non-empty list of event ids' return None def _gossip_publish(b: Mapping[str, Any]) -> Optional[str]: err = _gossip_topic(b) if err: return err if not hex64(b.get('event_id')): return 'event_id is not an event id' if not isinstance(b.get('envelope'), dict): return 'envelope is not an object' return None MAX_CHAIN: int = 4 # constants capability.chain.max_depth; a quorum link counts once MAX_COPIES: int = 64 # member copies in one quorum link def _control_command(b: Mapping[str, Any]) -> Optional[str]: if not _short(b.get('command'), MAX_NAME): return 'command is not a short name' return None def _control_request(b: Mapping[str, Any]) -> Optional[str]: err = _control_command(b) if err: return err if not isinstance(b.get('args', {}), dict): return 'args is not an object' chain = b.get('chain', []) if not isinstance(chain, list) or len(chain) > MAX_CHAIN: return 'chain is not a list of at most %d links' % MAX_CHAIN for i, link in enumerate(chain): copies = link if isinstance(link, list) else [link] if i > 0 and isinstance(link, list): return 'only the first link may be a quorum (a list of member copies)' if not copies or len(copies) > MAX_COPIES or not all(isinstance(t, str) and t for t in copies): return 'a link is a token string, or for the first link a list of them' return None def _control_result(b: Mapping[str, Any]) -> Optional[str]: return _control_command(b) def _control_refused(b: Mapping[str, Any]) -> Optional[str]: err = _control_command(b) if err: return err if not _short(b.get('code'), MAX_NAME): return 'code is not a short name' if not isinstance(b.get('detail', ''), str) or len(b.get('detail', '')) > 512: return 'detail is not a short string' return None def _network_id(v: Any) -> bool: """A network id: <creator pubkey hex>:<slug>, at most 256 characters.""" return isinstance(v, str) and 0 < len(v) <= 256 def _join_request(b: Mapping[str, Any]) -> Optional[str]: if not _network_id(b.get('network')): return 'network is not a network id' # The descriptor's signature, expiry and authorship are the module's # bad_descriptor rule; the body check only holds its shape, and does not # require it so that a missing descriptor is that rule and not a shape one. if b.get('descriptor') is not None and not isinstance(b.get('descriptor'), dict): return 'descriptor is not an object' note = b.get('note') if note is not None and (not isinstance(note, str) or len(note) > 280): return 'note is a string of at most 280 characters' return None def _join_decline(b: Mapping[str, Any]) -> Optional[str]: if not _network_id(b.get('network')): return 'network is not a network id' if not _short(b.get('code'), MAX_NAME): return 'code is not a short name' return None CHECKS: dict[tuple[str, str], Callable[[Mapping[str, Any]], Optional[str]]] = { ('budget', 'receipt'): _receipt, ('budget', 'close'): _close, ('budget', 'receipt-ack'): _receipt_ack, ('sync', 'open'): _open, ('sync', 'range'): _range, ('sync', 'have'): _have, ('sync', 'need'): _need, ('sync', 'deliver'): _deliver, ('sync', 'done'): _done, ('sync', 'handover'): _handover, ('complaint', 'notice'): _notice, ('complaint', 'remedy'): _remedy, ('complaint', 'withdraw'): _withdraw, ('standing', 'ask'): _ask, ('control', 'request'): _control_request, ('control', 'result'): _control_result, ('control', 'refused'): _control_refused, ('network', 'join-request'): _join_request, ('network', 'join-decline'): _join_decline, ('peering', 'offer'): _envelope_named('grant_envelope'), ('peering', 'accept'): _envelope_named('grant_envelope'), ('peering', 'amend'): _envelope_named('new_grant_envelope'), ('compute', 'quote'): _compute_quote, ('compute', 'accept'): _compute_accept, ('compute', 'sealed'): _compute_sealed, ('compute', 'settled'): _compute_settled, ('compute', 'refute'): _compute_refute, ('compute', 'stream'): _compute_stream, ('compute', 'progress'): _compute_progress, ('compute', 'cancel'): _compute_cancel, ('blob', 'have'): _blob_have, ('blob', 'offer'): _blob_offer, ('blob', 'pull'): _blob_pull, ('blob', 'chunk'): _blob_chunk, ('blob', 'refuse'): _blob_refuse, ('gossip', 'graft'): _gossip_graft, ('gossip', 'prune'): _gossip_prune, ('gossip', 'ihave'): _gossip_ids, ('gossip', 'iwant'): _gossip_ids, ('gossip', 'publish'): _gossip_publish, }
[docs]def split_type(t: Any) -> tuple[Optional[str], Optional[str]]: """('budget', 'receipt') from a fleetmesh or registered PIURI message type, else (None, None).""" if not isinstance(t, str): return None, None piuri, _, kind = t.rpartition('/') if _kinds_of(piuri) is None: return None, None return piuri.rstrip('/').rsplit('/', 2)[-2], kind
EXTENSIONS: dict[str, set[str]] = {} """PIURI -> message kinds for protocols registered at runtime by out-of-tree compartments. Foreign origins only: fleetmesh.org protocols come from schema/messages.json and are governed by the digest, never by code.""" origin_of = origin_mod.origin_of def _schema_origin(piuris: Iterable[str]) -> str: origins = {origin_of(p) for p in piuris} if len(origins) != 1: raise ValueError('schema/messages.json PIURIs do not share one origin: %s' % sorted(origins)) return origins.pop() FLEETMESH_ORIGIN = _schema_origin(MESSAGES)
[docs]def register_protocol(piuri: str, kinds: Iterable[str], checks: Optional[Mapping[str, Callable[[Mapping[str, Any]], Optional[str]]]] = None) -> str: """Put a foreign protocol on the door so its bodies are checked like ours.""" if not isinstance(piuri, str) or origin_mod.reserved(piuri, FLEETMESH_ORIGIN): raise ValueError('register_protocol takes a foreign-origin PIURI; fleetmesh.org protocols live in schema/messages.json') try: origin_of(piuri) except ValueError: raise ValueError('PIURI is not https://<origin>/<name>/<major>.<minor>: %r' % (piuri,)) parts = piuri.rstrip('/').rsplit('/', 2) if len(parts) != 3 or not parts[0].startswith('https://') or '/' not in parts[0][8:] + '/': raise ValueError('PIURI is not https://<origin>/<name>/<major>.<minor>: %r' % (piuri,)) name, ver = parts[1], parts[2] major, _, minor = ver.partition('.') if not name or not major.isdigit() or not minor.isdigit(): raise ValueError('PIURI is not https://<origin>/<name>/<major>.<minor>: %r' % (piuri,)) taken = {p.rstrip('/').rsplit('/', 2)[-2] for p in MESSAGES} | {p.rstrip('/').rsplit('/', 2)[-2] for p in EXTENSIONS} if name in taken and piuri not in EXTENSIONS: raise ValueError('protocol short name %r is already spoken on this node' % (name,)) kinds_s = {str(k) for k in kinds} if not kinds_s: raise ValueError('a protocol needs at least one message kind') EXTENSIONS[piuri] = kinds_s for kind, fn in (checks or {}).items(): if kind not in kinds_s: raise ValueError('check for %s/%s names a kind the protocol does not carry' % (name, kind)) key = (name, kind) if key in CHECKS: raise ValueError('a body check for %s/%s already exists; a plugin may add checks, not replace them' % key) CHECKS[key] = fn return name
[docs]def register_check(protocol: str, kind: str, fn: Callable[[Mapping[str, Any]], Optional[str]]) -> None: """Add one body checker for a (protocol, kind) the node does not already check.""" key = (protocol, kind) if key in CHECKS: raise ValueError('a body check for %s/%s already exists; a plugin may add checks, not replace them' % key) CHECKS[key] = fn
[docs]def unregister_protocol(piuri: str) -> None: """Undo register_protocol (tests and plugin stop()).""" kinds = EXTENSIONS.pop(piuri, None) if kinds is None: return name = piuri.rstrip('/').rsplit('/', 2)[-2] for k in kinds: CHECKS.pop((name, k), None)
def _kinds_of(piuri: str) -> Optional[set[str]]: p = MESSAGES.get(piuri) if p is not None: return set(p['messages']) return EXTENSIONS.get(piuri)
[docs]def check_body(protocol: str, kind: str, body: Any) -> Optional[str]: """Why a body of this protocol message must not be handled, or None.""" if not isinstance(body, dict): return 'body is not an object' f = CHECKS.get((protocol, kind)) return f(body) if f else None
[docs]def check(message: Any) -> Optional[str]: """Why a DIDComm plaintext must not be handled, or None if it may be.""" if not isinstance(message, dict): return 'not an object' if not _short(message.get('id'), MAX_ID): return 'id is not a short string' if not isinstance(message.get('type'), str) or '/' not in message['type']: return 'type is not a PIURI' thid = message.get('thid') if thid is not None and not _short(thid, MAX_ID): return 'thid is not a short string' body = message.get('body', {}) if not isinstance(body, dict): return 'body is not an object' protocol, kind = split_type(message['type']) if protocol is None or kind is None: return None piuri = message['type'].rpartition('/')[0] if kind not in (_kinds_of(piuri) or set()): return 'unknown %s message %r' % (protocol, kind[:32]) return check_body(protocol, kind, body)
__all__ = [ 'MESSAGES', 'PROGRESS_STATES', 'MAX_ID', 'MAX_NAME', 'MAX_COUNTERS', 'MAX_IDS', 'MAX_EVENTS', 'MAX_FRAME_HEX', 'MAX_BLOB_HAVE', 'MAX_BLOB_CHUNK_B64', 'STATUSES', 'is_int', 'is_num', 'hex64', 'check_handover_body', 'CHECKS', 'split_type', 'EXTENSIONS', 'origin_of', 'FLEETMESH_ORIGIN', '_schema_origin', 'register_protocol', 'register_check', 'unregister_protocol', 'check_body', 'check', ]