ActivityPub Implementation Guide

This document explains the ActivityPub and WebFinger implementation in the Email Blog platform.

ActivityPub is a decentralized social networking protocol that allows your blog to be discovered and followed from Mastodon, Pleroma, and other federated social networks. WebFinger is the discovery mechanism that allows users to find your blog using familiar @username@domain.com syntax.

• Endpoint: /.well-known/webfinger
• Formats Supported:
  • acct:blog@your-domain.com
  • https://your-domain.com/actor
• Response: JSON Resource Descriptor (JRD) format
• CORS: Enabled for cross-origin requests

• Endpoint: /actor
• Type: Person
• Username: blog
• Content-Type: application/activity+json

• Outbox (/outbox): Published blog posts as ActivityPub Create activities
• Followers (/followers): Collection of followers (placeholder)
• Following (/following): Collection of accounts being followed (placeholder)
• Inbox (/inbox): Receives ActivityPub activities (basic implementation)

# Optional: Set a custom domain for ActivityPub
ACTIVITYPUB_DOMAIN=your-custom-domain.com

If not set, the system will automatically detect the domain from the request headers.

1. Using WebFinger format: Search for @blog@your-domain.com in your Mastodon client
2. Using direct URL: Paste https://your-domain.com/actor in the search box

# Test with acct format
curl "https://your-domain.com/.well-known/webfinger?resource=acct:blog@your-domain.com"

# Test with direct URL format  
curl "https://your-domain.com/.well-known/webfinger?resource=https://your-domain.com/actor"

# Get actor document
curl -H "Accept: application/activity+json" https://your-domain.com/actor

# Get outbox (published posts)
curl -H "Accept: application/activity+json" https://your-domain.com/outbox

# Get followers collection
curl -H "Accept: application/activity+json" https://your-domain.com/followers

{
  "subject": "acct:blog@your-domain.com",
  "aliases": [
    "https://your-domain.com/actor",
    "https://your-domain.com/"
  ],
  "properties": {
    "http://schema.org/name": "Email Blog"
  },
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://your-domain.com/"
    },
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://your-domain.com/actor"
    },
    {
      "rel": "http://ostatus.org/schema/1.0/subscribe",
      "template": "https://your-domain.com/authorize_interaction?uri={uri}"
    }
  ]
}

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1"
  ],
  "type": "Person",
  "id": "https://your-domain.com/actor",
  "preferredUsername": "blog",
  "name": "Email Blog",
  "summary": "A blog powered by email publishing",
  "url": "https://your-domain.com",
  "inbox": "https://your-domain.com/inbox",
  "outbox": "https://your-domain.com/outbox",
  "followers": "https://your-domain.com/followers",
  "following": "https://your-domain.com/following",
  "publicKey": {
    "id": "https://your-domain.com/actor#main-key",
    "owner": "https://your-domain.com/actor",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\\n...\\n-----END PUBLIC KEY-----"
  }
}

When you publish a blog post via email, it automatically becomes available in the ActivityPub outbox as a Create activity:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Create",
  "id": "https://your-domain.com/post/my-post#create",
  "actor": "https://your-domain.com/actor",
  "published": "2024-01-01T12:00:00Z",
  "object": {
    "type": "Note",
    "id": "https://your-domain.com/post/my-post#note",
    "attributedTo": "https://your-domain.com/actor",
    "content": "<h2>My Post Title</h2><p>Post content...</p>",
    "published": "2024-01-01T12:00:00Z",
    "url": "https://your-domain.com/post/my-post",
    "to": ["https://www.w3.org/ns/activitystreams#Public"]
  }
}

1. No HTTP Signatures: Authentication is not yet implemented
2. No Follow Processing: The inbox doesn't process Follow activities yet
3. No Push Notifications: New posts aren't automatically pushed to followers
4. Placeholder Collections: Followers/following collections are empty
5. No Public Key: The public key in the actor document is a placeholder

1. HTTP Signatures: Implement cryptographic signatures for authentication
2. Follow Management: Process Follow/Unfollow activities
3. Push Delivery: Send new posts to followers' inboxes
4. Database Storage: Store followers and following relationships
5. Key Generation: Generate and manage cryptographic keys
6. Rich Content: Support for images, mentions, and hashtags

Use the /test-activitypub.ts endpoint to verify all ActivityPub endpoints are working correctly.

• ActivityPub Specification
• WebFinger Specification
• ActivityStreams Vocabulary
• Mastodon API Documentation

Your blog is now discoverable and followable from the fediverse! 🎉