@oxy.so/federation 1.0.0

package/dist/types/apUri.d.ts

@@ -0,0 +1,107 @@
+/**
+ * ActivityPub URI parsing + host canonicalisation + per-instance domain policy.
+ *
+ * `canonicalFederationHost` / `isSameFederationHost` are the one rule for "are
+ * these the same host", and every domain comparison the policy makes is built
+ * out of them. `extractActorUriFromActivityId` is pure and domain-agnostic. The
+ * blocked-domain check and the local-post-id extractor are DOMAIN-SCOPED — they
+ * depend on which hosts an app mints its own URIs under and which identity apex
+ * publishes its own users — so they come from a per-instance
+ * {@link createDomainPolicy} rather than a module-level constant.
+ */
+/**
+ * THE FORM THIS ENGINE COMPARES HOSTS IN — trimmed, lowercased, one leading
+ * `www.` removed, and nothing else.
+ *
+ * It is exported because it is not an implementation detail: it decides whether
+ * two spellings of a host are the SAME host, and {@link createDomainPolicy} —
+ * the blocked-domain gate every inbound activity and every actor fetch passes
+ * through — is built out of this exact function. A consumer that keeps its own
+ * copy of the rule (a moderation blocklist, a transparency page, a content
+ * purge) is keeping a second opinion about which hosts are which, and the moment
+ * the two drift the consumer acts on domains the engine never refused. For a
+ * consumer whose action is irreversible that difference is deleted content.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO
+ *
+ *   It does not strip a TRAILING DOT. `example.com.` is the fully-qualified
+ *   spelling of `example.com` in DNS, but it is a different string here — and
+ *   also on the wire, because `new URL('https://example.com./x').hostname`
+ *   preserves the dot and that value is what the engine feeds in. So the two
+ *   spellings do not match each other, in this function and in the engine
+ *   alike. Widening that is a POLICY decision (it makes a blocklist match hosts
+ *   it does not literally name) and belongs to whoever owns the policy, not to
+ *   a string transform.
+ *
+ *   It does not perform IDNA. The input is expected to be an ASCII host in the
+ *   form the WHATWG URL parser produces — `new URL(...).hostname` has already
+ *   applied ToASCII, so an internationalised host arrives as punycode
+ *   (`xn--ber-goa.example`). A host spelled in unicode is lowercased but NOT
+ *   converted, so it will not match its own punycode wire form. Callers that
+ *   accept operator-typed hosts must convert them before comparing.
+ *
+ * @param host a bare host — no scheme, no port, no path.
+ */
+export declare function canonicalFederationHost(host: string): string;
+/**
+ * Whether two spellings name the same host under {@link canonicalFederationHost}.
+ *
+ * This is the question a caller actually has ("is the host on this activity the
+ * host we blocked?"), and it exists so that asking it does not require each
+ * caller to assemble its own comparison around the normaliser. Assembling one is
+ * where the mistakes happen, and they are quiet ones: a comparison that
+ * lowercases but forgets `www.`, or that allows `www.` on one side only and so
+ * answers differently depending on argument order, looks correct at every call
+ * site and is wrong for exactly the hosts an evasive instance will use.
+ *
+ * A blank string names no host, so it matches nothing — including another blank.
+ * That is the same answer {@link DomainPolicy.isBlockedDomain} gives it: a host
+ * that is not named is not in any set.
+ */
+export declare function isSameFederationHost(a: string, b: string): boolean;
+/**
+ * Given an ActivityPub activity/object ID (URL), extract the actor URI by
+ * trimming everything from the first recognised post-path segment onward.
+ *
+ * e.g. "https://mastodon.social/users/alice/statuses/12345"
+ *    → "https://mastodon.social/users/alice"
+ *
+ * Returns null when the URL is malformed or no post-path segment is found.
+ */
+export declare function extractActorUriFromActivityId(activityId: string): string | null;
+/** Configuration for a per-instance {@link DomainPolicy}. */
+export interface DomainPolicyConfig {
+    /** The app's federation domain (where it mints webfinger / inbox / collection URIs). */
+    domain: string;
+    /** The host that owns actor URIs; defaults to `domain`. */
+    actorDomain?: string;
+    /**
+     * Oxy's identity apex (e.g. `oxy.so`). Every Oxy/Mention user is ALSO published
+     * as `acct:<username>@<apex>` via the DID layer, so an actor on this host is one
+     * of OUR OWN users — resolving it as remote would create duplicate actor rows
+     * for local users. Blocked when set.
+     */
+    identityApex?: string;
+    /** Additional explicitly-blocked domains (case-insensitive). */
+    blockedDomains?: Iterable<string>;
+}
+/** Per-instance domain policy: which hosts are ours/blocked, and our own post-URI shape. */
+export interface DomainPolicy {
+    /**
+     * True when a domain should be rejected for federation — our own ActivityPub
+     * domains, the Oxy identity apex (both publish our own users), or an explicitly
+     * configured blocked domain.
+     */
+    isBlockedDomain(domain: string): boolean;
+    /**
+     * Extract a local Post id from an ActivityPub object URI that points at one of
+     * our own posts (`https://<our-domain>/ap/users/<username>/posts/<postId>`).
+     * Returns null when the URI host is not one of ours or the path does not match
+     * the canonical scheme (the object is remote, resolved by activityId instead).
+     */
+    extractLocalPostId(objectUri: string): string | null;
+}
+/**
+ * Build the per-instance {@link DomainPolicy} from an app's domain configuration.
+ */
+export declare function createDomainPolicy(config: DomainPolicyConfig): DomainPolicy;

package/dist/types/httpSignature.d.ts

@@ -0,0 +1,113 @@
+/**
+ * HTTP Signatures (draft-cavage-http-signatures-12) — the PURE sign/verify
+ * crypto that every Oxy app's ActivityPub federation shares.
+ *
+ * This is the highest-risk surface in the federation engine: the exact bytes of
+ * the signing string, the covered-header list and its order, the signature
+ * parameters, and the `X-Forwarded-Host` host reconstruction are what remote
+ * servers (Mastodon et al.) verify against. A one-character drift silently kills
+ * ALL federation, so this module is a byte-for-byte extraction of Mention's
+ * proven implementation — with the ONLY behavioural knobs made explicit:
+ *
+ *  - **private-key custody is injected** ({@link HttpSignatureSigner}). The
+ *    private key NEVER enters this package; the app supplies a `sign(keyId,
+ *    signingString)` that (for Mention) calls oxy-api `POST /federation/sign`.
+ *  - **`X-Forwarded-Host` trust is opt-in** ({@link VerifyHttpSignatureOptions.trustForwardedHost}).
+ *    Mention runs behind a CF-proxied apex that rewrites the origin `Host`, so it
+ *    passes `true`; a directly-exposed origin leaves it `false`.
+ *
+ * Lives in the isomorphic `.` entry (no Express / Mongoose): it depends only on
+ * the runtime `crypto` builtin (Node / Bun) and is never invoked from browser /
+ * React-Native bundles — RN consumers import only the connector TYPES, which are
+ * erased at compile time.
+ */
+/** The signature algorithm parameter emitted in (and expected on) the `Signature` header. */
+export declare const HTTP_SIGNATURE_ALGORITHM = "rsa-sha256";
+/**
+ * The default content-type folded into the signing string for body-bearing
+ * requests. ActivityPub delivery signs `content-type` (some servers — e.g.
+ * Threads — require it), and the AP content type is always
+ * `application/activity+json`.
+ */
+export declare const DEFAULT_SIGNED_CONTENT_TYPE = "application/activity+json";
+/**
+ * Signs an already-composed signing string with the private key backing `keyId`
+ * and returns the base64 RSA-SHA256 signature. The private key custody lives
+ * behind this function — for Mention it delegates to oxy-api's
+ * `POST /federation/sign` so the key never leaves Oxy.
+ */
+export type HttpSignatureSigner = (keyId: string, signingString: string) => Promise<string>;
+/** Options controlling the signing-string composition (all optional). */
+export interface SignRequestOptions {
+    /**
+     * The content-type value included in the signing string (and covered by the
+     * signature) for body-bearing requests. Defaults to
+     * {@link DEFAULT_SIGNED_CONTENT_TYPE}. The Content-Type request HEADER itself is
+     * set by the deliverer's fetch, not returned here.
+     */
+    contentType?: string;
+}
+/**
+ * Build the HTTP Signature header per draft-cavage-http-signatures-12 and sign it
+ * via the injected {@link HttpSignatureSigner} (the private key never enters this
+ * package).
+ *
+ * The spec-correct signing string is composed locally: `(request-target)`, host,
+ * date, and — for body-bearing requests — digest and content-type. The composed
+ * string is handed to `sign`, and the resulting signature is assembled into the
+ * `Signature:` header.
+ *
+ * Returns the headers to attach to the outbound request (Host, Date, optional
+ * Digest, and Signature). Content-Type is set by the deliverer's fetch.
+ */
+export declare function signRequest(sign: HttpSignatureSigner, keyId: string, method: string, url: string, body?: string, options?: SignRequestOptions): Promise<Record<string, string>>;
+/** An inbound request reduced to what signature verification needs. */
+export interface VerifyHttpRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+}
+/** The verdict of {@link verifyHttpSignature}. */
+export interface VerifyHttpResult {
+    verified: boolean;
+    actorUri?: string;
+    reason?: string;
+}
+/**
+ * Resolve a `keyId` to its public key PEM and the actor URI that owns it, or
+ * `null` when the key cannot be fetched (a failed fetch fails verification).
+ */
+export type FetchPublicKey = (keyId: string) => Promise<{
+    publicKeyPem: string;
+    actorUri: string;
+} | null>;
+/** Options controlling inbound signature verification. */
+export interface VerifyHttpSignatureOptions {
+    /**
+     * When `true`, reconstruct the signed `host` line from `X-Forwarded-Host`
+     * (first comma token) instead of `Host` when the header is present.
+     *
+     * Load-bearing for an edge-proxied apex: when a CDN/edge rewrites the origin
+     * `Host` (e.g. `mention.earth` → `api.mention.earth`) and forwards the ORIGINAL
+     * signed host in `X-Forwarded-Host`, the verifier must rebuild the `host`
+     * signing line from it or the reconstructed string never matches what the
+     * sender signed. A proxy chain may append a comma-separated list whose FIRST
+     * token is the client-facing host. This grants a forger nothing: the signature
+     * cryptographically binds whatever host value the sender signed, so a bogus
+     * `X-Forwarded-Host` simply fails verification. Falls back to `host` when the
+     * header is absent (direct delivery). Defaults to `false` (trust only `Host`).
+     */
+    trustForwardedHost?: boolean;
+    /**
+     * Optional sink for non-fatal diagnostics (key-fetch failure, verify
+     * exception). No-op when omitted. Kept out of the return value so verdicts
+     * stay data-only.
+     */
+    onDebug?: (message: string, detail?: unknown) => void;
+}
+/**
+ * Verify the HTTP signature on an incoming request.
+ * Returns the actor URI (key owner) if valid, null otherwise.
+ */
+export declare function verifyHttpSignature(req: VerifyHttpRequest, fetchPublicKey: FetchPublicKey, options?: VerifyHttpSignatureOptions): Promise<VerifyHttpResult>;

package/dist/types/index.d.ts

@@ -0,0 +1,336 @@
+/**
+ * @oxy.so/federation — the app-agnostic federation substrate (isomorphic `.` entry).
+ *
+ * The pluggable network-connector CONTRACT and the normalized, cross-network
+ * DTOs every connector produces. An app's content/MTN core never knows about
+ * Mastodon (ActivityPub) or Bluesky (atproto); it only ever talks to a
+ * {@link NetworkConnector}. This module is that seam: the normalized DTOs every
+ * connector produces, the local-event union connectors deliver outbound, and
+ * the connector interface itself.
+ *
+ * IMPORTANT: this entry is intentionally free of Mongoose / Express / React
+ * Native so it can be imported from any Oxy app backend (and, in later phases,
+ * share the pure HTTP-signature + actor-object surface with browser/isomorphic
+ * callers). The runnable Express/Node engine — signed fetch, delivery transport,
+ * webfinger/actor/inbox routers, remote-actor resolution — lives under the
+ * separate `./node` subpath so it never enters isomorphic bundles.
+ *
+ * The one piece of app-specific data that flows through the outbound seam — a
+ * local post's canonical content — is a TYPE PARAMETER (`TContent`), supplied by
+ * the consuming app (Mention passes its `PostContent`). The engine holds no
+ * knowledge of any app's post shape.
+ */
+/**
+ * HTTP Signatures (draft-cavage) — the pure sign/verify crypto every Oxy app's
+ * ActivityPub federation shares. Private-key custody is injected; the key never
+ * enters this package.
+ */
+export { signRequest, verifyHttpSignature, HTTP_SIGNATURE_ALGORITHM, DEFAULT_SIGNED_CONTENT_TYPE, type HttpSignatureSigner, type SignRequestOptions, type VerifyHttpRequest, type VerifyHttpResult, type FetchPublicKey, type VerifyHttpSignatureOptions, } from './httpSignature';
+/**
+ * Domain-parameterized ActivityPub URL builders — each app instantiates them once
+ * with its own `FEDERATION_DOMAIN` so every actor stays `@user@its-own-domain`.
+ */
+export { createUrlBuilders, normalizeActorUsername, INSTANCE_ACTOR_USERNAME, type UrlBuilders } from './urls';
+/**
+ * Network identity: the MECHANISM for re-labelling an account republished by a
+ * bridge onto the network it actually came from, plus the network vocabulary and
+ * the bidirectional upstream-profile-URL rule.
+ *
+ * The mechanism is here; the ENTRIES are not, and must not be. Which operators
+ * may be trusted to re-attribute somebody's account is a moderation judgement an
+ * app commits and answers for — `createBridgeRelabeller` takes them as a
+ * parameter so no app inherits another's.
+ */
+export { FEDERATION_NETWORKS, BSKY_NETWORK_DOMAIN, blueskyUsernameFromHandle, createBridgeRelabeller, stripBridgeBoilerplate, upstreamProfileUrl, parseUpstreamProfileUrl, federatedUsernameFromUpstreamUrl, upstreamHandleFromProfileField, upstreamHandleFromAlsoKnownAs, upstreamHandleFromAutomatedActor, upstreamHandleFromPreferredUsername, upstreamHandleFromProxyOf, readProxyDeclarations, type FederationNetwork, type FederationBridgeEntry, type BridgeRelabeller, type BridgeConsentModel, type BridgeDerivation, type BridgedActorField, type DeriveNetworkIdentity, type NetworkIdentity, type NetworkIdentityCandidate, type ProxyDeclaration, } from './networkIdentity';
+/**
+ * The shared JSON-LD `@context` (load-bearing term declarations) and the
+ * ActivityPub URI helpers (actor-uri extraction + the per-instance domain policy:
+ * blocked-domain check + local-post-id extraction).
+ *
+ * `canonicalFederationHost` / `isSameFederationHost` are exported because the
+ * domain policy is not the only thing that has to decide whether two spellings
+ * are the same host: a moderation blocklist, a transparency page and a content
+ * purge all ask the same question about the same hosts, and any of them keeping
+ * its own copy of the rule is a second opinion waiting to diverge from the one
+ * the engine enforces. They are the very functions {@link createDomainPolicy} is
+ * built from — not a parallel implementation that agrees today.
+ */
+export { AP_CONTEXT } from './apContext';
+export { canonicalFederationHost, isSameFederationHost, extractActorUriFromActivityId, createDomainPolicy, type DomainPolicy, type DomainPolicyConfig, } from './apUri';
+/**
+ * The single builder of a LOCAL user's ActivityPub actor document —
+ * byte-identical across apps, with media resolution injected. The actor `type`
+ * follows the Oxy account kind ({@link LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND}).
+ */
+export { createLocalActorBuilder, localActorTypeForAccountKind, isApActorType, AP_ACTOR_TYPES, LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND, type ApActorType, type LocalActorType, type LocalActorBuilder, type LocalActorBuilderConfig, type BuildLocalActorParams, type ActorMediaResolver, } from './actorObject';
+/** Supported external networks. */
+export type NetworkId = 'activitypub' | 'atproto';
+/**
+ * A remote actor normalized into a network-neutral shape. Built by a connector
+ * from its protocol's profile representation, and consumed by the identity
+ * bridge ({@link NetworkConnector.mapIdentity}) to resolve/mint the federated
+ * Oxy user the actor maps to.
+ */
+export interface NormalizedExternalActor {
+    network: NetworkId;
+    /** Stable protocol id: an ActivityPub actor URI, or an atproto DID. */
+    externalId: string;
+    /** Fediverse-style handle (`user@domain` for AP; the atproto handle/DID otherwise). */
+    handle: string;
+    /**
+     * The canonical `local@domain` username this actor is stored under in Oxy — the
+     * exact value passed to `PUT /users/resolve`. Each connector derives it for its
+     * own protocol so the shared identity bridge never has to guess: AP uses the
+     * acct (`user@domain`); atproto synthesizes `<username>@<instance-domain>`, where
+     * a default Bluesky handle drops the redundant `.bsky.social` suffix
+     * (`skylee1.bsky.social` → `skylee1@bsky.social`) and a custom domain keeps its
+     * whole handle (`mayor.nyc.gov` → `mayor.nyc.gov@bsky.social`). It MUST equal
+     * `instanceDomain` after the `@` so oxy-api's username↔domain binding holds.
+     */
+    federatedUsername: string;
+    /**
+     * The instance/origin domain this actor's identity belongs to — the `domain`
+     * passed to `PUT /users/resolve` and stamped on imported `Post.instanceDomain`.
+     * AP: the actor host (e.g. `mastodon.social`); atproto: the handle's parent
+     * domain (e.g. `bsky.social`), since a DID carries no host.
+     */
+    instanceDomain: string;
+    displayName?: string;
+    avatarUrl?: string;
+    bannerUrl?: string;
+    bio?: string;
+    followersCount?: number;
+    followingCount?: number;
+    postsCount?: number;
+    /** The Oxy user this actor resolves to, once known. */
+    oxyUserId?: string;
+}
+/** A single media item on a normalized external post (mirrors the Post media shape). */
+export interface NormalizedExternalMedia {
+    id: string;
+    type: 'image' | 'video';
+    remoteUrl?: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    durationSec?: number;
+    orientation?: 'portrait' | 'landscape' | 'square';
+    aspectRatio?: number;
+}
+/**
+ * A remote post normalized into a network-neutral shape. Mirrors the
+ * `Post.federation` provenance block plus the author and media a connector
+ * resolves while importing it.
+ */
+export interface NormalizedExternalPost {
+    network: NetworkId;
+    /** Globally-unique provenance id (AP activity/object id, or atproto at:// URI). */
+    activityId: string;
+    /** Authoring actor's protocol id (AP actor URI / atproto DID). */
+    actorUri: string;
+    url?: string;
+    inReplyTo?: string;
+    sensitive?: boolean;
+    spoilerText?: string;
+    /** Resolved Oxy author, when the actor already maps to an Oxy user. */
+    authorOxyUserId?: string;
+    text: string;
+    media?: NormalizedExternalMedia[];
+    hashtags?: string[];
+    /**
+     * Resolved @mention Oxy user ids — the stored `mentions` allowlist, keyed by the
+     * `[mention:<id>]` placeholders the connector rewrote into {@link text}.
+     */
+    mentions?: string[];
+    /**
+     * The quoted post's external URI (an atproto `at://` URI / an AP quote uri) when
+     * this post quotes another. Resolved to a local `quoteOf` Post id at import time
+     * by matching an imported post's `federation.activityId`; left unresolved (no
+     * quote link) when the quoted post is not imported locally.
+     */
+    quotedUri?: string;
+    language?: string;
+    languages?: string[];
+    createdAt?: Date;
+}
+/** Options for paging a connector's post fetch. */
+export interface FetchPostsOptions {
+    limit?: number;
+    cursor?: string;
+}
+/** Result of a connector post fetch (opaque per-connector cursor). */
+export interface FetchPostsResult {
+    posts: NormalizedExternalPost[];
+    cursor?: string;
+}
+/**
+ * Local-post shape a `post.create` event carries to outbound delivery.
+ *
+ * `content` is the consuming app's CANONICAL post-content type (`TContent`), not
+ * a trimmed-down copy: a connector needs the post's localized variants and
+ * primary language to declare the post's language on the wire (ActivityPub
+ * `contentMap`, atproto `langs`), and a narrowed structural type here would
+ * silently DROP them at the seam. The federation package never inspects
+ * `content`; it flows through untouched to the app's own connector.
+ */
+export interface LocalPostEventPayload<TContent = unknown> {
+    _id: unknown;
+    content: TContent;
+    hashtags?: string[];
+    mentions?: string[];
+    /** The classifier's resolved primary language — the fallback when the author declared no primary tag. */
+    language?: string;
+    visibility: string;
+    createdAt: string;
+    /**
+     * The boosted original's local Post `_id` when this post is a boost
+     * (`type: 'boost'`). A boost carries an intentionally EMPTY body and MUST NOT
+     * federate as a `Create(Note)` — the connector re-routes it to an `Announce`.
+     * Preserving it through the seam is what lets `POST /posts` `boost_of` avoid
+     * emitting a blank Create.
+     */
+    boostOf?: string | null;
+    /**
+     * The parent's local Post `_id` when this post is a REPLY. The connector emits
+     * the Note with `inReplyTo` (the parent's canonical AP object id) + a
+     * parent-author `Mention`, and unions the parent author's inbox into delivery so
+     * a reply to a remote post threads and notifies its author. Preserving it through
+     * the seam is what lets the `/feed/reply` path federate replies. Absent for a
+     * top-level post.
+     */
+    parentPostId?: string | null;
+}
+/**
+ * The minimal boost shape a `post.boost` / `post.unboost` event carries to
+ * outbound delivery. A boost has no body of its own; the connector federates it
+ * as an `Announce` (or `Undo(Announce)`) of the original post's canonical AP id,
+ * resolved from `boostOf`. `createdAt` stamps the activity's `published`.
+ */
+export interface LocalBoostEventPayload {
+    _id: unknown;
+    boostOf: string;
+    createdAt: string | Date;
+}
+/**
+ * The minimal shape a `post.delete` event carries. A local post's canonical AP
+ * object id is minted deterministically from the deleter's username + this `_id`
+ * (`https://<domain>/ap/users/<username>/posts/<_id>`), so the connector needs
+ * nothing more to emit a `Delete(Tombstone)`. The post row is already gone by the
+ * time this fires — the id is captured BEFORE deletion.
+ */
+export interface LocalDeleteEventPayload {
+    _id: unknown;
+}
+/**
+ * The shape a `post.like` / `post.unlike` event carries to outbound delivery.
+ * A federated-post like federates as a `Like` (or `Undo(Like)`) whose `object` is
+ * the liked original's remote `federation.activityId`, resolved from `postId`, and
+ * delivered ONLY to that origin author's inbox (never fanned out to followers).
+ * The AP activity id is minted deterministically from the native Like doc's `_id`
+ * so the `Undo` re-mints the same id without persisting it.
+ */
+export interface LocalLikeEventPayload {
+    /** The native `Like` document `_id` — the deterministic AP Like activity id. */
+    _id: unknown;
+    /** The liked post's local `_id` — resolved to its canonical AP object id + author inbox. */
+    postId: string;
+}
+/**
+ * A local domain event handed to connectors for outbound delivery. Discriminated
+ * by `kind`: post lifecycle (`post.create` / `post.update` / `post.delete`),
+ * engagement (`post.boost` / `post.unboost` / `post.like` / `post.unlike`), actor
+ * profile changes (`actor.update`), and the follow lifecycle.
+ *
+ * Generic over the app's post-content type `TContent`, carried by the
+ * `post.create` / `post.update` payloads.
+ */
+export type LocalNetworkEvent<TContent = unknown> = {
+    kind: 'post.create';
+    post: LocalPostEventPayload<TContent>;
+    actorOxyUserId: string;
+    actorUsername: string;
+} | {
+    kind: 'post.boost';
+    boost: LocalBoostEventPayload;
+    actorOxyUserId: string;
+    actorUsername: string;
+} | {
+    kind: 'post.unboost';
+    boost: LocalBoostEventPayload;
+    actorOxyUserId: string;
+    actorUsername: string;
+} | {
+    kind: 'post.update';
+    post: LocalPostEventPayload<TContent>;
+    actorOxyUserId: string;
+    actorUsername: string;
+} | {
+    kind: 'post.delete';
+    post: LocalDeleteEventPayload;
+    actorOxyUserId: string;
+    actorUsername: string;
+} | {
+    kind: 'post.like';
+    like: LocalLikeEventPayload;
+    actorOxyUserId: string;
+    actorUsername: string;
+} | {
+    kind: 'post.unlike';
+    like: LocalLikeEventPayload;
+    actorOxyUserId: string;
+    actorUsername: string;
+} | {
+    /**
+     * A local user changed an actor-visible profile field OWNED by the app (e.g.
+     * a `profileHeaderImage` banner). The connector rebroadcasts the FULL actor
+     * document as an `Update(Person)` to remote followers so Mastodon refreshes.
+     * Oxy-owned fields (displayName/avatar/bio) are NOT hooked here — they change
+     * in Oxy, which has no signal into the app (see `federateActorUpdate`).
+     */
+    kind: 'actor.update';
+    actorOxyUserId: string;
+    actorUsername: string;
+} | {
+    kind: 'follow.add';
+    localOxyUserId: string;
+    localUsername: string;
+    targetActorUri: string;
+} | {
+    kind: 'follow.remove';
+    localOxyUserId: string;
+    localUsername: string;
+    targetActorUri: string;
+};
+/** Context passed alongside an inbound payload to {@link NetworkConnector.receive}. */
+export interface ReceiveContext {
+    /** The remote actor URI/DID whose signature was already verified by the transport. */
+    verifiedActorUri: string;
+}
+/**
+ * The common contract every external network speaks behind. A connector owns all
+ * protocol specifics; the registry and the app's content core only ever see this
+ * surface.
+ *
+ * Generic over the app's post-content type `TContent`, which flows through
+ * {@link NetworkConnector.deliver} on `post.create` / `post.update` events.
+ */
+export interface NetworkConnector<TContent = unknown> {
+    /** The network this connector serves. */
+    readonly id: NetworkId;
+    /** Whether this connector is enabled (env-gated). Disabled connectors are skipped. */
+    readonly enabled: boolean;
+    /** True when `subject` (a handle / URI / DID) belongs to this network. */
+    matches(subject: string): boolean;
+    /** Resolve a handle to a normalized actor (webfinger for AP, handle→DID for atproto). */
+    resolve(handle: string): Promise<NormalizedExternalActor | null>;
+    /** Fetch + normalize an actor profile by its protocol id. */
+    fetchProfile(externalId: string): Promise<NormalizedExternalActor | null>;
+    /** Backfill + normalize an actor's recent posts. */
+    fetchPosts(externalId: string, opts?: FetchPostsOptions): Promise<FetchPostsResult>;
+    /** Deliver a local domain event outbound (federate to followers / write a record). */
+    deliver(event: LocalNetworkEvent<TContent>): Promise<void>;
+    /** Process an inbound payload (already actor-verified by the transport). */
+    receive(payload: unknown, ctx: ReceiveContext): Promise<void>;
+    /** Resolve/mint the Oxy user this external actor maps to; null when unresolvable. */
+    mapIdentity(actor: NormalizedExternalActor): Promise<string | null>;
+}