Swarm/docs/activitypub/ACTIVITYPUB_IMPLEMENTATION.md

ActivityPub Implementation for Solar Network

Overview

This document outlines the initial implementation of ActivityPub federation for the Solar Network (DysonNetwork), following the plan outlined in ACTIVITYPUB_PLAN.md.

What Has Been Created

1. Database Models (DysonNetwork.Shared/Models)

All ActivityPub-related models are shared across projects and located in DysonNetwork.Shared/Models/:

FediverseInstance.cs

• Tracks ActivityPub instances (servers) in the fediverse
• Stores instance metadata, blocking status, and activity tracking
• Links to actors and content from that instance

FediverseActor.cs

• Represents remote actors (users/accounts) from other instances
• Stores actor information including keys, inbox/outbox URLs
• Links to instance and manages relationships
• Tracks whether the actor is a bot, locked, or discoverable

FediverseContent.cs

• Stores content (posts, notes, etc.) received from the fediverse
• Supports multiple content types (Note, Article, Image, Video, etc.)
• Includes attachments, mentions, tags, and emojis
• Links to local posts for unified display

FediverseActivity.cs

• Tracks ActivityPub activities (Create, Follow, Like, Announce, etc.)
• Stores raw activity data and processing status
• Links to actors, content, and local entities
• Supports both incoming and outgoing activities

FediverseRelationship.cs

• Manages follow relationships between local and remote actors
• Tracks relationship state (Pending, Accepted, Rejected)
• Supports muting and blocking
• Links to local accounts/publishers

FediverseReaction.cs

• Stores reactions (likes, emoji) from both local and remote actors
• Links to content and actor
• Supports federation of reactions

2. Database Migration

File: DysonNetwork.Sphere/Migrations/20251228120000_AddActivityPubModels.cs

This migration creates the following tables:

• fediverse_instances - Instance tracking
• fediverse_actors - Remote actor profiles
• fediverse_contents - Federated content storage
• fediverse_activities - Activity tracking and processing
• fediverse_relationships - Follow relationships
• fediverse_reactions - Reactions from fediverse

3. API Controllers (DysonNetwork.Sphere/ActivityPub)

WebFingerController.cs

• Endpoint: GET /.well-known/webfinger?resource=acct:<username>@<domain>
• Purpose: Allows other instances to discover actors via WebFinger protocol
• Response: Returns actor's inbox/outbox URLs and profile page links
• Maps local Publishers to ActivityPub actors

ActivityPubController.cs

Provides three main endpoints:

1. GET /activitypub/actors/{username}

   • Returns ActivityPub actor profile in JSON-LD format
   • Includes actor's keys, inbox, outbox, followers, and following URLs
   • Maps SnPublisher to ActivityPub Person type

2. GET /activitypub/actors/{username}/outbox

   • Returns actor's outbox collection
   • Lists public posts as ActivityPub activities
   • Supports pagination

3. POST /activitypub/actors/{username}/inbox

   • Receives incoming ActivityPub activities
   • Supports Create, Follow, Like, Announce activities
   • Placeholder for activity processing logic

Architecture

Data Flow

Remote Instance           Solar Network (Sphere)
    │                          │
    │  ───WebFinger─────>    │
    │                          │
    │  <───Actor JSON────       │
    │                          │
    │  ───Activity─────>      │  → Inbox Processing
    │                          │
    │  <───Activity──────       │  ← Outbox Distribution

Model Relationships

• SnFediverseInstance has many SnFediverseActor
• SnFediverseInstance has many SnFediverseContent
• SnFediverseActor has many SnFediverseContent
• SnFediverseActor has many SnFediverseActivity
• SnFediverseActor has many SnFediverseRelationship (as follower and following)
• SnFediverseContent has many SnFediverseActivity
• SnFediverseContent has many SnFediverseReaction
• SnFediverseContent optionally links to SnPost (local copy)

Local to Fediverse Mapping

Solar Network Model	ActivityPub Type
SnPublisher	Person (Actor)
SnPost	Note / Article
SnPostReaction	Like / EmojiReact
Follow	Follow Activity
SnPublisherSubscription	Follow Relationship

Next Steps

Stage 1: Core Infrastructure ✅ (COMPLETED)

• ✅ Create database models for ActivityPub entities
• ✅ Create database migration
• ✅ Implement basic WebFinger endpoint
• ✅ Implement basic Actor endpoint
• ✅ Implement Inbox/Outbox endpoints

Stage 2: Activity Processing ✅ (COMPLETED)

• ✅ Implement HTTP Signature verification (ActivityPubSignatureService)
• ✅ Process incoming activities:
  • Follow/Accept/Reject
  • Create (incoming posts)
  • Like/Announce
  • Delete/Update
  • Undo
• ✅ Generate outgoing activities (ActivityPubDeliveryService)
• ✅ Queue and retry failed deliveries (basic implementation)

Stage 3: Key Management ✅ (COMPLETED)

• ✅ Generate RSA key pairs for each Publisher (ActivityPubKeyService)
• ✅ Store public/private keys in Publisher.Meta
• ✅ Sign outgoing HTTP requests
• ✅ Verify incoming HTTP signatures

Stage 4: Content Federation (IN PROGRESS)

• ✅ Convert between SnPost and ActivityPub Note/Article (basic mapping)
• ✅ Handle content attachments and media
• ✅ Support content warnings and sensitive content
• ✅ Handle replies, boosts, and mentions
• ⏳ Add local post reference for federated content
• ⏳ Handle media attachments in federated content

Stage 5: Relationship Management ✅ (COMPLETED)

• ✅ Handle follow/unfollow logic
• ✅ Update followers/following collections
• ✅ Block/mute functionality (data model ready)
• ✅ Relationship state machine (Pending, Accepted, Rejected)

Stage 6: Testing & Interop (NEXT)

• ⏳ Test with Mastodon instances
• ⏳ Test with Pleroma/Akkoma instances
• ⏳ Test with Lemmy instances
• ⏳ Verify WebFinger and actor discovery
• ⏳ Test activity delivery and processing

Implementation Details

Core Services

1. ActivityPubKeyService

• Generates RSA 2048-bit key pairs for ActivityPub
• Signs data with private key
• Verifies signatures with public key
• Key stored in SnPublisher.Meta["private_key"] and ["public_key"]

2. ActivityPubSignatureService

• Verifies incoming HTTP Signature headers
• Signs outgoing HTTP requests
• Manages key retrieval and storage
• Builds signing strings according to ActivityPub spec

3. ActivityPubActivityProcessor

• Processes all incoming activity types
• Follow: Creates relationship, sends Accept
• Accept: Updates relationship to accepted state
• Reject: Updates relationship to rejected state
• Create: Stores federated content
• Like: Records like reaction
• Announce: Increments boost count
• Undo: Reverts previous actions
• Delete: Soft-deletes federated content
• Update: Marks content as edited

4. ActivityPubDeliveryService

• Sends Follow activities to remote instances
• Sends Accept activities in response to follows
• Sends Create activities (posts) to followers
• Sends Like activities to remote instances
• Sends Undo activities
• Fetches remote actor profiles on-demand

Data Flow

Incoming Activity Flow

Remote Server → HTTP Signature Verification → Activity Type → Specific Handler
                                                       ↓
                                          Database Update & Response

Outgoing Activity Flow

Local Action → Create Activity → Sign with Key → Send to Followers' Inboxes
                                   ↓
                            Track Status & Retry

Configuration

Add to appsettings.json:

{
  "ActivityPub": {
    "Domain": "your-domain.com",
    "EnableFederation": true
  }
}

Database Migration

To apply the migration:

cd DysonNetwork.Sphere
dotnet ef database update

Testing

WebFinger

curl "https://your-domain.com/.well-known/webfinger?resource=acct:username@your-domain.com"

Actor Profile

curl -H "Accept: application/activity+json" https://your-domain.com/activitypub/actors/username

Outbox

curl -H "Accept: application/activity+json" https://your-domain.com/activitypub/actors/username/outbox

Notes

• All models follow the existing Solar Network patterns (ModelBase, NodaTime, JSON columns)
• Controllers use standard ASP.NET Core patterns with dependency injection
• Database uses PostgreSQL with JSONB for flexible metadata storage
• Migration follows existing naming conventions
• Soft delete is enabled on all models

References

• ActivityPub W3C Recommendation
• ActivityStreams 2.0
• WebFinger RFC 7033
• Mastodon Federation Documentation

TODOs

• Implement HTTP Signature verification middleware
• Create activity processor service
• Implement activity queue and retry logic
• Add key generation for Publishers
• Implement content conversion between formats
• Add inbox background worker
• Add outbox delivery worker
• Implement relationship management logic
• Add moderation tools for federated content
• Add federation metrics and monitoring
• Write comprehensive tests