@oxy.so/federation 1.0.0

package/dist/esm/node/actorRouter.js

@@ -0,0 +1,304 @@
+/**
+ * The ActivityPub actor + inbox + follow-graph router.
+ *
+ * Serves the engine-owned half of the `/ap` namespace:
+ *  - `GET /users/:username` — the local `Person` actor (and the special `instance`
+ *    Application actor used for signed fetches),
+ *  - `POST /users/:username/inbox` + `POST /inbox` — inbound delivery, with HTTP
+ *    signature verification (Phase 2, `trustForwardedHost`) and actor-match, then
+ *    202 + async dispatch to the injected inbound dispatcher,
+ *  - `GET /users/:username/followers` + `/following` — the OXY follow graph
+ *    (local + bridged federated edges) as paginated `OrderedCollection`s.
+ *
+ * The CONTENT routes (`outbox`, `featured`, per-post dereference) stay in the app,
+ * mounted on the SAME `/ap/users/:username/*` prefix the actor advertises.
+ *
+ * Extracted behaviour-identically from Mention's `ap.routes.ts`. Everything
+ * app-specific — the actor's Oxy profile, the banner, the fediverse-sharing gate,
+ * the public-key lookup, the inbox enqueue transport, the follow-graph page fetch
+ * — is injected.
+ */
+import { Router } from 'express';
+import { AP_CONTEXT } from '../apContext.js';
+import { verifyHttpSignature } from '../httpSignature.js';
+import { INSTANCE_ACTOR_USERNAME, normalizeActorUsername } from '../urls.js';
+/** Page size for the paginated followers/following collections (mirrors the outbox). */
+const FOLLOW_PAGE_SIZE = 20;
+/** Extract the `:username` param safely as a string. */
+function getUsername(req) {
+    const val = req.params.username;
+    const raw = typeof val === 'string' ? val : Array.isArray(val) ? val[0] : String(val);
+    return normalizeActorUsername(raw);
+}
+/**
+ * Map a follow-graph member (an Oxy `User`) to its ActivityPub actor URI:
+ *  - a LOCAL Oxy/Mention user → our minted actor URL,
+ *  - a FEDERATED user → the remote actor URI on `federation.actorUri`.
+ * Returns null when unmappable (skip — never emit a raw oxyUserId as an actor id).
+ */
+function memberActorUri(user, urls) {
+    const isFederated = user.type === 'federated' || user.isFederated === true;
+    if (isFederated) {
+        const uri = user.federation?.actorUri;
+        return typeof uri === 'string' && uri.length > 0 ? uri : null;
+    }
+    const { username } = user;
+    return typeof username === 'string' && username.length > 0 ? urls.actor(username) : null;
+}
+/** Parse a non-negative page offset from the request query (missing/invalid ⇒ 0). */
+function parseFollowOffset(raw) {
+    const value = typeof raw === 'string' ? Number.parseInt(raw, 10) : Number.NaN;
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+/** Build the actor + inbox + follow-graph router for an app's domain. */
+export function createActorRouter(config) {
+    const router = Router();
+    const { urls, domain, apContentType, logger } = config;
+    function wantsActivityPub(req) {
+        return config.wantsActivityPub(req.headers.accept);
+    }
+    /** Common inbox handler with HTTP signature verification. */
+    async function handleInbox(req, res) {
+        try {
+            // Verify HTTP signature (use originalUrl to avoid proxy path mangling).
+            const { verified, actorUri, reason: signatureError } = await verifyHttpSignature({
+                method: req.method,
+                path: req.originalUrl || req.path,
+                headers: req.headers,
+                body: req.rawBody ?? req.body,
+            }, (keyId) => config.inbound.fetchPublicKey(keyId), {
+                trustForwardedHost: config.inbound.trustForwardedHost,
+                onDebug: (message, detail) => logger.debug(message, detail),
+            });
+            if (!verified || !actorUri) {
+                logger.debug('Inbox: HTTP signature verification failed', { reason: signatureError });
+                return res.status(401).json({ error: 'Invalid signature' });
+            }
+            const activity = req.body;
+            if (!activity || !activity.type) {
+                return res.status(400).json({ error: 'Invalid activity' });
+            }
+            // Verify the actor in the activity matches the signature.
+            const activityActor = typeof activity.actor === 'string' ? activity.actor : activity.actor?.id;
+            if (activityActor !== actorUri) {
+                logger.debug(`Inbox: Actor mismatch. Signed: ${actorUri}, Activity: ${activityActor}`);
+                return res.status(403).json({ error: 'Actor mismatch' });
+            }
+            // Process asynchronously — return 202 Accepted immediately. Durable path:
+            // enqueue onto BullMQ keyed by the activity id (dedupe). When the queue is
+            // unavailable (Redis not configured) OR the activity has no stable id to
+            // dedupe on, fall back to inline fire-and-forget processing so the activity
+            // is never dropped.
+            let enqueued = false;
+            try {
+                enqueued = await config.inbound.enqueueInboxActivity({ activity, verifiedActorUri: actorUri });
+            }
+            catch (err) {
+                logger.error('Failed to enqueue inbox activity — processing inline:', err);
+                enqueued = false;
+            }
+            if (!enqueued) {
+                config.inbound.processInboxActivity(activity, actorUri).catch((err) => {
+                    logger.error('Error processing inbox activity:', err);
+                });
+            }
+            return res.status(202).json({ status: 'accepted' });
+        }
+        catch (err) {
+            logger.error('Inbox error:', err);
+            return res.status(500).json({ error: 'Internal server error' });
+        }
+    }
+    /**
+     * Serve a user's followers OR following as a paginated `OrderedCollection` over
+     * the authoritative Oxy follow graph (local + bridged federated edges).
+     */
+    async function serveFollowCollection(req, res, direction, collectionUrl) {
+        if (!config.federationEnabled)
+            return res.status(404).json({ error: 'Federation disabled' });
+        const username = getUsername(req);
+        const page = req.query.page === 'true';
+        try {
+            const user = await config.resolveUser(username);
+            if (!user)
+                return res.status(404).json({ error: 'User not found' });
+            if (!config.consent.isSharingEnabledFromUser(user)) {
+                return res.status(404).json({ error: 'User not found' });
+            }
+            const userId = String(user._id || user.id);
+            const rawCount = direction === 'followers' ? user._count?.followers : user._count?.following;
+            const profileTotal = typeof rawCount === 'number' ? rawCount : undefined;
+            if (!page) {
+                // Prefer the profile `_count`; only when absent (the rare search fallback)
+                // fetch the authoritative total from a minimal graph list call. Fail-soft
+                // to 0 — never 500 the summary.
+                let totalItems = profileTotal ?? 0;
+                if (profileTotal === undefined) {
+                    try {
+                        totalItems = (await config.fetchFollowPage(userId, direction, 0, 1)).total;
+                    }
+                    catch (err) {
+                        logger.warn('[Federation] follow-collection summary total lookup failed', {
+                            username, direction, error: err,
+                        });
+                    }
+                }
+                res.set('Content-Type', apContentType);
+                return res.json({
+                    '@context': AP_CONTEXT,
+                    id: collectionUrl(username),
+                    type: 'OrderedCollection',
+                    totalItems,
+                    first: `${collectionUrl(username)}?page=true`,
+                });
+            }
+            const offset = parseFollowOffset(req.query.offset);
+            let members = [];
+            let total = profileTotal ?? 0;
+            let hasMore = false;
+            try {
+                const pageResult = await config.fetchFollowPage(userId, direction, offset, FOLLOW_PAGE_SIZE);
+                members = pageResult.members;
+                total = pageResult.total;
+                hasMore = pageResult.hasMore;
+            }
+            catch (err) {
+                // Fail-soft: never 500 the whole collection on an Oxy graph hiccup — serve
+                // an empty page against the best-known total rather than crashing.
+                logger.warn('[Federation] follow-collection Oxy graph list failed, serving empty page', {
+                    username, direction, offset, error: err,
+                });
+            }
+            const orderedItems = members
+                .map((member) => memberActorUri(member, urls))
+                .filter((uri) => uri !== null);
+            const pageId = offset > 0
+                ? `${collectionUrl(username)}?page=true&offset=${offset}`
+                : `${collectionUrl(username)}?page=true`;
+            const pageResponse = {
+                '@context': AP_CONTEXT,
+                id: pageId,
+                type: 'OrderedCollectionPage',
+                partOf: collectionUrl(username),
+                totalItems: total,
+                orderedItems,
+            };
+            if (hasMore) {
+                pageResponse.next = `${collectionUrl(username)}?page=true&offset=${offset + FOLLOW_PAGE_SIZE}`;
+            }
+            res.set('Content-Type', apContentType);
+            return res.json(pageResponse);
+        }
+        catch (err) {
+            logger.error('Follow collection endpoint error:', err);
+            return res.status(500).json({ error: 'Internal server error' });
+        }
+    }
+    // GET /ap/users/:username — ActivityPub Actor endpoint
+    router.get('/users/:username', async (req, res) => {
+        if (!config.federationEnabled)
+            return res.status(404).json({ error: 'Federation disabled' });
+        if (!wantsActivityPub(req)) {
+            // Redirect to the frontend profile if not an AP request.
+            return res.redirect(`https://${domain}/@${getUsername(req)}`);
+        }
+        const username = getUsername(req);
+        try {
+            // Instance actor: a special server-level actor used for signed fetches. It
+            // has no Oxy user — serve it directly from the key material. The WebFinger
+            // router answers for the SAME username, and its `self` href is built from
+            // the same `urls.actor(INSTANCE_ACTOR_USERNAME)` call as the `id` below,
+            // because Mastodon rejects a signed fetch when the two disagree.
+            if (username === INSTANCE_ACTOR_USERNAME) {
+                const publicKey = await config.getPublicKey(INSTANCE_ACTOR_USERNAME);
+                const actorObject = {
+                    '@context': AP_CONTEXT,
+                    id: urls.actor(INSTANCE_ACTOR_USERNAME),
+                    type: 'Application',
+                    preferredUsername: INSTANCE_ACTOR_USERNAME,
+                    name: domain,
+                    summary: '',
+                    url: `https://${domain}`,
+                    inbox: urls.inbox(INSTANCE_ACTOR_USERNAME),
+                    outbox: urls.outbox(INSTANCE_ACTOR_USERNAME),
+                    endpoints: { sharedInbox: urls.sharedInbox() },
+                    manuallyApprovesFollowers: false,
+                    discoverable: false,
+                    publicKey: {
+                        id: publicKey.keyId,
+                        owner: urls.actor(INSTANCE_ACTOR_USERNAME),
+                        publicKeyPem: publicKey.publicKeyPem,
+                    },
+                };
+                res.set('Content-Type', apContentType);
+                res.set('Cache-Control', 'max-age=1800');
+                return res.json(actorObject);
+            }
+            const user = await config.resolveUser(username);
+            if (!user)
+                return res.status(404).json({ error: 'User not found' });
+            // Sharing OFF must be indistinguishable from a nonexistent user — same 404
+            // body, no separate error code. Derived from the already-resolved user.
+            if (!config.consent.isSharingEnabledFromUser(user)) {
+                return res.status(404).json({ error: 'User not found' });
+            }
+            const publicKey = await config.getPublicKey(username);
+            // The profile banner lives in the app's own per-user settings (not the Oxy
+            // user DTO), keyed by the resolved Oxy user id. Advertise it as the AP
+            // `image` (Mastodon header). Absent settings / banner cleanly omits it.
+            const userId = user._id || user.id;
+            const profileHeaderImage = userId ? await config.getBanner(String(userId)) : null;
+            // Canonical display name is owned by the Oxy API (`name.displayName`); fall
+            // back to the username only if the API omitted it, so `name` is never empty.
+            const displayName = user.name?.displayName || username;
+            // ONE actor builder — shared with the outbound `Update(Person)` broadcast — so
+            // a fetched actor and a pushed actor Update never drift. The route owns the
+            // top-level JSON-LD `@context` (the builder omits it).
+            const actorObject = config.buildLocalActorObject({
+                username,
+                displayName,
+                kind: user.kind,
+                bio: user.bio,
+                avatar: user.avatar,
+                profileHeaderImage,
+                publicKey,
+                createdAt: user.createdAt,
+            });
+            res.set('Content-Type', apContentType);
+            res.set('Cache-Control', 'max-age=1800');
+            return res.json({ '@context': AP_CONTEXT, ...actorObject });
+        }
+        catch (err) {
+            logger.error('Actor endpoint error:', err);
+            return res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    // POST /ap/users/:username/inbox — User inbox
+    router.post('/users/:username/inbox', async (req, res) => {
+        if (!config.federationEnabled)
+            return res.status(404).json({ error: 'Federation disabled' });
+        // Sharing OFF (or a bogus `:username`) must be indistinguishable from a
+        // nonexistent user — same 404 body. An Oxy OUTAGE ('unavailable') is
+        // deliberately NOT 404'd: this is a POST delivery, and a 4xx makes the remote
+        // server drop it permanently rather than retry, so availability wins over
+        // gating freshness — the activity is processed and any consent decision is
+        // re-checked downstream by the id-based (fail-open) gates.
+        const username = getUsername(req);
+        const sharingState = await config.consent.getSharingStateByUsername(username);
+        if (sharingState === 'disabled' || sharingState === 'unknown-user') {
+            return res.status(404).json({ error: 'User not found' });
+        }
+        return handleInbox(req, res);
+    });
+    // POST /ap/inbox — Shared inbox
+    router.post('/inbox', async (req, res) => {
+        if (!config.federationEnabled)
+            return res.status(404).json({ error: 'Federation disabled' });
+        return handleInbox(req, res);
+    });
+    // GET /ap/users/:username/followers — Followers collection (Oxy graph: local + federated).
+    router.get('/users/:username/followers', (req, res) => serveFollowCollection(req, res, 'followers', urls.followers));
+    // GET /ap/users/:username/following — Following collection (Oxy graph: local + federated).
+    router.get('/users/:username/following', (req, res) => serveFollowCollection(req, res, 'following', urls.following));
+    return router;
+}