fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/peering/peering/core.py

@@ -0,0 +1,464 @@
+"""The Peering compartment: construction, the grant writers (`issue`,
+`decide`), the reconciler that is its tick, and the compartment contract.
+The handshake itself is in handshake.py; the envelope in envelope.py."""
+from __future__ import annotations
+
+import secrets
+from typing import Any, Callable, cast, Mapping, Optional, Sequence
+
+from fleetmesh_core.accounting import window
+from fleetmesh_core.identity import identity
+from fleetmesh_core.peering import peering
+from fleetmesh_core.services import discover
+from fleetmesh_core.wire.interfaces import GrantPayload, NostrEvent
+from fleetmesh_core.wire.wire_types import AmendCause, PeeringAmendBody
+from node import channels as ch_mod
+from node.channels import bus as eventbus_mod
+from fleetmesh_core.identity.did import did_nostr
+from node.storage import grants as grants_mod
+from node import metrics as mx_mod
+from node.compartment import stores as st
+from node.protocols.nostr import client as relay
+from node.config.records import PolicyConfig
+from node.compartment import Command, Handler, Need, Outbound, Refusal, WireProtocol
+from .envelope import CAUSES, GRANT_KIND, GrantUnpublished, LOG_KEEP, PeeringError, RECONCILE_EVERY, WireNode, open_envelope
+from .handshake import HandshakeMixin
+from .shape import PeeringHost
+
+
+from .types import (
+    Issued,
+    PeeringDecision,
+    PeeringStateReport,
+)
+
+
+class Peering(HandshakeMixin, WireProtocol):
+    """The handshake and the grants, as a compartment.
+
+    Its tick is the reconciler: an amend is a notification and the addressable
+    kind 30801 is what the grant IS, so a subject reads the coordinate rather
+    than waiting to be told. Its refusals are every amend it would not act on
+    and every peering it turned away - the path that recorded nothing at all on
+    the night every amend on the mesh was lost.
+    """
+
+    name: str = 'peering'
+    reads: tuple[str, ...] = ('policy',)
+    config_cls = PolicyConfig
+    # Nothing here reaches link, trust or strain: the handshake runs on the
+    # context's keystore, descriptor, peers, transport, policy and grant
+    # store. Capacity is a back-edge (bind), not a requirement.
+    requires: tuple[str, ...] = ()
+    piuris: tuple[str, ...] = (peering.PIURI,)
+    exact_types: tuple[str, ...] = (discover.QUERIES,)
+    HANDLERS = (
+        Handler(discover.QUERIES, run='handle_discover', exact=True, doc='answer discover-features/2.0 query'),
+        Handler('propose', run='handle_propose', writes=('grants',), doc='answer peering proposal'),
+        Handler('accept', run='handle_accept', writes=('grants',), doc='take peering acceptance'),
+        Handler('amend', run='handle_amend', writes=('grants',), doc='take amended grant'),
+        Handler('terminate', run='handle_terminate', writes=('grants',), doc='tear down peering'),
+    )
+    OUTBOUND = (
+        Outbound('propose', reply=('offer', 'decline'), doc='send peering proposal to peer'),
+        Outbound('offer', reply='accept', doc='offer peering terms to proposer'),
+        Outbound('accept', doc='accept offered peering terms'),
+        Outbound('decline', doc='decline peering proposal with code and reason'),
+        Outbound('amend', doc='notify peer of amended grant'),
+        Outbound('terminate', doc='terminate active peering relationship'),
+    )
+    COMMANDS = (
+        Command(
+            key='show',
+            name='Peering',
+            description='the peerings this node holds, and when each grant was last reconciled',
+            tags=('peering', 'status'),
+            permission='peering/show',
+            run='state',
+            reply='{peers, reconciled, refused}',
+        ),
+    )
+
+    # What it keeps. The log was a list appended once per inbound peering
+    # message - including the ones it ignored or failed on, so a stranger
+    # could grow it - and never trimmed. The newest LOG_KEEP, the same as the
+    # node's own log beside it.
+    STORES = (
+        st.Store(key='log', description='what the handshake did with each message, newest last',
+                 kind=st.RING, shape=tuple, bound=LOG_KEEP),
+        st.Store(key='_reconciled', description='when each peer grant coordinate was last read',
+                 kind=st.TABLE, shape=int, bound=4096, keyed_by='peer', evict=st.LRU),
+    )
+    CHANNELS = (
+        ch_mod.Channel('grant_issued', 'A peering grant was issued or amended for a peer',
+                       level=ch_mod.INFO, wire=eventbus_mod._wire_grant,
+                       say='peering grant issued to {peer} (cause: {cause}, tier: {tier})',
+                       tags=('peering', 'grant')),
+        ch_mod.Channel('peer_connected', 'A peer completed the peering handshake and connected',
+                       level=ch_mod.INFO, wire=eventbus_mod._wire_peer,
+                       say='peer connected: {peer} as {role} via {transport}',
+                       tags=('peering', 'handshake')),
+        ch_mod.Channel('peering_declined', 'Peering proposal was declined',
+                       level=ch_mod.TROUBLE, say='peering proposal declined from {peer}: {reason}',
+                       tags=('peering', 'decline')),
+        ch_mod.Channel('peering_terminated', 'Peering relationship was terminated',
+                       level=ch_mod.NOTE, say='peering terminated with {peer}: {reason}',
+                       tags=('peering', 'terminate')),
+    )
+    METRICS = (
+        mx_mod.Metric(name='peering_grants_issued', description='Grants issued or amended.',
+                      kind=mx_mod.COUNTER, counts='grant_issued', tags=('peering', 'grant')),
+        mx_mod.Metric(name='peering_peers_connected', description='Peers connected.',
+                      kind=mx_mod.COUNTER, counts='peer_connected', tags=('peering', 'handshake')),
+        mx_mod.Metric(name='peering_proposals_declined', description='Peering proposals declined.',
+                      kind=mx_mod.COUNTER, counts='peering_declined', tags=('peering', 'decline')),
+        mx_mod.Metric(name='peering_relationships_terminated', description='Peering relationships terminated.',
+                      kind=mx_mod.COUNTER, counts='peering_terminated', tags=('peering', 'terminate')),
+    )
+    NEEDS = (
+        Need('keystore', 'ks'),
+        Need('my_descriptor', 'descriptor'),
+        Need('peers'),
+        Need('transport'),
+        Need('relay_urls', 'relays'),
+        Need('grant_store', 'stores.grants'),
+        Need('policy'),
+        Need('node_class'),
+        Need('timeout'),
+        Need('events'),
+        Need('capacity', late=True),
+    )
+
+    def bind(self, capacity: Any) -> None:
+        """The node's own ceiling, through which a stranger is refused.
+        Capacity ticks after budget, which ticks after peering, so it is
+        bound once all three exist."""
+        self.capacity = capacity
+
+    def start(self) -> None:
+        if self.events is not None:
+            events = self.events
+            self.on_grant_issued.append(lambda *a: events.emit(eventbus_mod.TOPIC_GRANT_ISSUED, *a))
+            self.on_peered.append(lambda *a: events.emit(eventbus_mod.TOPIC_PEER_CONNECTED, *a))
+
+    def __init__(
+        self,
+        keystore: Any,
+        my_descriptor: Any,
+        peers: Any,
+        transport: Any,
+        relay_urls: Sequence[str],
+        grant_store: Optional[grants_mod.GrantStore] = None,
+        policy: Optional[Any] = None,
+        node_class: str = 'edge',
+        clock: Optional[Callable[[], int]] = None,
+        timeout: float = 15.0,
+        capacity: Optional[Any] = None,
+        node: Optional[Any] = None,
+        publisher: Optional[Callable[[Sequence[str], Any, float], dict[str, tuple[bool, str]]]] = None,
+        host: Optional[PeeringHost] = None,
+        events: Optional[Any] = None,
+    ) -> None:
+        super().__init__(node, clock)
+        self.capacity = capacity      # the node's own ceiling, or None
+        self.events = events
+        # How a grant envelope reaches the relays; the control-plane publish,
+        # not the peer transport. Given so a test can make every relay refuse.
+        self.publisher: Callable[[Sequence[str], Any, float], dict[str, tuple[bool, str]]] = publisher or relay.publish_all
+        self._reconciled: st.Table[str, int]         # peer -> when its grant coordinate was last read
+        self.ks: Any = keystore
+        desc = my_descriptor() if callable(my_descriptor) else my_descriptor
+        self.descriptor: Any = desc
+        self.peers: Any = peers
+        self.transport: Any = transport
+        self.relays: list[str] = list(relay_urls)  # not a store: the configured relays
+        self.grants: grants_mod.GrantStore = grant_store or grants_mod.GrantStore()
+        self.timeout: float = timeout
+        # The peering state machine. fleetmesh_core decides; WireNode adds the
+        # real envelope. Anything satisfying PeeringHost may stand in (R11).
+        self.host: PeeringHost = host or WireNode(keystore.node_sk, desc, policy, node_class, clock=self.clock)
+        self.log: st.Ring[tuple[Any, ...]]            # built and bound by the base (see STORES)
+        # callbacks the node bridges onto its event bus; the compartment does not know the bus
+        self.on_grant_issued: list[Callable[[str, str, str, Optional[str]], Any]] = [
+            lambda peer, cause, env_id, tier: self.say('grant_issued', peer=peer, cause=cause, envelope_id=env_id, tier=tier)
+        ]   # (peer, cause, envelope_id, tier)
+        def _say_peered(peer: str, role: str, transport: Optional[str] = None) -> Any:
+            return self.say('peer_connected', peer=peer, role=role, transport=transport or 'direct')
+
+        self.on_peered: list[Callable[[str, str, Optional[str]], Any]] = [_say_peered]
+
+    # ---- helpers -----------------------------------------------------------
+    def handle_discover(self, inbound: Any) -> Optional[tuple[Any, ...]]:
+        """discover-features/2.0: a peer asks what this node speaks and is
+        answered from the descriptor, by fleetmesh_core/peering's disclose, so the
+        answer cannot name a protocol the descriptor does not. Anyone may
+        ask; the answer is what the descriptor already says in public."""
+        msg, sender = getattr(inbound, 'message', None), getattr(inbound, 'sender', None)
+        if not isinstance(msg, dict) or not isinstance(sender, str) or not discover.is_queries(msg):
+            return None
+        reply = discover.disclose(self.ks.did, did_nostr(sender), str(msg.get('id', '')),
+                                  self.host.disclose(discover.query_list(msg) or None))
+        try:
+            self.wire_client.send(sender, reply)
+        except Exception as e:   # the asker may hold no descriptor we can address; nothing to do
+            return ('ignored', sender, 'disclose not deliverable: %s' % e)
+        return ('disclosed', sender, len(reply['body']['disclosures']))
+
+    def _flush_envelopes(self) -> dict[str, dict[str, tuple[bool, str]]]:
+        out: dict[str, dict[str, tuple[bool, str]]] = {}
+        while self.host.published:
+            ev = self.host.published.pop(0)
+            out[ev['id']] = self.publisher(self.relays, ev, self.timeout)
+        return out
+
+    def _fetch_envelope(self, envelope_id: Optional[str], issuer_pk: str) -> NostrEvent:
+        """The grant this issuer currently publishes for the two of us.
+
+        A kind 30801 is addressable, and every grant between one pair carries
+        the same blinded `d`, so each new grant replaces the last one at that
+        coordinate. Fetching by the id an amend happens to name therefore works
+        only until the next amend: two grants issued in the same second tie on
+        created_at, NIP-01 breaks the tie on the lower id, and about half the
+        time the *newer* envelope is the one the relay drops. The subject then
+        asks for an id nothing serves.
+
+        So the coordinate is what is asked for, and the named id is a
+        preference within the answer. An amend is a notification that the grant
+        changed; the addressable event is what the grant *is*.
+        """
+        d = identity.grant_tag(self.ks.node_sk, issuer_pk)
+        found = relay.query_all(self.relays, [{'kinds': [GRANT_KIND], 'authors': [issuer_pk],
+                                               '#d': [d]}], self.timeout)
+        if not found:
+            raise PeeringError('this issuer publishes no grant for us; %s was named'
+                               % (envelope_id or '?')[:16])
+        exact = [e for e in found if e['id'] == envelope_id]
+        if exact:
+            return exact[0]
+        # NIP-01 supersession order: latest created_at, lower id breaks a tie.
+        return sorted(found, key=lambda e: (-e['created_at'], e['id']))[0]
+
+    def reconcile(self, now: Optional[int] = None) -> list[tuple[Any, ...]]:
+        """Take up a grant that changed, without waiting to be told.
+
+        An amend is a notification; the addressable kind 30801 is what the grant
+        IS, and this method is that sentence made true. A subject used to learn
+        of a new grant only from a peering/1.0/amend, which travels as a stored
+        gift wrap - kind 1059, one of the four messages the specification says
+        must survive an offline recipient.
+
+        A relay is not obliged to keep one. `relay.pocketstr.com` answers a
+        kind 1059 publish with OK and true, and then neither stores it nor
+        serves it back to the recipient itself. Every amend on a four-node mesh
+        was lost that way for a night. The two ends then name different grants
+        for ever: every receipt is refused as divergent, so every window closes
+        with no claim, so every window is active silence, so every peering earns
+        an S2 that nobody did anything to deserve, and the tier falls to
+        probation where only a person can raise it.
+
+        Asking the coordinate costs one query per peering and depends on nothing
+        arriving. A protocol that must not conclude anything from an absence
+        must also not depend on a presence.
+        """
+        now_val = now if now is not None else self.clock()
+        did: list[tuple[Any, ...]] = []
+        for peer in self.grants.peers():
+            held = self.grants.get(peer, grants_mod.RECEIVED)
+            if held is None or held['status'] != 'live':
+                continue
+            if now_val - self._reconciled.get(peer, 0) < RECONCILE_EVERY:
+                continue
+            self._reconciled[peer] = now_val
+            before = held['envelope_id']
+            try:
+                # No id is named on purpose: a named id is a preference within
+                # the answer, and what is wanted here is whatever the issuer
+                # publishes now.
+                self._take_received(None, peer)
+            except Exception as e:
+                self._refuse('reconcile', 'could not read the grant this issuer publishes',
+                             peer, {'error': '%s: %s' % (type(e).__name__, e)})
+                continue
+            now_held = self.grants.get(peer, grants_mod.RECEIVED)
+            after = now_held['envelope_id'] if now_held is not None else None
+            if after and after != before:
+                did.append(('grant reconciled', peer, before[:12], after[:12]))
+        return did
+
+    def _refuse(self, kind: str, why: str, subject: Optional[str] = None, detail: Optional[Mapping[str, Any]] = None) -> Any:
+        return self.refusals.refuse(kind, why, subject=subject, detail=detail, at=self.clock())
+
+    @property
+    def refused(self) -> list[Refusal]:
+        """The last refusals, as the typed tuple Refusals keeps (positional
+        reads still work; a NamedTuple is a tuple)."""
+        return list(self.refusals.last(200))
+
+    def issue(
+        self,
+        peer: str,
+        payload: Mapping[str, Any],
+        cause: str,
+        reason: str,
+        effective_epoch: int,
+        now: Optional[int] = None,
+        on_clamp: Optional[Callable[[str, str, dict[str, list[Any]]], Any]] = None,
+    ) -> Issued:
+        """Write, publish and record one grant, and tell the subject why.
+
+        `effective_epoch` is the window this grant governs from. Passing the
+        window already running is what breaks a receipt chain, so a caller that
+        means "from the next boundary" should say so with `decide` instead of
+        working it out here.
+
+        Raises GrantUnpublished if no relay took the envelope, having recorded
+        nothing: a grant the subject cannot fetch is worse than no grant.
+        Raises ValueError for a cause the schema does not define.
+        """
+        if cause not in CAUSES:
+            raise ValueError('cause %r is not one the amend schema defines: %s'
+                             % (cause, ', '.join(CAUSES)))
+        now_val = self.clock() if now is None else now
+        tier = payload.get('tier')
+        if not isinstance(tier, str):
+            # ceilings() would raise a bare KeyError on None a line later; the
+            # payload is the caller's and the fault should be named as such.
+            raise ValueError('grant payload for %s names no tier' % peer[:16])
+        # Every tier has a ceiling and a grant MUST NOT set a limit above it.
+        # Only one of the three writers checked; the other two took whatever
+        # payload they were handed.
+        capped = window.within(payload.get('limits') or {}, tier)
+        if capped != (payload.get('limits') or {}):
+            over = {k: [payload['limits'][k], capped[k]] for k in capped
+                    if capped[k] != payload['limits'][k]}
+            self.refusals.refuse('grant', 'carried limits above its tier ceiling', subject=peer,
+                                 detail={'tier': tier, 'over': over}, at=now_val)
+            if on_clamp is not None:
+                on_clamp(peer, tier, over)
+            payload = dict(payload, limits={k: (int(v) if float(v).is_integer() else v)
+                                            for k, v in capped.items()})
+        # The cast is the boundary between the operator's untyped payload (from
+        # app.py / budget.py) and the protocol's GrantPayload shape; the keys
+        # were checked by the schema when the grant was written, not here.
+        grant = cast(GrantPayload, dict(payload, blinding=secrets.token_bytes(32).hex()))
+        env = self.host._publish_envelope(peer, grant, now_val)
+        published = self._flush_envelopes()
+        took = {url: note for url, (ok_, note) in (published.get(env['id']) or {}).items() if ok_}
+        if self.relays and not took:
+            why = {url: note for url, (_, note) in (published.get(env['id']) or {}).items()}
+            self.refusals.refuse('grant', 'no relay would take the envelope', subject=peer,
+                                 detail={'envelope': env['id'], 'cause': cause, 'relays': why}, at=now_val)
+            raise GrantUnpublished(
+                'the grant for %s was not recorded: no relay took envelope %s (%s)'
+                % (peer[:16], env['id'][:12],
+                   '; '.join('%s: %s' % (u, n or 'refused') for u, n in sorted(why.items())) or 'no relays'))
+        self.host.issued[peer] = grant
+        self.grants.put(peer, grants_mod.ISSUED, grant, env['id'], now_val, event=env,
+                        env_created_at=env['created_at'], effective_epoch=effective_epoch)
+        self.grants.clear_pending(peer)
+        # `cause` passed the CAUSES guard above, so the Literal holds; the
+        # envelope is signed because WireNode signs, which the Protocol does
+        # not promise - a host that returned an unsigned one would fail here
+        # at the relay, not silently.
+        amend_body: PeeringAmendBody = {'reason': reason, 'cause': cast(AmendCause, cause),
+                                        'new_grant_envelope': env['id'], 'envelope_event': cast(NostrEvent, env)}
+        self.wire_client.send(peer, self.host._msg('amend', amend_body,
+                                                    did_nostr(peer)), stored=True)
+        for cb in self.on_grant_issued:
+            cb(peer, cause, env['id'], tier)
+        return {'envelope': cast(NostrEvent, env), 'payload': grant, 'published': published, 'cause': cause}
+
+    def decide(
+        self,
+        peer: str,
+        payload: Mapping[str, Any],
+        reason: str,
+        severity: Optional[str],
+        decided_epoch: int,
+    ) -> PeeringDecision:
+        """Decide a grant now and let it take effect at the next boundary.
+
+        An amend inside a window makes the two ends name different grants for
+        the rest of it: the subject's receipts still cite the grant it holds,
+        the issuer has moved on, and every one is refused as naming a grant
+        that did not govern that window. The window then closes on a claim one
+        receipt short of what was measured, which is divergence, which is an S2
+        against a node that did nothing wrong.
+
+        So a decision is written down and published at the boundary. The store
+        keeps one pending grant per peer and a later decision replaces an
+        earlier one, which is how an operator's word outranks the ladder's
+        without either having to know about the other.
+        """
+        self.grants.put_pending(peer, payload, reason, severity, decided_epoch)
+        return {'payload': payload, 'effective_from': decided_epoch + 1}
+
+    # ---- the compartment contract -------------------------------------------------
+    def tick(self, now: int) -> list[tuple[Any, ...]]:
+        return self.reconcile(now)
+
+    def state(self) -> PeeringStateReport:
+        return {
+            'peers': len(self.grants.peers()),
+            'reconciled': {p[:16]: at for p, at in self._reconciled.items()},
+            'refused': self.refusals.total(),
+            # Peers that proposed from a different schema than this build. Not
+            # a fault - they peer on what we share - but a mesh on several
+            # schemas is something an operator should see, so it is here and
+            # in trouble().
+            'digest_mismatch': {p[:16]: d[:16] for p, d in self.host.digest_mismatch.items()},
+        }
+
+    def trouble(self) -> list[str]:
+        out: list[str] = []
+        recent = self.refusals.within(self.TROUBLE_WINDOW, self.clock(), kind='amend')
+        if recent:
+            out.append('%d amend(s) could not be acted on: %s. The two ends will name different '
+                       'grants until a reconcile fixes it'
+                       % (len(recent), '; '.join(sorted({r.why for r in recent}))[:120]))
+        drift = self.host.digest_mismatch
+        if drift:
+            out.append('%d peer(s) were built from another schema (%s): peering holds on the protocols '
+                       'shared with each; `meshnode peers` names them' % (
+                           len(drift), ', '.join(sorted({d[:8] for d in drift.values()}))))
+        return out
+
+    def _take_received(
+        self,
+        envelope_id: Optional[str],
+        issuer_pk: str,
+        envelope_event: Optional[Mapping[str, Any]] = None,
+    ) -> GrantPayload:
+        """Read the grant this issuer now publishes for us, and keep it.
+
+        Two things this must not do. It must not record the id an amend named
+        while holding a different envelope's payload, which is how the two came
+        to disagree about the tier in force. And it must not move backwards:
+        amends can arrive out of order and a grant is only superseded forwards,
+        so an envelope older than the one already held is left alone.
+        """
+        env: Mapping[str, Any]
+        if envelope_event is not None and (envelope_id is None or envelope_event.get('id') == envelope_id):
+            env = envelope_event
+        else:
+            env = self._fetch_envelope(envelope_id, issuer_pk)
+        held = self.grants.get(issuer_pk, grants_mod.RECEIVED)
+        if held is not None and held.get('env_created_at') is not None:
+            if (env['created_at'], env['id']) < (held['env_created_at'], held['envelope_id']):
+                return held['payload']
+        if envelope_id is None and held is not None and held['status'] != 'live' and env['created_at'] <= held['updated_at']:
+            # This node zeroed the grant it held, on a terminate or a
+            # revocation, and the issuer republishes nothing when it
+            # terminates: the coordinate goes on naming the grant it ended.
+            # Reading it back on the next reconcile made a terminate undo
+            # itself - the peer that sent one while this node was down saw its
+            # own grant come back live. An envelope no newer than the zero is
+            # the one it ended; only one the issuer made afterwards is a new
+            # grant, and that is a new peering, which `propose` begins - and a
+            # handshake names its envelope, so this blind read is never it.
+            return held['payload']
+        grant = open_envelope(env, self.ks.node_sk)
+        self.grants.put(issuer_pk, grants_mod.RECEIVED, grant, env['id'], self.clock(),
+                        env_created_at=env['created_at'], event=env)
+        return grant
+

node/planes/peering/peering/envelope.py

@@ -0,0 +1,142 @@
+"""The kind 30801 grant envelope: how one is written and signed (WireNode)
+and how the subject opens and checks one (open_envelope). Pure protocol;
+nothing here knows about the transport, the store or the node."""
+from __future__ import annotations
+
+import json
+import threading
+import time
+from typing import Any, Callable, Mapping, Optional, cast
+
+from fleetmesh_core.crypto import crypto, nip44
+from fleetmesh_core.identity import identity
+from fleetmesh_core.peering import peering
+from fleetmesh_core.storage import store
+from fleetmesh_core.wire import schema_files
+from fleetmesh_core.wire.interfaces import GrantPayload, NostrEvent
+
+GRANT_KIND: int = 30801
+
+# What may cause a grant to change, read from the schema rather than written
+# out again here. Three call sites each spelled their own cause as a bare
+# string; all three happened to be right, and nothing would have said so if one
+# were not. The subject's rules turn on this word - only `remedy` is adverse -
+# so a typo would file a fault against an honest issuer, or hide a real one.
+_SCHEMA: str = schema_files.schema_path('didcomm', 'peering', 'amend.schema.json')
+with open(_SCHEMA, encoding='utf-8') as _f:
+    CAUSES: tuple[str, ...] = tuple(json.load(_f)['properties']['body']['properties']['cause']['enum'])
+
+
+class PeeringError(Exception):
+    pass
+
+
+class GrantUnpublished(PeeringError):
+    """No relay would take the envelope, so the grant was not recorded.
+
+    The envelope IS the grant: the subject fetches it by id, opens it with the
+    conversation key and checks the commitment. An issuer that records a grant
+    whose envelope reached no relay has written down a decision the subject can
+    never read, and will then refuse every receipt that names the grant the
+    subject still holds - for ever, because nothing retries and nothing says
+    why. So the store is left alone and this is raised instead, naming what
+    each relay said.
+    """
+
+
+# How often a subject re-reads the grant its issuer publishes. An amend usually
+# arrives and this changes nothing; when one does not, this is the whole of what
+# keeps the two ends naming the same grant.
+RECONCILE_EVERY: int = 300
+# How much of the handshake log is kept: the node's own log keeps as many.
+LOG_KEEP: int = 500
+
+
+
+class WireNode(peering.Node):
+    """The reference node with one method made real: the envelope it publishes."""
+
+    def __init__(
+        self,
+        sk_hex: str,
+        descriptor: Any,
+        policy: Optional[Any] = None,
+        node_class: str = 'edge',
+        clock: Optional[Callable[[], int]] = None,
+    ) -> None:
+        super().__init__(sk_hex, descriptor, policy, node_class)
+        self.clock: Callable[[], int] = clock or (lambda: int(time.time()))
+        self.published: list[NostrEvent] = []                       # kind 30801 events awaiting publication
+        self._last_envelope_at: dict[str, int] = {}                 # subject -> created_at of the last one written
+        # The serve thread answers a propose with an offer while the tick
+        # thread's own propose comes back with an accept, and both write a
+        # grant for the same subject. Unlocked, both read the same `last` and
+        # stamped the same second, which is exactly the tie the guard below
+        # exists to prevent; on the rig the relay kept one and the issuer the other.
+        self._envelope_lock = threading.Lock()
+
+    def _publish_envelope(self, subject: str, grant: GrantPayload, now: Optional[int]) -> NostrEvent:
+        """Write and sign the kind 30801 for one grant.
+
+        Every grant to one subject carries the same blinded `d`, so each new one
+        replaces the last at that addressable coordinate - and NIP-01 breaks a
+        created_at tie on the *lower* id, so two grants written in the same
+        second leave the relay holding whichever id sorts first, which is the
+        older one about half the time. The issuer then believes it granted
+        something the subject can never read. A grant is only superseded
+        forwards, so the timestamp moves forwards too.
+        """
+        with self._envelope_lock:
+            now_val = now or self.clock()
+            last = self._last_envelope_at.get(subject)
+            if last is not None and now_val <= last:
+                now_val = last + 1
+            self._last_envelope_at[subject] = now_val
+            return self._write_envelope(subject, grant, now_val)
+
+    def _write_envelope(self, subject: str, grant: GrantPayload, now_val: int) -> NostrEvent:
+        d = identity.grant_tag(self.sk, subject)
+        canon = crypto.canonical(grant)
+        commit = crypto.commit(canon, grant['blinding'])
+        window_s = grant['window']
+        tags = [['d', d], ['commit', commit],
+                ['scheme', peering.CONSTANTS['commitment']['scheme'], 'nip44/2'],
+                ['window', str(window_s)], ['epoch', str(now_val // window_s)],
+                ['expiration', str(now_val + window_s * 24)]]
+        conv = nip44.conversation_key(self.sk, subject)
+        ev = store.make_signed_event(self.sk, now_val, GRANT_KIND, tags, nip44.encrypt(canon.decode(), conv))
+        self.envelopes[subject] = ev
+        self.published.append(ev)
+        return ev
+
+
+def open_envelope(envelope: NostrEvent | Mapping[str, Any], my_sk: str) -> GrantPayload:
+    """The grant inside a kind 30801 addressed to me, verified against its tags.
+
+    Three things must hold: the d tag is the blinded pair identifier I derive
+    myself; the ciphertext opens under the conversation key; and the commit
+    tag opens to the plaintext under the blinding the plaintext carries.
+    """
+    if envelope.get('kind') != GRANT_KIND:
+        raise PeeringError('not a kind 30801')
+    issuer = envelope['pubkey']
+    tags = {t[0]: t for t in envelope.get('tags', []) if t and isinstance(t, (list, tuple))}
+    d_tag = tags.get('d')
+    d_val = d_tag[1] if d_tag and len(d_tag) > 1 else None
+    if not d_val or d_val != identity.grant_tag(my_sk, issuer):
+        raise PeeringError('the d tag is not the pair identifier I derive with this issuer')
+    try:
+        plain = nip44.decrypt(envelope['content'], nip44.conversation_key(my_sk, issuer))
+        grant = json.loads(plain)
+    except (nip44.Nip44Error, ValueError) as e:
+        raise PeeringError('the envelope does not open: %s' % e)
+    if grant.get('subject') != crypto.pubkey(my_sk):
+        raise PeeringError('the grant names another subject')
+    commit_tag = tags.get('commit')
+    commit_val = commit_tag[1] if commit_tag and len(commit_tag) > 1 else None
+    if not commit_val or not crypto.open_commit(commit_val, crypto.canonical(grant), grant.get('blinding', '')):
+        raise PeeringError('the commitment does not open to the grant')
+    # json.loads gives a dict; the three checks above are what makes it a
+    # grant addressed to me. Its keys are node/validate.py's business.
+    return cast(GrantPayload, grant)
+