@oxy.so/federation 2.2.1 → 2.4.0

package/src/__tests__/routers.test.ts

@@ -50,7 +50,8 @@ function makeWebfingerApp(overrides: Partial<WebfingerRouterConfig> = {}): Expre
     resolveUser: async (username) => (username === 'alice' ? { _id: 'u-alice' } : null),
     consent: {
       isSharingEnabledFromUser: () => true,
-      getSharingStateByUsername: async (username) => (username === 'alice' ? 'enabled' : 'unknown-user'),
+      getSharingStateByUsername: async (username) =>
+        username === 'alice' ? 'enabled' : 'unknown-user',
     },
     cache: { get: async () => null, set: () => {} },
     logger: { error: () => {} },
@@ -60,10 +61,12 @@ function makeWebfingerApp(overrides: Partial<WebfingerRouterConfig> = {}): Expre
   return app;
 }
 
-function makeActorApp(overrides: {
-  actorConfig?: Partial<ActorRouterConfig>;
-  onDispatch?: (activity: Record<string, unknown>, verifiedActorUri: string) => void;
-} = {}): Express {
+function makeActorApp(
+  overrides: {
+    actorConfig?: Partial<ActorRouterConfig>;
+    onDispatch?: (activity: Record<string, unknown>, verifiedActorUri: string) => void;
+  } = {},
+): Express {
   const app = express();
   app.use(
     express.json({
@@ -80,17 +83,30 @@ function makeActorApp(overrides: {
     apContentType: 'application/activity+json',
     urls,
     wantsActivityPub,
-    getPublicKey: async () => ({ keyId: `${urls.actor('alice')}#main-key`, publicKeyPem: 'LOCALPEM' }),
-    resolveUser: async (username) => (username === 'alice' ? { _id: 'u-alice', name: { displayName: 'Alice' }, _count: { followers: 3, following: 1 } } : null),
+    getPublicKey: async () => ({
+      keyId: `${urls.actor('alice')}#main-key`,
+      publicKeyPem: 'LOCALPEM',
+    }),
+    resolveUser: async (username) =>
+      username === 'alice'
+        ? { _id: 'u-alice', name: { displayName: 'Alice' }, _count: { followers: 3, following: 1 } }
+        : null,
     consent: {
       isSharingEnabledFromUser: () => true,
-      getSharingStateByUsername: async (username) => (username === 'alice' ? 'enabled' : 'unknown-user'),
+      getSharingStateByUsername: async (username) =>
+        username === 'alice' ? 'enabled' : 'unknown-user',
     },
-    buildLocalActorObject: (params) => ({ id: urls.actor(params.username), type: 'Person', name: params.displayName }),
+    buildLocalActorObject: (params) => ({
+      id: urls.actor(params.username),
+      type: 'Person',
+      name: params.displayName,
+    }),
     getBanner: async () => null,
     inbound: {
       fetchPublicKey: async (keyId) =>
-        keyId === REMOTE_KEY_ID ? { publicKeyPem: REMOTE_PUBLIC_PEM, actorUri: REMOTE_ACTOR } : null,
+        keyId === REMOTE_KEY_ID
+          ? { publicKeyPem: REMOTE_PUBLIC_PEM, actorUri: REMOTE_ACTOR }
+          : null,
       trustForwardedHost: true,
       enqueueInboxActivity: async () => false, // force the inline dispatch path
       processInboxActivity: async (activity, verifiedActorUri) => {
@@ -107,24 +123,82 @@ function makeActorApp(overrides: {
 }
 
 describe('webfinger router', () => {
+  it('keeps the existing one-hour HTTP caching default', async () => {
+    const response = await request(makeWebfingerApp())
+      .get('/.well-known/webfinger')
+      .query({ resource: 'acct:alice@mention.earth' });
+    expect(response.headers['cache-control']).toBe('max-age=3600');
+  });
+
+  it.each([-1, 1.5, Number.NaN, Number.POSITIVE_INFINITY, 86401])(
+    'rejects invalid HTTP cache TTL %s at construction',
+    (httpCacheTtlSeconds) => {
+      expect(() => makeWebfingerApp({ httpCacheTtlSeconds })).toThrow(RangeError);
+    },
+  );
+
+  it('makes fresh, cached and instance discovery noncacheable when TTL is zero', async () => {
+    const cacheGet = jest.fn(async () => null as { subject: string; links: [] } | null);
+    const app = makeWebfingerApp({
+      httpCacheTtlSeconds: 0,
+      cache: { get: cacheGet, set: () => {} },
+    });
+    const fresh = await request(app)
+      .get('/.well-known/webfinger')
+      .query({ resource: 'acct:alice@mention.earth' });
+    expect(fresh.status).toBe(200);
+    expect(fresh.headers['cache-control']).toBe('no-store');
+    cacheGet.mockResolvedValue({ subject: 'acct:alice@mention.earth', links: [] });
+    const cached = await request(app)
+      .get('/.well-known/webfinger')
+      .query({ resource: 'acct:alice@mention.earth' });
+    expect(cached.status).toBe(200);
+    expect(cached.headers['cache-control']).toBe('no-store');
+    expect(cached.body.links).toEqual([]);
+    const instance = await request(app)
+      .get('/.well-known/webfinger')
+      .query({ resource: 'acct:instance@mention.earth' });
+    expect(instance.status).toBe(200);
+    expect(instance.headers['cache-control']).toBe('no-store');
+  });
+
+  it('accepts the documented maximum HTTP cache TTL', async () => {
+    const response = await request(makeWebfingerApp({ httpCacheTtlSeconds: 86400 }))
+      .get('/.well-known/webfinger')
+      .query({ resource: 'acct:alice@mention.earth' });
+    expect(response.headers['cache-control']).toBe('max-age=86400');
+  });
+
   it('resolves acct:alice@mention.earth to the actor self link (200)', async () => {
-    const res = await request(makeWebfingerApp()).get('/.well-known/webfinger').query({ resource: 'acct:alice@mention.earth' });
+    const res = await request(makeWebfingerApp())
+      .get('/.well-known/webfinger')
+      .query({ resource: 'acct:alice@mention.earth' });
     expect(res.status).toBe(200);
     expect(res.body.subject).toBe('acct:alice@mention.earth');
-    expect(res.body.links[0]).toEqual({ rel: 'self', type: 'application/activity+json', href: urls.actor('alice') });
+    expect(res.body.links[0]).toEqual({
+      rel: 'self',
+      type: 'application/activity+json',
+      href: urls.actor('alice'),
+    });
   });
 
   it('normalizes mixed-case acct local-parts before resolve', async () => {
-    const resolveUser = jest.fn(async (username: string) => (username === 'alice' ? { _id: 'u-alice' } : null));
+    const resolveUser = jest.fn(async (username: string) =>
+      username === 'alice' ? { _id: 'u-alice' } : null,
+    );
     const app = makeWebfingerApp({ resolveUser });
-    const res = await request(app).get('/.well-known/webfinger').query({ resource: 'acct:Alice@mention.earth' });
+    const res = await request(app)
+      .get('/.well-known/webfinger')
+      .query({ resource: 'acct:Alice@mention.earth' });
     expect(res.status).toBe(200);
     expect(resolveUser).toHaveBeenCalledWith('alice');
     expect(res.body.subject).toBe('acct:alice@mention.earth');
   });
 
   it('404s an unknown domain', async () => {
-    const res = await request(makeWebfingerApp()).get('/.well-known/webfinger').query({ resource: 'acct:alice@other.example' });
+    const res = await request(makeWebfingerApp())
+      .get('/.well-known/webfinger')
+      .query({ resource: 'acct:alice@other.example' });
     expect(res.status).toBe(404);
   });
 
@@ -138,9 +212,14 @@ describe('webfinger router', () => {
 
   it('404s a sharing-disabled user indistinguishably', async () => {
     const app = makeWebfingerApp({
-      consent: { isSharingEnabledFromUser: () => false, getSharingStateByUsername: async () => 'disabled' },
+      consent: {
+        isSharingEnabledFromUser: () => false,
+        getSharingStateByUsername: async () => 'disabled',
+      },
     });
-    const res = await request(app).get('/.well-known/webfinger').query({ resource: 'acct:alice@mention.earth' });
+    const res = await request(app)
+      .get('/.well-known/webfinger')
+      .query({ resource: 'acct:alice@mention.earth' });
     expect(res.status).toBe(404);
     expect(res.body).toEqual({ error: 'User not found' });
   });
@@ -193,9 +272,7 @@ describe('webfinger router — the instance (server) actor', () => {
     expect(webfinger.status).toBe(200);
     expect(actor.status).toBe(200);
 
-    const selfLink = webfinger.body.links.find(
-      (link: { rel: string }) => link.rel === 'self',
-    );
+    const selfLink = webfinger.body.links.find((link: { rel: string }) => link.rel === 'self');
     expect(selfLink).toBeDefined();
     // Positive control: neither side may be vacuously undefined.
     expect(typeof actor.body.id).toBe('string');
@@ -298,6 +375,30 @@ describe('webfinger router — the instance (server) actor', () => {
 });
 
 describe('actor router — GET /ap/users/:username', () => {
+  it('keeps the existing half-hour actor caching default', async () => {
+    const response = await request(makeActorApp())
+      .get('/ap/users/alice')
+      .set('Accept', 'application/activity+json');
+    expect(response.status).toBe(200);
+    expect(response.headers['cache-control']).toBe('max-age=1800');
+  });
+  it.each(['alice', 'instance'])(
+    'serves %s without HTTP caching when TTL is zero',
+    async (username) => {
+      const response = await request(makeActorApp({ actorConfig: { httpCacheTtlSeconds: 0 } }))
+        .get(`/ap/users/${username}`)
+        .set('Accept', 'application/activity+json');
+      expect(response.status).toBe(200);
+      expect(response.headers['cache-control']).toBe('no-store');
+    },
+  );
+  it.each([-1, 1.5, Number.NaN, Number.POSITIVE_INFINITY, 86401])(
+    'rejects invalid actor cache TTL %s',
+    (httpCacheTtlSeconds) => {
+      expect(() => makeActorApp({ actorConfig: { httpCacheTtlSeconds } })).toThrow(RangeError);
+    },
+  );
+
   it('serves the actor as 200 (NOT a redirect) for an AP Accept', async () => {
     const res = await request(makeActorApp())
       .get('/ap/users/alice')
@@ -333,17 +434,34 @@ describe('actor router — GET /ap/users/:username', () => {
 
 describe('actor router — inbox POST', () => {
   /** Build a validly-signed inbox request body + headers for `activity`. */
-  async function signedInbox(path: string, activity: Record<string, unknown>): Promise<{ body: string; headers: Record<string, string> }> {
+  async function signedInbox(
+    path: string,
+    activity: Record<string, unknown>,
+  ): Promise<{ body: string; headers: Record<string, string> }> {
     const body = JSON.stringify(activity);
-    const headers = await signRequest(sign, REMOTE_KEY_ID, 'POST', `https://${DOMAIN}${path}`, body);
+    const headers = await signRequest(
+      sign,
+      REMOTE_KEY_ID,
+      'POST',
+      `https://${DOMAIN}${path}`,
+      body,
+    );
     return { body, headers };
   }
 
   it('accepts a validly-signed activity (202) and reaches the dispatcher — no redirect', async () => {
     const dispatched: Array<{ activity: Record<string, unknown>; verifiedActorUri: string }> = [];
-    const app = makeActorApp({ onDispatch: (activity, verifiedActorUri) => dispatched.push({ activity, verifiedActorUri }) });
+    const app = makeActorApp({
+      onDispatch: (activity, verifiedActorUri) => dispatched.push({ activity, verifiedActorUri }),
+    });
 
-    const activity = { '@context': 'https://www.w3.org/ns/activitystreams', id: 'https://remote.example/f/1', type: 'Follow', actor: REMOTE_ACTOR, object: urls.actor('alice') };
+    const activity = {
+      '@context': 'https://www.w3.org/ns/activitystreams',
+      id: 'https://remote.example/f/1',
+      type: 'Follow',
+      actor: REMOTE_ACTOR,
+      object: urls.actor('alice'),
+    };
     const { body, headers } = await signedInbox('/ap/inbox', activity);
 
     const res = await request(app)
@@ -399,7 +517,9 @@ describe('actor router — inbox POST', () => {
       actorConfig: {
         inbound: {
           fetchPublicKey: async (keyId) =>
-            keyId === REMOTE_KEY_ID ? { publicKeyPem: REMOTE_PUBLIC_PEM, actorUri: REMOTE_ACTOR } : null,
+            keyId === REMOTE_KEY_ID
+              ? { publicKeyPem: REMOTE_PUBLIC_PEM, actorUri: REMOTE_ACTOR }
+              : null,
           trustForwardedHost: true,
           enqueueInboxActivity: async () => false,
           processInboxActivity: dispatcher.processInboxActivity,
@@ -436,7 +556,12 @@ describe('actor router — inbox POST', () => {
   });
 
   it('rejects an actor mismatch with 403', async () => {
-    const activity = { id: 'https://remote.example/f/2', type: 'Follow', actor: 'https://evil.example/users/x', object: urls.actor('alice') };
+    const activity = {
+      id: 'https://remote.example/f/2',
+      type: 'Follow',
+      actor: 'https://evil.example/users/x',
+      object: urls.actor('alice'),
+    };
     const { body, headers } = await signedInbox('/ap/inbox', activity);
     const res = await request(makeActorApp())
       .post('/ap/inbox')
@@ -448,7 +573,12 @@ describe('actor router — inbox POST', () => {
   });
 
   it('404s a user inbox for a sharing-disabled user (before signature verify)', async () => {
-    const activity = { id: 'https://remote.example/f/3', type: 'Follow', actor: REMOTE_ACTOR, object: urls.actor('ghost') };
+    const activity = {
+      id: 'https://remote.example/f/3',
+      type: 'Follow',
+      actor: REMOTE_ACTOR,
+      object: urls.actor('ghost'),
+    };
     const { body, headers } = await signedInbox('/ap/users/ghost/inbox', activity);
     const res = await request(makeActorApp())
       .post('/ap/users/ghost/inbox')

package/src/__tests__/tcoLinks.test.ts

@@ -0,0 +1,21 @@
+import { createTcoLinkExpander } from '../node/tcoLinks';
+import type { SingleHopFetch } from '../node/signedFetch';
+
+const fetchSingleHop: SingleHopFetch = async (url) => {
+  const location = { 'https://t.co/abc123': 'https://example.com/', 'https://t.co/self12': url }[
+    url
+  ];
+  return location
+    ? new Response(null, { status: 301, headers: { location } })
+    : new Response(null, { status: 404 });
+};
+
+it('replaces a t.co wrapper with its target and leaves anything else as written', async () => {
+  const expand = createTcoLinkExpander({ fetchSingleHop, userAgent: 'test' });
+
+  await expect(
+    expand('a https://t.co/abc123 b https://t.co/gone12 c https://t.co/self12 d https://bit.ly/x'),
+  ).resolves.toBe(
+    'a https://example.com/ b https://t.co/gone12 c https://t.co/self12 d https://bit.ly/x',
+  );
+});

package/src/actorObject.ts

@@ -257,7 +257,9 @@ function buildActorIcon(
   if (!avatar) return undefined;
   const resolved = config.media.resolveAvatar(avatar);
   if (!resolved || !isAbsoluteHttpUrl(resolved)) {
-    config.onWarn?.(`[Federation] Omitting actor icon — avatar did not resolve to an absolute URL (ref: ${avatar})`);
+    config.onWarn?.(
+      `[Federation] Omitting actor icon — avatar did not resolve to an absolute URL (ref: ${avatar})`,
+    );
     return undefined;
   }
   return apImageObject(resolved);
@@ -275,7 +277,9 @@ function buildActorImage(
   if (!banner) return undefined;
   const resolved = config.media.resolveBanner(banner);
   if (!resolved || !isAbsoluteHttpUrl(resolved)) {
-    config.onWarn?.(`[Federation] Omitting actor image — banner did not resolve to an absolute URL (ref: ${banner})`);
+    config.onWarn?.(
+      `[Federation] Omitting actor image — banner did not resolve to an absolute URL (ref: ${banner})`,
+    );
     return undefined;
   }
   return apImageObject(resolved);
@@ -309,7 +313,8 @@ export function normalizeAlsoKnownAs(values: readonly string[] | null | undefine
  */
 export function createLocalActorBuilder(config: LocalActorBuilderConfig): LocalActorBuilder {
   return (params: BuildLocalActorParams): Record<string, unknown> => {
-    const { username, displayName, kind, bio, avatar, profileHeaderImage, publicKey, createdAt } = params;
+    const { username, displayName, kind, bio, avatar, profileHeaderImage, publicKey, createdAt } =
+      params;
 
     const actorObject: Record<string, unknown> = {
       id: config.urls.actor(username),

package/src/apUri.ts

@@ -135,7 +135,9 @@ export function createDomainPolicy(config: DomainPolicyConfig): DomainPolicy {
     canonicalFederationHost(config.domain),
     canonicalFederationHost(config.actorDomain ?? config.domain),
   ]);
-  const identityApex = config.identityApex ? canonicalFederationHost(config.identityApex) : undefined;
+  const identityApex = config.identityApex
+    ? canonicalFederationHost(config.identityApex)
+    : undefined;
   const blocked = new Set<string>();
   for (const d of config.blockedDomains ?? []) {
     blocked.add(canonicalFederationHost(d));
@@ -144,7 +146,9 @@ export function createDomainPolicy(config: DomainPolicyConfig): DomainPolicy {
   return {
     isBlockedDomain(domain: string): boolean {
       const d = canonicalFederationHost(domain);
-      return localDomains.has(d) || (identityApex !== undefined && d === identityApex) || blocked.has(d);
+      return (
+        localDomains.has(d) || (identityApex !== undefined && d === identityApex) || blocked.has(d)
+      );
     },
     extractLocalPostId(objectUri: string): string | null {
       let parsed: URL;

package/src/httpSignature.ts

@@ -16,7 +16,7 @@
  *    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
+ * Lives in the isomorphic `.` entry (no Express / database driver): 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.

package/src/index.ts

@@ -8,8 +8,8 @@
  * 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,
+ * IMPORTANT: this entry is intentionally free of database drivers / 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
@@ -43,7 +43,12 @@ export {
  * 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';
+export {
+  createUrlBuilders,
+  normalizeActorUsername,
+  INSTANCE_ACTOR_USERNAME,
+  type UrlBuilders,
+} from './urls';
 
 /**
  * Network identity: the MECHANISM for re-labelling an account republished by a

package/src/networkIdentity.ts

@@ -168,7 +168,8 @@ export function parseUpstreamProfileUrl(
 
   const host = canonicalFederationHost(url.hostname);
   for (const network of networks) {
-    if (!network.profileHosts.some((allowed) => canonicalFederationHost(allowed) === host)) continue;
+    if (!network.profileHosts.some((allowed) => canonicalFederationHost(allowed) === host))
+      continue;
     const handle = profileUrlHandle(url.href, network.profileHosts, network.profilePathPrefix);
     if (handle !== undefined && handle.length > 0) return { network, handle };
   }
@@ -457,10 +458,16 @@ export function upstreamHandleFromProfileField(options: {
         // Observed bird.makeup Official assertion, 2026-09-13:
         // https://https://twitter.com/jordievole. Repair exactly one duplicated
         // HTTPS prefix, then run the ordinary host/path/credential validation.
-        const candidateHref = options.repairRepeatedHttpsScheme && href.startsWith('https://https://')
-          ? href.slice('https://'.length) : href;
+        const candidateHref =
+          options.repairRepeatedHttpsScheme && href.startsWith('https://https://')
+            ? href.slice('https://'.length)
+            : href;
         let handle: string | undefined;
-        try { handle = profileUrlHandle(candidateHref, options.hosts, prefix); } catch { continue; }
+        try {
+          handle = profileUrlHandle(candidateHref, options.hosts, prefix);
+        } catch {
+          continue;
+        }
         if (handle !== undefined && handle.length > 0) handles.set(handle.toLowerCase(), handle);
       }
     }
@@ -681,7 +688,9 @@ export function createBridgeRelabeller(
     vouchesForNetwork: (actorHost, networkDomain) => {
       const bridge = findBridge(actorHost);
       if (!bridge) return false;
-      return canonicalFederationHost(bridge.network.domain) === canonicalFederationHost(networkDomain);
+      return (
+        canonicalFederationHost(bridge.network.domain) === canonicalFederationHost(networkDomain)
+      );
     },
     deriveNetworkIdentity: (candidate) => {
       const entry = findBridge(candidate.host);