@oxy.so/federation 2.2.1 → 2.4.0

package/src/node/delivery.ts

@@ -38,6 +38,22 @@ 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';
 
+/** Trusted sender metadata supplied by the application or its durable job. */
+export interface DeliveryAuthorizationContext {
+  activity: Readonly<Record<string, unknown>>;
+  senderAccountId: string;
+}
+
+/** A definitive refusal: workers must discard, not retry or count a delivery. */
+export class DeliveryAuthorizationDeniedError extends Error {
+  readonly code = 'DELIVERY_AUTHORIZATION_DENIED';
+
+  constructor() {
+    super('Outbound federation delivery is not authorized');
+    this.name = 'DeliveryAuthorizationDeniedError';
+  }
+}
+
 /** Minimal logging sink the delivery service writes to. */
 export interface DeliveryLogger {
   debug(message: string, detail?: unknown): void;
@@ -81,7 +97,10 @@ export interface DeliverSingleHopInit {
  * 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>;
+export type DeliverSingleHop = (
+  url: string,
+  init: DeliverSingleHopInit,
+) => Promise<DeliverSingleHopResult>;
 
 /** A durable-delivery job body (BullMQ + the fallback queue share this shape). */
 export interface DeliveryQueueJob {
@@ -94,9 +113,8 @@ export interface DeliveryQueueJob {
  * 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.
+ * a database. Mention backs it with Postgres; the method names below are kept
+ * stable so the adapter shape stays stable for consumers.
  */
 export interface DeliveryFallbackQueue {
   /** Insert one fallback delivery row (`queueDelivery`). */
@@ -134,7 +152,9 @@ 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'>>>;
+  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. */
@@ -142,9 +162,16 @@ 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>;
+  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>;
+  findOutbound(
+    localOxyUserId: string,
+    remoteActorUri: string,
+  ): Promise<{ _id: unknown; activityId?: string } | null>;
   /** Delete a follow row by id (`sendUndoFollow`). */
   deleteById(id: unknown): Promise<void>;
 }
@@ -217,6 +244,13 @@ export interface DeliveryServiceConfig<TActor extends DeliveryActorFields> {
   deliverSingleHop: DeliverSingleHop;
   /** SSRF pre-check for a durable inbox enqueue (never queue a delivery to an unsafe URL). */
   assertSafeInboxUrl(url: string): Promise<SafeUrlVerdict>;
+  /**
+   * Optional live policy check. False throws DeliveryAuthorizationDeniedError before
+   * signing or enqueueing. A thrown authority error propagates unchanged so a
+   * durable worker can retry it. Checked once per fanout, then again at delivery.
+   * Never derive the sender from the activity actor URL or its signing key.
+   */
+  authorizeDelivery?(context: DeliveryAuthorizationContext): Promise<boolean>;
   /** BullMQ enqueue + the durable fallback queue. */
   transport: DeliveryTransport;
   /** The AP actor cache store. */
@@ -295,7 +329,10 @@ export interface DeliveryService {
     localUsername: string,
     remoteActorUri: string,
   ): Promise<{ success: boolean; pending: boolean }>;
-  /** Send an Undo(Follow) to a remote actor (removes the local follow first). */
+  /**
+   * Remove the local follow and attempt Undo delivery. True means the local
+   * relationship was removed, never that remote delivery succeeded.
+   */
   sendUndoFollow(
     localOxyUserId: string,
     localUsername: string,
@@ -333,11 +370,32 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
     return host === null || config.isBlockedDomain(host);
   }
 
+  async function authorizeDelivery(
+    activity: Record<string, unknown>,
+    senderAccountId: string,
+  ): Promise<void> {
+    if (
+      config.authorizeDelivery &&
+      !(await config.authorizeDelivery({ activity, senderAccountId }))
+    ) {
+      throw new DeliveryAuthorizationDeniedError();
+    }
+  }
+
   async function deliverActivity(
     activity: Record<string, unknown>,
     targetInbox: string,
     senderOxyUserId: string,
     senderUsername: string,
+  ): Promise<boolean> {
+    await authorizeDelivery(activity, senderOxyUserId);
+    return deliverAuthorizedActivity(activity, targetInbox, senderUsername);
+  }
+
+  async function deliverAuthorizedActivity(
+    activity: Record<string, unknown>,
+    targetInbox: string,
+    senderUsername: string,
   ): Promise<boolean> {
     if (isBlockedUrl(targetInbox)) {
       logger.warn(`[FedDeliver] refusing outbound delivery to blocked inbox ${targetInbox}`);
@@ -356,7 +414,9 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
         ...sigHeaders,
       };
 
-      logger.debug(`[FedDeliver] POST ${targetInbox} body=${body} sig-headers=${sigHeaders.Signature?.match(/headers="([^"]+)"/)?.[1]}`);
+      logger.debug(
+        `[FedDeliver] POST ${targetInbox} body=${body} sig-headers=${sigHeaders.Signature?.match(/headers="([^"]+)"/)?.[1]}`,
+      );
 
       const { response, status } = await config.deliverSingleHop(targetInbox, {
         method: 'POST',
@@ -372,7 +432,9 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
       }
 
       const responseBody = await readResponsePreview(response);
-      logger.debug(`Activity delivery failed to ${targetInbox}: ${status} body=${responseBody.slice(0, 500)}`);
+      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);
@@ -385,6 +447,7 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
     targetInbox: string,
     senderOxyUserId: string,
   ): Promise<void> {
+    await authorizeDelivery(activity, senderOxyUserId);
     if (isBlockedUrl(targetInbox)) {
       logger.warn(`[FedDeliver] not queueing delivery to blocked inbox ${targetInbox}`);
       return;
@@ -402,7 +465,9 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
       .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}`);
+        logger.warn(
+          `[FedDeliver] enqueue failed for ${targetInbox}, falling back to the durable queue: ${message}`,
+        );
         return false;
       });
 
@@ -429,6 +494,7 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
     senderUsername: string,
     options: { extraInboxes?: string[] } = {},
   ): Promise<void> {
+    await authorizeDelivery(activity, senderOxyUserId);
     const actorUris = await config.follows.listAcceptedInboundFollowerActorUris(senderOxyUserId);
     const actors = actorUris.length > 0 ? await config.store.findActorInboxesByUris(actorUris) : [];
 
@@ -473,12 +539,19 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
         .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}`);
+          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 });
+        durableFallback.push({
+          activityJson: activity,
+          targetInbox: inbox,
+          senderOxyUserId,
+          nextAttemptAt: now,
+        });
       }
     }
 
@@ -512,7 +585,9 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        logger.warn(`[FedSync] deferred follow delivery setup failed for ${remoteActorUri}: ${message}`);
+        logger.warn(
+          `[FedSync] deferred follow delivery setup failed for ${remoteActorUri}: ${message}`,
+        );
       }
     })();
   }
@@ -533,22 +608,13 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
     // 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 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: Record<string, unknown> = {
       '@context': 'https://www.w3.org/ns/activitystreams',
       id: activityId,
@@ -557,17 +623,25 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
       object: canonicalUri,
     };
 
+    // Refuse before committing an outbound follow or reporting success.
+    await authorizeDelivery(activity, localOxyUserId);
+    // A refused follow must not start remote actor discovery either.
+    config.actorRefresh.refreshActorInBackground(remoteActorUri, cached ?? undefined);
+    await config.follows.upsertOutboundPending(localOxyUserId, canonicalUri, activityId);
+
     // 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)
+      void deliverAuthorizedActivity(activity, targetInbox, 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}`);
+          logger.warn(
+            `[FedSync] background follow delivery failed for ${canonicalUri}: ${message}`,
+          );
         });
     } else {
       // No cached inbox yet — resolve the actor's inbox in the background and
@@ -623,10 +697,14 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
         })
         .catch((err) => {
           const message = err instanceof Error ? err.message : String(err);
-          logger.warn(`[FedSync] background undo-follow delivery failed for ${remoteActorUri}: ${message}`);
+          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}`);
+      logger.warn(
+        `[FedDeliver] skipping Undo(Follow) delivery to blocked origin ${remoteActorUri}`,
+      );
     }
 
     return true;
@@ -649,7 +727,9 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
       return;
     }
     if (isBlockedUrl(targetInbox) || isBlockedUrl(remoteActorUri)) {
-      logger.warn(`[FedDeliver] refusing Accept(Follow) delivery to blocked origin ${remoteActorUri}`);
+      logger.warn(
+        `[FedDeliver] refusing Accept(Follow) delivery to blocked origin ${remoteActorUri}`,
+      );
       return;
     }
 
@@ -681,7 +761,9 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
     try {
       const user = await config.identity.resolveUserByUsername(username);
       if (!user) {
-        logger.warn(`[FedDeliver] cannot federate actor update for ${username}: user not resolvable`);
+        logger.warn(
+          `[FedDeliver] cannot federate actor update for ${username}: user not resolvable`,
+        );
         return;
       }
 

package/src/node/httpCacheControl.ts

@@ -0,0 +1,8 @@
+/** Shared discovery config validation; zero forbids downstream response retention. */
+export function discoveryCacheControl(value: number | undefined, defaultSeconds: number): string {
+  const seconds = value ?? defaultSeconds;
+  if (!Number.isInteger(seconds) || seconds < 0 || seconds > 86400) {
+    throw new RangeError('httpCacheTtlSeconds must be an integer from 0 to 86400');
+  }
+  return seconds === 0 ? 'no-store' : `max-age=${seconds}`;
+}

package/src/node/identityBridge.ts

@@ -24,7 +24,11 @@ import type { NormalizedExternalActor } from '../index';
 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>;
+export type ServiceRequest = <T>(
+  method: ServiceRequestMethod,
+  path: string,
+  body?: unknown,
+) => Promise<T>;
 
 /** Minimal logging sink the identity bridge writes to. */
 export interface IdentityBridgeLogger {
@@ -183,15 +187,21 @@ export function createIdentityBridge(config: IdentityBridgeConfig): IdentityBrid
         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,
-          });
+          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,
-        });
+        config.logger.warn(
+          `[Federation] actor-gone report for ${id} failed transiently; leaving for retry`,
+          {
+            status: httpStatus,
+            reason,
+          },
+        );
         return 'failed';
       }
     },
@@ -201,9 +211,13 @@ export function createIdentityBridge(config: IdentityBridgeConfig): IdentityBrid
       if (!id) return 'skipped';
 
       try {
-        const data = await config.makeServiceRequest<ActorDeleteResponse>('POST', ACTOR_DELETE_PATH, {
-          oxyUserId: id,
-        });
+        const data = await config.makeServiceRequest<ActorDeleteResponse>(
+          '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}`,
@@ -214,15 +228,21 @@ export function createIdentityBridge(config: IdentityBridgeConfig): IdentityBrid
         const httpStatus = getErrorStatus(error);
         const reason = getErrorMessage(error);
         if (isPermanentClientError(httpStatus)) {
-          config.logger.warn(`[Federation] actor-delete for ${id} rejected (HTTP ${httpStatus}, permanent)`, {
-            reason,
-          });
+          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,
-        });
+        config.logger.warn(
+          `[Federation] actor-delete for ${id} failed transiently; leaving for retry`,
+          {
+            status: httpStatus,
+            reason,
+          },
+        );
         return 'failed';
       }
     },

package/src/node/inboundDispatch.ts

@@ -64,9 +64,7 @@ export interface InboundDispatcherLogger {
  * 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 };
+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 {
@@ -99,9 +97,16 @@ export interface InboundActorResolver {
 /** 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>;
+  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>;
+  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`). */
@@ -154,7 +159,11 @@ export interface InboundDispatcherConfig {
    * 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>;
+  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.
@@ -248,7 +257,10 @@ function objectTargetUri(object: unknown): string | undefined {
 export function createInboundDispatcher(config: InboundDispatcherConfig): InboundDispatcher {
   const { logger } = config;
 
-  async function handleIncomingFollow(activity: Record<string, unknown>, actorUri: string): Promise<void> {
+  async function handleIncomingFollow(
+    activity: Record<string, unknown>,
+    actorUri: string,
+  ): Promise<void> {
     const targetActorUri = objectTargetUri(activity.object);
     if (!targetActorUri) return;
 
@@ -314,7 +326,10 @@ export function createInboundDispatcher(config: InboundDispatcherConfig): Inboun
     logger.info(`Accepted follow from ${actorUri} to ${username}`);
   }
 
-  async function handleUndoFollow(object: Record<string, unknown>, actorUri: string): Promise<void> {
+  async function handleUndoFollow(
+    object: Record<string, unknown>,
+    actorUri: string,
+  ): Promise<void> {
     const targetActorUri = objectTargetUri(object.object);
     const match = targetActorUri?.match(/\/ap\/users\/([^/]+)$/);
     let localUserId: string | undefined;
@@ -374,9 +389,10 @@ export function createInboundDispatcher(config: InboundDispatcherConfig): Inboun
       }
     } else if ((object as { type?: unknown }).type === 'Follow') {
       const followActivityId = (object as { id?: unknown }).id;
-      updated = typeof followActivityId === 'string' && followActivityId.length > 0
-        ? await config.follows.markOutboundAcceptedByActivityId(actorUri, followActivityId)
-        : await config.follows.markOutboundAcceptedAnyPending(actorUri);
+      updated =
+        typeof followActivityId === 'string' && followActivityId.length > 0
+          ? await config.follows.markOutboundAcceptedByActivityId(actorUri, followActivityId)
+          : await config.follows.markOutboundAcceptedAnyPending(actorUri);
     }
 
     if (updated) {
@@ -394,7 +410,8 @@ export function createInboundDispatcher(config: InboundDispatcherConfig): Inboun
 
     const objectType = typeof object === 'string' ? null : (object as { type?: unknown }).type;
     if (objectType === 'Follow') {
-      const followActivityId = typeof object === 'object' ? (object as { id?: unknown }).id : undefined;
+      const followActivityId =
+        typeof object === 'object' ? (object as { id?: unknown }).id : undefined;
       await config.follows.markOutboundRejected(
         actorUri,
         typeof followActivityId === 'string' ? followActivityId : undefined,
@@ -403,7 +420,10 @@ export function createInboundDispatcher(config: InboundDispatcherConfig): Inboun
     }
   }
 
-  async function processInboxActivity(activity: Record<string, unknown>, verifiedActorUri: string): Promise<void> {
+  async function processInboxActivity(
+    activity: Record<string, unknown>,
+    verifiedActorUri: string,
+  ): Promise<void> {
     // Instance domain policy, FIRST — before the payload is even parsed.
     //
     // This is the single chokepoint for inbound federation: every transport (the

package/src/node/index.ts

@@ -26,6 +26,17 @@ export {
   type SignedFetchLogger,
 } from './signedFetch';
 
+/**
+ * X's `t.co` wrapper unwrapped into the link the author posted, over the same
+ * injected single-hop transport — for bridged X bios and posts.
+ */
+export {
+  createTcoLinkExpander,
+  type TcoLinkExpander,
+  type TcoLinkCache,
+  type CreateTcoLinkExpanderConfig,
+} from './tcoLinks';
+
 /**
  * The actor↔Oxy-user identity bridge — the default implementation of the
  * `PUT /users/resolve` + actor-gone archive/delete seam over an injected
@@ -70,6 +81,8 @@ export {
  */
 export {
   createDeliveryService,
+  DeliveryAuthorizationDeniedError,
+  type DeliveryAuthorizationContext,
   type DeliveryService,
   type DeliveryServiceConfig,
   type DeliveryLogger,

package/src/node/signedFetch.ts

@@ -156,7 +156,9 @@ export function createSignedFetch(config: CreateSignedFetchConfig): SignedFetch
     // resources. Retry from the post-redirect URL so we don't restart a chain that
     // already landed on the failing hop.
     if (res.status >= 500) {
-      config.logger?.info(`[FedSync] signedFetch got ${res.status} for ${finalUrl}, retrying unsigned`);
+      config.logger?.info(
+        `[FedSync] signedFetch got ${res.status} for ${finalUrl}, retrying unsigned`,
+      );
       return fetchFollowingRedirects(finalUrl, false).then(({ res: unsignedRes }) => unsignedRes);
     }
 

package/src/node/tcoLinks.ts

@@ -0,0 +1,114 @@
+/**
+ * Expanding X's `t.co` link wrapper back into the link the author posted.
+ *
+ * X rewrites EVERY link in a post or bio into `https://t.co/<id>`, and a bridge
+ * that mirrors an X account (bird.makeup, mastox) republishes that text as it
+ * is: the actor `summary` and the Note `content` carry only the wrapper. The
+ * author never wrote `t.co`; it is X's click tracker standing in for their link,
+ * and an X API client never shows it because it reads the expansion beside it.
+ * The bridges drop that expansion, so the only place left to recover it is the
+ * wrapper's own redirect.
+ *
+ * Only `t.co` is unwrapped, and only ONE hop. A `bit.ly` the author chose is
+ * their link and stays; so does wherever their link redirects next. What is
+ * replaced is exactly X's wrapper, by exactly the URL it names.
+ *
+ * The transport is injected — the same SSRF-safe, IP-pinned single-hop fetch
+ * {@link createSignedFetch} takes — so each backend keeps its own network
+ * contract. A link that does not resolve (timeout, 404, a malformed or
+ * self-referencing `Location`) is left as `t.co`: still a working link, never a
+ * broken one.
+ */
+
+import type { SingleHopFetch } from './signedFetch';
+
+/**
+ * A `t.co` link in plain text. X ids are alphanumeric; the lookahead stops a
+ * longer token (`t.co/abc/def`, `t.co/abcé`) from being half-replaced.
+ */
+const TCO_LINK = /\bhttps?:\/\/t\.co\/([A-Za-z0-9]+)(?![\w/])/gi;
+const REDIRECT_STATUS_CODES: ReadonlySet<number> = new Set([301, 302, 303, 307, 308]);
+/** A link that has not answered by then is kept as `t.co`. */
+const TCO_TIMEOUT_MS = 5_000;
+/** Bounds the requests one text can cost; the rest keep their wrapper. */
+const MAX_LINKS_PER_TEXT = 10;
+
+/**
+ * A store of resolved wrappers, keyed by the `t.co` id. A wrapper never changes
+ * what it points to, so an entry never goes stale. Failures are not cached.
+ */
+export interface TcoLinkCache {
+  get(id: string): Promise<string | null | undefined>;
+  set(id: string, target: string): Promise<void>;
+}
+
+/** Adapters a {@link TcoLinkExpander} is built from. */
+export interface CreateTcoLinkExpanderConfig {
+  /** SSRF-safe single-hop transport (does NOT follow redirects). */
+  fetchSingleHop: SingleHopFetch;
+  /** User-Agent presented to t.co. A browser UA gets an HTML page instead of the 301. */
+  userAgent: string;
+  cache?: TcoLinkCache;
+}
+
+/** Replace every `t.co` link in `text` with the URL it redirects to. */
+export type TcoLinkExpander = (text: string) => Promise<string>;
+
+/** The `t.co` ids in `text`, in order of first appearance. */
+function findTcoLinkIds(text: string): string[] {
+  return [...new Set(Array.from(text.matchAll(TCO_LINK), (match) => match[1]))];
+}
+
+/** The redirect target, if it is an http(s) URL that is not another `t.co` wrapper. */
+function readTarget(response: Response, from: string): string | null {
+  if (!REDIRECT_STATUS_CODES.has(response.status)) return null;
+  const location = response.headers.get('location');
+  if (!location) return null;
+  let target: URL;
+  try {
+    target = new URL(location, from);
+  } catch {
+    return null;
+  }
+  if (target.protocol !== 'https:' && target.protocol !== 'http:') return null;
+  if (target.hostname.toLowerCase() === 't.co') return null;
+  return target.href;
+}
+
+export function createTcoLinkExpander(config: CreateTcoLinkExpanderConfig): TcoLinkExpander {
+  const { cache } = config;
+
+  async function resolve(id: string): Promise<string | null> {
+    const cached = await cache?.get(id).catch(() => null);
+    if (cached) return cached;
+    const from = `https://t.co/${id}`;
+    let target: string | null;
+    try {
+      const response = await config.fetchSingleHop(from, {
+        headers: { Accept: '*/*', 'User-Agent': config.userAgent },
+        signal: AbortSignal.timeout(TCO_TIMEOUT_MS),
+        headersTimeoutMs: TCO_TIMEOUT_MS,
+      });
+      target = readTarget(response, from);
+      await response.body?.cancel().catch(() => undefined);
+    } catch {
+      return null;
+    }
+    if (target) await cache?.set(id, target).catch(() => undefined);
+    return target;
+  }
+
+  return async function expandTcoLinks(text: string): Promise<string> {
+    const ids = findTcoLinkIds(text).slice(0, MAX_LINKS_PER_TEXT);
+    if (ids.length === 0) return text;
+    const targets = new Map<string, string>();
+    await Promise.all(
+      ids.map(async (id) => {
+        const target = await resolve(id);
+        if (target) targets.set(id, target);
+      }),
+    );
+    if (targets.size === 0) return text;
+    return text.replace(TCO_LINK, (whole, id: string) => targets.get(id) ?? whole);
+  };
+}