"""peering/1.0: how two strangers end up holding a pair of grants.
Every other module assumes a grant already exists. This is the handshake that
produces one, and it is the only place in the protocol where a node decides
about somebody it has never carried traffic for.
What that decision is allowed to rest on is short, and deliberately so:
the protocols the required protocols (peering, budget) MUST be
compatible: same major, the peer's minor at or above
this node's floor (schema/constants.json
protocol_floors). Every other protocol is shared or
not; a peering whose policy needs one the peer lacks
is declined, the rest are simply not used with it.
The schema digest is provenance of the build and is
surfaced, never a refusal on its own (since 0.3).
What it is *not* allowed to rest on is standing, because a stranger has none.
A peering therefore always opens at the probation tier, whose ceilings are
worth almost nothing and whose reporter weight is exactly zero. That is the
whole sybil argument: enrolment can be open because admission buys nothing.
The result is two grants, not one. Each side issues its own, in its own
direction, blinded to its own pair identifier - so neither can be read from a
relay and neither depends on the other being honest.
Standard library only.
"""
from __future__ import annotations
import json
import secrets
from typing import Any, Iterable, Mapping, Optional, Sequence, get_args
from ..crypto import crypto
from ..identity import identity
from ..storage import replication, store
from ..wire import schema_files, wire_types
from ..accounting import window
from ..conformance.errors import FleetmeshError
from ..wire.interfaces import (
DIDCommMessage,
GrantPayload,
NostrEvent,
PeeringBudgetSelf,
PeeringOfferItem,
PeeringWant,
SchemaConstantsDocument,
UnsignedNostrEvent,
)
CONSTANTS: SchemaConstantsDocument = schema_files.load_constants()
DIGEST: str = schema_files.digest()
PIURI: str = 'https://fleetmesh.org/peering/1.0'
VERSION: str = schema_files.load_kinds()['version']
# Decline codes, taken from the published schema rather than invented beside
# it - the vocabulary belongs to schemas/didcomm/peering/decline.schema.json and
# wire_types.DeclineCode, and there should be exactly one of it. The names
# below ARE the published codes; there used to be a second vocabulary of
# aliases (PROTOCOL_MISMATCH for UNSUPPORTED_VERSION, ...) that a reader had
# to translate back. Non-adverse by definition: declining is not a finding,
# and a node that reads refusal as a signal has rebuilt the pressure to
# accept that open enrolment exists to remove.
UNSUPPORTED_VERSION: str = 'UNSUPPORTED_VERSION'
BAD_DESCRIPTOR: str = 'BAD_DESCRIPTOR'
INSUFFICIENT_POW: str = 'INSUFFICIENT_POW'
UNSUPPORTED_TRANSPORTS: str = 'UNSUPPORTED_TRANSPORTS'
UNSUPPORTED_PROTOCOL: str = 'UNSUPPORTED_PROTOCOL'
NO_MATCHING_SHARDS: str = 'NO_MATCHING_SHARDS'
POLICY: str = 'POLICY_MISMATCH'
CAPACITY: str = 'CAPACITY_EXCEEDED'
DISCRETIONARY: str = 'DISCRETIONARY'
_DECLINE_SCHEMA = schema_files.schema_path('didcomm', 'peering', 'decline.schema.json')
with open(_DECLINE_SCHEMA, encoding='utf-8') as _fh:
_ALLOWED: set[str] = set(json.load(_fh)['properties']['body']['properties']['code']['enum'])
assert {UNSUPPORTED_VERSION, BAD_DESCRIPTOR, INSUFFICIENT_POW, UNSUPPORTED_TRANSPORTS,
UNSUPPORTED_PROTOCOL, NO_MATCHING_SHARDS, POLICY, CAPACITY, DISCRETIONARY} <= _ALLOWED, \
'a decline code here is not in the published enum'
assert _ALLOWED == set(get_args(wire_types.DeclineCode)), \
'wire_types.DeclineCode and the published decline enum disagree'
[docs]class Policy:
"""What a node requires of a stranger. Its own choice, published as a
digest in its descriptor, and nobody else's business."""
[docs] def __init__(
self,
pow_bits: Optional[int] = None,
transports: Optional[dict[str, int]] = None,
shards: Optional[Mapping[str, Any]] = None,
open_enrolment: bool = True,
opening_tier: str = 'probation',
protocols: Optional[Iterable[str]] = None,
tiers: Optional[dict[str, str]] = None,
) -> None:
self.pow_bits: int = (
CONSTANTS['descriptor']['default_pow_bits']
if pow_bits is None else pow_bits
)
# None means "not configured", and gets the default; {} means the
# operator declared no transports, and every proposal is declined on
# that ground. `or` conflated the two, which Rust did not.
self.transports: dict[str, int] = (
{'iroh': 10, 'libp2p': 20, 'wss': 40} if transports is None else dict(transports))
self.shards: Mapping[str, Any] = shards or {}
# Only the boolean false closes enrolment. A policy file that spells
# it as 0, "", or null is a misconfiguration to notice, not an
# instruction to turn every peer away.
if open_enrolment is not None and not isinstance(open_enrolment, bool):
raise ValueError('open_enrolment must be true or false')
self.open_enrolment: bool = open_enrolment is not False
self.opening_tier: str = opening_tier
# Protocols this node needs a peer to implement beyond the ones every
# node must. A node peering for the compute market asks for compute/1.0
# here; a plain relay asks for nothing.
self.protocols: set[str] = set(protocols or ())
# Peers this operator has decided about out of band. Everyone else opens
# at opening_tier, which is probation, and ยง Trust weighting says that is
# the correct behaviour and also the slowest possible start: an operator
# in a hurry MAY seed the table by granting a higher tier to nodes it
# knows. That is a human decision, recorded as a signed event and
# reversible, and it is the only thing that raises a tier - nothing in
# the ladder ever does, because standing is bought with observed time
# rather than granted by arithmetic.
self.tiers: dict[str, str] = dict(tiers or {})
[docs] def tier_for(self, subject_pubkey: str) -> str:
return self.tiers.get(subject_pubkey, self.opening_tier)
[docs]class Declined(FleetmeshError):
"""Raised with a code so a caller cannot mistake a refusal for a failure."""
[docs] def __init__(self, code: str, message: str = '') -> None:
super().__init__('%s: %s' % (code, message) if message else code)
self.code: str = code
self.message: str = message
def _sender_key(sender: Any) -> str:
"""The 64-hex key a proposal's `from` names, or a BAD_DESCRIPTOR decline.
The sender is a did:nostr over a 64-hex key or it is nobody this node can
hold a tier for. Anything else - a different method, a non-string, a key
of the wrong length or case - is a decline, not a KeyError or a tier
looked up under a mangled name."""
if (not isinstance(sender, str) or not sender.startswith('did:nostr:')
or not store.is_hex64(sender[len('did:nostr:'):])):
raise Declined(BAD_DESCRIPTOR, 'from must be did:nostr:<64 hex>')
return sender[len('did:nostr:'):]
def _str_list(value: Any, field: str) -> list[str]:
"""A wire field that must be a list of strings, or a Declined naming it.
Peering messages arrive from strangers, so their shape is a claim like
any other. A field of the wrong type is a BAD_DESCRIPTOR decline - the
proposal does not describe a peer this node can reason about - and never
a TypeError that a caller would have to read as a failure of its own.
"""
if not isinstance(value, (list, tuple)) or not all(isinstance(x, str) for x in value):
raise Declined(BAD_DESCRIPTOR, '%s must be a list of strings' % field)
return list(value)
def _require_now(now: Optional[int]) -> int:
"""The one clock policy of this module: the caller supplies the instant.
Nothing here reads the wall clock and nothing defaults to 0, because a
grant envelope stamped at epoch 0 is one whose expiration passed decades
ago and whose window index is a lie. A missing clock is a programming
error and is reported as one.
"""
if now is None:
raise ValueError('now is required')
return now
[docs]class Node:
"""One node's side of a peering handshake.
Holds the node key, the descriptor it publishes, its policy, and the grants
it has issued. It never holds anything about the peer that the peer did not
sign.
"""
[docs] def __init__(
self,
sk_hex: str,
descriptor: Optional[NostrEvent],
policy: Optional[Policy] = None,
node_class: str = 'edge',
) -> None:
self.sk: str = sk_hex
self.pubkey: str = crypto.pubkey(sk_hex)
self.did: str = 'did:nostr:%s' % self.pubkey
self.descriptor: Optional[NostrEvent] = descriptor
self.protocols: set[str] = identity.protocols_of(descriptor) if descriptor else set()
self.policy: Policy = policy or Policy()
self.node_class: str = node_class
self.issued: dict[str, GrantPayload] = {} # subject pubkey -> grant payload
# subject pubkey -> kind 30801 event. Unsigned here; node/ overrides
# _publish_envelope with a signed one, so the map holds either.
self.envelopes: dict[str, NostrEvent | UnsignedNostrEvent] = {}
self.threads: dict[str, str] = {} # peer pubkey -> DIDComm thread id
self.digest_mismatch: dict[str, str] = {} # peer pubkey -> the schema digest it declared, when not ours
# ---- messages --------------------------------------------------------
def _msg(self, kind: str, body: Mapping[str, Any], to: str, thid: Optional[str] = None) -> DIDCommMessage:
"""A DIDComm plaintext message. Every reply carries the thread the
propose opened; only the propose itself has none, which is what makes
it the proposal rather than an answer to one."""
m: DIDCommMessage = {
'id': 'peer-%s-%s-%d' % (kind, self.pubkey[:8], len(self.threads)),
'type': '%s/%s' % (PIURI, kind),
'from': self.did,
'to': [to],
'body': body,
}
if kind != 'propose':
peer = to.rsplit(':', 1)[-1]
m['thid'] = thid or self.threads.get(peer) or m['id']
return m
[docs] def propose(
self,
to_did: str,
want: Sequence[PeeringWant | Mapping[str, Any]],
offer: Sequence[PeeringOfferItem | Mapping[str, Any]],
budget_self: PeeringBudgetSelf | Mapping[str, Any],
pow_event: Optional[str] = None,
pow_bits: Optional[int] = None,
) -> DIDCommMessage:
"""peering/1.0/propose. Declares who I am and what I want.
`want` is the interest this peering is for and `offer` is what I claim
to hold. Both are scoped: a peering is per shard, not per node, because
a grant is scoped to an interest and there is no such thing as a general
licence to send.
"""
body = {
'class': self.node_class,
'protocol': [VERSION, DIGEST],
'protocols': sorted(self.protocols),
'want': want,
'offer': offer,
'transports': sorted(self.policy.transports),
'budget_self': budget_self,
'policy': crypto.sha256(b'policy:' + self.pubkey.encode()),
}
if pow_event is not None:
body['pow'] = {
'bits': pow_bits if pow_bits is not None else identity.pow_bits(pow_event),
'event': pow_event,
}
m = self._msg('propose', body, to_did)
self.threads[to_did.rsplit(':', 1)[1]] = m['id']
return m
# ---- admission -------------------------------------------------------
[docs] def examine(
self,
proposal: Mapping[str, Any],
peer_descriptor: Optional[NostrEvent],
now: int,
) -> tuple[str, list[str]]:
"""Decide whether to peer. Raises Declined, or returns the tier to open at.
The tier is the operator's, not the arithmetic's: everyone opens at
probation unless this operator decided otherwise about that peer out of
band. See Policy.tier_for.
Ordered cheapest-first, and the order is not cosmetic: a digest
comparison costs nothing and a descriptor validation costs a parse, so
an incompatible node is turned away before anyone spends work on it.
"""
body = proposal.get('body')
if not isinstance(body, dict):
raise Declined(BAD_DESCRIPTOR, 'proposal has no body')
# The sender is a did:nostr over a 64-hex key or it is nobody this
# node can hold a tier for. Anything else - a different method, a
# non-string, a key of the wrong length - is a BAD_DESCRIPTOR decline,
# not a KeyError or a tier looked up under a mangled name.
subject = _sender_key(proposal.get('from'))
# Shape before meaning: a proposal whose `protocol` is not a
# [name, digest] pair of strings is turned away with a code, not a
# traceback. The name check that follows is the deliberate
# UNSUPPORTED_VERSION gate; this only makes sure it has something
# to look at.
proto = body.get('protocol')
if (not isinstance(proto, (list, tuple)) or len(proto) < 2
or not all(isinstance(x, str) for x in proto[:2])):
raise Declined(BAD_DESCRIPTOR, 'protocol must be [name, digest]')
name, digest = proto[0], proto[1]
if name != VERSION:
raise Declined(UNSUPPORTED_VERSION, 'version name %r' % name)
# The digest is provenance, not a gate (since 0.3). A peer built from a
# different schema is admitted on the strength of its per-protocol
# declaration below, and the difference is kept for the operator to
# see in `meshnode peers` and health: a mesh drifting onto several
# schemas is worth knowing about, and refusing it is not the answer.
if digest != DIGEST:
self.digest_mismatch[subject] = digest
else:
self.digest_mismatch.pop(subject, None)
if body.get('class') not in ('leaf', 'edge', 'anchor'):
raise Declined(BAD_DESCRIPTOR, 'class %r' % body.get('class'))
# The digest says which schema the peer was built from, not whether we
# can talk: that is decided per protocol. The proposal names what it
# implements; the required protocols must be compatible with ours
# (same major, minor at or above our floor), and a peering whose
# policy needs a protocol the peer does not share is declined here,
# before a descriptor is parsed, because the comparison costs nothing.
theirs_p = set(_str_list(body.get('protocols', []), 'protocols'))
short = lambda p: p[len(identity.FLEETMESH):]
why = identity.compatible(theirs_p)
if why:
raise Declined(UNSUPPORTED_PROTOCOL, why[0])
shared = identity.shared_families(theirs_p, set(identity.PROTOCOLS))
missing = sorted(p for p in self.policy.protocols
if (pv := identity.protocol_version(p)) is None or (pv[0], pv[1]) not in shared)
if missing:
raise Declined(UNSUPPORTED_PROTOCOL, 'this peering needs %s' % ', '.join(map(short, missing)))
if peer_descriptor is not None:
problems = identity.validate_descriptor(peer_descriptor, now=now, digest=DIGEST)
if problems:
raise Declined(BAD_DESCRIPTOR, '; '.join(problems[:2]))
# The descriptor is the signed, public declaration; the proposal is
# what the peer says in private. They must agree, or one of them lies.
published = identity.protocols_of(peer_descriptor)
if published != theirs_p:
raise Declined(BAD_DESCRIPTOR, 'proposal declares %s, descriptor declares %s'
% (sorted(map(short, theirs_p)), sorted(map(short, published))))
if self.policy.pow_bits:
pow_ = body.get('pow')
if not isinstance(pow_, dict) or not isinstance(pow_.get('event'), str):
raise Declined(INSUFFICIENT_POW, 'policy requires %d bits'
% self.policy.pow_bits)
try:
actual = identity.pow_bits(pow_['event'])
except ValueError:
raise Declined(BAD_DESCRIPTOR, 'pow.event is not a hex event id')
if actual < self.policy.pow_bits:
raise Declined(INSUFFICIENT_POW,
'%d bits, policy requires %d' % (actual, self.policy.pow_bits))
theirs = {t: i for i, t in enumerate(_str_list(body.get('transports'), 'transports'))}
ladder = replication.negotiate(self.policy.transports, theirs)
if not ladder:
raise Declined(UNSUPPORTED_TRANSPORTS, 'mine %s, theirs %s'
% (sorted(self.policy.transports), sorted(theirs)))
if not self.policy.open_enrolment:
raise Declined(POLICY, 'enrolment is by invitation')
tier = self.policy.tier_for(subject)
if tier not in window.C['tier_limits'] or tier == 'dup_ratio':
# An operator's table can name a tier the ladder does not have.
# That is this node's misconfiguration and not the peer's fault,
# so it is a policy decline rather than an offer with no limits.
raise Declined(POLICY, 'policy names tier %r, which is not a tier' % (tier,))
return tier, ladder
[docs] def offer(
self,
proposal: Mapping[str, Any],
peer_descriptor: Optional[NostrEvent],
now: int,
) -> DIDCommMessage:
"""peering/1.0/offer, or a decline. This is where the grant is written.
A leaf is refused as a *counterparty to issue to* only in the sense that
it may not issue back: it is the subject of one grant from its mediator
and nothing else. It is never refused admission for being a leaf.
`now` is the caller's clock and is required: the envelope written here
carries an epoch and an expiration, and a missing clock used to stamp
both at 0, which published a grant already a lifetime expired.
"""
_require_now(now)
sender = proposal.get('from')
try:
subject = _sender_key(sender)
self.threads[subject] = str(proposal.get('id') or '')
tier, ladder = self.examine(proposal, peer_descriptor, now)
except Declined as d:
# A decline is addressed to whatever the proposal said it was from;
# a sender that is not a string gets one addressed to nobody.
return self._msg('decline', {'code': d.code, 'message': d.message},
sender if isinstance(sender, str) else '')
# Past examine(), the sender is known to be a did:nostr string.
to = 'did:nostr:' + subject
want = proposal['body'].get('want') or []
if not isinstance(want, list) or not all(
isinstance(w, Mapping) and isinstance(w.get('filter'), Mapping) for w in want
):
return self._msg('decline', {'code': BAD_DESCRIPTOR, 'message': 'want must be a list'}, to)
grant = self._write_grant(subject, tier, want)
envelope = self._publish_envelope(subject, grant, now)
return self._msg('offer', {'tier': tier, 'limits': grant['limits'],
'transports': ladder,
'grant_envelope': envelope['id']}, to)
def _write_grant(self, subject: str, tier: str, want: Sequence[Mapping[str, Any]]) -> GrantPayload:
"""The grant payload, scoped to the interest that was asked for.
Ceilings are the tier's, and a grant MAY set any limit lower but MUST
NOT set one higher - so the ceiling is applied here rather than trusted
to whoever wrote the policy.
It opens BELOW the ceiling. A grant that opened at the ceiling left the
additive increase nothing to do - min(ceiling, v + step) is the ceiling
when v already is it - so every capacity in this protocol was issued
whole on the first day and could only afterwards be eroded. Volume opens
at a fraction and is earned by carrying load; the structural limits open
at the ceiling, because a peer needs enough plumbing to demonstrate
anything at all.
"""
limits = window.opening_limits(tier)
scope = {}
for w in want:
scope[w.get('mode', 'both')] = w['filter']
if 'both' in scope:
scope = {'push': scope['both'], 'pull': scope['both']}
payload: GrantPayload = {
'subject': subject,
'tier': tier,
'limits': limits,
'scope': scope,
'window': CONSTANTS['grant']['window_seconds_default'],
'receipt': [600, 1048576],
'settlement': 'none',
# Fresh per commitment and never derived: the grant is mostly
# guessable, so hiding rests on this alone. See
# commitment.blinding_factor in constants.json.
'blinding': secrets.token_bytes(32).hex(),
}
self.issued[subject] = payload
return payload
def _publish_envelope(self, subject: str, grant: GrantPayload, now: int) -> NostrEvent | UnsignedNostrEvent:
"""The public kind 30801: a blinded identifier and a commitment, nothing else."""
d = identity.grant_tag(self.sk, subject)
commit = crypto.commit(crypto.canonical(grant), grant['blinding'])
window_s = grant['window']
tags = [
['d', d],
['commit', commit],
['scheme', CONSTANTS['commitment']['scheme'], 'nip44/2'],
['window', str(window_s)],
['epoch', str(now // window_s)],
['expiration', str(now + window_s * 24)],
]
ev = store.make_event(
self.pubkey,
now,
30801,
tags,
'<nip44 ciphertext of the grant to the subject>',
)
self.envelopes[subject] = ev
return ev
# ---- the other side --------------------------------------------------
[docs] def accept(
self,
offer: Mapping[str, Any],
peer_did: str,
want: Sequence[Mapping[str, Any]],
now: int,
) -> Mapping[str, Any]:
"""peering/1.0/accept. Publishes the reverse grant, which is what makes
the peering exist: acceptance is an event, not a message. `now` is
required for the same reason as in offer()."""
_require_now(now)
if offer['type'].endswith('/decline'):
raise Declined(offer['body']['code'], offer['body'].get('message', ''))
subject = peer_did.rsplit(':', 1)[1]
ladder = _str_list((offer.get('body') or {}).get('transports'), 'transports')
if not ladder:
raise Declined(UNSUPPORTED_TRANSPORTS, 'offer names no transport')
grant = self._write_grant(subject, self.policy.tier_for(subject), want)
envelope = self._publish_envelope(subject, grant, now)
transport = ladder[0]
return self._msg('accept', {'grant_envelope': envelope['id'],
'selected_transport': transport}, peer_did)
[docs] def disclose(self, query: Optional[list[dict[str, str]]] = None) -> dict[str, list[dict[str, str]]]:
"""discover-features/2.0 disclose, answered from the descriptor.
The descriptor is the binding declaration and this is its echo, so the
two cannot disagree by construction. query is the DIDComm shape,
[{'feature-type': 'protocol', 'match': <identifier or prefix>}]. A
match ending in * is a prefix; anything else must equal the id.
"""
ids = sorted(self.protocols)
if query:
keep: list[str] = []
for q in query:
if q.get('feature-type', 'protocol') != 'protocol':
continue
m = q.get('match', '*')
keep += [i for i in ids if (i.startswith(m[:-1]) if m.endswith('*') else i == m)]
ids = sorted(set(keep))
return {'disclosures': [{'feature-type': 'protocol', 'id': i} for i in ids]}
[docs] def on_revocation(self, revocation: NostrEvent, ledger: Optional[Any] = None) -> Mapping[str, Any]:
"""A valid kind 11802 from a peer zeroes every grant issued to it.
Standing does not follow the successor tag: the ledger, if given, closes
the subject's record and opens nothing for anyone else. Returns what was
done, or the problems that made the revocation invalid.
"""
from ..services import lifecycle
problems = lifecycle.check_revocation(revocation)
if problems:
return {'applied': False, 'problems': problems}
pk = revocation['pubkey']
zeroed = pk in self.issued
if zeroed:
self.issued[pk]['limits'] = {k: 0 for k in self.issued[pk]['limits']}
self.issued[pk]['tier'] = 'revoked'
if ledger is not None:
ledger.on_revocation(pk)
return {
'applied': True,
'zeroed': zeroed,
'successor': lifecycle.successor_of(revocation),
'successor_inherits': 'nothing',
}
[docs] def terminate(self, peer_pubkey: str, reason: str = 'operator', grace_seconds: int = 0) -> DIDCommMessage:
"""peering/1.0/terminate. The grant is zeroed here and now; the grace
period is about draining traffic, not about keeping capacity."""
if peer_pubkey in self.issued:
self.issued[peer_pubkey]['limits'] = {k: 0 for k in self.issued[peer_pubkey]['limits']}
self.issued[peer_pubkey]['tier'] = 'revoked'
return self._msg('terminate', {'reason': reason, 'grace_seconds': grace_seconds},
'did:nostr:%s' % peer_pubkey)
[docs]def handshake(
proposer: Node,
acceptor: Node,
want: Sequence[PeeringWant | Mapping[str, Any]] | Mapping[str, Any],
offer: Optional[Sequence[PeeringOfferItem | Mapping[str, Any]]] = None,
budget_self: Optional[PeeringBudgetSelf | Mapping[str, Any]] = None,
pow_event: Optional[str] = None,
proposer_descriptor: Optional[NostrEvent] = None,
*,
now: int,
) -> DIDCommMessage | Mapping[str, Any]:
"""Run a whole peering and return both grants, or the decline.
The pair is the point. Each side issues in its own direction, so a peering
is symmetric in structure and independent in substance: the limits, the
tier and the scope on one side say nothing about the other.
`now` is the clock both envelopes are stamped with and has no default: a
reference handshake that silently ran at epoch 0 proved nothing about
expiry.
"""
_require_now(now)
want_list: Sequence[Mapping[str, Any]] = [want] if isinstance(want, Mapping) else list(want)
proposal = proposer.propose(acceptor.did, want_list, offer or [],
budget_self or {'events_in': 600, 'bytes_in': 8388608,
'window': 3600},
pow_event=pow_event)
reply = acceptor.offer(proposal, proposer_descriptor, now)
if reply['type'].endswith('/decline'):
return {'declined': reply['body'], 'transcript': [proposal, reply]}
accept = proposer.accept(reply, acceptor.did, want_list, now)
return {
'transcript': [proposal, reply, accept],
'to_proposer': acceptor.issued[proposer.pubkey],
'to_acceptor': proposer.issued[acceptor.pubkey],
'proposer_envelope': proposer.envelopes[acceptor.pubkey],
'acceptor_envelope': acceptor.envelopes[proposer.pubkey],
'transport': accept['body']['selected_transport'],
}