fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/transport/mediation/leaf.py

@@ -0,0 +1,107 @@
+"""MobileLeafClient: the leaf side. Cold-start mediator discovery over
+kind 11801 descriptors under the operator-independence rule, the
+mediate-request it sends, the grant it records, and the forward it wraps
+an inner envelope in."""
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any, Mapping, Sequence
+
+from fleetmesh_core.wire.interfaces import NostrEvent
+from fleetmesh_core.wire.wire_types import ForwardBody, Message
+from node import keystore
+from .messages import make_forward, make_mediate_request
+
+
+from .types import MediationGrantInfo
+
+
+class MobileLeafClient:
+    """Mobile Leaf client implementing mediation negotiation and cold-start discovery."""
+
+    def __init__(self, ks: keystore.Keystore) -> None:
+        self.ks: keystore.Keystore = ks
+        self.did: str = f"did:nostr:{ks.node_pk}"
+        self.mediators: dict[str, MediationGrantInfo] = {}  # mediator_did -> grant info
+
+    @staticmethod
+    def discover_mediators(
+        descriptors: Sequence[NostrEvent],
+        required_count: int = 2,
+        require_distinct_operators: bool = True,
+    ) -> list[NostrEvent]:
+        """Select independent mediator anchors per 3-Layer Operator Independence Model.
+
+        Spec reference: spec.html lines 3332-3348 (Cold-Start Mediator Discovery via NIP-66).
+        Filters for:
+        1. Descriptor carries ['c', 'mediator'] capability hint.
+        2. Carries WebSocket endpoint (wss:// or ws://).
+        3. Selected anchors have distinct 'operator' pubkeys.
+        """
+        candidates: list[NostrEvent] = []
+        for ev in descriptors:
+            if ev.get('kind') != 11801:
+                continue
+            tags = ev.get('tags', [])
+            tag_map = {t[0]: [row[1:] for row in tags if row and row[0] == t[0]] for t in tags if t}
+
+            # Check mediator capability
+            c_tags = [c[0] for c in tag_map.get('c', []) if c]
+            if 'mediator' not in c_tags:
+                continue
+
+            # Check endpoint
+            eps = tag_map.get('endpoint', [])
+            has_ws = any(e and e[0] in ('wss', 'ws') for e in eps)
+            if not has_ws:
+                continue
+
+            candidates.append(ev)
+
+        # Select independent anchors by operator
+        selected: list[NostrEvent] = []
+        seen_operators: set[str] = set()
+
+        for cand in candidates:
+            # The comprehension above builds a different map (tag -> rows), so
+            # this one gets its own name rather than reusing `tags`.
+            first_values = {t[0]: t[1] for t in cand.get('tags', []) if len(t) > 1}
+            op = first_values.get('operator') or cand.get('pubkey')
+
+            if require_distinct_operators and op in seen_operators:
+                continue
+
+            seen_operators.add(op)
+            selected.append(cand)
+            if len(selected) >= required_count:
+                break
+
+        return selected
+
+    def build_mediate_request(self, mediator_did: str) -> Message[Mapping[str, Any]]:
+        return make_mediate_request(self.did, mediator_did)
+
+    def record_mediation_grant(self, grant_msg: Mapping[str, Any]) -> None:
+        med_did = grant_msg.get('from', '')
+        body = grant_msg.get('body', {})
+        self.mediators[med_did] = {
+            'routing_keys': body.get('routing_keys', []),
+            'endpoint': body.get('endpoint'),
+            'granted_at': int(time.time()),
+        }
+
+    def wrap_forward(self, inner_envelope_json: str, mediator_did: str, recipient_leaf_did: str) -> Message[ForwardBody]:
+        """Wrap an inner encrypted payload into a routing/2.0 forward message."""
+        attachment = {
+            'id': 'att-' + os.urandom(8).hex(),
+            'data': {'json': json.loads(inner_envelope_json) if isinstance(inner_envelope_json, str) else inner_envelope_json},
+        }
+        return make_forward(
+            from_did=self.did,
+            to_did=mediator_did,
+            next_recipient=recipient_leaf_did,
+            attachments=[attachment],
+        )
+

node/planes/transport/mediation/messages.py

@@ -0,0 +1,302 @@
+"""The wire: PIURIs, bounds, the two guards every handler shares, and the
+constructors for every coordinate-mediation/2.0, routing/2.0 and
+messagepickup/2.0 message this node sends.
+
+Nothing here touches storage or the node; it is the vocabulary the service
+and the leaf client both speak.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping, Optional, Sequence
+
+from fleetmesh_core.wire.wire_types import (
+    ForwardBody, KeylistUpdateBody, KeylistUpdateResponseBody, MediateDenyBody, MediateGrantBody,
+    Message, PickupDeliveryBody, PickupDeliveryRequestBody, PickupMessagesReceivedBody, PickupStatusBody,
+    PickupStatusRequestBody,
+)
+
+# Protocol PIURIs
+MEDIATE_REQUEST = 'https://didcomm.org/coordinate-mediation/2.0/mediate-request'
+MEDIATE_GRANT = 'https://didcomm.org/coordinate-mediation/2.0/mediate-grant'
+MEDIATE_DENY = 'https://didcomm.org/coordinate-mediation/2.0/mediate-deny'
+KEYLIST_UPDATE = 'https://didcomm.org/coordinate-mediation/2.0/keylist-update'
+KEYLIST_UPDATE_RESPONSE = 'https://didcomm.org/coordinate-mediation/2.0/keylist-update-response'
+KEYLIST_QUERY = 'https://didcomm.org/coordinate-mediation/2.0/keylist-query'
+KEYLIST_RESPONSE = 'https://didcomm.org/coordinate-mediation/2.0/keylist-response'
+
+ROUTING_FORWARD = 'https://didcomm.org/routing/2.0/forward'
+
+PICKUP_STATUS_REQUEST = 'https://didcomm.org/messagepickup/2.0/status-request'
+PICKUP_STATUS = 'https://didcomm.org/messagepickup/2.0/status'
+PICKUP_DELIVERY_REQUEST = 'https://didcomm.org/messagepickup/2.0/delivery-request'
+PICKUP_DELIVERY = 'https://didcomm.org/messagepickup/2.0/delivery'
+PICKUP_MESSAGES_RECEIVED = 'https://didcomm.org/messagepickup/2.0/messages-received'
+
+# The prefixes the Mediation subsystem takes off the ProtocolRouter.
+PIURIS = (
+    'https://didcomm.org/coordinate-mediation/2.0',
+    'https://didcomm.org/routing/2.0',
+    'https://didcomm.org/messagepickup/2.0',
+)
+
+# Bounds on one pickup delivery-request. `limit` is the leaf's own number and
+# was taken as sent: 0 or a negative number is a LIMIT SQLite reads as "no
+# limit", and a huge one is the whole inbox serialised into one reply. One
+# drain per request, between one message and this many.
+PICKUP_LIMIT_MIN: int = 1
+PICKUP_LIMIT_MAX: int = 100
+PICKUP_LIMIT_DEFAULT: int = 10
+
+
+def clamp_pickup_limit(raw: Any) -> int:
+    """`limit` from a delivery-request as an int in [PICKUP_LIMIT_MIN, PICKUP_LIMIT_MAX]."""
+    try:
+        n = int(raw)
+    except (TypeError, ValueError):
+        n = PICKUP_LIMIT_DEFAULT
+    if isinstance(raw, bool):
+        n = PICKUP_LIMIT_DEFAULT
+    return max(PICKUP_LIMIT_MIN, min(PICKUP_LIMIT_MAX, n))
+
+
+def leaf_of(msg: Mapping[str, Any], sender: Optional[str]) -> str:
+    """The DID a mediation message is acting for.
+
+    `msg['from']` is a plaintext field the sender wrote. On its own it is a
+    claim, and every mediation handler used it as the identity: a leaf that
+    wrote another leaf's DID into `from` drained that leaf's inbox and
+    rewrote its keylist. The authenticated identity is the authcrypt `skid`
+    of the envelope the message arrived in, which the transport layer hands
+    down as `sender`. When it is given, `from` must agree with it; when it is
+    not (an operator command, a test), `from` is all there is and is used.
+    """
+    claimed = msg.get('from', '') or ''
+    if sender:
+        if claimed and claimed != sender:
+            raise PermissionError('message from %s claims to be from %s' % (sender, claimed))
+        return sender
+    return claimed
+
+
+# ---------------------------------------------------------------------------
+# Message Constructors
+# ---------------------------------------------------------------------------
+
+def make_mediate_request(
+    from_did: str,
+    to_did: str,
+    thid: Optional[str] = None,
+) -> Message[Mapping[str, Any]]:
+    msg_id = 'med-req-' + os.urandom(8).hex()
+    msg: Message[Mapping[str, Any]] = {
+        'id': msg_id,
+        'type': MEDIATE_REQUEST,
+        'from': from_did,
+        'to': [to_did],
+        'thid': thid or msg_id,
+        'body': {},
+    }
+    return msg
+
+
+def make_mediate_grant(
+    from_did: str,
+    to_did: str,
+    routing_keys: Sequence[str],
+    endpoint: Optional[str] = None,
+    thid: Optional[str] = None,
+) -> Message[MediateGrantBody]:
+    msg_id = 'med-grant-' + os.urandom(8).hex()
+    body: MediateGrantBody = {'routing_keys': list(routing_keys)}
+    if endpoint:
+        body['endpoint'] = endpoint
+    msg: Message[MediateGrantBody] = {
+        'id': msg_id,
+        'type': MEDIATE_GRANT,
+        'from': from_did,
+        'to': [to_did],
+        'thid': thid or msg_id,
+        'body': body,
+    }
+    return msg
+
+
+def make_mediate_deny(
+    from_did: str,
+    to_did: str,
+    reason: str = 'capacity',
+    thid: Optional[str] = None,
+) -> Message[MediateDenyBody]:
+    msg_id = 'med-deny-' + os.urandom(8).hex()
+    msg: Message[MediateDenyBody] = {
+        'id': msg_id,
+        'type': MEDIATE_DENY,
+        'from': from_did,
+        'to': [to_did],
+        'thid': thid or msg_id,
+        'body': {'reason': reason},
+    }
+    return msg
+
+
+def make_keylist_update(
+    from_did: str,
+    to_did: str,
+    updates: Sequence[Mapping[str, str]],
+    thid: Optional[str] = None,
+) -> Message[KeylistUpdateBody]:
+    msg_id = 'kl-upd-' + os.urandom(8).hex()
+    msg: Message[KeylistUpdateBody] = {
+        'id': msg_id,
+        'type': KEYLIST_UPDATE,
+        'from': from_did,
+        'to': [to_did],
+        'thid': thid or msg_id,
+        'body': {'updates': list(updates)},
+    }
+    return msg
+
+
+def make_keylist_update_response(
+    from_did: str,
+    to_did: str,
+    updated: Sequence[Mapping[str, str]],
+    thid: Optional[str] = None,
+) -> Message[KeylistUpdateResponseBody]:
+    msg_id = 'kl-resp-' + os.urandom(8).hex()
+    msg: Message[KeylistUpdateResponseBody] = {
+        'id': msg_id,
+        'type': KEYLIST_UPDATE_RESPONSE,
+        'from': from_did,
+        'to': [to_did],
+        'thid': thid or msg_id,
+        'body': {'updated': list(updated)},
+    }
+    return msg
+
+
+def make_forward(
+    from_did: str,
+    to_did: str,
+    next_recipient: str,
+    attachments: Sequence[Mapping[str, Any]],
+    thid: Optional[str] = None,
+) -> Message[ForwardBody]:
+    """DIDComm routing/2.0 forward message wrapping an inner encrypted envelope."""
+    msg_id = 'fwd-' + os.urandom(8).hex()
+    msg: Message[ForwardBody] = {
+        'id': msg_id,
+        'type': ROUTING_FORWARD,
+        'from': from_did,
+        'to': [to_did],
+        'thid': thid or msg_id,
+        'body': {'next': next_recipient},
+        'attachments': list(attachments),
+    }
+    return msg
+
+
+def make_pickup_status_request(
+    from_did: str,
+    to_did: str,
+    recipient_key: Optional[str] = None,
+    thid: Optional[str] = None,
+) -> Message[PickupStatusRequestBody]:
+    msg_id = 'pck-req-' + os.urandom(8).hex()
+    body: PickupStatusRequestBody = {}
+    if recipient_key:
+        body['recipient_key'] = recipient_key
+    msg: Message[PickupStatusRequestBody] = {
+        'id': msg_id,
+        'type': PICKUP_STATUS_REQUEST,
+        'from': from_did,
+        'to': [to_did],
+        'thid': thid or msg_id,
+        'body': body,
+    }
+    return msg
+
+
+def make_pickup_status(
+    from_did: str,
+    to_did: str,
+    message_count: int = 0,
+    recipient_key: Optional[str] = None,
+    thid: Optional[str] = None,
+) -> Message[PickupStatusBody]:
+    msg_id = 'pck-stat-' + os.urandom(8).hex()
+    body: PickupStatusBody = {'message_count': message_count}
+    if recipient_key:
+        body['recipient_key'] = recipient_key
+    msg: Message[PickupStatusBody] = {
+        'id': msg_id,
+        'type': PICKUP_STATUS,
+        'from': from_did,
+        'to': [to_did],
+        'thid': thid or msg_id,
+        'body': body,
+    }
+    return msg
+
+
+def make_pickup_delivery_request(
+    from_did: str,
+    to_did: str,
+    limit: int = 10,
+    recipient_key: Optional[str] = None,
+    thid: Optional[str] = None,
+) -> Message[PickupDeliveryRequestBody]:
+    msg_id = 'pck-del-req-' + os.urandom(8).hex()
+    body: PickupDeliveryRequestBody = {'limit': limit}
+    if recipient_key:
+        body['recipient_key'] = recipient_key
+    msg: Message[PickupDeliveryRequestBody] = {
+        'id': msg_id,
+        'type': PICKUP_DELIVERY_REQUEST,
+        'from': from_did,
+        'to': [to_did],
+        'thid': thid or msg_id,
+        'body': body,
+    }
+    return msg
+
+
+def make_pickup_delivery(
+    from_did: str,
+    to_did: str,
+    messages: Sequence[Mapping[str, Any]],
+    recipient_key: Optional[str] = None,
+    thid: Optional[str] = None,
+) -> Message[PickupDeliveryBody]:
+    msg_id = 'pck-del-' + os.urandom(8).hex()
+    body: PickupDeliveryBody = {'messages': list(messages)}
+    if recipient_key:
+        body['recipient_key'] = recipient_key
+    msg: Message[PickupDeliveryBody] = {
+        'id': msg_id,
+        'type': PICKUP_DELIVERY,
+        'from': from_did,
+        'to': [to_did],
+        'thid': thid or msg_id,
+        'body': body,
+    }
+    return msg
+
+
+def make_pickup_messages_received(
+    from_did: str,
+    to_did: str,
+    message_id_list: Sequence[str],
+    thid: Optional[str] = None,
+) -> Message[PickupMessagesReceivedBody]:
+    msg_id = 'pck-ack-' + os.urandom(8).hex()
+    msg: Message[PickupMessagesReceivedBody] = {
+        'id': msg_id,
+        'type': PICKUP_MESSAGES_RECEIVED,
+        'from': from_did,
+        'to': [to_did],
+        'thid': thid or msg_id,
+        'body': {'message_id_list': list(message_id_list)},
+    }
+    return msg

node/planes/transport/mediation/service.py

@@ -0,0 +1,233 @@
+"""MediatorService: the anchor side. Admits leaves, keeps their keylists,
+buffers forwarded envelopes and drains them on pickup, bounded.
+
+Every handler identifies the leaf by `leaf_of(msg, sender)` - the proven
+envelope sender, with `from` allowed only to agree - and acts only on that
+leaf's own keys and inbox. See the docstrings on `_keys_of` and
+`handle_messages_received` for the two cross-leaf reads that rule closed.
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+from fleetmesh_core.wire.wire_types import KeylistUpdateResponseBody, MediateDenyBody, MediateGrantBody, Message, PickupDeliveryBody
+from .messages import (PICKUP_LIMIT_DEFAULT, ROUTING_FORWARD, clamp_pickup_limit, leaf_of,
+                       make_keylist_update_response, make_mediate_deny, make_mediate_grant,
+                       make_pickup_delivery)
+from .store import MediationStore
+
+
+from .types import DeliveredMessage
+
+
+class MediatorService:
+    """Anchor-side mediation and store-and-forward buffer for mobile leaves."""
+
+    def __init__(
+        self,
+        db_path: str = ':memory:',
+        mediator_did: str = '',
+        routing_keys: Optional[Sequence[str]] = None,
+        clock: Optional[Callable[[], int]] = None,
+        max_buffered_messages: int = 1000,
+        db: Optional[Any] = None,
+    ) -> None:
+        self.db_path: str = db_path
+        self.mediator_did: str = mediator_did
+        self.routing_keys: list[str] = list(routing_keys or ([mediator_did + '#agree'] if mediator_did else []))
+        self.clock: Callable[[], int] = clock or (lambda: int(time.time()))
+        self.max_buffered_messages: int = max_buffered_messages
+        self._lock: threading.RLock = threading.RLock()
+        self.db: Any = db if db is not None else MediationStore(db_path)
+
+    def close(self) -> None:
+        """Safely close underlying SQLite persistence."""
+        self.db.close()
+
+    def handle_mediate_request(self, msg: Mapping[str, Any], sender: Optional[str] = None) -> Message[MediateGrantBody] | Message[MediateDenyBody]:
+        """Admit leaf into mediation and grant routing keys.
+
+        `sender` is the authenticated envelope sender (see `leaf_of`)."""
+        leaf_did = leaf_of(msg, sender)
+        if not leaf_did:
+            return make_mediate_deny(self.mediator_did, leaf_did, reason='missing from DID', thid=msg.get('id'))
+
+        now = self.clock()
+        with self.db.transaction() as cur:
+            cur.execute('''
+                INSERT OR REPLACE INTO leaves (leaf_did, admitted_at, status)
+                VALUES (?, ?, 'active')
+            ''', (leaf_did, now))
+            # Automatically register leaf_did as initial recipient_key
+            cur.execute('''
+                INSERT OR REPLACE INTO keylist (recipient_key, leaf_did, registered_at)
+                VALUES (?, ?, ?)
+            ''', (leaf_did, leaf_did, now))
+
+        return make_mediate_grant(
+            from_did=self.mediator_did,
+            to_did=leaf_did,
+            routing_keys=self.routing_keys,
+            thid=msg.get('id'),
+        )
+
+    def handle_keylist_update(self, msg: Mapping[str, Any], sender: Optional[str] = None) -> Message[KeylistUpdateResponseBody]:
+        """Update registered recipient keys for a leaf."""
+        leaf_did = leaf_of(msg, sender)
+        updates = msg.get('body', {}).get('updates', [])
+        updated_out: list[dict[str, str]] = []
+        now = self.clock()
+
+        with self.db.transaction() as cur:
+            for u in updates:
+                key = u.get('recipient_key')
+                action = u.get('action')
+                if not key:
+                    continue
+                if action == 'add':
+                    cur.execute('''
+                        INSERT OR REPLACE INTO keylist (recipient_key, leaf_did, registered_at)
+                        VALUES (?, ?, ?)
+                    ''', (key, leaf_did, now))
+                    updated_out.append({'recipient_key': key, 'action': 'add', 'result': 'success'})
+                elif action == 'remove':
+                    cur_res = cur.execute('''
+                        DELETE FROM keylist WHERE recipient_key = ? AND leaf_did = ?
+                    ''', (key, leaf_did))
+                    res = 'success' if cur_res.rowcount > 0 else 'no_change'
+                    updated_out.append({'recipient_key': key, 'action': 'remove', 'result': res})
+
+        return make_keylist_update_response(
+            from_did=self.mediator_did,
+            to_did=leaf_did,
+            updated=updated_out,
+            thid=msg.get('id'),
+        )
+
+    def handle_forward(self, msg: Mapping[str, Any]) -> bool:
+        """Buffer inbound forward envelope for delivery to leaf."""
+        if msg.get('type') != ROUTING_FORWARD:
+            return False
+
+        next_recipient = msg.get('body', {}).get('next', '')
+        if not next_recipient:
+            return False
+
+        # Find registered leaf and verify queue bound
+        with self.db.transaction() as cur:
+            cur.execute('SELECT leaf_did FROM keylist WHERE recipient_key = ?', (next_recipient,))
+            row = cur.fetchone()
+            if not row:
+                # Check if next_recipient is an admitted leaf_did directly
+                cur.execute('SELECT leaf_did FROM leaves WHERE leaf_did = ?', (next_recipient,))
+                leaf_row = cur.fetchone()
+                if not leaf_row:
+                    return False
+
+            # Bound queue to avoid memory/storage exhaustion
+            cur.execute('SELECT COUNT(*) FROM inbox WHERE recipient_key = ? AND delivered = 0', (next_recipient,))
+            count_row = cur.fetchone()
+            current_count = int(count_row[0] or 0) if count_row else 0
+            if current_count >= self.max_buffered_messages:
+                return False
+
+            # Store forwarded envelope attachments in inbox
+            attachments = msg.get('attachments', [])
+            payload_str = json.dumps(attachments, sort_keys=True)
+            msg_id = msg.get('id') or ('fwd-store-' + os.urandom(8).hex())
+            now = self.clock()
+
+            cur.execute('''
+                INSERT OR REPLACE INTO inbox (msg_id, recipient_key, sender_did, payload, enqueued_at, delivered)
+                VALUES (?, ?, ?, ?, ?, 0)
+            ''', (msg_id, next_recipient, msg.get('from', ''), payload_str, now))
+
+        return True
+
+    def get_queue_status(self, recipient_key: str) -> int:
+        row = self.db._one('SELECT COUNT(*) FROM inbox WHERE recipient_key = ? AND delivered = 0', (recipient_key,))
+        return int(row[0] or 0) if row else 0
+
+    def _keys_of(self, leaf_did: str) -> list[str]:
+        """Every recipient_key registered to this leaf, and nothing else.
+
+        The leaf's own DID is here only because mediate-request registered it.
+        A `recipient_key` a leaf merely names in a request is NOT added, which
+        is what let one leaf ask for another leaf's messages."""
+        return [r[0] for r in self.db._all('SELECT recipient_key FROM keylist WHERE leaf_did = ?', (leaf_did,))]
+
+    def handle_pickup_delivery_request(self, msg: Mapping[str, Any], sender: Optional[str] = None) -> Message[PickupDeliveryBody]:
+        """Drain queued forwarded envelopes for the requesting leaf."""
+        leaf_did = leaf_of(msg, sender)
+        limit = clamp_pickup_limit(msg.get('body', {}).get('limit', PICKUP_LIMIT_DEFAULT))
+        target_key = msg.get('body', {}).get('recipient_key') or leaf_did
+
+        messages_out: list[DeliveredMessage] = []
+        with self.db._lock:
+            keys = self._keys_of(leaf_did)
+            if target_key in keys:
+                keys = [target_key]            # a named key narrows the drain to that key
+            if not keys:
+                return make_pickup_delivery(from_did=self.mediator_did, to_did=leaf_did, messages=[],
+                                            recipient_key=target_key, thid=msg.get('id'))
+
+            placeholders = ','.join('?' for _ in keys)
+            rows = self.db._all(f'''
+                SELECT msg_id, recipient_key, sender_did, payload, enqueued_at
+                FROM inbox WHERE recipient_key IN ({placeholders}) AND delivered = 0
+                ORDER BY enqueued_at ASC LIMIT ?
+            ''', (*keys, limit))
+
+            for mid, rk, sender, payload_str, enq in rows:
+                try:
+                    attachments = json.loads(payload_str)
+                except Exception:
+                    attachments = []
+                messages_out.append({
+                    'id': mid,
+                    'recipient_key': rk,
+                    'sender': sender,
+                    'attachments': attachments,
+                    'enqueued_at': enq,
+                })
+
+        return make_pickup_delivery(
+            from_did=self.mediator_did,
+            to_did=leaf_did,
+            messages=messages_out,
+            recipient_key=target_key,
+            thid=msg.get('id'),
+        )
+
+    def handle_messages_received(self, msg: Mapping[str, Any], sender: Optional[str] = None) -> int:
+        """Mark picked-up messages as delivered and purge.
+
+        Only messages addressed to one of THIS leaf's registered keys are
+        purged. The DELETE was by msg_id alone, so a leaf that learned or
+        guessed another leaf's message ids could destroy that leaf's mail."""
+        leaf_did = leaf_of(msg, sender)
+        mids = [m for m in msg.get('body', {}).get('message_id_list', []) if isinstance(m, str)]
+        if not mids:
+            return 0
+
+        with self.db.transaction() as cur:
+            keys = [r[0] for r in cur.execute('SELECT recipient_key FROM keylist WHERE leaf_did = ?',
+                                              (leaf_did,)).fetchall()]
+            if not keys:
+                return 0
+            purged = 0
+            # Chunked so a long ack cannot exceed SQLite's bound-variable limit.
+            step = 400
+            for i in range(0, len(mids), step):
+                chunk = mids[i:i + step]
+                cur_del = cur.execute(f'''
+                    DELETE FROM inbox WHERE msg_id IN ({','.join('?' for _ in chunk)})
+                      AND recipient_key IN ({','.join('?' for _ in keys)})
+                ''', (*chunk, *keys))
+                purged += cur_del.rowcount
+            return purged
+

node/planes/transport/mediation/store.py

@@ -0,0 +1,37 @@
+"""SQLite persistence for mediation: admitted leaves, their keylists, and
+the buffered inbox a leaf drains on pickup."""
+from __future__ import annotations
+
+from node.compartment.schema import Column, Index, Table
+from node.storage import SqliteStore
+
+
+class MediationStore(SqliteStore):
+    """Thread-safe SQLite store for mediation leaves, keylists, and buffered inboxes."""
+
+    SCHEMA = (
+        Table('leaves', (
+            Column('leaf_did', 'TEXT', primary_key=True),
+            Column('admitted_at', 'INTEGER', not_null=True),
+            Column('status', 'TEXT', not_null=True, default="'active'"),
+        )),
+        Table('keylist', (
+            Column('recipient_key', 'TEXT', primary_key=True),
+            Column('leaf_did', 'TEXT', not_null=True),
+            Column('registered_at', 'INTEGER', not_null=True),
+        ), indices=(
+            Index('idx_keylist_leaf', ('leaf_did',)),
+        )),
+        Table('inbox', (
+            Column('msg_id', 'TEXT', primary_key=True),
+            Column('recipient_key', 'TEXT', not_null=True),
+            Column('sender_did', 'TEXT'),
+            Column('payload', 'TEXT', not_null=True),
+            Column('enqueued_at', 'INTEGER', not_null=True),
+            Column('delivered', 'INTEGER', not_null=True, default=0),
+        ), indices=(
+            Index('idx_inbox_recip', ('recipient_key', 'delivered')),
+        )),
+    )
+
+