fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/gateway/settle.py

@@ -0,0 +1,279 @@
+"""Unified peering capacity, rate-limiting, and Cashu ecash settlement.
+
+Enforces bilateral resource quotas and Cashu NUT-18 / NUT-24 ecash settlement
+across all four protocol boundaries:
+- Nostr relays & paid filters
+- ATProto XRPC & Firehose sync
+- ActivityPub S2S federation & media delivery
+- Secure Scuttlebutt MuxRPC & Blob sync
+"""
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass, field
+import json
+import threading
+import time
+from typing import Any, Mapping, Optional, Tuple
+
+from fleetmesh_core.accounting import cashu
+from fleetmesh_core.conformance.errors import FleetmeshError
+from node.protocols.atproto.metering import TokenBucket
+
+
+class GatewaySettlementError(FleetmeshError):
+    """Raised on settlement or quota verification failures."""
+
+
+@dataclass
+class CrossProtocolPeer:
+    """A tracked peer communicating across any supported wire protocol."""
+    protocol: str
+    peer_id: str
+    bucket: TokenBucket
+    balance_sat: int = 0
+    total_consumed_tokens: int = 0
+    total_settled_sat: int = 0
+    penalty_score: float = 0.0
+    created_at: int = field(default_factory=lambda: int(time.time()))
+
+
+@dataclass
+class PaymentChallenge:
+    """Standardized payment challenge issued when a peer exceeds quota."""
+    protocol: str
+    peer_id: str
+    required_sat: int
+    mint_url: str
+    memo: str
+
+    def to_http_402(self) -> tuple[int, Mapping[str, str], bytes]:
+        """Format as HTTP 402 Payment Required with Cashu challenge header & body."""
+        headers = {
+            "Content-Type": "application/json",
+            "WWW-Authenticate": f'Cashu mint="{self.mint_url}", amount={self.required_sat}, unit="sat"',
+        }
+        body = json.dumps({
+            "error": "PaymentRequired",
+            "message": f"Peer quota exceeded on {self.protocol}. Deposit Cashu ecash to continue.",
+            "mint": self.mint_url,
+            "amount_sat": self.required_sat,
+            "unit": "sat",
+            "memo": self.memo,
+        }, indent=2).encode('utf-8')
+        return 402, headers, body
+
+    def to_nostr_notice(self) -> str:
+        """Format as Nostr NOTICE message content."""
+        return (
+            f"restricted: quota exceeded. Pay {self.required_sat} sats via Cashu to {self.mint_url} "
+            f"with memo '{self.memo}'"
+        )
+
+    def to_muxrpc_error(self) -> str:
+        """Format as SSB MuxRPC error message."""
+        return (
+            f"PaymentRequired: quota exceeded for @{self.peer_id}. "
+            f"Deposit {self.required_sat} sats at {self.mint_url}"
+        )
+
+
+@dataclass
+class SettlementReceipt:
+    """Proof of completed ecash settlement credit."""
+    protocol: str
+    peer_id: str
+    credited_sat: int
+    new_balance_sat: int
+    proof_count: int
+    timestamp: int = field(default_factory=lambda: int(time.time()))
+
+
+class CrossProtocolSettlementGateway:
+    """Unified resource accounting, rate limiting, and ecash settlement gateway."""
+
+    def __init__(
+        self,
+        default_capacity: float = 30.0,
+        default_refill_per_sec: float = 0.5,
+        price_per_topup_sat: int = 21,
+        tokens_per_topup: int = 100,
+        mint_url: str = "https://mint.example.org",
+        max_penalty_score: float = 10.0,
+    ):
+        self.default_capacity = default_capacity
+        self.default_refill_per_sec = default_refill_per_sec
+        self.price_per_topup_sat = price_per_topup_sat
+        self.tokens_per_topup = tokens_per_topup
+        self.mint_url = mint_url.rstrip('/')
+        self.max_penalty_score = max_penalty_score
+
+        self._peers: dict[tuple[str, str], CrossProtocolPeer] = {}
+        self._spent_secrets: set[str] = set()
+        self._total_challenges_issued = 0
+        self._total_settled_sat = 0
+        self._lock = threading.RLock()
+
+    def _peer_key(self, protocol: str, peer_id: str) -> tuple[str, str]:
+        return (protocol.lower().strip(), peer_id.strip())
+
+    def get_or_create_peer(
+        self,
+        protocol: str,
+        peer_id: str,
+        capacity: Optional[float] = None,
+        refill_rate: Optional[float] = None,
+    ) -> CrossProtocolPeer:
+        """Fetch or initialize a tracked peer record."""
+        key = self._peer_key(protocol, peer_id)
+        with self._lock:
+            if key not in self._peers:
+                cap = capacity if capacity is not None else self.default_capacity
+                refill = refill_rate if refill_rate is not None else self.default_refill_per_sec
+                bucket = TokenBucket(capacity=cap, refill_rate=refill)
+                self._peers[key] = CrossProtocolPeer(
+                    protocol=key[0],
+                    peer_id=key[1],
+                    bucket=bucket,
+                )
+            return self._peers[key]
+
+    def record_penalty(self, protocol: str, peer_id: str, penalty: float = 1.0) -> float:
+        """Increase penalty score for bad behavior (e.g. invalid signatures, flooding)."""
+        with self._lock:
+            peer = self.get_or_create_peer(protocol, peer_id)
+            peer.penalty_score += penalty
+            # Also drain tokens proportional to penalty
+            peer.bucket.tokens = max(0.0, peer.bucket.tokens - penalty * 2.0)
+            return peer.penalty_score
+
+    def check_access(
+        self,
+        protocol: str,
+        peer_id: str,
+        cost: int = 1,
+    ) -> Tuple[bool, Optional[PaymentChallenge]]:
+        """Authorize a request or issue a payment challenge.
+
+        Returns:
+            (True, None) if permitted under current token bucket or satoshi balance.
+            (False, PaymentChallenge) if dry and requires payment.
+        """
+        with self._lock:
+            peer = self.get_or_create_peer(protocol, peer_id)
+
+            # 1. Circuit breaker: excessive penalties reject without immediate topup
+            if peer.penalty_score >= self.max_penalty_score:
+                challenge = PaymentChallenge(
+                    protocol=protocol,
+                    peer_id=peer_id,
+                    required_sat=self.price_per_topup_sat * 5,
+                    mint_url=self.mint_url,
+                    memo=f"penalty-recovery-{peer_id[:16]}",
+                )
+                self._total_challenges_issued += 1
+                return False, challenge
+
+            # 2. Try consuming from rate-limiter token bucket
+            if peer.bucket.consume(float(cost)):
+                peer.total_consumed_tokens += cost
+                return True, None
+
+            # 3. If bucket dry, attempt to convert prepaid satoshi balance to tokens
+            if peer.balance_sat >= self.price_per_topup_sat:
+                peer.balance_sat -= self.price_per_topup_sat
+                peer.bucket.tokens += self.tokens_per_topup
+                peer.bucket.consume(float(cost))
+                peer.total_consumed_tokens += cost
+                return True, None
+
+            # 4. Quota exceeded: Issue payment challenge
+            self._total_challenges_issued += 1
+            challenge = PaymentChallenge(
+                protocol=protocol,
+                peer_id=peer_id,
+                required_sat=self.price_per_topup_sat,
+                mint_url=self.mint_url,
+                memo=f"quota-{protocol}-{peer_id[:16]}",
+            )
+            return False, challenge
+
+    def settle_cashu(self, protocol: str, peer_id: str, token_str: str) -> SettlementReceipt:
+        """Parse, validate, and credit Cashu ecash payment (V3 cashuA or V4 cashuB)."""
+        raw_token = token_str.strip()
+        proofs: list[Mapping[str, Any]] = []
+
+        if raw_token.startswith(cashu.TOKEN_V4_PREFIX):
+            try:
+                tok_v4 = cashu.decode_token_v4(raw_token)
+                proofs = list(tok_v4.get('proofs', []))
+            except Exception as e:
+                raise GatewaySettlementError(f"Invalid Cashu V4 token: {e}") from e
+        elif raw_token.startswith('cashuA'):
+            try:
+                payload = raw_token[6:]
+                # Pad base64 if needed
+                payload += '=' * (-len(payload) % 4)
+                data = json.loads(base64.urlsafe_b64decode(payload).decode('utf-8'))
+                token_entries = data.get('token', [])
+                for entry in token_entries:
+                    proofs.extend(entry.get('proofs', []))
+            except Exception as e:
+                raise GatewaySettlementError(f"Invalid Cashu V3 token: {e}") from e
+        else:
+            raise GatewaySettlementError("Unrecognized Cashu token prefix (expected cashuA or cashuB)")
+
+        proof_count = len(proofs)
+        sat_amount = sum(int(p.get('amount', 0)) for p in proofs)
+
+        if sat_amount <= 0 or proof_count == 0:
+            raise GatewaySettlementError("Token contains 0 sats or empty proofs")
+
+        with self._lock:
+            # Double-spend prevention across tokens
+            for p in proofs:
+                sec = p.get('secret')
+                if sec and sec in self._spent_secrets:
+                    raise GatewaySettlementError(f"Double-spend attempt: proof secret already redeemed ({sec})")
+
+            for p in proofs:
+                sec = p.get('secret')
+                if sec:
+                    self._spent_secrets.add(sec)
+
+            peer = self.get_or_create_peer(protocol, peer_id)
+
+            # Credit balance
+            peer.balance_sat += sat_amount
+            peer.total_settled_sat += sat_amount
+            self._total_settled_sat += sat_amount
+
+            # Refill tokens proportional to satoshis
+            granted_tokens = (sat_amount // self.price_per_topup_sat) * self.tokens_per_topup
+            if granted_tokens > 0:
+                peer.bucket.tokens = min(peer.bucket.capacity * 2, peer.bucket.tokens + granted_tokens)
+
+            # Decay penalty score on successful payment
+            peer.penalty_score = max(0.0, peer.penalty_score - 2.0)
+
+            return SettlementReceipt(
+                protocol=protocol,
+                peer_id=peer_id,
+                credited_sat=sat_amount,
+                new_balance_sat=peer.balance_sat,
+                proof_count=proof_count,
+            )
+
+    def stats(self) -> Mapping[str, Any]:
+        """Aggregate cross-protocol accounting statistics."""
+        with self._lock:
+            by_proto: dict[str, int] = {}
+            for (proto, _), _ in self._peers.items():
+                by_proto[proto] = by_proto.get(proto, 0) + 1
+
+            return {
+                "total_peers": len(self._peers),
+                "peers_by_protocol": by_proto,
+                "total_challenges_issued": self._total_challenges_issued,
+                "total_settled_sat": self._total_settled_sat,
+            }