@oxy.so/federation 1.0.0

package/dist/esm/node/inboundDispatch.js

@@ -0,0 +1,263 @@
+/**
+ * Inbound ActivityPub dispatch + the follow-protocol handlers.
+ *
+ * The engine owns the DISPATCHER (validate the untrusted activity, switch on its
+ * type) and the FOLLOW-PROTOCOL verbs — Follow / Accept / Undo(Follow) / Reject —
+ * because those are identical across every Oxy app: they bridge a federated follow
+ * edge into the Oxy graph (via the identity adapter), record the AP-side follow
+ * row (via the store adapter), and send the Accept back (via the delivery
+ * service). Every CONTENT verb (Create / Announce / Like / Delete / Update, and a
+ * non-follow Undo) is handed to the app-registered
+ * {@link InboundDispatcherConfig.onContentActivity} callback, where the app's own
+ * post/engagement handlers live. The consent gate + notification side effects are
+ * injected so the engine holds no app knowledge.
+ *
+ * Extracted behaviour-identically from Mention's former `InboxProcessingService`
+ * dispatcher + `handleIncomingFollow` / `handleUndo(Follow)` / `handleAccept` /
+ * `handleReject`.
+ */
+import { normalizeActorUsername } from '../urls.js';
+/**
+ * Thrown when a federated follow is about to be bridged but the FOLLOWER actor
+ * has not yet resolved to an Oxy user (`oxyUserId` missing) — e.g. Oxy was
+ * unreachable when the actor was fetched. A federated follow MUST become a real
+ * Oxy edge, never a ghost, so the whole inbound activity is DEFERRED rather than
+ * bridged half-way:
+ *
+ *  - in the BullMQ inbox worker, throwing fails the job, which retries with
+ *    bounded exponential backoff; a later attempt (Oxy reachable) resolves the
+ *    actor and bridges the follow. A permanently-unresolvable actor exhausts the
+ *    attempts and the activity is dropped — never a ghost edge.
+ *  - in the inline (no-Redis) fallback, it surfaces as a 500 from the inbox
+ *    endpoint, so the remote re-delivers per ActivityPub.
+ */
+export class ActorResolutionPendingError extends Error {
+    constructor(actorUri, context) {
+        super(`Actor ${actorUri} is not yet resolved to an Oxy user${context ? ` (${context})` : ''}; deferring inbound activity`);
+        this.name = 'ActorResolutionPendingError';
+        this.actorUri = actorUri;
+    }
+}
+/**
+ * The lowercased host of an actor URI, or null when it is not a parseable absolute
+ * URL. Callers treat null as blocked: an origin whose host cannot be determined
+ * cannot be checked against the domain policy, so it fails closed.
+ */
+function actorUriHost(actorUri) {
+    try {
+        return new URL(actorUri).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the `object`'s referenced actor/target uri (a string, or an embedded `{ id }`). */
+function objectTargetUri(object) {
+    if (typeof object === 'string')
+        return object;
+    if (object && typeof object === 'object') {
+        const id = object.id;
+        if (typeof id === 'string')
+            return id;
+    }
+    return undefined;
+}
+/** Build the inbound-activity dispatcher from an app's adapters + content handlers. */
+export function createInboundDispatcher(config) {
+    const { logger } = config;
+    async function handleIncomingFollow(activity, actorUri) {
+        const targetActorUri = objectTargetUri(activity.object);
+        if (!targetActorUri)
+            return;
+        // Extract username from our actor URL
+        const match = targetActorUri.match(/\/ap\/users\/([^/]+)$/);
+        if (!match)
+            return;
+        const username = normalizeActorUsername(match[1]);
+        // Resolve the Oxy user to get a real user ID
+        const user = await config.identity.resolveUserByUsername(username);
+        if (!user) {
+            logger.warn(`Incoming follow for unknown user ${username} from ${actorUri}`);
+            return;
+        }
+        const localUserId = String(user._id || user.id);
+        // The target user may have turned fediverse sharing off — drop the Follow
+        // silently (no bridge, no Accept, no Reject). A Reject is unverifiable
+        // against a 404'd actor and would reveal the account exists, so this must
+        // look identical to a Follow sent to an unknown user. Gated here, BEFORE
+        // the follower actor is fetched/resolved, so an OFF user never triggers any
+        // of the bridge/Accept/notification side effects below.
+        if (!config.consent.isSharingEnabledFromUser(user)) {
+            logger.debug(`[Federation] inbound follow for ${username} dropped — sharing off`);
+            return;
+        }
+        // Resolve the follower actor and REQUIRE its Oxy user id: a fediverse
+        // follower must become a real Oxy edge, never a ghost. When the actor is
+        // missing or not yet resolved to an Oxy user (Oxy was unreachable when it was
+        // fetched), throw `ActorResolutionPendingError` so the BullMQ inbox job
+        // retries with backoff and bridges the follow on a later attempt.
+        const actor = await config.actorResolver.getOrFetchActor(actorUri);
+        const followerOxyUserId = actor?.oxyUserId;
+        if (!followerOxyUserId) {
+            throw new ActorResolutionPendingError(actorUri, `Follow ${String(activity.id)}`);
+        }
+        // A self-follow (the follower resolves to the same local user) is meaningless
+        // in the Oxy graph — skip before touching any state or delivering an Accept.
+        if (followerOxyUserId === localUserId) {
+            logger.debug(`[Federation] ignoring self-follow from ${actorUri} to ${username}`);
+            return;
+        }
+        // Create the Oxy follow edge BEFORE sending Accept so a retry never spams
+        // Accepts: the bridge is idempotent (safe to re-run), but an Accept delivered
+        // before the edge was committed could be re-sent on every retry. On failure
+        // the bridge throws, failing the job so the whole sequence retries.
+        await config.identity.bridgeFollow(followerOxyUserId, localUserId);
+        await config.follows.upsertInboundAccepted(localUserId, actorUri, String(activity.id));
+        // Send Accept back so the remote server knows the follow succeeded
+        await config.delivery.sendAccept(localUserId, username, String(activity.id), actorUri);
+        // Fail-soft: the Oxy edge is already committed, so a notification failure must
+        // never fail (and thus retry) the follow.
+        if (config.onInboundFollowAccepted) {
+            await config.onInboundFollowAccepted(localUserId, followerOxyUserId, actorUri);
+        }
+        logger.info(`Accepted follow from ${actorUri} to ${username}`);
+    }
+    async function handleUndoFollow(object, actorUri) {
+        const targetActorUri = objectTargetUri(object.object);
+        const match = targetActorUri?.match(/\/ap\/users\/([^/]+)$/);
+        let localUserId;
+        if (match) {
+            const user = await config.identity.resolveUserByUsername(normalizeActorUsername(match[1]));
+            if (user)
+                localUserId = String(user._id || user.id);
+        }
+        // Idempotency: locate the follow row FIRST. Absent → this Undo was already
+        // processed (a redelivery), so there is nothing to tear down — return.
+        const follow = await config.follows.findInboundFollow(actorUri, localUserId);
+        if (!follow) {
+            logger.debug(`Undo follow from ${actorUri}: no matching row (already processed)`);
+            return;
+        }
+        // Remove the Oxy follow edge BEFORE deleting the local row, so a transient
+        // bridge failure retries with the row still present. The edge can only exist
+        // when the follower actor resolved to an Oxy user; without an `oxyUserId` no
+        // edge was ever created, so there is nothing to remove. THROW on transient
+        // bridge failure (job retry); the bridge is idempotent.
+        const followerOxyUserId = await config.follows.findActorOxyUserId(actorUri);
+        if (followerOxyUserId) {
+            await config.identity.bridgeUnfollow(followerOxyUserId, follow.localUserId);
+        }
+        await config.follows.deleteFollowById(follow._id);
+        logger.debug(`Undo follow from ${actorUri}`);
+    }
+    async function handleUndo(activity, actorUri) {
+        const object = activity.object;
+        if (!object)
+            return;
+        const objectType = typeof object === 'string' ? null : object.type;
+        if (objectType === 'Follow') {
+            await handleUndoFollow(object, actorUri);
+        }
+        else {
+            // Undo(Like) / Undo(Announce) — content teardown. Hand the WHOLE Undo
+            // activity to the app (it re-inspects the embedded object type).
+            await config.onContentActivity(activity, actorUri);
+        }
+    }
+    async function handleAccept(activity, actorUri) {
+        const object = activity.object;
+        if (!object)
+            return;
+        let updated = false;
+        if (typeof object === 'string') {
+            // Remote sent Accept with a string reference (the Follow activity ID).
+            // Try matching by activityId first, fall back to any pending follow.
+            updated = await config.follows.markOutboundAcceptedByActivityId(actorUri, object);
+            if (!updated) {
+                updated = await config.follows.markOutboundAcceptedAnyPending(actorUri);
+            }
+        }
+        else if (object.type === 'Follow') {
+            const followActivityId = object.id;
+            updated = typeof followActivityId === 'string' && followActivityId.length > 0
+                ? await config.follows.markOutboundAcceptedByActivityId(actorUri, followActivityId)
+                : await config.follows.markOutboundAcceptedAnyPending(actorUri);
+        }
+        if (updated) {
+            logger.debug(`Follow accepted by ${actorUri}`);
+            // Fire-and-forget: backfill the newly followed actor's recent posts.
+            if (config.onOutboundFollowAccepted) {
+                await config.onOutboundFollowAccepted(actorUri);
+            }
+        }
+    }
+    async function handleReject(activity, actorUri) {
+        const object = activity.object;
+        if (!object)
+            return;
+        const objectType = typeof object === 'string' ? null : object.type;
+        if (objectType === 'Follow') {
+            const followActivityId = typeof object === 'object' ? object.id : undefined;
+            await config.follows.markOutboundRejected(actorUri, typeof followActivityId === 'string' ? followActivityId : undefined);
+            logger.debug(`Follow rejected by ${actorUri}`);
+        }
+    }
+    async function processInboxActivity(activity, verifiedActorUri) {
+        // Instance domain policy, FIRST — before the payload is even parsed.
+        //
+        // This is the single chokepoint for inbound federation: every transport (the
+        // inbox route's inline path, the BullMQ inbox worker replaying a queued job,
+        // and any direct connector call) converges here, and every verb — Follow,
+        // Accept, Undo, Reject, and the app's content verbs — is dispatched below it.
+        // So one check here suspends an instance completely: no posts, no actors, no
+        // follows, no boosts, no notifications.
+        //
+        // It is keyed on `verifiedActorUri`, the origin the HTTP signature actually
+        // proved, which is also the identity every handler downstream trusts — so
+        // there is no second, weaker identity a hostile payload could be routed under.
+        const originHost = actorUriHost(verifiedActorUri);
+        if (originHost === null || config.isBlockedDomain(originHost)) {
+            logger.warn(`[Federation] dropping inbound activity from blocked origin ${verifiedActorUri} (host=${originHost ?? 'unparseable'})`);
+            return;
+        }
+        // Inbound JSON arrives from arbitrary, UNTRUSTED remote servers. Validate the
+        // whole activity BEFORE any handler reads it. The validation never throws; a
+        // malformed or hostile payload is rejected cleanly here.
+        const validation = config.validateActivity(activity);
+        if (!validation.ok) {
+            const rawType = typeof activity?.type === 'string'
+                ? activity.type
+                : Array.isArray(activity?.type)
+                    ? activity.type.join(',')
+                    : 'unknown';
+            const rawId = typeof activity?.id === 'string' ? activity.id : 'unknown';
+            logger.warn(`[Federation] dropping invalid inbound activity from ${verifiedActorUri} (type=${rawType}, id=${rawId}): ${validation.summary}`);
+            return;
+        }
+        switch (validation.type) {
+            case 'Follow':
+                await handleIncomingFollow(activity, verifiedActorUri);
+                break;
+            case 'Undo':
+                await handleUndo(activity, verifiedActorUri);
+                break;
+            case 'Accept':
+                await handleAccept(activity, verifiedActorUri);
+                break;
+            case 'Reject':
+                await handleReject(activity, verifiedActorUri);
+                break;
+            // Content verbs — the app owns these (posts, engagement, actor profile edits).
+            case 'Create':
+            case 'Delete':
+            case 'Like':
+            case 'Announce':
+            case 'Update':
+                await config.onContentActivity(activity, verifiedActorUri);
+                break;
+            default:
+                logger.debug(`Unhandled activity type: ${validation.type}`);
+        }
+    }
+    return { processInboxActivity };
+}

package/dist/esm/node/index.js

@@ -0,0 +1,51 @@
+/**
+ * `@oxy.so/federation/node` — the runnable Node/Express federation engine.
+ *
+ * A SEPARATE subpath from the package root so this Node-only code never enters
+ * isomorphic bundles that import `@oxy.so/federation`.
+ *
+ * Phase 2 (HTTP signatures): the signed-fetch transport — a signed ActivityPub
+ * GET with per-hop HTTP-signature re-signing, built over an app-injected
+ * SSRF-safe single-hop transport. The pure sign/verify crypto it drives lives in
+ * the isomorphic `.` entry.
+ *
+ * Phase 3 (actor model + resolution): the identity bridge + remote-actor resolver.
+ *
+ * Phase 4 (delivery + follow lifecycle + routers + inbound dispatch): the outbound
+ * delivery transport + follow protocol, the inbound dispatcher (Follow/Accept/
+ * Undo(Follow)/Reject, delegating content verbs to the app), and the webfinger +
+ * actor + inbox + follow-graph Express routers.
+ */
+export { createSignedFetch, } from './signedFetch.js';
+/**
+ * The actor↔Oxy-user identity bridge — the default implementation of the
+ * `PUT /users/resolve` + actor-gone archive/delete seam over an injected
+ * service-request transport.
+ */
+export { createIdentityBridge, } from './identityBridge.js';
+/**
+ * Remote-actor resolution/caching/refresh (webfinger, signed actor fetch,
+ * 410-Gone tombstone) over a bring-your-own-store adapter, the identity bridge,
+ * and injected transports + text normalization.
+ */
+export { createActorResolver, ActorResolver, } from './actorResolver.js';
+/**
+ * Outbound activity delivery + the follow lifecycle (Follow / Undo(Follow) /
+ * Accept(Follow)) + the `Update(Person)` actor rebroadcast, over injected key
+ * custody, an SSRF-safe delivery transport, and bring-your-own-store adapters.
+ */
+export { createDeliveryService, } from './delivery.js';
+/**
+ * Inbound ActivityPub dispatch — the untrusted-activity validator + switch, the
+ * follow-protocol handlers (Follow / Accept / Undo(Follow) / Reject) over the
+ * identity + store adapters, and the `onContentActivity` seam every content verb
+ * (Create / Announce / Like / Delete / Update, non-follow Undo) is handed to.
+ */
+export { createInboundDispatcher, ActorResolutionPendingError, } from './inboundDispatch.js';
+/** The WebFinger + host-meta discovery router (domain-parameterized, consent-gated). */
+export { createWebfingerRouter, } from './webfingerRouter.js';
+/**
+ * The ActivityPub actor + inbox + follow-graph router (actor GET incl. the
+ * `instance` actor, inbox POST with HTTP-sig verify, followers/following pages).
+ */
+export { createActorRouter, } from './actorRouter.js';

package/dist/esm/node/signedFetch.js

@@ -0,0 +1,119 @@
+/**
+ * `signedFetch` — a signed ActivityPub GET with per-hop HTTP-signature
+ * re-signing, built over an injected SSRF-safe single-hop transport.
+ *
+ * WHY A FACTORY OVER AN INJECTED TRANSPORT (not core `safeFetch` directly)
+ * -----------------------------------------------------------------------
+ * An HTTP signature is bound to the `(request-target)`/`host` of ONE specific
+ * URL, so on a redirect the signature MUST be recomputed for the new target.
+ * `@oxy.so/core/server`'s `safeFetch` follows redirects internally and re-sends
+ * the ORIGINAL headers on each hop (it never re-signs, and it destroys redirect
+ * bodies), so it cannot back per-hop re-signing. Instead — mirroring how
+ * `@oxy.so/protocol/node` injects its `NodeFetch` adapter over `safeFetch` — this
+ * factory takes a single-hop transport that validates + IP-pins ONE request and
+ * returns the response WITHOUT following redirects. The engine owns the
+ * federation policy (signing, the bounded redirect loop that re-signs each hop,
+ * the unsigned 5xx fallback); the app supplies the SSRF transport (Mention adapts
+ * its `@oxy.so/core/server`-based single-hop fetch), keeping the SSRF/DNS-pin
+ * policy in ONE place.
+ */
+import { signRequest } from '../httpSignature.js';
+/** Total time budget for a single signed hop (connect + response headers). */
+const SIGNED_FETCH_TIMEOUT_MS = 10000;
+/** Bounded redirect budget for signed AP GETs; each hop is re-validated and re-signed. */
+const SIGNED_FETCH_MAX_REDIRECTS = 3;
+const REDIRECT_STATUS_CODES = new Set([301, 302, 303, 307, 308]);
+function requestInitHeaders(init) {
+    if (!init.headers)
+        return {};
+    if (init.headers instanceof Headers) {
+        // `Headers.forEach` is typed on the base `DOM` lib, whereas
+        // `Headers.entries()` requires `DOM.Iterable` — which this package's build
+        // tsconfig deliberately omits (isomorphic node/web split). `forEach` keeps
+        // the flatten build-safe under every lib config (Docker + local).
+        const flattened = {};
+        init.headers.forEach((value, key) => {
+            flattened[key] = value;
+        });
+        return flattened;
+    }
+    if (Array.isArray(init.headers))
+        return Object.fromEntries(init.headers);
+    return init.headers;
+}
+/**
+ * Build a `signedFetch(url, accept, init?)`:
+ *
+ * Signs a GET request using the instance actor key (via the injected signer) and
+ * performs it under the SSRF-safe contract (the injected single-hop transport
+ * validates the URL AND pins the TCP connection to the validated IP).
+ *
+ * Redirects are followed manually (bounded by {@link SIGNED_FETCH_MAX_REDIRECTS}),
+ * re-validating AND re-signing each hop — an HTTP signature is bound to the
+ * `(request-target)`/`host` of a specific URL. When the caller passes
+ * `init.redirect === 'manual'`, the redirect `Response` is returned directly so
+ * the caller can apply its own stricter redirect policy.
+ *
+ * Signed for servers that enforce authorized fetch (e.g. Threads). On a 5xx the
+ * request is retried unsigned (same SSRF-safe path) as a fallback for public
+ * resources.
+ */
+export function createSignedFetch(config) {
+    return async function signedFetch(url, accept, init = {}) {
+        const acceptHeader = `${accept}, application/ld+json; profile="https://www.w3.org/ns/activitystreams"`;
+        const keyId = await config.getInstanceKeyId();
+        const extraHeaders = requestInitHeaders(init);
+        const manualRedirect = init.redirect === 'manual';
+        const fetchOnce = async (targetUrl, signed) => {
+            const sigHeaders = signed ? await signRequest(config.sign, keyId, 'GET', targetUrl) : {};
+            return config.fetchSingleHop(targetUrl, {
+                headers: {
+                    Accept: acceptHeader,
+                    'User-Agent': config.userAgent,
+                    ...sigHeaders,
+                    ...extraHeaders,
+                },
+                signal: init.signal ?? AbortSignal.timeout(SIGNED_FETCH_TIMEOUT_MS),
+                headersTimeoutMs: SIGNED_FETCH_TIMEOUT_MS,
+            });
+        };
+        const fetchFollowingRedirects = async (initialUrl, signed) => {
+            let currentUrl = initialUrl;
+            for (let hop = 0; hop <= SIGNED_FETCH_MAX_REDIRECTS; hop++) {
+                const res = await fetchOnce(currentUrl, signed);
+                if (!REDIRECT_STATUS_CODES.has(res.status)) {
+                    return { res, finalUrl: currentUrl };
+                }
+                // The caller asked to handle redirects itself (stricter per-hop policy).
+                if (manualRedirect) {
+                    return { res, finalUrl: currentUrl };
+                }
+                const location = res.headers.get('location');
+                if (hop === SIGNED_FETCH_MAX_REDIRECTS || !location) {
+                    return { res, finalUrl: currentUrl };
+                }
+                currentUrl = new URL(location, currentUrl).toString();
+            }
+            throw new Error('redirect loop exhausted');
+        };
+        const { res, finalUrl } = await fetchFollowingRedirects(url, true);
+        // If the remote server returns a 5xx (e.g. it can't resolve our keyId to
+        // verify the signature), retry without the signature as a fallback for public
+        // resources. Retry from the post-redirect URL so we don't restart a chain that
+        // already landed on the failing hop.
+        if (res.status >= 500) {
+            config.logger?.info(`[FedSync] signedFetch got ${res.status} for ${finalUrl}, retrying unsigned`);
+            return fetchFollowingRedirects(finalUrl, false).then(({ res: unsignedRes }) => unsignedRes);
+        }
+        // A 401/403 on a signed request means the remote rejected OUR signature (e.g.
+        // it could not resolve/verify our keyId, or our instance key pair is
+        // missing/invalid because the service token could not be acquired). Without a
+        // log this silently yields zero results — surface it so the failure mode is
+        // observable in production. The caller still receives the response and decides
+        // how to proceed; we do not change control flow here.
+        if (res.status === 401 || res.status === 403) {
+            config.logger?.warn(`[FedSync] signedFetch got ${res.status} ${res.statusText} for ${url} — remote rejected our HTTP signature (check instance key pair / service token); returning the failed response so no posts are imported from this source`);
+        }
+        return res;
+    };
+}

package/dist/esm/node/webfingerRouter.js

@@ -0,0 +1,163 @@
+/**
+ * The WebFinger + host-meta discovery router.
+ *
+ * `/.well-known/webfinger` resolves `acct:<user>@<domain>` to the local actor URL;
+ * `/.well-known/host-meta(.json)` advertises the WebFinger LRDD template. Both are
+ * domain-parameterized (each app answers for its OWN `domain`) and both enforce
+ * the fediverse-sharing consent gate — a disabled/unknown user 404s
+ * indistinguishably. The JRD cache (Mention: Redis) is injected so the caching
+ * strategy stays app-side; the response bytes + the 404-when-off semantics live
+ * here so every Oxy app discovers identically.
+ *
+ * Extracted behaviour-identically from Mention's `wellKnown.routes.ts`.
+ */
+import { Router } from 'express';
+import { isSameFederationHost } from '../apUri.js';
+import { INSTANCE_ACTOR_USERNAME, normalizeActorUsername } from '../urls.js';
+/** 1 hour, in seconds — the WebFinger JRD cache TTL + response `max-age`. */
+const WEBFINGER_CACHE_TTL = 3600;
+/** 24h — host-meta is effectively static. */
+const HOST_META_CACHE_CONTROL = `max-age=${60 * 60 * 24}`;
+/** Build the WebFinger + host-meta discovery router for an app's domain. */
+export function createWebfingerRouter(config) {
+    const router = Router();
+    const { domain } = config;
+    const webfingerTemplate = `https://${domain}/.well-known/webfinger?resource={uri}`;
+    router.get('/webfinger', async (req, res) => {
+        if (!config.federationEnabled) {
+            return res.status(404).json({ error: 'Federation is disabled' });
+        }
+        const resource = typeof req.query.resource === 'string' ? req.query.resource : undefined;
+        if (!resource || !resource.startsWith('acct:')) {
+            return res.status(400).json({ error: 'Resource must start with acct:' });
+        }
+        const acct = resource.replace('acct:', '');
+        const atIndex = acct.indexOf('@');
+        if (atIndex === -1) {
+            return res.status(400).json({ error: 'Invalid acct format' });
+        }
+        const username = normalizeActorUsername(acct.substring(0, atIndex));
+        const acctDomain = acct.substring(atIndex + 1).trim();
+        if (!isSameFederationHost(acctDomain, domain)) {
+            return res.status(404).json({ error: 'Unknown domain' });
+        }
+        try {
+            // The instance actor is NOT an Oxy user: it has no profile, no consent
+            // record, and `resolveUser` will never find it — so it must be answered
+            // here, ahead of both the resolve and the sharing-consent gate, exactly as
+            // the actor route answers ahead of them. Without this branch the server
+            // actor is served as an actor but is not WebFinger-resolvable, and every
+            // secure-mode instance then refuses our signed GETs: Mastodon's
+            // `FetchRemoteKeyService#find_actor` calls `FetchRemoteActorService`
+            // WITHOUT `only_key:`, which runs `check_webfinger!` unconditionally, so a
+            // 404 here raises `Webfinger::Error` and the signed fetch 401s.
+            //
+            // Deliberately NOT cached: the document is static (no I/O to amortize) and
+            // routing it through the app's JRD cache would let one stale or evicted
+            // entry make the server actor undiscoverable for a full TTL — which is the
+            // outage this branch exists to prevent.
+            if (username === INSTANCE_ACTOR_USERNAME) {
+                const instanceJrd = {
+                    subject: `acct:${INSTANCE_ACTOR_USERNAME}@${domain}`,
+                    links: [
+                        {
+                            rel: 'self',
+                            type: 'application/activity+json',
+                            // The SAME builder call the actor route uses for the actor `id`.
+                            // Mastodon compares `webfinger.self_link_href` against the actor
+                            // uri and rejects a mismatch, so these must not be built twice.
+                            href: config.urls.actor(INSTANCE_ACTOR_USERNAME),
+                        },
+                        // No `profile-page` rel: the server actor has no human-facing page
+                        // (`/@instance` is not a profile), and the file's existing policy is
+                        // that a dangling link is worse than an absent one.
+                    ],
+                };
+                res.set('Content-Type', 'application/jrd+json; charset=utf-8');
+                res.set('Cache-Control', `max-age=${WEBFINGER_CACHE_TTL}`);
+                return res.json(instanceJrd);
+            }
+            // Check the JRD cache first.
+            const cached = await config.cache.get(username);
+            if (cached) {
+                res.set('Content-Type', 'application/jrd+json; charset=utf-8');
+                res.set('Cache-Control', `max-age=${WEBFINGER_CACHE_TTL}`);
+                return res.json(cached);
+            }
+            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. UNLIKE the other user-scoped surfaces,
+            // webfinger does a SECOND, uncached consent read here rather than reusing
+            // the already-resolved `user`: this response is ALSO cached for a full hour
+            // below, so a stale-DTO false positive would lock the actor (un)discoverable
+            // for up to an hour. An Oxy OUTAGE ('unavailable') on that fresh read falls
+            // back to the already-resolved `user` instead of 404ing, so a transient
+            // hiccup never makes a real account momentarily undiscoverable.
+            const sharingState = await config.consent.getSharingStateByUsername(username);
+            if (sharingState === 'disabled' || sharingState === 'unknown-user') {
+                return res.status(404).json({ error: 'User not found' });
+            }
+            if (sharingState === 'unavailable' && !config.consent.isSharingEnabledFromUser(user)) {
+                return res.status(404).json({ error: 'User not found' });
+            }
+            const response = {
+                subject: `acct:${username}@${domain}`,
+                links: [
+                    {
+                        rel: 'self',
+                        type: 'application/activity+json',
+                        href: config.urls.actor(username),
+                    },
+                    {
+                        rel: 'http://webfinger.net/rel/profile-page',
+                        type: 'text/html',
+                        href: `https://${domain}/@${username}`,
+                    },
+                    // NOTE: the `http://ostatus.org/schema/1.0/subscribe` (remote-follow) rel
+                    // is intentionally omitted — there is no authorize-interaction endpoint
+                    // to point it at, and a dangling template would be worse than its absence.
+                ],
+            };
+            config.cache.set(username, response);
+            res.set('Content-Type', 'application/jrd+json; charset=utf-8');
+            res.set('Cache-Control', `max-age=${WEBFINGER_CACHE_TTL}`);
+            return res.json(response);
+        }
+        catch (err) {
+            config.logger.error('WebFinger error:', err);
+            return res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    router.get('/host-meta', (_req, res) => {
+        if (!config.federationEnabled) {
+            return res.status(404).json({ error: 'Federation is disabled' });
+        }
+        const xrd = `<?xml version="1.0" encoding="UTF-8"?>
+<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
+  <Link rel="lrdd" type="application/jrd+json" template="${webfingerTemplate}"/>
+</XRD>
+`;
+        res.set('Content-Type', 'application/xrd+xml; charset=utf-8');
+        res.set('Cache-Control', HOST_META_CACHE_CONTROL);
+        return res.send(xrd);
+    });
+    router.get('/host-meta.json', (_req, res) => {
+        if (!config.federationEnabled) {
+            return res.status(404).json({ error: 'Federation is disabled' });
+        }
+        res.set('Content-Type', 'application/jrd+json; charset=utf-8');
+        res.set('Cache-Control', HOST_META_CACHE_CONTROL);
+        return res.json({
+            links: [
+                {
+                    rel: 'lrdd',
+                    type: 'application/jrd+json',
+                    template: webfingerTemplate,
+                },
+            ],
+        });
+    });
+    return router;
+}

package/dist/esm/urls.js

@@ -0,0 +1,50 @@
+/**
+ * Domain-parameterized ActivityPub URL builders.
+ *
+ * Every Oxy app federates under its OWN domain (`@user@mention.earth`,
+ * `@user@homiio.com`, `@user@oxy.so`), so the actor/inbox/outbox/collection URLs
+ * an app mints must be scoped to that app's instance — never a module-level
+ * constant. {@link createUrlBuilders} is the factory each app instantiates once
+ * with its `FEDERATION_DOMAIN` (and, optionally, a distinct `ACTOR_DOMAIN`); the
+ * returned builders produce the exact URL shapes Mastodon and the rest of the
+ * fediverse expect, byte-for-byte identical to the strings the actor document
+ * advertises.
+ *
+ * `actor()` is scoped to `actorDomain` (the host in the actor `id` / `publicKey`
+ * owner) while every other builder is scoped to `domain`; in the common case both
+ * are the same host. The two are kept separate so a deployment that serves the
+ * actor namespace from a different host than the webfinger/inbox host can still
+ * advertise a self-consistent actor.
+ */
+/**
+ * Build the ActivityPub URL builders for an app instance.
+ *
+ * @param domain the app's federation domain (webfinger / inbox / collections host).
+ * @param actorDomain the host that owns the actor `id`; defaults to `domain`.
+ */
+export function createUrlBuilders(domain, actorDomain = domain) {
+    return {
+        actor: (username) => `https://${actorDomain}/ap/users/${username}`,
+        inbox: (username) => `https://${domain}/ap/users/${username}/inbox`,
+        outbox: (username) => `https://${domain}/ap/users/${username}/outbox`,
+        featured: (username) => `https://${domain}/ap/users/${username}/collections/featured`,
+        followers: (username) => `https://${domain}/ap/users/${username}/followers`,
+        following: (username) => `https://${domain}/ap/users/${username}/following`,
+        sharedInbox: () => `https://${domain}/ap/inbox`,
+    };
+}
+/**
+ * The reserved local-part of the instance-wide server actor (`Application`).
+ *
+ * This actor signs the engine's own outbound GETs; it is NOT an Oxy user, has no
+ * profile page and no fediverse-sharing consent record. Both the actor route and
+ * the WebFinger route must answer for it, and Mastodon compares the WebFinger
+ * `self` href against the actor `id` byte-for-byte before it will trust a signed
+ * fetch — so the two routers derive that URL from THIS constant through the same
+ * {@link UrlBuilders.actor} builder rather than each spelling the name themselves.
+ */
+export const INSTANCE_ACTOR_USERNAME = 'instance';
+/** Normalize a local actor username from a path segment or WebFinger acct local-part. */
+export function normalizeActorUsername(username) {
+    return username.trim().toLowerCase();
+}