"""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))