fleetmesh-node 0.2.0__py3-none-any.whl

node/protocols/nostr/client.py

@@ -0,0 +1,377 @@
+"""A nostr relay client: publish an event and wait for its OK, or query.
+
+The only module in the node that speaks the relay wire (REQ/EVENT/OK/EOSE/
+AUTH). Two kinds of caller: the relay rung (node.transport.relay_rung), for
+gift wraps to and from peers, and the control-plane publishers (descriptor,
+presence, discovery, reports), for the node's own signed events. Neither is
+the other's business, so they share this and nothing else.
+
+The node talks to relays for three things: to publish its own descriptor,
+grants and reports; to read other nodes' descriptors; and, as its default
+transport, to send and receive gift wraps. Query collects until EOSE; a
+subscription yields events as they arrive and is how the transport listens.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import socket
+import time
+from typing import Any, Callable, cast, Iterator, Mapping, Optional, Sequence
+
+from node.interfaces import EventLike, NostrEvent, NostrFilter
+from node.transport import ws
+
+log = logging.getLogger(__name__)
+
+
+class RelayError(Exception):
+    pass
+
+
+# A subscription that receives nothing is either quiet or dead, and a socket
+# that was dropped without a close frame looks quiet forever. Past PING_AFTER
+# seconds of silence the client pings; past DEAD_AFTER with no frame back,
+# not even a pong, the subscription is declared dead and the listener
+# reconnects.
+PING_AFTER: float = 60.0
+DEAD_AFTER: float = 150.0
+
+
+class Relay:
+    def __init__(
+        self,
+        url: str,
+        timeout: float = 15.0,
+        auth_signer: Optional[Callable[[str, str], Optional[EventLike]]] = None,
+        ping_after: float = PING_AFTER,
+        dead_after: float = DEAD_AFTER,
+        on_eose: Optional[Callable[[str], None]] = None,
+    ) -> None:
+        self.url: str = url
+        self.timeout: float = timeout
+        # Liveness thresholds are per connection so a test (or an operator
+        # on a flaky link) sets them on the one Relay, not on the module.
+        self.ping_after: float = ping_after
+        self.dead_after: float = dead_after
+        self.auth_signer: Optional[Callable[[str, str], Optional[EventLike]]] = auth_signer
+        self.on_eose: Optional[Callable[[str], None]] = on_eose
+        self.ws: Optional[ws.WebSocket] = None
+        self._n: int = 0
+        self._subs: dict[str, list[NostrFilter | Mapping[str, Any]]] = {}
+        self._pending: dict[str, list[NostrEvent]] = {}    # events read while waiting for an EOSE
+        self._confirmed: set[str] = set()                  # subscriptions the relay answered with an EOSE
+
+    def connect(self) -> Relay:
+        if self.ws is None:
+            # Every way the handshake can fail is one answer to the caller:
+            # the relay is not reachable. ws.connect raises OSError for the
+            # socket (refused, timed out, DNS), ws.ConnectionClosed for a
+            # peer that closed mid-handshake or sent an endless header, and
+            # ConnectionError for a refused upgrade (both are OSError
+            # subclasses; named so a reader need not know that). Callers
+            # that catch RelayError must not see a bare ConnectionClosed.
+            try:
+                self.ws = ws.connect(self.url, self.timeout)
+            except (OSError, ws.ConnectionClosed) as e:
+                raise RelayError('%s: %s: %s' % (self.url, type(e).__name__, e)) from e
+            if hasattr(self.ws.sock, 'settimeout'):
+                self.ws.sock.settimeout(self.timeout)
+        return self
+
+    def close(self) -> None:
+        if self.ws is not None:
+            self.ws.close()
+            self.ws = None
+        self._subs.clear()
+
+    def _send(self, msg: list[Any]) -> None:
+        self.connect()
+        assert self.ws is not None
+        self.ws.send_text(json.dumps(msg, separators=(',', ':')))
+
+    def _recv(self) -> list[Any]:
+        assert self.ws is not None
+        raw = self.ws.recv_text()
+        try:
+            msg = json.loads(raw)
+        except ValueError:
+            raise RelayError('relay sent something that is not JSON')
+        if not isinstance(msg, list) or not msg:
+            raise RelayError('relay sent a malformed message')
+        return msg
+
+    def _handle_auth(self, challenge: str) -> bool:
+        """Sign and send a NIP-42 AUTH message if auth_signer is configured.
+
+        Returns True if an AUTH response was sent.
+        """
+        if self.auth_signer is not None:
+            try:
+                auth_ev = self.auth_signer(self.url, challenge)
+            except Exception:
+                # The signer is caller-supplied code (keystore, HSM, test
+                # stub); a fault in it means "no AUTH", which the caller
+                # sees as the relay refusing the subscription. Logged, since
+                # a broken signer is a bug and not a relay condition.
+                log.exception('relay %s: auth_signer failed', self.url)
+                return False
+            if auth_ev is not None:
+                self._send(['AUTH', auth_ev])
+                return True
+        return False
+
+    def _sub_id(self) -> str:
+        self._n += 1
+        return 'sub-%d-%s' % (self._n, os.urandom(3).hex())
+
+    def publish(self, event: EventLike) -> tuple[bool, str]:
+        """(accepted, message) for one event."""
+        self._send(['EVENT', event])
+        deadline = time.time() + self.timeout
+        authed = False
+        retried = False
+        last_rejected_reason: Optional[str] = None
+        while time.time() < deadline:
+            msg = self._recv()
+            if msg[0] == 'AUTH' and len(msg) > 1 and isinstance(msg[1], str):
+                if self._handle_auth(msg[1]):
+                    authed = True
+                    if last_rejected_reason and 'auth-required' in last_rejected_reason and not retried:
+                        retried = True
+                        self._send(['EVENT', event])
+                continue
+            if msg[0] == 'OK' and len(msg) > 2:
+                if msg[1] == event['id']:
+                    accepted = bool(msg[2])
+                    reason = msg[3] if len(msg) > 3 else ''
+                    if not accepted and 'auth-required' in reason:
+                        last_rejected_reason = reason
+                        if authed and not retried:
+                            retried = True
+                            self._send(['EVENT', event])
+                            continue
+                        if self.auth_signer and not retried:
+                            # Wait for AUTH challenge if one arrives
+                            continue
+                    return accepted, reason
+                # OK for another event (e.g. kind 22242 AUTH response); continue
+                continue
+            if msg[0] == 'NOTICE':
+                return False, 'NOTICE: %s' % (msg[1] if len(msg) > 1 else '')
+        if last_rejected_reason is not None:
+            return False, last_rejected_reason
+        return False, 'no OK within %.0fs' % self.timeout
+
+    def query(self, filters: Sequence[NostrFilter | Mapping[str, Any]], limit_time: Optional[float] = None) -> list[NostrEvent]:
+        """Every stored event matching the filters, until EOSE."""
+        sid = self._sub_id()
+        self._subs[sid] = list(filters)
+        self._send(['REQ', sid] + list(filters))
+        out: list[NostrEvent] = []
+        seen: set[str] = set()
+        deadline = time.time() + (limit_time or self.timeout)
+        authed = False
+        re_requested = False
+        while time.time() < deadline:
+            msg = self._recv()
+            if msg[0] == 'AUTH' and len(msg) > 1 and isinstance(msg[1], str):
+                if self._handle_auth(msg[1]):
+                    authed = True
+                    if not re_requested:
+                        re_requested = True
+                        self._send(['REQ', sid] + self._subs[sid])
+                continue
+            if msg[0] == 'EVENT' and len(msg) > 2 and msg[1] == sid:
+                ev = msg[2]
+                # Anything that is not an object with an id is not an event and
+                # every caller indexes ev['id'], so it is dropped here rather
+                # than crash the first reader.
+                if isinstance(ev, dict) and isinstance(ev.get('id'), str) and ev['id'] not in seen:
+                    seen.add(ev['id'])
+                    # The wire boundary: what a relay serves under EVENT is an
+                    # event by contract, and callers verify the ones they trust.
+                    out.append(cast(NostrEvent, ev))
+            elif msg[0] == 'EOSE' and len(msg) > 1 and msg[1] == sid:
+                if re_requested:
+                    re_requested = False
+                    continue
+                break
+            elif msg[0] == 'CLOSED' and len(msg) > 1 and msg[1] == sid:
+                reason = msg[2] if len(msg) > 2 else ''
+                if 'auth-required' in reason and self.auth_signer and not re_requested:
+                    if authed:
+                        re_requested = True
+                        self._send(['REQ', sid] + self._subs[sid])
+                        continue
+                    try:
+                        next_msg = self._recv()
+                        if next_msg[0] == 'AUTH' and len(next_msg) > 1 and isinstance(next_msg[1], str):
+                            if self._handle_auth(next_msg[1]):
+                                authed = True
+                                re_requested = True
+                                self._send(['REQ', sid] + self._subs[sid])
+                                continue
+                    except (RelayError, ws.ConnectionClosed, OSError) as e:
+                        # The relay closed us after CLOSED without a usable AUTH
+                        # challenge; the RelayError below is the answer either way.
+                        log.debug('relay %s: no AUTH after CLOSED: %s', self.url, e)
+                raise RelayError('relay closed the subscription: %s' % reason)
+        self._send(['CLOSE', sid])
+        self._subs.pop(sid, None)
+        return out
+
+    def subscribe(self, filters: Sequence[NostrFilter | Mapping[str, Any]], ready: bool = False) -> str:
+        """Open a subscription; returns its id. Read with events().
+
+        `ready` waits for the relay's EOSE before returning, which is the only
+        way a caller can know the subscription is registered. Without it this
+        sends REQ and returns, so a caller that subscribes and then causes an
+        event races the server: an ephemeral kind fanned out before the REQ is
+        processed reaches nobody, is never stored, and no timeout on events()
+        can recover it. Stored events that arrive before the EOSE are kept and
+        handed to events() rather than dropped on the floor.
+        """
+        sid = self._sub_id()
+        self._subs[sid] = list(filters)
+        self._send(['REQ', sid] + list(filters))
+        if ready and self._await_eose(sid):
+            self._confirmed.add(sid)
+        return sid
+
+    def confirmed(self, sid: str) -> bool:
+        """True if the relay answered this subscription's REQ with an EOSE.
+
+        Only ever true for a `subscribe(ready=True)`. A caller that waited and
+        did not get one has a socket that is up and a subscription the relay
+        has not owned up to, which is worth saying rather than assuming either
+        way.
+        """
+        return sid in self._confirmed
+
+    def _await_eose(self, sid: str) -> bool:
+        """Read until this subscription's EOSE, buffering what comes first.
+
+        True if the EOSE came. False if the wait ran out, the relay closed the
+        subscription, or the socket went - the three cases where a caller that
+        is about to cause an event must not believe it is being listened to.
+        """
+        deadline = time.time() + self.timeout
+        while time.time() < deadline:
+            try:
+                msg = self._recv()
+            except socket.timeout:
+                continue
+            except (OSError, ws.ConnectionClosed):
+                return False
+            if msg[0] == 'EOSE' and len(msg) > 1 and msg[1] == sid:
+                return True
+            if msg[0] == 'AUTH' and len(msg) > 1 and isinstance(msg[1], str):
+                if self._handle_auth(msg[1]):
+                    self._send(['REQ', sid] + self._subs[sid])
+                continue
+            if msg[0] == 'CLOSED' and len(msg) > 1 and msg[1] == sid:
+                return False
+            if msg[0] == 'EVENT' and len(msg) > 2 and msg[1] == sid:
+                self._pending.setdefault(sid, []).append(msg[2])
+        return False
+
+    def events(self, sid: str, until: Optional[float] = None) -> Iterator[NostrEvent]:
+        """Yield events on a subscription until `until` (a time) or the socket closes."""
+        for held in self._pending.pop(sid, []):
+            yield held                  # arrived before the EOSE `ready` waited for
+        pinged_at: Optional[float] = None
+        authed = False
+        while until is None or time.time() < until:
+            try:
+                msg = self._recv()
+            except socket.timeout:
+                assert self.ws is not None
+                idle = self.ws.idle()
+                if idle > self.dead_after:
+                    raise ws.ConnectionClosed('no frame in %.0fs, not even a pong: the subscription is dead' % idle)
+                if idle > self.ping_after and (pinged_at is None or time.time() - pinged_at > self.ping_after / 2):
+                    try:
+                        self.ws.ping()
+                    except OSError:
+                        return
+                    pinged_at = time.time()
+                continue            # nothing arrived; the subscription is still open
+            except (OSError, ws.ConnectionClosed):
+                return
+            if msg[0] == 'AUTH' and len(msg) > 1 and isinstance(msg[1], str):
+                if self._handle_auth(msg[1]):
+                    authed = True
+                continue
+            if msg[0] == 'CLOSED' and len(msg) > 1 and msg[1] == sid:
+                reason = msg[2] if len(msg) > 2 else ''
+                if 'auth-required' in reason and self.auth_signer and sid in self._subs:
+                    if authed:
+                        self._send(['REQ', sid] + self._subs[sid])
+                        continue
+                    try:
+                        next_msg = self._recv()
+                        if next_msg[0] == 'AUTH' and len(next_msg) > 1 and isinstance(next_msg[1], str):
+                            if self._handle_auth(next_msg[1]):
+                                authed = True
+                                self._send(['REQ', sid] + self._subs[sid])
+                                continue
+                    except (RelayError, ws.ConnectionClosed, OSError) as e:
+                        # Same as query(): CLOSED with no AUTH to answer ends the stream.
+                        log.debug('relay %s: no AUTH after CLOSED: %s', self.url, e)
+                return
+            if msg[0] == 'EOSE' and len(msg) > 1 and msg[1] == sid:
+                self._confirmed.add(sid)
+                if self.on_eose is not None:
+                    self.on_eose(sid)
+                continue
+            if msg[0] == 'EVENT' and len(msg) > 2 and msg[1] == sid and isinstance(msg[2], dict):
+                # The guard used to sit in every consumer; it belongs here,
+                # where the promise of the return type is made.
+                yield cast(NostrEvent, msg[2])
+
+    def unsubscribe(self, sid: str) -> None:
+        self._send(['CLOSE', sid])
+        self._subs.pop(sid, None)
+
+
+def publish_all(
+    urls: Sequence[str],
+    event: EventLike,
+    timeout: float = 15.0,
+    auth_signer: Optional[Callable[[str, str], Optional[EventLike]]] = None,
+) -> dict[str, tuple[bool, str]]:
+    """{url: (accepted, message)}; one failed relay does not stop the others."""
+    out: dict[str, tuple[bool, str]] = {}
+    for url in urls:
+        r = Relay(url, timeout, auth_signer=auth_signer)
+        try:
+            out[url] = r.publish(event)
+        except Exception as e:
+            out[url] = (False, '%s: %s' % (type(e).__name__, e))
+        finally:
+            r.close()
+    return out
+
+
+def query_all(
+    urls: Sequence[str],
+    filters: Sequence[NostrFilter | Mapping[str, Any]],
+    timeout: float = 15.0,
+    auth_signer: Optional[Callable[[str, str], Optional[EventLike]]] = None,
+) -> list[NostrEvent]:
+    """Events from every relay, deduplicated by id."""
+    seen: dict[str, NostrEvent] = {}
+    for url in urls:
+        r = Relay(url, timeout, auth_signer=auth_signer)
+        try:
+            for ev in r.query(filters):
+                seen.setdefault(ev['id'], ev)
+        except (RelayError, ws.ConnectionClosed, OSError) as e:
+            # One relay down must not cost the answers of the others; the
+            # caller asked for the union of what is reachable.
+            log.info('relay %s: query skipped: %s', url, e)
+        finally:
+            r.close()
+    return list(seen.values())

node/protocols/nostr/descriptor.py

@@ -0,0 +1,211 @@
+"""The kind 11801 a node publishes, and the DID document a resolver derives.
+
+Built from the node's keys and its MeshNode manifest: class, endpoints,
+operator, the protocols it implements as c tags, the plain capabilities as
+hints, expiry within the class maximum, and a NIP-13 nonce mined to the
+policy's bits. Every descriptor is run through fleetmesh_core.identity.validate_descriptor
+before it leaves, so this node can never publish what it would decline.
+"""
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any, Mapping, Optional, Sequence, TypedDict
+from fleetmesh_core.crypto import crypto
+from fleetmesh_core.identity import did, identity
+from fleetmesh_core.identity.did import Document as DIDDocument
+from fleetmesh_core.wire import schema_files
+from fleetmesh_core.storage import store  # noqa: E402
+from node.interfaces import EventLike, NostrEvent, TagList
+
+if TYPE_CHECKING:
+    from node.keystore import Keystore
+
+CONSTANTS = identity.CONSTANTS
+DIGEST = schema_files.digest()
+VERSION = schema_files.load_kinds()['version']
+SOFTWARE = (identity.FLEETMESH.rstrip('/'), '0.0.1')   # the project URL, derived and never written down
+KIND: int = 11801
+
+
+def mine(
+    pubkey: str,
+    created_at: int,
+    kind: int,
+    tags: TagList,
+    content: str,
+    bits: int,
+    max_tries: int = 1 << 26,
+) -> tuple[TagList, str]:
+    """Find a NIP-13 nonce so the event id has at least `bits` leading zeros.
+
+    The nonce tag is ['nonce', '<n>', '<target bits>'] and it is the last tag,
+    so everything else about the event is fixed before mining starts.
+    """
+    base = [t for t in tags if t[0] != 'nonce']
+    for n in range(max_tries):
+        trial = base + [['nonce', str(n), str(bits)]]
+        eid = store.event_id(pubkey, created_at, kind, trial, content)
+        if identity.pow_bits(eid) >= bits:
+            return trial, eid
+    raise RuntimeError('no nonce found in %d tries' % max_tries)
+
+
+
+def build(
+    keystore: Keystore,
+    node_class: str,
+    endpoints: Sequence[tuple[str, str, int] | list[Any]],
+    operator_pubkey: str,
+    protocols: Sequence[str],
+    now: Optional[int] = None,
+    capabilities: Sequence[str] = (),
+    mediator: Optional[str] = None,
+    policy: Optional[tuple[str, ...] | list[str]] = None,
+    coverage: Optional[str] = None,
+    nips: Optional[Sequence[int]] = None,
+    lifetime: Optional[int] = None,
+    bits: Optional[int] = None,
+    content: str = '',
+    fips_key: Optional[str] = None,
+    extra_tags: Sequence[Sequence[str]] = (),
+) -> NostrEvent:
+    """A signed kind 11801.
+
+    endpoints: [(scheme, address, preference)]. protocols: the fleetmesh protocol
+    identifiers this node implements; peering/1.0 and budget/1.0 are required
+    of every class and are added if missing. policy: (sha256 hex, url).
+    extra_tags: optional tags a subsystem contributes (mint, price), placed
+    before operator so the fixed tail stays where readers expect it.
+    """
+    now = int(now if now is not None else time.time())
+    cap = CONSTANTS['descriptor']
+    max_life = cap['max_lifetime_seconds_leaf' if node_class == 'leaf' else 'max_lifetime_seconds_anchor_edge']
+    lifetime = min(lifetime or max_life, max_life)
+    bits = cap['default_pow_bits'] if bits is None else bits
+    mk = keystore.multikeys()
+    protos = sorted(set(protocols) | set(identity.REQUIRED_PROTOCOLS))
+    tags: TagList = [
+        ['class', node_class],
+        ['protocol', VERSION, DIGEST],
+        ['software', SOFTWARE[0], SOFTWARE[1]],
+        ['key', 'agreement', mk['agreement']],
+        ['key', 'transport', mk['transport']],
+    ]
+    if fips_key:
+        tags.append(['key', 'fips', fips_key])
+    for scheme, address, pref in sorted(endpoints, key=lambda e: (int(e[2]), e[0])):
+        tags.append(['endpoint', scheme, address, str(pref)])
+    if mediator:
+        tags.append(['mediator', mediator])
+    tags += [['c', p] for p in protos]
+    tags += [['c', c] for c in capabilities]
+    if nips:
+        tags.append(['nips'] + [str(n) for n in nips])
+    if coverage:
+        tags.append(['coverage', coverage])
+    if policy:
+        tags.append(['policy', policy[0]] + ([policy[1]] if len(policy) > 1 and policy[1] else []))
+    for t in extra_tags:
+        tags.append([str(x) for x in t])
+    tags.append(['operator', operator_pubkey])
+    tags.append(['expiration', str(now + lifetime)])
+    if bits:
+        tags, _ = mine(keystore.node_pk, now, KIND, tags, content, bits)
+    ev: NostrEvent = store.make_signed_event(keystore.node_sk, now, KIND, tags, content)
+    problems = identity.validate_descriptor(ev, now=now, digest=DIGEST)
+    if problems:
+        raise ValueError('refusing to publish an invalid descriptor: %s' % '; '.join(problems))
+    return ev
+
+
+class ManifestEndpoint(TypedDict, total=False):
+    transport: str
+    address: str
+    ticket: str
+    priority: int
+
+
+class ManifestOperator(TypedDict, total=False):
+    pubkey: str
+    policyUrl: str
+
+
+ManifestSpecDict = TypedDict('ManifestSpecDict', {
+    'class': str,
+    'endpoints': list[ManifestEndpoint],
+    'capabilities': list[str],
+    'operator': ManifestOperator,
+}, total=False)
+
+
+class MeshNodeManifest(TypedDict, total=False):
+    spec: ManifestSpecDict
+
+
+def from_manifest(
+    keystore: Keystore,
+    manifest: MeshNodeManifest | Mapping[str, Any],
+    now: Optional[int] = None,
+    bits: Optional[int] = None,
+) -> NostrEvent:
+    """A descriptor from a MeshNode manifest (manifests/meshnode-*.yaml, parsed)."""
+    spec = manifest['spec']
+    eps: list[tuple[str, str, int]] = []
+    for e in spec.get('endpoints', []):
+        addr = str(e.get('address') or e.get('ticket') or '')
+        eps.append((str(e.get('transport', '')), addr, int(e.get('priority', 50))))
+    caps = [c for c in spec.get('capabilities', []) if not c.startswith('https://')]
+    protos = [c for c in spec.get('capabilities', []) if c.startswith('https://')]
+    pol = spec.get('operator', {}).get('policyUrl')
+    policy = (crypto.sha256(pol.encode()), pol) if pol else None
+    return build(keystore, spec['class'], eps, spec['operator']['pubkey'], protos, now=now,
+                 capabilities=caps, policy=policy, bits=bits)
+
+
+# ---------------------------------------------------------- resolution ----
+def genuine(desc: Any, pubkey: Optional[str] = None) -> bool:
+    """Signed by its own pubkey, and by the pubkey it was asked for.
+
+    A relay answers a query by author with whatever it chooses to serve under
+    that name. Nothing verified the signature of a resolved descriptor, so a
+    relay could hand a node a descriptor naming an agreement key of the
+    relay's choosing, and every envelope to that peer would then be encrypted
+    to it. The rule for heartbeats already says it: believing an event
+    unsigned lets a relay speak as any peer.
+    """
+    from fleetmesh_core.crypto import giftwrap
+    return (isinstance(desc, dict) and (pubkey is None or desc.get('pubkey') == pubkey)
+            and giftwrap.verify_event(desc))
+
+
+def newest(
+    descriptors: Sequence[NostrEvent | EventLike],
+    now: Optional[int] = None,
+    digest: str = DIGEST,
+    pubkey: Optional[str] = None,
+) -> Optional[NostrEvent]:
+    """The live, genuine descriptor among candidates for one pubkey, or None."""
+    now = int(now if now is not None else time.time())
+    cands = list(descriptors)
+    live = [d for d in cands if genuine(d, pubkey)
+            and not identity.validate_descriptor(d, now=now, digest=digest)]
+    picked = max(live, key=lambda d: int(d['created_at'])) if live else None
+    return picked  # type: ignore[return-value]
+
+
+def resolve(
+    pubkey: str,
+    relay_urls: Sequence[str],
+    now: Optional[int] = None,
+    timeout: float = 15.0,
+) -> Optional[NostrEvent]:
+    """The live kind 11801 for a pubkey from these relays, or None."""
+    from . import client
+    found = client.query_all(relay_urls, [{'kinds': [KIND], 'authors': [pubkey]}], timeout)
+    return newest(found, now, pubkey=pubkey)
+
+
+def did_document(desc: EventLike) -> DIDDocument:
+    """The node profile a did:nostr resolver emits for a kind 11801 (fleetmesh_core/did)."""
+    return did.document(desc)
+