@oxy.so/federation 2.3.0 → 2.4.0

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

@@ -107,6 +107,8 @@ export interface ActorRouterConfig {
     };
     /** Fetch one page of a user's Oxy follow graph (followers OR following). */
     fetchFollowPage(userId: string, direction: 'followers' | 'following', 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;
 }

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

@@ -27,6 +27,16 @@ import type { AccountKind } from '@oxy.so/contracts';
 import { type HttpSignatureSigner } from '../httpSignature';
 import type { UrlBuilders } from '../urls';
 import type { LocalActorBuilder } from '../actorObject';
+/** 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 declare class DeliveryAuthorizationDeniedError extends Error {
+    readonly code = "DELIVERY_AUTHORIZATION_DENIED";
+    constructor();
+}
 /** Minimal logging sink the delivery service writes to. */
 export interface DeliveryLogger {
     debug(message: string, detail?: unknown): void;
@@ -199,6 +209,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. */
@@ -242,7 +259,10 @@ export interface DeliveryService {
         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, remoteActorUri: string): Promise<boolean>;
     /** Send an Accept(Follow) back to a remote actor. */
     sendAccept(localOxyUserId: string, localUsername: string, followActivityId: string, remoteActorUri: string): Promise<void>;

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

@@ -0,0 +1,2 @@
+/** Shared discovery config validation; zero forbids downstream response retention. */
+export declare function discoveryCacheControl(value: number | undefined, defaultSeconds: number): string;

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

@@ -39,7 +39,7 @@ export { createActorResolver, ActorResolver, type ActorResolverConfig, type Acto
  * Accept(Follow)) + the `Update(Person)` actor rebroadcast, over injected key
  * custody, an SSRF-safe delivery transport, and bring-your-own-store adapters.
  */
-export { createDeliveryService, type DeliveryService, type DeliveryServiceConfig, type DeliveryLogger, type DeliveryKeys, type DeliverSingleHop, type DeliverSingleHopInit, type DeliverSingleHopResult, type DeliveryResponseStream, type DeliveryTransport, type DeliveryQueueJob, type DeliveryFallbackQueue, type DeliveryActorFields, type DeliveryActorStore, type DeliveryFollowStore, type DeliveryActorRefresh, type DeliveryConsent, type DeliveryActorProfile, type DeliveryIdentity, type DeliveryProfile, type SafeUrlVerdict, } from './delivery';
+export { createDeliveryService, DeliveryAuthorizationDeniedError, type DeliveryAuthorizationContext, type DeliveryService, type DeliveryServiceConfig, type DeliveryLogger, type DeliveryKeys, type DeliverSingleHop, type DeliverSingleHopInit, type DeliverSingleHopResult, type DeliveryResponseStream, type DeliveryTransport, type DeliveryQueueJob, type DeliveryFallbackQueue, type DeliveryActorFields, type DeliveryActorStore, type DeliveryFollowStore, type DeliveryActorRefresh, type DeliveryConsent, type DeliveryActorProfile, type DeliveryIdentity, type DeliveryProfile, type SafeUrlVerdict, } from './delivery';
 /**
  * Inbound ActivityPub dispatch — the untrusted-activity validator + switch, the
  * follow-protocol handlers (Follow / Accept / Undo(Follow) / Reject) over the

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

@@ -55,6 +55,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;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/federation",
-  "version": "2.3.0",
+  "version": "2.4.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",

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);