@oxy.so/federation 1.0.0

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

@@ -0,0 +1,287 @@
+/**
+ * Resolution, caching and refresh of remote ActivityPub actors.
+ *
+ * Extracted behaviour-identically from Mention's `ActorService`. The engine owns
+ * the PROTOCOL — webfinger resolution, the signed actor fetch, the redirect /
+ * WebFinger fallback, the 410-Gone tombstone, the self-consistency + same-origin
+ * guards, and the staleness/refresh policy. Everything app-specific is injected:
+ *
+ *  - the FederatedActor CACHE lives in the app DB, reached through a
+ *    {@link FederatedActorStore} adapter ("bring your own store" — no data move),
+ *  - the actor↔Oxy-user bridge is the injected {@link ActorResolverIdentity}
+ *    (`PUT /users/resolve` + actor-gone archive),
+ *  - the signed AP fetch + the SSRF-safe WebFinger fetch are injected transports,
+ *  - remote-text normalization is an injected {@link ActorTextAdapter} (the app's
+ *    canonical normalizer + sanitizer), so the engine ships no HTML deps.
+ *
+ * The resolver is generic over the app's stored actor record shape (`TActor`,
+ * e.g. Mention's `IFederatedActor`) so callers keep full typing on the returned
+ * document.
+ */
+import { type DeriveNetworkIdentity } from '../networkIdentity';
+import type { NormalizedExternalActor } from '../index';
+import type { SignedFetch } from './signedFetch';
+import type { ReportActorGoneOutcome } from './identityBridge';
+/** The minimal fields the resolver reads off / writes to a stored actor record. */
+export interface FederatedActorRecordBase {
+    _id?: unknown;
+    uri: string;
+    acct?: string;
+    oxyUserId?: string | null;
+    avatarUrl?: string;
+    headerUrl?: string;
+    publicKeyPem?: string;
+    lastFetchedAt?: Date | null;
+}
+/** A verified profile field (PropertyValue) stored on the actor cache. */
+export interface FederatedActorField {
+    name: string;
+    value: string;
+    verifiedAt?: Date;
+}
+/** The full write shape the resolver upserts into the actor cache. */
+export interface FederatedActorUpsert {
+    protocol: 'activitypub';
+    uri: string;
+    username: string;
+    domain: string;
+    acct: string;
+    summary: string;
+    avatarUrl?: string;
+    headerUrl?: string;
+    inboxUrl?: string;
+    outboxUrl?: string;
+    sharedInboxUrl?: string;
+    followersUrl?: string;
+    followingUrl?: string;
+    publicKeyPem?: string;
+    publicKeyId?: string;
+    type: string;
+    manuallyApprovesFollowers: boolean;
+    discoverable: boolean;
+    memorial: boolean;
+    suspended: boolean;
+    fields: FederatedActorField[];
+    featuredUrl?: string;
+    featuredTagsUrl?: string;
+    alsoKnownAs?: string[];
+    /**
+     * The `<handle>@<network-domain>` identity this actor was re-labelled onto, when
+     * it came from a bridge; absent for the ordinary actor whose identity is simply
+     * its acct.
+     *
+     * Persisted rather than re-derived on demand because it is the key two rows are
+     * the SAME PERSON on: the same X account mirrored by two different bridges
+     * produces two actor rows with different URIs and different accts, and this is
+     * the only field on which they match. An app that de-duplicates bridged
+     * identities queries it; one that does not can ignore it.
+     */
+    networkAcct?: string;
+    remoteCreatedAt?: Date;
+    followersCount: number;
+    followingCount: number;
+    postsCount: number;
+    lastFetchedAt: Date;
+}
+/** Bring-your-own-store: the AP actor cache stays in the app DB behind this adapter. */
+export interface FederatedActorStore<TActor extends FederatedActorRecordBase> {
+    /** Look up a cached actor by its protocol URI. */
+    findActorByUri(uri: string): Promise<TActor | null>;
+    /** Upsert (create-or-update) the actor cache row keyed by `uri`. */
+    upsertActor(uri: string, update: FederatedActorUpsert): Promise<TActor | null>;
+    /** Look up a cached actor by its `publicKey.id` (HTTP-signature key resolution). */
+    findActorByPublicKeyId(keyId: string): Promise<Pick<TActor, 'uri' | 'publicKeyPem'> | null>;
+    /** Stamp the resolved Oxy user id onto an actor row (identified by its `_id`). */
+    setActorOxyUserId(actorId: unknown, oxyUserId: string): Promise<void>;
+    /**
+     * Tombstone a permanently-gone actor (mark it suspended) and return its linked
+     * Oxy user id (or null when no row matched).
+     */
+    tombstoneActor(uri: string): Promise<{
+        oxyUserId?: string | null;
+    } | null>;
+}
+/** The identity-bridge subset the actor resolver depends on. */
+export interface ActorResolverIdentity {
+    resolveExternalUser(actor: NormalizedExternalActor, opts?: {
+        forceAvatarRefresh?: boolean;
+    }): Promise<string | null>;
+    reportActorGone(oxyUserId: string): Promise<ReportActorGoneOutcome>;
+}
+/**
+ * App-supplied normalization of remote actor text. The engine owns WHICH fields
+ * to read and the order; the app owns HOW to normalize (its canonical whitespace
+ * normalizer + HTML sanitizer), so the engine ships no HTML/entity dependency.
+ */
+export interface ActorTextAdapter {
+    /** One-line field (preferredUsername / name / PropertyValue name); '' for non-strings. */
+    inlineField(value: unknown): string;
+    /** Entity-decode + inline-normalize a display name. */
+    inlineDisplayName(raw: string): string;
+    /** Sanitize (safe inline markup only) + inline-normalize a PropertyValue html value. */
+    sanitizeFieldValue(html: string): string;
+    /** Multiline HTML → plain text (the actor bio/summary). */
+    htmlToPlainText(html: string): string;
+    /**
+     * Qualify the bare `@handle`s an actor wrote in its own bio with the network
+     * they belong to — `@openai` on an X-relabelled actor means `@openai@x.com`.
+     *
+     * A handle is only meaningful beside the network it was written on, and that
+     * context is exactly what is lost when the text crosses over: copied verbatim,
+     * `@openai` reads on the receiving server as a LOCAL name, pointing readers at
+     * whoever holds it there.
+     *
+     * OPTIONAL, and the engine does not care whether an app supplies it: the rule
+     * for what may be a handle is the app's (Mention scans with the same entity
+     * scanner its composer and renderer use, so a URL's `@handle`, an email and an
+     * already-qualified handle are all left alone by construction). An app that
+     * omits it gets the previous behaviour exactly.
+     *
+     * Applied ONCE, where the bio is settled — so the stored actor row and the Oxy
+     * profile cannot disagree, and no renderer is left to re-derive it.
+     */
+    qualifyHandles?(text: string, instanceDomain: string): string;
+}
+/** A parsed WebFinger JRD (only the `links` we read). */
+export interface WebFingerJrd {
+    links?: Array<{
+        rel?: string;
+        type?: string;
+        href?: string;
+    }>;
+}
+/**
+ * SSRF-safe bounded WebFinger fetch: GET the JRD URL and return the parsed JSON,
+ * or `null` on a non-2xx response. MAY throw on a network / parse / size-limit
+ * failure — the resolver catches it and treats the resolution as failed.
+ */
+export type WebFingerFetch = (url: string) => Promise<WebFingerJrd | null>;
+/** Minimal logging sink the actor resolver writes to. */
+export interface ActorResolverLogger {
+    info(message: string): void;
+    warn(message: string, detail?: unknown): void;
+}
+/** Adapters + config an {@link ActorResolver} is built from. */
+export interface ActorResolverConfig<TActor extends FederatedActorRecordBase> {
+    /** Whether federation is enabled (gates background refreshes). */
+    federationEnabled: boolean;
+    /** Signed AP GET (actor + collection-count fetches). */
+    signedFetch: SignedFetch;
+    /** SSRF-safe bounded WebFinger fetch. */
+    fetchWebFinger: WebFingerFetch;
+    /** Per-instance blocked-domain check (own domains + identity apex + configured blocks). */
+    isBlockedDomain: (domain: string) => boolean;
+    /** Canonicalize a fediverse acct (`user@domain`), or undefined when invalid. */
+    normalizeFederatedAcct: (acct: string | undefined) => string | undefined;
+    /** Extract the domain from a canonical acct. */
+    domainFromAcct: (acct: string) => string | undefined;
+    /** Recursively find the first absolute http(s) URL in a value (icon/image). */
+    firstStringUrl: (value: unknown) => string | undefined;
+    /**
+     * Optional re-labelling of a bridged actor onto its real network. Absent means
+     * every actor keeps the identity of the host it was fetched from.
+     */
+    deriveNetworkIdentity?: DeriveNetworkIdentity;
+    /** The app's actor cache store. */
+    store: FederatedActorStore<TActor>;
+    /** The actor↔Oxy-user identity bridge. */
+    identity: ActorResolverIdentity;
+    /** Remote-text normalization. */
+    text: ActorTextAdapter;
+    /** Diagnostics sink. */
+    logger: ActorResolverLogger;
+}
+/**
+ * Resolution, caching and refresh of remote ActivityPub actors, over app-provided
+ * storage + identity + transports. A class so that internal cross-calls dispatch
+ * through the instance (e.g. `fetchRemoteActor` → `this.tombstoneGoneActor`),
+ * which keeps them spy-able and overridable in tests.
+ */
+export declare class ActorResolver<TActor extends FederatedActorRecordBase> {
+    private readonly config;
+    /** Actor URIs with an in-flight background refresh (guards against refresh storms). */
+    private readonly inFlightActorRefreshes;
+    constructor(config: ActorResolverConfig<TActor>);
+    /**
+     * Whether an actor URI's host is refused by the instance domain policy. An
+     * unparseable URI has no host to check, so it is refused too — the policy is a
+     * safety gate and fails closed rather than letting a malformed URI slip past it.
+     */
+    private isBlockedActorUri;
+    private acctMatchesActorHost;
+    /**
+     * Resolve a WebFinger acct to an ActivityPub actor URI.
+     * @param acct - e.g. "alice@mastodon.social" or "@alice@mastodon.social"
+     */
+    resolveWebFinger(acct: string): Promise<string | null>;
+    /**
+     * Fetch and store/update a remote ActivityPub actor by URI.
+     *
+     * @param actorUri - the remote actor URI to fetch.
+     * @param forceAvatarRefresh - when true, tell Oxy's `PUT /users/resolve` to
+     *   re-download and replace the federated avatar even if it already has a stored
+     *   file ID. Pass `true` from refresh paths and `false` for first-time creation.
+     */
+    fetchRemoteActor(actorUri: string, forceAvatarRefresh?: boolean, acctHint?: string): Promise<TActor | null>;
+    /**
+     * Run the app's {@link DeriveNetworkIdentity} hook and REFUSE any result the
+     * identity bridge could not bind.
+     *
+     * oxy-api binds a federated username to its domain, so a `federatedUsername`
+     * that does not end with `@${instanceDomain}` would be rejected downstream — or
+     * worse, mint an identity under a domain it does not name. Validating here means
+     * no app can produce that shape, and a hook that gets it wrong degrades to the
+     * actor's real protocol acct (the pre-hook behaviour) instead of losing the
+     * actor. The refusal is logged: it is a bug in the app's rule, not a normal
+     * outcome, and it must not pass silently.
+     */
+    private resolveNetworkIdentity;
+    /**
+     * Tombstone a remote actor that returned a definitive 410 Gone. Marks the stored
+     * actor suspended (via the store) and, when it links to an Oxy identity, asks
+     * oxy-api to archive it so it drops out of search.
+     *
+     * Best-effort and fail-soft: neither the store write nor the Oxy archive call is
+     * allowed to throw out of the caller. Idempotent.
+     */
+    tombstoneGoneActor(actorUri: string): Promise<void>;
+    /** Fetch the totalItems count from an ActivityPub collection URL. */
+    private fetchCollectionCount;
+    /**
+     * Get a cached actor or fetch if missing/stale (>24h).
+     *
+     * Never blocks on remote network I/O when a cached actor already exists: a stale
+     * cached actor is returned immediately and a background refresh is enqueued. Only
+     * a completely missing actor triggers a blocking fetch.
+     */
+    getOrFetchActor(actorUri: string): Promise<TActor | null>;
+    /**
+     * Enqueue a fire-and-forget full-actor refresh. Safe to call on a client request
+     * path: it returns synchronously and the fetch runs detached. Guards against
+     * refresh storms (in-flight dedup + a recency skip unless the profile is
+     * incomplete). The avatar refresh is forced only when the actor already exists.
+     */
+    refreshActorInBackground(actorUri: string, existing?: TActor): void;
+    /**
+     * Resolve a remote actor URI to its listable Oxy user id. Returns null when the
+     * actor cannot be resolved to an Oxy user — callers must then skip.
+     */
+    resolveActorOxyUserId(actorUri: string): Promise<string | null>;
+    /**
+     * Fetch a public key by keyId (used for HTTP signature verification).
+     *
+     * Deliberately NOT domain-policy gated on the cached branch: this answers "what
+     * key signs for this keyId", a question about authenticity, not about whether we
+     * federate with the answer. Suspending an instance is enforced where the activity
+     * is dispatched (`createInboundDispatcher`), so a blocked instance's signature is
+     * still evaluated honestly and its activity is then dropped as policy, rather
+     * than being reported as a forged signature. The uncached branch still refuses,
+     * because resolving it would mean network I/O toward a blocked host.
+     */
+    fetchPublicKey(keyId: string): Promise<{
+        publicKeyPem: string;
+        actorUri: string;
+    } | null>;
+}
+/** Build the remote-actor resolver from an app's storage + identity + transports. */
+export declare function createActorResolver<TActor extends FederatedActorRecordBase>(config: ActorResolverConfig<TActor>): ActorResolver<TActor>;

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

@@ -0,0 +1,108 @@
+/**
+ * The ActivityPub actor + inbox + follow-graph router.
+ *
+ * Serves the engine-owned half of the `/ap` namespace:
+ *  - `GET /users/:username` — the local `Person` actor (and the special `instance`
+ *    Application actor used for signed fetches),
+ *  - `POST /users/:username/inbox` + `POST /inbox` — inbound delivery, with HTTP
+ *    signature verification (Phase 2, `trustForwardedHost`) and actor-match, then
+ *    202 + async dispatch to the injected inbound dispatcher,
+ *  - `GET /users/:username/followers` + `/following` — the OXY follow graph
+ *    (local + bridged federated edges) as paginated `OrderedCollection`s.
+ *
+ * The CONTENT routes (`outbox`, `featured`, per-post dereference) stay in the app,
+ * mounted on the SAME `/ap/users/:username/*` prefix the actor advertises.
+ *
+ * Extracted behaviour-identically from Mention's `ap.routes.ts`. Everything
+ * app-specific — the actor's Oxy profile, the banner, the fediverse-sharing gate,
+ * the public-key lookup, the inbox enqueue transport, the follow-graph page fetch
+ * — is injected.
+ */
+import { Router } from 'express';
+import type { AccountKind } from '@oxy.so/contracts';
+import type { User } from '@oxy.so/core';
+import type { UrlBuilders } from '../urls';
+import type { LocalActorBuilder } from '../actorObject';
+/** The resolved-user fields the actor + collection routes read. */
+export interface ActorRouteUser {
+    _id?: string | null;
+    id?: string | null;
+    name?: {
+        displayName?: string | null;
+    } | null;
+    bio?: string | null;
+    avatar?: string | null;
+    createdAt?: string | null;
+    /** Account-graph classification — decides the actor `type`. */
+    kind?: AccountKind | null;
+    _count?: {
+        followers?: number;
+        following?: number;
+    } | null;
+}
+/** The tri-state consent read for a username with no already-resolved user object. */
+export type ActorSharingState = 'enabled' | 'disabled' | 'unknown-user' | 'unavailable';
+/** Minimal logging sink the actor router writes to. */
+export interface ActorRouterLogger {
+    debug(message: string, detail?: unknown): void;
+    warn(message: string, detail?: unknown): void;
+    error(message: string, detail?: unknown): void;
+}
+/** A page of a user's follow graph (from the authoritative Oxy graph). */
+export interface FollowPage {
+    members: User[];
+    total: number;
+    hasMore: boolean;
+}
+/** Adapters + config a {@link createActorRouter} is built from. */
+export interface ActorRouterConfig {
+    /** The app's federation domain (the human-facing `url` host + non-AP redirect target). */
+    domain: string;
+    /** Whether federation is enabled (all routes 404 when off). */
+    federationEnabled: boolean;
+    /** The AP content type (`application/activity+json`). */
+    apContentType: string;
+    /** Per-instance URL builders. */
+    urls: UrlBuilders;
+    /** True when the request's Accept header asks for ActivityPub JSON. */
+    wantsActivityPub(accept: string | string[] | undefined): boolean;
+    /** Fetch the public keyId + PEM for a username (`instance` for the server actor). */
+    getPublicKey(username: string): Promise<{
+        keyId: string;
+        publicKeyPem: string;
+    }>;
+    /** Resolve a username to its Oxy user (null when unknown). */
+    resolveUser(username: string): Promise<ActorRouteUser | null>;
+    /** The fediverse-sharing consent gate. */
+    consent: {
+        isSharingEnabledFromUser(user: ActorRouteUser): boolean;
+        getSharingStateByUsername(username: string): Promise<ActorSharingState>;
+    };
+    /** The single local-actor builder (shared with the `Update(Person)` broadcast). */
+    buildLocalActorObject: LocalActorBuilder;
+    /** The app-owned profile banner (Mention: `UserSettings.profileHeaderImage`). */
+    getBanner(oxyUserId: string): Promise<string | null>;
+    /** Inbound-delivery adapters. */
+    inbound: {
+        /** Resolve a `keyId` to its public key PEM + owning actor uri (HTTP-sig verify). */
+        fetchPublicKey(keyId: string): Promise<{
+            publicKeyPem: string;
+            actorUri: string;
+        } | null>;
+        /** Whether to trust `X-Forwarded-Host` when reconstructing the signed host line. */
+        trustForwardedHost: boolean;
+        /** Enqueue a verified inbound activity for async processing (false ⇒ process inline). */
+        enqueueInboxActivity(job: {
+            activity: Record<string, unknown>;
+            verifiedActorUri: string;
+        }): Promise<boolean>;
+        /** The inbound dispatcher (the inline-fallback + post-enqueue processor). */
+        processInboxActivity(activity: Record<string, unknown>, verifiedActorUri: string): Promise<void>;
+    };
+    /** Fetch one page of a user's Oxy follow graph (followers OR following). */
+    fetchFollowPage(userId: string, direction: 'followers' | 'following', offset: number, limit: number): Promise<FollowPage>;
+    /** Diagnostics sink. */
+    logger: ActorRouterLogger;
+}
+/** Build the actor + inbox + follow-graph router for an app's domain. */
+export declare function createActorRouter(config: ActorRouterConfig): Router;

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

@@ -0,0 +1,248 @@
+/**
+ * Outbound activity delivery + the follow lifecycle (Follow / Undo(Follow) /
+ * Accept(Follow)) and the `Update(Person)` actor rebroadcast.
+ *
+ * The delivery TRANSPORT (sign → SSRF-safe POST → BullMQ / durable fallback queue),
+ * the shared-inbox dedup fan-out, and the follow-protocol activity shapes are the
+ * SAME across every Oxy app, so they live here — behaviour-identical to Mention's
+ * former `FollowService` delivery half. Everything app-specific is injected:
+ *
+ *  - private-key CUSTODY stays behind the {@link DeliveryKeys} adapter (Mention:
+ *    oxy-api `/federation/sign` + `/federation/public-key`); the key never enters
+ *    this package,
+ *  - the SSRF-safe single-hop POST + the BullMQ enqueue + the durable
+ *    fallback are the {@link DeliveryTransport}, so the delivery policy stays in
+ *    one place (Mention's `fetchUpstreamSingleHop` + `FederationDeliveryQueue`),
+ *  - the AP-specific `FederatedActor` / `FederatedFollow` rows stay in the app DB
+ *    behind the {@link DeliveryActorStore} / {@link DeliveryFollowStore} adapters
+ *    ("bring your own store" — no data move),
+ *  - the actor cache refresh (for a follow whose target inbox is not yet known),
+ *    the consent gate, the actor-profile resolver, the banner, and the local-actor
+ *    builder are all injected.
+ *
+ * The CONTENT federate methods (build the Note / boost / like) STAY in the app and
+ * call `deliverToFollowers` / `deliverActivity` / `queueDelivery` here.
+ */
+import type { AccountKind } from '@oxy.so/contracts';
+import { type HttpSignatureSigner } from '../httpSignature';
+import type { UrlBuilders } from '../urls';
+import type { LocalActorBuilder } from '../actorObject';
+/** Minimal logging sink the delivery service writes to. */
+export interface DeliveryLogger {
+    debug(message: string, detail?: unknown): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string, detail?: unknown): void;
+}
+/**
+ * Private-key custody for outbound signing. The private key NEVER enters this
+ * package — `getPublicKey` returns only the actor's public keyId (to name the
+ * signature) and `sign` delegates the RSA-SHA256 signing (Mention → oxy-api).
+ */
+export interface DeliveryKeys {
+    getPublicKey(username: string): Promise<{
+        keyId: string;
+        publicKeyPem: string;
+    }>;
+    sign: HttpSignatureSigner;
+}
+/** A bounded, destroyable byte stream — the raw single-hop delivery response body. */
+export interface DeliveryResponseStream extends AsyncIterable<Buffer | Uint8Array> {
+    destroy(): void;
+}
+/** The result of one SSRF-safe single-hop delivery POST (redirects NOT followed). */
+export interface DeliverSingleHopResult {
+    response: DeliveryResponseStream;
+    status: number;
+}
+/** Per-request options handed to the injected single-hop delivery transport. */
+export interface DeliverSingleHopInit {
+    method: 'POST';
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+    headersTimeoutMs: number;
+}
+/**
+ * An SSRF-safe single-hop POST: validates + IP-pins the URL and returns the raw
+ * response WITHOUT following redirects. Mention adapts its `@oxy.so/core/server`-
+ * backed `fetchUpstreamSingleHop` into this shape.
+ */
+export type DeliverSingleHop = (url: string, init: DeliverSingleHopInit) => Promise<DeliverSingleHopResult>;
+/** A durable-delivery job body (BullMQ + the fallback queue share this shape). */
+export interface DeliveryQueueJob {
+    activityJson: Record<string, unknown>;
+    targetInbox: string;
+    senderOxyUserId: string;
+}
+/**
+ * The durable-delivery fallback (written when BullMQ is unavailable).
+ *
+ * App-supplied, like every other store in this package: the engine never names
+ * a database. Mention backs it with Postgres; the method names below are the
+ * ones its original Mongoose collection exposed and are kept only so the
+ * adapter shape stays stable for consumers.
+ */
+export interface DeliveryFallbackQueue {
+    /** Insert one fallback delivery row (`queueDelivery`). */
+    create(job: DeliveryQueueJob & {
+        nextAttemptAt: Date;
+    }): Promise<unknown>;
+    /** Insert many fallback delivery rows in one write (`deliverToFollowers`). */
+    insertMany(jobs: Array<DeliveryQueueJob & {
+        nextAttemptAt: Date;
+    }>): Promise<unknown>;
+}
+/** The delivery transport: BullMQ enqueue with a durable app-supplied fallback. */
+export interface DeliveryTransport {
+    /**
+     * Enqueue one durable delivery. Resolves `false` when the queue is unavailable
+     * (Redis not configured) so the engine falls back to {@link DeliveryFallbackQueue}.
+     * May REJECT (the engine treats a rejection as `false` and falls back).
+     */
+    enqueueDelivery(job: DeliveryQueueJob): Promise<boolean>;
+    fallbackQueue: DeliveryFallbackQueue;
+}
+/**
+ * The delivery-relevant fields of a stored remote actor. `TActor` (the app's own
+ * `FederatedActor` shape) extends this; the engine reads only these fields and
+ * hands the FULL record back to `actorRefresh.refreshActorInBackground`.
+ */
+export interface DeliveryActorFields {
+    _id?: unknown;
+    uri: string;
+    sharedInboxUrl?: string | null;
+    inboxUrl?: string | null;
+    manuallyApprovesFollowers?: boolean;
+}
+/** Bring-your-own-store: the AP actor cache stays in the app DB behind this adapter. */
+export interface DeliveryActorStore<TActor extends DeliveryActorFields> {
+    /** One cached actor by uri (`resolveActorInbox` / `sendFollow` / `sendUndoFollow` / `sendAccept`). */
+    findActorByUri(uri: string): Promise<TActor | null>;
+    /** Inbox fields for many actor uris (`deliverToFollowers`, step 2). */
+    findActorInboxesByUris(uris: string[]): Promise<Array<Pick<DeliveryActorFields, 'sharedInboxUrl' | 'inboxUrl'>>>;
+}
+/** Bring-your-own-store: the AP follow records stay in the app DB behind this adapter. */
+export interface DeliveryFollowStore {
+    /** Accepted inbound followers' remote actor uris (`deliverToFollowers`, step 1). */
+    listAcceptedInboundFollowerActorUris(localOxyUserId: string): Promise<string[]>;
+    /** Upsert an outbound pending follow with its activity id (`sendFollow`). */
+    upsertOutboundPending(localOxyUserId: string, remoteActorUri: string, activityId: string): Promise<void>;
+    /** The outbound follow row for `(localOxyUserId, remoteActorUri)` (`sendUndoFollow`). */
+    findOutbound(localOxyUserId: string, remoteActorUri: string): Promise<{
+        _id: unknown;
+        activityId?: string;
+    } | null>;
+    /** Delete a follow row by id (`sendUndoFollow`). */
+    deleteById(id: unknown): Promise<void>;
+}
+/** The actor-cache refresh the follow path uses when a target inbox is not yet known. */
+export interface DeliveryActorRefresh<TActor extends DeliveryActorFields> {
+    /** Fire-and-forget full-actor refresh (keeps a followee's inbox/profile current). */
+    refreshActorInBackground(actorUri: string, existing?: TActor): void;
+    /** Blocking actor fetch to resolve an inbox when none is cached (`queueFollowOnceActorKnown`). */
+    fetchRemoteActor(actorUri: string): Promise<TActor | null>;
+}
+/** The consent gate — only `federateActorUpdate` gates outbound delivery on it. */
+export interface DeliveryConsent {
+    isSharingEnabled(oxyUserId: string): Promise<boolean>;
+}
+/** The Oxy profile fields the actor `Update` rebroadcast reads. */
+export interface DeliveryActorProfile {
+    name?: {
+        displayName?: string | null;
+    } | null;
+    bio?: string | null;
+    avatar?: string | null;
+    createdAt?: string | null;
+    /**
+     * Account-graph classification — decides the actor `type`. It MUST travel with
+     * the rebroadcast: an `Update` carrying a different `type` from the one the GET
+     * route serves is exactly the drift the shared builder exists to prevent, and
+     * on a type change it is also the migration vehicle (a follower's instance
+     * adopts the new type from this push rather than waiting out its own actor
+     * staleness window).
+     */
+    kind?: AccountKind | null;
+}
+/** Resolve a local username to its Oxy profile (for the `Update(Person)` rebroadcast). */
+export interface DeliveryIdentity {
+    resolveUserByUsername(username: string): Promise<DeliveryActorProfile | null>;
+}
+/** The app-owned profile banner (Mention: `UserSettings.profileHeaderImage`). */
+export interface DeliveryProfile {
+    getBanner(oxyUserId: string): Promise<string | null>;
+}
+/** The result shape of the injected SSRF pre-check for a durable inbox enqueue. */
+export interface SafeUrlVerdict {
+    ok: boolean;
+    reason?: string;
+}
+/** Adapters + config a {@link DeliveryService} is built from. */
+export interface DeliveryServiceConfig<TActor extends DeliveryActorFields> {
+    /** Whether federation is enabled (gates `sendFollow`/`sendUndoFollow`/`federateActorUpdate`). */
+    federationEnabled: boolean;
+    /** User-Agent presented to remote inboxes. */
+    userAgent: string;
+    /** The AP content type (`application/activity+json`) used for delivery headers. */
+    apContentType: string;
+    /** Private-key custody + public keyId lookup. */
+    keys: DeliveryKeys;
+    /** Per-instance URL builders (actor URL for the follow/update activities). */
+    urls: UrlBuilders;
+    /** SSRF-safe single-hop delivery POST (does NOT follow redirects). */
+    deliverSingleHop: DeliverSingleHop;
+    /** SSRF pre-check for a durable inbox enqueue (never queue a delivery to an unsafe URL). */
+    assertSafeInboxUrl(url: string): Promise<SafeUrlVerdict>;
+    /** BullMQ enqueue + the durable fallback queue. */
+    transport: DeliveryTransport;
+    /** The AP actor cache store. */
+    store: DeliveryActorStore<TActor>;
+    /** The AP follow-record store. */
+    follows: DeliveryFollowStore;
+    /** Actor-cache refresh for the follow path. */
+    actorRefresh: DeliveryActorRefresh<TActor>;
+    /** The fediverse-sharing consent gate (used by `federateActorUpdate` only). */
+    consent: DeliveryConsent;
+    /** Resolve a local username to its Oxy profile (`federateActorUpdate`). */
+    identity: DeliveryIdentity;
+    /** App-owned profile banner (`federateActorUpdate`). */
+    profile: DeliveryProfile;
+    /** The single local-actor builder (shared with the actor GET route). */
+    buildLocalActorObject: LocalActorBuilder;
+    /** Diagnostics sink. */
+    logger: DeliveryLogger;
+    /**
+     * The app's per-instance domain policy (`DomainPolicy.isBlockedDomain`) — the
+     * same predicate inbound dispatch and actor resolution use. Outbound delivery
+     * must refuse blocked origins symmetrically: a domain blocked inbound must not
+     * keep receiving Follow/Undo/Accept or follower fan-out via a cached inbox.
+     */
+    isBlockedDomain(host: string): boolean;
+}
+/** The outbound delivery + follow-lifecycle service. */
+export interface DeliveryService {
+    /** Deliver an activity to one remote inbox, signed with the sender's key. */
+    deliverActivity(activity: Record<string, unknown>, targetInbox: string, senderOxyUserId: string, senderUsername: string): Promise<boolean>;
+    /** Queue one activity for durable delivery (BullMQ, fallback queue). */
+    queueDelivery(activity: Record<string, unknown>, targetInbox: string, senderOxyUserId: string): Promise<void>;
+    /** Resolve a remote actor's delivery inbox (shared preferred) from the store. */
+    resolveActorInbox(actorUri: string | undefined): Promise<string | undefined>;
+    /** Deliver to all accepted inbound followers plus `options.extraInboxes` (deduped by shared inbox). */
+    deliverToFollowers(activity: Record<string, unknown>, senderOxyUserId: string, senderUsername: string, options?: {
+        extraInboxes?: string[];
+    }): Promise<void>;
+    /** Send a Follow activity to a remote actor (records the outbound follow, delivers/queues). */
+    sendFollow(localOxyUserId: string, localUsername: string, remoteActorUri: string): Promise<{
+        success: boolean;
+        pending: boolean;
+    }>;
+    /** Send an Undo(Follow) to a remote actor (removes the local follow first). */
+    sendUndoFollow(localOxyUserId: string, localUsername: string, remoteActorUri: string): Promise<boolean>;
+    /** Send an Accept(Follow) back to a remote actor. */
+    sendAccept(localOxyUserId: string, localUsername: string, followActivityId: string, remoteActorUri: string): Promise<void>;
+    /** Rebroadcast the FULL actor document as an Update(Person) to remote followers. */
+    federateActorUpdate(actorOxyUserId: string, username: string): Promise<void>;
+}
+/** Build the outbound delivery + follow-lifecycle service from an app's adapters. */
+export declare function createDeliveryService<TActor extends DeliveryActorFields>(config: DeliveryServiceConfig<TActor>): DeliveryService;