@fedify/adonisjs 2.4.0-dev.0

package/dist/src/types.d.cts

@@ -0,0 +1,269 @@
+import { HttpContext } from "@adonisjs/core/http";
+import { Federation, FederationBuilder, FederationOptions, FederationOrigin, KvStore, RequestContext } from "@fedify/fedify";
+
+//#region src/types.d.ts
+/**
+* The "register pattern" interface used to configure the context data type of
+* an application, in the same spirit as AdonisJS's own `ContainerBindings` or
+* `EventsList` interfaces.
+*
+* Fedify threads an application-defined value — `TContextData` — through every
+* dispatcher, collection callback and inbox listener.  Because a package cannot
+* know that type in advance, an application declares it by augmenting this
+* interface once, usually in `config/fedify.ts`:
+*
+* ```ts
+* declare module '@fedify/adonisjs/types' {
+*   interface FedifyTypes {
+*     contextData: { user: User | null }
+*   }
+* }
+* ```
+*
+* After that augmentation, {@link ContextData} resolves to the declared type
+* everywhere in the application, including inside `ctx.federation`.
+*/
+interface FedifyTypes {}
+/**
+* The context data type of the current application.
+*
+* Resolves to whatever {@link FedifyTypes.contextData} was augmented to, and
+* falls back to `HttpContext | null` when the application has not augmented
+* anything.
+*
+* The `| null` half of the default is deliberate and important.  Fedify invokes
+* dispatchers and inbox listeners from two very different places:
+*
+* - During an HTTP request, where an `HttpContext` exists, and
+* - From a background queue worker or an Ace command, where one does *not*.
+*
+* Defaulting to a non-nullable `HttpContext` would let application code write
+* `ctx.data.auth.user` in an inbox listener and only discover at 3 a.m. in
+* production — once a real server delivers an activity through the queue — that
+* there was never an HTTP context to read.  The nullable default forces that
+* case to be handled at compile time.
+*/
+type ContextData = FedifyTypes extends {
+  contextData: infer TContextData;
+} ? TContextData : HttpContext | null;
+/**
+* A callback that produces the Fedify context data for a single HTTP request.
+*
+* This mirrors the `ContextDataFactory` type exported by the other Fedify
+* integration packages (`@fedify/express`, `@fedify/hono`, `@fedify/koa`, …).
+* Like Hono's and Koa's variants — and unlike Express's, which only receives
+* the request — it is handed the whole framework context.
+*
+* That context is a *pre-routing* one, though: the factory runs in the server
+* middleware stack, before route matching and every router middleware, so only
+* `ctx.request`, `ctx.response`, `ctx.logger` and `ctx.containerResolver` are
+* set.  `ctx.auth`, `ctx.session`, `ctx.bouncer`, `ctx.params` and `ctx.route`
+* are still `undefined` (`ctx.params` is `{}`), and dereferencing one fails
+* every request the middleware does not bypass.
+*
+* The ordering is forced rather than chosen: Fedify has to decide whether it
+* serves a request before AdonisJS routes it, and `Federation.fetch()` takes
+* the context data by value rather than as a callback.  Carry request-level
+* state here, and look anything session-bound up inside the dispatcher that
+* needs it.
+*
+* It may be synchronous or asynchronous, and it is invoked at most once per
+* request.
+*/
+type ContextDataFactory<TContextData> = (ctx: HttpContext) => TContextData | Promise<TContextData>;
+/**
+* Options for bridging Fedify's LogTape logs into the AdonisJS logger.
+*/
+interface FedifyLoggingConfig {
+  /**
+  * The LogTape categories to route into the AdonisJS logger.
+  *
+  * Defaults to Fedify's own category plus LogTape's meta category, which is
+  * where LogTape reports its own configuration problems.
+  *
+  * @default `[['logtape', 'meta'], ['fedify']]`
+  */
+  categories?: (string | string[])[];
+}
+/**
+* Everything {@link FedifyConfig} accepts except `contextDataFactory`, whose
+* optionality is decided separately by {@link ContextDataFactoryOption}.
+*
+* It is Fedify's own {@link FederationOptions} — so every Fedify option is
+* available and documented in Fedify's own reference — plus a handful of
+* AdonisJS-specific keys, and with two differences:
+*
+* - `origin` is **required** (Fedify treats it as optional and derives the
+*   origin from the incoming request, which produces wrong actor URIs the
+*   moment the app sits behind a proxy or a tunnel), and
+* - `kv` is **optional** (it falls back to an in-memory store in development).
+*/
+interface FedifyConfigBase extends Omit<FederationOptions<ContextData>, "kv" | "origin"> {
+  /**
+  * The canonical public origin of this server, for example
+  * `https://social.example.com`.
+  *
+  * Fedify mints actor URIs, activity IDs and collection URLs from this value,
+  * so it must be the address remote servers can reach — not the address the
+  * Node process happens to be listening on.  Read it from an environment
+  * variable (the `configure` hook adds `PUBLIC_URL` for exactly this purpose).
+  *
+  * Pass a {@link FederationOrigin} object when the WebFinger handle domain
+  * differs from the web origin, for example handles `@me@example.com` served
+  * from `https://social.example.com`.
+  */
+  origin: string | FederationOrigin;
+  /**
+  * The key–value store Fedify uses for caching remote documents, tracking
+  * inbox idempotency, and holding outbox state.
+  *
+  * Defaults to an in-memory store, which is fine for development and tests but
+  * loses all state on restart and cannot be shared between processes.  A
+  * warning is logged if the default is used in production.  Use a persistent
+  * implementation such as `@fedify/sqlite`, `@fedify/postgres`,
+  * `@fedify/redis`, or `@fedify/mysql` in production.
+  */
+  kv?: KvStore;
+  /**
+  * URL path prefixes that Fedify should never see.
+  *
+  * Requests whose path starts with one of these prefixes skip the Fedify
+  * middleware entirely and go straight to the AdonisJS router.  This is a pure
+  * performance escape hatch for hot paths that can never be federation
+  * endpoints — Vite's dev-server routes are the usual example.
+  *
+  * Accessing `ctx.federation` inside a request that matched one of these
+  * prefixes throws, because no Fedify context was created for it.
+  *
+  * @default `[]`
+  */
+  ignoreRoutePrefixes?: string[];
+  /**
+  * Whether to pipe Fedify's LogTape logs into the AdonisJS logger.
+  *
+  * Fedify logs a great deal of useful diagnostic detail (signature
+  * verification, delivery attempts, WebFinger lookups) through LogTape.
+  * Without this bridge, none of it appears in the application's log output.
+  *
+  * Set to `false` if the application configures LogTape itself.
+  *
+  * @default `true`
+  */
+  logging?: boolean | FedifyLoggingConfig;
+  /**
+  * Who drains Fedify's task queue, and with what context data.
+  *
+  * Required whenever {@link FederationOptions.queue} is set, because there is
+  * no safe default.  Letting Fedify start the queue lazily — which is what it
+  * does out of the box — captures the context data of whichever HTTP request
+  * happened to enqueue the first task, and every background job for the rest
+  * of the process then runs with that one stale request's `HttpContext`.
+  *
+  * Pass a callback to have the **web process** drain the queue: the service
+  * provider starts the worker in the `ready` lifecycle hook and stops it on
+  * shutdown.  There is no `HttpContext` behind a queued task, hence the
+  * callback takes no arguments.
+  *
+  * Pass `false` when a **separate worker process** owns the queue.  Nothing is
+  * started in-process, and it is then that worker's job to call
+  * `federation.startQueue()`.
+  *
+  * Without a {@link FederationOptions.queue}, a callback is accepted with a
+  * warning — a task registered through `defineTask()` may bring its own
+  * queue, which this configuration cannot see — while `false` is accepted
+  * silently: it stays true when there is no queue at all, so a configuration
+  * that enables one in production only does not fail to boot in development.
+  */
+  queueContextData?: (() => ContextData | Promise<ContextData>) | false;
+}
+/**
+* The `contextDataFactory` half of {@link FedifyConfig}, whose optionality
+* depends on {@link ContextData}.
+*
+* The runtime default is `(ctx) => ctx`, which is only a correct
+* {@link ContextData} while the application has not augmented
+* {@link FedifyTypes} — after an augmentation an `HttpContext` is precisely
+* what a dispatcher must *not* receive.  Making the key required in that case
+* turns "every dispatcher silently gets the wrong value" into a compile error
+* on `config/fedify.ts`, which is the only place that can fix it.
+*
+* The tuple wrappers keep the conditional from distributing over a union
+* {@link ContextData}, so an augmentation such as `User | null` is compared as
+* a whole.
+*/
+type ContextDataFactoryOption = [HttpContext] extends [ContextData] ? {
+  /**
+  * Produces the {@link ContextData} for each incoming HTTP request.
+  *
+  * Defaults to `(ctx) => ctx`, i.e. the `HttpContext` itself, which matches
+  * the default of {@link ContextData}.
+  */
+  contextDataFactory?: ContextDataFactory<ContextData>;
+} : {
+  /**
+  * Produces the {@link ContextData} for each incoming HTTP request.
+  *
+  * Required here because the application augmented {@link FedifyTypes}:
+  * the built-in default hands dispatchers the `HttpContext`, which is no
+  * longer the declared context data type.
+  */
+  contextDataFactory: ContextDataFactory<ContextData>;
+};
+/**
+* The shape of the object passed to {@link defineConfig} in `config/fedify.ts`.
+*
+* {@link FedifyConfigBase} plus {@link ContextDataFactoryOption}, which makes
+* `contextDataFactory` required exactly when {@link FedifyTypes} has been
+* augmented.
+*/
+type FedifyConfig = FedifyConfigBase & ContextDataFactoryOption;
+/**
+* The fully-resolved configuration held by the `fedify.config` container
+* binding: {@link FedifyConfig} with every optional AdonisJS-specific key
+* filled in.
+*/
+interface ResolvedFedifyConfig extends FederationOptions<ContextData> {
+  contextDataFactory: ContextDataFactory<ContextData>;
+  ignoreRoutePrefixes: string[];
+  logging: boolean | FedifyLoggingConfig;
+  queueContextData?: (() => ContextData | Promise<ContextData>) | false;
+}
+declare module "@adonisjs/core/types" {
+  interface ContainerBindings {
+    /**
+    * The built {@link Federation} instance.  Resolvable only once the
+    * application is ready — see the service provider for why.
+    */
+    "fedify": Federation<ContextData>;
+    /**
+    * The {@link FederationBuilder} that dispatchers and inbox listeners are
+    * registered on, before the `Federation` instance is built.
+    */
+    "fedify.builder": FederationBuilder<ContextData>;
+    /**
+    * The resolved contents of `config/fedify.ts`.
+    */
+    "fedify.config": ResolvedFedifyConfig;
+  }
+}
+declare module "@adonisjs/core/http" {
+  interface HttpContext {
+    /**
+    * The Fedify {@link RequestContext} for the current request.
+    *
+    * Use it to mint canonical URIs (`ctx.federation.getActorUri('me')`), look
+    * remote objects up (`ctx.federation.lookupObject('@user@example.com')`),
+    * or send activities (`ctx.federation.sendActivity(...)`) from ordinary
+    * AdonisJS controllers.
+    *
+    * The context is created lazily on first access, so requests that never
+    * touch it pay nothing.  Accessing it throws if the request path matched
+    * {@link FedifyConfig.ignoreRoutePrefixes}, or if the Fedify server
+    * middleware is not registered in `start/kernel.ts`.
+    */
+    federation: RequestContext<ContextData>;
+  }
+}
+//#endregion
+export { ContextData, ContextDataFactory, ContextDataFactoryOption, FedifyConfig, FedifyConfigBase, FedifyLoggingConfig, FedifyTypes, ResolvedFedifyConfig };
+//# sourceMappingURL=types.d.cts.map

package/dist/src/types.d.ts

@@ -0,0 +1,269 @@
+import { HttpContext } from "@adonisjs/core/http";
+import { Federation, FederationBuilder, FederationOptions, FederationOrigin, KvStore, RequestContext } from "@fedify/fedify";
+
+//#region src/types.d.ts
+/**
+* The "register pattern" interface used to configure the context data type of
+* an application, in the same spirit as AdonisJS's own `ContainerBindings` or
+* `EventsList` interfaces.
+*
+* Fedify threads an application-defined value — `TContextData` — through every
+* dispatcher, collection callback and inbox listener.  Because a package cannot
+* know that type in advance, an application declares it by augmenting this
+* interface once, usually in `config/fedify.ts`:
+*
+* ```ts
+* declare module '@fedify/adonisjs/types' {
+*   interface FedifyTypes {
+*     contextData: { user: User | null }
+*   }
+* }
+* ```
+*
+* After that augmentation, {@link ContextData} resolves to the declared type
+* everywhere in the application, including inside `ctx.federation`.
+*/
+interface FedifyTypes {}
+/**
+* The context data type of the current application.
+*
+* Resolves to whatever {@link FedifyTypes.contextData} was augmented to, and
+* falls back to `HttpContext | null` when the application has not augmented
+* anything.
+*
+* The `| null` half of the default is deliberate and important.  Fedify invokes
+* dispatchers and inbox listeners from two very different places:
+*
+* - During an HTTP request, where an `HttpContext` exists, and
+* - From a background queue worker or an Ace command, where one does *not*.
+*
+* Defaulting to a non-nullable `HttpContext` would let application code write
+* `ctx.data.auth.user` in an inbox listener and only discover at 3 a.m. in
+* production — once a real server delivers an activity through the queue — that
+* there was never an HTTP context to read.  The nullable default forces that
+* case to be handled at compile time.
+*/
+type ContextData = FedifyTypes extends {
+  contextData: infer TContextData;
+} ? TContextData : HttpContext | null;
+/**
+* A callback that produces the Fedify context data for a single HTTP request.
+*
+* This mirrors the `ContextDataFactory` type exported by the other Fedify
+* integration packages (`@fedify/express`, `@fedify/hono`, `@fedify/koa`, …).
+* Like Hono's and Koa's variants — and unlike Express's, which only receives
+* the request — it is handed the whole framework context.
+*
+* That context is a *pre-routing* one, though: the factory runs in the server
+* middleware stack, before route matching and every router middleware, so only
+* `ctx.request`, `ctx.response`, `ctx.logger` and `ctx.containerResolver` are
+* set.  `ctx.auth`, `ctx.session`, `ctx.bouncer`, `ctx.params` and `ctx.route`
+* are still `undefined` (`ctx.params` is `{}`), and dereferencing one fails
+* every request the middleware does not bypass.
+*
+* The ordering is forced rather than chosen: Fedify has to decide whether it
+* serves a request before AdonisJS routes it, and `Federation.fetch()` takes
+* the context data by value rather than as a callback.  Carry request-level
+* state here, and look anything session-bound up inside the dispatcher that
+* needs it.
+*
+* It may be synchronous or asynchronous, and it is invoked at most once per
+* request.
+*/
+type ContextDataFactory<TContextData> = (ctx: HttpContext) => TContextData | Promise<TContextData>;
+/**
+* Options for bridging Fedify's LogTape logs into the AdonisJS logger.
+*/
+interface FedifyLoggingConfig {
+  /**
+  * The LogTape categories to route into the AdonisJS logger.
+  *
+  * Defaults to Fedify's own category plus LogTape's meta category, which is
+  * where LogTape reports its own configuration problems.
+  *
+  * @default `[['logtape', 'meta'], ['fedify']]`
+  */
+  categories?: (string | string[])[];
+}
+/**
+* Everything {@link FedifyConfig} accepts except `contextDataFactory`, whose
+* optionality is decided separately by {@link ContextDataFactoryOption}.
+*
+* It is Fedify's own {@link FederationOptions} — so every Fedify option is
+* available and documented in Fedify's own reference — plus a handful of
+* AdonisJS-specific keys, and with two differences:
+*
+* - `origin` is **required** (Fedify treats it as optional and derives the
+*   origin from the incoming request, which produces wrong actor URIs the
+*   moment the app sits behind a proxy or a tunnel), and
+* - `kv` is **optional** (it falls back to an in-memory store in development).
+*/
+interface FedifyConfigBase extends Omit<FederationOptions<ContextData>, "kv" | "origin"> {
+  /**
+  * The canonical public origin of this server, for example
+  * `https://social.example.com`.
+  *
+  * Fedify mints actor URIs, activity IDs and collection URLs from this value,
+  * so it must be the address remote servers can reach — not the address the
+  * Node process happens to be listening on.  Read it from an environment
+  * variable (the `configure` hook adds `PUBLIC_URL` for exactly this purpose).
+  *
+  * Pass a {@link FederationOrigin} object when the WebFinger handle domain
+  * differs from the web origin, for example handles `@me@example.com` served
+  * from `https://social.example.com`.
+  */
+  origin: string | FederationOrigin;
+  /**
+  * The key–value store Fedify uses for caching remote documents, tracking
+  * inbox idempotency, and holding outbox state.
+  *
+  * Defaults to an in-memory store, which is fine for development and tests but
+  * loses all state on restart and cannot be shared between processes.  A
+  * warning is logged if the default is used in production.  Use a persistent
+  * implementation such as `@fedify/sqlite`, `@fedify/postgres`,
+  * `@fedify/redis`, or `@fedify/mysql` in production.
+  */
+  kv?: KvStore;
+  /**
+  * URL path prefixes that Fedify should never see.
+  *
+  * Requests whose path starts with one of these prefixes skip the Fedify
+  * middleware entirely and go straight to the AdonisJS router.  This is a pure
+  * performance escape hatch for hot paths that can never be federation
+  * endpoints — Vite's dev-server routes are the usual example.
+  *
+  * Accessing `ctx.federation` inside a request that matched one of these
+  * prefixes throws, because no Fedify context was created for it.
+  *
+  * @default `[]`
+  */
+  ignoreRoutePrefixes?: string[];
+  /**
+  * Whether to pipe Fedify's LogTape logs into the AdonisJS logger.
+  *
+  * Fedify logs a great deal of useful diagnostic detail (signature
+  * verification, delivery attempts, WebFinger lookups) through LogTape.
+  * Without this bridge, none of it appears in the application's log output.
+  *
+  * Set to `false` if the application configures LogTape itself.
+  *
+  * @default `true`
+  */
+  logging?: boolean | FedifyLoggingConfig;
+  /**
+  * Who drains Fedify's task queue, and with what context data.
+  *
+  * Required whenever {@link FederationOptions.queue} is set, because there is
+  * no safe default.  Letting Fedify start the queue lazily — which is what it
+  * does out of the box — captures the context data of whichever HTTP request
+  * happened to enqueue the first task, and every background job for the rest
+  * of the process then runs with that one stale request's `HttpContext`.
+  *
+  * Pass a callback to have the **web process** drain the queue: the service
+  * provider starts the worker in the `ready` lifecycle hook and stops it on
+  * shutdown.  There is no `HttpContext` behind a queued task, hence the
+  * callback takes no arguments.
+  *
+  * Pass `false` when a **separate worker process** owns the queue.  Nothing is
+  * started in-process, and it is then that worker's job to call
+  * `federation.startQueue()`.
+  *
+  * Without a {@link FederationOptions.queue}, a callback is accepted with a
+  * warning — a task registered through `defineTask()` may bring its own
+  * queue, which this configuration cannot see — while `false` is accepted
+  * silently: it stays true when there is no queue at all, so a configuration
+  * that enables one in production only does not fail to boot in development.
+  */
+  queueContextData?: (() => ContextData | Promise<ContextData>) | false;
+}
+/**
+* The `contextDataFactory` half of {@link FedifyConfig}, whose optionality
+* depends on {@link ContextData}.
+*
+* The runtime default is `(ctx) => ctx`, which is only a correct
+* {@link ContextData} while the application has not augmented
+* {@link FedifyTypes} — after an augmentation an `HttpContext` is precisely
+* what a dispatcher must *not* receive.  Making the key required in that case
+* turns "every dispatcher silently gets the wrong value" into a compile error
+* on `config/fedify.ts`, which is the only place that can fix it.
+*
+* The tuple wrappers keep the conditional from distributing over a union
+* {@link ContextData}, so an augmentation such as `User | null` is compared as
+* a whole.
+*/
+type ContextDataFactoryOption = [HttpContext] extends [ContextData] ? {
+  /**
+  * Produces the {@link ContextData} for each incoming HTTP request.
+  *
+  * Defaults to `(ctx) => ctx`, i.e. the `HttpContext` itself, which matches
+  * the default of {@link ContextData}.
+  */
+  contextDataFactory?: ContextDataFactory<ContextData>;
+} : {
+  /**
+  * Produces the {@link ContextData} for each incoming HTTP request.
+  *
+  * Required here because the application augmented {@link FedifyTypes}:
+  * the built-in default hands dispatchers the `HttpContext`, which is no
+  * longer the declared context data type.
+  */
+  contextDataFactory: ContextDataFactory<ContextData>;
+};
+/**
+* The shape of the object passed to {@link defineConfig} in `config/fedify.ts`.
+*
+* {@link FedifyConfigBase} plus {@link ContextDataFactoryOption}, which makes
+* `contextDataFactory` required exactly when {@link FedifyTypes} has been
+* augmented.
+*/
+type FedifyConfig = FedifyConfigBase & ContextDataFactoryOption;
+/**
+* The fully-resolved configuration held by the `fedify.config` container
+* binding: {@link FedifyConfig} with every optional AdonisJS-specific key
+* filled in.
+*/
+interface ResolvedFedifyConfig extends FederationOptions<ContextData> {
+  contextDataFactory: ContextDataFactory<ContextData>;
+  ignoreRoutePrefixes: string[];
+  logging: boolean | FedifyLoggingConfig;
+  queueContextData?: (() => ContextData | Promise<ContextData>) | false;
+}
+declare module "@adonisjs/core/types" {
+  interface ContainerBindings {
+    /**
+    * The built {@link Federation} instance.  Resolvable only once the
+    * application is ready — see the service provider for why.
+    */
+    "fedify": Federation<ContextData>;
+    /**
+    * The {@link FederationBuilder} that dispatchers and inbox listeners are
+    * registered on, before the `Federation` instance is built.
+    */
+    "fedify.builder": FederationBuilder<ContextData>;
+    /**
+    * The resolved contents of `config/fedify.ts`.
+    */
+    "fedify.config": ResolvedFedifyConfig;
+  }
+}
+declare module "@adonisjs/core/http" {
+  interface HttpContext {
+    /**
+    * The Fedify {@link RequestContext} for the current request.
+    *
+    * Use it to mint canonical URIs (`ctx.federation.getActorUri('me')`), look
+    * remote objects up (`ctx.federation.lookupObject('@user@example.com')`),
+    * or send activities (`ctx.federation.sendActivity(...)`) from ordinary
+    * AdonisJS controllers.
+    *
+    * The context is created lazily on first access, so requests that never
+    * touch it pay nothing.  Accessing it throws if the request path matched
+    * {@link FedifyConfig.ignoreRoutePrefixes}, or if the Fedify server
+    * middleware is not registered in `start/kernel.ts`.
+    */
+    federation: RequestContext<ContextData>;
+  }
+}
+//#endregion
+export { ContextData, ContextDataFactory, ContextDataFactoryOption, FedifyConfig, FedifyConfigBase, FedifyLoggingConfig, FedifyTypes, ResolvedFedifyConfig };
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.js

@@ -0,0 +1 @@
+export {  };

package/dist/src/unusable_authority.cjs

@@ -0,0 +1,79 @@
+
+//#region src/unusable_authority.ts
+/**
+* The host used when the request carries no usable authority.
+*
+* `FederationOptions.origin` covers the URLs Fedify *mints* — actor URIs,
+* activity IDs, collection URLs — so the placeholder never reaches a peer
+* through them, and only the path has to survive for routing.  It does not
+* cover verification: RFC 9421's `@authority`, `@target-uri` and `@scheme`
+* are derived from this URL, so a request signed over `@authority` fails to
+* verify while the placeholder stands in.  That is the cost of answering
+* instead of failing, and why the fallback is logged.
+*/
+const PLACEHOLDER_HOST = "localhost";
+/**
+* Unusable authorities already warned about in the current window.  Any
+* client can trigger the warning through `Host`, so each distinct value is
+* reported once and the set is capped, leaving neither it nor the log
+* unbounded.  The key is the whole value, since two hostile values can share
+* a 128-character prefix.
+*/
+const warnedAuthorities = new Set();
+/**
+* How many distinct values one window reports.
+*/
+const WARNED_AUTHORITIES_LIMIT = 16;
+/**
+* How long the cap holds before the budget starts over.
+*
+* Without a window the cap is spent for the life of the process, and the
+* values that spend it are the client's to choose: sixteen junk `Host`
+* headers would silence the warning for good, so a proxy misconfigured an
+* hour later—every request falling back to {@link PLACEHOLDER_HOST}, every
+* signature over `@authority` failing to verify—would never be reported.
+* Starting over bounds the log at {@link WARNED_AUTHORITIES_LIMIT} lines per
+* window instead of over all time, which is what the log has to be protected
+* from, and leaves a standing misconfiguration visible.
+*/
+const WARNED_AUTHORITIES_WINDOW_MS = 60 * 60 * 1e3;
+/**
+* When the current window began; `0` so the first warning opens one.  It
+* advances lazily, on the first warning after the window has elapsed, rather
+* than from a timer that would hold the event loop open on a quiet process.
+*/
+let warnedAuthoritiesWindowStart = 0;
+/**
+* Whether the cap has already been reported in this window.  Reaching it
+* silences every later distinct value, which should not happen invisibly.
+*/
+let warnedAuthoritiesCapReported = false;
+/**
+* Reports an authority the request URL could not be built from, once per
+* distinct value and window.
+*/
+function warnUnusableAuthority(logger, host) {
+	const now = Date.now();
+	if (now < warnedAuthoritiesWindowStart || now - warnedAuthoritiesWindowStart >= 36e5) {
+		warnedAuthoritiesWindowStart = now;
+		warnedAuthorities.clear();
+		warnedAuthoritiesCapReported = false;
+	}
+	if (warnedAuthorities.has(host)) return;
+	if (warnedAuthorities.size >= 16) {
+		if (warnedAuthoritiesCapReported) return;
+		warnedAuthoritiesCapReported = true;
+		logger.warn("Reached %d distinct unusable request authorities within %d minutes; " + "further distinct values are not reported until that window ends", 16, WARNED_AUTHORITIES_WINDOW_MS / 6e4);
+		return;
+	}
+	warnedAuthorities.add(host);
+	const points = Array.from(host);
+	const shown = points.length > 128 ? `${points.slice(0, 128).join("")}…` : host;
+	logger.warn("Unusable request authority \"%s\"; the URL Fedify sees falls back to " + "\"%s\", so signatures covering the authority will not verify. Behind a " + "proxy this is a misbehaving X-Forwarded-Host; otherwise a client sent " + "it directly. Each distinct value is reported once per %d minutes, up " + "to %d values in that window", shown, PLACEHOLDER_HOST, WARNED_AUTHORITIES_WINDOW_MS / 6e4, 16);
+}
+
+//#endregion
+exports.PLACEHOLDER_HOST = PLACEHOLDER_HOST;
+exports.WARNED_AUTHORITIES_WINDOW_MS = WARNED_AUTHORITIES_WINDOW_MS;
+exports.warnUnusableAuthority = warnUnusableAuthority;
+//# sourceMappingURL=unusable_authority.cjs.map

package/dist/src/unusable_authority.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"unusable_authority.cjs","names":[],"sources":["../../src/unusable_authority.ts"],"sourcesContent":["/**\n * The warning for a request whose authority cannot be used, and the budget\n * that keeps it from flooding the log.\n *\n * Internal to the package: this module is reachable through none of the\n * published subpaths.  The two constants are exported for the tests, which\n * have to spend exactly this budget.\n *\n * @module\n */\nimport type { HttpContext } from \"@adonisjs/core/http\";\n\n/**\n * The host used when the request carries no usable authority.\n *\n * `FederationOptions.origin` covers the URLs Fedify *mints* — actor URIs,\n * activity IDs, collection URLs — so the placeholder never reaches a peer\n * through them, and only the path has to survive for routing.  It does not\n * cover verification: RFC 9421's `@authority`, `@target-uri` and `@scheme`\n * are derived from this URL, so a request signed over `@authority` fails to\n * verify while the placeholder stands in.  That is the cost of answering\n * instead of failing, and why the fallback is logged.\n */\nexport const PLACEHOLDER_HOST: string = \"localhost\";\n\n/**\n * Unusable authorities already warned about in the current window.  Any\n * client can trigger the warning through `Host`, so each distinct value is\n * reported once and the set is capped, leaving neither it nor the log\n * unbounded.  The key is the whole value, since two hostile values can share\n * a 128-character prefix.\n */\nconst warnedAuthorities = new Set<string>();\n\n/**\n * How many distinct values one window reports.\n */\nexport const WARNED_AUTHORITIES_LIMIT: number = 16;\n\n/**\n * How long the cap holds before the budget starts over.\n *\n * Without a window the cap is spent for the life of the process, and the\n * values that spend it are the client's to choose: sixteen junk `Host`\n * headers would silence the warning for good, so a proxy misconfigured an\n * hour later—every request falling back to {@link PLACEHOLDER_HOST}, every\n * signature over `@authority` failing to verify—would never be reported.\n * Starting over bounds the log at {@link WARNED_AUTHORITIES_LIMIT} lines per\n * window instead of over all time, which is what the log has to be protected\n * from, and leaves a standing misconfiguration visible.\n */\nexport const WARNED_AUTHORITIES_WINDOW_MS: number = 60 * 60 * 1000;\n\n/**\n * When the current window began; `0` so the first warning opens one.  It\n * advances lazily, on the first warning after the window has elapsed, rather\n * than from a timer that would hold the event loop open on a quiet process.\n */\nlet warnedAuthoritiesWindowStart = 0;\n\n/**\n * Whether the cap has already been reported in this window.  Reaching it\n * silences every later distinct value, which should not happen invisibly.\n */\nlet warnedAuthoritiesCapReported = false;\n\n/**\n * Reports an authority the request URL could not be built from, once per\n * distinct value and window.\n */\nexport function warnUnusableAuthority(\n  logger: HttpContext[\"logger\"],\n  host: string,\n): void {\n  const now = Date.now();\n  // `<` as well as the elapsed check: a backwards clock step (an NTP\n  // correction) would otherwise freeze the window until real time caught up\n  // with a start that lies in the future.\n  if (\n    now < warnedAuthoritiesWindowStart ||\n    now - warnedAuthoritiesWindowStart >= WARNED_AUTHORITIES_WINDOW_MS\n  ) {\n    warnedAuthoritiesWindowStart = now;\n    warnedAuthorities.clear();\n    warnedAuthoritiesCapReported = false;\n  }\n\n  if (warnedAuthorities.has(host)) return;\n  if (warnedAuthorities.size >= WARNED_AUTHORITIES_LIMIT) {\n    if (warnedAuthoritiesCapReported) return;\n    warnedAuthoritiesCapReported = true;\n    logger.warn(\n      \"Reached %d distinct unusable request authorities within %d minutes; \" +\n        \"further distinct values are not reported until that window ends\",\n      WARNED_AUTHORITIES_LIMIT,\n      WARNED_AUTHORITIES_WINDOW_MS / 60_000,\n    );\n    return;\n  }\n  warnedAuthorities.add(host);\n  // By code point, so an emoji straddling the boundary cannot leave a lone\n  // surrogate in the key or the log line.\n  const points = Array.from(host);\n  const shown = points.length > 128\n    ? `${points.slice(0, 128).join(\"\")}…`\n    : host;\n  logger.warn(\n    'Unusable request authority \"%s\"; the URL Fedify sees falls back to ' +\n      '\"%s\", so signatures covering the authority will not verify. Behind a ' +\n      \"proxy this is a misbehaving X-Forwarded-Host; otherwise a client sent \" +\n      \"it directly. Each distinct value is reported once per %d minutes, up \" +\n      \"to %d values in that window\",\n    shown,\n    PLACEHOLDER_HOST,\n    WARNED_AUTHORITIES_WINDOW_MS / 60_000,\n    WARNED_AUTHORITIES_LIMIT,\n  );\n}\n"],"mappings":";;;;;;;;;;;;;AAuBA,MAAa,mBAA2B;;;;;;;;AASxC,MAAM,oBAAoB,IAAI,IAAY;;;;AAK1C,MAAa,2BAAmC;;;;;;;;;;;;;AAchD,MAAa,+BAAuC,KAAK,KAAK;;;;;;AAO9D,IAAI,+BAA+B;;;;;AAMnC,IAAI,+BAA+B;;;;;AAMnC,SAAgB,sBACd,QACA,MACM;CACN,MAAM,MAAM,KAAK,IAAI;CAIrB,IACE,MAAM,gCACN,MAAM,sCACN;EACA,+BAA+B;EAC/B,kBAAkB,MAAM;EACxB,+BAA+B;CACjC;CAEA,IAAI,kBAAkB,IAAI,IAAI,GAAG;CACjC,IAAI,kBAAkB,YAAkC;EACtD,IAAI,8BAA8B;EAClC,+BAA+B;EAC/B,OAAO,KACL,yEACE,uEAEF,+BAA+B,GACjC;EACA;CACF;CACA,kBAAkB,IAAI,IAAI;CAG1B,MAAM,SAAS,MAAM,KAAK,IAAI;CAC9B,MAAM,QAAQ,OAAO,SAAS,MAC1B,GAAG,OAAO,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,KACjC;CACJ,OAAO,KACL,0EACE,4EACA,2EACA,0EACA,+BACF,OACA,kBACA,+BAA+B,OAEjC;AACF"}