"""Node identity: blinded identifiers, and what makes a descriptor valid.
Every label comes from schema/constants.json and every tag rule from
schema/kinds.json, so this module cannot disagree with the protocol version
digest. If it does, check-package.py or check-registry.py has already failed.
"""
from __future__ import annotations
import os
from typing import Optional
from ..crypto import crypto
from ..wire import schema_files
from ..storage import store
from ..wire import spelling
from ..wire.interfaces import (
EventLike,
KindSpec,
SchemaConstantsDocument,
SchemaMessagesDocument,
)
CONSTANTS: SchemaConstantsDocument = schema_files.load_constants()
KINDS: dict[str, KindSpec] = schema_files.load_kinds()['kinds']
MESSAGES: SchemaMessagesDocument = schema_files.load_messages()
PROTOCOLS: frozenset[str] = frozenset(MESSAGES['protocols'])
# The prefix a c value must carry to be read as a protocol identifier. Derived
# from the declared identifiers rather than written down, so this file names
# no address of its own and the unplug scan stays honest.
FLEETMESH: str = os.path.commonprefix(sorted(PROTOCOLS))
assert FLEETMESH.endswith('/') and all(p.startswith(FLEETMESH) for p in PROTOCOLS)
REQUIRED_PROTOCOLS: tuple[str, ...] = tuple(CONSTANTS['descriptor']['required_protocols'])
PROTOCOL_FLOORS: dict[str, str] = dict(CONSTANTS['descriptor'].get('protocol_floors', {}))
[docs]def protocol_version(identifier: str) -> Optional[tuple[str, int, int]]:
"""FLEETMESH + 'sync/1.2' -> ('sync', 1, 2); None if it is not shaped so."""
if not identifier.startswith(FLEETMESH):
return None
rest = identifier[len(FLEETMESH):]
name, _, ver = rest.rpartition('/')
major, _, minor = ver.partition('.')
# ASCII digits only: str.isdigit() also accepts superscripts and other
# scripts' digits, which int() then rejects or another implementation
# reads differently. One spelling, so every reader agrees on the version.
maj, mnr = store.ascii_int(major), store.ascii_int(minor)
if not name or '/' in name or maj is None or mnr is None:
return None
return name, maj, mnr
[docs]def floor_of(name: str, major: int) -> int:
"""The lowest minor of <name>/<major> this node still talks to."""
f = PROTOCOL_FLOORS.get(name)
if not f:
return 0
fmaj, _, fmin = f.partition('.')
a, b = store.ascii_int(fmaj), store.ascii_int(fmin)
return b if a == major and b is not None else 0
[docs]def shared_protocols(theirs: set[str], ours: set[str]) -> set[str]:
"""The protocols two nodes can run with each other, one identifier each.
Exact guarantee: for every (name, major) that both sides declare, where
the peer's minor is at or above our floor for that name/major, the
result holds FLEETMESH + name/major.min(our minor, peer minor) - the
highest version both are known to read, since minors are additive. If
either side declares the same name/major more than once the lowest of
each side's minors is what is compared. Different majors never match,
and nothing in the result is an identifier neither side declared.
Callers that want "is name/major shared" rather than the exact
identifier compare on protocol_version()[:2]; see compatible()."""
mine: dict[tuple[str, int], int] = {}
for p in ours:
v = protocol_version(p)
if v is not None:
mine[(v[0], v[1])] = min(v[2], mine.get((v[0], v[1]), v[2]))
peer: dict[tuple[str, int], int] = {}
for p in theirs:
v = protocol_version(p)
if v is not None:
peer[(v[0], v[1])] = min(v[2], peer.get((v[0], v[1]), v[2]))
out: set[str] = set()
for (name, major), minor in peer.items():
our_minor = mine.get((name, major))
if our_minor is not None and minor >= floor_of(name, major):
out.add('%s%s/%d.%d' % (FLEETMESH, name, major, min(our_minor, minor)))
return out
[docs]def shared_families(theirs: set[str], ours: set[str]) -> set[tuple[str, int]]:
"""The (name, major) pairs shared_protocols() would return an identifier for."""
return {(v[0], v[1]) for p in shared_protocols(theirs, ours) if (v := protocol_version(p))}
[docs]def compatible(theirs: set[str], ours: Optional[set[str]] = None) -> list[str]:
"""Why a peer's protocol declaration cannot peer with ours; empty means it can.
Only the required protocols decide this. Everything else is shared or
not, which is a subsystem's business, not the peering's."""
ours_s = ours if ours is not None else set(PROTOCOLS)
shared = shared_families(theirs, ours_s)
out: list[str] = []
for req in REQUIRED_PROTOCOLS:
v = protocol_version(req)
if v is None or (v[0], v[1]) in shared:
continue
name, major, _ = v
same_name = [t for t in theirs if (pv := protocol_version(t)) and pv[0] == name]
if not same_name:
out.append('every node implements %s and this one does not declare it' % req[len(FLEETMESH):])
else:
out.append('%s is not compatible with %s/%d.x at or above the floor %d.%d'
% (', '.join(sorted(s[len(FLEETMESH):] for s in same_name)), name, major,
major, floor_of(name, major)))
return out
[docs]def notices(event: EventLike, digest: Optional[str] = None) -> list[str]:
"""What is worth telling an operator about a peer's descriptor without
refusing it: a different schema digest (provenance, since 0.3), and
protocols this build does not define (a newer peer, most likely)."""
out: list[str] = []
proto = first(event, 'protocol')
if proto and len(proto) >= 3 and digest and proto[2] != digest:
out.append('schema digest %s, this node was built from %s' % (proto[2][:16], digest[:16]))
unknown = sorted(protocols_of(event) - PROTOCOLS)
if unknown:
out.append('declares %s, which this version does not define' % ', '.join(p[len(FLEETMESH):] for p in unknown))
return out
CLASS_MAX_LIFETIME: dict[str, int] = {
'anchor': CONSTANTS['descriptor']['max_lifetime_seconds_anchor_edge'],
'edge': CONSTANTS['descriptor']['max_lifetime_seconds_anchor_edge'],
'leaf': CONSTANTS['descriptor']['max_lifetime_seconds_leaf'],
}
# ------------------------------------------------------- blinded tags ----
def _blind(sk_hex: str, counterparty_pk_hex: str, label: str) -> str:
b = CONSTANTS['blinding'][label]
shared = bytes.fromhex(crypto.ecdh_x(sk_hex, counterparty_pk_hex))
return crypto.hkdf(shared, b['info'].encode(), b['salt'].encode(), 32).hex()
[docs]def grant_tag(sk_hex: str, counterparty_pk_hex: str) -> str:
"""The d tag of a kind 30801. Both parties derive it; nobody else can."""
return _blind(sk_hex, counterparty_pk_hex, 'grant')
[docs]def job_tag(sk_hex: str, counterparty_pk_hex: str) -> str:
"""The d tag of a kind 30811. Same construction, different labels."""
return _blind(sk_hex, counterparty_pk_hex, 'job')
# --------------------------------------------------------- descriptor ----
# Tag access is store.tags / store.first_tag; the copies that lived here were
# the same function under other names.
tags_of = store.tags
[docs]def first(
event: EventLike,
name: str,
default: Optional[list[str]] = None,
) -> Optional[list[str]]:
t = store.first_tag(event, name)
return t if t is not None else default
[docs]def protocols_of(event: EventLike) -> set[str]:
"""The fleetmesh protocols a descriptor declares: every c tag whose value is
a protocol identifier. Plain capabilities (relay, blossom, mediator) are
hints and are not returned; these are binding."""
return {t[1] for t in tags_of(event, 'c') if len(t) > 1 and t[1].startswith(FLEETMESH)}
[docs]def foreign_protocols_of(event: EventLike) -> set[str]:
"""Protocol identifiers a descriptor declares under an origin that is not
fleetmesh's: every https:// c tag shaped <origin>/<name>/<major>.<minor>
that protocols_of() leaves out.
These are dialects - protocols minted by someone else, under their own
origin, which fleetmesh relays and never judges. They take no part in
peering admission (only the required fleetmesh protocols do), are not
governed by the schema digest, and need no registry entry here: the
origin is the namespace. A node that speaks one says so with the same
tag it uses for ours; one that does not ignores it.
"""
out: set[str] = set()
for t in tags_of(event, 'c'):
if len(t) < 2 or not t[1].startswith('https://') or t[1].startswith(FLEETMESH):
continue
parts = t[1].rstrip('/').rsplit('/', 2)
if len(parts) != 3:
continue
major, _, minor = parts[2].partition('.')
if parts[1] and store.ascii_int(major) is not None and store.ascii_int(minor) is not None:
out.add(t[1])
return out
[docs]def validate_descriptor(
event: EventLike,
now: int,
digest: Optional[str] = None,
) -> list[str]:
"""Check a kind 11801 against every rule the specification states.
Returns a list of failures; empty means valid. Deliberately returns all of
them rather than raising on the first, because an operator fixing a
descriptor wants the whole list.
`now` is the caller's clock, always: this library never reads the wall
clock, so a verdict about expiry is reproducible from its inputs alone.
"""
if now is None:
raise ValueError('now is required')
now_ts = now
out: list[str] = []
if event.get('kind') != 11801:
return ['not a kind 11801']
spec = KINDS['11801']
raw_tags = event.get('tags')
if not isinstance(raw_tags, list):
return ['tags must be an array of arrays of strings']
# A tag that is not an array of strings is not a tag (NIP-01); it is
# reported once here and ignored by every tags_of() below, so no later
# rule crashes on it.
if any(not isinstance(t, list) or not t or not all(isinstance(x, str) for x in t) for t in raw_tags):
out.append('every tag must be a non-empty array of strings')
present = {t[0] for t in raw_tags if isinstance(t, list) and t and isinstance(t[0], str)}
for req in spec['required_tags']:
if req not in present:
out.append('missing required tag: %s' % req)
cls = first(event, 'class')
if cls and (len(cls) < 2 or cls[1] not in CLASS_MAX_LIFETIME):
out.append('class must be one of %s' % sorted(CLASS_MAX_LIFETIME))
proto = first(event, 'protocol')
if proto:
if len(proto) < 3:
out.append('protocol tag needs a name and a digest')
elif not spelling.is_hex(proto[2], 64):
out.append('protocol digest is not 64 lowercase hex')
# A digest that differs from ours is not a failure: compatibility is
# decided per protocol below (constants.json protocol_floors_note).
# notices() reports the difference to the operator.
declared = protocols_of(event)
for p in sorted(declared):
if protocol_version(p) is None:
out.append('c names %s, which is not <name>/<major>.<minor>' % p[len(FLEETMESH):])
out.extend(compatible(declared))
exp = first(event, 'expiration')
if exp:
ts = store.ascii_int(exp[1]) if len(exp) > 1 else None
if ts is None:
out.append('expiration is not a timestamp')
else:
if ts <= now_ts:
out.append('descriptor has expired')
created = event.get('created_at', now_ts)
if not store.is_int(created):
out.append('created_at must be an integer')
elif cls and len(cls) > 1 and cls[1] in CLASS_MAX_LIFETIME:
lifetime = ts - created
if lifetime > CLASS_MAX_LIFETIME[cls[1]]:
out.append('lifetime %ds exceeds the %s maximum of %ds'
% (lifetime, cls[1], CLASS_MAX_LIFETIME[cls[1]]))
# A leaf claims nothing and mediates for nobody.
if cls and len(cls) > 1 and cls[1] == 'leaf':
if tags_of(event, 'coverage'):
out.append('a leaf MUST NOT publish coverage claims')
caps = {t[1] for t in tags_of(event, 'c') if len(t) > 1}
if 'mediator' in caps:
out.append('a leaf cannot be a mediator')
for k in tags_of(event, 'key'):
if len(k) < 3 or k[1] not in ('agreement', 'transport', 'fips'):
out.append('key tag must be agreement, transport, or fips with a value')
elif k[1] in ('agreement', 'transport') and (not k[2].startswith(('fec01', 'fed01'))
or not spelling.is_hex(k[2][5:], 64)):
out.append('key %s is not a multibase-f multikey over 32 bytes' % k[1])
elif k[1] == 'fips' and not ((k[2].startswith('fec01') and spelling.is_hex(k[2][5:], 64))
or spelling.is_hex(k[2], 64)):
out.append('key fips is not a 64-hex key or multibase-f multikey over 32 bytes')
for e in tags_of(event, 'endpoint'):
if len(e) < 3:
out.append('endpoint needs a scheme and an address')
elif len(e) > 3 and store.ascii_int(e[3]) is None:
out.append('endpoint preference must be ASCII digits')
if event.get('pubkey') and first(event, 'operator'):
op = first(event, 'operator')
if op and len(op) > 1 and op[1] == event['pubkey']:
out.append('operator pubkey equals the node key, which defeats the '
'independence check that compares them')
return out
[docs]def pow_bits(event_id_hex: str) -> int:
"""Leading zero bits of an event id, for NIP-13.
The id must be exactly 64 hex digits; anything else raises ValueError.
int(s, 16) alone accepted an eight-character string and counted the 224
bits it did not have as leading zeros, which is a proof of work for free."""
if not spelling.is_hex(event_id_hex, 64, upper=True):
raise ValueError('an event id is 64 hex digits')
n = int(event_id_hex, 16)
return 256 - n.bit_length() if n else 256
[docs]def meets_pow(event_id_hex: str, target_bits: Optional[int] = None) -> bool:
target = target_bits if target_bits is not None else CONSTANTS['descriptor']['default_pow_bits']
return pow_bits(event_id_hex) >= target