Source code for fleetmesh_core.storage.replication

"""Delivery envelopes, range fingerprints and transport selection."""
from __future__ import annotations

import hashlib
from typing import Iterable, Mapping, Optional, Sequence

from ..crypto import crypto

from ..wire import schema_files
from ..wire.interfaces import (
    DeliveryEnvelope,
    DeliveryHop,
    EventLike,
    GrantPayload,
    HopSignatureConstants,
    SchemaConstantsDocument,
    TransportConstants,
)

CONSTANTS: SchemaConstantsDocument = schema_files.load_constants()
MAX_HOPS: int = CONSTANTS.get('delivery', {}).get('max_forward_hops', 5)
HOP: HopSignatureConstants = CONSTANTS.get('delivery', {}).get('hop_signature', {})
LADDER: TransportConstants = CONSTANTS.get('transport', {})


# ---------------------------------------------------- delivery envelope ----
def _hop_message(event_id: str, prev_hop: Optional[str], at: int) -> bytes:
    """The 32 bytes a hop signs, per constants.json delivery.hop_signature:
    SHA256(domain || '|' || event_id || '|' || prev_hop || '|' || at), prev_hop
    being the previous path entry's node string and empty for the first hop.
    The domain label keeps a hop signature from ever being mistaken for a nostr
    event id or anything else the same key signs.

    `at` is inside the signature because it was outside it once, and a field a
    signature does not cover is a field anyone may rewrite: the same hop could
    be lifted onto a different time, so a path proved that a node forwarded an
    event and never when. A hop is now a statement about a moment, which is
    what makes it evidence a reader can date.
    """
    return hashlib.sha256(('%s|%s|%s|%d' % (HOP['domain'], event_id, prev_hop or '', at)).encode()).digest()


[docs]def hop_message_hex(event_id: str, prev_hop: Optional[str], at: int) -> str: return _hop_message(event_id, prev_hop, at).hex()
[docs]def append_hop( envelope: DeliveryEnvelope, node_did: str, sk_hex: str, at: int, ) -> DeliveryEnvelope: """Sign over (event_id, prev_hop, at) and append. This is what makes a forwarder accountable for traffic it did not originate.""" path: list[DeliveryHop] = list(envelope.get('path', [])) prev: Optional[str] = path[-1]['node'] if path else None sig = crypto.schnorr_sign(_hop_message(envelope['event']['id'], prev, at), sk_hex) path.append({'node': node_did, 'at': at, 'sig': sig}) res: DeliveryEnvelope = {'event': envelope['event'], 'path': path} return res
[docs]def verify_envelope(envelope: DeliveryEnvelope) -> list[str]: """Check every hop signature and the hop limit. Returns failures.""" out: list[str] = [] prev: Optional[str] = None path: list[DeliveryHop] = envelope.get('path', []) if len(path) > MAX_HOPS: out.append('path is %d hops, limit is %d' % (len(path), MAX_HOPS)) for i, hop in enumerate(path): pk = hop['node'].split(':')[-1] try: msg = _hop_message(envelope['event']['id'], prev, int(hop['at'])) except (KeyError, TypeError, ValueError): out.append('hop %d has no usable timestamp' % i) prev = hop.get('node') continue if not crypto.schnorr_verify(msg, pk, hop['sig']): out.append('hop %d (%s) signature does not verify' % (i, hop['node'][:24])) prev = hop['node'] return out
[docs]def signed_by(envelope: DeliveryEnvelope, pubkey: str) -> bool: """True when this key appears in the path with a hop signature that verifies. What makes a delivery envelope citable evidence: the forwarder signed the hop even when somebody else authored the event, so it is the subject's own statement that it sent this, at this moment. """ if verify_envelope(envelope): return False return any(h.get('node', '').split(':')[-1] == pubkey for h in envelope.get('path', []))
[docs]def chargeable_hops( envelope: DeliveryEnvelope, my_grants: Sequence[str] | set[str] | Mapping[str, GrantPayload], ) -> list[str]: """Which nodes in the path this receiver holds a grant with. A forwarder outside the grant table is uncharged - and also unknown, so probation-limited. This is what closes grant-evasion routing. """ return [h['node'] for h in envelope.get('path', []) if h['node'] in my_grants]
# ------------------------------------------------------ range fingerprint ---- # NIP-77's algorithm, not a second one. The fingerprint is a SUM, which is what # makes range-based set reconciliation cheap: sub-range fingerprints compose by # addition and decompose by subtraction, so a range split is an index lookup # rather than a re-hash of everything in the new range. An order-dependent # chained hash would have the wrong algebraic shape for the protocol fleetmesh # already mandates.
[docs]def varint(n: int) -> bytes: """Base-128, most significant digit first, high bit set on all but the last.""" if n == 0: return b'\x00' out = bytearray() while n: out.insert(0, n & 0x7F) n >>= 7 for i in range(len(out) - 1): out[i] |= 0x80 return bytes(out)
[docs]def fingerprint(event_ids: Iterable[str]) -> str: """NIP-77 Negentropy V1 fingerprint: 16 bytes. acc = sum(id as 32-byte little-endian uint) mod 2**256 out = SHA256(acc_le_32 || varint(count))[:16] The count is what stops the additive structure colliding trivially - two different sets summing to the same accumulator still differ in cardinality almost always, and always for the sets a shard actually contains. """ acc = 0 n = 0 for eid in event_ids: acc = (acc + int.from_bytes(bytes.fromhex(eid), 'little')) % (1 << 256) n += 1 return hashlib.sha256(acc.to_bytes(32, 'little') + varint(n)).hexdigest()[:32]
[docs]def fingerprint_union(ids_a: Iterable[str], ids_b: Iterable[str]) -> str: """Demonstrates the property the sum buys: disjoint sub-ranges compose. Not a wire operation - it exists so the tests can assert that splitting a range and fingerprinting the halves is equivalent to fingerprinting the whole, which is the reason this construction was chosen over a chained hash. """ return fingerprint(list(ids_a) + list(ids_b))
[docs]def sort_for_enumeration(events: Iterable[EventLike]) -> list[str]: """(created_at ASC, id ASC). Required for enumerate_range, whose output order is observable. The fingerprint does not need it: a sum is order-independent, which is a property worth having rather than a rule worth stating. """ return [e['id'] for e in sorted(events, key=lambda e: (e['created_at'], e['id']))]
# ------------------------------------------------------ transport ladder ----
[docs]def negotiate(mine: dict[str, int], theirs: dict[str, int]) -> list[str]: """Rank the mutually supported transports, most preferred first. Each side advertises {scheme: preference}, low first. The ranking is by the sum of both preferences, so neither side dictates: a transport one peer hates cannot win just because the other loves it. Equal sums rank by scheme name, ascending bytewise - constants.json transport.ladder_tie_break - so two implementations pick the same rung for the same descriptor pair. """ assert 'bytewise' in LADDER['ladder_tie_break'] shared = set(mine) & set(theirs) return sorted(shared, key=lambda s: (mine[s] + theirs[s], s.encode()))
[docs]def ladder_exhausted( attempted: Iterable[str], mine: dict[str, int], theirs: dict[str, int], ) -> bool: """A peer may only be reported unreachable once every shared rung failed.""" return set(attempted) >= set(negotiate(mine, theirs))