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