@oxy.so/federation 1.0.0

package/dist/types/node/identityBridge.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The network-neutral identity bridge — the DEFAULT implementation of the
+ * actor↔Oxy-user seam.
+ *
+ * The DATA is Oxy's: a remote actor is minted/updated as a `type:'federated'` Oxy
+ * user via `PUT /users/resolve`, and permanently-gone actors are archived
+ * (`POST /federation/actor-gone`) or hard-deleted (`POST /federation/actor-delete`)
+ * on the Oxy side. Those are service-scoped oxy-api calls (scope `federation:write`),
+ * so the transport is injected ({@link IdentityBridgeConfig.makeServiceRequest} —
+ * for Mention, `getServiceOxyClient().makeServiceRequest`). Private keys and
+ * canonical identity never enter this package.
+ *
+ * App-owned side effects are injected too: a post-resolve cache invalidation hook
+ * ({@link IdentityBridgeConfig.onUserResolved}) and the banner mirror
+ * ({@link IdentityBridgeConfig.mirrorBanner}, which uses the app's own media
+ * pipeline). The banner mirror is best-effort: a failure there must never discard
+ * an already-successful user resolution.
+ */
+import type { NormalizedExternalActor } from '../index';
+/** The HTTP methods the service-scoped oxy-api transport is invoked with. */
+export type ServiceRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** The service-scoped request transport oxy-api calls go through (`{ data }`-unwrapped). */
+export type ServiceRequest = <T>(method: ServiceRequestMethod, path: string, body?: unknown) => Promise<T>;
+/** Minimal logging sink the identity bridge writes to. */
+export interface IdentityBridgeLogger {
+    info(message: string, meta?: unknown): void;
+    warn(message: string, meta?: unknown): void;
+}
+/** Adapters the identity bridge is built from. */
+export interface IdentityBridgeConfig {
+    /** Service-scoped oxy-api request transport (unwraps the API's `{ data }` envelope). */
+    makeServiceRequest: ServiceRequest;
+    /**
+     * Called with the resolved Oxy user id after a successful `PUT /users/resolve`
+     * (before the banner mirror). For Mention: evict the warm user-summary cache.
+     */
+    onUserResolved?: (oxyUserId: string) => Promise<void> | void;
+    /**
+     * Mirror the actor's remote banner into a durable app-owned asset. Best-effort:
+     * MUST NOT throw (it handles its own errors); a failure never drops the resolved
+     * user. Absent ⇒ banners are not mirrored.
+     */
+    mirrorBanner?: (bannerUrl: string, oxyUserId: string, actorUri: string) => Promise<void>;
+    /** Diagnostics sink. */
+    logger: IdentityBridgeLogger;
+}
+/**
+ * Outcome discriminant of {@link IdentityBridge.reportActorGone}. NEVER thrown —
+ * both callers (the live 410 tombstone and the one-shot prune sweep) are
+ * fail-soft, so the transient/retryable case is surfaced as a value (`'failed'`).
+ *
+ *  - `archived` — Oxy archived a previously-active identity (removed from search).
+ *  - `already`  — the identity was already archived (idempotent no-op, still 200).
+ *  - `skipped`  — nothing to report, or a PERMANENT client error (400/403/404/409).
+ *  - `failed`   — a genuinely transient failure (5xx, 408/429, network). Retryable.
+ */
+export type ReportActorGoneOutcome = 'archived' | 'already' | 'skipped' | 'failed';
+/**
+ * Outcome discriminant of {@link IdentityBridge.deleteActorIdentity}. NEVER thrown.
+ *
+ *  - `deleted` — oxy-api hard-deleted a live Oxy identity (+ follow edges/blocks).
+ *  - `absent`  — the identity was already gone (200, `deleted:false`). Oxy side clean.
+ *  - `skipped` — nothing to delete, or a PERMANENT client error (400/403/409).
+ *  - `failed`  — a genuinely transient failure (5xx, 408/429, network). Retryable.
+ */
+export type DeleteActorIdentityOutcome = 'deleted' | 'absent' | 'skipped' | 'failed';
+/** The actor↔Oxy-user identity bridge. */
+export interface IdentityBridge {
+    /**
+     * Resolve/mint the Oxy user a normalized external actor maps to, via
+     * `PUT /users/resolve` (service-scoped). Returns the resolved id, or `null` when
+     * Oxy is unreachable / returns no id (callers must then skip, never persisting an
+     * orphan). Mirrors the banner after resolution (best-effort).
+     */
+    resolveExternalUser(actor: NormalizedExternalActor, opts?: {
+        forceAvatarRefresh?: boolean;
+    }): Promise<string | null>;
+    /** Ask oxy-api to ARCHIVE the identity of a permanently-gone actor (reversible). */
+    reportActorGone(oxyUserId: string): Promise<ReportActorGoneOutcome>;
+    /** Ask oxy-api to HARD-DELETE the identity of a permanently-gone actor (irreversible). */
+    deleteActorIdentity(oxyUserId: string): Promise<DeleteActorIdentityOutcome>;
+}
+/** Build the network-neutral identity bridge from an app's adapters. */
+export declare function createIdentityBridge(config: IdentityBridgeConfig): IdentityBridge;

package/dist/types/node/inboundDispatch.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 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`.
+ */
+/**
+ * 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 declare class ActorResolutionPendingError extends Error {
+    /** The remote actor URI whose Oxy resolution is still pending. */
+    readonly actorUri: string;
+    constructor(actorUri: string, context?: string);
+}
+/** Minimal logging sink the inbound dispatcher writes to. */
+export interface InboundDispatcherLogger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string, detail?: unknown): void;
+}
+/**
+ * The verdict of validating an untrusted inbound activity: its primary type, or a
+ * compact failure summary. The app owns the validation (its zod schemas); the
+ * engine owns the drop-with-warn behaviour so every app logs identically.
+ */
+export type InboundActivityValidation = {
+    ok: true;
+    type: string;
+} | {
+    ok: false;
+    summary: string;
+};
+/** The Oxy-user fields the engine reads off a resolved local user (Follow target). */
+export interface InboundLocalUser {
+    _id?: string | null;
+    id?: string | null;
+}
+/** The actor↔Oxy-user identity bridge the follow verbs use. */
+export interface InboundIdentity {
+    /** Resolve a local username to its Oxy user (the Follow target). Null when unknown. */
+    resolveUserByUsername(username: string): Promise<InboundLocalUser | null>;
+    /** Create the Oxy follow edge (`POST /federation/follow`). Throws on transport failure (retry). */
+    bridgeFollow(followerOxyUserId: string, localUserId: string): Promise<void>;
+    /** Remove the Oxy follow edge. Throws on transport failure (retry). */
+    bridgeUnfollow(followerOxyUserId: string, localUserId: string): Promise<void>;
+}
+/** The fediverse-sharing consent gate for the inbound Follow. */
+export interface InboundConsent {
+    /** Sync read off an already-resolved user object (absent flag ⇒ enabled). */
+    isSharingEnabledFromUser(user: InboundLocalUser): boolean;
+}
+/** The actor resolver subset the inbound follow uses (resolve + require an Oxy id). */
+export interface InboundActorResolver {
+    /** Resolve/mint the follower actor and its Oxy user (`getOrFetchActor`). */
+    getOrFetchActor(actorUri: string): Promise<{
+        oxyUserId?: string | null;
+    } | null>;
+}
+/** Bring-your-own-store: the AP follow records + actor cache reads the follow verbs need. */
+export interface InboundFollowStore {
+    /** `handleIncomingFollow`: upsert the accepted inbound follow row. */
+    upsertInboundAccepted(localUserId: string, remoteActorUri: string, activityId: string): Promise<void>;
+    /** `handleUndo(Follow)`: the inbound follow row (scoped by localUserId when known). */
+    findInboundFollow(remoteActorUri: string, localUserId?: string): Promise<{
+        _id: unknown;
+        localUserId: string;
+    } | null>;
+    /** `handleUndo(Follow)`: delete a follow row by id. */
+    deleteFollowById(id: unknown): Promise<void>;
+    /** `handleUndo(Follow)`: the follower actor's cached Oxy user id (for `bridgeUnfollow`). */
+    findActorOxyUserId(uri: string): Promise<string | null | undefined>;
+    /** `handleAccept`: mark the matching outbound-pending follow accepted BY its activity id. Returns whether a row changed. */
+    markOutboundAcceptedByActivityId(remoteActorUri: string, activityId: string): Promise<boolean>;
+    /** `handleAccept`: mark ANY outbound-pending follow for this actor accepted. Returns whether a row changed. */
+    markOutboundAcceptedAnyPending(remoteActorUri: string): Promise<boolean>;
+    /** `handleReject`: mark the matching outbound-pending follow rejected. */
+    markOutboundRejected(remoteActorUri: string, activityId?: string): Promise<void>;
+}
+/** The delivery subset the inbound Follow uses (send the Accept back). */
+export interface InboundDelivery {
+    sendAccept(localOxyUserId: string, localUsername: string, followActivityId: string, remoteActorUri: string): Promise<void>;
+}
+/** Adapters + hooks an {@link InboundDispatcher} is built from. */
+export interface InboundDispatcherConfig {
+    /**
+     * The app's per-instance domain policy (`DomainPolicy.isBlockedDomain`) — our own
+     * ActivityPub domains, the Oxy identity apex, and every explicitly suspended
+     * instance. Applied to the host of the VERIFIED origin actor before an inbound
+     * activity is dispatched, so a suspended instance can create nothing here.
+     *
+     * REQUIRED, deliberately: an app that forgets to wire it would silently federate
+     * with every instance it has ever cached, which is exactly the failure this gate
+     * exists to prevent. A missing policy must be a compile error, not a quiet hole.
+     */
+    isBlockedDomain(host: string): boolean;
+    /** Validate + extract the primary type of an untrusted inbound activity (app's zod schemas). */
+    validateActivity(activity: Record<string, unknown>): InboundActivityValidation;
+    /** The actor↔Oxy-user identity bridge. */
+    identity: InboundIdentity;
+    /** The fediverse-sharing consent gate. */
+    consent: InboundConsent;
+    /** The actor resolver (resolve the follower actor). */
+    actorResolver: InboundActorResolver;
+    /** The AP follow-record store. */
+    follows: InboundFollowStore;
+    /** The delivery service (send the Accept). */
+    delivery: InboundDelivery;
+    /**
+     * Best-effort: notify the local user of a newly-accepted inbound follow.
+     * NEVER throws (it handles its own errors); a failure must not fail (and thus
+     * retry) the inbox activity. Absent ⇒ no notification.
+     */
+    onInboundFollowAccepted?(localUserId: string, followerOxyUserId: string, actorUri: string): Promise<void>;
+    /**
+     * Best-effort: backfill the newly-followed remote actor's recent posts after an
+     * outbound Follow was Accepted. NEVER throws. Absent ⇒ no backfill.
+     */
+    onOutboundFollowAccepted?(actorUri: string): Promise<void>;
+    /**
+     * Handle a CONTENT activity the engine does not own — Create / Announce / Like /
+     * Delete / Update, and a non-follow Undo. The app's post/engagement handlers.
+     */
+    onContentActivity(activity: Record<string, unknown>, verifiedActorUri: string): Promise<void>;
+    /** Diagnostics sink. */
+    logger: InboundDispatcherLogger;
+}
+/** The inbound-activity dispatcher. */
+export interface InboundDispatcher {
+    /** Process one already-actor-verified inbound activity. */
+    processInboxActivity(activity: Record<string, unknown>, verifiedActorUri: string): Promise<void>;
+}
+/** Build the inbound-activity dispatcher from an app's adapters + content handlers. */
+export declare function createInboundDispatcher(config: InboundDispatcherConfig): InboundDispatcher;

package/dist/types/node/index.d.ts

@@ -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, 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/dist/types/node/signedFetch.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `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 { type HttpSignatureSigner } from '../httpSignature';
+/** 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>;
+/**
+ * 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 declare function createSignedFetch(config: CreateSignedFetchConfig): SignedFetch;

package/dist/types/node/webfingerRouter.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 type { UrlBuilders } from '../urls';
+/** 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 declare function createWebfingerRouter(config: WebfingerRouterConfig): Router;

package/dist/types/urls.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 declare function createUrlBuilders(domain: string, actorDomain?: string): UrlBuilders;
+/**
+ * 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 declare const INSTANCE_ACTOR_USERNAME = "instance";
+/** Normalize a local actor username from a path segment or WebFinger acct local-part. */
+export declare function normalizeActorUsername(username: string): string;

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@oxy.so/federation",
+  "version": "1.0.0",
+  "description": "Oxy Federation — the app-agnostic ActivityPub identity + follow engine substrate: the network-connector contract, normalized cross-network DTOs, HTTP signatures, actor resolution, the outbound delivery transport + follow lifecycle, the inbound dispatcher, and the webfinger/actor/inbox Express routers. Domain-parameterized so every Oxy app backend federates under its own domain.",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "node": [
+        "dist/types/node/index.d.ts"
+      ]
+    }
+  },
+  "source": "src/index.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      },
+      "default": "./dist/esm/index.js"
+    },
+    "./node": {
+      "import": {
+        "types": "./dist/types/node/index.d.ts",
+        "default": "./dist/esm/node/index.js"
+      },
+      "require": {
+        "types": "./dist/types/node/index.d.ts",
+        "default": "./dist/cjs/node/index.js"
+      },
+      "default": "./dist/esm/node/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "NOTICE",
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "oxyhq",
+    "federation",
+    "activitypub",
+    "webfinger",
+    "fediverse",
+    "connector"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OxyHQ/OxyHQServices",
+    "directory": "packages/federation"
+  },
+  "author": "OxyHQ",
+  "license": "Apache-2.0",
+  "homepage": "https://oxy.so",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "bun run --filter @oxy.so/contracts build && bun run --filter @oxy.so/protocol build && bun run --filter @oxy.so/core build && bun run build:cjs && bun run build:esm && bun run build:types",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json && node scripts/fix-esm-imports.mjs",
+    "build:types": "tsc -p tsconfig.types.json",
+    "clean": "rm -rf dist",
+    "typescript": "tsc --noEmit",
+    "test": "jest --passWithNoTests",
+    "lint": "biome lint --error-on-warnings ./src",
+    "prepublishOnly": "node ../../scripts/assert-bun-publish.mjs && bun run clean && bun run build",
+    "release": "rm -rf dist && bun run build && release-it"
+  },
+  "release-it": {
+    "git": {
+      "tagName": "@oxy.so/federation@${version}",
+      "tagAnnotation": "Release @oxy.so/federation@${version}",
+      "commitMessage": "chore(federation): release @oxy.so/federation@${version}"
+    },
+    "github": {
+      "release": true,
+      "releaseName": "@oxy.so/federation@${version}"
+    },
+    "npm": {
+      "publish": true
+    }
+  },
+  "dependencies": {
+    "@oxy.so/contracts": "^1.0.0",
+    "@oxy.so/core": "^1.0.0"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/express": "^4.17.25",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.20.1",
+    "express": "^4.22.2",
+    "jest": "^30.5.1",
+    "release-it": "^19.0.6",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.4.12",
+    "typescript": "^5.9.2"
+  }
+}