Source code for fleetmesh_strfry.policy

"""strfry write-policy engine, its configuration, and the stdio plugin runner.

1. Native strfry Write-Policy Plugin Protocol (stdio line-based IPC):
   - Line-delimited JSON interface compliant with strfry's `writePolicy` plugin engine.
   - Evaluates BIP-340 Schnorr signatures, timestamp skew, NIP-40 expiration, payload MTUs,
     per-IP/per-pubkey rate limits, and Fleetmesh bilateral grants (Kind 30803).
   - Automatically intercepts and records mesh control events (11801, 11802, 11803,
     30801, 30802, 30803, 30810, 30811) into the local meshnode store.
   - Answers with strfry actions: `accept`, `reject` (with diagnostic reason), and `shadowReject`.
2. Symmetrical Egress Policy (`pluginOut`):
   - As specified in `spec.html` (§ Sovereignty and Policy Seams):
     Enforces local shard sovereignty, preventing quarantined notes from leaking to
     wide-mesh peers with actions: `allow`, `drop`, `shadowDrop`, and `redact`.

Moved verbatim from meshnode's fleetmesh_node/strfry_bridge.py; only the import paths changed.
"""
from __future__ import annotations

import collections
import json
import os
import sys
import threading
import time
from typing import (
    Any,
    Callable,
    Counter,
    Mapping,
    Optional,
    Sequence,
    TextIO,
)
from fleetmesh_core.storage import store  # noqa: E402
from fleetmesh_node.planes.transport.bridge.ratelimit import RateLimiter  # noqa: E402  (shared, audit D4)

DEFAULT_STRFRY_URL: str = 'ws://127.0.0.1:7777'
DEFAULT_MAX_FUTURE_SECONDS: int = 900
DEFAULT_MAX_EVENT_BYTES: int = 256 * 1024
DEFAULT_RATE_LIMIT_PER_MIN: int = 1200
DEFAULT_RATE_LIMIT_PER_PUBKEY: int = 180
DEFAULT_RATE_LIMIT_PER_IP: int = 300

MESH_CONTROL_KINDS: set[int] = {
    11801, 11802, 11803, 21801, 21802,
    30166, 30385, 30801, 30802, 30803, 30810, 30811,
}


[docs]class StrfryPolicyError(Exception): pass
[docs]class StrfryPolicyConfig: """Configuration governing strfry writePolicy and egressPolicy evaluation."""
[docs] def __init__( self, require_valid_sig: bool = True, max_future_seconds: int = DEFAULT_MAX_FUTURE_SECONDS, max_event_bytes: int = DEFAULT_MAX_EVENT_BYTES, rate_limit_per_min: int = DEFAULT_RATE_LIMIT_PER_MIN, rate_limit_per_pubkey: int = DEFAULT_RATE_LIMIT_PER_PUBKEY, rate_limit_per_ip: int = DEFAULT_RATE_LIMIT_PER_IP, enforce_grants: bool = False, shadow_reject: bool = False, blocked_pubkeys: Optional[Sequence[str]] = None, allowed_pubkeys: Optional[Sequence[str]] = None, blocked_kinds: Optional[Sequence[int]] = None, allowed_kinds: Optional[Sequence[int]] = None, allowed_shards: Optional[Sequence[str]] = None, quarantine_kinds: Optional[Sequence[int]] = None, roster_file: Optional[str] = None, ) -> None: self.require_valid_sig: bool = require_valid_sig self.max_future_seconds: int = max_future_seconds self.max_event_bytes: int = max_event_bytes self.rate_limit_per_min: int = rate_limit_per_min self.rate_limit_per_pubkey: int = rate_limit_per_pubkey self.rate_limit_per_ip: int = rate_limit_per_ip self.enforce_grants: bool = enforce_grants self.shadow_reject: bool = shadow_reject self.blocked_pubkeys: set[str] = set(blocked_pubkeys or ()) self.allowed_pubkeys: Optional[set[str]] = set(allowed_pubkeys) if allowed_pubkeys is not None else None self.blocked_kinds: set[int] = set(blocked_kinds or ()) self.allowed_kinds: Optional[set[int]] = set(allowed_kinds) if allowed_kinds is not None else None self.allowed_shards: Optional[set[str]] = set(allowed_shards) if allowed_shards is not None else None self.quarantine_kinds: set[int] = set(quarantine_kinds or ()) # Plan D6, the roster-protected relay: a JSON file written atomically # by the meshnode network compartment (face.roster_export_path) of # the shape {network_id: [pubkeys]}. Its pubkeys are merged with the # static `allowed_pubkeys` list; the file is re-read when its mtime # changes; an unreadable or missing file leaves the static list as # the whole allow-list rather than opening the relay. self.roster_file: Optional[str] = roster_file self._roster_mtime: Optional[float] = None self._roster_pubkeys: set[str] = set() self._static_allowed: Optional[set[str]] = ( set(self.allowed_pubkeys) if self.allowed_pubkeys is not None else None) if roster_file is not None and self._static_allowed is None: # naming a roster file at all makes this a roster-only relay self._static_allowed = set() self.allowed_pubkeys = set() self.reload_roster()
[docs] def reload_roster(self, force: bool = False) -> bool: """Re-read the roster file if its mtime moved (or `force`); True when the merged allow-list changed. Safe to call on every event: a stat.""" if self.roster_file is None: return False try: mtime = os.stat(self.roster_file).st_mtime except OSError: mtime = None if not force and mtime == self._roster_mtime: return False self._roster_mtime = mtime fresh: set[str] = set() if mtime is not None: try: with open(self.roster_file, encoding='utf-8') as fh: data = json.load(fh) if isinstance(data, dict): for members in data.values(): if isinstance(members, list): fresh.update(m for m in members if isinstance(m, str) and len(m) == 64) except (OSError, ValueError): fresh = set() # a half-written or broken file is nobody, not everybody if fresh == self._roster_pubkeys and self.allowed_pubkeys is not None: return False self._roster_pubkeys = fresh self.allowed_pubkeys = set(self._static_allowed or ()) | fresh return True
[docs] @classmethod def from_dict(cls, d: Mapping[str, Any]) -> StrfryPolicyConfig: return cls( require_valid_sig=bool(d.get('require_valid_sig', True)), max_future_seconds=int(d.get('max_future_seconds', DEFAULT_MAX_FUTURE_SECONDS)), max_event_bytes=int(d.get('max_event_bytes', DEFAULT_MAX_EVENT_BYTES)), rate_limit_per_min=int(d.get('rate_limit_per_min', DEFAULT_RATE_LIMIT_PER_MIN)), rate_limit_per_pubkey=int(d.get('rate_limit_per_pubkey', DEFAULT_RATE_LIMIT_PER_PUBKEY)), rate_limit_per_ip=int(d.get('rate_limit_per_ip', DEFAULT_RATE_LIMIT_PER_IP)), enforce_grants=bool(d.get('enforce_grants', False)), shadow_reject=bool(d.get('shadow_reject', False)), blocked_pubkeys=d.get('blocked_pubkeys'), allowed_pubkeys=d.get('allowed_pubkeys'), blocked_kinds=d.get('blocked_kinds'), allowed_kinds=d.get('allowed_kinds'), allowed_shards=d.get('allowed_shards'), quarantine_kinds=d.get('quarantine_kinds'), roster_file=d.get('roster_file'), )
[docs]class StrfryPolicyEngine: """Core policy engine evaluating strfry ingress and symmetrical egress traffic."""
[docs] def __init__( self, config: Optional[StrfryPolicyConfig] = None, store_backend: Optional[Any] = None, grant_store: Optional[Any] = None, clock: Optional[Callable[[], int]] = None, ) -> None: self.config: StrfryPolicyConfig = config or StrfryPolicyConfig() self.store: Optional[Any] = store_backend self.grants: Optional[Any] = grant_store self.clock: Callable[[], int] = clock or (lambda: int(time.time())) # Rate limiters self.global_limiter: RateLimiter = RateLimiter(self.config.rate_limit_per_min) # Least recently used first: at MAX_TRACKED_LIMITERS the idlest is # forgotten, so rotating addresses cannot reset a busy client's limit. self.ip_limiters: collections.OrderedDict[str, RateLimiter] = collections.OrderedDict() self.pubkey_limiters: collections.OrderedDict[str, RateLimiter] = collections.OrderedDict() self._lock: threading.Lock = threading.Lock() # Telemetry & Operational Metrics self.ingress_evaluated: int = 0 self.ingress_accepted: int = 0 self.ingress_rejected: int = 0 self.ingress_shadow_rejected: int = 0 self.rejection_reasons: Counter[str] = collections.Counter() self.egress_evaluated: int = 0 self.egress_allowed: int = 0 self.egress_dropped: int = 0 self.egress_redacted: int = 0
MAX_TRACKED_LIMITERS: int = 4096 def _limiter(self, table: 'collections.OrderedDict[str, RateLimiter]', key: str, rate: Any) -> RateLimiter: """`key`'s limiter, made on first use and marked most recently used. Caller holds _lock.""" lim = table.get(key) if lim is None: if len(table) >= self.MAX_TRACKED_LIMITERS: table.popitem(last=False) lim = RateLimiter(rate) table[key] = lim else: table.move_to_end(key) return lim def _get_ip_limiter(self, ip: str) -> RateLimiter: with self._lock: return self._limiter(self.ip_limiters, ip, self.config.rate_limit_per_ip) def _get_pubkey_limiter(self, pubkey: str) -> RateLimiter: with self._lock: return self._limiter(self.pubkey_limiters, pubkey, self.config.rate_limit_per_pubkey) # ----------------------------------------------------------------------- # Ingress Evaluation (strfry writePolicy Plugin Protocol) # -----------------------------------------------------------------------
[docs] def evaluate_ingress(self, payload: object) -> dict[str, Any]: """Evaluate an inbound event submitted via strfry writePolicy. Returns one of: {"id": "<id>", "action": "accept"} {"id": "<id>", "action": "reject", "msg": "blocked: <reason>"} {"id": "<id>", "action": "shadowReject"} """ self.ingress_evaluated += 1 now = self.clock() # 1. Parse JSON input payload if string if isinstance(payload, str): try: data = json.loads(payload) except Exception as e: self.ingress_rejected += 1 self.rejection_reasons['malformed_json'] += 1 return {"id": "", "action": "reject", "msg": f"invalid: malformed json - {e}"} elif isinstance(payload, collections.abc.Mapping): data = dict(payload) else: self.ingress_rejected += 1 self.rejection_reasons['invalid_type'] += 1 return {"id": "", "action": "reject", "msg": "invalid: expected json object"} # 2. Check request type req_type = data.get('type') if req_type == 'lookups': # strfry lookup query eid = data.get('event', {}).get('id', '') self.ingress_accepted += 1 return {"id": eid, "action": "accept"} # Extract event dictionary ev: Any = data.get('event') if 'event' in data else data source_info: Any = data.get('sourceInfo') or data.get('source') or {} if isinstance(source_info, str): # strfry itself sends sourceInfo as a bare string: the client IP for # IP4/IP6 sources, a relay URL for Stream/Sync. source_info = {'ip': source_info} if data.get('sourceType') in (None, 'IP4', 'IP6') else {} elif not isinstance(source_info, collections.abc.Mapping): source_info = {} if not isinstance(ev, dict): self.ingress_rejected += 1 self.rejection_reasons['missing_event'] += 1 return {"id": "", "action": "reject", "msg": "invalid: event object missing"} eid = ev.get('id', '') if not isinstance(eid, str) or len(eid) != 64: self.ingress_rejected += 1 self.rejection_reasons['invalid_id'] += 1 return {"id": str(eid), "action": "reject", "msg": "invalid: 32-byte hex id required"} # 3. Global & Source Rate Limiting if not self.global_limiter.allow(now): return self._reject(eid, "rate limit: global rate limit exceeded", 'global_rate_limited') ip_addr = str(source_info.get('realIp') or source_info.get('ip') or '') if ip_addr and not self._get_ip_limiter(ip_addr).allow(now): return self._reject(eid, "rate limit: source IP rate limit exceeded", 'ip_rate_limited') pubkey = ev.get('pubkey', '') if isinstance(pubkey, str) and pubkey: if not self._get_pubkey_limiter(pubkey).allow(now): return self._reject(eid, "rate limit: pubkey submission rate limit exceeded", 'pubkey_rate_limited') # 4. Payload Size Limit raw_size = len(json.dumps(ev, separators=(',', ':'))) if raw_size > self.config.max_event_bytes: return self._reject(eid, f"size: exceeds maximum event bytes ({raw_size} > {self.config.max_event_bytes})", 'size_limit') # 5. Timestamp Skew (Future & Expiration) created_at = ev.get('created_at') if not isinstance(created_at, int): return self._reject(eid, "invalid: created_at must be an integer", 'invalid_created_at') if created_at > now + self.config.max_future_seconds: skew = created_at - now return self._reject(eid, f"clock: created_at is {skew}s in the future", 'future_skew') # NIP-40 Expiration exp = store.expiration(ev) if exp is not None and exp <= now: return self._reject(eid, "expired: event expiration date has passed", 'expired') # 6. Pubkey Whitelist / Blacklist if pubkey in self.config.blocked_pubkeys: return self._reject(eid, "blocked: author pubkey is blacklisted", 'blocked_pubkey') self.config.reload_roster() if self.config.allowed_pubkeys is not None and pubkey not in self.config.allowed_pubkeys: return self._reject(eid, "blocked: author pubkey is not whitelisted", 'pubkey_not_whitelisted') # 7. Kind Whitelist / Blacklist kind = ev.get('kind') if not isinstance(kind, int): return self._reject(eid, "invalid: event kind must be an integer", 'invalid_kind') if kind in self.config.blocked_kinds: return self._reject(eid, f"blocked: kind {kind} is prohibited", 'blocked_kind') if self.config.allowed_kinds is not None and kind not in self.config.allowed_kinds: return self._reject(eid, f"blocked: kind {kind} is not in allowed kinds", 'kind_not_allowed') # 8. Shard Tag Whitelist if self.config.allowed_shards is not None: tags = ev.get('tags', []) if isinstance(tags, list): for t in tags: if isinstance(t, list) and len(t) > 1 and t[0] == 't': if t[1] not in self.config.allowed_shards: return self._reject(eid, f"blocked: shard {t[1]} is not permitted", 'unauthorized_shard') # 9. Cryptographic BIP-340 Signature Verification if self.config.require_valid_sig: if not store.verify_event(ev): return self._reject(eid, "invalid: BIP-340 Schnorr signature or event id does not verify", 'bad_signature') # 10. Bilateral Peering Grant Enforcement if self.config.enforce_grants and self.grants is not None: # Check if source claims to be a peered node or transit hop source_peer = source_info.get('pubkey') or '' if not source_peer and isinstance(ev.get('tags'), list): for t in ev['tags']: if isinstance(t, list) and len(t) > 1 and t[0] in ('mesh-peer', 'transit-peer'): source_peer = t[1] break if source_peer: # Check bilateral grant table g = self.grants.get(source_peer, 'received') if g is None or g.get('status') != 'live': return self._reject(eid, f"blocked: no active bilateral peering grant for peer {source_peer[:16]}", 'no_grant') if self.config.shadow_reject: self.ingress_shadow_rejected += 1 return {"id": eid, "action": "shadowReject", "msg": ""} # 11. Mesh Control Interception & Local Ingestion if self.store is not None: if kind in MESH_CONTROL_KINDS or not store.is_ephemeral(kind): try: self.store.insert_event(ev, now) if hasattr(self.store, 'note_origin'): self.store.note_origin(eid, getattr(self.store, 'LOCAL', 'local')) except Exception: pass # 12. Acceptance self.ingress_accepted += 1 return {"id": eid, "action": "accept"}
def _reject(self, eid: str, reason: str, category: str) -> dict[str, Any]: self.ingress_rejected += 1 self.rejection_reasons[category] += 1 if self.config.shadow_reject: self.ingress_shadow_rejected += 1 return {"id": eid, "action": "shadowReject"} return {"id": eid, "action": "reject", "msg": f"blocked: {reason}"} # ----------------------------------------------------------------------- # Egress Evaluation (spec.html § Sovereignty and Policy Seams: pluginOut) # -----------------------------------------------------------------------
[docs] def evaluate_egress( self, event: Mapping[str, Any], target_info: Optional[Mapping[str, Any]] = None, ) -> dict[str, Any]: """Evaluate an outbound event before emitting to mesh or downstream relays. Returns one of: {"action": "allow"} {"action": "drop", "msg": "<reason>"} {"action": "shadowDrop"} {"action": "redact", "fields": ["tags"], "redacted_tags": [...]} """ self.egress_evaluated += 1 target = dict(target_info or {}) kind = event.get('kind', 0) pubkey = event.get('pubkey', '') # 1. Quarantined Kinds or Blacklisted Pubkeys if kind in self.config.quarantine_kinds: self.egress_dropped += 1 return {"action": "drop", "msg": f"kind {kind} is quarantined from egress"} if pubkey in self.config.blocked_pubkeys: self.egress_dropped += 1 return {"action": "drop", "msg": "author pubkey is blocked from egress"} # 2. Target Peer Tier Governance target_class = target.get('class', '') if target_class == 'edge': # Edge peers cannot receive internal unblinded control events if kind in (30801, 30802, 30803) and not event.get('content', '').startswith('{'): self.egress_dropped += 1 return {"action": "drop", "msg": "raw grant data restricted from edge peers"} # 3. Tag Redaction (stripping private/internal metadata tags) tags = event.get('tags', []) redacted_tags = [] needs_redaction = False if isinstance(tags, list): for t in tags: if isinstance(t, list) and len(t) > 0: if t[0].startswith('x-internal') or t[0].startswith('_'): needs_redaction = True continue redacted_tags.append(t) if needs_redaction: self.egress_redacted += 1 return { "action": "redact", "fields": ["tags"], "redacted_tags": redacted_tags, } self.egress_allowed += 1 return {"action": "allow"}
[docs] def stats(self) -> dict[str, Any]: """Telemetry metrics for the policy engine.""" return { 'ingress': { 'evaluated': self.ingress_evaluated, 'accepted': self.ingress_accepted, 'rejected': self.ingress_rejected, 'shadow_rejected': self.ingress_shadow_rejected, 'rejection_reasons': dict(self.rejection_reasons), }, 'egress': { 'evaluated': self.egress_evaluated, 'allowed': self.egress_allowed, 'dropped': self.egress_dropped, 'redacted': self.egress_redacted, }, 'active_ip_limiters': len(self.ip_limiters), 'active_pubkey_limiters': len(self.pubkey_limiters), 'roster_pubkeys': len(self.config._roster_pubkeys), }
# --------------------------------------------------------------------------- # strfry Write-Policy Plugin Stdio Loop Runner # ---------------------------------------------------------------------------
[docs]class StrfryPluginRunner: """Manages external process execution conforming to strfry's writePolicy plugin IPC."""
[docs] def __init__(self, engine: StrfryPolicyEngine) -> None: self.engine: StrfryPolicyEngine = engine
[docs] def run_stdio(self, in_stream: TextIO = sys.stdin, out_stream: TextIO = sys.stdout) -> None: """Stream line-by-line JSON requests from stdin, evaluate, and write responses to stdout.""" for line in in_stream: line_str = line.strip() if not line_str: continue try: verdict = self.engine.evaluate_ingress(line_str) except Exception as e: verdict = {"id": "", "action": "reject", "msg": f"plugin error: {e}"} out_stream.write(json.dumps(verdict, separators=(',', ':')) + '\n') out_stream.flush()