"""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()