@oxy.so/federation 1.0.1 → 2.1.0

package/src/node/actorResolver.ts

@@ -45,6 +45,12 @@ const AP_CONTENT_TYPE = 'application/activity+json';
 /** Maximum decompressed response sizes accepted from untrusted federation hosts. */
 const ACTOR_BODY_MAX_BYTES = 1024 * 1024;
 const COLLECTION_BODY_MAX_BYTES = 64 * 1024;
+/**
+ * Collection responses that DEFINITIVELY withhold the count: the owner hid the
+ * collection (401/403) or it no longer exists (404/410). Anything else non-2xx
+ * is a failed attempt, not an answer.
+ */
+const COLLECTION_WITHHELD_STATUSES: ReadonlySet<number> = new Set([401, 403, 404, 410]);
 const ERROR_BODY_MAX_BYTES = 4 * 1024;
 
 async function readBoundedResponseBody(res: Response, maxBytes: number): Promise<string> {
@@ -157,12 +163,33 @@ export interface FederatedActorUpsert {
    */
   networkAcct?: string;
   remoteCreatedAt?: Date;
-  followersCount: number;
-  followingCount: number;
-  postsCount: number;
+  /**
+   * The remote's own totals for its `followers`, `following` and `outbox`
+   * collections, read from each collection's `totalItems`. Each is a
+   * {@link CollectionCount}, and the three states mean three different writes:
+   *
+   * - a number — the remote reported it; store it. `0` is a real zero.
+   * - `null` — the remote definitively does not disclose it (no collection
+   *   advertised, a hidden collection answering 401/403, a gone one answering
+   *   404/410, or a collection that carries no numeric `totalItems`). Store it
+   *   as UNKNOWN — never as `0`.
+   * - absent (`undefined`) — this refresh could not tell (a timeout, a network
+   *   error, a 429/5xx, an unreadable body). The store must LEAVE the stored
+   *   value in place, and a first insert must record it as unknown.
+   */
+  followersCount?: number | null;
+  followingCount?: number | null;
+  postsCount?: number | null;
   lastFetchedAt: Date;
 }
 
+/**
+ * A remote collection's size as one refresh observed it: the reported
+ * `totalItems`, `null` when the remote definitively withholds it, or `undefined`
+ * when this attempt could not find out. See {@link FederatedActorUpsert.followersCount}.
+ */
+export type CollectionCount = number | null | undefined;
+
 /** 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. */
@@ -591,9 +618,11 @@ export class ActorResolver<TActor extends FederatedActorRecordBase> {
         alsoKnownAs,
         networkAcct: networkIdentity?.federatedUsername,
         remoteCreatedAt: typeof actor.published === 'string' ? new Date(actor.published) : undefined,
-        followersCount,
-        followingCount,
-        postsCount,
+        // Omitted, not written as `undefined`, when this refresh could not tell:
+        // an absent key is what tells the store to keep the value it has.
+        ...(followersCount !== undefined && { followersCount }),
+        ...(followingCount !== undefined && { followingCount }),
+        ...(postsCount !== undefined && { postsCount }),
         lastFetchedAt: new Date(),
       };
 
@@ -627,9 +656,11 @@ export class ActorResolver<TActor extends FederatedActorRecordBase> {
             // string away made both of those unrepresentable, so the stale text
             // survived every later refresh with nothing in the logs.
             bio: identityBio,
-            followersCount,
-            followingCount,
-            postsCount,
+            // The identity bridge takes a number or nothing; an unknown count is
+            // sent as nothing rather than as a zero it would store.
+            followersCount: followersCount ?? undefined,
+            followingCount: followingCount ?? undefined,
+            postsCount: postsCount ?? undefined,
             oxyUserId: fedActor.oxyUserId ?? undefined,
           };
           const oxyId = await this.config.identity.resolveExternalUser(normalized, { forceAvatarRefresh });
@@ -717,16 +748,34 @@ export class ActorResolver<TActor extends FederatedActorRecordBase> {
     }
   }
 
-  /** Fetch the totalItems count from an ActivityPub collection URL. */
-  private async fetchCollectionCount(url?: string): Promise<number> {
-    if (!url) return 0;
+  /**
+   * Read an ActivityPub collection's `totalItems`.
+   *
+   * Every failure used to come back as `0`, so a follower count the remote HID,
+   * or one a timeout kept us from reading, was stored and shown as a real
+   * "0 followers" — indistinguishable from an account nobody follows. A failure
+   * now says which kind it is (see {@link CollectionCount}):
+   *
+   * - `null` when the answer is definitive: no collection advertised, 401/403
+   *   (the owner hid it), 404/410 (it is gone), or a readable collection with no
+   *   usable `totalItems` (the server does not publish the count).
+   * - `undefined` when this attempt simply failed — a thrown fetch (timeout,
+   *   network, SSRF refusal), any other non-2xx (429, 5xx), or a body that could
+   *   not be read as a JSON object. The next refresh may well succeed, so the
+   *   caller keeps whatever it last knew rather than forgetting it.
+   */
+  private async fetchCollectionCount(url?: string): Promise<CollectionCount> {
+    if (!url) return null;
     try {
       const res = await this.config.signedFetch(url, AP_CONTENT_TYPE);
-      if (!res.ok) return 0;
+      if (!res.ok) {
+        return COLLECTION_WITHHELD_STATUSES.has(res.status) ? null : undefined;
+      }
       const col = await readBoundedJson(res, COLLECTION_BODY_MAX_BYTES);
-      return typeof col.totalItems === 'number' ? col.totalItems : 0;
+      const total = col.totalItems;
+      return typeof total === 'number' && Number.isSafeInteger(total) && total >= 0 ? total : null;
     } catch {
-      return 0;
+      return undefined;
     }
   }
 

package/src/node/actorRouter.ts

@@ -41,6 +41,12 @@ export interface ActorRouteUser {
   createdAt?: string | null;
   /** Account-graph classification — decides the actor `type`. */
   kind?: AccountKind | null;
+  /**
+   * The actor URIs Oxy publishes as this account's aliases
+   * (`GET /profiles/username/:username` → `alsoKnownAs`). Emitted on the actor
+   * only when non-empty.
+   */
+  alsoKnownAs?: readonly string[] | null;
   _count?: { followers?: number; following?: number } | null;
 }
 
@@ -388,6 +394,7 @@ export function createActorRouter(config: ActorRouterConfig): Router {
         profileHeaderImage,
         publicKey,
         createdAt: user.createdAt,
+        alsoKnownAs: user.alsoKnownAs,
       });
 
       res.set('Content-Type', apContentType);

package/src/node/delivery.ts

@@ -177,6 +177,12 @@ export interface DeliveryActorProfile {
    * staleness window).
    */
   kind?: AccountKind | null;
+  /**
+   * The aliases Oxy publishes for the account. Must travel with the `Update`
+   * for the same reason `kind` does: the pushed actor and the fetched actor are
+   * one document, and a follower's instance learns a new alias from this push.
+   */
+  alsoKnownAs?: readonly string[] | null;
 }
 
 /** Resolve a local username to its Oxy profile (for the `Update(Person)` rebroadcast). */
@@ -695,6 +701,7 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
         profileHeaderImage,
         publicKey,
         createdAt: user.createdAt,
+        alsoKnownAs: user.alsoKnownAs,
       });
 
       const actor = urls.actor(username);

package/src/node/inboundDispatch.ts

@@ -12,6 +12,12 @@
  * post/engagement handlers live. The consent gate + notification side effects are
  * injected so the engine holds no app knowledge.
  *
+ * `Move` (account migration) is handed to {@link InboundDispatcherConfig.onMove}
+ * after a SHAPE check only: the engine proves the activity is the signing actor
+ * moving itself, and the app forwards it to Oxy (`POST /federation/move`), which
+ * owns the identity decision — the alias check and the re-fetch of the old
+ * actor's `movedTo`.
+ *
  * Extracted behaviour-identically from Mention's former `InboxProcessingService`
  * dispatcher + `handleIncomingFollow` / `handleUndo(Follow)` / `handleAccept` /
  * `handleReject`.
@@ -159,10 +165,56 @@ export interface InboundDispatcherConfig {
    * Delete / Update, and a non-follow Undo. The app's post/engagement handlers.
    */
   onContentActivity(activity: Record<string, unknown>, verifiedActorUri: string): Promise<void>;
+  /**
+   * Handle an account `Move` whose shape the engine has verified: signed by
+   * `oldActorUri`, which is both its `actor` and its `object`, naming a
+   * `targetActorUri`. The app forwards it to Oxy (`POST /federation/move`),
+   * which decides. Absent ⇒ a Move is logged and dropped.
+   */
+  onMove?(move: InboundMove): Promise<void>;
   /** Diagnostics sink. */
   logger: InboundDispatcherLogger;
 }
 
+/** A shape-verified inbound `Move`. Nothing here is trusted beyond the signature. */
+export interface InboundMove {
+  /** The activity `id`, the idempotency key Oxy records. */
+  activityId: string;
+  /** The account that is moving — the verified signer, its `actor` and its `object`. */
+  oldActorUri: string;
+  /** Where it says it moved. Oxy checks this names a local account that aliases the old one. */
+  targetActorUri: string;
+}
+
+/**
+ * The shape check for an inbound `Move`.
+ *
+ * A Move is only meaningful as an actor moving ITSELF: `actor` and `object` must
+ * both be the actor whose HTTP signature was verified, so a relay or a third
+ * party cannot move somebody else's followers. `target` must be an absolute
+ * https URI, and differ from the old actor.
+ */
+function parseInboundMove(
+  activity: Record<string, unknown>,
+  verifiedActorUri: string,
+): { ok: true; move: InboundMove } | { ok: false; reason: string } {
+  const activityId = typeof activity.id === 'string' ? activity.id : undefined;
+  if (!activityId) return { ok: false, reason: 'missing id' };
+  const actor = objectTargetUri(activity.actor);
+  if (actor !== verifiedActorUri) return { ok: false, reason: 'actor is not the signer' };
+  const object = objectTargetUri(activity.object);
+  if (object !== verifiedActorUri) return { ok: false, reason: 'object is not the moving actor' };
+  const target = objectTargetUri(activity.target);
+  if (!target) return { ok: false, reason: 'missing target' };
+  try {
+    if (new URL(target).protocol !== 'https:') return { ok: false, reason: 'target is not https' };
+  } catch {
+    return { ok: false, reason: 'target is not a URL' };
+  }
+  if (target === verifiedActorUri) return { ok: false, reason: 'target is the moving actor' };
+  return { ok: true, move: { activityId, oldActorUri: verifiedActorUri, targetActorUri: target } };
+}
+
 /** The inbound-activity dispatcher. */
 export interface InboundDispatcher {
   /** Process one already-actor-verified inbound activity. */
@@ -411,6 +463,19 @@ export function createInboundDispatcher(config: InboundDispatcherConfig): Inboun
       case 'Update':
         await config.onContentActivity(activity, verifiedActorUri);
         break;
+      case 'Move': {
+        const parsed = parseInboundMove(activity, verifiedActorUri);
+        if (!parsed.ok) {
+          logger.warn(`[Federation] dropping Move from ${verifiedActorUri}: ${parsed.reason}`);
+          break;
+        }
+        if (!config.onMove) {
+          logger.debug(`Unhandled Move from ${verifiedActorUri} (no onMove handler)`);
+          break;
+        }
+        await config.onMove(parsed.move);
+        break;
+      }
       default:
         logger.debug(`Unhandled activity type: ${validation.type}`);
     }

package/src/node/index.ts

@@ -55,6 +55,7 @@ export {
   type ActorResolverLogger,
   type ActorTextAdapter,
   type FederatedActorStore,
+  type CollectionCount,
   type FederatedActorRecordBase,
   type FederatedActorUpsert,
   type FederatedActorField,
@@ -100,6 +101,7 @@ export {
 export {
   createInboundDispatcher,
   ActorResolutionPendingError,
+  type InboundMove,
   type InboundDispatcher,
   type InboundDispatcherConfig,
   type InboundDispatcherLogger,