@oxy.so/federation 1.0.0

package/dist/esm/node/delivery.js

@@ -0,0 +1,412 @@
+/**
+ * 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 { AP_CONTEXT } from '../apContext.js';
+import { signRequest } from '../httpSignature.js';
+/** Total time budget for a single delivery POST (connect + response headers). */
+const DELIVER_ACTIVITY_TIMEOUT_MS = 15000;
+/** How many bytes of a failed-delivery response body are read for the debug log. */
+const DELIVERY_RESPONSE_PREVIEW_MAX_BYTES = 1024;
+/** The ActivityStreams public collection — the `to` addressee of a public activity. */
+const AP_PUBLIC = 'https://www.w3.org/ns/activitystreams#Public';
+/** Read a bounded prefix of a failed-delivery response body for the debug log. */
+async function readResponsePreview(response) {
+    const chunks = [];
+    let totalBytes = 0;
+    try {
+        for await (const chunk of response) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            totalBytes += buffer.byteLength;
+            chunks.push(buffer);
+            if (totalBytes >= DELIVERY_RESPONSE_PREVIEW_MAX_BYTES)
+                break;
+        }
+    }
+    catch {
+        return '';
+    }
+    finally {
+        response.destroy();
+    }
+    return Buffer.concat(chunks).toString('utf8', 0, DELIVERY_RESPONSE_PREVIEW_MAX_BYTES);
+}
+/** Build the outbound delivery + follow-lifecycle service from an app's adapters. */
+export function createDeliveryService(config) {
+    const { logger, urls } = config;
+    /** Lowercased host of an absolute URL, or null when unparseable (fails closed). */
+    function urlHost(url) {
+        try {
+            return new URL(url).hostname.toLowerCase();
+        }
+        catch {
+            return null;
+        }
+    }
+    /** True when `url`'s host is missing or on the blocked-domain policy. */
+    function isBlockedUrl(url) {
+        const host = urlHost(url);
+        return host === null || config.isBlockedDomain(host);
+    }
+    async function deliverActivity(activity, targetInbox, senderOxyUserId, senderUsername) {
+        if (isBlockedUrl(targetInbox)) {
+            logger.warn(`[FedDeliver] refusing outbound delivery to blocked inbox ${targetInbox}`);
+            return false;
+        }
+        try {
+            const { keyId } = await config.keys.getPublicKey(senderUsername);
+            const body = JSON.stringify(activity);
+            const sigHeaders = await signRequest(config.keys.sign, keyId, 'POST', targetInbox, body);
+            const allHeaders = {
+                'Content-Type': config.apContentType,
+                'Content-Length': String(Buffer.byteLength(body, 'utf-8')),
+                'User-Agent': config.userAgent,
+                Accept: config.apContentType,
+                ...sigHeaders,
+            };
+            logger.debug(`[FedDeliver] POST ${targetInbox} body=${body} sig-headers=${sigHeaders.Signature?.match(/headers="([^"]+)"/)?.[1]}`);
+            const { response, status } = await config.deliverSingleHop(targetInbox, {
+                method: 'POST',
+                headers: allHeaders,
+                body,
+                signal: AbortSignal.timeout(DELIVER_ACTIVITY_TIMEOUT_MS),
+                headersTimeoutMs: DELIVER_ACTIVITY_TIMEOUT_MS,
+            });
+            if ((status >= 200 && status < 300) || status === 202) {
+                response.destroy();
+                return true;
+            }
+            const responseBody = await readResponsePreview(response);
+            logger.debug(`Activity delivery failed to ${targetInbox}: ${status} body=${responseBody.slice(0, 500)}`);
+            return false;
+        }
+        catch (err) {
+            logger.debug(`Activity delivery error to ${targetInbox}:`, err);
+            return false;
+        }
+    }
+    async function queueDelivery(activity, targetInbox, senderOxyUserId) {
+        if (isBlockedUrl(targetInbox)) {
+            logger.warn(`[FedDeliver] not queueing delivery to blocked inbox ${targetInbox}`);
+            return;
+        }
+        // Defense-in-depth: never enqueue a durable delivery to an unsafe inbox URL.
+        // The per-send POST is already SSRF-pinned, but a blocked URL would otherwise
+        // sit in the queue and be retried forever.
+        const guard = await config.assertSafeInboxUrl(targetInbox);
+        if (!guard.ok) {
+            logger.warn(`[FedDeliver] not queueing unsafe inbox URL ${targetInbox}: ${guard.reason}`);
+            return;
+        }
+        const enqueued = await config.transport
+            .enqueueDelivery({ activityJson: activity, targetInbox, senderOxyUserId })
+            .catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn(`[FedDeliver] enqueue failed for ${targetInbox}, falling back to the durable queue: ${message}`);
+            return false;
+        });
+        if (enqueued)
+            return;
+        await config.transport.fallbackQueue.create({
+            activityJson: activity,
+            targetInbox,
+            senderOxyUserId,
+            nextAttemptAt: new Date(),
+        });
+    }
+    async function resolveActorInbox(actorUri) {
+        if (!actorUri)
+            return undefined;
+        const actor = await config.store.findActorByUri(actorUri);
+        if (!actor)
+            return undefined;
+        return actor.sharedInboxUrl ?? actor.inboxUrl ?? undefined;
+    }
+    async function deliverToFollowers(activity, senderOxyUserId, senderUsername, options = {}) {
+        const actorUris = await config.follows.listAcceptedInboundFollowerActorUris(senderOxyUserId);
+        const actors = actorUris.length > 0 ? await config.store.findActorInboxesByUris(actorUris) : [];
+        // Group by shared inbox to avoid duplicate deliveries. Follower inboxes
+        // first, then the explicit targets — the shared `seen` set dedupes an
+        // explicit inbox that an instance already receives as a follower.
+        const seen = new Set();
+        const inboxes = [];
+        for (const actor of actors) {
+            const inbox = actor.sharedInboxUrl || actor.inboxUrl;
+            if (inbox && !seen.has(inbox)) {
+                seen.add(inbox);
+                inboxes.push(inbox);
+            }
+        }
+        for (const inbox of options.extraInboxes ?? []) {
+            if (inbox && !seen.has(inbox)) {
+                seen.add(inbox);
+                inboxes.push(inbox);
+            }
+        }
+        if (inboxes.length === 0)
+            return;
+        // Durable path: enqueue one BullMQ delivery per shared inbox (deduped per
+        // inbox + activity id). When the queue is unavailable fall back to a single
+        // batch insert into the durable queue for the inboxes that were not enqueued.
+        const now = new Date();
+        const durableFallback = [];
+        for (const inbox of inboxes) {
+            if (isBlockedUrl(inbox)) {
+                logger.warn(`[FedDeliver] not queueing delivery to blocked inbox ${inbox}`);
+                continue;
+            }
+            const guard = await config.assertSafeInboxUrl(inbox);
+            if (!guard.ok) {
+                logger.warn(`[FedDeliver] not queueing unsafe inbox URL ${inbox}: ${guard.reason}`);
+                continue;
+            }
+            const enqueued = await config.transport
+                .enqueueDelivery({ activityJson: activity, targetInbox: inbox, senderOxyUserId })
+                .catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.warn(`[FedDeliver] follower enqueue failed for ${inbox}, falling back to the durable queue: ${message}`);
+                return false;
+            });
+            if (!enqueued) {
+                durableFallback.push({ activityJson: activity, targetInbox: inbox, senderOxyUserId, nextAttemptAt: now });
+            }
+        }
+        if (durableFallback.length > 0) {
+            await config.transport.fallbackQueue.insertMany(durableFallback);
+        }
+    }
+    /**
+     * Resolve the target actor's inbox in the background and queue the Follow
+     * activity for delivery once known. Fire-and-forget: returns synchronously and
+     * never blocks the caller on remote I/O.
+     */
+    function queueFollowOnceActorKnown(activity, canonicalUri, localOxyUserId, remoteActorUri) {
+        void (async () => {
+            try {
+                let actor = await config.store.findActorByUri(canonicalUri);
+                if (!actor?.inboxUrl) {
+                    actor = await config.actorRefresh.fetchRemoteActor(remoteActorUri);
+                }
+                const inbox = actor?.sharedInboxUrl ?? actor?.inboxUrl;
+                if (inbox && !isBlockedUrl(inbox) && !isBlockedUrl(remoteActorUri)) {
+                    await queueDelivery(activity, inbox, localOxyUserId);
+                }
+                else {
+                    logger.warn(`[FedSync] could not resolve inbox to deliver Follow to ${remoteActorUri}`);
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.warn(`[FedSync] deferred follow delivery setup failed for ${remoteActorUri}: ${message}`);
+            }
+        })();
+    }
+    async function sendFollow(localOxyUserId, localUsername, remoteActorUri) {
+        if (!config.federationEnabled)
+            return { success: false, pending: false };
+        if (isBlockedUrl(remoteActorUri)) {
+            logger.warn(`[FedDeliver] refusing outbound Follow to blocked origin ${remoteActorUri}`);
+            return { success: false, pending: false };
+        }
+        // Never block the follow request on a remote actor fetch. Use whatever is
+        // cached; if the actor is unknown locally we still record the follow and
+        // queue the Follow activity, then refresh the actor in the background.
+        const cached = await config.store.findActorByUri(remoteActorUri);
+        // Always refresh the actor in the background so its inbox/profile stay
+        // current (and so a missing actor gets resolved for delivery shortly).
+        config.actorRefresh.refreshActorInBackground(remoteActorUri, cached ?? undefined);
+        const canonicalUri = cached?.uri ?? remoteActorUri;
+        const localActorUri = urls.actor(localUsername);
+        // Use the actor _id when known, otherwise a stable hash of the URI so the
+        // activity ID is deterministic across retries before the actor is cached.
+        const activityIdSuffix = cached?._id
+            ? String(cached._id)
+            : encodeURIComponent(canonicalUri);
+        const activityId = `${localActorUri}/follows/${activityIdSuffix}`;
+        // Create or update the follow record
+        await config.follows.upsertOutboundPending(localOxyUserId, canonicalUri, activityId);
+        const activity = {
+            '@context': 'https://www.w3.org/ns/activitystreams',
+            id: activityId,
+            type: 'Follow',
+            actor: localActorUri,
+            object: canonicalUri,
+        };
+        // If we know the inbox, attempt delivery in the background; otherwise queue
+        // for the delivery worker, which resolves the inbox once the actor lands.
+        const targetInbox = cached?.sharedInboxUrl ?? cached?.inboxUrl;
+        if (targetInbox && !isBlockedUrl(targetInbox)) {
+            void deliverActivity(activity, targetInbox, localOxyUserId, localUsername)
+                .then((delivered) => {
+                if (!delivered)
+                    return queueDelivery(activity, targetInbox, localOxyUserId);
+            })
+                .catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.warn(`[FedSync] background follow delivery failed for ${canonicalUri}: ${message}`);
+            });
+        }
+        else {
+            // No cached inbox yet — resolve the actor's inbox in the background and
+            // queue the Follow for delivery once known. Reports success optimistically;
+            // the delivery worker retries the queued delivery. Never blocks the caller.
+            queueFollowOnceActorKnown(activity, canonicalUri, localOxyUserId, remoteActorUri);
+        }
+        return { success: true, pending: cached?.manuallyApprovesFollowers ?? false };
+    }
+    async function sendUndoFollow(localOxyUserId, localUsername, remoteActorUri) {
+        if (!config.federationEnabled)
+            return false;
+        const follow = await config.follows.findOutbound(localOxyUserId, remoteActorUri);
+        if (!follow)
+            return false;
+        const actor = await config.store.findActorByUri(remoteActorUri);
+        if (!actor)
+            return false;
+        const localActorUri = urls.actor(localUsername);
+        const activity = {
+            '@context': AP_CONTEXT,
+            id: `${localActorUri}/follows/${actor._id}/undo`,
+            type: 'Undo',
+            actor: localActorUri,
+            object: {
+                id: follow.activityId,
+                type: 'Follow',
+                actor: localActorUri,
+                object: remoteActorUri,
+            },
+        };
+        // Remove the local follow immediately so the unfollow reflects in the UI,
+        // then deliver the Undo in the background — never block the request on the
+        // remote POST.
+        await config.follows.deleteById(follow._id);
+        // `inboxUrl` is schema-optional (atproto actors have none); an AP actor we
+        // are sending Undo(Follow) to always has one. When neither inbox is known the
+        // local follow is already removed — just skip the outbound delivery.
+        const targetInbox = actor.sharedInboxUrl ?? actor.inboxUrl;
+        if (targetInbox && !isBlockedUrl(targetInbox) && !isBlockedUrl(remoteActorUri)) {
+            void deliverActivity(activity, targetInbox, localOxyUserId, localUsername)
+                .then((delivered) => {
+                if (!delivered)
+                    return queueDelivery(activity, targetInbox, localOxyUserId);
+            })
+                .catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.warn(`[FedSync] background undo-follow delivery failed for ${remoteActorUri}: ${message}`);
+            });
+        }
+        else if (targetInbox) {
+            logger.warn(`[FedDeliver] skipping Undo(Follow) delivery to blocked origin ${remoteActorUri}`);
+        }
+        return true;
+    }
+    async function sendAccept(localOxyUserId, localUsername, followActivityId, remoteActorUri) {
+        const actor = await config.store.findActorByUri(remoteActorUri);
+        if (!actor)
+            return;
+        // `inboxUrl` is schema-optional (atproto actors have none); an AP actor we
+        // are sending Accept(Follow) to always has one. When neither inbox is known the
+        // local follow is already removed — just skip the outbound delivery.
+        const targetInbox = actor.sharedInboxUrl ?? actor.inboxUrl;
+        if (!targetInbox) {
+            logger.warn(`[FedSync] cannot send Accept(Follow) to ${remoteActorUri}: actor has no inbox`);
+            return;
+        }
+        if (isBlockedUrl(targetInbox) || isBlockedUrl(remoteActorUri)) {
+            logger.warn(`[FedDeliver] refusing Accept(Follow) delivery to blocked origin ${remoteActorUri}`);
+            return;
+        }
+        const localActorUri = urls.actor(localUsername);
+        const activity = {
+            '@context': AP_CONTEXT,
+            id: `${localActorUri}/accepts/${Date.now()}`,
+            type: 'Accept',
+            actor: localActorUri,
+            object: {
+                id: followActivityId,
+                type: 'Follow',
+                actor: remoteActorUri,
+                object: localActorUri,
+            },
+        };
+        const delivered = await deliverActivity(activity, targetInbox, localOxyUserId, localUsername);
+        if (!delivered) {
+            await queueDelivery(activity, targetInbox, localOxyUserId);
+        }
+    }
+    async function federateActorUpdate(actorOxyUserId, username) {
+        if (!config.federationEnabled)
+            return;
+        if (!(await config.consent.isSharingEnabled(actorOxyUserId)))
+            return;
+        try {
+            const user = await config.identity.resolveUserByUsername(username);
+            if (!user) {
+                logger.warn(`[FedDeliver] cannot federate actor update for ${username}: user not resolvable`);
+                return;
+            }
+            const publicKey = await config.keys.getPublicKey(username);
+            const profileHeaderImage = await config.profile.getBanner(actorOxyUserId);
+            // Canonical display name is owned by the Oxy API; fall back to the handle
+            // when absent (never recompose from name parts).
+            const displayName = user.name?.displayName || username;
+            const actorObject = config.buildLocalActorObject({
+                username,
+                displayName,
+                kind: user.kind,
+                bio: user.bio,
+                avatar: user.avatar,
+                profileHeaderImage,
+                publicKey,
+                createdAt: user.createdAt,
+            });
+            const actor = urls.actor(username);
+            const now = new Date();
+            const activity = {
+                '@context': AP_CONTEXT,
+                id: `${actor}#updates/${now.getTime()}`,
+                type: 'Update',
+                actor,
+                updated: now.toISOString(),
+                to: [AP_PUBLIC],
+                cc: [`${actor}/followers`],
+                object: actorObject,
+            };
+            await deliverToFollowers(activity, actorOxyUserId, username);
+        }
+        catch (err) {
+            logger.error('Failed to federate actor update:', err);
+        }
+    }
+    return {
+        deliverActivity,
+        queueDelivery,
+        resolveActorInbox,
+        deliverToFollowers,
+        sendFollow,
+        sendUndoFollow,
+        sendAccept,
+        federateActorUpdate,
+    };
+}

package/dist/esm/node/identityBridge.js

@@ -0,0 +1,130 @@
+/**
+ * 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 { getErrorMessage, getErrorStatus } from '@oxy.so/core';
+const ACTOR_GONE_PATH = '/federation/actor-gone';
+const ACTOR_DELETE_PATH = '/federation/actor-delete';
+/** True for a PERMANENT (non-retryable) 4xx: 400/403/404/409, but NOT 408/429. */
+function isPermanentClientError(httpStatus) {
+    return (httpStatus !== undefined &&
+        httpStatus >= 400 &&
+        httpStatus < 500 &&
+        httpStatus !== 408 &&
+        httpStatus !== 429);
+}
+/** Build the network-neutral identity bridge from an app's adapters. */
+export function createIdentityBridge(config) {
+    return {
+        async resolveExternalUser(actor, opts = {}) {
+            const forceAvatarRefresh = opts.forceAvatarRefresh ?? false;
+            try {
+                // The connector owns deriving the canonical `local@domain` username and the
+                // instance domain for its protocol, so this bridge stays protocol-agnostic:
+                // it never has to guess a domain out of a bare atproto handle or a hostless
+                // DID. oxy-api binds the two (username domain must equal `domain`).
+                const oxyUser = await config.makeServiceRequest('PUT', '/users/resolve', {
+                    type: 'federated',
+                    username: actor.federatedUsername,
+                    actorUri: actor.externalId,
+                    domain: actor.instanceDomain,
+                    displayName: actor.displayName,
+                    avatar: actor.avatarUrl,
+                    bio: actor.bio,
+                    // On refresh, tell Oxy to re-download and replace the avatar even if it
+                    // already stored a file ID. Coordinated with oxy-api's
+                    // `refresh` / `forceAvatarRefresh` flag on PUT /users/resolve.
+                    refresh: forceAvatarRefresh,
+                    forceAvatarRefresh,
+                });
+                const oxyId = String(oxyUser?._id || oxyUser?.id || '');
+                if (!oxyId)
+                    return null;
+                // A re-resolve can refresh the federated actor's display name / avatar in
+                // Oxy. Let the app evict any warm cache so the next read is fresh.
+                if (config.onUserResolved) {
+                    await config.onUserResolved(oxyId);
+                }
+                if (actor.bannerUrl && config.mirrorBanner) {
+                    // Best-effort on the live path: the mirror handles its own failures.
+                    await config.mirrorBanner(actor.bannerUrl, oxyId, actor.externalId);
+                }
+                return oxyId;
+            }
+            catch (resolveErr) {
+                config.logger.warn(`Failed to resolve Oxy user for ${actor.externalId}:`, resolveErr);
+                return null;
+            }
+        },
+        async reportActorGone(oxyUserId) {
+            const id = oxyUserId.trim();
+            if (!id)
+                return 'skipped';
+            try {
+                const data = await config.makeServiceRequest('POST', ACTOR_GONE_PATH, {
+                    oxyUserId: id,
+                });
+                const alreadyArchived = data?.alreadyArchived === true;
+                config.logger.info(`[Federation] oxy-api archived gone actor ${id}`, { alreadyArchived });
+                return alreadyArchived ? 'already' : 'archived';
+            }
+            catch (error) {
+                const httpStatus = getErrorStatus(error);
+                const reason = getErrorMessage(error);
+                if (isPermanentClientError(httpStatus)) {
+                    config.logger.warn(`[Federation] actor-gone report for ${id} rejected (HTTP ${httpStatus}, permanent)`, {
+                        reason,
+                    });
+                    return 'skipped';
+                }
+                config.logger.warn(`[Federation] actor-gone report for ${id} failed transiently; leaving for retry`, {
+                    status: httpStatus,
+                    reason,
+                });
+                return 'failed';
+            }
+        },
+        async deleteActorIdentity(oxyUserId) {
+            const id = oxyUserId.trim();
+            if (!id)
+                return 'skipped';
+            try {
+                const data = await config.makeServiceRequest('POST', ACTOR_DELETE_PATH, {
+                    oxyUserId: id,
+                });
+                const deleted = data?.deleted === true;
+                config.logger.info(`[Federation] oxy-api ${deleted ? 'hard-deleted' : 'found no'} identity for gone actor ${id}`, { followEdgesRemoved: data?.followEdgesRemoved ?? 0 });
+                return deleted ? 'deleted' : 'absent';
+            }
+            catch (error) {
+                const httpStatus = getErrorStatus(error);
+                const reason = getErrorMessage(error);
+                if (isPermanentClientError(httpStatus)) {
+                    config.logger.warn(`[Federation] actor-delete for ${id} rejected (HTTP ${httpStatus}, permanent)`, {
+                        reason,
+                    });
+                    return 'skipped';
+                }
+                config.logger.warn(`[Federation] actor-delete for ${id} failed transiently; leaving for retry`, {
+                    status: httpStatus,
+                    reason,
+                });
+                return 'failed';
+            }
+        },
+    };
+}