Source code for fleetmesh_node.protocols.activitypub.federation

"""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 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 fleetmesh_node.protocols.activitypub.actor import Actor
from fleetmesh_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 fleetmesh_node.protocols.activitypub.store import ActivityPubStore
from fleetmesh_node.transport import netfetch

__all__ = [
    'FederationError',
    'StrainThrottledError',
    'StrainScoreKeeper',
    'FederationService',
    'is_safe_federation_url',
]

MAX_INBOX_BODY_BYTES = 10 * 1024 * 1024  # 10 MB
# An actor document is a JSON-LD object with a PEM or two; 1 MiB is already
# an order of magnitude more than any real one, and it stops a hostile
# server from streaming us a large body while we parse it.
MAX_ACTOR_DOC_BYTES = 1 * 1024 * 1024
# A delivery answer is a 202 with no body, or a small error JSON.
MAX_DELIVERY_RESPONSE_BYTES = 64 * 1024


[docs]def is_safe_federation_url(url: str, allow_local: bool = False) -> bool: """Validate whether an outbound federation target URL is safe against SSRF attacks. This is the pre-netfetch check kept for callers that only want a cheap answer before doing work; the request itself still goes through ``netfetch.fetch``, which re-checks scheme, address and redirects. With ``allow_local`` (operator opt-in for a local/LAN dev fleet) any http(s) URL passes here, and netfetch's address policy is what actually refuses the private ones. """ 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
[docs]class FederationError(FleetmeshError): """Base error for federation processing."""
[docs]class StrainThrottledError(FederationError): """Raised when an abusive or high-strain host is temporarily throttled."""
[docs]class StrainScoreKeeper: """Tracks verification failures per peer host to mitigate DoS and invalid traffic. Integrates optionally with Fleetmesh StrainLedger. """
[docs] 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
[docs] 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
[docs] 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)
[docs] 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)
[docs]class FederationService: """ActivityPub S2S Federation handler and outbound delivery engine."""
[docs] 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 = False, ): """``allow_local_federation`` is the operator's explicit opt-in for federating with a peer on a loopback/LAN address (a local dev fleet, or two nodes on one host). It defaults off: the actor document and inbox URLs we fetch come from remote signatures, so by default a peer must not be able to point this node at 127.0.0.1 or 169.254.169.254. It is passed to netfetch as ``allow_private`` for exactly those two fetches; nothing a remote peer sends can turn it on. """ 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 # The URL comes from an inbound signature's keyId, so whoever sent the # request chose it. It gets the full netfetch policy: http/https only, # no loopback/private/link-local/metadata address (redirects included), # and a body cap. allow_private follows the operator's explicit # local-federation opt-in only -- never anything a peer controls. try: body, _ = netfetch.fetch( actor_url, max_bytes=MAX_ACTOR_DOC_BYTES, timeout=10.0, headers={'Accept': 'application/activity+json, application/ld+json'}, allow_private=self.allow_local_federation, ) data = json.loads(body.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]: """Deliver a signed activity through the guarded fetcher. The inbox URL comes from the recipient's actor document, i.e. the peer chooses it; same policy as the actor fetch. netfetch only returns a body for a 2xx, so a return here is a success (200) and a rejection is the remote's status and error body, which is what callers log. """ try: res_body, _ = netfetch.fetch( url, max_bytes=MAX_DELIVERY_RESPONSE_BYTES, timeout=15.0, method='POST', data=body, headers=headers, allow_private=self.allow_local_federation, ) except netfetch.FetchHTTPError as e: return e.code, e.body return 200, res_body
[docs] 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 # -------------------------------------------------------------------------
[docs] 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 # -------------------------------------------------------------------------
[docs] 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)
[docs] 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
[docs] 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
[docs] 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