import { Temporal } from "@js-temporal/polyfill"; import { URLPattern } from "urlpattern-polyfill"; import { testDefinitions } from "@fedify/fixture"; import { Activity, Actor, Collection, CryptographicKey, Hashtag, Link, LookupObjectOptions, Multikey, Object as Object$1, Recipient, Tombstone, TraverseCollectionOptions } from "@fedify/vocab"; import { Link as Link$1, LookupWebFingerOptions, ResourceDescriptor } from "@fedify/webfinger"; import { TracerProvider } from "@opentelemetry/api"; import { DocumentLoader, GetUserAgentOptions } from "@fedify/vocab-runtime"; //#region src/nodeinfo/types.d.ts /** * The type of the result of parsing JSON. */ type JsonValue = { [key: string]: JsonValue | undefined; } | JsonValue[] | string | number | boolean | null; /** * A NodeInfo object as defined in the NodeInfo 2.1 schema. */ interface NodeInfo { /** * Metadata about server software in use. */ readonly software: Software; /** * The protocols supported on this server. At least one protocol must be * supported. */ readonly protocols: readonly Protocol[]; /** * The third party sites this server can connect to via their application API. */ readonly services?: Services; /** * Whether this server allows open self-registration. Defaults to `false`. */ readonly openRegistrations?: boolean; /** * Usage statistics for this server. */ readonly usage: Usage; /** * Free form key value pairs for software specific values. * Clients should not rely on any specific key present. */ readonly metadata?: Readonly>; } /** * Metadata about server software in use. */ interface Software { /** * The canonical name of this server software. This must comply with * pattern `/^[a-z0-9-]+$/`. */ readonly name: string; /** * The version of this server software. */ readonly version: string; /** * The URL of the source code repository of this server software. */ readonly repository?: URL; /** * The URL of the homepage of this server software. */ readonly homepage?: URL; } /** * The protocols supported on this server. */ type Protocol = "activitypub" | "buddycloud" | "dfrn" | "diaspora" | "libertree" | "ostatus" | "pumpio" | "tent" | "xmpp" | "zot"; /** * The third party sites this server can connect to via their application API. */ interface Services { /** * The third party sites this server can retrieve messages from for combined * display with regular traffic. */ readonly inbound?: readonly InboundService[]; /** * The third party sites this server can publish messages to on the behalf * of a user. */ readonly outbound?: readonly OutboundService[]; } /** * The third party sites this server can retrieve messages from for combined * display with regular traffic. */ type InboundService = "atom1.0" | "gnusocial" | "imap" | "pnut" | "pop3" | "pumpio" | "rss2.0" | "twitter"; /** * The third party sites this server can publish messages to on the behalf * of a user. */ type OutboundService = "atom1.0" | "blogger" | "buddycloud" | "diaspora" | "dreamwidth" | "drupal" | "facebook" | "friendica" | "gnusocial" | "google" | "insanejournal" | "libertree" | "linkedin" | "livejournal" | "mediagoblin" | "myspace" | "pinterest" | "pnut" | "posterous" | "pumpio" | "redmatrix" | "rss2.0" | "smtp" | "tent" | "tumblr" | "twitter" | "wordpress" | "xmpp"; /** * Usage statistics for this server. */ interface Usage { /** * Statistics about the users of this server. */ readonly users: { /** * The total amount of on this server registered users. This number * has to be an integer greater than or equal to zero. */ readonly total?: number; /** * The amount of users that signed in at least once in the last 180 days. * This number has to be an integer greater than or equal to zero. */ readonly activeHalfyear?: number; /** * The amount of users that signed in at least once in the last 30 days. * This number has to be an integer greater than or equal to zero. */ readonly activeMonth?: number; }; /** * The amount of posts that were made by users that are registered on this * server. This number has to be an integer greater than or equal to zero. */ readonly localPosts: number; /** * The amount of comments that were made by users that are registered on this * server. This number has to be an integer greater than or equal to zero. */ readonly localComments: number; } //#endregion //#region src/nodeinfo/client.d.ts /** * Options for {@link getNodeInfo} function. * @since 1.2.0 */ interface GetNodeInfoOptions { /** * Whether to directly fetch the NodeInfo document from the given URL. * Otherwise, the NodeInfo document will be fetched from the `.well-known` * location of the given URL. * * Turned off by default. */ direct?: boolean; /** * How strictly to parse the NodeInfo document. * * - `"strict"`: Parse the NodeInfo document strictly. If the document is * invalid, `undefined` is returned. This is the default. * - `"best-effort"`: Try to parse the NodeInfo document even if it is * invalid. * - `"none"`: Do not parse the NodeInfo document. The function will return * the raw JSON value. */ parse?: "strict" | "best-effort" | "none"; /** * The options for making `User-Agent` header. * If a string is given, it is used as the `User-Agent` header value. * If an object is given, it is passed to {@link getUserAgent} to generate * the `User-Agent` header value. * @since 1.3.0 */ userAgent?: GetUserAgentOptions | string; } //#endregion //#region src/sig/key.d.ts /** * Detailed fetch failure information from {@link fetchKeyDetailed}. * @since 2.1.0 */ type FetchKeyErrorResult = { readonly status: number; readonly response: Response; } | { readonly error: Error; }; //#endregion //#region src/sig/owner.d.ts /** * Options for {@link getKeyOwner}. * @since 0.8.0 */ interface GetKeyOwnerOptions { /** * The document loader to use for fetching the key and its owner. */ documentLoader?: DocumentLoader; /** * The context loader to use for JSON-LD context retrieval. */ contextLoader?: DocumentLoader; /** * The OpenTelemetry tracer provider to use for tracing. If omitted, * the global tracer provider is used. * @since 1.3.0 */ tracerProvider?: TracerProvider; } //#endregion //#region src/sig/http.d.ts /** * The reason why {@link verifyRequestDetailed} could not verify a request. * @since 2.1.0 */ type VerifyRequestFailureReason = { readonly type: "keyFetchError"; readonly keyId: URL; readonly result: FetchKeyErrorResult; } | { readonly type: "invalidSignature"; readonly keyId?: URL; } | { readonly type: "noSignature"; }; //#endregion //#region src/federation/collection.d.ts /** * A page of items. */ interface PageItems { readonly prevCursor?: string | null; readonly nextCursor?: string | null; readonly items: readonly TItem[]; } //#endregion //#region src/federation/send.d.ts /** * A key pair for an actor who sends an activity. * @since 0.10.0 */ interface SenderKeyPair { /** * The actor's private key to sign the request. */ readonly privateKey: CryptoKey; /** * The public key ID that corresponds to the private key. */ readonly keyId: URL; } /** * An error that is thrown when an activity fails to send to a remote inbox. * It contains structured information about the failure, including the HTTP * status code, the inbox URL, and the response body. * @since 2.0.0 */ declare class SendActivityError extends Error { /** * The inbox URL that the activity was being sent to. */ readonly inbox: URL; /** * The HTTP status code returned by the inbox. */ readonly statusCode: number; /** * The response body from the inbox, if any. Note that this may be * truncated to a maximum of 1 KiB to prevent excessive memory consumption * when remote servers return large error pages (e.g., Cloudflare error pages). * If truncated, the string will end with `"… (truncated)"`. */ readonly responseBody: string; /** * Creates a new {@link SendActivityError}. * @param inbox The inbox URL. * @param statusCode The HTTP status code. * @param message The error message. * @param responseBody The response body. */ constructor(inbox: URL, statusCode: number, message: string, responseBody: string); } //#endregion //#region src/federation/callback.d.ts /** * A callback that dispatches a {@link NodeInfo} object. * * @template TContextData The context data to pass to the {@link Context}. */ type NodeInfoDispatcher = (context: RequestContext) => NodeInfo | Promise; /** * A callback that dispatches a array of {@link Link}. * * @template TContextData The context data to pass to the {@link Context}. * @param resource The URL queried via WebFinger. * @returns Links related to the queried resource. */ type WebFingerLinksDispatcher = (context: RequestContext, resource: URL) => readonly Link$1[] | Promise; /** * A callback that dispatches an {@link Actor} object or a {@link Tombstone}. * * @template TContextData The context data to pass to the {@link Context}. * @param context The request context. * @param identifier The actor's internal identifier or username. */ type ActorDispatcher = (context: RequestContext, identifier: string) => Actor | Tombstone | null | Promise; /** * A callback that dispatches key pairs for an actor. * * @template TContextData The context data to pass to the {@link Context}. * @param context The context. * @param identifier The actor's internal identifier or username. * @returns The key pairs. * @since 0.10.0 */ type ActorKeyPairsDispatcher = (context: Context, identifier: string) => CryptoKeyPair[] | Promise; /** * A callback that maps a WebFinger username to the corresponding actor's * internal identifier, or `null` if the username is not found. * @template TContextData The context data to pass to the {@link Context}. * @param context The context. * @param username The WebFinger username. * @returns The actor's internal identifier, or `null` if the username is not * found. * @since 0.15.0 */ type ActorHandleMapper = (context: Context, username: string) => string | null | Promise; /** * A callback that maps a WebFinger query to the corresponding actor's * internal identifier or username, or `null` if the query is not found. * @template TContextData The context data to pass to the {@link Context}. * @param context The request context. * @param resource The URL that was queried through WebFinger. * @returns The actor's internal identifier or username, or `null` if the query * is not found. * @since 1.4.0 */ type ActorAliasMapper = (context: RequestContext, resource: URL) => { identifier: string; } | { username: string; } | null | Promise<{ identifier: string; } | { username: string; } | null>; /** * A callback that dispatches an object. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of object to dispatch. * @template TParam The parameter names of the requested URL. * @since 0.7.0 */ type ObjectDispatcher = (context: RequestContext, values: Record) => TObject | null | Promise; /** * A callback that dispatches a collection. * * @template TItem The type of items in the collection. * @template TContext The type of the context. {@link Context} or * {@link RequestContext}. * @template TContextData The context data to pass to the `TContext`. * @template TFilter The type of the filter, if any. * @param context The context. * @param identifier The internal identifier or the username of the collection * owner. * @param cursor The cursor to start the collection from, or `null` to dispatch * the entire collection without pagination. * @param filter The filter to apply to the collection, if any. */ type CollectionDispatcher, TContextData, TFilter> = (context: TContext, identifier: string, cursor: string | null, filter?: TFilter) => PageItems | null | Promise | null>; /** * A callback that counts the number of items in a collection. * * @template TContextData The context data to pass to the {@link Context}. * @param context The context. * @param identifier The internal identifier or the username of the collection * owner. * @param filter The filter to apply to the collection, if any. */ type CollectionCounter = (context: RequestContext, identifier: string, filter?: TFilter) => number | bigint | null | Promise; /** * A callback that returns a cursor for a collection. * * @template TContext The type of the context. {@link Context} or * {@link RequestContext}. * @template TContextData The context data to pass to the {@link Context}. * @template TFilter The type of the filter, if any. * @param context The context. * @param identifier The internal identifier or the username of the collection * owner. * @param filter The filter to apply to the collection, if any. */ type CollectionCursor, TContextData, TFilter> = (context: TContext, identifier: string, filter?: TFilter) => string | null | Promise; /** * A callback that listens for activities in an inbox. * * @template TContextData The context data to pass to the {@link Context}. * @template TActivity The type of activity to listen for. * @param context The inbox context. * @param activity The activity that was received. */ type InboxListener = (context: InboxContext, activity: TActivity) => void | Promise; /** * A callback that listens for activities in an outbox. * * @template TContextData The context data to pass to the {@link Context}. * @template TActivity The type of activity to listen for. * @param context The outbox context. * @param activity The activity that was received. * @since 2.2.0 */ type OutboxListener = (context: OutboxContext, activity: TActivity) => void | Promise; /** * The reason why an incoming activity could not be verified. * * Unlike inbox listeners registered through {@link InboxListenerSetters.on}, * unverified activity handlers are called only when the activity payload could * be parsed but its HTTP signatures could not be verified. * * @since 2.1.0 */ type UnverifiedActivityReason = VerifyRequestFailureReason; /** * A callback that handles activities whose signatures could not be verified. * * Returning a {@link Response} overrides Fedify's default `401 Unauthorized` * response. Returning `void` keeps the default behavior. * * @template TContextData The context data to pass to the {@link Context}. * @param context The request context. * @param activity The incoming activity that could be parsed. * @param reason The reason why signature verification failed. * @since 2.1.0 */ type UnverifiedActivityHandler = (context: RequestContext, activity: Activity, reason: UnverifiedActivityReason) => void | Response | Promise; /** * A callback that handles errors in an inbox. * * @template TContextData The context data to pass to the {@link Context}. * @param context The inbox context. */ type InboxErrorHandler = (context: Context, error: Error) => void | Promise; /** * A callback that handles errors in an outbox listener. * * @template TContextData The context data to pass to the {@link Context}. * @param context The outbox context. * @param error The error that occurred. * @since 2.2.0 */ type OutboxListenerErrorHandler = (context: OutboxContext, error: Error) => void | Promise; /** * A callback that dispatches the key pair for the authenticated document loader * of the {@link Context} passed to the shared inbox listener. * * @template TContextData The context data to pass to the {@link Context}. * @param context The context. * @returns The username or the internal identifier of the actor or the key pair * for the authenticated document loader of the {@link Context} passed * to the shared inbox listener. If `null` is returned, the request is * not authorized. * @since 0.11.0 */ type SharedInboxKeyDispatcher = (context: Context) => SenderKeyPair | { identifier: string; } | { username: string; } | null | Promise; /** * A callback that handles permanent delivery failures when sending activities * to remote inboxes. * * This handler is called when an inbox returns an HTTP status code that * indicates permanent failure (such as `410 Gone` or `404 Not Found`), * allowing the application to clean up followers that are no longer reachable. * * Unlike {@link OutboxErrorHandler}, which is called for every delivery failure * (including retries), this handler is called only once for permanent failures, * after which delivery is not retried. * * If any errors are thrown in this callback, they are caught, logged, * and ignored. * * @template TContextData The context data to pass to the {@link Context}. * @param context The context. * @param values The delivery failure information. * @since 2.0.0 */ type OutboxPermanentFailureHandler = (context: Context, values: { /** The inbox URL that failed. */readonly inbox: URL; /** The activity that failed to deliver. */ readonly activity: Activity; /** The error that occurred. */ readonly error: SendActivityError; /** The HTTP status code returned by the inbox. */ readonly statusCode: number; /** * The actor IDs that were supposed to receive the activity at this inbox. */ readonly actorIds: readonly URL[]; }) => void | Promise; /** * A callback that determines if a request is authorized or not. * * @template TContextData The context data to pass to the {@link Context}. * @param context The request context. * @param identifier The internal identifier of the actor that is being * requested. * @returns `true` if the request is authorized, `false` otherwise. * @since 0.7.0 */ type AuthorizePredicate = (context: RequestContext, identifier: string) => boolean | Promise; /** * A callback that determines if a request is authorized or not. * * @template TContextData The context data to pass to the {@link Context}. * @template TParam The parameter names of the requested URL. * @param context The request context. * @param values The parameters of the requested URL. * @returns `true` if the request is authorized, `false` otherwise. * @since 0.7.0 */ type ObjectAuthorizePredicate = (context: RequestContext, values: Record) => boolean | Promise; /** * A callback that dispatches a custom collection. * * @template TItem The type of items in the collection. * @template TParams The parameter names of the requested URL. * @template TContext The type of the context. {@link Context} or * {@link RequestContext}. * @template TContextData The context data to pass to the `TContext`. * @template TFilter The type of the filter, if any. * @param context The context. * @param values The parameters of the requested URL. * @param cursor The cursor to start the collection from, or `null` to dispatch * the entire collection without pagination. * @since 1.8.0 */ type CustomCollectionDispatcher, TContextData> = (context: TContext, values: Record, cursor: string | null) => PageItems | null | Promise | null>; /** * A callback that counts the number of items in a custom collection. * * @template TParams The parameter names of the requested URL. * @template TContextData The context data to pass to the {@link Context}. * @param context The context. * @param values The parameters of the requested URL. * @since 1.8.0 */ type CustomCollectionCounter = (context: RequestContext, values: Record) => number | bigint | null | Promise; /** * A callback that returns a cursor for a custom collection. * * @template TParams The parameter names of the requested URL. * @template TContext The type of the context. {@link Context} or * {@link RequestContext}. * @template TContextData The context data to pass to the {@link Context}. * @template TFilter The type of the filter, if any. * @param context The context. * @param values The parameters of the requested URL. * @since 1.8.0 */ type CustomCollectionCursor, TContextData> = (context: TContext, values: Record) => string | null | Promise; //#endregion //#region src/federation/queue.d.ts interface SenderKeyJwkPair { readonly keyId: string; readonly privateKey: JsonWebKey; } /** * A message that represents a task to be processed by the background worker. * The concrete type of the message depends on the `type` property. * * Please do not depend on the concrete types of the messages, as they may * change in the future. You should treat the `Message` type as an opaque * type. * @since 1.6.0 */ type Message = FanoutMessage | OutboxMessage | InboxMessage; interface FanoutMessage { readonly type: "fanout"; readonly id: ReturnType; readonly baseUrl: string; readonly keys: readonly SenderKeyJwkPair[]; readonly inboxes: Readonly>; readonly activity: unknown; readonly activityId?: string; readonly activityType: string; readonly collectionSync?: string; readonly orderingKey?: string; /** * Whether to apply outgoing JSON-LD wire-format normalization to queued * activities that already carry Object Integrity Proofs. * * `true` is used for proofs Fedify created before fanout, or when callers * explicitly request normalization for locally pre-signed activities. * `false`/`undefined` preserves existing proofs as-is. */ readonly normalizeExistingProofs?: boolean; readonly traceContext: Readonly>; } interface OutboxMessage { readonly type: "outbox"; readonly id: ReturnType; readonly baseUrl: string; readonly keys: readonly SenderKeyJwkPair[]; readonly activity: unknown; readonly activityId?: string; readonly activityType: string; readonly inbox: string; readonly sharedInbox: boolean; readonly actorIds?: readonly string[]; readonly started: string; readonly attempt: number; readonly headers: Readonly>; readonly orderingKey?: string; readonly traceContext: Readonly>; } interface InboxMessage { readonly type: "inbox"; readonly id: ReturnType; readonly baseUrl: string; readonly activity: unknown; /** * The normalized JSON-LD representation of a signed inbox activity that * Fedify already compacted successfully while accepting the request. Queue * workers can reuse this producer-side parse cache under stricter loader or * network constraints without changing the raw payload preserved for * forwarding. * * This may exist even when {@link ldSignatureVerified} is `false`, because * fallback-authenticated traffic and already-queued backlog items can still * depend on the cached normalized form to avoid re-fetching remote custom * contexts during worker processing. * * This is optional for backward compatibility with messages that were * queued by older Fedify versions or that were already in a queue before * upgrading. * * Fedify keeps this on the queued message itself instead of an external * sidecar because generic queue backends do not provide reliable lifecycle * guarantees for auxiliary storage across retries and redeliveries. * * @internal */ readonly normalizedActivity?: unknown; /** * Whether the producer actually verified the Linked Data Signature before * queueing this message. This lets workers distinguish verified LDS replay * from other authenticated inbox traffic that merely happened to include a * signature block. This provenance marker is separate from the optional * normalizedActivity parse cache. * * `undefined` preserves backward compatibility with older queued messages * that predate this marker. * * @internal */ readonly ldSignatureVerified?: boolean; readonly started: string; readonly attempt: number; readonly identifier: string | null; readonly traceContext: Readonly>; } //#endregion //#region src/federation/federation.d.ts /** * Options for {@link Federation.startQueue} method. * @since 1.0.0 */ interface FederationStartQueueOptions { /** * The signal to abort the task queue. */ 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. * @since 1.3.0 */ queue?: "inbox" | "outbox" | "fanout"; } /** * 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 { /** * Registers a NodeInfo dispatcher. * @param path The URI path pattern for the NodeInfo dispatcher. The syntax * is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have no variables. * @param dispatcher A NodeInfo dispatcher callback to register. * @throws {RouterError} Thrown if the path pattern is invalid. */ setNodeInfoDispatcher(path: string, dispatcher: NodeInfoDispatcher): void; /** * Registers a links dispatcher to WebFinger * @param dispatcher A links dispatcher callback to register. */ setWebFingerLinksDispatcher(dispatcher: WebFingerLinksDispatcher): void; /** * Registers an actor dispatcher. * * @example * ``` typescript * federation.setActorDispatcher( * "/users/{identifier}", * async (ctx, identifier) => { * return new Person({ * id: ctx.getActorUri(identifier), * // ... * }); * } * ); * ``` * * @param path The URI path pattern for the actor dispatcher. The syntax is * based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one variable: `{identifier}`. * @param dispatcher An actor dispatcher callback to register. It may return * an actor, a `Tombstone`, or `null` if the actor is not * found. * @returns An object with methods to set other actor dispatcher callbacks. * @throws {RouterError} Thrown if the path pattern is invalid. */ setActorDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: ActorDispatcher): ActorCallbackSetters; /** * Registers an object dispatcher. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of object to dispatch. * @template TParam The parameter names of the requested URL. * @param cls The Activity Vocabulary class of the object to dispatch. * @param path The URI path pattern for the object dispatcher. The syntax is * based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one or more variables. * @param dispatcher An object dispatcher callback to register. */ setObjectDispatcher(cls: ConstructorWithTypeId, path: `${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}`, dispatcher: ObjectDispatcher): ObjectCallbackSetters; /** * Registers an object dispatcher. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of object to dispatch. * @template TParam The parameter names of the requested URL. * @param cls The Activity Vocabulary class of the object to dispatch. * @param path The URI path pattern for the object dispatcher. The syntax is * based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one or more variables. * @param dispatcher An object dispatcher callback to register. */ setObjectDispatcher(cls: ConstructorWithTypeId, path: `${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}`, dispatcher: ObjectDispatcher): ObjectCallbackSetters; /** * Registers an object dispatcher. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of object to dispatch. * @template TParam The parameter names of the requested URL. * @param cls The Activity Vocabulary class of the object to dispatch. * @param path The URI path pattern for the object dispatcher. The syntax is * based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one or more variables. * @param dispatcher An object dispatcher callback to register. */ setObjectDispatcher(cls: ConstructorWithTypeId, path: `${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}`, dispatcher: ObjectDispatcher): ObjectCallbackSetters; /** * Registers an object dispatcher. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of object to dispatch. * @template TParam The parameter names of the requested URL. * @param cls The Activity Vocabulary class of the object to dispatch. * @param path The URI path pattern for the object dispatcher. The syntax is * based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one or more variables. * @param dispatcher An object dispatcher callback to register. */ setObjectDispatcher(cls: ConstructorWithTypeId, path: `${string}${Rfc6570Expression}${string}${Rfc6570Expression}${string}${Rfc6570Expression}${string}`, dispatcher: ObjectDispatcher): ObjectCallbackSetters; /** * Registers an object dispatcher. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of object to dispatch. * @template TParam The parameter names of the requested URL. * @param cls The Activity Vocabulary class of the object to dispatch. * @param path The URI path pattern for the object dispatcher. The syntax is * based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one or more variables. * @param dispatcher An object dispatcher callback to register. */ setObjectDispatcher(cls: ConstructorWithTypeId, path: `${string}${Rfc6570Expression}${string}${Rfc6570Expression}${string}`, dispatcher: ObjectDispatcher): ObjectCallbackSetters; /** * Registers an object dispatcher. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of object to dispatch. * @template TParam The parameter names of the requested URL. * @param cls The Activity Vocabulary class of the object to dispatch. * @param path The URI path pattern for the object dispatcher. The syntax is * based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one or more variables. * @param dispatcher An object dispatcher callback to register. */ setObjectDispatcher(cls: ConstructorWithTypeId, path: `${string}${Rfc6570Expression}${string}`, dispatcher: ObjectDispatcher): ObjectCallbackSetters; /** * Registers an inbox dispatcher. * * @param path The URI path pattern for the inbox dispatcher. The syntax is * based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one variable: `{identifier}`, and must match * the inbox listener path. * @param dispatcher An inbox dispatcher callback to register. * @throws {@link RouterError} Thrown if the path pattern is invalid. */ setInboxDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher, TContextData, void>): CollectionCallbackSetters, TContextData, void>; /** * Registers an outbox dispatcher. * * @example * ``` typescript * federation.setOutboxDispatcher( * "/users/{identifier}/outbox", * async (ctx, identifier, options) => { * let items: Activity[]; * let nextCursor: string; * // ... * return { items, nextCursor }; * } * ); * ``` * * @param path The URI path pattern for the outbox dispatcher. The syntax is * based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one variable: `{identifier}`. * @param dispatcher An outbox dispatcher callback to register. * @throws {@link RouterError} Thrown if the path pattern is invalid. */ setOutboxDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher, TContextData, void>): CollectionCallbackSetters, TContextData, void>; /** * Assigns the URL path for the outbox and starts setting outbox listeners. * * @example * ``` typescript * federation * .setOutboxListeners("/users/{identifier}/outbox") * .on(Activity, async (ctx, activity) => { * await ctx.sendActivity({ identifier: ctx.identifier }, "followers", activity); * }) * .authorize(async (ctx, identifier) => { * return ctx.request.headers.get("authorization") === `Bearer ${identifier}`; * }); * ``` * * @param outboxPath The URI path pattern for the outbox. The syntax is based * on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The * path must have one variable: `{identifier}`. If an * outbox dispatcher is configured, this path must match * the outbox dispatcher path. * @returns An object to register outbox listeners. * @throws {RouterError} Thrown if the path pattern is invalid. * @since 2.2.0 */ setOutboxListeners(outboxPath: `${string}${Rfc6570Expression<"identifier">}${string}`): OutboxListenerSetters; /** * Registers a following collection dispatcher. * @param path The URI path pattern for the following collection. The syntax * is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one variable: `{identifier}`. * @param dispatcher A following collection callback to register. * @returns An object with methods to set other following collection * callbacks. * @throws {RouterError} Thrown if the path pattern is invalid. */ setFollowingDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher, TContextData, void>): CollectionCallbackSetters, TContextData, void>; /** * Registers a followers collection dispatcher. * @param path The URI path pattern for the followers collection. The syntax * is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one variable: `{identifier}`. * @param dispatcher A followers collection callback to register. * @returns An object with methods to set other followers collection * callbacks. * @throws {@link RouterError} Thrown if the path pattern is invalid. */ setFollowersDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher, TContextData, URL>): CollectionCallbackSetters, TContextData, URL>; /** * Registers a liked collection dispatcher. * @param path The URI path pattern for the liked collection. The syntax * is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one variable: `{identifier}`. * @param dispatcher A liked collection callback to register. * @returns An object with methods to set other liked collection * callbacks. * @throws {@link RouterError} Thrown if the path pattern is invalid. */ setLikedDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher, TContextData, void>): CollectionCallbackSetters, TContextData, void>; /** * Registers a featured collection dispatcher. * @param path The URI path pattern for the featured collection. The syntax * is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one variable: `{identifier}`. * @param dispatcher A featured collection callback to register. * @returns An object with methods to set other featured collection * callbacks. * @throws {@link RouterError} Thrown if the path pattern is invalid. */ setFeaturedDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher, TContextData, void>): CollectionCallbackSetters, TContextData, void>; /** * Registers a featured tags collection dispatcher. * @param path The URI path pattern for the featured tags collection. * The syntax is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). The path * must have one variable: `{identifier}`. * @param dispatcher A featured tags collection callback to register. * @returns An object with methods to set other featured tags collection * callbacks. * @throws {@link RouterError} Thrown if the path pattern is invalid. */ setFeaturedTagsDispatcher(path: `${string}${Rfc6570Expression<"identifier">}${string}`, dispatcher: CollectionDispatcher, TContextData, void>): CollectionCallbackSetters, TContextData, void>; /** * Assigns the URL path for the inbox and starts setting inbox listeners. * * @example * ``` typescript * federation * .setInboxListeners("/users/{identifier}/inbox", "/inbox") * .on(Follow, async (ctx, follow) => { * const from = await follow.getActor(ctx); * if (!isActor(from)) return; * // ... * }) * .on(Undo, async (ctx, undo) => { * // ... * }); * ``` * * @param inboxPath The URI path pattern for the inbox. The syntax is based * on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). * The path must have one variable: `{identifier}`, and must * match the inbox dispatcher path. * @param sharedInboxPath An optional URI path pattern for the shared inbox. * The syntax is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). * The path must have no variables. * @returns An object to register inbox listeners. * @throws {RouterError} Thrown if the path pattern is invalid. */ setInboxListeners(inboxPath: `${string}${Rfc6570Expression<"identifier">}${string}`, sharedInboxPath?: string): InboxListenerSetters; /** * Registers a collection of objects dispatcher. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of objects to dispatch. * @template TParam The parameter names of the requested URL. * @param name A unique name for the collection dispatcher. * @param itemType The Activity Vocabulary class of the object to dispatch. * @param path The URI path pattern for the collection dispatcher. * The syntax is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). * The path must have one or more variables. * @param dispatcher A collection dispatcher callback to register. */ setCollectionDispatcher(name: string | symbol, itemType: ConstructorWithTypeId, path: `${string}${Rfc6570Expression}${string}${Rfc6570Expression}${string}${Rfc6570Expression}${string}`, dispatcher: CustomCollectionDispatcher, TContextData>): CustomCollectionCallbackSetters, TContextData>; /** * Registers a collection of objects dispatcher. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of objects to dispatch. * @template TParam The parameter names of the requested URL. * @param name A unique name for the collection dispatcher. * @param itemType The Activity Vocabulary class of the object to dispatch. * @param path The URI path pattern for the collection dispatcher. * The syntax is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). * The path must have one or more variables. * @param dispatcher A collection dispatcher callback to register. */ setCollectionDispatcher(name: string | symbol, itemType: ConstructorWithTypeId, path: `${string}${Rfc6570Expression}${string}${Rfc6570Expression}${string}`, dispatcher: CustomCollectionDispatcher, TContextData>): CustomCollectionCallbackSetters, TContextData>; /** * Registers a collection of objects dispatcher. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of objects to dispatch. * @template TParam The parameter names of the requested URL. * @param name A unique name for the collection dispatcher. * @param itemType The Activity Vocabulary class of the object to dispatch. * @param path The URI path pattern for the collection dispatcher. * The syntax is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). * The path must have one or more variables. * @param dispatcher A collection dispatcher callback to register. */ setCollectionDispatcher(name: string | symbol, itemType: ConstructorWithTypeId, path: `${string}${Rfc6570Expression}${string}`, dispatcher: CustomCollectionDispatcher, TContextData>): CustomCollectionCallbackSetters, TContextData>; /** * Registers an ordered collection of objects dispatcher. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of objects to dispatch. * @template TParam The parameter names of the requested URL. * @param name A unique name for the collection dispatcher. * @param itemType The Activity Vocabulary class of the object to dispatch. * @param path The URI path pattern for the collection dispatcher. * The syntax is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). * The path must have one or more variables. * @param dispatcher A collection dispatcher callback to register. */ setOrderedCollectionDispatcher(name: string | symbol, itemType: ConstructorWithTypeId, path: `${string}${Rfc6570Expression}${string}${Rfc6570Expression}${string}${Rfc6570Expression}${string}`, dispatcher: CustomCollectionDispatcher, TContextData>): CustomCollectionCallbackSetters, TContextData>; /** * Registers an ordered collection of objects dispatcher. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of objects to dispatch. * @template TParam The parameter names of the requested URL. * @param name A unique name for the collection dispatcher. * @param itemType The Activity Vocabulary class of the object to dispatch. * @param path The URI path pattern for the collection dispatcher. * The syntax is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). * The path must have one or more variables. * @param dispatcher A collection dispatcher callback to register. */ setOrderedCollectionDispatcher(name: string | symbol, itemType: ConstructorWithTypeId, path: `${string}${Rfc6570Expression}${string}${Rfc6570Expression}${string}`, dispatcher: CustomCollectionDispatcher, TContextData>): CustomCollectionCallbackSetters, TContextData>; /** * Registers an ordered collection of objects dispatcher. * * @template TContextData The context data to pass to the {@link Context}. * @template TObject The type of objects to dispatch. * @template TParam The parameter names of the requested URL. * @param name A unique name for the collection dispatcher. * @param itemType The Activity Vocabulary class of the object to dispatch. * @param path The URI path pattern for the collection dispatcher. * The syntax is based on URI Template * ([RFC 6570](https://tools.ietf.org/html/rfc6570)). * The path must have one or more variables. * @param dispatcher A collection dispatcher callback to register. */ setOrderedCollectionDispatcher(name: string | symbol, itemType: ConstructorWithTypeId, path: `${string}${Rfc6570Expression}${string}`, dispatcher: CustomCollectionDispatcher, TContextData>): CustomCollectionCallbackSetters, TContextData>; /** * Registers a handler for permanent delivery failures. * * This handler is called when an inbox returns an HTTP status code * that indicates permanent failure (`410 Gone`, `404 Not Found`, etc.), * allowing the application to clean up followers that are no longer * reachable. * * Unlike `onOutboxError`, which is called for every delivery failure * (including retries), this handler is called only once for permanent * failures, after which delivery is not retried. * * @param handler A callback to handle permanent failures. * @since 2.0.0 */ setOutboxPermanentFailureHandler(handler: OutboxPermanentFailureHandler): void; } /** * An object that registers federation-related business logic and dispatches * requests to the appropriate handlers. * * It also provides a middleware interface for handling requests before your * web framework's router; see {@link Federation.fetch}. * @template TContextData The context data to pass to the {@link Context}. * @since 0.13.0 */ interface Federation extends Federatable { /** * Manually start the task queue. * * This method is useful when you set the `manuallyStartQueue` option to * `true` in the {@link createFederation} function. * @param contextData The context data to pass to the context. * @param options Additional options for starting the queue. */ startQueue(contextData: TContextData, options?: FederationStartQueueOptions): Promise; /** * Processes a queued message task. This method handles different types of * tasks such as fanout, outbox, and inbox messages. * * Note that you usually do not need to call this method directly unless you * are deploying your federated application on a platform that does not * support long-running processing, such as Cloudflare Workers. * @param contextData The context data to pass to the context. * @param message The message that represents the task to be processed. * @returns A promise that resolves when the message has been processed. * @since 1.6.0 */ processQueuedTask(contextData: TContextData, message: Message): Promise; /** * Create a new context. * @param baseUrl The base URL of the server. The `pathname` remains root, * and the `search` and `hash` are stripped. * @param contextData The context data to pass to the context. * @returns The new context. */ createContext(baseUrl: URL, contextData: TContextData): Context; /** * Create a new context for a request. * @param request The request object. * @param contextData The context data to pass to the context. * @returns The new request context. */ createContext(request: Request, contextData: TContextData): RequestContext; /** * Handles a request related to federation. If a request is not related to * federation, the `onNotFound` or `onNotAcceptable` callback is called. * * Usually, this method is called from a server's request handler or * a web framework's middleware. * * @param request The request object. * @param parameters The parameters for handling the request. * @returns The response to the request. */ fetch(request: Request, options: FederationFetchOptions): Promise; } /** * Additional settings for the actor dispatcher. * * ``` typescript * const federation = createFederation({ ... }); * federation * .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => { * // ... * }) * .setKeyPairsDispatcher(async (ctxData, identifier) => { * // ... * }); * ``` */ interface ActorCallbackSetters { /** * Sets the key pairs dispatcher for actors. * @param dispatcher A callback that returns the key pairs for an actor. * @returns The setters object so that settings can be chained. * @since 0.10.0 */ setKeyPairsDispatcher(dispatcher: ActorKeyPairsDispatcher): ActorCallbackSetters; /** * Sets the callback function that maps a WebFinger username to * the corresponding actor's identifier. If it's omitted, the identifier * is assumed to be the same as the WebFinger username, which makes your * actors have the immutable handles. If you want to let your actors change * their fediverse handles, you should set this dispatcher. * @param mapper A callback that maps a WebFinger username to * the corresponding actor's identifier. * @returns The setters object so that settings can be chained. * @since 0.15.0 */ mapHandle(mapper: ActorHandleMapper): ActorCallbackSetters; /** * Sets the callback function that maps a WebFinger query to the corresponding * actor's identifier or username. If it's omitted, the WebFinger handler * only supports the actor URIs and `acct:` URIs. If you want to support * other queries, you should set this dispatcher. * @param mapper A callback that maps a WebFinger query to the corresponding * actor's identifier or username. * @returns The setters object so that settings can be chained. * @since 1.4.0 */ mapAlias(mapper: ActorAliasMapper): ActorCallbackSetters; /** * Specifies the conditions under which requests are authorized. * @param predicate A callback that returns whether a request is authorized. * @returns The setters object so that settings can be chained. * @since 0.7.0 */ authorize(predicate: AuthorizePredicate): ActorCallbackSetters; } /** * Additional settings for an object dispatcher. */ interface ObjectCallbackSetters { /** * Specifies the conditions under which requests are authorized. * @param predicate A callback that returns whether a request is authorized. * @returns The setters object so that settings can be chained. * @since 0.7.0 */ authorize(predicate: ObjectAuthorizePredicate): ObjectCallbackSetters; } /** * Additional settings for a collection dispatcher. * * @template TContext The type of the context. {@link Context} or * {@link RequestContext}. * @template TContextData The context data to pass to the {@link Context}. * @template TFilter The type of filter for the collection. */ interface CollectionCallbackSetters, TContextData, TFilter> { /** * Sets the counter for the collection. * @param counter A callback that returns the number of items in the collection. * @returns The setters object so that settings can be chained. */ setCounter(counter: CollectionCounter): CollectionCallbackSetters; /** * Sets the first cursor for the collection. * @param cursor The cursor for the first item in the collection. * @returns The setters object so that settings can be chained. */ setFirstCursor(cursor: CollectionCursor): CollectionCallbackSetters; /** * Sets the last cursor for the collection. * @param cursor The cursor for the last item in the collection. * @returns The setters object so that settings can be chained. */ setLastCursor(cursor: CollectionCursor): CollectionCallbackSetters; /** * Specifies the conditions under which requests are authorized. * @param predicate A callback that returns whether a request is authorized. * @returns The setters object so that settings can be chained. * @since 0.7.0 */ authorize(predicate: AuthorizePredicate): CollectionCallbackSetters; } /** * The strategy for handling activity idempotency in inbox processing. * * - `"global"`: Activities are deduplicated globally across all inboxes and * origins. The same activity ID will be processed only once, regardless * of which inbox receives it or which server sent it. * * - `"per-origin"`: Activities are deduplicated per receiving server's origin. * The same activity ID will be processed only once on each receiving server, * but can be processed separately on different receiving servers. This had * been the default behavior in Fedify 1.x versions. * * - `"per-inbox"`: Activities are deduplicated per inbox. The same activity * ID can be processed once per inbox, allowing the same activity to be * delivered to multiple inboxes independently. This follows standard * ActivityPub behavior and is the default strategy since Fedify 2.0.0. * * @since 1.9.0 */ type IdempotencyStrategy = "global" | "per-origin" | "per-inbox"; /** * A callback to generate a custom idempotency key for an activity. * Returns the cache key to use, or null to skip idempotency checking. * @template TContextData The context data to pass to the {@link InboxContext}. * @param ctx The inbox context. * @param activity The activity being processed. * @returns The idempotency key to use for caching, or null to skip caching. * @since 1.9.0 */ type IdempotencyKeyCallback = (ctx: InboxContext, activity: Activity) => string | null | Promise; /** * Registry for outbox listeners for different activity types. * @since 2.2.0 */ interface OutboxListenerSetters { /** * Registers a listener for a specific incoming activity type. * * @param type A subclass of {@link Activity} to listen to. * @param listener A callback to handle an incoming activity. * @returns The setters object so that settings can be chained. * @since 2.2.0 */ on(type: new (...args: any[]) => TActivity, listener: OutboxListener): OutboxListenerSetters; /** * Registers an error handler for outbox listeners. Any exceptions thrown * from the listeners are caught and passed to this handler. * * @param handler A callback to handle an error. * @returns The setters object so that settings can be chained. * @since 2.2.0 */ onError(handler: OutboxListenerErrorHandler): OutboxListenerSetters; /** * Registers a callback to authorize POST requests to the outbox. * * @param predicate A callback to authorize the request. * @returns The setters object so that settings can be chained. * @since 2.2.0 */ authorize(predicate: AuthorizePredicate): OutboxListenerSetters; } /** * Registry for inbox listeners for different activity types. */ interface InboxListenerSetters { /** * Registers a listener for a specific incoming activity type. * * @param type A subclass of {@link Activity} to listen to. * @param listener A callback to handle an incoming activity. * @returns The setters object so that settings can be chained. */ on(type: new (...args: any[]) => TActivity, listener: InboxListener): InboxListenerSetters; /** * Registers an error handler for inbox listeners. Any exceptions thrown * from the listeners are caught and passed to this handler. * * @param handler A callback to handle an error. * @returns The setters object so that settings can be chained. */ onError(handler: InboxErrorHandler): InboxListenerSetters; /** * Registers a callback for incoming activities whose HTTP signatures could * not be verified. * * The regular inbox listeners registered through {@link on} continue to * receive only verified activities. This hook is an opt-in escape hatch for * applications that need to inspect unverified deliveries and optionally * override the default `401 Unauthorized` response. * * @example * ``` typescript * federation * .setInboxListeners("/users/{identifier}/inbox", "/inbox") * .onUnverifiedActivity((ctx, activity, reason) => { * if ( * reason.type === "keyFetchError" && * "status" in reason.result && * reason.result.status === 410 * ) { * return new Response(null, { status: 202 }); * } * }); * ``` * * @param handler A callback to handle an unverified activity. * @returns The setters object so that settings can be chained. * @since 2.1.0 */ onUnverifiedActivity(handler: UnverifiedActivityHandler): InboxListenerSetters; /** * Configures a callback to dispatch the key pair for the authenticated * document loader of the {@link Context} passed to the shared inbox listener. * * @param dispatcher A callback to dispatch the key pair for the authenticated * document loader. * @returns The setters object so that settings can be chained. * @since 0.11.0 */ setSharedKeyDispatcher(dispatcher: SharedInboxKeyDispatcher): InboxListenerSetters; /** * Configures the strategy for handling activity idempotency in inbox processing. * * @example * Use per-inbox strategy (standard ActivityPub behavior): * ``` * federation * .setInboxListeners("/users/{identifier}/inbox", "/inbox") * .withIdempotency("per-inbox"); * ``` * * Use custom strategy: * ``` * federation * .setInboxListeners("/users/{identifier}/inbox", "/inbox") * .withIdempotency((ctx, activity) => { * // Return null to skip idempotency * return `${ctx.origin}:${activity.id?.href}:${ctx.recipient}`; * }); * ``` * * @param strategy The idempotency strategy to use. Can be: * - `"global"`: Activities are deduplicated across all inboxes and origins * - `"per-origin"`: Activities are deduplicated per inbox origin * - `"per-inbox"`: Activities are deduplicated per inbox * - A custom callback function that returns the cache key to use * @returns The setters object so that settings can be chained. * @since 1.9.0 */ withIdempotency(strategy: IdempotencyStrategy | IdempotencyKeyCallback): InboxListenerSetters; } /** * Parameters of {@link Federation.fetch} method. * * @template TContextData The context data to pass to the {@link Context}. * @since 0.6.0 */ interface FederationFetchOptions { /** * The context data to pass to the {@link Context}. */ contextData: TContextData; /** * A callback to handle a request when the route is not found. * If not provided, a 404 response is returned. * @param request The request object. * @returns The response to the request. */ onNotFound?: (request: Request) => Response | Promise; /** * A callback to handle a request when the request's `Accept` header is not * acceptable. If not provided, a 406 response is returned. * @param request The request object. * @returns The response to the request. */ onNotAcceptable?: (request: Request) => Response | Promise; /** * A callback to handle a request when the request is unauthorized. * If not provided, a 401 response is returned. * @param request The request object. * @returns The response to the request. * @since 0.7.0 */ onUnauthorized?: (request: Request) => Response | Promise; } /** * Additional settings for a custom collection dispatcher. * * @template TParam The type of the parameters in the URL path. * @template TContext The type of the context. {@link Context} or * {@link RequestContext}. * @template TContextData The context data to pass to the {@link Context}. * @template TFilter The type of filter for the collection. */ interface CustomCollectionCallbackSetters, TContextData> { /** * Sets the counter for the custom collection. * @param counter A callback that returns the number of items in the custom collection. * @returns The setters object so that settings can be chained. */ setCounter(counter: CustomCollectionCounter): CustomCollectionCallbackSetters; /** * Sets the first cursor for the custom collection. * @param cursor The cursor for the first item in the custom collection. * @returns The setters object so that settings can be chained. */ setFirstCursor(cursor: CustomCollectionCursor): CustomCollectionCallbackSetters; /** * Sets the last cursor for the custom collection. * @param cursor The cursor for the last item in the custom collection. * @returns The setters object so that settings can be chained. */ setLastCursor(cursor: CustomCollectionCursor): CustomCollectionCallbackSetters; /** * Specifies the conditions under which requests are authorized. * @param predicate A callback that returns whether a request is authorized. * @returns The setters object so that settings can be chained. * @since 0.7.0 */ authorize(predicate: ObjectAuthorizePredicate): CustomCollectionCallbackSetters; } /** * Represents an object with a type ID, which is either a constructor or an * instance of the object. * * @template TObject The type of the object. */ type ConstructorWithTypeId = (new (...args: any[]) => TObject) & { typeId: URL; }; /** * Defines a union of all valid RFC 6570 URI Template expressions for a given * parameter name. * * RFC 6570 specifies a syntax for URI templates, allowing for variable * expansion. This type captures all Level 1-4 operator expressions for a * single, named variable. * * The supported expression types are: * - `{Param}`: Simple string expansion * - `+{Param}`: Reserved string expansion * - `#{Param}`: Fragment expansion * - `{.Param}`: Label expansion with a dot-prefix * - `{/Param}`: Path segment expansion * - `{;Param}`: Path-style parameter expansion * - `{?Param}`: Query component expansion * - `{&Param}`: Query continuation expansion * * @template Param The name of the parameter to be used in the expressions. * @example * ```ts * type UserIdExpression = Rfc6570Expression<"userId">; * * // The variable `userPath` can be assigned any of the valid expressions. * const userPath: UserIdExpression = "{/userId}"; * ``` * @see {@link https://tools.ietf.org/html/rfc6570} for the full specification. */ type Rfc6570Expression = `{${Param}}` | `{+${Param}}` | `{#${Param}}` | `{.${Param}}` | `{/${Param}}` | `{;${Param}}` | `{?${Param}}` | `{&${Param}}`; //#endregion //#region src/federation/context.d.ts /** * A context. */ interface Context { /** * The origin of the federated server, including the scheme (`http://` or * `https://`) and the host (e.g., `example.com:8080`). * @since 0.12.0 */ readonly origin: string; /** * The canonical origin of the federated server, including the scheme * (`http://` or `https://`) and the host (e.g., `example.com:8080`). * * When the associated {@link Federation} object does not have any explicit * canonical origin, it is the same as the {@link Context.origin}. * @since 1.5.0 */ readonly canonicalOrigin: string; /** * The host of the federated server, including the hostname * (e.g., `example.com`) and the port following a colon (e.g., `:8080`) * if it is not the default port for the scheme. * @since 0.12.0 */ readonly host: string; /** * The hostname of the federated server (e.g., `example.com`). This is * the same as the host without the port. * @since 0.12.0 */ readonly hostname: string; /** * The user-defined data associated with the context. */ readonly data: TContextData; /** * The OpenTelemetry tracer provider. * @since 1.3.0 */ readonly tracerProvider: TracerProvider; /** * The document loader for loading remote JSON-LD documents. */ readonly documentLoader: DocumentLoader; /** * The context loader for loading remote JSON-LD contexts. */ readonly contextLoader: DocumentLoader; /** * The federation object that this context belongs to. * @since 1.6.0 */ readonly federation: Federation; /** * Creates a new context with the same properties as this one, * but with the given data. * @param data The new data to associate with the context. * @returns A new context with the same properties as this one, * but with the given data. * @since 1.6.0 */ clone(data: TContextData): Context; /** * Builds the URI of the NodeInfo document. * @returns The NodeInfo URI. * @throws {RouterError} If no NodeInfo dispatcher is available. * @since 0.2.0 */ getNodeInfoUri(): URL; /** * Builds the URI of an actor with the given identifier. * @param identifier The actor's identifier. * @returns The actor's URI. * @throws {RouterError} If no actor dispatcher is available. */ getActorUri(identifier: string): URL; /** * Builds the URI of an object with the given class and values. * @param cls The class of the object. * @param values The values to pass to the object dispatcher. * @returns The object's URI. * @throws {RouterError} If no object dispatcher is available for the class. * @throws {TypeError} If values are invalid. * @since 0.7.0 */ getObjectUri(cls: ConstructorWithTypeId, values: Record): URL; /** * Builds the URI of an actor's outbox with the given identifier. * @param identifier The actor's identifier. * @returns The actor's outbox URI. * @throws {RouterError} If no outbox dispatcher is available. */ getOutboxUri(identifier: string): URL; /** * Builds the URI of the shared inbox. * @returns The shared inbox URI. * @throws {RouterError} If no inbox listener is available. */ getInboxUri(): URL; /** * Builds the URI of an actor's inbox with the given identifier. * @param identifier The actor's identifier. * @returns The actor's inbox URI. * @throws {RouterError} If no inbox listener is available. */ getInboxUri(identifier: string): URL; /** * Builds the URI of an actor's following collection with the given * identifier. * @param identifier The actor's identifier. * @returns The actor's following collection URI. * @throws {RouterError} If no following collection is available. */ getFollowingUri(identifier: string): URL; /** * Builds the URI of an actor's followers collection with the given * identifier. * @param identifier The actor's identifier. * @returns The actor's followers collection URI. * @throws {RouterError} If no followers collection is available. */ getFollowersUri(identifier: string): URL; /** * Builds the URI of an actor's liked collection with the given identifier. * @param identifier The actor's identifier. * @returns The actor's liked collection URI. * @throws {RouterError} If no liked collection is available. * @since 0.11.0 */ getLikedUri(identifier: string): URL; /** * Builds the URI of an actor's featured collection with the given identifier. * @param identifier The actor's identifier. * @returns The actor's featured collection URI. * @throws {RouterError} If no featured collection is available. * @since 0.11.0 */ getFeaturedUri(identifier: string): URL; /** * Builds the URI of an actor's featured tags collection with the given * identifier. * @param identifier The actor's identifier. * @returns The actor's featured tags collection URI. * @throws {RouterError} If no featured tags collection is available. * @since 0.11.0 */ getFeaturedTagsUri(identifier: string): URL; /** * Determines the type of the URI and extracts the associated data. * @param uri The URI to parse. * @returns The result of parsing the URI. If `null` is given or * the URI is not recognized, `null` is returned. * @since 0.9.0 */ parseUri(uri: URL | null): ParseUriResult | null; /** * Gets the key pairs for an actor. * @param identifier The actor's identifier. * @returns An async iterable of the actor's key pairs. It can be empty. * @since 0.10.0 */ getActorKeyPairs(identifier: string): Promise; /** * Gets an authenticated {@link DocumentLoader} for the given identity. * Note that an authenticated document loader intentionally does not cache * the fetched documents. * @param identity The identity to get the document loader for. * The actor's identifier or username. * @returns The authenticated document loader. * @throws {Error} If the identity is not valid. * @throws {TypeError} If the key is invalid or unsupported. * @since 0.4.0 */ getDocumentLoader(identity: { identifier: string; } | { username: string; }): Promise; /** * Gets an authenticated {@link DocumentLoader} for the given identity. * Note that an authenticated document loader intentionally does not cache * the fetched documents. * @param identity The identity to get the document loader for. * The actor's key pair. * @returns The authenticated document loader. * @throws {TypeError} If the key is invalid or unsupported. * @since 0.4.0 */ getDocumentLoader(identity: { keyId: URL; privateKey: CryptoKey; }): DocumentLoader; /** * Looks up an ActivityStreams object by its URI (including `acct:` URIs) * or a fediverse handle (e.g., `@user@server` or `user@server`). * * @example * ``` typescript * // Look up an actor by its fediverse handle: * await ctx.lookupObject("@hongminhee@fosstodon.org"); * // returning a `Person` object. * * // A fediverse handle can omit the leading '@': * await ctx.lookupObject("hongminhee@fosstodon.org"); * // returning a `Person` object. * * // A `acct:` URI can be used as well: * await ctx.lookupObject("acct:hongminhee@fosstodon.org"); * // returning a `Person` object. * * // Look up an object by its URI: * await ctx.lookupObject("https://todon.eu/@hongminhee/112060633798771581"); * // returning a `Note` object. * * // It can be a `URL` object as well: * await ctx.lookupObject( * new URL("https://todon.eu/@hongminhee/112060633798771581") * ); * // returning a `Note` object. * ``` * * It's almost the same as the {@link lookupObject} function, but it uses * the context's document loader and context loader by default. * * @param identifier The URI or fediverse handle to look up. * @param options Lookup options. * @returns The object, or `null` if not found. * @since 0.15.0 */ lookupObject(identifier: string | URL, options?: LookupObjectOptions): Promise; /** * Traverses a collection, yielding each item in the collection. * If the collection is paginated, it will fetch the next page * automatically. * * @example * ``` typescript * const collection = await ctx.lookupObject(collectionUrl); * if (collection instanceof Collection) { * for await (const item of ctx.traverseCollection(collection)) { * console.log(item.id?.href); * } * } * ``` * * It's almost the same as the {@link traverseCollection} function, but it * uses the context's document loader and context loader by default. * @param collection The collection to traverse. * @param options Options for traversing the collection. * @returns An async iterable of each item in the collection. * @since 1.1.0 */ traverseCollection(collection: Collection, options?: TraverseCollectionOptions): AsyncIterable; /** * Fetches the NodeInfo document from the given URL. * @param url The base URL of the server. If `options.direct` is turned off * (default), the NodeInfo document will be fetched from * the `.well-known` location of this URL (hence the only origin * of the URL is used). If `options.direct` is turned on, * the NodeInfo document will be fetched from the given URL. * @param options Options for fetching the NodeInfo document. * @returns The NodeInfo document if it could be fetched successfully. * Otherwise, `undefined` is returned. * @since 1.4.0 */ lookupNodeInfo(url: URL | string, options?: GetNodeInfoOptions & { parse?: "strict" | "best-effort"; }): Promise; /** * Fetches the NodeInfo document from the given URL. * @param url The base URL of the server. If `options.direct` is turned off * (default), the NodeInfo document will be fetched from * the `.well-known` location of this URL (hence the only origin * of the URL is used). If `options.direct` is turned on, * the NodeInfo document will be fetched from the given URL. * @param options Options for fetching the NodeInfo document. * @returns The NodeInfo document if it could be fetched successfully. * Otherwise, `undefined` is returned. * @since 1.4.0 */ lookupNodeInfo(url: URL | string, options?: GetNodeInfoOptions & { parse: "none"; }): Promise; /** * Looks up a WebFinger resource. * * It's almost the same as the {@link lookupWebFinger} function, but it uses * the context's configuration by default. * * @param resource The resource URL to look up. * @param options Extra options for looking up the resource. * @returns The resource descriptor, or `null` if not found. * @since 1.6.0 */ lookupWebFinger(resource: URL | string, options?: LookupWebFingerOptions): Promise; /** * Sends an activity to recipients' inboxes. * @param sender The sender's identifier or the sender's username or * the sender's key pair(s). * @param recipients The recipients of the activity. * @param activity The activity to send. * @param options Options for sending the activity. */ sendActivity(sender: SenderKeyPair | SenderKeyPair[] | { identifier: string; } | { username: string; }, recipients: Recipient | Recipient[], activity: Activity, options?: SendActivityOptions): Promise; /** * Sends an activity to the inboxes of the sender's followers. * @param sender The sender's identifier or the sender's username. * @param recipients In this case, it must be `"followers"`. * @param activity The activity to send. * @param options Options for sending the activity. * @throws {Error} If no followers collection is registered. * @since 0.14.0 */ sendActivity(sender: { identifier: string; } | { username: string; }, recipients: "followers", activity: Activity, options?: SendActivityOptionsForCollection): Promise; /** * Manually routes an activity to the appropriate inbox listener. * * It is useful for routing an activity that is not received from the network, * or for routing an activity that is enclosed in another activity. * * Note that the activity will be verified if it has Object Integrity Proofs * or is equivalent to the actual remote object. If the activity is not * verified, it will be rejected. * @param recipient The recipient of the activity. If it is `null`, * the activity will be routed to the shared inbox. * Otherwise, the activity will be routed to the personal * inbox of the recipient with the given identifier. * @param activity The activity to route. It must have a proof or * a dereferenceable `id` to verify the activity. * @param options Options for routing the activity. * @returns `true` if the activity is successfully verified and routed. * Otherwise, `false`. * @since 1.3.0 */ routeActivity(recipient: string | null, activity: Activity, options?: RouteActivityOptions): Promise; /** * 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. * @param values The values of the URI parameters. * @return The URI of the collection. * @throws {RouterError} If no object dispatcher is available for the name. * @throws {TypeError} If values are invalid. * @since 1.8.0 */ getCollectionUri>(name: string | symbol, values: TParam): URL; } /** * Options for {@link RequestContext.getActor}. * @since 2.2.0 */ interface GetActorOptions { /** * Controls how tombstoned actors are returned. * * By default, tombstones are suppressed and returned as `null`. Set this to * `"passthrough"` to receive a {@link Tombstone} result instead. */ readonly tombstone?: "suppress" | "passthrough"; } /** * A context for a request. */ interface RequestContext extends Context { /** * The request object. */ readonly request: Request; /** * The URL of the request. */ readonly url: URL; /** * Creates a new context with the same properties as this one, * but with the given data. * @param data The new data to associate with the context. * @returns A new context with the same properties as this one, * but with the given data. * @since 1.6.0 */ clone(data: TContextData): RequestContext; /** * Gets an {@link Actor} object for the given identifier. * @param identifier The actor's identifier. * @returns The actor object, or `null` if the actor is not found. * @throws {Error} If no actor dispatcher is available. * @since 0.7.0 */ getActor(identifier: string): Promise; /** * Gets an {@link Actor} object or {@link Tombstone} for the given * identifier. * @param identifier The actor's identifier. * @param options Options for getting the actor. Set * `options.tombstone` to `"passthrough"` to receive * tombstoned actors instead of `null`. * @returns The actor object, a tombstone, or `null` if the actor is not * found. * @throws {Error} If no actor dispatcher is available. * @since 2.2.0 */ getActor(identifier: string, options: GetActorOptions & { readonly tombstone: "passthrough"; }): Promise; /** * Gets an {@link Actor} object for the given identifier. * @param identifier The actor's identifier. * @param options Options for getting the actor. * @returns The actor object, or `null` if the actor is not found. * Tombstoned actors are suppressed unless `options.tombstone` is * `"passthrough"`. * @throws {Error} If no actor dispatcher is available. * @since 2.2.0 */ getActor(identifier: string, options: GetActorOptions & { readonly tombstone?: "suppress" | undefined; }): Promise; /** * Gets an {@link Actor} object or {@link Tombstone} for the given * identifier. * @param identifier The actor's identifier. * @param options Options for getting the actor. * @returns The actor object, a tombstone, or `null` if the actor is not * found. This broad overload is used when the caller passes an * options value whose `tombstone` mode is not known statically. * @throws {Error} If no actor dispatcher is available. * @since 2.2.0 */ getActor(identifier: string, options: GetActorOptions): Promise; /** * Gets an object of the given class with the given values. * @param cls The class to instantiate. * @param values The values to pass to the object dispatcher. * @returns The object of the given class with the given values, or `null` * if the object is not found. * @throws {Error} If no object dispatcher is available for the class. * @throws {TypeError} If values are invalid. * @since 0.7.0 */ getObject(cls: ConstructorWithTypeId, values: Record): Promise; /** * Gets the public key of the sender, if any exists and it is verified. * Otherwise, `null` is returned. * * This can be used for implementing [authorized fetch] (also known as * secure mode) in ActivityPub. * * [authorized fetch]: https://swicg.github.io/activitypub-http-signature/#authorized-fetch * * @returns The public key of the sender, or `null` if the sender is not verified. * @since 0.7.0 */ getSignedKey(): Promise; /** * Gets the public key of the sender, if any exists and it is verified. * Otherwise, `null` is returned. * * This can be used for implementing [authorized fetch] (also known as * secure mode) in ActivityPub. * * [authorized fetch]: https://swicg.github.io/activitypub-http-signature/#authorized-fetch * * @param options Options for getting the signed key. You usually may want to * specify the custom `documentLoader` so that making * an HTTP request to the sender's server is signed with * your [instance actor]. * @returns The public key of the sender, or `null` if the sender is not verified. * @since 1.5.0 * * [instance actor]: https://swicg.github.io/activitypub-http-signature/#instance-actor */ getSignedKey(options: GetSignedKeyOptions): Promise; /** * Gets the owner of the signed key, if any exists and it is verified. * Otherwise, `null` is returned. * * This can be used for implementing [authorized fetch] (also known as * secure mode) in ActivityPub. * * [authorized fetch]: https://swicg.github.io/activitypub-http-signature/#authorized-fetch * * @returns The owner of the signed key, or `null` if the key is not verified * or the owner is not found. * @since 0.7.0 */ getSignedKeyOwner(): Promise; /** * Gets the owner of the signed key, if any exists and it is verified. * Otherwise, `null` is returned. * * This can be used for implementing [authorized fetch] (also known as * secure mode) in ActivityPub. * * [authorized fetch]: https://swicg.github.io/activitypub-http-signature/#authorized-fetch * * @param options Options for getting the key owner. You usually may want to * specify the custom `documentLoader` so that making * an HTTP request to the key owner's server is signed with * your [instance actor]. * @returns The owner of the signed key, or `null` if the key is not verified * or the owner is not found. * @since 1.5.0 * * [instance actor]: https://swicg.github.io/activitypub-http-signature/#instance-actor */ getSignedKeyOwner(options: GetKeyOwnerOptions): Promise; } /** * A context for inbox listeners. * @since 1.0.0 */ interface InboxContext extends Context { /** * The identifier of the recipient of the inbox. If the inbox is a shared * inbox, it is `null`. * @since 1.2.0 */ readonly recipient: string | null; /** * Creates a new context with the same properties as this one, * but with the given data. * @param data The new data to associate with the context. * @returns A new context with the same properties as this one, * but with the given data. * @since 1.6.0 */ clone(data: TContextData): InboxContext; /** * Forwards a received activity to the recipients' inboxes. The forwarded * activity will be signed in HTTP Signatures by the forwarder, but its * payload will not be modified, i.e., Linked Data Signatures and Object * Integrity Proofs will not be added. Even when Fedify internally * normalizes a Linked Data Signature activity for parsing, this method still * forwards the original received payload so the sender's signatures/proofs * are preserved as-is. Therefore, if the activity is not signed (i.e., it * has neither Linked Data Signatures nor Object Integrity Proofs), the * recipient probably will not trust the activity. * @param forwarder The forwarder's identifier or the forwarder's username * or the forwarder's key pair(s). * @param recipients The recipients of the activity. * @param options Options for forwarding the activity. * @since 1.0.0 */ forwardActivity(forwarder: SenderKeyPair | SenderKeyPair[] | { identifier: string; } | { username: string; }, recipients: Recipient | Recipient[], options?: ForwardActivityOptions): Promise; /** * Forwards a received activity to the recipients' inboxes. The forwarded * activity will be signed in HTTP Signatures by the forwarder, but its * payload will not be modified, i.e., Linked Data Signatures and Object * Integrity Proofs will not be added. Even when Fedify internally * normalizes a Linked Data Signature activity for parsing, this method still * forwards the original received payload so the sender's signatures/proofs * are preserved as-is. Therefore, if the activity is not signed (i.e., it * has neither Linked Data Signatures nor Object Integrity Proofs), the * recipient probably will not trust the activity. * @param forwarder The forwarder's identifier or the forwarder's username. * @param recipients In this case, it must be `"followers"`. * @param options Options for forwarding the activity. * @since 1.0.0 */ forwardActivity(forwarder: { identifier: string; } | { username: string; }, recipients: "followers", options?: ForwardActivityOptions): Promise; } /** * A context for outbox listeners. * @since 2.2.0 */ interface OutboxContext extends Context { /** * The identifier of the actor whose outbox received the POST. * @since 2.2.0 */ readonly identifier: string; /** * Indicates whether the posted activity has been delivered during the * current outbox listener invocation. * @returns `true` if the posted activity has been delivered; `false` * otherwise. * @since 2.2.0 */ hasDeliveredActivity(): boolean; /** * Forwards a posted activity to the recipients' inboxes without * re-serializing the original payload. The forwarded activity will be * signed in HTTP Signatures by the forwarder, but its payload will not be * modified, i.e., Linked Data Signatures and Object Integrity Proofs will * not be added. Therefore, if the posted activity is not signed (i.e., it * has neither Linked Data Signatures nor Object Integrity Proofs), the * recipients probably will not trust the activity. * @param forwarder The forwarder's identifier or the forwarder's username * or the forwarder's key pair(s). * @param recipients The recipients of the activity. * @param options Options for forwarding the activity. * @since 2.2.0 */ forwardActivity(forwarder: SenderKeyPair | SenderKeyPair[] | { identifier: string; } | { username: string; }, recipients: Recipient | Recipient[], options?: ForwardActivityOptions): Promise; /** * Forwards a posted activity to the recipients' inboxes without * re-serializing the original payload. The forwarded activity will be * signed in HTTP Signatures by the forwarder, but its payload will not be * modified, i.e., Linked Data Signatures and Object Integrity Proofs will * not be added. Therefore, if the posted activity is not signed (i.e., it * has neither Linked Data Signatures nor Object Integrity Proofs), the * recipients probably will not trust the activity. * @param forwarder The forwarder's identifier or the forwarder's username. * @param recipients In this case, it must be `"followers"`. * @param options Options for forwarding the activity. * @since 2.2.0 */ forwardActivity(forwarder: { identifier: string; } | { username: string; }, recipients: "followers", options?: ForwardActivityOptions): Promise; /** * Creates a new context with the same properties as this one, * but with the given data. * @param data The new data to associate with the context. * @returns A new context with the same properties as this one, * but with the given data. * @since 2.2.0 */ clone(data: TContextData): OutboxContext; } /** * A result of parsing an URI. */ type ParseUriResult = /** * The case of an actor URI. */ { readonly type: "actor"; readonly identifier: string; } /** * The case of an object URI. */ | { readonly type: "object"; readonly class: ConstructorWithTypeId; readonly typeId: URL; readonly values: Record; } /** * The case of an shared inbox URI. */ | { readonly type: "inbox"; readonly identifier: undefined; } /** * The case of an personal inbox URI. */ | { readonly type: "inbox"; readonly identifier: string; } /** * The case of an outbox collection URI. */ | { readonly type: "outbox"; readonly identifier: string; } /** * The case of a following collection URI. */ | { readonly type: "following"; readonly identifier: string; } /** * The case of a followers collection URI. */ | { readonly type: "followers"; readonly identifier: string; } /** * The case of a liked collection URI. * @since 0.11.0 */ | { readonly type: "liked"; readonly identifier: string; } /** * The case of a featured collection URI. * @since 0.11.0 */ | { readonly type: "featured"; readonly identifier: string; } /** * The case of a featured tags collection URI. * @since 0.11.0 */ | { readonly type: "featuredTags"; readonly identifier: string; } /** * The case of a custom collection URI. * @since 1.8.0 */ | { readonly type: "collection"; readonly name: string | symbol; readonly class: ConstructorWithTypeId; readonly typeId: URL; readonly values: Record; } /** * The case of a custom ordered collection URI. * @since 1.8.0 */ | { readonly type: "orderedCollection"; readonly name: string | symbol; readonly class: ConstructorWithTypeId; readonly typeId: URL; readonly values: Record; }; /** * Options for {@link Context.sendActivity} method. */ interface SendActivityOptions { /** * Whether to prefer the shared inbox for the recipients. */ readonly preferSharedInbox?: boolean; /** * Whether to send the activity immediately, without enqueuing it. * If `true`, the activity will be sent immediately and the retrial * policy will not be applied. * * @since 0.3.0 */ readonly immediate?: boolean; /** * Determines how activities are queued when sent to multiple recipients. * * - "auto" (default): Automatically chooses optimal strategy based on * recipient count. * - "skip": Always enqueues individual messages per recipient, * bypassing the fanout queue. Use when payload needs to vary per recipient. * - "force": Always uses fanout queue regardless of recipient count. * Useful for testing or special cases. * * This option is ignored when `immediate: true` is specified, as immediate * delivery bypasses all queuing mechanisms. * * @default `"auto"` * @since 1.5.0 */ readonly fanout?: "auto" | "skip" | "force"; /** * Whether to apply Fedify's outgoing JSON-LD wire-format compatibility fixes * to activities that already carry Object Integrity Proofs. * * By default, Fedify preserves existing proofs byte-for-byte because it * cannot know whether they were created for the normalized outgoing wire * form. Set this to `true` when sending an activity that was pre-signed * locally with `signObject()` or `createProof()`, so the emitted * compact JSON-LD matches the bytes covered by the proof. * * @since 2.2.0 */ readonly normalizeExistingProofs?: boolean; /** * The base URIs to exclude from the recipients' inboxes. It is useful * for excluding the recipients having the same shared inbox with the sender. * * Note that the only `origin` parts of the `URL`s are compared. * * @since 0.9.0 */ readonly excludeBaseUris?: readonly URL[]; /** * An optional key to ensure ordered delivery of activities. Activities with * the same `orderingKey` are guaranteed to be delivered in the order they * were enqueued, per recipient server. * * Typical use case: pass the object ID (e.g., `Note` ID) to ensure that * `Create`, `Update`, and `Delete` activities for the same object are * delivered in order. * * When omitted, no ordering is guaranteed (maximum parallelism). * * @since 2.0.0 */ readonly orderingKey?: string; } /** * Options for {@link Context.sendActivity} method when sending to a collection. * @since 1.5.0 */ interface SendActivityOptionsForCollection extends SendActivityOptions { /** * Whether to synchronize the collection using `Collection-Synchronization` * header ([FEP-8fcf]). * * [FEP-8fcf]: https://w3id.org/fep/8fcf */ syncCollection?: boolean; } /** * Options for {@link InboxContext.forwardActivity} method. * @since 1.0.0 */ type ForwardActivityOptions = Omit & { /** * Whether to skip forwarding the activity if it is not signed, i.e., it has * neither Linked Data Signatures nor Object Integrity Proofs. * * If the activity is not signed, the recipient probably will not trust the * activity. Therefore, it is recommended to skip forwarding the activity * if it is not signed. */ skipIfUnsigned: boolean; }; /** * Options for {@link Context.routeActivity} method. * @since 1.3.0 */ interface RouteActivityOptions { /** * Whether to skip enqueuing the activity and invoke the listener immediately. * If no inbox queue is available, this option is ignored and the activity * will be always invoked immediately. * @default false */ immediate?: boolean; /** * The document loader for loading remote JSON-LD documents. */ documentLoader?: DocumentLoader; /** * The context loader for loading remote JSON-LD contexts. */ contextLoader?: DocumentLoader; /** * The OpenTelemetry tracer provider. If omitted, the global tracer provider * is used. */ tracerProvider?: TracerProvider; } /** * Options for {@link Context.getSignedKey} method. * @since 1.5.0 */ interface GetSignedKeyOptions { /** * The document loader for loading remote JSON-LD documents. */ documentLoader?: DocumentLoader; /** * The context loader for loading remote JSON-LD contexts. */ contextLoader?: DocumentLoader; /** * The OpenTelemetry tracer provider. If omitted, the global tracer provider * is used. */ tracerProvider?: TracerProvider; } /** * A pair of a public key and a private key in various formats. * @since 0.10.0 */ interface ActorKeyPair extends CryptoKeyPair { /** * The URI of the public key for {@link CryptographicKey}, which is used for * verifying HTTP Signatures and Linked Data Signatures. Note that this is * the ID of the {@link cryptographicKey}, not of the {@link multikey}; * the {@link Multikey} instance has a distinct ID of its own. */ readonly keyId: URL; /** * A {@link CryptographicKey} instance of the public key. */ readonly cryptographicKey: CryptographicKey; /** * A {@link Multikey} instance of the public key. */ readonly multikey: Multikey; } //#endregion //#region src/testing/context.d.ts declare function createRequestContext(args: Partial> & { url: URL; data: TContextData; federation: Federation; }): RequestContext; declare function createInboxContext(args: Partial> & { url?: URL; data: TContextData; recipient?: string | null; federation: Federation; }): InboxContext; declare function createOutboxContext(args: Partial> & { url?: URL; data: TContextData; identifier: string; federation: Federation; }): OutboxContext; //#endregion export { createInboxContext, createOutboxContext, createRequestContext, testDefinitions };