Skip to content

ActivityPub Federation

Ankit Upadhyay edited this page Aug 25, 2026 · 1 revision

ActivityPub Federation

Clinic-to-clinic federation over the ActivityPub protocol: verified clinics on any Yosemite Crew instance can discover each other in a network directory, follow peers, exchange patient referrals, and broadcast to followers - without a central hub. The subsystem landed in 2026-08 and lives entirely behind the backend API; the code is canonical, this page is the map.

The landed surface

Area What is there Where
Protocol services Actor management, follow/accept/reject, referrals, notes, announces, outbox/directory activitypub.service.ts
HTTP endpoints WebFinger + actor documents, inbox/shared-inbox, outbox, and authenticated /manage/* routes (follows, referrals, directory listing) activitypub.router.ts · activitypub.controller.ts
HTTP signatures Per-actor RSA keys (private keys stored encrypted); requests signed on delivery and signature + body digest verified on receipt activitypub-crypto.service.ts · http-signature.ts
Async delivery Inbound and outbound activities are processed through BullMQ queues and workers ap-delivery.queue.ts · ap-inbox.service.ts
Data model APActor, APFollower, APFollowing, APRemoteActor, APActivity, APReferral in the Prisma schema; the migration enables row-level security on every table it creates schema.prisma · migration
Frontend Network directory at /network plus a federation section in Settings (directory listing toggle) features/federation/ · FederationSection.tsx

Trust model

  • Only verified organisations federate. Organization.isVerified is derived from an active Stripe Connect account (able to accept payments) plus at least one compliance certificate; a manual override by the platform always wins (organization-verification.service.ts). An organisation must be verified before it can be listed in the federation directory.
  • Instances are license-gated. Every outbound activity requires a valid federation license token for the instance (ap-license.service.ts).
  • Referrals require an accepted link. A clinic must follow a peer and be accepted before referrals can flow; inbound referral payloads are Zod-validated rather than trusted.

Security posture

  • SSRF and DNS-rebinding defences on every outbound fetch. ap-url-guard.ts requires https, rejects hosts resolving to loopback/private/link-local/metadata/CGNAT and equivalent IPv6 ranges (including v4-mapped and NAT64 forms), and a shared HTTPS agent re-validates the resolved IP at socket-connect time, closing the window where a host resolves publicly during validation but internally at connection.
  • Directed activities stay private. The unauthenticated outbox serves only publicly addressed activities; referral Offers carry clinical context and are never exposed there.
  • Agent-to-agent task protocol. A yc:AgentTask extension (an Offer-wrapped task object) lets instances query each other programmatically; v1 is limited to read-only capability and availability queries (activitypub-builder.ts).

Related

Product & Domain
Architecture
Applications
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Roadmap
Operations
Meta

Canonical code & docs: main repo · Auto-generated companion: DeepWiki

Clone this wiki locally