@fedify/fedify 2.4.0-dev.1490 → 2.4.0-dev.1504

package/dist/testing/mod.d.mts

@@ -2,11 +2,12 @@ import { Temporal } from "@js-temporal/polyfill";
 import { URLPattern } from "urlpattern-polyfill";
 import { ExportResultCode } from "@opentelemetry/core";
 import { Router } from "@fedify/uri-template";
-import { Activity, Actor, Collection, CryptographicKey, Hashtag, Link, LookupObjectOptions, Multikey, Object as Object$1, Recipient, Tombstone, TraverseCollectionOptions } from "@fedify/vocab";
+import { Activity, Actor, Collection, CryptographicKey, Hashtag, Link, LookupObjectOptions, Multikey, Note, Object as Object$1, Recipient, Tombstone, TraverseCollectionOptions } from "@fedify/vocab";
 import { Link as Link$1, LookupWebFingerOptions, ResourceDescriptor } from "@fedify/webfinger";
 import { MeterProvider, TracerProvider } from "@opentelemetry/api";
-import { DocumentLoader, GetUserAgentOptions } from "@fedify/vocab-runtime";
+import { AuthenticatedDocumentLoaderFactory, DocumentLoader, DocumentLoaderFactory, GetUserAgentOptions } from "@fedify/vocab-runtime";
 import { MeterProvider as MeterProvider$1, MetricReader } from "@opentelemetry/sdk-metrics";
+import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region src/nodeinfo/types.d.ts
 /**
@@ -202,7 +203,29 @@ interface GetKeyOwnerOptions {
   tracerProvider?: TracerProvider;
 }
 //#endregion
+//#region src/compat/types.d.ts
+/**
+ * A function that transforms an activity object.
+ * @since 1.4.0
+ */
+type ActivityTransformer<TContextData> = (activity: Activity, context: Context<TContextData>) => Activity;
+//#endregion
 //#region src/sig/http.d.ts
+/**
+ * The standard to use for signing and verifying HTTP signatures.
+ * @since 1.6.0
+ */
+type HttpMessageSignaturesSpec =
+/**
+ * The Signing HTTP Messages (draft-cavage-http-signatures-12) specification,
+ * which is widely adopted and used in the fediverse (as of May 2025).
+ */
+"draft-cavage-http-signatures-12"
+/**
+ * The HTTP Message Signatures (RFC 9421) specification, which is the
+ * finalized standard but not widely adopted yet (as of May 2025).
+ */
+| "rfc9421";
 /**
  * The reason why {@link verifyRequestDetailed} could not verify a request.
  * @since 2.1.0
@@ -471,6 +494,15 @@ type SharedInboxKeyDispatcher<TContextData> = (context: Context<TContextData>) =
 } | {
   username: string;
 } | null>;
+/**
+ * A callback that handles errors during outbox processing.
+ *
+ * @param error The error that occurred.
+ * @param activity The activity that caused the error.  If it is `null`, the
+ *                 error occurred during deserializing the activity.
+ * @since 0.6.0
+ */
+type OutboxErrorHandler = (error: Error, activity: Activity | null) => void | Promise<void>;
 /**
  * A callback that handles permanent delivery failures when sending activities
  * to remote inboxes.
@@ -580,6 +612,472 @@ type CustomCollectionCounter<TParam extends string, TContextData> = (context: Re
  */
 type CustomCollectionCursor<TParam extends string, TContext extends Context<TContextData>, TContextData> = (context: TContext, values: Record<TParam, string>) => string | null | Promise<string | null>;
 //#endregion
+//#region src/federation/kv.d.ts
+/**
+ * A key for a key–value store.  An array of one or more strings.
+ *
+ * @since 0.5.0
+ */
+type KvKey = readonly [string] | readonly [string, ...string[]];
+/**
+ * Additional options for setting a value in a key–value store.
+ *
+ * @since 0.5.0
+ */
+interface KvStoreSetOptions {
+  /**
+   * The time-to-live (TTL) for the value.
+   */
+  ttl?: Temporal.Duration;
+}
+/**
+ * An entry returned by the {@link KvStore.list} method.
+ *
+ * @since 1.10.0
+ */
+interface KvStoreListEntry {
+  /**
+   * The key of the entry.
+   */
+  readonly key: KvKey;
+  /**
+   * The value of the entry.
+   */
+  readonly value: unknown;
+}
+/**
+ * An abstract interface for a key–value store.
+ *
+ * @since 0.5.0
+ */
+interface KvStore {
+  /**
+   * Gets the value for the given key.
+   * @param key The key to get the value for.
+   * @returns The value for the key, or `undefined` if the key does not exist.
+   * @template T The type of the value to get.
+   */
+  get<T = unknown>(key: KvKey): Promise<T | undefined>;
+  /**
+   * Sets the value for the given key.
+   * @param key The key to set the value for.
+   * @param value The value to set.
+   * @param options Additional options for setting the value.
+   */
+  set(key: KvKey, value: unknown, options?: KvStoreSetOptions): Promise<void>;
+  /**
+   * Deletes the value for the given key.
+   * @param key The key to delete.
+   */
+  delete(key: KvKey): Promise<void>;
+  /**
+   * Compare-and-swap (CAS) operation for the key–value store.
+   * @param key The key to perform the CAS operation on.
+   * @param expectedValue The expected value for the key.
+   * @param newValue The new value to set if the expected value matches.
+   * @param options Additional options for setting the value.
+   * @return `true` if the CAS operation was successful, `false` otherwise.
+   * @since 1.8.0
+   */
+  cas?: (key: KvKey, expectedValue: unknown, newValue: unknown, options?: KvStoreSetOptions) => Promise<boolean>;
+  /**
+   * Lists all entries in the store that match the given prefix.
+   * If no prefix is given, all entries are returned.
+   * @param prefix The prefix to filter keys by.  If not specified, all entries
+   *               are returned.
+   * @returns An async iterable of entries matching the prefix.
+   * @since 1.10.0
+   * @since 2.0.0 This method is now required instead of optional.
+   */
+  list(prefix?: KvKey): AsyncIterable<KvStoreListEntry>;
+}
+//#endregion
+//#region src/federation/circuit-breaker.d.ts
+/**
+ * The state of a remote host circuit breaker.
+ * @since 2.3.0
+ */
+type CircuitBreakerState = "closed" | "open" | "half-open";
+/**
+ * Details passed to {@link CircuitBreakerOptions.onActivityDrop} when a held
+ * activity expires before the remote host recovers.
+ * @since 2.3.0
+ */
+interface CircuitBreakerActivityDrop {
+  /** The inbox URL that would have received the activity. */
+  readonly inbox: URL;
+  /** The activity that was dropped. */
+  readonly activity: Activity;
+  /** The activity ID, when known. */
+  readonly activityId?: string;
+  /** The activity type. */
+  readonly activityType: string;
+  /** The actor IDs represented by this inbox. */
+  readonly actorIds: readonly URL[];
+  /** The time when Fedify first held this activity. */
+  readonly heldSince: Temporal.Instant;
+}
+/**
+ * Configures how a remote host circuit opens after repeated delivery
+ * failures.
+ * @since 2.3.0
+ */
+type CircuitBreakerFailurePolicy = {
+  failure(timestamps: readonly Temporal.Instant[]): boolean;
+  readonly failureThreshold?: never;
+  readonly failureWindow?: never;
+} | {
+  readonly failure?: never;
+  readonly failureThreshold?: number;
+  readonly failureWindow?: Temporal.Duration | Temporal.DurationLike;
+};
+/**
+ * Options for Fedify's outbound activity circuit breaker.
+ * @since 2.3.0
+ */
+type CircuitBreakerOptions = CircuitBreakerFailurePolicy & {
+  /**
+   * How long an open circuit waits before allowing a half-open recovery probe.
+   * @default `{ minutes: 30 }`
+   */
+  readonly recoveryDelay?: Temporal.Duration | Temporal.DurationLike;
+  /**
+   * How long Fedify keeps requeueing activities held by an open circuit before
+   * dropping them.
+   * @default `{ days: 7 }`
+   */
+  readonly heldActivityTtl?: Temporal.Duration | Temporal.DurationLike;
+  /**
+   * How often other held activities retry while a half-open probe is in
+   * flight.  The probe is treated as stale after the recovery delay.
+   * @default `{ seconds: 1 }`
+   */
+  readonly releaseInterval?: Temporal.Duration | Temporal.DurationLike;
+  /**
+   * Called whenever the circuit state changes.
+   */
+  readonly onStateChange?: (remoteHost: string, previousState: CircuitBreakerState, newState: CircuitBreakerState) => void | Promise<void>;
+  /**
+   * Called when an activity held by the circuit breaker expires.
+   */
+  readonly onActivityDrop?: (remoteHost: string, details: CircuitBreakerActivityDrop) => void | Promise<void>;
+};
+//#endregion
+//#region src/federation/mq.d.ts
+/**
+ * Additional options for enqueuing a message in a queue.
+ *
+ * @since 0.5.0
+ */
+interface MessageQueueEnqueueOptions {
+  /**
+   * The delay before the message is enqueued.  No delay by default.
+   *
+   * It must not be negative.
+   */
+  readonly delay?: Temporal.Duration;
+  /**
+   * An optional key that ensures messages with the same ordering key are
+   * processed sequentially (one at a time).  Messages with different ordering
+   * keys (or no ordering key) may be processed in parallel.
+   *
+   * This is useful for ensuring that related messages are processed in order,
+   * such as ensuring that a `Delete` activity is processed after a `Create`
+   * activity for the same object.
+   *
+   * @since 2.0.0
+   */
+  readonly orderingKey?: string;
+  /**
+   * An optional key requesting at-most-once enqueue semantics for messages
+   * that share it.  A backend that declares
+   * {@link MessageQueue.nativeDeduplication} `true` owns the check: a message
+   * whose `deduplicationKey` was already seen within the backend's
+   * deduplication window is dropped instead of enqueued.  Backends without
+   * native deduplication ignore this field; Fedify performs its own
+   * best-effort deduplication before reaching them on the paths that support
+   * it.
+   *
+   * @since 2.4.0
+   */
+  readonly deduplicationKey?: string;
+}
+/**
+ * Additional options for listening to a message queue.
+ *
+ * @since 1.0.0
+ */
+interface MessageQueueListenOptions {
+  /**
+   * The signal to abort listening to the message queue.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * The number of messages waiting in a message queue.
+ *
+ * @since 2.3.0
+ */
+interface MessageQueueDepth {
+  /**
+   * The total number of messages still waiting in the backend queue.
+   *
+   * This does not include messages that have already been handed to a worker
+   * for processing.
+   */
+  readonly queued: number;
+  /**
+   * The number of queued messages eligible for immediate processing.
+   *
+   * Queue backends that cannot cheaply distinguish ready and delayed messages
+   * may omit this field.
+   */
+  readonly ready?: number;
+  /**
+   * The number of queued messages scheduled for later delivery.
+   *
+   * Queue backends that cannot cheaply distinguish ready and delayed messages
+   * may omit this field.
+   */
+  readonly delayed?: number;
+}
+/**
+ * An abstract interface for a message queue.
+ *
+ * @since 0.5.0
+ */
+interface MessageQueue {
+  /**
+   * Whether the message queue backend provides native retry mechanisms.
+   * When `true`, Fedify will skip its own retry logic and rely on the backend
+   * to handle retries. When `false` or omitted, Fedify will handle retries
+   * using its own retry policies.
+   *
+   * @default `false`
+   * @since 1.7.0
+   */
+  readonly nativeRetrial?: boolean;
+  /**
+   * Whether the message queue backend deduplicates messages that share a
+   * {@link MessageQueueEnqueueOptions.deduplicationKey} natively.  When `true`,
+   * Fedify forwards the `deduplicationKey` and relies on the backend to drop
+   * duplicates; when `false` or omitted, Fedify applies its own best-effort
+   * key–value deduplication on the paths that request it.
+   *
+   * @default `false`
+   * @since 2.4.0
+   */
+  readonly nativeDeduplication?: boolean;
+  /**
+   * Enqueues a message in the queue.
+   * @param message The message to enqueue.
+   * @param options Additional options for enqueuing the message.
+   */
+  enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
+  /**
+   * Enqueues multiple messages in the queue.  This operation is optional,
+   * and may not be supported by all implementations.  If not supported,
+   * Fedify will invoke {@link enqueue} for each message.
+   *
+   * @param messages The messages to enqueue.
+   * @param options Additional options for enqueuing the messages.
+   */
+  enqueueMany?: (messages: readonly any[], options?: MessageQueueEnqueueOptions) => Promise<void>;
+  /**
+   * Listens for messages in the queue.
+   * @param handler The handler for messages in the queue.
+   * @param options Additional options for listening to the message queue.
+   * @returns A promise that resolves when the listening is done.  It never
+   *          rejects, and is resolved when the signal is aborted.  If no
+   *          signal is provided, it never resolves.
+   */
+  listen(handler: (message: any) => Promise<void> | void, options?: MessageQueueListenOptions): Promise<void>;
+  /**
+   * Gets the number of messages waiting in the queue.
+   *
+   * This operation is optional, and may not be supported by all
+   * implementations.  The returned counts exclude messages currently being
+   * handled by a worker.
+   *
+   * @since 2.3.0
+   */
+  getDepth?(): Promise<MessageQueueDepth>;
+}
+//#endregion
+//#region src/federation/retry.d.ts
+/**
+ * The context passed to a {@link RetryPolicy} callback.
+ * @since 0.12.0
+ */
+interface RetryContext {
+  /**
+   * The elapsed time since the first attempt.
+   */
+  readonly elapsedTime: Temporal.Duration;
+  /**
+   * The number of attempts so far.
+   */
+  readonly attempts: number;
+}
+/**
+ * A policy that determines the delay before the next retry.
+ * @param context The retry context.
+ * @returns The delay before the next retry, or `null` to stop retrying.
+ *          It must not negative.
+ * @since 0.12.0
+ */
+type RetryPolicy = (context: RetryContext) => Temporal.Duration | null;
+//#endregion
+//#region src/federation/tasks/task.d.ts
+/**
+ * A callback that processes a custom background task.
+ * @template TContextData The context data to pass to the {@link Context}.
+ * @template TData The type of the task payload, inferred from the task's
+ *                 schema.
+ * @param ctx The context for the worker processing the task.
+ * @param data The decoded and validated task payload.
+ * @since 2.4.0
+ */
+type TaskHandler<TContextData, TData> = (ctx: Context<TContextData>, data: TData) => Promise<void> | void;
+/**
+ * Options for {@link TaskRegistry.defineTask}.
+ * @template TContextData The context data to pass to the {@link Context}.
+ * @template TSchema The [Standard Schema](https://standardschema.dev/) that
+ *                   validates the task payload.
+ * @since 2.4.0
+ */
+interface TaskDefinitionOptions<TContextData, TSchema extends StandardSchemaV1> {
+  /**
+   * The [Standard Schema](https://standardschema.dev/) that validates the
+   * task payload.  The payload type is inferred from this schema.
+   *
+   * The payload is validated twice: once at enqueue time (fail fast) and
+   * once at dequeue time (drift protection against payloads enqueued by an
+   * older deployment).  Because the same schema runs on both sides, its
+   * validation must be idempotent: the validated output must itself be
+   * a valid input.  Transforming schemas (e.g., Zod's `.transform()`) whose
+   * output differs in shape from their input are not supported.
+   */
+  readonly schema: TSchema;
+  /**
+   * The callback that processes the task on a background worker.
+   */
+  readonly handler: TaskHandler<TContextData, StandardSchemaV1.InferOutput<TSchema>>;
+  /**
+   * The retry policy for this task.  If omitted, the federation-wide
+   * task retry policy is used, which defaults to an exponential backoff
+   * policy.
+   */
+  readonly retryPolicy?: RetryPolicy;
+  /**
+   * A callback invoked when the {@link handler} throws an error, before
+   * a retry is scheduled.
+   * @param ctx The context for the worker processing the task.
+   * @param error The error thrown by the handler.
+   * @param data The decoded and validated task payload.
+   */
+  readonly onError?: (ctx: Context<TContextData>, error: unknown, data: StandardSchemaV1.InferOutput<TSchema>) => Promise<void> | void;
+  /**
+   * The message queue dedicated to this task.  If omitted, the task is
+   * routed to the federation-wide task queue, falling back to the outbox
+   * queue (unless `taskQueueResolution: "strict"` is configured).
+   */
+  readonly queue?: MessageQueue;
+}
+/**
+ * Phantom key binding a {@link TaskDefinition} to its federation's context
+ * data type.  Declared only—no value exists at runtime, and the symbol is
+ * not exported, so the marker stays out of user-facing completions.
+ */
+declare const contextDataBrand: unique symbol;
+/**
+ * The handle returned by {@link TaskRegistry.defineTask}.  It carries the
+ * task name and schema so that {@link Context.enqueueTask} can validate the
+ * payload and infer its type at every call site.
+ * @template TContextData The context data to pass to the {@link Context}.
+ * @template TData The type of the task payload, inferred from the task's
+ *                 schema.
+ * @since 2.4.0
+ */
+interface TaskDefinition<TContextData, TData> {
+  /**
+   * The unique name of the task.
+   */
+  readonly name: string;
+  /**
+   * The [Standard Schema](https://standardschema.dev/) that validates the
+   * task payload.
+   */
+  readonly schema: StandardSchemaV1<unknown, TData>;
+  /**
+   * @internal Phantom marker binding the handle to its federation.
+   */
+  readonly [contextDataBrand]?: TContextData;
+}
+/**
+ * Registration of custom background tasks.  Both {@link Federation} and
+ * {@link FederationBuilder} implement this interface.
+ * @template TContextData The context data to pass to the {@link Context}.
+ * @since 2.4.0
+ */
+interface TaskRegistry<TContextData> {
+  /**
+   * Defines a custom background task.  The returned handle is passed to
+   * {@link Context.enqueueTask} to enqueue the task.
+   *
+   * @example
+   * ``` typescript
+   * const sendDigest = federation.defineTask("sendDigest", {
+   *   schema: digestSchema,
+   *   handler: async (ctx, data) => {
+   *     // …process the payload on a background worker…
+   *   },
+   * });
+   * ```
+   *
+   * @param name The unique name of the task.
+   * @param options The task definition options.  The payload type is
+   *                inferred from `options.schema`.
+   * @returns The handle to pass to {@link Context.enqueueTask}.
+   * @throws {TypeError} If a task with the same name is already defined.
+   */
+  defineTask<TSchema extends StandardSchemaV1>(name: string, options: TaskDefinitionOptions<TContextData, TSchema>): TaskDefinition<TContextData, StandardSchemaV1.InferOutput<TSchema>>;
+}
+/**
+ * Options for {@link Context.enqueueTask} and {@link Context.enqueueTaskMany}.
+ * @since 2.4.0
+ */
+interface TaskEnqueueOptions {
+  /**
+   * The delay before the task is processed.  No delay by default.
+   */
+  readonly delay?: Temporal.DurationLike;
+  /**
+   * An optional key that ensures tasks with the same ordering key are
+   * processed sequentially (one at a time).
+   */
+  readonly orderingKey?: string;
+  /**
+   * An optional key requesting at-most-once enqueue for tasks that share it.
+   *
+   * A queue with {@link MessageQueue.nativeDeduplication} `true` enforces it
+   * strictly; otherwise deduplication is best-effort via {@link KvStore.cas},
+   * and {@link FederationOptions.taskDeduplicationFallback} decides whether a
+   * missing `cas` proceeds without deduplication or throws.
+   *
+   * For {@link Context.enqueueTaskMany}, one key governs the whole batch.  When
+   * deduplication is actually applied—a native queue, or the key–value
+   * fallback through {@link KvStore.cas}—a multi-item batch with a
+   * `deduplicationKey` requires the queue to implement
+   * {@link MessageQueue.enqueueMany} so it enqueues atomically, or the call
+   * throws a `TypeError`.  Under the `"open"` fallback with no `cas`, no marker
+   * is taken, so such a batch instead fans out without deduplication.
+   *
+   * @since 2.4.0
+   */
+  readonly deduplicationKey?: string;
+}
+//#endregion
 //#region src/federation/queue.d.ts
 interface SenderKeyJwkPair {
   readonly keyId: string;
@@ -594,7 +1092,7 @@ interface SenderKeyJwkPair {
  * type.
  * @since 1.6.0
  */
-type Message = FanoutMessage | OutboxMessage | InboxMessage;
+type Message = FanoutMessage | OutboxMessage | InboxMessage | TaskMessage;
 interface FanoutMessage {
   readonly type: "fanout";
   readonly id: ReturnType<typeof crypto.randomUUID>;
@@ -648,6 +1146,24 @@ interface OutboxMessage {
   readonly circuitHeldSince?: string;
   readonly traceContext: Readonly<Record<string, string>>;
 }
+/**
+ * A message that carries a custom background task.  Every field is
+ * a string, number, or plain record so that the message survives both
+ * JSON serialization and structured clone on every queue backend.
+ * @since 2.4.0
+ */
+interface TaskMessage {
+  readonly type: "task";
+  readonly id: ReturnType<typeof crypto.randomUUID>;
+  readonly baseUrl: string;
+  readonly taskName: string;
+  /** devalue-encoded task data; vocab objects bridged to expanded JSON-LD. */
+  readonly data: string;
+  readonly started: string;
+  readonly attempt: number;
+  readonly orderingKey?: string;
+  readonly traceContext: Readonly<Record<string, string>>;
+}
 interface InboxMessage {
   readonly type: "inbox";
   readonly id: ReturnType<typeof crypto.randomUUID>;
@@ -695,6 +1211,107 @@ interface InboxMessage {
   readonly traceContext: Readonly<Record<string, string>>;
 }
 //#endregion
+//#region src/federation/middleware.d.ts
+/**
+ * Configures the task queues for sending and receiving activities.
+ * @since 1.3.0
+ */
+interface FederationQueueOptions {
+  /**
+   * The message queue for incoming activities.  If not provided, incoming
+   * activities will not be queued and will be processed immediately.
+   */
+  readonly inbox?: MessageQueue;
+  /**
+   * The message queue for outgoing activities.  If not provided, outgoing
+   * activities will not be queued and will be sent immediately.
+   */
+  readonly outbox?: MessageQueue;
+  /**
+   * The message queue for fanning out outgoing activities.  If not provided,
+   * outgoing activities will not be fanned out in the background, but will be
+   * fanned out immediately, which causes slow response times on
+   * {@link Context.sendActivity} calls.
+   */
+  readonly fanout?: MessageQueue;
+  /**
+   * The message queue for custom background tasks.  If not provided,
+   * tasks are routed to the outbox queue (unless
+   * {@link FederationOptions.taskQueueResolution} is `"strict"`).
+   * @since 2.4.0
+   */
+  readonly task?: MessageQueue;
+}
+/**
+ * Prefixes for namespacing keys in the Deno KV store.
+ */
+interface FederationKvPrefixes {
+  /**
+   * The key prefix used for storing whether activities have already been
+   * processed or not.
+   * @default `["_fedify", "activityIdempotence"]`
+   */
+  readonly activityIdempotence: KvKey;
+  /**
+   * The key prefix used for storing remote JSON-LD documents.
+   * @default `["_fedify", "remoteDocument"]`
+   */
+  readonly remoteDocument: KvKey;
+  /**
+   * The key prefix used for caching public keys.
+   * @default `["_fedify", "publicKey"]`
+   * @since 0.12.0
+   */
+  readonly publicKey: KvKey;
+  /**
+   * The key prefix used for caching HTTP Message Signatures specs.
+   * The cached spec is used to reduce the number of requests to make signed
+   * requests ("double-knocking" technique).
+   * @default `["_fedify", "httpMessageSignaturesSpec"]`
+   * @since 1.6.0
+   */
+  readonly httpMessageSignaturesSpec: KvKey;
+  /**
+   * The key prefix used for storing `Accept-Signature` challenge nonces.
+   * Only used when {@link InboxChallengePolicy.requestNonce} is `true`.
+   * @default `["_fedify", "acceptSignatureNonce"]`
+   * @since 2.1.0
+   */
+  readonly acceptSignatureNonce: KvKey;
+  /**
+   * The key prefix used for storing outbound delivery circuit breaker state.
+   * @default `["_fedify", "circuit"]`
+   * @since 2.3.0
+   */
+  readonly circuitBreaker: KvKey;
+  /**
+   * The key prefix used for storing custom background task deduplication
+   * markers.  Kept separate from {@link activityIdempotence} so the two key
+   * spaces never collide.
+   * @default `["_fedify", "taskDeduplication"]`
+   * @since 2.4.0
+   */
+  readonly taskDeduplication: KvKey;
+}
+/**
+ * Options for {@link FederationOptions.origin} when it is not a string.
+ * @since 1.5.0
+ */
+interface FederationOrigin {
+  /**
+   * The canonical hostname for fediverse handles (which are looked up through
+   * WebFinger).  This is used for WebFinger lookups.  It has to be a valid
+   * hostname, e.g., `"example.com"`.
+   */
+  handleHost: string;
+  /**
+   * The canonical origin for web URLs.  This is used for constructing absolute
+   * URLs.  It has to start with either `"http://"` or `"https://"`, and must
+   * not contain a path or query string, e.g., `"https://example.com"`.
+   */
+  webOrigin: string;
+}
+//#endregion
 //#region src/federation/federation.d.ts
 /**
  * Options for {@link Federation.startQueue} method.
@@ -707,18 +1324,18 @@ interface FederationStartQueueOptions {
   signal?: AbortSignal;
   /**
    * Starts the task worker only for the specified queue.  If unspecified,
-   * which is the default, the task worker starts for all three queues:
-   * inbox, outbox, and fanout.
+   * which is the default, the task worker starts for all four queues:
+   * inbox, outbox, fanout, and task.
    * @since 1.3.0
    */
-  queue?: "inbox" | "outbox" | "fanout";
+  queue?: "inbox" | "outbox" | "fanout" | "task";
 }
 /**
  * A common interface between {@link Federation} and {@link FederationBuilder}.
  * @template TContextData The context data to pass to the {@link Context}.
  * @since 1.6.0
  */
-interface Federatable<TContextData> {
+interface Federatable<TContextData> extends TaskRegistry<TContextData> {
   /**
    * Registers a NodeInfo dispatcher.
    * @param path The URI path pattern for the NodeInfo dispatcher.  The syntax
@@ -1164,6 +1781,321 @@ interface Federation<TContextData> extends Federatable<TContextData> {
    */
   fetch(request: Request, options: FederationFetchOptions<TContextData>): Promise<Response>;
 }
+/**
+ * Policy for emitting `Accept-Signature` challenges on inbox `401`
+ * responses, as defined in
+ * [RFC 9421 §5](https://www.rfc-editor.org/rfc/rfc9421#section-5).
+ * @since 2.1.0
+ */
+interface InboxChallengePolicy {
+  /**
+   * Whether to emit `Accept-Signature` headers on `401` responses
+   * caused by HTTP Signature verification failures.
+   */
+  enabled: boolean;
+  /**
+   * The covered component identifiers to request.  Only request-applicable
+   * identifiers should be used (`@status` is automatically excluded).
+   * @default `["@method", "@target-uri", "@authority", "content-digest"]`
+   */
+  components?: string[];
+  /**
+   * Whether to generate and require a one-time nonce for replay protection.
+   * When enabled, a cryptographically random nonce is included in each
+   * challenge and verified on subsequent requests.  Requires a
+   * {@link KvStore}.
+   * @default `false`
+   */
+  requestNonce?: boolean;
+  /**
+   * The time-to-live (in seconds) for stored nonces.  After this period,
+   * nonces expire and are no longer accepted.
+   * @default `300` (5 minutes)
+   */
+  nonceTtlSeconds?: number;
+}
+/**
+ * Options for cooperative benchmark mode.
+ * @since 2.3.0
+ */
+interface FederationBenchmarkOptions {
+  /**
+   * Server-controlled inbox URLs that the benchmark trigger endpoint may
+   * deliver to.
+   */
+  triggerSinks?: readonly (string | URL)[];
+  /**
+   * Whether the benchmark trigger endpoint may deliver to recipients outside
+   * {@link FederationBenchmarkOptions.triggerSinks}.
+   *
+   * Do not enable this option unless the benchmark endpoint is only reachable
+   * by a trusted benchmark controller.
+   */
+  allowUnsafeTriggerRecipients?: boolean;
+}
+/**
+ * Options for creating a {@link Federation} object.
+ * @template TContextData The context data to pass to the {@link Context}.
+ * @since 1.6.0
+ */
+interface FederationOptions<TContextData> {
+  /**
+   * The key–value store used for caching, outbox queues, and inbox idempotence.
+   */
+  kv: KvStore;
+  /**
+   * Prefixes for namespacing keys in the Deno KV store.  By default, all keys
+   * are prefixed with `["_fedify"]`.
+   */
+  kvPrefixes?: Partial<FederationKvPrefixes>;
+  /**
+   * The message queue for sending and receiving activities.  If not provided,
+   * activities will not be queued and will be processed immediately.
+   *
+   * If a `MessageQueue` is provided, both the `inbox` and `outbox` queues
+   * will be set to the same queue.
+   *
+   * If a `FederationQueueOptions` object is provided, you can set the queues
+   * separately (since Fedify 1.3.0).
+   */
+  queue?: FederationQueueOptions | MessageQueue;
+  /**
+   * Whether to start the task queue manually or automatically.
+   *
+   * If `true`, the task queue will not start automatically and you need to
+   * manually start it by calling the {@link Federation.startQueue} method.
+   *
+   * If `false`, the task queue will start automatically as soon as
+   * the first task is enqueued.
+   *
+   * By default, the queue starts automatically.
+   *
+   * @since 0.12.0
+   */
+  manuallyStartQueue?: boolean;
+  /**
+   * The canonical base URL of the server.  This is used for constructing
+   * absolute URLs and fediverse handles.
+   * @since 1.5.0
+   */
+  origin?: string | FederationOrigin;
+  /**
+   * A custom JSON-LD document loader factory.  By default, this uses
+   * the built-in cache-backed loader that fetches remote documents over
+   * HTTP(S).
+   * @since 1.4.0
+   */
+  documentLoaderFactory?: DocumentLoaderFactory;
+  /**
+   * A custom JSON-LD context loader factory.  By default, this uses the same
+   * loader as the document loader.
+   * @since 1.4.0
+   */
+  contextLoaderFactory?: DocumentLoaderFactory;
+  /**
+   * A factory function that creates an authenticated document loader for a
+   * given identity.  This is used for fetching documents that require
+   * authentication.
+   */
+  authenticatedDocumentLoaderFactory?: AuthenticatedDocumentLoaderFactory;
+  /**
+   * Whether to allow fetching private network addresses in the document loader.
+   *
+   * If turned on, {@link FederationOptions.documentLoader},
+   * {@link FederationOptions.contextLoader}, and
+   * {@link FederationOptions.authenticatedDocumentLoaderFactory}
+   * cannot be configured.
+   *
+   * Mostly useful for testing purposes.  *Do not use in production.*
+   *
+   * Turned off by default.
+   * @since 0.15.0
+   */
+  allowPrivateAddress?: boolean;
+  /**
+   * Whether to enable cooperative benchmark mode.  This mode exposes
+   * benchmark-only endpoints and relaxes selected defaults for benchmark
+   * targets.  Pass an object to configure benchmark trigger delivery.
+   * Do not enable this option in production.
+   *
+   * When enabled, {@link FederationOptions.allowPrivateAddress} defaults to
+   * `true` unless {@link FederationOptions.documentLoaderFactory} or
+   * {@link FederationOptions.contextLoaderFactory} is configured, and
+   * {@link FederationOptions.signatureTimeWindow} defaults to `false`.
+   *
+   * Turned off by default.
+   * @since 2.3.0
+   */
+  benchmarkMode?: boolean | FederationBenchmarkOptions;
+  /**
+   * Options for making `User-Agent` strings for HTTP requests.
+   * If a string is provided, it is used as the `User-Agent` header.
+   * If an object is provided, it is passed to the {@link getUserAgent}
+   * function.
+   * @since 1.3.0
+   */
+  userAgent?: GetUserAgentOptions | string;
+  /**
+   * A callback that handles errors during outbox processing.  Note that this
+   * callback can be called multiple times for the same activity, because
+   * the delivery is retried according to the backoff schedule until it
+   * succeeds or reaches the maximum retry count.
+   *
+   * If any errors are thrown in this callback, they are ignored.
+   */
+  onOutboxError?: OutboxErrorHandler;
+  /**
+   * HTTP status codes that should be treated as permanent delivery failures.
+   * When an inbox returns one of these codes, the delivery will not be retried
+   * and the permanent failure handler (if registered via
+   * {@link Federatable.setOutboxPermanentFailureHandler}) will be called.
+   *
+   * By default, `[404, 410]`.
+   *
+   * @since 2.0.0
+   */
+  permanentFailureStatusCodes?: readonly number[];
+  /**
+   * The time window for verifying HTTP Signatures of incoming requests.  If the
+   * request is older or newer than this window, it is rejected.  Or if it is
+   * `false`, the request's timestamp is not checked at all.
+   *
+   * By default, the window is an hour.
+   */
+  signatureTimeWindow?: Temporal.Duration | Temporal.DurationLike | false;
+  /**
+   * Whether to skip HTTP Signatures verification for incoming activities.
+   * This is useful for testing purposes, but should not be used in production.
+   *
+   * By default, this is `false` (i.e., signatures are verified).
+   * @since 0.13.0
+   */
+  skipSignatureVerification?: boolean;
+  /**
+   * The HTTP Signatures specification to use for the first signature
+   * attempt when communicating with unknown servers. This option affects
+   * the "double-knocking" mechanism as described in the ActivityPub HTTP
+   * Signature documentation.
+   *
+   * When making HTTP requests to servers that haven't been encountered before,
+   * Fedify will first attempt to sign the request using the specified
+   * signature specification. If the request fails, it will retry with the
+   * alternative specification.
+   *
+   * Defaults to `"rfc9421"` (HTTP Message Signatures).
+   *
+   * @see {@link https://swicg.github.io/activitypub-http-signature/#how-to-upgrade-supported-versions}
+   * @default `"rfc9421"`
+   * @since 1.7.0
+   */
+  firstKnock?: HttpMessageSignaturesSpec;
+  /**
+   * The policy for emitting `Accept-Signature` challenges on inbox `401`
+   * responses (RFC 9421 §5).  When enabled, failed HTTP Signature
+   * verification responses will include an `Accept-Signature` header
+   * telling the sender which components and parameters to include.
+   *
+   * Disabled by default (no `Accept-Signature` header is emitted).
+   * @since 2.1.0
+   */
+  inboxChallengePolicy?: InboxChallengePolicy;
+  /**
+   * The retry policy for sending activities to recipients' inboxes.
+   * By default, this uses an exponential backoff strategy with a maximum of
+   * 10 attempts and a maximum delay of 12 hours.
+   * @since 0.12.0
+   */
+  outboxRetryPolicy?: RetryPolicy;
+  /**
+   * The circuit breaker for queued outbound activity delivery.  When enabled,
+   * Fedify tracks repeated failures per remote host and temporarily holds
+   * queued activities instead of repeatedly hammering an unreachable server.
+   *
+   * Passing `false` disables the circuit breaker.
+   *
+   * @since 2.3.0
+   */
+  circuitBreaker?: false | CircuitBreakerOptions;
+  /**
+   * The retry policy for processing incoming activities.  By default, this
+   * uses an exponential backoff strategy with a maximum of 10 attempts and a
+   * maximum delay of 12 hours.
+   * @since 0.12.0
+   */
+  inboxRetryPolicy?: RetryPolicy;
+  /**
+   * The retry policy for processing custom background tasks.  By default,
+   * this uses an exponential backoff strategy with a maximum of 10 attempts
+   * and a maximum delay of 12 hours.  A per-task retry policy
+   * ({@link TaskDefinitionOptions.retryPolicy}) overrides this.
+   * @since 2.4.0
+   */
+  taskRetryPolicy?: RetryPolicy;
+  /**
+   * How a queue is resolved for a custom background task when neither
+   * a per-task queue ({@link TaskDefinitionOptions.queue}) nor a dedicated
+   * task queue ({@link FederationQueueOptions.task}) is configured.
+   *
+   * - `"fallback"` (the default): the task is routed to the outbox queue.
+   * - `"strict"`: no fallback; enqueuing the task throws instead of
+   *   silently sharing the outbox queue.
+   * @default `"fallback"`
+   * @since 2.4.0
+   */
+  taskQueueResolution?: "fallback" | "strict";
+  /**
+   * The time-to-live for a {@link TaskEnqueueOptions.deduplicationKey} marker
+   * stored in the key–value deduplication fallback.  A second enqueue with the
+   * same key within this window is skipped; once it expires, the key may
+   * enqueue again.  Ignored when the task's queue declares
+   * {@link MessageQueue.nativeDeduplication} (the backend owns the window).
+   * @default `{ hours: 1 }`
+   * @since 2.4.0
+   */
+  taskDeduplicationTtl?: Temporal.DurationLike;
+  /**
+   * The behavior when a {@link TaskEnqueueOptions.deduplicationKey} is supplied
+   * but the task's queue does not declare
+   * {@link MessageQueue.nativeDeduplication} *and* the configured
+   * {@link KvStore} exposes no `cas` (compare-and-swap) primitive:
+   *
+   * - `"open"` (the default): proceeds without deduplication after logging at
+   *   debug level.
+   * - `"closed"`: rejects with a `TypeError` before enqueuing.
+   *
+   * @default `"open"`
+   * @since 2.4.0
+   */
+  taskDeduplicationFallback?: "open" | "closed";
+  /**
+   * Activity transformers that are applied to outgoing activities.  It is
+   * useful for adjusting outgoing activities to satisfy some ActivityPub
+   * implementations.
+   *
+   * By default, {@link defaultActivityTransformers} are applied.
+   * @since 1.4.0
+   */
+  activityTransformers?: readonly ActivityTransformer<TContextData>[];
+  /**
+   * Whether the router should be insensitive to trailing slashes in the URL
+   * paths.  For example, if this option is `true`, `/foo` and `/foo/` are
+   * treated as the same path.  Turned off by default.
+   * @since 0.12.0
+   */
+  trailingSlashInsensitive?: boolean;
+  /**
+   * The OpenTelemetry tracer provider for tracing operations.  If not provided,
+   * the default global tracer provider is used.
+   * @since 1.3.0
+   */
+  tracerProvider?: TracerProvider;
+  /**
+   * The OpenTelemetry meter provider for recording metrics.  If not provided,
+   * the default global meter provider is used.
+   * @since 2.3.0
+   */
+  meterProvider?: MeterProvider;
+}
 /**
  * Additional settings for the actor dispatcher.
  *
@@ -1887,6 +2819,48 @@ interface Context<TContextData> {
    * @since 1.3.0
    */
   routeActivity(recipient: string | null, activity: Activity, options?: RouteActivityOptions): Promise<boolean>;
+  /**
+   * Enqueues a custom background task.  The payload is validated against
+   * the task's schema, serialized, and processed by the task's handler on
+   * a background worker.
+   *
+   * @example
+   * ``` typescript
+   * await ctx.enqueueTask(sendDigest, { userId: "alice" });
+   * ```
+   *
+   * @template TData The type of the task payload, inferred from the task's
+   *                 schema.
+   * @param task The handle returned by {@link TaskRegistry.defineTask}.
+   * @param data The task payload.  It is validated against the task's
+   *             schema before being enqueued.
+   * @param options Options for enqueuing the task.
+   * @throws {TypeError} If the task is not defined on this federation,
+   *                     if no message queue is configured for tasks, or if
+   *                     the payload fails schema validation.
+   * @since 2.4.0
+   */
+  enqueueTask<TData>(task: TaskDefinition<TContextData, TData>, data: TData, options?: TaskEnqueueOptions): Promise<void>;
+  /**
+   * Enqueues multiple payloads for a custom background task at once.
+   * Uses the queue's bulk enqueue operation when available.  Without
+   * deduplication, it may fall back to parallel single enqueues when the
+   * queue does not implement bulk enqueue.
+   * @template TData The type of the task payload, inferred from the task's
+   *                 schema.
+   * @param task The handle returned by {@link TaskRegistry.defineTask}.
+   * @param payloads The task payloads.  Each is validated against the
+   *                 task's schema before being enqueued.
+   * @param options Options for enqueuing the tasks.
+   * @throws {TypeError} If the task is not defined on this federation,
+   *                     if no message queue is configured for tasks, if
+   *                     a payload fails schema validation, or if a
+   *                     deduplicated multi-item batch cannot be enqueued
+   *                     atomically because the queue does not implement
+   *                     bulk enqueue.
+   * @since 2.4.0
+   */
+  enqueueTaskMany<TData>(task: TaskDefinition<TContextData, TData>, payloads: readonly TData[], options?: TaskEnqueueOptions): Promise<void>;
   /**
    * Builds the URI of a collection of objects with the given name and values.
    * @param name The name of the collection, which can be a string or a symbol.
@@ -2470,9 +3444,64 @@ declare function createOutboxContext<TContextData>(args: Partial<OutboxContext<T
   federation: Federation<TContextData>;
 }): OutboxContext<TContextData>;
 //#endregion
+//#region src/testing/tasks.d.ts
+/** Federation options (sans `queue`) shared by the task suites. */
+declare const baseOptions: Omit<FederationOptions<void>, "queue">;
+/**
+ * Builds a minimal [Standard Schema](https://standardschema.dev/) from a type
+ * guard, for use as a task payload schema in tests.
+ */
+declare const makeSchema: <T>(check: (data: unknown) => data is T) => StandardSchemaV1<unknown, T>;
+declare const stringSchema: StandardSchemaV1<unknown, string>;
+declare const numberSchema: StandardSchemaV1<unknown, number>;
+/** A task payload that carries a vocabulary object, to exercise the codec's
+ * vocab-to-JSON-LD bridging. */
+interface Envelope {
+  note: Note;
+  title: string;
+}
+declare const envelopeSchema: StandardSchemaV1<unknown, Envelope>;
+/**
+ * Options for the {@link MockQueue} constructor.
+ */
+interface MockQueueOptions {
+  /** Sets {@link MessageQueue.nativeRetrial}.  Defaults to `false`. */
+  readonly nativeRetrial?: boolean;
+  /** Sets {@link MessageQueue.nativeDeduplication}.  Defaults to `false`. */
+  readonly nativeDeduplication?: boolean;
+  /**
+   * When `true`, the queue exposes {@link MockQueue.enqueueMany} and records
+   * bulk enqueues; when omitted, the method is absent so callers exercise the
+   * per-message fan-out path.
+   */
+  readonly supportsEnqueueMany?: boolean;
+}
+/**
+ * An in-memory {@link MessageQueue} that records task enqueues for assertions
+ * instead of delivering anything.  Its {@link listen} resolves only when the
+ * abort signal fires.
+ */
+declare class MockQueue implements MessageQueue {
+  readonly nativeRetrial: boolean;
+  readonly nativeDeduplication: boolean;
+  readonly enqueued: {
+    message: TaskMessage;
+    options?: MessageQueueEnqueueOptions;
+  }[];
+  readonly enqueuedMany: {
+    messages: readonly TaskMessage[];
+    options?: MessageQueueEnqueueOptions;
+  }[];
+  listenCount: number;
+  enqueueMany?: (messages: readonly TaskMessage[], options?: MessageQueueEnqueueOptions) => Promise<void>;
+  constructor(options?: MockQueueOptions);
+  enqueue(message: TaskMessage, options?: MessageQueueEnqueueOptions): Promise<void>;
+  listen(_handler: (message: TaskMessage) => Promise<void> | void, options?: MessageQueueListenOptions): Promise<void>;
+}
+//#endregion
 //#region ../fixture/dist/mod.d.ts
 //#endregion
 //#region src/test.d.ts
 declare const testDefinitions: Deno.TestDefinition[];
 //#endregion
-export { createInboxContext, createOutboxContext, createRequestContext, testDefinitions };
+export { type Envelope, MockQueue, type MockQueueOptions, baseOptions, createInboxContext, createOutboxContext, createRequestContext, envelopeSchema, makeSchema, numberSchema, stringSchema, testDefinitions };