@oxy.so/federation 2.3.0 → 2.4.1

package/README.md

@@ -0,0 +1,31 @@
+# Oxy federation
+
+## Authorizing outbound delivery
+
+`createDeliveryService({ authorizeDelivery })` optionally checks live application
+policy before signing or queueing an activity. It receives `activity` and the
+trusted `senderAccountId` supplied by the app or persisted delivery job. Never
+infer that identity from an activity URL or a key ID. Follower fanout checks once
+for the batch; each later worker delivery checks again.
+
+Return `true` to allow or `false` for a definitive refusal. A refusal throws
+`DeliveryAuthorizationDeniedError`: a durable worker should mark the job
+suppressed (or permanently failed), without marking it delivered or retrying it.
+Other thrown errors are transient authority failures and should follow the
+worker's normal bounded retry policy. Neither path signs or sends the activity.
+Do not catch an authority failure and retry through an unguarded transport.
+
+Without the optional hook, delivery behavior is unchanged. `sendUndoFollow`'s
+boolean reports local relationship removal; it does not confirm remote delivery.
+
+## Discovery response caching
+
+`createWebfingerRouter({ httpCacheTtlSeconds })` controls HTTP caching of fresh,
+cached and instance WebFinger responses. The default remains 3600 seconds.
+`createActorRouter` accepts the same option for human and instance actor
+responses, retaining its existing 1800-second default.
+Use `0` for `Cache-Control: no-store` when live privacy decisions must govern
+each request. Only whole seconds from 0 through 86400 are accepted. This does
+not change the injected JRD cache: applications must also authorize its reads
+and their user resolver against current policy. It cannot retract documents
+already cached by remote consumers before this setting changes.

package/dist/cjs/node/actorRouter.js

@@ -23,6 +23,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createActorRouter = createActorRouter;
 const express_1 = require("express");
 const apContext_1 = require("../apContext");
+const httpCacheControl_1 = require("./httpCacheControl");
 const httpSignature_1 = require("../httpSignature");
 const urls_1 = require("../urls");
 /** Page size for the paginated followers/following collections (mirrors the outbox). */
@@ -57,6 +58,7 @@ function parseFollowOffset(raw) {
 function createActorRouter(config) {
     const router = (0, express_1.Router)();
     const { urls, domain, apContentType, logger } = config;
+    const httpCacheControl = (0, httpCacheControl_1.discoveryCacheControl)(config.httpCacheTtlSeconds, 1800);
     function wantsActivityPub(req) {
         return config.wantsActivityPub(req.headers.accept);
     }
@@ -242,7 +244,7 @@ function createActorRouter(config) {
                     },
                 };
                 res.set('Content-Type', apContentType);
-                res.set('Cache-Control', 'max-age=1800');
+                res.set('Cache-Control', httpCacheControl);
                 return res.json(actorObject);
             }
             const user = await config.resolveUser(username);
@@ -277,7 +279,7 @@ function createActorRouter(config) {
                 alsoKnownAs: user.alsoKnownAs,
             });
             res.set('Content-Type', apContentType);
-            res.set('Cache-Control', 'max-age=1800');
+            res.set('Cache-Control', httpCacheControl);
             return res.json({ '@context': apContext_1.AP_CONTEXT, ...actorObject });
         }
         catch (err) {

package/dist/cjs/node/delivery.js

@@ -25,6 +25,7 @@
  * call `deliverToFollowers` / `deliverActivity` / `queueDelivery` here.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeliveryAuthorizationDeniedError = void 0;
 exports.createDeliveryService = createDeliveryService;
 const apContext_1 = require("../apContext");
 const httpSignature_1 = require("../httpSignature");
@@ -34,6 +35,15 @@ const DELIVER_ACTIVITY_TIMEOUT_MS = 15000;
 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';
+/** A definitive refusal: workers must discard, not retry or count a delivery. */
+class DeliveryAuthorizationDeniedError extends Error {
+    constructor() {
+        super('Outbound federation delivery is not authorized');
+        this.code = 'DELIVERY_AUTHORIZATION_DENIED';
+        this.name = 'DeliveryAuthorizationDeniedError';
+    }
+}
+exports.DeliveryAuthorizationDeniedError = DeliveryAuthorizationDeniedError;
 /** Read a bounded prefix of a failed-delivery response body for the debug log. */
 async function readResponsePreview(response) {
     const chunks = [];
@@ -72,7 +82,17 @@ function createDeliveryService(config) {
         const host = urlHost(url);
         return host === null || config.isBlockedDomain(host);
     }
+    async function authorizeDelivery(activity, senderAccountId) {
+        if (config.authorizeDelivery &&
+            !(await config.authorizeDelivery({ activity, senderAccountId }))) {
+            throw new DeliveryAuthorizationDeniedError();
+        }
+    }
     async function deliverActivity(activity, targetInbox, senderOxyUserId, senderUsername) {
+        await authorizeDelivery(activity, senderOxyUserId);
+        return deliverAuthorizedActivity(activity, targetInbox, senderUsername);
+    }
+    async function deliverAuthorizedActivity(activity, targetInbox, senderUsername) {
         if (isBlockedUrl(targetInbox)) {
             logger.warn(`[FedDeliver] refusing outbound delivery to blocked inbox ${targetInbox}`);
             return false;
@@ -110,6 +130,7 @@ function createDeliveryService(config) {
         }
     }
     async function queueDelivery(activity, targetInbox, senderOxyUserId) {
+        await authorizeDelivery(activity, senderOxyUserId);
         if (isBlockedUrl(targetInbox)) {
             logger.warn(`[FedDeliver] not queueing delivery to blocked inbox ${targetInbox}`);
             return;
@@ -147,6 +168,7 @@ function createDeliveryService(config) {
         return actor.sharedInboxUrl ?? actor.inboxUrl ?? undefined;
     }
     async function deliverToFollowers(activity, senderOxyUserId, senderUsername, options = {}) {
+        await authorizeDelivery(activity, senderOxyUserId);
         const actorUris = await config.follows.listAcceptedInboundFollowerActorUris(senderOxyUserId);
         const actors = actorUris.length > 0 ? await config.store.findActorInboxesByUris(actorUris) : [];
         // Group by shared inbox to avoid duplicate deliveries. Follower inboxes
@@ -241,17 +263,12 @@ function createDeliveryService(config) {
         // cached; if the actor is unknown locally we still record the follow and
         // 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
         // activity ID is deterministic across retries before the actor is cached.
         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 = {
             '@context': 'https://www.w3.org/ns/activitystreams',
             id: activityId,
@@ -259,11 +276,16 @@ function createDeliveryService(config) {
             actor: localActorUri,
             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/dist/cjs/node/httpCacheControl.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoveryCacheControl = discoveryCacheControl;
+/** Shared discovery config validation; zero forbids downstream response retention. */
+function discoveryCacheControl(value, defaultSeconds) {
+    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/dist/cjs/node/index.js

@@ -18,7 +18,7 @@
  * actor + inbox + follow-graph Express routers.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createActorRouter = exports.createWebfingerRouter = exports.ActorResolutionPendingError = exports.createInboundDispatcher = exports.createDeliveryService = exports.ActorResolver = exports.createActorResolver = exports.createIdentityBridge = exports.createTcoLinkExpander = exports.createSignedFetch = void 0;
+exports.createActorRouter = exports.createWebfingerRouter = exports.ActorResolutionPendingError = exports.createInboundDispatcher = exports.DeliveryAuthorizationDeniedError = exports.createDeliveryService = exports.ActorResolver = exports.createActorResolver = exports.createIdentityBridge = exports.createTcoLinkExpander = exports.createSignedFetch = void 0;
 var signedFetch_1 = require("./signedFetch");
 Object.defineProperty(exports, "createSignedFetch", { enumerable: true, get: function () { return signedFetch_1.createSignedFetch; } });
 /**
@@ -49,6 +49,7 @@ Object.defineProperty(exports, "ActorResolver", { enumerable: true, get: functio
  */
 var delivery_1 = require("./delivery");
 Object.defineProperty(exports, "createDeliveryService", { enumerable: true, get: function () { return delivery_1.createDeliveryService; } });
+Object.defineProperty(exports, "DeliveryAuthorizationDeniedError", { enumerable: true, get: function () { return delivery_1.DeliveryAuthorizationDeniedError; } });
 /**
  * Inbound ActivityPub dispatch — the untrusted-activity validator + switch, the
  * follow-protocol handlers (Follow / Accept / Undo(Follow) / Reject) over the

package/dist/cjs/node/webfingerRouter.js

@@ -15,9 +15,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWebfingerRouter = createWebfingerRouter;
 const express_1 = require("express");
+const httpCacheControl_1 = require("./httpCacheControl");
 const apUri_1 = require("../apUri");
 const urls_1 = require("../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}`;
@@ -25,6 +26,7 @@ const HOST_META_CACHE_CONTROL = `max-age=${60 * 60 * 24}`;
 function createWebfingerRouter(config) {
     const router = (0, express_1.Router)();
     const { domain } = config;
+    const httpCacheControl = (0, httpCacheControl_1.discoveryCacheControl)(config.httpCacheTtlSeconds, WEBFINGER_CACHE_TTL);
     const webfingerTemplate = `https://${domain}/.well-known/webfinger?resource={uri}`;
     router.get('/webfinger', async (req, res) => {
         if (!config.federationEnabled) {
@@ -77,14 +79,14 @@ function createWebfingerRouter(config) {
                     ],
                 };
                 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);
             }
             // Check the JRD cache first.
             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);
             }
             const user = await config.resolveUser(username);
@@ -125,7 +127,7 @@ function createWebfingerRouter(config) {
             };
             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) {

package/dist/esm/node/actorRouter.js

@@ -20,6 +20,7 @@
  */
 import { Router } from 'express';
 import { AP_CONTEXT } from '../apContext.js';
+import { discoveryCacheControl } from './httpCacheControl.js';
 import { verifyHttpSignature } from '../httpSignature.js';
 import { INSTANCE_ACTOR_USERNAME, normalizeActorUsername } from '../urls.js';
 /** Page size for the paginated followers/following collections (mirrors the outbox). */
@@ -54,6 +55,7 @@ function parseFollowOffset(raw) {
 export function createActorRouter(config) {
     const router = Router();
     const { urls, domain, apContentType, logger } = config;
+    const httpCacheControl = discoveryCacheControl(config.httpCacheTtlSeconds, 1800);
     function wantsActivityPub(req) {
         return config.wantsActivityPub(req.headers.accept);
     }
@@ -239,7 +241,7 @@ export function createActorRouter(config) {
                     },
                 };
                 res.set('Content-Type', apContentType);
-                res.set('Cache-Control', 'max-age=1800');
+                res.set('Cache-Control', httpCacheControl);
                 return res.json(actorObject);
             }
             const user = await config.resolveUser(username);
@@ -274,7 +276,7 @@ export function createActorRouter(config) {
                 alsoKnownAs: user.alsoKnownAs,
             });
             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) {

package/dist/esm/node/delivery.js

@@ -31,6 +31,14 @@ const DELIVER_ACTIVITY_TIMEOUT_MS = 15000;
 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';
+/** A definitive refusal: workers must discard, not retry or count a delivery. */
+export class DeliveryAuthorizationDeniedError extends Error {
+    constructor() {
+        super('Outbound federation delivery is not authorized');
+        this.code = 'DELIVERY_AUTHORIZATION_DENIED';
+        this.name = 'DeliveryAuthorizationDeniedError';
+    }
+}
 /** Read a bounded prefix of a failed-delivery response body for the debug log. */
 async function readResponsePreview(response) {
     const chunks = [];
@@ -69,7 +77,17 @@ export function createDeliveryService(config) {
         const host = urlHost(url);
         return host === null || config.isBlockedDomain(host);
     }
+    async function authorizeDelivery(activity, senderAccountId) {
+        if (config.authorizeDelivery &&
+            !(await config.authorizeDelivery({ activity, senderAccountId }))) {
+            throw new DeliveryAuthorizationDeniedError();
+        }
+    }
     async function deliverActivity(activity, targetInbox, senderOxyUserId, senderUsername) {
+        await authorizeDelivery(activity, senderOxyUserId);
+        return deliverAuthorizedActivity(activity, targetInbox, senderUsername);
+    }
+    async function deliverAuthorizedActivity(activity, targetInbox, senderUsername) {
         if (isBlockedUrl(targetInbox)) {
             logger.warn(`[FedDeliver] refusing outbound delivery to blocked inbox ${targetInbox}`);
             return false;
@@ -107,6 +125,7 @@ export function createDeliveryService(config) {
         }
     }
     async function queueDelivery(activity, targetInbox, senderOxyUserId) {
+        await authorizeDelivery(activity, senderOxyUserId);
         if (isBlockedUrl(targetInbox)) {
             logger.warn(`[FedDeliver] not queueing delivery to blocked inbox ${targetInbox}`);
             return;
@@ -144,6 +163,7 @@ export function createDeliveryService(config) {
         return actor.sharedInboxUrl ?? actor.inboxUrl ?? undefined;
     }
     async function deliverToFollowers(activity, senderOxyUserId, senderUsername, options = {}) {
+        await authorizeDelivery(activity, senderOxyUserId);
         const actorUris = await config.follows.listAcceptedInboundFollowerActorUris(senderOxyUserId);
         const actors = actorUris.length > 0 ? await config.store.findActorInboxesByUris(actorUris) : [];
         // Group by shared inbox to avoid duplicate deliveries. Follower inboxes
@@ -238,17 +258,12 @@ export function createDeliveryService(config) {
         // cached; if the actor is unknown locally we still record the follow and
         // 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
         // activity ID is deterministic across retries before the actor is cached.
         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 = {
             '@context': 'https://www.w3.org/ns/activitystreams',
             id: activityId,
@@ -256,11 +271,16 @@ export function createDeliveryService(config) {
             actor: localActorUri,
             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/dist/esm/node/httpCacheControl.js

@@ -0,0 +1,8 @@
+/** Shared discovery config validation; zero forbids downstream response retention. */
+export function discoveryCacheControl(value, defaultSeconds) {
+    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/dist/esm/node/index.js

@@ -39,7 +39,7 @@ export { createActorResolver, ActorResolver, } from './actorResolver.js';
  * Accept(Follow)) + the `Update(Person)` actor rebroadcast, over injected key
  * custody, an SSRF-safe delivery transport, and bring-your-own-store adapters.
  */
-export { createDeliveryService, } from './delivery.js';
+export { createDeliveryService, DeliveryAuthorizationDeniedError, } from './delivery.js';
 /**
  * Inbound ActivityPub dispatch — the untrusted-activity validator + switch, the
  * follow-protocol handlers (Follow / Accept / Undo(Follow) / Reject) over the

package/dist/esm/node/webfingerRouter.js

@@ -12,9 +12,10 @@
  * Extracted behaviour-identically from Mention's `wellKnown.routes.ts`.
  */
 import { Router } from 'express';
+import { discoveryCacheControl } from './httpCacheControl.js';
 import { isSameFederationHost } from '../apUri.js';
 import { INSTANCE_ACTOR_USERNAME, normalizeActorUsername } from '../urls.js';
-/** 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}`;
@@ -22,6 +23,7 @@ const HOST_META_CACHE_CONTROL = `max-age=${60 * 60 * 24}`;
 export function createWebfingerRouter(config) {
     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, res) => {
         if (!config.federationEnabled) {
@@ -74,14 +76,14 @@ export function createWebfingerRouter(config) {
                     ],
                 };
                 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);
             }
             // Check the JRD cache first.
             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);
             }
             const user = await config.resolveUser(username);
@@ -122,7 +124,7 @@ export function createWebfingerRouter(config) {
             };
             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) {

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.1",
   "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",
@@ -45,6 +45,7 @@
   "files": [
     "NOTICE",
     "dist",
+    "!dist/**/*.tsbuildinfo",
     "src"
   ],
   "keywords": [
@@ -57,7 +58,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/OxyHQ/OxyHQServices",
+    "url": "git+https://github.com/OxyHQ/oxy.git",
     "directory": "packages/federation"
   },
   "author": "OxyHQ",
@@ -75,26 +76,11 @@
     "typescript": "tsc --noEmit",
     "test": "jest --passWithNoTests",
     "lint": "biome lint --error-on-warnings ./src",
-    "prepublishOnly": "node ../../scripts/assert-bun-publish.mjs && bun run clean && bun run build",
-    "release": "rm -rf dist && bun run build && release-it"
-  },
-  "release-it": {
-    "git": {
-      "tagName": "@oxy.so/federation@${version}",
-      "tagAnnotation": "Release @oxy.so/federation@${version}",
-      "commitMessage": "chore(federation): release @oxy.so/federation@${version}"
-    },
-    "github": {
-      "release": true,
-      "releaseName": "@oxy.so/federation@${version}"
-    },
-    "npm": {
-      "publish": true
-    }
+    "prepublishOnly": "node ../../scripts/assert-bun-publish.mjs && bun run clean && bun run build"
   },
   "dependencies": {
     "@oxy.so/contracts": "^1.0.0 || ^2.0.0 || ^3.0.0 || ^4.0.0 || 4.11.0-oxy-one.0",
-    "@oxy.so/core": "^1.0.0 || ^2.0.0 || ^3.0.0 || ^4.0.0"
+    "@oxy.so/core": "^1.0.0 || ^2.0.0 || ^3.0.0 || ^4.0.0 || ^5.0.0"
   },
   "peerDependencies": {
     "express": "^4.18.0 || ^5.0.0"
@@ -110,7 +96,6 @@
     "@types/node": "^22.20.1",
     "express": "^4.22.2",
     "jest": "^30.5.1",
-    "release-it": "^19.0.6",
     "supertest": "^7.0.0",
     "ts-jest": "^29.4.12",
     "typescript": "^5.9.2"