fleetmesh-node 0.2.0__py3-none-any.whl

node/examples/follower.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""The reference out-of-process plugin: follow a node, print, ask.
+
+    python3 -m node.examples.follower ~/.meshnode [topic ...]
+
+Everything it does goes through the control socket (docs/extending.md,
+"Out-of-process plugins"). It holds no keys, runs as whoever started it,
+and when a grant is issued it asks the node who the peer is - the one
+"act" in the example, chosen because it reads rather than changes.
+"""
+import json
+import sys
+
+from node.app import socket as control
+
+
+def follow(node_dir, topics=(), out=sys.stdout, limit=None):
+    """Print envelopes until the node goes away, `limit` envelopes or ^C.
+
+    Returns how many envelopes it printed; the test counts them.
+    """
+    args = {'topics': list(topics)} if topics else {}
+    it = control.stream(node_dir, 'subscribe', timeout=None, **args)
+    ack = next(it)
+    print('following from seq %s' % ack['seq'], file=sys.stderr)
+    seen = 0
+    for env in it:
+        line = {'seq': env['seq'], 'topic': env['topic'], 'data': env['data']}
+        if env['topic'] == 'grant.issued':
+            # A plugin acts with the operator's verbs and no others.
+            peers = control.call(node_dir, 'peers')
+            line['peer_known'] = any(p.get('peer') == env['data']['peer'] for p in peers)
+        print(json.dumps(line), file=out, flush=True)
+        seen += 1
+        if limit and seen >= limit:
+            break
+    return seen
+
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+    try:
+        follow(sys.argv[1], sys.argv[2:])
+    except KeyboardInterrupt:
+        pass

node/interfaces.py

@@ -0,0 +1,235 @@
+"""Formal interfaces, protocols, and data contracts for meshnode.
+
+Standard library only. All wire types reflect the normative JSON Schemas in
+schemas/ and the protocol invariants verified in fleetmesh_core/.
+"""
+from __future__ import annotations
+
+from typing import (
+    Any,
+    Counter,
+    Mapping,
+    Optional,
+    Protocol,
+    Sequence,
+    TypedDict,
+    runtime_checkable,
+)
+
+# Core wire, event, filter, and DIDComm shapes are defined once in
+# fleetmesh_core.wire.interfaces and re-exported here to ensure exact parity.
+from fleetmesh_core.wire.interfaces import (
+    DIDCommAttachment,
+    DIDCommAttachmentData,
+    DIDCommMessage,
+    DeliveryEnvelope,
+    DeliveryHop,
+    EventLike,
+    GrantLimits,
+    GrantPayload,
+    GrantScope,
+    NostrEvent,
+    NostrFilter,
+    Tag,
+    TagList,
+    UnsignedNostrEvent,
+    ProtocolHealth,
+    RouteMatch,
+    ProtocolHostRouter,
+    ProtocolIdentityAdapter,
+    ProtocolPackage,
+)
+
+__all__ = [
+    'DeliveryEnvelope', 'DeliveryHop', 'GrantLimits', 'GrantPayload', 'GrantScope',
+    'Tag', 'TagList', 'NostrEvent', 'UnsignedNostrEvent', 'EventLike', 'NostrFilter',
+    'DIDCommAttachmentData', 'DIDCommAttachment', 'DIDCommMessage',
+    'RelayHealthRow', 'AwaitingAckRow', 'ThrottledRow', 'ReceiptRefusedRow',
+    'GrantStatusRow', 'PendingGrantRow', 'EvaluationRow', 'RepricedRow',
+    'HealthStatusDict', 'NodeStatusDict', 'CommandSpec',
+    'KeyStoreProtocol', 'TransportProtocol', 'EventStoreProtocol', 'CompartmentProtocol',
+    'ProtocolHealth', 'RouteMatch', 'ProtocolHostRouter', 'ProtocolIdentityAdapter', 'ProtocolPackage',
+]
+
+
+@runtime_checkable
+class KeyStoreProtocol(Protocol):
+    """The node keys and identity."""
+    node_sk: str
+    node_pk: str
+    did: str
+
+    def multikeys(self) -> dict[str, str]: ...
+    def kid(self, which: str = 'agreement') -> str: ...
+    def save(self, directory: Any) -> str: ...
+
+
+@runtime_checkable
+class TransportProtocol(Protocol):
+    """The transport adapter interface: sends and receives DIDComm envelopes."""
+    scheme: str
+    health: Mapping[str, Mapping[str, Any]]
+    drop_counts: Counter[str]
+
+    def send(self, peer_pk: str, message: DIDCommMessage | Mapping[str, Any], authenticated: bool = True) -> Any: ...
+    def request(
+        self,
+        peer_pk: str,
+        message: DIDCommMessage | Mapping[str, Any],
+        timeout: Optional[float] = None,
+        authenticated: bool = True,
+    ) -> Optional[DIDCommMessage | Mapping[str, Any]]: ...
+    def close(self) -> None: ...
+
+
+@runtime_checkable
+class EventStoreProtocol(Protocol):
+    """Storage for Nostr events and provenance."""
+    def insert_event(self, event: NostrEvent) -> str: ...
+    def get_event(self, event_id: str) -> Optional[NostrEvent]: ...
+    def has_event(self, event_id: str) -> bool: ...
+    def note_origin(self, event_id: str, origin: str) -> None: ...
+    def origin_of(self, event_id: str) -> Optional[str]: ...
+    def any_replicated(self, event_ids: Sequence[str]) -> bool: ...
+    def fingerprint_range(self, filt: NostrFilter | Mapping[str, Any], since: int, until: int, now: int) -> str: ...
+
+
+# ---- what `meshnode status` and `meshnode health` format -------------------
+#
+# A compartment's state() is free-form: it is JSON-serialised the moment it is
+# read, and the CLI prints most of it with .get(). These are the rows whose
+# fields the CLI formats by name, so a compartment that renames one is caught
+# where it is written rather than where an operator reads it. total=False
+# because status.json on disk predates every one of them.
+
+class RelayHealthRow(TypedDict, total=False):
+    connected: bool
+    confirmed: bool              # the relay answered the REQ, not merely received it
+    since: Optional[int]
+    reconnects: int
+    last_event_at: Optional[int]
+    last_error: Optional[str]
+
+
+class AwaitingAckRow(TypedDict, total=False):
+    peer: str
+    type: str
+    at: int
+    relays: list[str]
+    heard_at: Optional[int]      # unacknowledged rows only: when the peer last spoke
+
+
+class ThrottledRow(TypedDict, total=False):
+    peer: str
+    shard: str
+    why: str
+    until: int
+
+
+class ReceiptRefusedRow(TypedDict, total=False):
+    peer: Optional[str]
+    window: Optional[int]
+    named: Optional[str]
+    acceptable: list[str]
+    at: int
+
+
+class GrantStatusRow(TypedDict, total=False):
+    peer: str
+    direction: str
+    tier: Optional[str]
+    status: str
+
+
+class PendingGrantRow(TypedDict, total=False):
+    peer: str
+    tier: Optional[str]
+    from_epoch: int
+
+
+class EvaluationRow(TypedDict, total=False):
+    peer: str
+    epoch: int
+    severity: Optional[str]      # None for a silent window: nothing was priced
+    state: str
+
+
+class RepricedRow(TypedDict, total=False):
+    peer: str
+    epoch: int
+    was: str
+    severity: str
+    remedy_cancelled: bool
+
+
+class HealthStatusDict(TypedDict, total=False):
+    subsystem_trouble: list[str]
+    config_error: Optional[str]
+    handler_failures: int
+    tick_failures: int
+    last_tick_error: Optional[str]
+    rejected: Mapping[str, int]
+    relays: Mapping[str, RelayHealthRow]
+    sessions_refused: int
+    receipts_refused: list[ReceiptRefusedRow]
+    awaiting_ack: list[AwaitingAckRow]
+    throttled: list[ThrottledRow]
+    grants: list[GrantStatusRow]
+    evaluations: list[EvaluationRow]
+    repriced: list[RepricedRow]
+    subsystems: Mapping[str, Any]
+
+
+NodeStatusDict = TypedDict('NodeStatusDict', {
+    'at': int,
+    'did': str,
+    'node_did': str,
+    'pubkey': str,
+    'class': str,
+    'release': Mapping[str, Any],
+    'face': str,
+    'relays': list[str],
+    'descriptor': str,
+    'events_stored': int,
+    'grants': list[GrantStatusRow],
+    'pending_grants': list[PendingGrantRow],
+    'evaluations': list[EvaluationRow],
+    'repriced': list[RepricedRow],
+    'reports_published': int,
+    'pending_findings': int,
+    'refused_sessions': int,
+    'last_tick': list[list[str]],
+    'uptime': int | float,
+    'health': HealthStatusDict,
+    'compartments': Mapping[str, Any],
+    'subsystems': Mapping[str, Any],
+}, total=False)
+
+
+class CommandSpec(TypedDict, total=False):
+    """One control-socket command as the socket documents it under `commands`:
+    the dispatch table is the documentation, so it cannot drift from it."""
+    args: Mapping[str, str]      # name -> required | optional | a short note
+    does: str
+    reply: str
+    subsystem: str               # set by the registry when it prefixes the name
+
+
+@runtime_checkable
+class CompartmentProtocol(Protocol):
+    """A compartment of the node, assembled and ticked uniformly."""
+    name: Optional[str]
+    reads: tuple[str, ...]
+    live: tuple[str, ...]
+    commands: Mapping[str, CommandSpec]
+
+    def start(self) -> None: ...
+    def tick(self, now: int) -> list[tuple[Any, ...]]: ...
+    def stop(self) -> Any: ...
+    def state(self) -> Mapping[str, Any]: ...
+    def trouble(self) -> list[str]: ...
+    def notes(self) -> list[str]: ...
+    def report(self) -> Mapping[str, Any]: ...
+    def command(self, name: str, args: Mapping[str, Any]) -> Any: ...
+    def capability_protocols(self) -> Sequence[str]: ...
+    def descriptor_tags(self) -> Sequence[Sequence[str]]: ...

node/keystore/__init__.py

@@ -0,0 +1,27 @@
+"""The node's cryptographic keys and hardware enclave on disk."""
+from __future__ import annotations
+
+from .core import FILE, Keystore
+from .enclave import (
+    DEFAULT_ORIGIN,
+    DEFAULT_RP_ID,
+    EnclaveKey,
+    EnclaveKeystore,
+    detect_hardware_enclave,
+    verify_detached_attestation,
+    verify_enclave_attestation,
+    verify_signature,
+)
+
+__all__ = [
+    'FILE',
+    'Keystore',
+    'EnclaveKey',
+    'EnclaveKeystore',
+    'detect_hardware_enclave',
+    'verify_detached_attestation',
+    'verify_enclave_attestation',
+    'verify_signature',
+    'DEFAULT_RP_ID',
+    'DEFAULT_ORIGIN',
+]

node/keystore/core.py

@@ -0,0 +1,103 @@
+"""The node's keys on disk.
+
+One JSON file, mode 0600, holding the three secrets constants.json names: the
+secp256k1 node key (the nostr identity and did:nostr subject), the X25519
+agreement key, and the Ed25519 transport key. Generated once, read every
+start. Nothing else is stored here: grants, receipts and the event store have
+their own files, and an operator who rotates the node key has a new node.
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from typing import Literal
+
+from cryptography.hazmat.primitives.asymmetric import ed25519, x25519
+
+from fleetmesh_core.crypto import crypto, keys  # noqa: E402
+
+FILE = 'keys.json'
+
+
+class Keystore:
+    node_sk: str
+    node_pk: str
+    did: str
+    agreement_priv: x25519.X25519PrivateKey
+    agreement_pub: x25519.X25519PublicKey
+    transport_priv: ed25519.Ed25519PrivateKey
+    transport_pub: ed25519.Ed25519PublicKey
+    _seeds: tuple[bytes, bytes]
+
+    def __init__(self, node_sk: str, agreement_seed: bytes, transport_seed: bytes) -> None:
+        # A secret that is not a scalar in [1, N) is not a key. Below 1 the
+        # curve arithmetic returned None and the node died on a TypeError;
+        # at or above N it was silently reduced, so the node signed with a
+        # key that was not the one in its file. Refuse both by name.
+        try:
+            value = int(node_sk, 16)
+        except (TypeError, ValueError):
+            raise ValueError('node_sk is 64 hex characters')
+        if not isinstance(node_sk, str) or len(node_sk) != 64 or not (1 <= value < crypto.N):
+            raise ValueError('node_sk must be a 32-byte scalar in [1, N)')
+        if len(agreement_seed) != 32 or len(transport_seed) != 32:
+            raise ValueError('agreement and transport seeds are 32 bytes')
+        self.node_sk = node_sk                          # hex
+        self.node_pk = crypto.pubkey(node_sk)           # hex, x-only
+        self.did = 'did:nostr:' + self.node_pk
+        self.agreement_priv, self.agreement_pub = keys.agreement_keypair(agreement_seed)
+        self.transport_priv, self.transport_pub = keys.transport_keypair(transport_seed)
+        self._seeds = (agreement_seed, transport_seed)
+
+    # ---- encodings the descriptor and DID document carry ----------------
+    def multikeys(self) -> dict[str, str]:
+        return {'node': keys.multikey('node', bytes.fromhex(self.node_pk)),
+                'agreement': keys.multikey('agreement', keys.raw_public(self.agreement_pub)),
+                'transport': keys.multikey('transport', keys.raw_public(self.transport_pub))}
+
+    def kid(self, which: Literal['agreement', 'transport', 'node'] = 'agreement') -> str:
+        return '%s#%s' % (self.did, {'agreement': 'agree', 'transport': 'wire', 'node': 'nostr'}[which])
+
+    # ---- persistence -----------------------------------------------------
+    @classmethod
+    def generate(cls) -> Keystore:
+        sk = os.urandom(32).hex()
+        while not (1 <= int(sk, 16) < crypto.N):
+            sk = os.urandom(32).hex()
+        return cls(sk, keys.fresh_seed(), keys.fresh_seed())
+
+    @classmethod
+    def load(cls, directory: str | os.PathLike[str]) -> Keystore:
+        path = os.path.join(directory, FILE)
+        mode = stat.S_IMODE(os.stat(path).st_mode)
+        if mode & 0o077:
+            raise PermissionError('%s is readable by others (mode %o); refusing to load' % (path, mode))
+        with open(path, encoding='utf-8') as _fh:
+            d = json.load(_fh)
+        if d.get('format') != 'meshnode-keys/1':
+            raise ValueError('not a meshnode key file')
+        return cls(d['node_sk'], bytes.fromhex(d['agreement_seed']), bytes.fromhex(d['transport_seed']))
+
+    def save(self, directory: str | os.PathLike[str]) -> str:
+        os.makedirs(directory, mode=0o700, exist_ok=True)
+        path = os.path.join(directory, FILE)
+        if os.path.exists(path):
+            raise FileExistsError('%s exists; a node does not overwrite its own keys' % path)
+        body = json.dumps({'format': 'meshnode-keys/1', 'node_sk': self.node_sk,
+                           'agreement_seed': self._seeds[0].hex(),
+                           'transport_seed': self._seeds[1].hex(),
+                           'node_pk': self.node_pk, 'did': self.did}, indent=2)
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(fd, 'w', encoding='utf-8') as f:
+            f.write(body + '\n')
+        return path
+
+    @classmethod
+    def load_or_generate(cls, directory: str | os.PathLike[str]) -> Keystore:
+        if os.path.exists(os.path.join(directory, FILE)):
+            return cls.load(directory)
+        ks = cls.generate()
+        ks.save(directory)
+        return ks
+