@oxy.so/federation 2.3.0 → 2.4.1

package/src/__tests__/delivery.test.ts

@@ -2,6 +2,7 @@ import { Readable } from 'node:stream';
 import { createDomainPolicy } from '../apUri';
 import {
   createDeliveryService,
+  DeliveryAuthorizationDeniedError,
   type DeliveryServiceConfig,
   type DeliveryActorFields,
   type DeliveryQueueJob,
@@ -39,6 +40,7 @@ function makeRig(
     sharingEnabled?: boolean;
     assertSafeInboxUrl?: DeliveryServiceConfig<StoredActor>['assertSafeInboxUrl'];
     blockedHosts?: string[];
+    authorizeDelivery?: DeliveryServiceConfig<StoredActor>['authorizeDelivery'];
   } = {},
 ) {
   const deliveredBodies: Array<{ url: string; body: string }> = [];
@@ -53,7 +55,11 @@ function makeRig(
   const deletedFollowIds: unknown[] = [];
   const refreshedInBackground: string[] = [];
 
-  const sign: HttpSignatureSigner = async () => 'TESTSIG';
+  const signatures: string[] = [];
+  const sign: HttpSignatureSigner = async (keyId) => {
+    signatures.push(keyId);
+    return 'TESTSIG';
+  };
   const domainPolicy =
     overrides.blockedHosts === undefined
       ? createDomainPolicy({ domain: DOMAIN })
@@ -61,6 +67,7 @@ function makeRig(
 
   const config: DeliveryServiceConfig<StoredActor> = {
     federationEnabled: overrides.federationEnabled ?? true,
+    authorizeDelivery: overrides.authorizeDelivery,
     userAgent: 'Mention/mention.earth (ActivityPub)',
     apContentType: 'application/activity+json',
     keys: {
@@ -145,6 +152,7 @@ function makeRig(
 
   return {
     service: createDeliveryService(config),
+    signatures,
     deliveredBodies,
     enqueued,
     fallbackCreates,
@@ -462,3 +470,103 @@ describe('federateActorUpdate', () => {
     expect(rig.enqueued).toHaveLength(0);
   });
 });
+
+describe('live delivery authorization', () => {
+  const activity = {
+    type: 'Create',
+    actor: 'https://untrusted.example/not-the-sender',
+    object: { type: 'Note', content: 'protected' },
+  };
+  const remoteActorUri = 'https://remote.example/users/bob';
+  const actorsByUri = {
+    [remoteActorUri]: { uri: remoteActorUri, inboxUrl: 'https://remote.example/inbox' },
+  };
+
+  it('uses trusted sender metadata and refuses before signing, sending or enqueueing', async () => {
+    const authorizeDelivery = jest.fn(async () => false);
+    const rig = makeRig({ authorizeDelivery });
+    await expect(
+      rig.service.deliverActivity(
+        activity,
+        'https://remote.example/inbox',
+        'canonical-sender',
+        'alice',
+      ),
+    ).rejects.toBeInstanceOf(DeliveryAuthorizationDeniedError);
+    await expect(
+      rig.service.queueDelivery(activity, 'https://remote.example/inbox', 'canonical-sender'),
+    ).rejects.toBeInstanceOf(DeliveryAuthorizationDeniedError);
+    expect(authorizeDelivery).toHaveBeenCalledWith({
+      activity,
+      senderAccountId: 'canonical-sender',
+    });
+    expect(rig.signatures).toEqual([]);
+    expect(rig.deliveredBodies).toEqual([]);
+    expect(rig.enqueued).toEqual([]);
+    expect(rig.fallbackCreates).toEqual([]);
+  });
+
+  it('propagates transient authority failure without disguising it as a denial or send success', async () => {
+    const unavailable = new Error('policy service unavailable');
+    const rig = makeRig({
+      authorizeDelivery: async () => {
+        throw unavailable;
+      },
+    });
+    await expect(
+      rig.service.deliverActivity(activity, 'https://remote.example/inbox', 'sender', 'alice'),
+    ).rejects.toBe(unavailable);
+    expect(rig.signatures).toEqual([]);
+    expect(rig.deliveredBodies).toEqual([]);
+  });
+
+  it('checks internal Follow and Accept paths and does not commit a refused follow', async () => {
+    const rig = makeRig({ actorsByUri, authorizeDelivery: async () => false });
+    await expect(rig.service.sendFollow('sender', 'alice', remoteActorUri)).rejects.toBeInstanceOf(
+      DeliveryAuthorizationDeniedError,
+    );
+    await expect(
+      rig.service.sendAccept('sender', 'alice', 'follow-id', remoteActorUri),
+    ).rejects.toBeInstanceOf(DeliveryAuthorizationDeniedError);
+    await flush();
+    expect(rig.upsertedFollows).toEqual([]);
+    expect(rig.refreshedInBackground).toEqual([]);
+    expect(rig.signatures).toEqual([]);
+    expect(rig.deliveredBodies).toEqual([]);
+    expect(rig.enqueued).toEqual([]);
+  });
+
+  it('authorizes one fanout once and rechecks a durable delivery after revocation', async () => {
+    const authorizeDelivery = jest.fn(async () => true);
+    const rig = makeRig({
+      authorizeDelivery,
+      followerActorUris: ['a', 'b'],
+      followerInboxes: {
+        a: { inboxUrl: 'https://a.example/inbox' },
+        b: { inboxUrl: 'https://b.example/inbox' },
+      },
+    });
+    await rig.service.deliverToFollowers(activity, 'sender', 'alice');
+    expect(authorizeDelivery).toHaveBeenCalledTimes(1);
+    expect(rig.enqueued).toHaveLength(2);
+    authorizeDelivery.mockResolvedValue(false);
+    const job = rig.enqueued[0];
+    await expect(
+      rig.service.deliverActivity(job.activityJson, job.targetInbox, job.senderOxyUserId, 'alice'),
+    ).rejects.toBeInstanceOf(DeliveryAuthorizationDeniedError);
+    expect(rig.signatures).toEqual([]);
+  });
+
+  it('preserves approved adult delivery and checks a Follow once per immediate operation', async () => {
+    const authorizeDelivery = jest.fn(async () => true);
+    const rig = makeRig({ actorsByUri, authorizeDelivery });
+    expect(await rig.service.sendFollow('adult', 'alice', remoteActorUri)).toEqual({
+      success: true,
+      pending: false,
+    });
+    await flush();
+    expect(authorizeDelivery).toHaveBeenCalledTimes(1);
+    expect(rig.deliveredBodies).toHaveLength(1);
+    expect(rig.signatures).toHaveLength(1);
+  });
+});

package/src/__tests__/routers.test.ts

@@ -123,6 +123,52 @@ function makeActorApp(
 }
 
 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')
@@ -329,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')

package/src/node/actorRouter.ts

@@ -23,6 +23,7 @@ import { Router, type Request, type Response } from 'express';
 import type { AccountKind } from '@oxy.so/contracts';
 import type { User } from '@oxy.so/core';
 import { AP_CONTEXT } from '../apContext';
+import { discoveryCacheControl } from './httpCacheControl';
 import { verifyHttpSignature } from '../httpSignature';
 import type { UrlBuilders } from '../urls';
 import { INSTANCE_ACTOR_USERNAME, normalizeActorUsername } from '../urls';
@@ -121,6 +122,8 @@ export interface ActorRouterConfig {
     offset: number,
     limit: number,
   ): Promise<FollowPage>;
+  /** Actor HTTP response TTL in whole seconds, 0..86400. Defaults to 1800; 0 sends no-store. */
+  httpCacheTtlSeconds?: number;
   /** Diagnostics sink. */
   logger: ActorRouterLogger;
 }
@@ -158,6 +161,7 @@ function parseFollowOffset(raw: unknown): number {
 export function createActorRouter(config: ActorRouterConfig): Router {
   const router = Router();
   const { urls, domain, apContentType, logger } = config;
+  const httpCacheControl = discoveryCacheControl(config.httpCacheTtlSeconds, 1800);
 
   function wantsActivityPub(req: Request): boolean {
     return config.wantsActivityPub(req.headers.accept);
@@ -383,7 +387,7 @@ export function createActorRouter(config: ActorRouterConfig): Router {
           },
         };
         res.set('Content-Type', apContentType);
-        res.set('Cache-Control', 'max-age=1800');
+        res.set('Cache-Control', httpCacheControl);
         return res.json(actorObject);
       }
 
@@ -424,7 +428,7 @@ export function createActorRouter(config: ActorRouterConfig): Router {
       });
 
       res.set('Content-Type', apContentType);
-      res.set('Cache-Control', 'max-age=1800');
+      res.set('Cache-Control', httpCacheControl);
       return res.json({ '@context': AP_CONTEXT, ...actorObject });
     } catch (err) {
       logger.error('Actor endpoint error:', err);

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;
@@ -228,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. */
@@ -306,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,
@@ -344,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}`);
@@ -400,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;
@@ -446,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) : [];
 
@@ -559,10 +608,6 @@ 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
@@ -570,9 +615,6 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
     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,
@@ -581,11 +623,17 @@ 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);
         })

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/index.ts

@@ -81,6 +81,8 @@ export {
  */
 export {
   createDeliveryService,
+  DeliveryAuthorizationDeniedError,
+  type DeliveryAuthorizationContext,
   type DeliveryService,
   type DeliveryServiceConfig,
   type DeliveryLogger,

package/src/node/webfingerRouter.ts

@@ -13,11 +13,12 @@
  */
 
 import { Router, type Request, type Response } from 'express';
+import { discoveryCacheControl } from './httpCacheControl';
 import { isSameFederationHost } from '../apUri';
 import type { UrlBuilders } from '../urls';
 import { INSTANCE_ACTOR_USERNAME, normalizeActorUsername } from '../urls';
 
-/** 1 hour, in seconds — the WebFinger JRD cache TTL + response `max-age`. */
+/** Default HTTP response max-age. The injected JRD cache has its own policy. */
 const WEBFINGER_CACHE_TTL = 3600;
 /** 24h — host-meta is effectively static. */
 const HOST_META_CACHE_CONTROL = `max-age=${60 * 60 * 24}`;
@@ -64,6 +65,8 @@ export interface WebfingerRouterConfig {
     get(username: string): Promise<WebfingerJrd | null>;
     set(username: string, jrd: WebfingerJrd): void;
   };
+  /** HTTP response TTL in whole seconds, 0..86400. Defaults to 3600; 0 sends no-store. */
+  httpCacheTtlSeconds?: number;
   /** Diagnostics sink. */
   logger: WebfingerLogger;
 }
@@ -72,6 +75,7 @@ export interface WebfingerRouterConfig {
 export function createWebfingerRouter(config: WebfingerRouterConfig): Router {
   const router = Router();
   const { domain } = config;
+  const httpCacheControl = discoveryCacheControl(config.httpCacheTtlSeconds, WEBFINGER_CACHE_TTL);
   const webfingerTemplate = `https://${domain}/.well-known/webfinger?resource={uri}`;
 
   router.get('/webfinger', async (req: Request, res: Response) => {
@@ -130,7 +134,7 @@ export function createWebfingerRouter(config: WebfingerRouterConfig): Router {
           ],
         };
         res.set('Content-Type', 'application/jrd+json; charset=utf-8');
-        res.set('Cache-Control', `max-age=${WEBFINGER_CACHE_TTL}`);
+        res.set('Cache-Control', httpCacheControl);
         return res.json(instanceJrd);
       }
 
@@ -138,7 +142,7 @@ export function createWebfingerRouter(config: WebfingerRouterConfig): Router {
       const cached = await config.cache.get(username);
       if (cached) {
         res.set('Content-Type', 'application/jrd+json; charset=utf-8');
-        res.set('Cache-Control', `max-age=${WEBFINGER_CACHE_TTL}`);
+        res.set('Cache-Control', httpCacheControl);
         return res.json(cached);
       }
 
@@ -183,7 +187,7 @@ export function createWebfingerRouter(config: WebfingerRouterConfig): Router {
       config.cache.set(username, response);
 
       res.set('Content-Type', 'application/jrd+json; charset=utf-8');
-      res.set('Cache-Control', `max-age=${WEBFINGER_CACHE_TTL}`);
+      res.set('Cache-Control', httpCacheControl);
       return res.json(response);
     } catch (err) {
       config.logger.error('WebFinger error:', err);