fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/transport/link/compartment.py

@@ -0,0 +1,257 @@
+"""The relay links this node holds open, as a compartment.
+
+The transport keeps the sockets and counts what it drops. Nothing watched it:
+the tick read `transport.health` directly to decide what to say to the journal,
+and `health()` read six more of its counters by name. A subscription that
+dropped was therefore visible in two hand-written places and in no refusal
+channel at all, so `meshnode refusals` - the one view that answers "what has
+this node been saying no to" - could not show a relay that had been refusing
+this node for an hour.
+
+This compartment owns what the journal has already been told, so it says a
+transition once and not once a tick, and it records the drop as a refusal like
+every other no.
+
+It also records the transport's verdicts on stored messages. A kind 1059 the
+relay accepted and never served used to be indistinguishable from one that
+arrived; now every stored message asks for an acknowledgment, and a peer that
+has spoken since and not acknowledged is a `stored: unacknowledged` refusal
+here, with the message type and the relays it went through, so `meshnode
+refusals` can show the day the control plane went quiet.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from node.compartment import stores as st
+from node.channels import Channel, NOTE, TROUBLE
+from node.compartment import Command, Compartment, Need
+from node.metrics import COUNTER, Metric
+from node.interfaces import AwaitingAckRow
+from node.transport.ladder import Fault
+from node.transport.relay_rung.cooldown import Cooling
+
+
+from node.config import TransportConfig
+from .types import LinkState
+
+
+class Link(Compartment):
+
+    name: str = 'link'
+    reads: tuple[str, ...] = ('transport',)
+    config_cls = TransportConfig
+    # strain is constructed before link so a reconnect can be recorded into it,
+    # but ticks after link (the journal first); it is bound, not required.
+    requires: tuple[str, ...] = ()
+    NEEDS = (
+        Need('transport'),
+        Need('strain', late=True),
+    )
+    COMMANDS = (
+        Command(
+            key='show',
+            name='Link',
+            description='every relay subscription, what it has dropped, what is waiting to be '
+                        'read, and the stored messages still waiting to be acknowledged',
+            tags=('link', 'status'),
+            permission='link/show',
+            run='state',
+            reply='{relays, dropped, recent_faults, publish_refused_in_window, cooling, inbox, '
+                  'wraps_in, wraps_seen_again, unfinished_envelopes, awaiting_ack, acked, '
+                  'acks_in, acks_out, unacknowledged}',
+        ),
+    )
+    STORES = (
+        st.Store(key='_up', description='last reported connection state per relay url',
+                 kind=st.TABLE, shape=bool, bound=1024, keyed_by='url', evict=st.LRU),
+        st.Store(key='_said', description='last reported unreachable reason per relay url',
+                 kind=st.TABLE, bound=1024, keyed_by='url', evict=st.LRU),
+        st.Store(key='_ack', description='last reported subscription-acknowledged state per relay url',
+                 kind=st.TABLE, shape=bool, bound=1024, keyed_by='url', evict=st.LRU),
+    )
+    CHANNELS = (
+        Channel('relay_up', 'Relay subscription connected', say='relay {url} subscription up'),
+        Channel('relay_down', 'Relay subscription disconnected', level=TROUBLE,
+                say='relay {url} subscription down ({reason}), reconnecting'),
+        Channel('relay_unreachable', 'Relay not reachable', level=TROUBLE,
+                say='relay {url} not reachable ({reason}), retrying'),
+        Channel('unacknowledged', 'Stored message was never acknowledged', level=NOTE,
+                say='stored {peer} {type} never acknowledged; the peer has spoken since via {relays}'),
+        Channel('relay_deaf', 'Relay holds the socket but never acknowledged the subscription',
+                level=TROUBLE,
+                say='relay {url} took the subscription and never acknowledged it ({reason})'),
+        Channel('relay_acked', 'Relay acknowledged the subscription',
+                say='relay {url} acknowledged the subscription'),
+    )
+    METRICS = (
+        Metric(name='link_relays_connected', description='Times a relay connection came up.',
+               kind=COUNTER, counts='relay_up', tags=('link', 'relay')),
+        Metric(name='link_relays_dropped', description='Times a relay connection dropped.',
+               kind=COUNTER, counts='relay_down', tags=('link', 'relay')),
+        Metric(name='link_relays_unreachable', description='Times a relay was unreachable.',
+               kind=COUNTER, counts='relay_unreachable', tags=('link', 'relay')),
+        Metric(name='link_unacknowledged', description='Times a stored message was unacknowledged.',
+               kind=COUNTER, counts='unacknowledged', tags=('link', 'transport')),
+    )
+
+    def bind(self, strain: Any) -> None:
+        """The ledger a reconnect is recorded into. Bound after both exist
+        because strain ticks after link and the assembler builds in tick order."""
+        self.strain = strain
+
+    def __init__(
+        self,
+        transport: Any,
+        strain: Optional[Any] = None,
+        clock: Optional[Callable[[], int]] = None,
+        node: Optional[Any] = None,
+    ) -> None:
+        super().__init__(node, clock)
+        self.transport: Any = transport
+        self.strain = strain
+        self._up: st.Table[str, bool]        # url -> the connected state the journal was last told
+        self._said: st.Table[str, Optional[str]]      # url -> the last unreachable reason the journal was told
+        self._ack: st.Table[str, bool]       # url -> the acknowledged state the journal was last told
+
+    def tick(self, now: int) -> list[tuple[Any, ...]]:
+        """Say what changed, once each way it changed.
+
+        A relay that is down stays down, and saying so every thirty seconds
+        buries everything else in the journal. A transition is news; a state
+        is not.
+        """
+        for url, h in self.transport.health.items():
+            prev = self._up.get(url)
+            if h['connected'] and prev is not True:
+                self.say('relay_up', url=url)
+            elif not h['connected'] and prev is True:
+                self.say('relay_down', url=url, reason=h['last_error'] or 'no reason')
+                self.refusals.refuse('subscription', 'dropped', subject=url,
+                                     detail={'error': h['last_error']}, at=now)
+                self._said[url] = h['last_error']    # the next tick must not say the same reason again
+                if self.strain is not None:
+                    self.strain.record('reconnect', transport=url)
+            elif not h['connected'] and h['last_error'] and self._said.get(url) != h['last_error']:
+                self.say('relay_unreachable', url=url, reason=h['last_error'])
+                self._said[url] = h['last_error']
+                self.refusals.refuse('subscription', 'not reachable', subject=url,
+                                     detail={'error': h['last_error']}, at=now)
+            # `connected` is the socket; `confirmed` is the relay's own EOSE.
+            # A relay that holds the socket and never acknowledges carries no
+            # events to us, so the inbox is deaf - and every branch above keys
+            # off `connected`, which is True, so the journal said 'subscription
+            # up' and nothing further (audit I13). Said on transition, like
+            # `connected`; trouble() is what covers a run that is never
+            # acknowledged at all, because that run has no transition to say.
+            if h['connected']:
+                was = self._ack.get(url)
+                acked = bool(h.get('confirmed'))
+                if acked and was is not True:
+                    self.say('relay_acked', url=url)
+                elif not acked and was is True:
+                    self.say('relay_deaf', url=url, reason=h['last_error'] or 'no EOSE')
+                self._ack[url] = acked
+            self._up[url] = h['connected']
+        out: list[tuple[Any, ...]] = []
+        self.transport.sweep(now)
+        for v in self.transport.take_unacked():
+            if v['verdict'] != 'unacknowledged':
+                continue           # expired: nothing could arrive any more, and nobody was heard
+            self.say('unacknowledged', peer=v['peer'][:16], type=v['type'], relays=', '.join(v['relays']) or 'no relay')
+            self.refusals.refuse('stored', 'unacknowledged', subject=v['peer'],
+                                 detail={'type': v['type'], 'sent_at': v['at'], 'heard_at': v['heard_at'],
+                                         'relays': v['relays'], 'mid': v['mid'][:16]}, at=now)
+            out.append(('unacknowledged', v['peer'], v['type']))
+        return out
+
+    FAULTS_SHOWN: int = 20
+
+    def _faults(self, since: Optional[int] = None) -> list[Fault]:
+        recent = getattr(self.transport, 'recent_faults', None)
+        if recent is None:          # a transport without a fault log: nothing to read
+            return []
+        return list(recent(since))
+
+    def _cooling(self) -> dict[str, Cooling]:
+        cd = self.transport.cooldown
+        return cd.state() if cd is not None else {}
+
+    def publish_refused(self, now: Optional[int] = None) -> list[Fault]:
+        """Wraps a relay refused within TROUBLE_WINDOW: the fault the OK
+        reports and nothing else shows, because a refused wrap is counted
+        as sent by the caller that published it."""
+        at = self.clock() if now is None else now
+        return [f for f in self._faults(at - self.TROUBLE_WINDOW)
+                if f['reason'].split(':', 1)[0] == 'publish refused']
+
+    def state(self) -> LinkState:
+        t = self.transport
+        return LinkState(
+            relays={url: dict(h) for url, h in t.health.items()},      # type: ignore[misc]
+            rungs=dict(t.rung_health()) if hasattr(t, 'rung_health') else {},
+            dropped=dict(t.drop_counts),
+            recent_faults=list(reversed(self._faults()))[:self.FAULTS_SHOWN],
+            publish_refused_in_window=len(self.publish_refused()),
+            cooling=self._cooling(),
+            inbox=t.inbox.qsize(),
+            wraps_in={str(k): v for k, v in t.wraps_in.items()},
+            wraps_seen_again={str(k): v for k, v in t.wraps_seen_again.items()},
+            unfinished_envelopes=t.unfinished(),
+            awaiting_ack=[AwaitingAckRow(peer=e['peer'][:16], type=e['type'], at=e['at'], relays=e['relays'])
+                          for e in list(t.awaiting.values())],
+            acked=dict(t.acked),
+            acks_in=t.acks_in,
+            acks_out=t.acks_out,
+            unacknowledged=[AwaitingAckRow(peer=v['peer'][:16], type=v['type'], at=v['at'],
+                                           heard_at=v['heard_at'], relays=v['relays'])
+                            for v in list(t.unacked) if v['verdict'] == 'unacknowledged'],
+        )
+
+    def notes(self) -> list[str]:
+        cooling = self._cooling()
+        if not cooling:
+            return []
+        # Not wrong in the node, but a relay it is not publishing to; an
+        # operator who sees a quiet relay should know it was asked to stop.
+        return ['%d relay(s) cooling after a rate-limit: %s'
+                % (len(cooling), '; '.join('%s until %d (%s)' % (u, c['until'], c['why'])
+                                            for u, c in sorted(cooling.items())))]
+
+    def trouble(self) -> list[str]:
+        out: list[str] = []
+        down = sorted(u for u, h in self.transport.health.items() if not h['connected'])
+        if down:
+            out.append('relay subscription down: %s' % ', '.join(down))
+        # The deaf inbox. `wait_listening` counts `confirmed`, and app start
+        # warns once on a timeout justifying itself with "`link` will keep
+        # saying so" - which it did not, because every row here read
+        # `connected` instead. A relay that holds the socket and never sends
+        # EOSE is connected, unconfirmed, quiet, and green in health and
+        # `meshctl watch`, while live wraps sent to it are lost: kind 21059 is
+        # ephemeral, so no relay keeps a copy (audit I13).
+        deaf = sorted((u, h['last_error']) for u, h in self.transport.health.items()
+                      if h['connected'] and not h.get('confirmed'))
+        if deaf:
+            out.append('%d relay subscription(s) connected but never acknowledged: %s'
+                       % (len(deaf), '; '.join('%s (%s)' % (u, e or 'no EOSE') for u, e in deaf)))
+        refused = self.publish_refused()
+        if refused:
+            # A relay that takes the subscription and refuses every wrap
+            # looks healthy in every other row: connected, confirmed, quiet.
+            by_relay: dict[str, str] = {}
+            for f in refused:
+                rest = f['reason'].split(':', 1)[1].strip()        # 'wss://relay reason text'
+                url, _, why = rest.partition(' ')
+                by_relay.setdefault(url, why)
+            out.append('%d wrap(s) refused by relays in the last %ds: %s'
+                       % (len(refused), self.TROUBLE_WINDOW,
+                          '; '.join('%s (%s)' % (u, w) for u, w in sorted(by_relay.items()))))
+        recent = self.refusals.within(self.TROUBLE_WINDOW, self.clock(), kind='stored')
+        if recent:
+            # The one fault the publish result cannot show: what was said to
+            # the peer never reached it, and the peer was there to hear it.
+            by = sorted({'%s %s' % ((r.subject or '')[:16], r.detail.get('type', '')) for r in recent})
+            out.append('%d stored message(s) never acknowledged by a peer that has spoken since: %s'
+                       % (len(recent), '; '.join(by)))
+        return out

node/planes/transport/link/types.py

@@ -0,0 +1,27 @@
+"""Types and records for the Link compartment."""
+from __future__ import annotations
+
+from typing import Any, Mapping, TypedDict
+
+from node.interfaces import AwaitingAckRow, RelayHealthRow
+from node.transport.ladder import Fault
+from node.transport.relay_rung.cooldown import Cooling
+
+
+class LinkState(TypedDict):
+    """What `meshnode link show` and the health report say about the relays."""
+    relays: dict[str, RelayHealthRow]
+    rungs: dict[str, Mapping[str, Any]]  # every transport rung's own report, by rung name (nostr, iroh, ...)
+    dropped: dict[str, int]              # fault family -> count, ever across the ladder
+    recent_faults: list[Fault]           # the newest first, FAULTS_SHOWN of them, with reasons
+    publish_refused_in_window: int       # wraps a relay refused within TROUBLE_WINDOW
+    cooling: dict[str, Cooling]          # relays held out of publishing after a rate-limit, until when
+    inbox: int
+    wraps_in: dict[str, int]
+    wraps_seen_again: dict[str, int]
+    unfinished_envelopes: int
+    awaiting_ack: list[AwaitingAckRow]
+    acked: dict[str, int]
+    acks_in: int
+    acks_out: int
+    unacknowledged: list[AwaitingAckRow]

node/planes/transport/mediation/__init__.py

@@ -0,0 +1,45 @@
+"""Mobile Leaf & DIDComm Mediation (`routing/2.0` and `coordinate-mediation/2.0`).
+
+Spec reference: spec.html section "Mediation is how a phone gets an address" and
+"Cold-Start Mediator Discovery via NIP-66" (lines 3313-3348).
+
+Covers:
+1. DIDComm `coordinate-mediation/2.0` protocol (mediate-request, mediate-grant, mediate-deny, keylist-update).
+2. DIDComm `routing/2.0` protocol (forward messages wrapping inner encrypted envelopes).
+3. DIDComm `messagepickup/2.0` protocol (status-request, delivery-request, delivery, messages-received).
+4. `MediatorService`: Anchor mediator buffering store-and-forward envelopes for offline/mobile leaves.
+5. `MobileLeafClient`: Mobile leaf lifecycle, dual-mediation, and NIP-66 cold-start mediator discovery.
+6. `Mediation` Compartment: Wire integration with NodeApp.
+
+Laid out as a package by those seams: messages.py (the wire vocabulary),
+store.py, service.py (the anchor), leaf.py (the phone), compartment.py (the
+compartment). Everything the module used to export is re-exported here.
+"""
+from __future__ import annotations
+
+from .leaf import MobileLeafClient
+from .messages import (KEYLIST_QUERY, KEYLIST_RESPONSE, KEYLIST_UPDATE, KEYLIST_UPDATE_RESPONSE,
+                       MEDIATE_DENY, MEDIATE_GRANT, MEDIATE_REQUEST, PICKUP_DELIVERY,
+                       PICKUP_DELIVERY_REQUEST, PICKUP_LIMIT_DEFAULT, PICKUP_LIMIT_MAX, PICKUP_LIMIT_MIN,
+                       PICKUP_MESSAGES_RECEIVED, PICKUP_STATUS, PICKUP_STATUS_REQUEST, PIURIS,
+                       ROUTING_FORWARD, clamp_pickup_limit, leaf_of, make_forward, make_keylist_update,
+                       make_keylist_update_response, make_mediate_deny, make_mediate_grant,
+                       make_mediate_request, make_pickup_delivery, make_pickup_delivery_request,
+                       make_pickup_messages_received, make_pickup_status, make_pickup_status_request)
+from .service import MediatorService
+from .store import MediationStore
+from .compartment import Mediation
+from .types import DeliveredMessage, MediationGrantInfo
+
+__all__ = [
+    'KEYLIST_QUERY', 'KEYLIST_RESPONSE', 'KEYLIST_UPDATE', 'KEYLIST_UPDATE_RESPONSE',
+    'MEDIATE_DENY', 'MEDIATE_GRANT', 'MEDIATE_REQUEST', 'PICKUP_DELIVERY',
+    'PICKUP_DELIVERY_REQUEST', 'PICKUP_LIMIT_DEFAULT', 'PICKUP_LIMIT_MAX', 'PICKUP_LIMIT_MIN',
+    'PICKUP_MESSAGES_RECEIVED', 'PICKUP_STATUS', 'PICKUP_STATUS_REQUEST', 'PIURIS', 'ROUTING_FORWARD',
+    'clamp_pickup_limit', 'leaf_of', 'make_forward', 'make_keylist_update', 'make_keylist_update_response',
+    'make_mediate_deny', 'make_mediate_grant', 'make_mediate_request', 'make_pickup_delivery',
+    'make_pickup_delivery_request', 'make_pickup_messages_received', 'make_pickup_status',
+    'make_pickup_status_request',
+    'MediationStore', 'MediatorService', 'MobileLeafClient', 'Mediation',
+    'DeliveredMessage', 'MediationGrantInfo',
+]

node/planes/transport/mediation/compartment.py

@@ -0,0 +1,238 @@
+"""The Mediation compartment: the operator commands and the inbound door
+for the three mediation PIURIs, acting for the proven sender."""
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Mapping, Optional
+
+from node import channels as ch_mod
+from node import metrics as mx_mod
+from node.compartment import stores as st
+from node.compartment import Command, Handler, Need, Outbound, WireProtocol
+from node.config import MediationConfig
+from node.config.parameter import Parameter
+from .messages import (KEYLIST_UPDATE, MEDIATE_REQUEST, PICKUP_DELIVERY_REQUEST, PICKUP_MESSAGES_RECEIVED,
+                       PIURIS, ROUTING_FORWARD, make_mediate_request, make_pickup_delivery_request)
+from .service import MediatorService
+from .store import MediationStore
+
+
+class Mediation(WireProtocol):
+    """The mediation compartment of meshnode (routing/2.0 & coordinate-mediation/2.0)."""
+
+    name = 'mediation'
+    piuris: tuple[str, ...] = tuple(PIURIS)
+    OUTBOUND = (
+        Outbound('mediate-grant', doc='grant coordinate-mediation admission and routing keys to leaf'),
+        Outbound('mediate-deny', doc='deny coordinate-mediation admission to leaf'),
+        Outbound('keylist-update-response', doc='acknowledge leaf routing keys updates'),
+        Outbound('delivery', doc='drain queued messages to leaf'),
+        Outbound('status', doc='deliver queue status to leaf'),
+    )
+    reads = ('mediation', 'endpoints', 'relays')
+    config_cls = MediationConfig
+    SCHEMA = MediationStore.SCHEMA
+    STORES = (
+        st.Store(key='handled', description='messages handled by protocol message type',
+                 kind=st.TABLE, shape=int, bound=64, keyed_by='msg_type', evict=st.LRU),
+    )
+    CHANNELS = (
+        ch_mod.Channel('message_forwarded', 'Mediation forward message queued for leaf',
+                       level=ch_mod.INFO, say='forward message queued for recipient {recipient}',
+                       tags=('mediation', 'forward')),
+        ch_mod.Channel('forward_refused', 'Mediation forward message refused or dropped',
+                       level=ch_mod.TROUBLE, say='forward message refused for recipient {recipient}',
+                       tags=('mediation', 'forward')),
+        ch_mod.Channel('mediation_granted', 'Mediation admission granted to leaf',
+                       level=ch_mod.INFO, say='mediation admission granted to {leaf}',
+                       tags=('mediation', 'admission')),
+        ch_mod.Channel('messages_drained', 'Queued messages picked up by leaf',
+                       level=ch_mod.INFO, say='picked up {count} messages for {leaf}',
+                       tags=('mediation', 'pickup')),
+        ch_mod.Channel('sender_unauthenticated', 'Mediation message sender not authenticated',
+                       level=ch_mod.TROUBLE, say='mediation request refused: sender not authenticated',
+                       tags=('mediation', 'security')),
+    )
+    METRICS = (
+        mx_mod.Metric(name='mediation_messages_forwarded', description='Messages buffered for mediated leaves.',
+                      kind=mx_mod.COUNTER, counts='message_forwarded', tags=('mediation', 'forward')),
+        mx_mod.Metric(name='mediation_forward_refused', description='Forward messages refused or dropped.',
+                      kind=mx_mod.COUNTER, counts='forward_refused', tags=('mediation', 'forward')),
+        mx_mod.Metric(name='mediation_admissions_granted', description='Leaves admitted into mediation.',
+                      kind=mx_mod.COUNTER, counts='mediation_granted', tags=('mediation', 'admission')),
+        mx_mod.Metric(name='mediation_messages_drained', description='Batches of messages drained by leaves.',
+                      kind=mx_mod.COUNTER, counts='messages_drained', tags=('mediation', 'pickup')),
+        mx_mod.Metric(name='mediation_unauthenticated', description='Mediation messages from unauthenticated senders.',
+                      kind=mx_mod.COUNTER, counts='sender_unauthenticated', tags=('mediation', 'security')),
+    )
+    HANDLERS = (
+        Handler('forward', run='handle_forward', doc='buffer inbound routing/2.0 forward envelope for mobile leaf'),
+        Handler('mediate-request', run='handle_mediate_request', writes=('mediation',), doc='grant coordinate-mediation admission'),
+        Handler('keylist-update', run='handle_keylist_update', writes=('mediation',), doc='update leaf routing keys'),
+        Handler('delivery-request', run='handle_pickup_delivery_request', reads=('mediation',), doc='drain queued messages for leaf'),
+        Handler('messages-received', run='handle_pickup_messages_received', writes=('mediation',), doc='acknowledge and purge delivered messages'),
+    )
+    COMMANDS = (
+        Command(
+            key='show',
+            name='Mediation Status',
+            description='display active mediated leaves and queue depth',
+            tags=('mediation', 'status'),
+            permission='mediation/show',
+            run='show_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='grant',
+            name='Grant Mediation',
+            description='admit leaf into mediation and grant routing keys',
+            tags=('mediation', 'grant'),
+            parameters=(
+                Parameter(key='leaf', name='leaf', description='did of the leaf to admit', type=str, default='', required=True),
+            ),
+            permission='mediation/grant',
+            run='grant_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='forward',
+            name='Forward Message',
+            description='buffer inbound routing/2.0 forward envelope for mobile leaf',
+            tags=('mediation', 'forward'),
+            parameters=(
+                Parameter(key='message', name='message', description='forward envelope (dict or json string)', type=object, default=dict, required=True),
+            ),
+            permission='mediation/forward',
+            run='forward_cmd',
+            reply='bool',
+        ),
+        Command(
+            key='pickup',
+            name='Pickup Messages',
+            description='drain queued forwarded envelopes for mobile leaf',
+            tags=('mediation', 'pickup'),
+            parameters=(
+                Parameter(key='leaf', name='leaf', description='did of the leaf to drain for', type=str, default='', required=True),
+                Parameter(key='limit', name='limit', description='max envelopes to drain', type=int, default=10, required=False),
+            ),
+            permission='mediation/pickup',
+            run='pickup_cmd',
+            reply='dict',
+        ),
+    )
+
+    DB: str = 'mediation.sqlite'
+    NEEDS = (
+        Need('db_path', path='DB'),
+        Need('mediator_did', 'did'),
+        Need('transport', 'transport'),
+    )
+
+    def __init__(self, node: Any = None, db_path: Optional[str] = None, mediator_did: Optional[str] = None,
+                 clock: Optional[Callable[[], int]] = None, transport: Optional[Any] = None,
+                 db: Optional[Any] = None) -> None:
+        """Built by `from_context` in a node. The bare `Mediation()` and
+        `Mediation(node=fake)` forms the tests use still work: with no path
+        the store is in memory, and with no DID the one on `node.ks` is used
+        if there is one."""
+        if db is None and db_path is not None:
+            from node.storage.adapter import SqliteAdapter
+            db = SqliteAdapter(db_path, schema=self.SCHEMA, clock=clock)
+        super().__init__(node, clock, db=db)
+        # The transport a reply goes back over; off the fake node in the suites.
+        self.transport: Optional[Any] = transport if transport is not None else getattr(node, 'transport', None)
+        self.handled: st.Table[str, int]
+        if mediator_did is None:
+            ks = getattr(node, 'ks', None) if node is not None else None
+            actual_did = 'did:nostr:%s' % ks.node_pk if ks is not None else ''
+        else:
+            actual_did = str(mediator_did)
+        if db_path is not None:
+            self.service: MediatorService = MediatorService(db_path=db_path, mediator_did=actual_did, clock=clock, db=self.db)
+        else:
+            self.service = MediatorService(mediator_did=actual_did, clock=clock, db=self.db)
+
+    def show_cmd(self) -> Mapping[str, Any]:
+        return {
+            'mediator_did': self.service.mediator_did,
+            'routing_keys': self.service.routing_keys,
+        }
+
+    def grant_cmd(self, args: Mapping[str, Any]) -> Any:
+        req = make_mediate_request(from_did=str(args['leaf']), to_did=self.service.mediator_did)
+        return self.service.handle_mediate_request(req)
+
+    def forward_cmd(self, args: Mapping[str, Any]) -> bool:
+        raw = args['message']
+        msg = raw if isinstance(raw, dict) else json.loads(raw)
+        return bool(self.service.handle_forward(msg))
+
+    def pickup_cmd(self, args: Mapping[str, Any]) -> Any:
+        pick = make_pickup_delivery_request(
+            from_did=str(args['leaf']),
+            to_did=self.service.mediator_did,
+            limit=int(args.get('limit') or 10),
+        )
+        return self.service.handle_pickup_delivery_request(pick)
+
+    # ---- the wire ---------------------------------------------------------
+    def handle_forward(self, inbound: Any, sender: str) -> Optional[tuple[Any, ...]]:
+        msg = getattr(inbound, 'message', inbound)
+        if not isinstance(msg, dict) or not isinstance(sender, str) or not sender:
+            return None
+        queued = self.service.handle_forward(msg)
+        self._count(ROUTING_FORWARD)
+        recipient = str(msg.get('body', {}).get('next', ''))[:24]
+        if queued:
+            self.say('message_forwarded', recipient=recipient)
+        else:
+            self.say('forward_refused', recipient=recipient)
+        return ('mediation forward', 'queued' if queued else 'refused', recipient)
+
+    def _handle_authenticated(self, inbound: Any, sender_pk: str, mtype: str, action: Callable[..., Any]) -> Optional[tuple[Any, ...]]:
+        msg = getattr(inbound, 'message', inbound)
+        if not isinstance(msg, dict) or not isinstance(sender_pk, str) or not sender_pk:
+            return None
+        if not getattr(inbound, 'authenticated', False):
+            self._count('unauthenticated')
+            self.say('sender_unauthenticated')
+            return ('mediation refused', mtype.rsplit('/', 1)[-1], 'sender not authenticated')
+        sender = 'did:nostr:' + sender_pk
+        try:
+            reply = action(msg, sender=sender)
+        except PermissionError as e:
+            self._count('impersonation')
+            return ('mediation refused', mtype.rsplit('/', 1)[-1], str(e))
+        self._count(mtype)
+        if mtype == MEDIATE_REQUEST and isinstance(reply, dict) and reply.get('type', '').endswith('mediate-grant'):
+            self.say('mediation_granted', leaf=sender)
+        elif mtype == PICKUP_DELIVERY_REQUEST and isinstance(reply, dict):
+            msgs = reply.get('body', {}).get('messages', [])
+            self.say('messages_drained', count=len(msgs), leaf=sender)
+        if mtype == PICKUP_MESSAGES_RECEIVED:
+            return ('mediation received', sender_pk[:16], reply)
+        if self.transport is not None and isinstance(reply, dict):
+            self.wire_client.send(sender_pk, reply)
+        return ('mediation', mtype.rsplit('/', 1)[-1], sender_pk[:16], str(reply.get('type', ''))[-30:] if isinstance(reply, dict) else '')
+
+    def handle_mediate_request(self, inbound: Any, sender: str) -> Optional[tuple[Any, ...]]:
+        return self._handle_authenticated(inbound, sender, MEDIATE_REQUEST, self.service.handle_mediate_request)
+
+    def handle_keylist_update(self, inbound: Any, sender: str) -> Optional[tuple[Any, ...]]:
+        return self._handle_authenticated(inbound, sender, KEYLIST_UPDATE, self.service.handle_keylist_update)
+
+    def handle_pickup_delivery_request(self, inbound: Any, sender: str) -> Optional[tuple[Any, ...]]:
+        return self._handle_authenticated(inbound, sender, PICKUP_DELIVERY_REQUEST, self.service.handle_pickup_delivery_request)
+
+    def handle_pickup_messages_received(self, inbound: Any, sender: str) -> Optional[tuple[Any, ...]]:
+        return self._handle_authenticated(inbound, sender, PICKUP_MESSAGES_RECEIVED, self.service.handle_messages_received)
+
+    def _count(self, key: str) -> None:
+        self.handled[key] = self.handled.get(key, 0) + 1
+
+    def stop(self) -> None:
+        """Safely close mediation persistence and worker state on shutdown."""
+        if hasattr(self, 'service') and self.service:
+            self.service.close()
+        super().stop()
+