@zerotal/core 1.8.1 → 1.10.0

package/src/middleware/RateLimiter.ts

@@ -4,7 +4,7 @@
  * later attached to routes or checked manually as `ThrottleMiddleware`.
  */
 import type { HttpContext } from "../pipeline/HttpContext.ts";
-import { ThrottleMiddleware } from "./ThrottleMiddleware.ts";
+import { ThrottleMiddleware, _clientIp, _markIpDerived } from "./ThrottleMiddleware.ts";
 import type { ThrottleOptions } from "./ThrottleMiddleware.ts";
 
 /**
@@ -14,7 +14,19 @@ import type { ThrottleOptions } from "./ThrottleMiddleware.ts";
 export class LimiterDefinition {
   private _max = 60;
   private _window = 60;
-  private _keyFn?: (ctx: HttpContext) => string;
+  private _trustedProxies?: number;
+
+  /**
+   * How this limiter keys its buckets, recorded rather than resolved.
+   *
+   * The built-in strategies all fall back to the client address, and resolving that
+   * needs `trustedProxies` — which the fluent API may not have been told yet when
+   * `.byIp()` runs. Keeping the *decision* here and building the resolver in
+   * {@link toMiddlewareClass} means `.byIp().trustedProxies(1)` and
+   * `.trustedProxies(1).byIp()` mean the same thing, which is the only defensible
+   * answer for a builder.
+   */
+  private _key: KeyStrategy = { kind: "default" };
 
   constructor(private readonly _name: string) {}
 
@@ -30,9 +42,33 @@ export class LimiterDefinition {
     return this;
   }
 
-  /** Custom key resolver — defaults to client IP. */
+  /**
+   * Number of trusted reverse proxies in front of this server.
+   *
+   * Needed by every strategy that can fall back to the client address, which is all
+   * the built-in ones. Without it the address used is the socket's — the *proxy's*,
+   * behind a reverse proxy, so every visitor shares one bucket and the limiter
+   * inverts into the thing it was installed to prevent.
+   *
+   * @param count - How many proxies sit in front; see {@link ThrottleOptions.trustedProxies}.
+   *
+   * @example
+   * RateLimiter.for("login").limit(5).every(60).trustedProxies(1).register();
+   */
+  trustedProxies(count: number): this {
+    this._trustedProxies = count;
+    return this;
+  }
+
+  /**
+   * Custom key resolver — defaults to client IP.
+   *
+   * Whatever this returns is the bucket. If it derives from the client address,
+   * resolve that with `ctx.ip()` plus your own proxy handling, or prefer
+   * {@link byIp}, which honours {@link trustedProxies} for you.
+   */
   by(fn: (ctx: HttpContext) => string): this {
-    this._keyFn = fn;
+    this._key = { kind: "custom", fn };
     return this;
   }
 
@@ -45,10 +81,7 @@ export class LimiterDefinition {
    * RateLimiter.for('api').limit(1000).every(3600).byUser().register();
    */
   byUser(): this {
-    this._keyFn = (ctx) => {
-      const user = (ctx as unknown as Record<string, unknown>).user as { id?: number } | undefined;
-      return user?.id !== undefined ? `user:${user.id}` : `ip:${_resolveIp(ctx)}`;
-    };
+    this._key = { kind: "user" };
     return this;
   }
 
@@ -60,10 +93,7 @@ export class LimiterDefinition {
    * RateLimiter.for('api').limit(500).every(60).byApiKey('x-api-key').register();
    */
   byApiKey(header = "x-api-key"): this {
-    this._keyFn = (ctx) => {
-      const key = ctx.header(header);
-      return key ? `apikey:${key}` : `ip:${_resolveIp(ctx)}`;
-    };
+    this._key = { kind: "apiKey", header };
     return this;
   }
 
@@ -73,7 +103,7 @@ export class LimiterDefinition {
    * through the fluent API.
    */
   byIp(): this {
-    this._keyFn = (ctx) => `ip:${_resolveIp(ctx)}`;
+    this._key = { kind: "ip" };
     return this;
   }
 
@@ -97,7 +127,12 @@ export class LimiterDefinition {
       maxAttempts: this._max,
       windowSeconds: this._window,
     };
-    if (this._keyFn) options.keyResolver = this._keyFn;
+    if (this._trustedProxies !== undefined) options.trustedProxies = this._trustedProxies;
+
+    // `default` deliberately sets no resolver: ThrottleMiddleware's own is already
+    // proxy-aware, and every resolver set here has to be too.
+    const resolver = _resolverFor(this._key, this._trustedProxies);
+    if (resolver) options.keyResolver = resolver;
     return ThrottleMiddleware.with(options);
   }
 
@@ -114,14 +149,62 @@ export class LimiterDefinition {
   }
 }
 
-/** Resolve the best available client IP from the context. */
-function _resolveIp(ctx: HttpContext): string {
-  return (
-    ctx.ip() ??
-    ctx.header("x-forwarded-for")?.split(",")[0]?.trim() ??
-    ctx.header("x-real-ip") ??
-    "unknown"
-  );
+/** How a limiter decides which bucket a request belongs to. */
+type KeyStrategy =
+  | { kind: "default" }
+  | { kind: "ip" }
+  | { kind: "user" }
+  | { kind: "apiKey"; header: string }
+  | { kind: "custom"; fn: (ctx: HttpContext) => string };
+
+/**
+ * Build the key resolver for a strategy, or `undefined` to let `ThrottleMiddleware`
+ * use its own.
+ *
+ * Every branch that can end up keying on an address goes through `_clientIp` with the
+ * proxy count, and is marked so `zt doctor` still audits it. The previous versions
+ * used a private helper that read the socket address and fell back to the *leftmost*
+ * `X-Forwarded-For` entry with no proxy count at all — so behind a reverse proxy
+ * every visitor keyed on the proxy's own address and shared a single bucket. A named
+ * `login` limiter of five attempts a minute was five attempts a minute across the
+ * entire user base, and one attacker locked everybody out.
+ *
+ * @param strategy - What the builder recorded.
+ * @param trustedProxies - How many proxies sit in front, if the builder was told.
+ */
+function _resolverFor(
+  strategy: KeyStrategy,
+  trustedProxies: number | undefined,
+): ((ctx: HttpContext) => string) | undefined {
+  switch (strategy.kind) {
+    case "default":
+      return undefined;
+
+    case "ip":
+      return _markIpDerived((ctx) => `ip:${_clientIp(ctx, trustedProxies)}`);
+
+    case "user":
+      // Marked, because the *unauthenticated* half of this keys on an address —
+      // which is the half a rate limiter on a login form exists for.
+      return _markIpDerived((ctx) => {
+        const user = (ctx as unknown as Record<string, unknown>).user as
+          { id?: number } | undefined;
+        return user?.id !== undefined ? `user:${user.id}` : `ip:${_clientIp(ctx, trustedProxies)}`;
+      });
+
+    case "apiKey": {
+      const { header } = strategy;
+      return _markIpDerived((ctx) => {
+        const key = ctx.header(header);
+        return key ? `apikey:${key}` : `ip:${_clientIp(ctx, trustedProxies)}`;
+      });
+    }
+
+    case "custom":
+      // Unmarked on purpose: an app-supplied resolver is the app's to reason about,
+      // and most of them key on something no proxy can affect.
+      return strategy.fn;
+  }
 }
 
 /**

package/src/middleware/SecureHeadersMiddleware.ts

@@ -14,48 +14,48 @@ export interface SecureHeadersOptions {
    * `Content-Security-Policy` header value.
    * Omitted by default — set this to a policy appropriate for your application.
    */
-  contentSecurityPolicy?: string;
+  contentSecurityPolicy?: string | undefined;
 
   /**
    * `Strict-Transport-Security` max-age in seconds.
    * Defaults to 1 year (31 536 000 s). Set to `0` to disable HSTS entirely.
    * Only emitted when `secure: true` to avoid HSTS issues in plain-HTTP dev environments.
    */
-  hstsMaxAge?: number;
+  hstsMaxAge?: number | undefined;
 
   /**
    * Include `includeSubDomains` in the HSTS header. Defaults to `true`.
    */
-  hstsIncludeSubDomains?: boolean;
+  hstsIncludeSubDomains?: boolean | undefined;
 
   /**
    * Set the HSTS `preload` directive. Defaults to `false`.
    * Only set this if you have registered the domain with the HSTS preload list.
    */
-  hstsPreload?: boolean;
+  hstsPreload?: boolean | undefined;
 
   /**
    * Enable HSTS and the `Secure` flag on the XSRF-TOKEN cookie.
    * Default `false` — set to `true` in production when serving over HTTPS.
    */
-  secure?: boolean;
+  secure?: boolean | undefined;
 
   /**
    * `X-Frame-Options` value. Defaults to `'SAMEORIGIN'`.
    * Set to `'DENY'` for maximum protection, or `false` to omit the header.
    */
-  frameOptions?: "DENY" | "SAMEORIGIN" | false;
+  frameOptions?: "DENY" | "SAMEORIGIN" | false | undefined;
 
   /**
    * `Referrer-Policy` value. Defaults to `'strict-origin-when-cross-origin'`.
    */
-  referrerPolicy?: string;
+  referrerPolicy?: string | undefined;
 
   /**
    * `Permissions-Policy` header value.
    * Defaults to a conservative policy disabling sensitive APIs.
    */
-  permissionsPolicy?: string | false;
+  permissionsPolicy?: string | false | undefined;
 }
 
 const DEFAULT_PERMISSIONS_POLICY = "camera=(), microphone=(), geolocation=(), payment=()";

package/src/middleware/ThrottleMiddleware.ts

@@ -14,12 +14,12 @@ export interface ThrottleOptions {
   /** Maximum number of requests allowed within the window. */
   maxAttempts: number;
   /** Time window in seconds. Defaults to 60. */
-  windowSeconds?: number;
+  windowSeconds?: number | undefined;
   /**
    * Custom key resolver — defaults to client IP address.
    * Use this to rate-limit by user ID, API key, route, etc.
    */
-  keyResolver?: (ctx: HttpContext) => string;
+  keyResolver?: ((ctx: HttpContext) => string) | undefined;
   /**
    * Number of trusted reverse proxies in front of this server.
    *
@@ -35,7 +35,7 @@ export interface ThrottleOptions {
    * // Behind one load balancer:
    * ThrottleMiddleware.with({ maxAttempts: 60, trustedProxies: 1 })
    */
-  trustedProxies?: number;
+  trustedProxies?: number | undefined;
 }
 
 interface HitRecord {
@@ -226,7 +226,60 @@ export function _pruneStore(store: Map<string, HitRecord>, now: number): void {
   for (let i = 0; i < live.length - _MAX_KEYS; i++) store.delete(live[i]![0]);
 }
 
-function _clientIp(ctx: HttpContext, trustedProxies?: number): string {
+/**
+ * A `keyResolver` that derives its key from the client's address, tagged so the
+ * doctor can tell it apart from one that does not.
+ *
+ * `zt doctor` exempts a throttle with a custom `keyResolver` from the
+ * `trustedProxies` check, and that is right for a limiter keyed on a user id or a
+ * tenant — no proxy can affect it. It is exactly wrong for one keyed on an IP,
+ * which is what `RateLimiter`'s `.byIp()`, `.byUser()` and `.byApiKey()` build.
+ * Unmarked, those slipped past the one check that exists to catch them.
+ *
+ * @internal
+ */
+export const _IP_DERIVED_KEY = Symbol.for("zerotal.throttle.ipDerivedKey");
+
+/** Shape of a resolver carrying the marker. @internal */
+type MaybeMarked = { [_IP_DERIVED_KEY]?: boolean };
+
+/**
+ * Tag `resolver` as deriving its key from the client address.
+ *
+ * @param resolver - The key resolver to mark.
+ * @returns The same function, marked.
+ * @internal
+ */
+export function _markIpDerived<T extends (ctx: HttpContext) => string>(resolver: T): T {
+  (resolver as T & MaybeMarked)[_IP_DERIVED_KEY] = true;
+  return resolver;
+}
+
+/**
+ * Whether `resolver` keys on the client address, and so still needs `trustedProxies`.
+ *
+ * @param resolver - The key resolver to test, if there is one.
+ * @internal
+ */
+export function _isIpDerived(resolver: unknown): boolean {
+  return typeof resolver === "function" && (resolver as MaybeMarked)[_IP_DERIVED_KEY] === true;
+}
+
+/**
+ * The client's address, honouring `trustedProxies`.
+ *
+ * Exported so `RateLimiter`'s built-in key resolvers use the same rule rather than
+ * their own. Theirs read the socket address and fell back to the *leftmost*
+ * `X-Forwarded-For` entry with no proxy count at all — so behind a reverse proxy
+ * every visitor keyed on the proxy's address and shared one bucket, and a named
+ * `login` limiter of five attempts a minute was five attempts a minute for the whole
+ * user base. One attacker locked everybody out.
+ *
+ * @param ctx - The request to resolve an address for.
+ * @param trustedProxies - How many proxies sit in front; see {@link ThrottleOptions.trustedProxies}.
+ * @internal
+ */
+export function _clientIp(ctx: HttpContext, trustedProxies?: number): string {
   // Default (undefined) and an explicit 0 both mean "not behind a trusted proxy": read the raw
   // socket address, which cannot be spoofed.
   //

package/src/middleware/WebhookMiddleware.ts

@@ -13,32 +13,32 @@ export interface WebhookOptions {
   /** HMAC secret used to verify the signature. */
   secret: string;
   /** Request header that carries the signature. Default: 'x-webhook-signature'. */
-  header?: string;
+  header?: string | undefined;
   /** HMAC algorithm. Default: 'sha256'. */
-  algorithm?: "sha256" | "sha1" | "sha512";
+  algorithm?: "sha256" | "sha1" | "sha512" | undefined;
   /**
    * Expected signature prefix that will be stripped before comparison
    * (e.g. `'sha256='` for GitHub). Default: `''`.
    */
-  prefix?: string;
+  prefix?: string | undefined;
   /**
    * Max age in seconds for replay-attack protection.
    * Requires `timestampHeader` (or `format: 'stripe'`). Disabled when `undefined`.
    */
-  tolerance?: number;
+  tolerance?: number | undefined;
   /**
    * Header that carries the Unix timestamp of the request.
    * When present the signed payload becomes `{timestamp}{timestampSeparator}{body}`.
    */
-  timestampHeader?: string;
+  timestampHeader?: string | undefined;
   /** Separator between timestamp and body in the signed payload. Default: `'.'`. */
-  timestampSeparator?: string;
+  timestampSeparator?: string | undefined;
   /**
    * Header format.
    * - `'raw'` (default) — signature is the full (or prefix-stripped) header value.
    * - `'stripe'` — header is parsed as `t=<ts>,v1=<sig>` (Stripe-Signature style).
    */
-  format?: "raw" | "stripe";
+  format?: "raw" | "stripe" | undefined;
 }
 
 /**

package/src/pipeline/ContextRegistry.ts

@@ -32,11 +32,21 @@
  * still compiles and returns `unknown`.
  *
  * @category Extension registries
+ *
+ * @internal
  */
 export interface ContextRegistry {}
 
-/** Union of every registered context key. `never` until a package augments {@link ContextRegistry}. */
+/**
+ * Union of every registered context key. `never` until a package augments {@link ContextRegistry}.
+ *
+ * @internal
+ */
 export type ContextKey = keyof ContextRegistry;
 
-/** The value type stored under a registered context key. */
+/**
+ * The value type stored under a registered context key.
+ *
+ * @internal
+ */
 export type ContextValue<K extends ContextKey> = ContextRegistry[K];

package/src/pipeline/HttpContext.ts

@@ -31,6 +31,8 @@ type AnyViewComponent = (ctx: HttpContext<any>, props: any) => ViewMarkup | Prom
 /**
  * Minimal Bun server interface needed for socket-level IP resolution.
  * Duck-typed so HttpContext has no hard dependency on Bun's global types.
+ *
+ * @internal
  */
 export interface RequestIPProvider {
   requestIP(req: Request): { address: string; family: string; port: number } | null;
@@ -874,6 +876,8 @@ const _prototypeMethods: ReadonlyArray<[string, (...args: unknown[]) => unknown]
  * @param origin - The current request origin to match against.
  * @returns The same-origin `url`, or `undefined` when it is absent, unparseable,
  * or points to a different origin.
+ *
+ * @internal
  */
 export function safeRedirectPath(
   url: string | null | undefined,

package/src/pipeline/currentPage.ts

@@ -5,6 +5,8 @@ import { HttpContext } from "./HttpContext.ts";
  *
  * @param pageName - The paginator's name, so one request can drive several independently.
  * @returns The 1-based page, or `undefined` to fall back to the query string.
+ *
+ * @internal
  */
 export type CurrentPageResolver = (pageName: string) => number | undefined;
 
@@ -21,6 +23,8 @@ export type CurrentPageResolver = (pageName: string) => number | undefined;
  * another one. Keep it that way — a module-level slot would not be request-scoped.
  *
  * @param resolver - Called with the paginator name; return `undefined` to defer to the query string.
+ *
+ * @internal
  */
 export function setCurrentPageResolver(resolver: CurrentPageResolver): void {
   const ctx = HttpContext.tryGet();

package/src/pipeline/types.ts

@@ -74,6 +74,8 @@ export interface Pipe<T> {
 /**
  * A payload that can carry a `Response`. Pipes set `response` and return the
  * payload to short-circuit; the pipeline terminal reads it back.
+ *
+ * @internal
  */
 export interface HasResponse {
   response: Response | undefined;

package/src/router/FileRouter.ts

@@ -23,6 +23,8 @@ export type { FileHandler };
 /**
  * Per-method middleware map for a route file's `export const middleware`.
  * `ALL` applies to every method the file handles; the per-verb arrays add to it.
+ *
+ * @internal
  */
 export interface RouteMethodMiddleware {
   ALL?: MiddlewareClass[];
@@ -45,6 +47,7 @@ export type RouteMiddleware = MiddlewareClass[] | RouteMethodMiddleware;
 
 /** Shape of a route module. `default` may be a FileHandler or a ViewComponent;
  *  `layout` overrides the directory `_layout` (null = no layout). */
+/** @internal */
 export interface RouteModule {
   default?: FileHandler | ViewComponent;
   GET?: FileHandler;
@@ -57,7 +60,11 @@ export interface RouteModule {
   middleware?: RouteMiddleware;
 }
 
-/** Optional `export const meta = { GET: { name: 'users.show' } }` in route files. */
+/**
+ * Optional `export const meta = { GET: { name: 'users.show' } }` in route files.
+ *
+ * @internal
+ */
 export interface RouteFileMeta {
   GET?: { name?: string };
   POST?: { name?: string };
@@ -66,7 +73,11 @@ export interface RouteFileMeta {
   DELETE?: { name?: string };
 }
 
-/** Shape of a `_middleware.ts` file. */
+/**
+ * Shape of a `_middleware.ts` file.
+ *
+ * @internal
+ */
 export interface MiddlewareModule {
   middleware: MiddlewareClass[];
 }
@@ -75,6 +86,8 @@ export interface MiddlewareModule {
 
 /**
  * Context handed to a file-route resolver for each scanned route file.
+ *
+ * @internal
  */
 export interface FileRouteContext {
   /** URL path derived from the file location (e.g. '/users/:id'). */
@@ -105,6 +118,8 @@ export interface FileRouteContext {
  *   Router.flow(urlPath, PageClass, middleware);
  *   return true;
  * });
+ *
+ * @internal
  */
 export type FileRouteResolver = (ctx: FileRouteContext) => boolean;
 
@@ -112,6 +127,7 @@ const _fileRouteResolvers: FileRouteResolver[] = [];
 
 /** Register a resolver. Call from a provider's onRegister() so it is in place
  *  before Application.boot() scans file routes. */
+/** @internal */
 export function registerFileRouteResolver(resolver: FileRouteResolver): void {
   _fileRouteResolvers.push(resolver);
 }
@@ -390,6 +406,8 @@ async function _collectLayout(
  *                  creates a fresh module namespace instead of returning the
  *                  cached version.  Omit on first boot.
  * @returns The number of individual method handlers registered.
+ *
+ * @internal
  */
 export async function scanFileRoutes(baseDir: string, reloadId?: string): Promise<number> {
   const absoluteBase = _resolveAbsoluteBase(baseDir);

package/src/router/Route.ts

@@ -18,6 +18,7 @@ export type MiddlewareClass = new (...args: any[]) => Pipe<HttpContext>;
 /** Handler signature for file-based routes. Receives the request {@link HttpContext}
  *  directly — route params and resolved model bindings live on `ctx.params`. May return
  *  a Response or mutate `ctx` directly. */
+/** @internal */
 export type FileHandler = (ctx: HttpContext) => void | Response | Promise<void | Response>;
 
 /**
@@ -49,6 +50,8 @@ export type ViewLayout = (ctx: HttpContext, props: { children: unknown }) => unk
  * Receives the raw string param value and the current context;
  * must return (or resolve to) the model instance.
  * Throw `ModelNotFoundError` (or any 404 error) when the record does not exist.
+ *
+ * @internal
  */
 export type ModelBindingResolver = (value: string, ctx: HttpContext) => Promise<unknown>;
 

package/src/router/RouteHandler.ts

@@ -85,7 +85,7 @@ export interface DispatchOptions {
   exceptionHandler?: ExceptionHandler | undefined;
   providerHooks?: ProviderHooks | undefined;
   /** Configure the freshly created context (params, route info) before dispatch. */
-  configure?: (ctx: HttpContext) => void;
+  configure?: ((ctx: HttpContext) => void) | undefined;
   /**
    * Path-specific work: run the pipeline and produce the response (or leave it
    * on `ctx.response`). Errors thrown here are rendered by the exception handler.
@@ -95,7 +95,7 @@ export interface DispatchOptions {
    * Render an unhandled error to a Response. Defaults to reporting + rendering
    * through `exceptionHandler` when present, else `ExceptionHandler.defaultRender`.
    */
-  renderError?: (error: unknown, ctx: HttpContext) => Promise<Response>;
+  renderError?: ((error: unknown, ctx: HttpContext) => Promise<Response>) | undefined;
 }
 
 /**

package/src/router/Router.ts

@@ -124,13 +124,13 @@ type CompiledRoutes = Record<string, Record<string, RouteHandlerFn> | Response>;
 /** Options for {@link Router.static}. */
 export interface StaticOptions {
   /** Extra response headers applied to every served file (e.g. Cache-Control). */
-  headers?: Record<string, string>;
+  headers?: Record<string, string> | undefined;
   /**
    * When true (default) every file in the directory is pre-registered at
    * compile() time as a static `Response`, so Bun serves it without invoking
    * JS. Set false to fall back to the per-request lookup in Application.fetch.
    */
-  eager?: boolean;
+  eager?: boolean | undefined;
 }
 
 type StaticDir = { prefix: string; rootDir: string; options?: StaticOptions | undefined };
@@ -143,7 +143,7 @@ type MarkdownDir = {
 /** Options for Router.group(). All fields are optional. */
 export interface GroupOptions {
   /** URL prefix applied to every route registered inside the group. */
-  prefix?: string;
+  prefix?: string | undefined;
   /**
    * Middleware to prepend to every route inside the group.
    * Accepts a named group (string), an array of names/classes, or middleware class(es) directly.
@@ -152,9 +152,9 @@ export interface GroupOptions {
    * Router.group({ middleware: 'api' }, () => { ... });
    * Router.group({ middleware: ['web', AuthMiddleware] }, () => { ... });
    */
-  middleware?: string | string[] | MiddlewareClass | MiddlewareClass[];
+  middleware?: string | string[] | MiddlewareClass | MiddlewareClass[] | undefined;
   /** Host pattern; routes inside the group only match this host (e.g. ':tenant.app.com'). */
-  domain?: string;
+  domain?: string | undefined;
 }
 
 // ── Internal helpers ──────────────────────────────────────────────────────────
@@ -178,6 +178,8 @@ function _toResolver(modelOrResolver: ModelClass | ModelBindingResolver): ModelB
  * All mutable router state in one swappable object: registered routes, the
  * active group prefix/middleware/domain, static and markdown directories, named
  * routes, and named middleware groups.
+ *
+ * @internal
  */
 export class RouterState {
   routes = new Map<string, RouteDefinition>();

package/src/router/domain.ts

@@ -6,6 +6,7 @@
  * exposed on the request via `ctx.subdomains`.
  */
 
+/** @internal */
 export interface CompiledDomain {
   /** The original pattern, e.g. ':tenant.app.com'. */
   source: string;

package/src/router/registry.ts

@@ -23,7 +23,11 @@
  * updates with it.
  */
 
-/** A value that can be substituted into a `:param` segment. */
+/**
+ * A value that can be substituted into a `:param` segment.
+ *
+ * @internal
+ */
 export type RouteParamValue = string | number;
 
 /** The loose param bag accepted by the untyped `route()` overload. */
@@ -68,7 +72,11 @@ export type RouteName = Extract<keyof RouteRegistry, string>;
  */
 export type RouteTarget = [RouteName] extends [never] ? string : RouteName;
 
-/** The URL pattern registered for route `N`, or plain `string` when it isn't a known name. */
+/**
+ * The URL pattern registered for route `N`, or plain `string` when it isn't a known name.
+ *
+ * @internal
+ */
 export type RoutePattern<N extends string> = N extends RouteName
   ? RouteRegistry[N] extends string
     ? RouteRegistry[N]
@@ -101,6 +109,8 @@ export type RouteParams<N extends string> = Prettify<ParamsOf<RoutePattern<N>>>;
  * generated, loose before that. Used by the helpers that take params without
  * being able to take `route()`'s rest-tuple — `redirect().to(name, params,
  * status)` and Flow's `redirectRoute`.
+ *
+ * @internal
  */
 export type RouteParamsArg<N extends string> = [RouteName] extends [never]
   ? RouteParamValues

package/src/security/redactGraph.ts

@@ -48,7 +48,7 @@ export interface RedactGraphOptions {
    * `JSON.stringify` drops the key it sits under, and a debugging tool that
    * silently omits a field is worse than one that says `‹fn›`.
    */
-  flatten?: (value: unknown) => string | undefined;
+  flatten?: ((value: unknown) => string | undefined) | undefined;
 }
 
 /**