fleetmesh-node 0.2.0__py3-none-any.whl

node/protocols/activitypub/federation.py

@@ -0,0 +1,490 @@
+"""ActivityPub Server-to-Server (S2S) Federation and Delivery.
+
+Standard library only. Manages:
+- Inbound inbox request handling (/inbox, /users/<user>/inbox) with HTTP signature verification.
+- Actor key resolution (local cache & remote lookup).
+- Inbound activity routing: Follow, Accept, Create, Undo, Delete, Announce.
+- Outbox publishing and multi-recipient fanout delivery with Ed25519 / RSA HTTP signing.
+- Strain and abuse scoring: tracks signature verification failures and throttles abusive hosts.
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+from fleetmesh_core.conformance.errors import FleetmeshError
+from fleetmesh_core.crypto.http_signatures import (
+    parse_signature_header,
+    sign_http_request,
+    verify_http_signature,
+)
+from node.protocols.activitypub.actor import Actor
+from node.protocols.activitypub.models import (
+    PUBLIC_COLLECTION,
+    Activity,
+    build_accept_activity,
+    build_create_activity,
+    build_follow_activity,
+    build_note,
+    build_undo_activity,
+    parse_activity,
+)
+from node.protocols.activitypub.store import ActivityPubStore
+
+__all__ = [
+    'FederationError',
+    'StrainThrottledError',
+    'StrainScoreKeeper',
+    'FederationService',
+    'is_safe_federation_url',
+]
+
+MAX_INBOX_BODY_BYTES = 10 * 1024 * 1024  # 10 MB
+
+
+def is_safe_federation_url(url: str, allow_local: bool = True) -> bool:
+    """Validate whether an outbound federation target URL is safe against SSRF attacks."""
+    if not url:
+        return False
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme not in ('http', 'https'):
+        return False
+    if allow_local:
+        return True
+    if parsed.scheme != 'https':
+        return False
+    host = parsed.hostname
+    if not host:
+        return False
+    import ipaddress
+    try:
+        ip = ipaddress.ip_address(host)
+        if ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_reserved:
+            return False
+    except ValueError:
+        if host.lower() in ('localhost', 'metadata.google.internal') or host.endswith('.local'):
+            return False
+    return True
+
+
+class FederationError(FleetmeshError):
+    """Base error for federation processing."""
+
+
+class StrainThrottledError(FederationError):
+    """Raised when an abusive or high-strain host is temporarily throttled."""
+
+
+class StrainScoreKeeper:
+    """Tracks verification failures per peer host to mitigate DoS and invalid traffic.
+
+    Integrates optionally with Fleetmesh StrainLedger.
+    """
+
+    def __init__(
+        self,
+        max_failures: int = 5,
+        window_seconds: float = 300.0,
+        strain_ledger: Optional[Any] = None,
+    ):
+        self.max_failures = max_failures
+        self.window_seconds = window_seconds
+        self.strain_ledger = strain_ledger
+        self._failures: dict[str, list[float]] = {}
+
+    def _clean_old(self, host: str, now: float) -> list[float]:
+        cutoff = now - self.window_seconds
+        valid = [t for t in self._failures.get(host, []) if t >= cutoff]
+        self._failures[host] = valid
+        return valid
+
+    def is_throttled(self, host: str) -> bool:
+        """Check if a remote host currently exceeds allowable strain."""
+        now = time.time()
+        failures = self._clean_old(host, now)
+        return len(failures) >= self.max_failures
+
+    def record_failure(self, host: str) -> int:
+        """Record a signature verification failure or malformed request."""
+        now = time.time()
+        failures = self._clean_old(host, now)
+        failures.append(now)
+        self._failures[host] = failures
+
+        if self.strain_ledger is not None:
+            try:
+                self.strain_ledger.record(kind='abort', peer=host, transport='activitypub')
+            except Exception:
+                pass
+
+        return len(failures)
+
+    def record_success(self, host: str) -> None:
+        """Reward valid request by decreasing recorded failures."""
+        if host in self._failures and self._failures[host]:
+            self._failures[host].pop(0)
+
+
+class FederationService:
+    """ActivityPub S2S Federation handler and outbound delivery engine."""
+
+    def __init__(
+        self,
+        store: ActivityPubStore,
+        local_actor: Actor,
+        private_key: Any,
+        strain_score_keeper: Optional[StrainScoreKeeper] = None,
+        remote_resolver: Optional[Callable[[str], Optional[Mapping[str, Any]]]] = None,
+        http_client: Optional[Callable[[str, Mapping[str, str], bytes], tuple[int, bytes]]] = None,
+        auto_accept_follows: bool = True,
+        allow_local_federation: bool = True,
+    ):
+        self.store = store
+        self.local_actor = local_actor
+        self.private_key = private_key
+        self.strain = strain_score_keeper or StrainScoreKeeper()
+        self.remote_resolver = remote_resolver or self._default_resolver
+        self.http_client = http_client or self._default_http_post
+        self.auto_accept_follows = auto_accept_follows
+        self.allow_local_federation = allow_local_federation
+
+        # Ensure local actor is registered in store
+        self.store.upsert_actor(local_actor)
+
+    def _default_resolver(self, uri: str) -> Optional[Mapping[str, Any]]:
+        """Fetch remote actor JSON-LD document over HTTP if not already in store."""
+        # Strip fragment if keyId was passed
+        actor_url = uri.split('#')[0]
+        cached = self.store.get_actor(actor_url)
+        if cached:
+            return cached
+
+        try:
+            req = urllib.request.Request(
+                actor_url,
+                headers={'Accept': 'application/activity+json, application/ld+json'},
+            )
+            with urllib.request.urlopen(req, timeout=10.0) as resp:
+                if resp.status == 200:
+                    data = json.loads(resp.read().decode('utf-8'))
+                    if isinstance(data, dict) and str(data.get('id') or actor_url).split('#')[0] == actor_url:
+                        self.store.upsert_actor(data)
+                        return data
+        except Exception:
+            pass
+        return None
+
+    def _default_http_post(
+        self,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes,
+    ) -> tuple[int, bytes]:
+        """Perform real HTTP POST request using urllib."""
+        req = urllib.request.Request(url, data=body, headers=headers, method='POST')
+        with urllib.request.urlopen(req, timeout=15.0) as resp:
+            return resp.status, resp.read()
+
+    def resolve_public_key(self, key_id: str) -> Optional[str]:
+        """Resolve public key PEM string for a given keyId."""
+        actor_url = key_id.split('#')[0]
+        doc = self.remote_resolver(actor_url)
+        if not doc:
+            return None
+
+        pk_obj = doc.get('publicKey')
+        if isinstance(pk_obj, dict):
+            # Check if this public key matches key_id
+            target_id = pk_obj.get('id')
+            if not target_id or target_id == key_id or key_id == actor_url:
+                pem = pk_obj.get('publicKeyPem')
+                if pem and isinstance(pem, str):
+                    return pem
+        return None
+
+    # -------------------------------------------------------------------------
+    # Inbound Inbox Handling
+    # -------------------------------------------------------------------------
+
+    def handle_inbox(
+        self,
+        method: str,
+        path: str,
+        headers: Mapping[Any, Any],
+        body: bytes,
+    ) -> tuple[int, dict[str, str], bytes]:
+        """Process inbound HTTP request to shared or personal inbox."""
+        if method.upper() != 'POST':
+            return 405, {'Content-Type': 'application/json'}, b'{"error": "Method not allowed"}'
+
+        if len(body) > MAX_INBOX_BODY_BYTES:
+            return 413, {'Content-Type': 'application/json'}, b'{"error": "Payload too large"}'
+
+        norm_headers: dict[str, str] = {
+            (k.decode('latin-1') if isinstance(k, bytes) else str(k)): (
+                v.decode('latin-1') if isinstance(v, bytes) else str(v)
+            )
+            for k, v in headers.items()
+        }
+
+        # Extract Host for strain tracking
+        host = norm_headers.get('Host') or norm_headers.get('host') or 'unknown-host'
+
+        if self.strain.is_throttled(host):
+            return 429, {'Content-Type': 'application/json', 'Retry-After': '60'}, b'{"error": "Rate limit / strain exceeded"}'
+
+        # Find and parse Signature header
+        sig_val = None
+        for k, v in norm_headers.items():
+            if k.lower() == 'signature':
+                sig_val = v
+                break
+
+        if not sig_val:
+            self.strain.record_failure(host)
+            return 401, {'Content-Type': 'application/json'}, b'{"error": "Missing HTTP Signature"}'
+
+        try:
+            parsed_sig = parse_signature_header(sig_val)
+        except Exception:
+            self.strain.record_failure(host)
+            return 400, {'Content-Type': 'application/json'}, b'{"error": "Malformed Signature header"}'
+
+        key_id = parsed_sig.get('keyId')
+        if not key_id:
+            self.strain.record_failure(host)
+            return 400, {'Content-Type': 'application/json'}, b'{"error": "Missing keyId in Signature"}'
+
+        pub_key_pem = self.resolve_public_key(key_id)
+        if not pub_key_pem:
+            self.strain.record_failure(host)
+            return 401, {'Content-Type': 'application/json'}, b'{"error": "Could not resolve signer public key"}'
+
+        # Verify signature
+        if not verify_http_signature(method=method, path=path, headers=norm_headers, body=body, public_key=pub_key_pem):
+            self.strain.record_failure(host)
+            return 401, {'Content-Type': 'application/json'}, b'{"error": "Invalid HTTP Signature"}'
+
+        # Signature verified successfully
+        self.strain.record_success(host)
+
+        # Parse ActivityStreams 2.0 Activity
+        try:
+            activity = parse_activity(body)
+        except Exception as e:
+            return 400, {'Content-Type': 'application/json'}, json.dumps({'error': f"Invalid activity: {e}"}).encode('utf-8')
+
+        # Actor verification: signer keyId actor must match activity actor
+        signer_actor = key_id.split('#')[0]
+        if activity.actor != signer_actor:
+            return 403, {'Content-Type': 'application/json'}, b'{"error": "Signer does not match activity actor"}'
+
+        # Record activity in store
+        self.store.record_activity(activity, direction='inbox')
+
+        # Dispatch activity-specific logic
+        self._dispatch_inbound(activity)
+
+        return 202, {'Content-Type': 'application/json'}, b'{"status": "accepted"}'
+
+    def _dispatch_inbound(self, activity: Activity) -> None:
+        """Route inbound activity actions."""
+        act_type = activity.type
+
+        if act_type == 'Follow':
+            target = activity.object_id
+            if target == self.local_actor.actor_url:
+                self.store.add_follower(self.local_actor.actor_url, activity.actor)
+                if self.auto_accept_follows:
+                    self._send_accept_follow(activity)
+
+        elif act_type == 'Undo':
+            obj = activity.object
+            obj_type = obj.get('type') if isinstance(obj, dict) else None
+            # If undoing a Follow
+            if obj_type == 'Follow' or isinstance(obj, str):
+                self.store.remove_follower(self.local_actor.actor_url, activity.actor)
+
+        elif act_type == 'Accept':
+            # Remote actor accepted our follow request
+            obj = activity.object
+            if isinstance(obj, dict) and obj.get('type') == 'Follow':
+                target_url = obj.get('object')
+                if isinstance(target_url, str):
+                    self.store.add_following(self.local_actor.actor_url, target_url)
+            elif isinstance(obj, str):
+                self.store.add_following(self.local_actor.actor_url, activity.actor)
+
+    def _send_accept_follow(self, follow_activity: Activity) -> None:
+        """Construct and deliver an Accept activity in response to a Follow."""
+        accept_id = f"{self.local_actor.actor_url}/activities/accept-{uuid.uuid4().hex[:12]}"
+        accept_act = build_accept_activity(
+            activity_id=accept_id,
+            actor_uri=self.local_actor.actor_url,
+            follow_activity=follow_activity.to_dict(),
+            recipient_uri=follow_activity.actor,
+        )
+        self.store.record_activity(accept_act, direction='outbox')
+
+        # Find recipient's inbox
+        recipient_doc = self.remote_resolver(follow_activity.actor)
+        if recipient_doc:
+            inbox_url = recipient_doc.get('inbox')
+            if inbox_url:
+                try:
+                    self.deliver_to_inbox(inbox_url, accept_act)
+                except Exception:
+                    pass
+
+    # -------------------------------------------------------------------------
+    # Outbound Delivery
+    # -------------------------------------------------------------------------
+
+    def deliver_to_inbox(
+        self,
+        inbox_url: str,
+        activity_dict: Mapping[str, Any],
+    ) -> tuple[int, bytes]:
+        """Sign and deliver an activity directly to a target inbox."""
+        if not is_safe_federation_url(inbox_url, allow_local=self.allow_local_federation):
+            raise FederationError(f"Rejected unsafe federation URL (SSRF guard): {inbox_url}")
+
+        body = json.dumps(activity_dict, sort_keys=True).encode('utf-8')
+        base_headers = {
+            'Content-Type': 'application/activity+json',
+            'Accept': 'application/activity+json',
+        }
+        signed_headers = sign_http_request(
+            method='POST',
+            url=inbox_url,
+            headers=base_headers,
+            body=body,
+            private_key=self.private_key,
+            key_id=self.local_actor.public_key_id,
+        )
+
+        return self.http_client(inbox_url, signed_headers, body)
+
+    def post_note(
+        self,
+        content: str,
+        to: Optional[Sequence[str]] = None,
+        cc: Optional[Sequence[str]] = None,
+        in_reply_to: Optional[str] = None,
+        attachment: Optional[Sequence[Mapping[str, Any]]] = None,
+    ) -> Mapping[str, Any]:
+        """Publish a new Note, record Create activity, and fan out to followers/recipients."""
+        item_id = uuid.uuid4().hex[:12]
+        note_id = f"{self.local_actor.actor_url}/notes/{item_id}"
+        act_id = f"{self.local_actor.actor_url}/activities/create-{item_id}"
+
+        target_to = list(to) if to is not None else [PUBLIC_COLLECTION]
+        target_cc = list(cc) if cc is not None else [self.local_actor.followers_url]
+
+        note_doc = build_note(
+            id=note_id,
+            attributed_to=self.local_actor.actor_url,
+            content=content,
+            to=target_to,
+            cc=target_cc,
+            in_reply_to=in_reply_to,
+            attachment=attachment,
+        )
+
+        create_act = build_create_activity(
+            activity_id=act_id,
+            actor_uri=self.local_actor.actor_url,
+            note_or_object=note_doc,
+            to=target_to,
+            cc=target_cc,
+        )
+
+        # Record locally
+        self.store.record_activity(create_act, direction='outbox')
+
+        # Fan out delivery
+        self._fanout_activity(create_act)
+
+        return create_act
+
+    def follow(self, target_actor_url: str) -> Mapping[str, Any]:
+        """Send a Follow request to a remote actor."""
+        act_id = f"{self.local_actor.actor_url}/activities/follow-{uuid.uuid4().hex[:12]}"
+        follow_act = build_follow_activity(
+            activity_id=act_id,
+            actor_uri=self.local_actor.actor_url,
+            target_actor_uri=target_actor_url,
+        )
+        self.store.record_activity(follow_act, direction='outbox')
+
+        remote_doc = self.remote_resolver(target_actor_url)
+        if remote_doc:
+            inbox_url = remote_doc.get('inbox')
+            if inbox_url:
+                try:
+                    self.deliver_to_inbox(inbox_url, follow_act)
+                except Exception:
+                    pass
+
+        return follow_act
+
+    def unfollow(self, target_actor_url: str) -> Mapping[str, Any]:
+        """Send an Undo Follow request to a remote actor."""
+        act_id = f"{self.local_actor.actor_url}/activities/undo-{uuid.uuid4().hex[:12]}"
+        follow_to_undo = build_follow_activity(
+            activity_id=f"{self.local_actor.actor_url}/activities/follow-temp",
+            actor_uri=self.local_actor.actor_url,
+            target_actor_uri=target_actor_url,
+        )
+        undo_act = build_undo_activity(
+            activity_id=act_id,
+            actor_uri=self.local_actor.actor_url,
+            activity_to_undo=follow_to_undo,
+            recipient_uri=target_actor_url,
+        )
+        self.store.record_activity(undo_act, direction='outbox')
+        self.store.remove_following(self.local_actor.actor_url, target_actor_url)
+
+        remote_doc = self.remote_resolver(target_actor_url)
+        if remote_doc:
+            inbox_url = remote_doc.get('inbox')
+            if inbox_url:
+                try:
+                    self.deliver_to_inbox(inbox_url, undo_act)
+                except Exception:
+                    pass
+
+        return undo_act
+
+    def _fanout_activity(self, activity_doc: Mapping[str, Any]) -> None:
+        """Deliver activity to all addressed inboxes and follower inboxes."""
+        inboxes_to_deliver: set[str] = set()
+
+        # Check explicit recipients in to/cc
+        recipients = list(activity_doc.get('to') or []) + list(activity_doc.get('cc') or [])
+        delivers_to_followers = False
+
+        for r in recipients:
+            if r == self.local_actor.followers_url:
+                delivers_to_followers = True
+            elif r != PUBLIC_COLLECTION:
+                doc = self.remote_resolver(r)
+                if doc and 'inbox' in doc:
+                    inboxes_to_deliver.add(doc['inbox'])
+
+        if delivers_to_followers:
+            followers = self.store.get_followers(self.local_actor.actor_url)
+            for f_uri in followers:
+                f_doc = self.remote_resolver(f_uri)
+                if f_doc and 'inbox' in f_doc:
+                    inboxes_to_deliver.add(f_doc['inbox'])
+
+        for inbox in inboxes_to_deliver:
+            try:
+                self.deliver_to_inbox(inbox, activity_doc)
+            except Exception:
+                pass

node/protocols/activitypub/media.py

@@ -0,0 +1,145 @@
+"""ActivityPub Media Attachment storage and Blossom BlobStore unification.
+
+Standard library only. Manages:
+- Storing and retrieving media attachments (images, audio, video, documents).
+- Content-addressed indexing using SHA-256 digests.
+- Direct unification with Fleetmesh Blossom BlobStore when available.
+- HTTP media serving endpoint with immutable caching headers.
+"""
+from __future__ import annotations
+
+import hashlib
+import urllib.request
+from typing import Any, Mapping, Optional
+
+from fleetmesh_core.conformance.errors import FleetmeshError
+
+__all__ = [
+    'ActivityPubMediaError',
+    'ActivityPubMediaManager',
+]
+
+
+class ActivityPubMediaError(FleetmeshError):
+    """Base error for media attachment operations."""
+
+
+class ActivityPubMediaManager:
+    """Manages media attachments with Blossom BlobStore integration."""
+
+    def __init__(
+        self,
+        base_url: str = "https://node.example.org",
+        blob_store: Optional[Any] = None,
+        max_bytes: int = 50 * 1024 * 1024,  # 50 MB
+    ):
+        self.base_url = base_url.rstrip('/')
+        self.blob_store = blob_store
+        self.max_bytes = max_bytes
+        # In-memory CAS fallback when BlobStore is not attached
+        self._memory_blobs: dict[str, bytes] = {}
+        self._media_types: dict[str, str] = {}
+
+    def store_attachment(
+        self,
+        data: bytes,
+        media_type: str = "application/octet-stream",
+        name: Optional[str] = None,
+    ) -> Mapping[str, Any]:
+        """Store binary attachment and produce ActivityStreams Document/Image descriptor."""
+        if len(data) > self.max_bytes:
+            raise ActivityPubMediaError(f"attachment exceeds maximum allowed size ({len(data)} > {self.max_bytes})")
+
+        sha256_hex = hashlib.sha256(data).hexdigest()
+
+        if self.blob_store is not None:
+            # Store in unified Blossom BlobStore
+            try:
+                self.blob_store.put(data, mime_type=media_type)
+            except Exception:
+                # If blob_store fails or lacks put signature, record locally
+                self._memory_blobs[sha256_hex] = data
+        else:
+            self._memory_blobs[sha256_hex] = data
+
+        self._media_types[sha256_hex] = media_type
+
+        # Classify ActivityStreams object type
+        as_type = "Document"
+        if media_type.startswith("image/"):
+            as_type = "Image"
+        elif media_type.startswith("video/"):
+            as_type = "Video"
+        elif media_type.startswith("audio/"):
+            as_type = "Audio"
+
+        media_url = f"{self.base_url}/media/{sha256_hex}"
+
+        doc = {
+            "type": as_type,
+            "mediaType": media_type,
+            "url": media_url,
+            "sha256": sha256_hex,
+            "size": len(data),
+        }
+        if name:
+            doc["name"] = name
+
+        return doc
+
+    def get_attachment(self, sha256_hex: str) -> tuple[Optional[bytes], Optional[str]]:
+        """Retrieve attachment binary data and mime-type."""
+        data = None
+        if self.blob_store is not None:
+            try:
+                data = self.blob_store.get(sha256_hex)
+            except Exception:
+                pass
+
+        if data is None:
+            data = self._memory_blobs.get(sha256_hex)
+
+        if data is None:
+            return None, None
+
+        media_type = self._media_types.get(sha256_hex, "application/octet-stream")
+        return data, media_type
+
+    def fetch_and_cache(
+        self,
+        url: str,
+        expected_sha256: Optional[str] = None,
+    ) -> Optional[Mapping[str, Any]]:
+        """Fetch remote media, verify digest, and cache locally."""
+        try:
+            req = urllib.request.Request(url, headers={'User-Agent': 'Fleetmesh-ActivityPub/1.0'})
+            with urllib.request.urlopen(req, timeout=10.0) as resp:
+                data = resp.read()
+                content_type = resp.headers.get_content_type() or "application/octet-stream"
+
+            sha256_hex = hashlib.sha256(data).hexdigest()
+            if expected_sha256 and sha256_hex.lower() != expected_sha256.lower():
+                return None
+
+            return self.store_attachment(data, media_type=content_type)
+        except Exception:
+            return None
+
+    def handle_media_request(self, path: str) -> tuple[int, dict[str, str], bytes]:
+        """Handle HTTP GET /media/<sha256> requests."""
+        parts = path.strip('/').split('/')
+        if len(parts) < 2 or parts[0] != 'media':
+            return 404, {'Content-Type': 'text/plain'}, b'Not found'
+
+        sha256_hex = parts[1]
+        data, media_type = self.get_attachment(sha256_hex)
+        if data is None:
+            return 404, {'Content-Type': 'text/plain'}, b'Media attachment not found'
+
+        headers = {
+            'Content-Type': media_type or 'application/octet-stream',
+            'Content-Length': str(len(data)),
+            'Cache-Control': 'public, max-age=31536000, immutable',
+            'ETag': f'"{sha256_hex}"',
+        }
+        return 200, headers, data