@oxy.so/federation 1.0.0

package/src/node/index.ts

@@ -0,0 +1,136 @@
+/**
+ * `@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,
+  type SignedFetch,
+  type CreateSignedFetchConfig,
+  type SingleHopFetch,
+  type SingleHopFetchInit,
+  type SignedFetchLogger,
+} from './signedFetch';
+
+/**
+ * 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,
+  type IdentityBridge,
+  type IdentityBridgeConfig,
+  type IdentityBridgeLogger,
+  type ServiceRequest,
+  type ServiceRequestMethod,
+  type ReportActorGoneOutcome,
+  type DeleteActorIdentityOutcome,
+} from './identityBridge';
+
+/**
+ * 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,
+  type ActorResolverConfig,
+  type ActorResolverIdentity,
+  type ActorResolverLogger,
+  type ActorTextAdapter,
+  type FederatedActorStore,
+  type FederatedActorRecordBase,
+  type FederatedActorUpsert,
+  type FederatedActorField,
+  type WebFingerFetch,
+  type WebFingerJrd,
+} from './actorResolver';
+
+/**
+ * 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,
+  type DeliveryService,
+  type DeliveryServiceConfig,
+  type DeliveryLogger,
+  type DeliveryKeys,
+  type DeliverSingleHop,
+  type DeliverSingleHopInit,
+  type DeliverSingleHopResult,
+  type DeliveryResponseStream,
+  type DeliveryTransport,
+  type DeliveryQueueJob,
+  type DeliveryFallbackQueue,
+  type DeliveryActorFields,
+  type DeliveryActorStore,
+  type DeliveryFollowStore,
+  type DeliveryActorRefresh,
+  type DeliveryConsent,
+  type DeliveryActorProfile,
+  type DeliveryIdentity,
+  type DeliveryProfile,
+  type SafeUrlVerdict,
+} from './delivery';
+
+/**
+ * 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,
+  type InboundDispatcher,
+  type InboundDispatcherConfig,
+  type InboundDispatcherLogger,
+  type InboundActivityValidation,
+  type InboundLocalUser,
+  type InboundIdentity,
+  type InboundConsent,
+  type InboundActorResolver,
+  type InboundFollowStore,
+  type InboundDelivery,
+} from './inboundDispatch';
+
+/** The WebFinger + host-meta discovery router (domain-parameterized, consent-gated). */
+export {
+  createWebfingerRouter,
+  type WebfingerRouterConfig,
+  type WebfingerSharingState,
+  type WebfingerUser,
+  type WebfingerJrd,
+  type WebfingerLogger,
+} from './webfingerRouter';
+
+/**
+ * The ActivityPub actor + inbox + follow-graph router (actor GET incl. the
+ * `instance` actor, inbox POST with HTTP-sig verify, followers/following pages).
+ */
+export {
+  createActorRouter,
+  type ActorRouterConfig,
+  type ActorRouteUser,
+  type ActorSharingState,
+  type ActorRouterLogger,
+  type FollowPage,
+} from './actorRouter';

package/src/node/signedFetch.ts

@@ -0,0 +1,177 @@
+/**
+ * `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, type HttpSignatureSigner } from '../httpSignature';
+
+/** 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: ReadonlySet<number> = new Set([301, 302, 303, 307, 308]);
+
+/** Per-request options handed to the injected single-hop transport. */
+export interface SingleHopFetchInit {
+  /** The EXACT request headers to send (the factory assembles these). */
+  headers: Record<string, string>;
+  /** Aborts the in-flight request when the signal fires. */
+  signal: AbortSignal;
+  /** Time-to-first-byte deadline in milliseconds. */
+  headersTimeoutMs?: number;
+}
+
+/**
+ * An SSRF-safe single-hop fetch: it validates + IP-pins the URL and returns the
+ * response WITHOUT following redirects (a 3xx is returned as-is so the caller can
+ * re-sign the next hop). Mention adapts its `@oxy.so/core/server`-backed
+ * `fetchUpstreamSingleHop` into this shape.
+ */
+export type SingleHopFetch = (url: string, init: SingleHopFetchInit) => Promise<Response>;
+
+/** Non-fatal diagnostics sink for signed fetches. */
+export interface SignedFetchLogger {
+  info(message: string): void;
+  warn(message: string): void;
+}
+
+/** Adapters + config a {@link SignedFetch} is built from. */
+export interface CreateSignedFetchConfig {
+  /** RSA-SHA256 signer — private-key custody stays behind this (Mention: oxy-api). */
+  sign: HttpSignatureSigner;
+  /** Resolve the instance actor's `keyId` used to sign outbound GETs. */
+  getInstanceKeyId: () => Promise<string>;
+  /** SSRF-safe single-hop transport (does NOT follow redirects). */
+  fetchSingleHop: SingleHopFetch;
+  /** User-Agent presented to remote servers. */
+  userAgent: string;
+  /** Optional diagnostics sink (5xx unsigned retry, 401/403 rejection). */
+  logger?: SignedFetchLogger;
+}
+
+/** A signed ActivityPub GET, returning the standard WHATWG {@link Response}. */
+export type SignedFetch = (url: string, accept: string, init?: RequestInit) => Promise<Response>;
+
+function requestInitHeaders(init: RequestInit): Record<string, string> {
+  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: Record<string, string> = {};
+    init.headers.forEach((value, key) => {
+      flattened[key] = value;
+    });
+    return flattened;
+  }
+  if (Array.isArray(init.headers)) return Object.fromEntries(init.headers);
+  return init.headers as Record<string, string>;
+}
+
+/**
+ * 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: CreateSignedFetchConfig): SignedFetch {
+  return async function signedFetch(
+    url: string,
+    accept: string,
+    init: RequestInit = {},
+  ): Promise<Response> {
+    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: string, signed: boolean): Promise<Response> => {
+      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: string,
+      signed: boolean,
+    ): Promise<{ res: Response; finalUrl: string }> => {
+      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/src/node/webfingerRouter.ts

@@ -0,0 +1,226 @@
+/**
+ * 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, type Request, type Response } from 'express';
+import { isSameFederationHost } from '../apUri';
+import type { UrlBuilders } from '../urls';
+import { INSTANCE_ACTOR_USERNAME, normalizeActorUsername } from '../urls';
+
+/** 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}`;
+
+/** The tri-state consent read for a username with no already-resolved user object. */
+export type WebfingerSharingState = 'enabled' | 'disabled' | 'unknown-user' | 'unavailable';
+
+/** The resolved-user fields the webfinger consent fallback reads. */
+export interface WebfingerUser {
+  _id?: string | null;
+  id?: string | null;
+}
+
+/** A cached WebFinger JRD document (the `subject` + `links` shape served below). */
+export interface WebfingerJrd {
+  subject: string;
+  links: Array<{ rel: string; type?: string; href: string }>;
+}
+
+/** Minimal logging sink the webfinger router writes to. */
+export interface WebfingerLogger {
+  error(message: string, detail?: unknown): void;
+}
+
+/** Adapters + config a {@link createWebfingerRouter} is built from. */
+export interface WebfingerRouterConfig {
+  /** The app's federation domain (the only `acct:` domain this instance answers for). */
+  domain: string;
+  /** Whether federation is enabled (all routes 404 when off). */
+  federationEnabled: boolean;
+  /** Per-instance URL builders (the actor `self` link). */
+  urls: UrlBuilders;
+  /** Resolve a username to its Oxy user (null when unknown). */
+  resolveUser(username: string): Promise<WebfingerUser | null>;
+  /** The fediverse-sharing consent gate. */
+  consent: {
+    /** Sync read off an already-resolved user (the `'unavailable'` fallback). */
+    isSharingEnabledFromUser(user: WebfingerUser): boolean;
+    /** Fresh, uncached tri-state read by username. */
+    getSharingStateByUsername(username: string): Promise<WebfingerSharingState>;
+  };
+  /** JRD response cache (Mention: Redis). Reads/writes are best-effort. */
+  cache: {
+    get(username: string): Promise<WebfingerJrd | null>;
+    set(username: string, jrd: WebfingerJrd): void;
+  };
+  /** Diagnostics sink. */
+  logger: WebfingerLogger;
+}
+
+/** Build the WebFinger + host-meta discovery router for an app's domain. */
+export function createWebfingerRouter(config: WebfingerRouterConfig): Router {
+  const router = Router();
+  const { domain } = config;
+  const webfingerTemplate = `https://${domain}/.well-known/webfinger?resource={uri}`;
+
+  router.get('/webfinger', async (req: Request, res: Response) => {
+    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: WebfingerJrd = {
+          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: WebfingerJrd = {
+        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: Request, res: Response) => {
+    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: Request, res: Response) => {
+    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/src/urls.ts

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+
+/** The per-instance ActivityPub URL builders, scoped to one app's domain. */
+export interface UrlBuilders {
+  /** Actor `id` / `attributedTo` — `https://<actorDomain>/ap/users/<username>`. */
+  actor(username: string): string;
+  /** The actor's personal inbox. */
+  inbox(username: string): string;
+  /** The actor's outbox collection. */
+  outbox(username: string): string;
+  /** The actor's `featured` (pinned posts) collection. */
+  featured(username: string): string;
+  /** The actor's followers collection. */
+  followers(username: string): string;
+  /** The actor's following collection. */
+  following(username: string): string;
+  /** The instance-wide shared inbox. */
+  sharedInbox(): string;
+}
+
+/**
+ * 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: string, actorDomain: string = domain): UrlBuilders {
+  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: string): string {
+  return username.trim().toLowerCase();
+}