README

Integrate your MediaWiki instance with the Fediverse via ActivityPub.

Overview

ActivityWiki is a MediaWiki extension that enables wiki instances to participate in the Fediverse by implementing the ActivityPub W3C protocol. It allows Mastodon users and other Fediverse participants to follow your wiki and receive notifications when pages are created, edited, or deleted — directly in their Fediverse timeline.

ℹ️ Current status: v1.1.0 — first fully working release. Identity (actor + WebFinger), Security (HTTP Signatures, including a documented key rotation path), Publishing (outbound delivery to followers, with a real database-backed outbox), and Receiving (inbox, Follow/Undo handling, a real database-backed followers collection) are all complete and verified live against real Fediverse traffic (Mastodon). All five ActivityPub-spec-required endpoints — actor, WebFinger, outbox, followers, inbox — are implemented and working end-to-end. See the Roadmap section below for what's deferred as a post-release fast-follow.

Requirements

MediaWiki 1.41 or later
PHP 8.0 or later
MariaDB / MySQL
Apache or Nginx with the ability to add a rewrite rule (see WebFinger routing below — this is required, not optional)

Installation

Choose whichever of the two methods below fits how you manage your MediaWiki installation. Both end up in the same place — an ActivityWiki directory inside your extensions/ folder — so the remaining steps (2–4) are identical either way.

Option A — Clone from GitHub

cd /path/to/your/mediawiki/extensions
git clone https://github.com/lucamauri/ActivityWiki.git ActivityWiki

Option B — Install from Packagist via Composer

ActivityWiki is published on Packagist as lucamauri/activitywiki. This method only works if your MediaWiki installation is itself Composer-managed (i.e. you ran composer install at some point to set up core, rather than installing purely from a tarball/git clone with no composer.json at the wiki root — most modern installations qualify).

From your MediaWiki installation root (the directory containing the main composer.json, not the extensions/ directory):

composer require lucamauri/activitywiki

This package declares "type": "mediawiki-extension" in its own composer.json, which the composer/installers plugin (bundled with MediaWiki core's own composer.json by default) recognises and uses to place the extension's files directly into extensions/ActivityWiki/ automatically — no manual cloning or moving required.

If composer require fails with something like "could not find a matching version" or complains about missing composer/installers, your MediaWiki installation likely isn't Composer-managed at the root level. In that case, use Option A instead — there is no functional difference between the two once the files are in place.

To upgrade later, either method works the same way going forward: git pull for Option A, or composer update lucamauri/activitywiki for Option B.

2. Add to LocalSettings.php

wfLoadExtension( 'ActivityWiki' );

3. Run database setup

php maintenance/run.php update.php

4. Set up WebFinger routing

This step is required. Without it, the wiki is completely invisible to Fediverse search, even though every other endpoint works correctly. See WebFinger routing below for full instructions.

Configuration

All configuration variables are optional. The defaults are shown below.

// Master switch — disable to pause all federation without uninstalling
$wgActivityWikiEnabled = true;

// Display name shown on Mastodon and other Fediverse clients
// Defaults to $wgSitename if not set
$wgActivityWikiActorName = null;

// The handle for the wiki actor (the part before @domain)
// Defaults to a slugified $wgSitename if not set
$wgActivityWikiActorUsername = null;

// Short bio shown on Mastodon profile
$wgActivityWikiActorSummary = '';

// Absolute URL to the wiki logo used as the actor avatar
// Defaults to $wgFavicon if not set
$wgActivityWikiActorIcon = null;

// RSA key size in bits for HTTP Signature key pair generation
// Minimum 2048, recommended 4096
$wgActivityWikiKeySize = 2048;

// Namespaces to federate — default is main namespace only
$wgActivityWikiPublishNamespaces = [ NS_MAIN ];

// Which event types to federate
$wgActivityWikiPublishCreations   = true;
$wgActivityWikiPublishEdits       = true;
$wgActivityWikiPublishDeletions   = true;
$wgActivityWikiPublishMoves       = true;
$wgActivityWikiPublishMinorEdits  = false; // Minor edits suppressed by default
$wgActivityWikiPublishProtections = false;

// Maximum plain-text excerpt length in characters included in activities
$wgActivityWikiExcerptLength = 500;

// Number of retry attempts for failed HTTP deliveries (outbound activities
// and Accept replies alike)
$wgActivityWikiDeliveryRetries = 3;

// Maximum number of activities returned by the outbox endpoint
// (most recent first). Does not affect the reported "totalItems" count,
// which always reflects the true total number of activities.
$wgActivityWikiOutboxLimit = 20;

// Enable per-user ActivityPub actors. Post-MVP feature — do not enable
// in production; not yet implemented.
$wgActivityWikiEnableUserActors = false;

// Debug logging (0 = off, 1 = verbose)
$wgActivityWikiDebugLevel = 0;

To see ActivityWiki's debug log output, add a dedicated log channel in LocalSettings.php:

$wgDebugLogGroups['ActivityWiki'] = '/path/to/your/logs/ActivityWiki.log';

WebFinger routing

The WebFinger protocol (RFC 7033) requires that requests be served from a fixed, well-known path at the root of your domain:

https://yourdomain.org/.well-known/webfinger?resource=acct:user@yourdomain.org

This path is outside MediaWiki's normal URL space, and MediaWiki cannot serve it on its own. Setting this up correctly requires two things: a small entry-point script, and a web-server rewrite rule pointing to it. Both are described below.

Throughout this section, replace /path/to/your/wiki/ with wherever your MediaWiki installation actually lives (the directory containing rest.php), and replace /your-script-path/ with your own $wgScriptPath (e.g. /w, /wiki, or empty if MediaWiki is installed at your domain root). These vary per installation — there is no universal default.

Why a separate entry-point file is needed

MediaWiki's REST router validates that every incoming REQUEST_URI starts with the REST base path (e.g. /your-script-path/rest.php). A plain web-server-level rewrite from /.well-known/webfinger straight to the REST path is not enough on its own — the rewrite happens after PHP has already read $_SERVER['REQUEST_URI'], so MediaWiki's router still sees the original, unrewritten URI and rejects the request with a rest-prefix-mismatch error, even though the route and handler (WebFingerHandler) are correctly registered.

The fix is entry-points/webfinger.php, included with this extension. It corrects $_SERVER['REQUEST_URI'] itself before MediaWiki boots, then hands off entirely to rest.php. It contains no business logic of its own — all actual WebFinger handling still happens in WebFingerHandler.php.

Future improvement: A MediaWiki core patch to accept configurable REST base path validation would make this entry-point file unnecessary. Worth contributing upstream separately.

Step 1 — Copy the entry-point file and set your script path

Copy entry-points/webfinger.php from the extension to the same directory as rest.php:

cp extensions/ActivityWiki/entry-points/webfinger.php /path/to/your/wiki/webfinger.php

Open the copied file and confirm the rewritten path matches your $wgScriptPath:

$_SERVER['REQUEST_URI'] = '/your-script-path/rest.php/activitywiki/webfinger'
    . ( /* ...query string handling... */ );

Replace /your-script-path/ with your actual $wgScriptPath (for example, if $wgScriptPath = '/w', this line should read '/w/rest.php/activitywiki/webfinger').

Step 2 — Add the web-server rewrite rule

Apache

Add the following rule inside the <VirtualHost> block that serves your wiki, before any existing MediaWiki rewrite rules:

# ActivityWiki — WebFinger discovery endpoint
RewriteRule ^\.well-known/webfinger$ %{DOCUMENT_ROOT}/webfinger.php [QSA,L]

⚠️ Do not anchor the pattern with a leading /. Inside a <VirtualHost> block (as opposed to an .htaccess file), Apache's RewriteRule matches the URL path without a leading slash. A pattern written as ^/\.well-known/webfinger$ will never match — Apache will silently fall through to its normal file-serving logic and return a generic Apache 404 page, with nothing logged anywhere that points to the actual cause. If %{DOCUMENT_ROOT}/webfinger.php is not where you copied the file in Step 1 (for example, if your DocumentRoot is a parent directory of your wiki installation rather than the installation directory itself), adjust the target path accordingly.

The QSA flag (Query String Append) passes the ?resource=... parameter through. The L flag stops further rule processing for this request.

Nginx

Add the following to your server block:

# ActivityWiki — WebFinger discovery endpoint
location = /.well-known/webfinger {
    fastcgi_param REQUEST_URI /your-script-path/rest.php/activitywiki/webfinger;
    fastcgi_param QUERY_STRING $query_string;
    # ... your existing fastcgi_pass and other fastcgi_param settings
}

Replace /your-script-path/ with your $wgScriptPath, matching Step 1. This approach rewrites REQUEST_URI directly via FastCGI parameters, so the entry-points/webfinger.php file is not needed for the Nginx path.

Behind a reverse proxy (Anubis, Varnish, Cloudflare, etc.)

If your setup uses a reverse proxy in front of your web server, make sure /.well-known/ paths are passed through without being blocked or challenged. Most proxy configurations already allow this for Let's Encrypt compatibility, but bot-detection layers (e.g. Anubis) can sometimes intercept paths that look unusual. If WebFinger works when tested directly against your web server but not from the public internet, check your proxy's passthrough or allow-list rules for /.well-known/.

Step 3 — Reload your web server

sudo systemctl reload apache2   # or: sudo systemctl reload nginx

Step 4 — Verify

Request the well-known URL directly:

curl -v "https://yourdomain.org/.well-known/webfinger?resource=acct:yourusername@yourdomain.org"

A correct response is 200 OK, with Content-Type: application/jrd+json, and a JSON body shaped like:

{
    "subject": "acct:yourusername@yourdomain.org",
    "aliases": [
        "https://yourdomain.org/your-script-path/rest.php/activitywiki/actor"
    ],
    "links": [
        {
            "rel": "self",
            "type": "application/activity+json",
            "href": "https://yourdomain.org/your-script-path/rest.php/activitywiki/actor"
        },
        {
            "rel": "http://webfinger.net/rel/profile-page",
            "type": "text/html",
            "href": "https://yourdomain.org/your-script-path/index.php"
        }
    ]
}

An unrecognized resource correctly returns a 404 with a small JSON error body (e.g. {"error":"Resource not found on this server."}) — that's expected and fine.

Troubleshooting

Symptom	Likely cause	Fix
`404 Not Found`, `Content-Type: text/html`, Apache/Nginx server signature in the body	Rewrite rule isn't matching — most commonly the leading-slash mistake described above	Check the `RewriteRule`/`location` pattern; confirm it's in the `<VirtualHost>` block that actually serves your public HTTPS traffic
`500`, JSON body mentioning `rest-prefix-mismatch`	`entry-points/webfinger.php` missing, in the wrong location, or its hardcoded script path doesn't match `$wgScriptPath`	Re-check Step 1
`500`, JSON body mentioning `ArgumentCountError` or similar	`routes.json`'s `webfinger` route is missing a required service, or extension files are out of date	Confirm you're running the current version of the extension; check `routes.json` lists all services `WebFingerHandler`'s constructor requires
Works when curled directly against the server but not from the public internet	A reverse proxy is intercepting or challenging the request	Check your proxy's passthrough rules for `/.well-known/`
`404` with a small JSON body (not HTML)	This is MediaWiki's own "resource not found" response	Check that the `resource` parameter's username and domain match your actual `$wgActivityWikiActorUsername` and `$wgServer`

Key rotation

ActivityWiki's HTTP Signature key pair (used to sign every outbound activity, and served publicly as part of the actor object) is generated automatically on first install — you don't need to do anything for normal operation. A dedicated maintenance script, maintenance/GenerateKeys.php, exists for two situations:

First-time setup didn't generate a key for some reason (e.g. it was skipped, or OpenSSL failed at that point and you've since fixed the underlying cause). Running the script with no key present is safe and non-destructive.
Deliberate rotation — e.g. you suspect the private key has been compromised, or you've increased $wgActivityWikiKeySize and want to regenerate. This is destructive: the existing key pair is replaced, and is gated behind an explicit --force flag so it can never happen by accident.

# First-time generation, or check current state (safe, no key yet):
php maintenance/run.php extensions/ActivityWiki/maintenance/GenerateKeys.php

# Deliberate rotation of an existing key:
php maintenance/run.php extensions/ActivityWiki/maintenance/GenerateKeys.php --force

# Rotation, printing the new public key PEM afterward for verification:
php maintenance/run.php extensions/ActivityWiki/maintenance/GenerateKeys.php --force --show

⚠️ Rotation is immediate and has real consequences. The moment the new key is stored, every outbound HTTP Signature is signed with it. Any Fediverse server that has cached your old public key (some do cache aggressively) may continue rejecting your signed requests until that cache expires on their end — there is no way to force this from your side. This is expected and self-resolves; it is not a bug in the rotation itself.

Restart PHP-FPM after running the script, as a precaution (the script will remind you).

Repository Structure

ActivityWiki/
├── extension.json              # Extension metadata, config, and service/job wiring
├── composer.json                # PHP dependencies
├── README.md                    # This file
├── entry-points/
│   └── webfinger.php            # Required manual install step — see WebFinger routing
├── i18n/                         # Localisation files
├── src/
│   ├── ServiceWiring.php        # Registers all ActivityWiki services
│   ├── Hooks.php                 # Page save/edit/delete event hooks
│   ├── ActivityBuilder.php       # Builds outbound ActivityPub activity arrays
│   ├── WikiActorUrls.php         # Shared wiki base-URL / actor-URL building logic
│   │                              #   (consolidated from four classes)
│   ├── ActorFetcher.php          # Shared remote actor document fetching
│   │                              #   (consolidated from SignatureVerifier/FollowManager)
│   ├── DeliveryQueue.php         # Persists outbound activities, enqueues delivery jobs
│   ├── KeyManager.php            # RSA key pair generation and storage
│   ├── HttpSigner.php            # Signs outbound HTTP requests
│   ├── SignatureVerifier.php     # Verifies incoming HTTP Signatures
│   ├── FollowManager.php         # Follow/Undo business logic for the inbox
│   ├── Api/
│   │   └── ActivityPubModule.php # Shared actor/URL-building helpers
│   ├── Jobs/
│   │   ├── DeliveryJob.php       # Async fan-out delivery to all followers
│   │   └── AcceptJob.php         # Async single-recipient delivery (Accept replies)
│   └── Rest/
│       ├── ActorHandler.php      # GET  /activitywiki/actor
│       ├── WebFingerHandler.php  # GET  /activitywiki/webfinger
│       ├── OutboxHandler.php     # GET  /activitywiki/outbox (real data, see $wgActivityWikiOutboxLimit)
│       ├── FollowersHandler.php  # GET  /activitywiki/followers (real data)
│       ├── InboxHandler.php      # POST /activitywiki/inbox
│       └── routes.json           # REST route definitions
├── db/                            # Database schema files
└── maintenance/
    └── GenerateKeys.php           # Manual key (re)generation — see Key rotation

Roadmap

Phase 0 — Audit fixes ✅ Complete

Fixed all blockers and compatibility issues found in the initial audit
Modernised deprecated MW API calls
Renamed all config keys to the ActivityWiki* prefix

Phase 1 — Identity ✅ Complete

Actor object endpoint
WebFinger endpoint for Fediverse discoverability

Phase 2 — Security ✅ Complete

RSA key pair generation and storage
HTTP Signature signing on all outbound requests

Phase 3 — Publishing ✅ Complete

Full event hook coverage (create, edit, delete, move)
Async HTTP delivery to follower inboxes, with per-follower retry
Outbox endpoint completion

Phase 4 — Receiving ✅ Complete

Inbox endpoint
Follow / Undo{Follow} handling
Followers collection serving real, database-backed data

Phase 5 — Administration & consolidation ✅ Mostly complete

Shared URL-building logic consolidated into WikiActorUrls
Shared remote actor fetching consolidated into ActorFetcher
Real database-backed outbox ($wgActivityWikiOutboxLimit)
maintenance/GenerateKeys.php — manual key generation and --force-gated rotation (see Key rotation)
Still planned: Special:ActivityWiki status page and MediaWiki log integration (see Post-release fast-follows below)

Post-release fast-follows (not blockers)

Actor caching (activitywiki_actor_cache)
Full outbox pagination (OrderedCollectionPage with first/next/prev links) — the outbox currently returns the most recent activities up to $wgActivityWikiOutboxLimit, with an accurate totalItems, but no cursor pagination
Special:ActivityWiki status page and related MediaWiki log integration

Post-MVP (deferred, not scoped)

Per-user ActivityPub actors ($wgActivityWikiEnableUserActors)
Extended inbox activity handling (Like, Announce, reply mentions)

Troubleshooting

Check the actor endpoint is reachable

curl -H "Accept: application/activity+json" "https://yourdomain.org/your-script-path/rest.php/activitywiki/actor"

Should return actor JSON, not a 404.

Check WebFinger is reachable at the public well-known path

curl -v "https://yourdomain.org/.well-known/webfinger?resource=acct:yourusername@yourdomain.org"

See the WebFinger routing troubleshooting table above if this doesn't return a correct JSON response.

Check debug logs

Set $wgActivityWikiDebugLevel = 1; and configure a log channel (see Configuration above), then:

tail -f /path/to/your/logs/ActivityWiki.log

License

GPL-2.0-or-later. See LICENSE file for details.

References

In the spirit of IDIC 🖖🏻 forged at WikiTrek, shared freely with the Galaxy

lucamauri / activitywiki

Maintainers

Package info

Statistics

Security

README

Overview

Requirements

Installation

Option A — Clone from GitHub

Option B — Install from Packagist via Composer

2. Add to LocalSettings.php

3. Run database setup

4. Set up WebFinger routing

Configuration

WebFinger routing

Why a separate entry-point file is needed

Step 1 — Copy the entry-point file and set your script path

Step 2 — Add the web-server rewrite rule

Apache

Nginx

Behind a reverse proxy (Anubis, Varnish, Cloudflare, etc.)

Step 3 — Reload your web server

Step 4 — Verify

Troubleshooting

Key rotation

Repository Structure

Roadmap

Phase 0 — Audit fixes ✅ Complete

Phase 1 — Identity ✅ Complete

Phase 2 — Security ✅ Complete

Phase 3 — Publishing ✅ Complete

Phase 4 — Receiving ✅ Complete

Phase 5 — Administration & consolidation ✅ Mostly complete

Post-release fast-follows (not blockers)

Post-MVP (deferred, not scoped)

Troubleshooting

Check the actor endpoint is reachable

Check WebFinger is reachable at the public well-known path

Check debug logs

License

References