@oxy.so/federation 1.0.1 → 2.0.0

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

@@ -78,11 +78,31 @@ 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. */
@@ -245,7 +265,22 @@ export declare class ActorResolver<TActor extends FederatedActorRecordBase> {
      * allowed to throw out of the caller. Idempotent.
      */
     tombstoneGoneActor(actorUri: string): Promise<void>;
-    /** Fetch the totalItems count from an ActivityPub collection URL. */
+    /**
+     * 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 fetchCollectionCount;
     /**
      * Get a cached actor or fetch if missing/stale (>24h).

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

@@ -28,7 +28,7 @@ export { createIdentityBridge, type IdentityBridge, type IdentityBridgeConfig, t
  * 410-Gone tombstone) over a bring-your-own-store adapter, the identity bridge,
  * and injected transports + text normalization.
  */
-export { createActorResolver, ActorResolver, type ActorResolverConfig, type ActorResolverIdentity, type ActorResolverLogger, type ActorTextAdapter, type FederatedActorStore, type FederatedActorRecordBase, type FederatedActorUpsert, type FederatedActorField, type WebFingerFetch, type WebFingerJrd, } from './actorResolver';
+export { createActorResolver, ActorResolver, type ActorResolverConfig, type ActorResolverIdentity, type ActorResolverLogger, type ActorTextAdapter, type FederatedActorStore, type CollectionCount, type FederatedActorRecordBase, type FederatedActorUpsert, type FederatedActorField, type WebFingerFetch, type WebFingerJrd, } from './actorResolver';
 /**
  * Outbound activity delivery + the follow lifecycle (Follow / Undo(Follow) /
  * Accept(Follow)) + the `Update(Person)` actor rebroadcast, over injected key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/federation",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Oxy Federation — the app-agnostic ActivityPub identity + follow engine substrate: the network-connector contract, normalized cross-network DTOs, HTTP signatures, actor resolution, the outbound delivery transport + follow lifecycle, the inbound dispatcher, and the webfinger/actor/inbox Express routers. Domain-parameterized so every Oxy app backend federates under its own domain.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -61,13 +61,13 @@
     "directory": "packages/federation"
   },
   "author": "OxyHQ",
-  "license": "Apache-2.0",
+  "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://oxy.so",
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "bun run --filter @oxy.so/contracts build && bun run --filter @oxy.so/protocol build && bun run --filter @oxy.so/core build && bun run build:cjs && bun run build:esm && bun run build:types",
+    "build": "node ../core/scripts/build-workspace-deps.mjs @oxy.so/contracts @oxy.so/protocol @oxy.so/core && bun run build:cjs && bun run build:esm && bun run build:types",
     "build:cjs": "tsc -p tsconfig.cjs.json",
     "build:esm": "tsc -p tsconfig.esm.json && node scripts/fix-esm-imports.mjs",
     "build:types": "tsc -p tsconfig.types.json",

package/src/__tests__/actorCollectionCounts.test.ts

@@ -0,0 +1,172 @@
+import type { NormalizedExternalActor } from '../index';
+import {
+  createActorResolver,
+  type ActorResolverConfig,
+  type FederatedActorRecordBase,
+  type FederatedActorUpsert,
+} from '../node/actorResolver';
+
+/**
+ * A remote collection count that could not be read is UNKNOWN, not zero.
+ *
+ * `fetchCollectionCount` used to turn every failure — a hidden collection's 403,
+ * a timeout, a body with no `totalItems` — into `0`, so the store recorded and
+ * the profile showed "0 followers" for accounts with thousands. These pin the
+ * three outcomes apart: a reported number (including a real 0), a definitive
+ * `null`, and an ABSENT key for a failed attempt, which is what tells the store
+ * to keep the value it already has.
+ */
+
+interface TestActor extends FederatedActorRecordBase {
+  uri: string;
+}
+
+const ACTOR = 'https://remote.example/users/bob';
+const FOLLOWERS = 'https://remote.example/users/bob/followers';
+const FOLLOWING = 'https://remote.example/users/bob/following';
+const OUTBOX = 'https://remote.example/users/bob/outbox';
+
+type CollectionReply = Response | (() => Promise<Response>);
+
+function actorDocument(overrides: Record<string, unknown> = {}): string {
+  return JSON.stringify({
+    id: ACTOR,
+    type: 'Person',
+    inbox: 'https://remote.example/users/bob/inbox',
+    preferredUsername: 'bob',
+    followers: FOLLOWERS,
+    following: FOLLOWING,
+    outbox: OUTBOX,
+    ...overrides,
+  });
+}
+
+function collection(totalItems: unknown): Response {
+  return new Response(JSON.stringify({ type: 'OrderedCollection', totalItems }));
+}
+
+async function resolveWith(replies: {
+  actor?: string;
+  followers?: CollectionReply;
+  following?: CollectionReply;
+  outbox?: CollectionReply;
+}): Promise<{ upserts: FederatedActorUpsert[]; bridged: NormalizedExternalActor[] }> {
+  const upserts: FederatedActorUpsert[] = [];
+  const bridged: NormalizedExternalActor[] = [];
+  const reply = (r: CollectionReply | undefined): Promise<Response> => {
+    if (!r) return Promise.resolve(collection(7));
+    return typeof r === 'function' ? r() : Promise.resolve(r);
+  };
+
+  const config: ActorResolverConfig<TestActor> = {
+    federationEnabled: true,
+    signedFetch: async (url) => {
+      if (url === ACTOR) return new Response(replies.actor ?? actorDocument());
+      if (url === FOLLOWERS) return reply(replies.followers);
+      if (url === FOLLOWING) return reply(replies.following);
+      if (url === OUTBOX) return reply(replies.outbox);
+      return new Response(null, { status: 404 });
+    },
+    fetchWebFinger: async () => null,
+    isBlockedDomain: () => false,
+    normalizeFederatedAcct: (acct) => acct,
+    domainFromAcct: (acct) => acct.split('@')[1],
+    firstStringUrl: () => undefined,
+    store: {
+      findActorByUri: async () => null,
+      upsertActor: async (uri, update) => {
+        upserts.push(update);
+        return { _id: 'row-1', uri };
+      },
+      findActorByPublicKeyId: async () => null,
+      setActorOxyUserId: async () => {},
+      tombstoneActor: async () => null,
+    },
+    identity: {
+      resolveExternalUser: async (actor) => {
+        bridged.push(actor);
+        return null;
+      },
+      reportActorGone: async () => 'archived',
+    },
+    text: {
+      inlineField: (value) => (typeof value === 'string' ? value : ''),
+      inlineDisplayName: (raw) => raw,
+      sanitizeFieldValue: (html) => html,
+      htmlToPlainText: (html) => html,
+    },
+    logger: { info: () => {}, warn: () => {} },
+  };
+
+  await createActorResolver(config).fetchRemoteActor(ACTOR);
+  return { upserts, bridged };
+}
+
+describe('fetchRemoteActor — remote collection counts', () => {
+  it('stores reported totals, and a real 0 stays 0', async () => {
+    const { upserts } = await resolveWith({
+      followers: collection(1234),
+      following: collection(0),
+      outbox: collection(56),
+    });
+
+    expect(upserts).toHaveLength(1);
+    expect(upserts[0]).toMatchObject({ followersCount: 1234, followingCount: 0, postsCount: 56 });
+  });
+
+  it.each([401, 403, 404, 410])('records a collection that answers %i as unknown (null), not 0', async (status) => {
+    const { upserts } = await resolveWith({
+      followers: new Response(null, { status }),
+      following: collection(3),
+    });
+
+    expect(upserts[0]?.followersCount).toBeNull();
+    expect(upserts[0]?.followingCount).toBe(3);
+  });
+
+  it.each([
+    ['missing', undefined],
+    ['a string', '1234'],
+    ['negative', -1],
+    ['fractional', 1.5],
+  ])('records a collection whose totalItems is %s as unknown (null)', async (_label, totalItems) => {
+    const { upserts } = await resolveWith({ followers: collection(totalItems) });
+
+    expect(upserts[0]?.followersCount).toBeNull();
+  });
+
+  it('records an actor that advertises no collection as unknown (null)', async () => {
+    const { upserts } = await resolveWith({
+      actor: actorDocument({ followers: undefined, following: undefined }),
+    });
+
+    expect(upserts[0]?.followersCount).toBeNull();
+    expect(upserts[0]?.followingCount).toBeNull();
+  });
+
+  it.each([
+    ['a timeout', () => Promise.reject(new Error('The operation was aborted due to timeout'))],
+    ['a 500', () => Promise.resolve(new Response(null, { status: 500 }))],
+    ['a 429', () => Promise.resolve(new Response(null, { status: 429 }))],
+    ['malformed JSON', () => Promise.resolve(new Response('{"totalItems": 12'))],
+    ['an empty body', () => Promise.resolve(new Response(''))],
+  ] as const)('OMITS a count whose fetch failed with %s, so a known value is kept', async (_label, followers) => {
+    const { upserts } = await resolveWith({ followers, following: collection(9) });
+
+    expect(upserts[0]).not.toHaveProperty('followersCount');
+    expect(upserts[0]?.followingCount).toBe(9);
+  });
+
+  it('never hands the identity bridge a zero it did not read', async () => {
+    const { bridged } = await resolveWith({
+      followers: new Response(null, { status: 403 }),
+      following: () => Promise.reject(new Error('timeout')),
+      outbox: collection(0),
+    });
+
+    expect(bridged).toHaveLength(1);
+    expect(bridged[0]?.followersCount).toBeUndefined();
+    expect(bridged[0]?.followingCount).toBeUndefined();
+    expect(bridged[0]?.postsCount).toBe(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/index.ts

@@ -55,6 +55,7 @@ export {
   type ActorResolverLogger,
   type ActorTextAdapter,
   type FederatedActorStore,
+  type CollectionCount,
   type FederatedActorRecordBase,
   type FederatedActorUpsert,
   type FederatedActorField,