@zerotal/core 1.0.0

package/src/middleware/RateLimiter.ts

@@ -0,0 +1,255 @@
+/**
+ * The named rate-limiter registry and its fluent definition builder. Limiters
+ * are defined once at boot (`RateLimiter.for('api').limit(…).register()`) and
+ * later attached to routes or checked manually as `ThrottleMiddleware`.
+ */
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+import { ThrottleMiddleware } from "./ThrottleMiddleware.ts";
+import type { ThrottleOptions } from "./ThrottleMiddleware.ts";
+
+/**
+ * Fluent rate-limiter definition.
+ * Build one via `RateLimiter.for('name')` then register with `.register()`.
+ */
+export class LimiterDefinition {
+  private _max = 60;
+  private _window = 60;
+  private _keyFn?: (ctx: HttpContext) => string;
+
+  constructor(private readonly _name: string) {}
+
+  /** Maximum number of requests in the window. */
+  limit(max: number): this {
+    this._max = max;
+    return this;
+  }
+
+  /** Window duration in seconds. */
+  every(seconds: number): this {
+    this._window = seconds;
+    return this;
+  }
+
+  /** Custom key resolver — defaults to client IP. */
+  by(fn: (ctx: HttpContext) => string): this {
+    this._keyFn = fn;
+    return this;
+  }
+
+  /**
+   * Key by the authenticated user's ID.
+   * Unauthenticated requests fall back to the client IP so they are still
+   * rate-limited independently from each other.
+   *
+   * @example
+   * 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)}`;
+    };
+    return this;
+  }
+
+  /**
+   * Key by an API key header value.
+   * Requests that omit the header fall back to client IP.
+   *
+   * @example
+   * 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)}`;
+    };
+    return this;
+  }
+
+  /**
+   * Key by client IP address (explicitly named; this is already the default).
+   * Useful to make intent explicit when combining with other `.by*()` calls
+   * through the fluent API.
+   */
+  byIp(): this {
+    this._keyFn = (ctx) => `ip:${_resolveIp(ctx)}`;
+    return this;
+  }
+
+  /** Register this limiter with the global RateLimiter registry. */
+  register(): this {
+    RateLimiter._register(this._name, this);
+    return this;
+  }
+
+  /**
+   * Build a dedicated `ThrottleMiddleware` **subclass** for this definition.
+   *
+   * A subclass rather than a bare instance for two reasons. First, routes and
+   * `Pipeline.through()` take middleware *classes* and call `new PipeClass()`; handing them an
+   * instance threw `TypeError: ThrottleMiddleware is not a constructor` on every request.
+   * Second, hit counters are keyed on the concrete class, so giving each named limiter its own
+   * subclass is what keeps `login` and `api` counting into separate buckets.
+   */
+  toMiddlewareClass(): new () => ThrottleMiddleware {
+    const options: ThrottleOptions = {
+      maxAttempts: this._max,
+      windowSeconds: this._window,
+    };
+    if (this._keyFn) options.keyResolver = this._keyFn;
+    return ThrottleMiddleware.with(options);
+  }
+
+  /**
+   * Build a `ThrottleMiddleware` instance from this definition.
+   *
+   * Prefer {@link toMiddlewareClass} for anything that goes into a route or a pipeline. This
+   * remains for the imperative API (`RateLimiter.tooManyAttempts`, `resetFor`), which needs a
+   * live object; it shares counters with the class because both are the same subclass.
+   */
+  toMiddleware(): ThrottleMiddleware {
+    const Cls = this.toMiddlewareClass();
+    return new Cls();
+  }
+}
+
+/** 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"
+  );
+}
+
+/**
+ * Named rate-limiter registry.
+ *
+ * @example
+ * // In a ServiceProvider (boot time):
+ * RateLimiter.for('api')
+ *   .limit(120).every(60)
+ *   .by(ctx => String(ctx.user?.id ?? ctx.request.headers.get('x-forwarded-for')))
+ *   .register();
+ *
+ * RateLimiter.for('login').limit(5).every(60).register();
+ *
+ * // On a route:
+ * Router.post('/login', AuthController, 'login', [
+ *   RateLimiter.middleware('login'),
+ * ]);
+ *
+ * // Manual check:
+ * if (RateLimiter.tooManyAttempts('login', ctx)) {
+ *   ctx.response = Response.json({ message: 'Too Many Requests' }, { status: 429 });
+ *   return;
+ * }
+ */
+export class RateLimiter {
+  private static _definitions = new Map<string, LimiterDefinition>();
+  // Per-named-limiter ThrottleMiddleware subclasses (keyed by name). One class per limiter
+  // keeps their hit counters isolated, since the store is keyed on the concrete class.
+  private static _middlewareClasses = new Map<string, new () => ThrottleMiddleware>();
+  // A live instance of each class, for the imperative tooManyAttempts()/resetFor() API.
+  // Shares counters with the class above — same constructor, same bucket.
+  private static _middlewares = new Map<string, ThrottleMiddleware>();
+
+  /** @internal Called by `LimiterDefinition.register()`. */
+  static _register(name: string, definition: LimiterDefinition): void {
+    const Cls = definition.toMiddlewareClass();
+    RateLimiter._definitions.set(name, definition);
+    RateLimiter._middlewareClasses.set(name, Cls);
+    RateLimiter._middlewares.set(name, new Cls());
+  }
+
+  /**
+   * Start building a named limiter.
+   * Call `.register()` at the end to make it available globally.
+   *
+   * @example
+   * RateLimiter.for('api').limit(100).every(60).register();
+   */
+  static for(name: string): LimiterDefinition {
+    return new LimiterDefinition(name);
+  }
+
+  /**
+   * Get the ThrottleMiddleware for a registered named limiter.
+   * Throws if the limiter was never registered.
+   *
+   * @example
+   * Router.post('/login', AuthController, 'login', [RateLimiter.middleware('login')]);
+   */
+  static middleware(name: string): new () => ThrottleMiddleware {
+    const Cls = RateLimiter._middlewareClasses.get(name);
+    if (!Cls) throw new Error(`[Zerotal] RateLimiter "${name}" has not been registered.`);
+    return Cls;
+  }
+
+  /**
+   * The live `ThrottleMiddleware` instance backing a registered limiter.
+   *
+   * Only needed when you want to call `handle()`/`reset()` directly. Route and pipeline
+   * registration wants {@link middleware}, which returns the class.
+   *
+   * @internal
+   */
+  static _instance(name: string): ThrottleMiddleware {
+    const middleware = RateLimiter._middlewares.get(name);
+    if (!middleware) throw new Error(`[Zerotal] RateLimiter "${name}" has not been registered.`);
+    return middleware;
+  }
+
+  /**
+   * Manually record a hit and check whether the limit is exceeded.
+   * Returns `true` when the caller should be throttled.
+   *
+   * Unlike the middleware, this does NOT automatically send a 429 response —
+   * the caller decides how to handle the throttle condition.
+   *
+   * @example
+   * if (RateLimiter.tooManyAttempts('login', ctx)) {
+   *   ctx.response = Response.json({ message: 'Too Many Requests' }, { status: 429 });
+   *   return;
+   * }
+   */
+  static async tooManyAttempts(name: string, ctx: HttpContext): Promise<boolean> {
+    const middleware = RateLimiter._middlewares.get(name);
+    if (!middleware) throw new Error(`[Zerotal] RateLimiter "${name}" has not been registered.`);
+
+    let throttled = false;
+    await middleware.handle(ctx, async () => {
+      // Reaching this callback means the request was not throttled.
+      ctx.response = new Response("ok");
+      return ctx.response;
+    });
+    throttled = ctx.response?.status === 429;
+    // Discard the synthetic "ok" response so the real handler can set its own.
+    ctx.response = undefined;
+    return throttled;
+  }
+
+  /**
+   * Reset the rate-limit counter for a specific key within a named limiter.
+   *
+   * Use this after a successful action to allow the actor to start fresh —
+   * e.g. clear failed login attempts after a successful authentication.
+   *
+   * @example
+   * // In your LoginController:
+   * await RateLimiter.resetFor('login', ctx);
+   */
+  static resetFor(name: string, ctx: HttpContext): void {
+    const middleware = RateLimiter._middlewares.get(name);
+    if (!middleware) throw new Error(`[Zerotal] RateLimiter "${name}" has not been registered.`);
+    middleware.resetKey(ctx);
+  }
+
+  /** Remove all registered limiters (useful in tests). */
+  static clear(): void {
+    RateLimiter._definitions.clear();
+    RateLimiter._middlewares.clear();
+  }
+}

package/src/middleware/SecureHeadersMiddleware.ts

@@ -0,0 +1,127 @@
+/**
+ * Security-headers middleware: adds a sensible baseline of protective response
+ * headers (`X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`,
+ * `Permissions-Policy`, optional CSP and HSTS) to every response.
+ */
+import type { NextFn } from "../pipeline/types.ts";
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+import { BaseMiddleware } from "./BaseMiddleware.ts";
+import { withHeaders } from "../http/withHeaders.ts";
+import { config } from "../helpers/config.ts";
+
+export interface SecureHeadersOptions {
+  /**
+   * `Content-Security-Policy` header value.
+   * Omitted by default — set this to a policy appropriate for your application.
+   */
+  contentSecurityPolicy?: string;
+
+  /**
+   * `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;
+
+  /**
+   * Include `includeSubDomains` in the HSTS header. Defaults to `true`.
+   */
+  hstsIncludeSubDomains?: boolean;
+
+  /**
+   * Set the HSTS `preload` directive. Defaults to `false`.
+   * Only set this if you have registered the domain with the HSTS preload list.
+   */
+  hstsPreload?: boolean;
+
+  /**
+   * Enable HSTS and the `Secure` flag on the XSRF-TOKEN cookie.
+   * Default `false` — set to `true` in production when serving over HTTPS.
+   */
+  secure?: boolean;
+
+  /**
+   * `X-Frame-Options` value. Defaults to `'SAMEORIGIN'`.
+   * Set to `'DENY'` for maximum protection, or `false` to omit the header.
+   */
+  frameOptions?: "DENY" | "SAMEORIGIN" | false;
+
+  /**
+   * `Referrer-Policy` value. Defaults to `'strict-origin-when-cross-origin'`.
+   */
+  referrerPolicy?: string;
+
+  /**
+   * `Permissions-Policy` header value.
+   * Defaults to a conservative policy disabling sensitive APIs.
+   */
+  permissionsPolicy?: string | false;
+}
+
+const DEFAULT_PERMISSIONS_POLICY = "camera=(), microphone=(), geolocation=(), payment=()";
+
+/**
+ * Adds common security response headers to every request.
+ *
+ * Defaults provide a solid security baseline out of the box:
+ *   - `X-Content-Type-Options: nosniff`
+ *   - `X-Frame-Options: SAMEORIGIN`
+ *   - `Referrer-Policy: strict-origin-when-cross-origin`
+ *   - `Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=()`
+ *   - `Strict-Transport-Security` (only when `secure: true`)
+ *
+ * @example
+ * // Development (HTTP)
+ * app.use([SecureHeadersMiddleware]);
+ *
+ * // Production (HTTPS)
+ * app.use([SecureHeadersMiddleware.with({ secure: true })]);
+ *
+ * // Custom CSP
+ * app.use([SecureHeadersMiddleware.with({
+ *   secure: true,
+ *   contentSecurityPolicy: "default-src 'self'; script-src 'self' 'nonce-{nonce}'",
+ * })]);
+ */
+export class SecureHeadersMiddleware extends BaseMiddleware<SecureHeadersOptions> {
+  protected options: SecureHeadersOptions;
+  constructor() {
+    super();
+    // App-level defaults from config('app.secureHeaders'); .with(...) overrides these.
+    this.options = { ...config.safe("app.secureHeaders", {} as SecureHeadersOptions) };
+  }
+
+  async handle(_ctx: HttpContext, next: NextFn): Promise<Response | void> {
+    const response = await next();
+    if (!response) return;
+
+    const secure: Record<string, string> = {
+      // Always-on security headers
+      "X-Content-Type-Options": "nosniff",
+      "Referrer-Policy": this.options.referrerPolicy ?? "strict-origin-when-cross-origin",
+    };
+
+    const frameOptions = this.options.frameOptions ?? "SAMEORIGIN";
+    if (frameOptions) secure["X-Frame-Options"] = frameOptions;
+
+    const permissionsPolicy = this.options.permissionsPolicy ?? DEFAULT_PERMISSIONS_POLICY;
+    if (permissionsPolicy) secure["Permissions-Policy"] = permissionsPolicy;
+
+    if (this.options.contentSecurityPolicy) {
+      secure["Content-Security-Policy"] = this.options.contentSecurityPolicy;
+    }
+
+    // HSTS only over HTTPS — emitting it on HTTP can lock users out
+    if (this.options.secure) {
+      const maxAge = this.options.hstsMaxAge ?? 31_536_000;
+      if (maxAge > 0) {
+        const parts = [`max-age=${maxAge}`];
+        if (this.options.hstsIncludeSubDomains !== false) parts.push("includeSubDomains");
+        if (this.options.hstsPreload) parts.push("preload");
+        secure["Strict-Transport-Security"] = parts.join("; ");
+      }
+    }
+
+    return withHeaders(response, secure);
+  }
+}

package/src/middleware/ThrottleMiddleware.ts

@@ -0,0 +1,252 @@
+/**
+ * Rate-limiting middleware backed by an in-memory sliding-window counter.
+ * Returns `429 Too Many Requests` (with `Retry-After` and `X-RateLimit-*`
+ * headers) once a client exceeds its allowance within the window.
+ */
+import type { NextFn } from "../pipeline/types.ts";
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+import { BaseMiddleware, deepMerge } from "./BaseMiddleware.ts";
+import { withHeaders } from "../http/withHeaders.ts";
+import { negotiate } from "../http/negotiate.ts";
+import { config } from "../helpers/config.ts";
+
+export interface ThrottleOptions {
+  /** Maximum number of requests allowed within the window. */
+  maxAttempts: number;
+  /** Time window in seconds. Defaults to 60. */
+  windowSeconds?: number;
+  /**
+   * Custom key resolver — defaults to client IP address.
+   * Use this to rate-limit by user ID, API key, route, etc.
+   */
+  keyResolver?: (ctx: HttpContext) => string;
+  /**
+   * Number of trusted reverse proxies in front of this server.
+   *
+   * `X-Forwarded-For` is client-writable, so it is only consulted when you state how many
+   * proxies sit in front of the app — the count is what says which entry is not
+   * attacker-controlled. Without it the unspoofable socket address is used.
+   *
+   * - `undefined` (default) / `0` — no trusted proxy; key on the socket address
+   * - `1` — one trusted proxy; the client IP is the second-to-last XFF entry
+   * - `n` — the client IP is `n` entries from the right
+   *
+   * @example
+   * // Behind one load balancer:
+   * ThrottleMiddleware.with({ maxAttempts: 60, trustedProxies: 1 })
+   */
+  trustedProxies?: number;
+}
+
+interface HitRecord {
+  count: number;
+  resetsAt: number; // unix ms
+}
+
+/**
+ * Rate-limiting middleware using an in-memory sliding window counter.
+ *
+ * Returns 429 Too Many Requests with Retry-After and X-RateLimit-* headers
+ * when a client exceeds the configured threshold within the time window.
+ *
+ * @example
+ * // Global: 120 req / min
+ * app.use([ThrottleMiddleware.with({ maxAttempts: 120, windowSeconds: 60 })]);
+ *
+ * // Per-route: 5 login attempts / min
+ * Router.post('/login', AuthController, 'login', [
+ *   ThrottleMiddleware.with({ maxAttempts: 5, windowSeconds: 60 }),
+ * ]);
+ *
+ * // By authenticated user ID
+ * ThrottleMiddleware.with({
+ *   maxAttempts: 1000,
+ *   windowSeconds: 3600,
+ *   keyResolver: (ctx) => String(ctx.user?.id ?? _clientIp(ctx.request)),
+ * })
+ */
+export class ThrottleMiddleware extends BaseMiddleware<ThrottleOptions> {
+  protected options: ThrottleOptions = {
+    maxAttempts: 60,
+    windowSeconds: 60,
+  };
+
+  constructor(options: Partial<ThrottleOptions> = {}) {
+    super();
+    // App-level defaults from config('app.throttle') layer over the built-ins; explicit
+    // options (constructor arg or .with(...)) win over both. Without this read, an operator
+    // who hardened `app.throttle` in config got the built-in 60/60 and no indication why.
+    this.options = deepMerge(
+      this.options,
+      config.safe("app.throttle", {} as Partial<ThrottleOptions>),
+    );
+    this.options = deepMerge(this.options, options);
+  }
+
+  /**
+   * The hit counters for this middleware class.
+   *
+   * This **must not** be per-instance. The pipeline constructs a fresh pipe for every request
+   * unless the class is container-registered, and middleware never is — so an instance field
+   * was reset on each request and the limiter counted to 1 forever, silently allowing unlimited
+   * traffic through every `ThrottleMiddleware` and `RateLimiter` (including login throttles).
+   *
+   * The store is keyed on the concrete class, so each `ThrottleMiddleware.with({...})` call
+   * site — which returns its own anonymous subclass — keeps an isolated bucket, exactly as the
+   * per-instance field intended. `reset()` and `resetKey()` operate on the same shared map.
+   */
+  private get _store(): Map<string, HitRecord> {
+    return _storeFor(this.constructor as ThrottleClass);
+  }
+
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    const max = this.options.maxAttempts;
+    const windowMs = (this.options.windowSeconds ?? 60) * 1000;
+    const keyFn =
+      this.options.keyResolver ?? ((context) => _clientIp(context, this.options.trustedProxies));
+
+    const key = keyFn(http);
+    const now = Date.now();
+    const store = this._store;
+    const existing = store.get(key);
+
+    let record: HitRecord;
+
+    if (!existing || now >= existing.resetsAt) {
+      record = { count: 1, resetsAt: now + windowMs };
+      store.set(key, record);
+      _pruneStore(store, now);
+    } else {
+      record = existing;
+      record.count++;
+    }
+
+    const remaining = Math.max(0, max - record.count);
+    const resetSeconds = Math.ceil((record.resetsAt - now) / 1000);
+
+    if (record.count > max) {
+      await negotiate(http)({
+        web: () => {
+          http.response = new Response(
+            `<!DOCTYPE html>\n<html><head><title>429 Too Many Requests</title></head>` +
+              `<body><h1>429 Too Many Requests</h1>` +
+              `<p>You have exceeded the request limit. Please retry after ${resetSeconds} seconds.</p>` +
+              `</body></html>`,
+            { status: 429, headers: { "Content-Type": "text/html; charset=utf-8" } },
+          );
+        },
+        json: () => {
+          http.response = Response.json({ message: "Too Many Requests" }, { status: 429 });
+        },
+        cli: (cli) => cli.text(`Rate limit exceeded. Retry after ${resetSeconds}s.`, 429),
+      });
+
+      // Apply rate-limit headers uniformly regardless of channel
+      if (http.response) {
+        http.response = withHeaders(http.response, {
+          "Retry-After": String(resetSeconds),
+          "X-RateLimit-Limit": String(max),
+          "X-RateLimit-Remaining": "0",
+          "X-RateLimit-Reset": String(Math.floor(record.resetsAt / 1000)),
+        });
+      }
+
+      return http.response;
+    }
+
+    const response = await next();
+
+    // Attach informational headers to every successful response.
+    if (response) {
+      return withHeaders(response, {
+        "X-RateLimit-Limit": String(max),
+        "X-RateLimit-Remaining": String(remaining),
+        "X-RateLimit-Reset": String(Math.floor(record.resetsAt / 1000)),
+      });
+    }
+  }
+
+  /** Reset all counters — useful in tests. */
+  reset(): void {
+    this._store.clear();
+  }
+
+  /**
+   * Reset the counter for a single key derived from the given context.
+   * Used by `RateLimiter.resetFor()` to clear a specific actor's bucket
+   * (e.g. after a successful login clears failed-attempt counters).
+   */
+  resetKey(ctx: HttpContext): void {
+    const keyFn =
+      this.options.keyResolver ?? ((context) => _clientIp(context, this.options.trustedProxies));
+    this._store.delete(keyFn(ctx));
+  }
+}
+
+/**
+ * Hard cap on distinct keys held per middleware class.
+ *
+ * The key is derived from client-controlled input (the peer address, a forwarded header, an
+ * API key, or an app-supplied `keyResolver`), so an unbounded map is a memory-exhaustion
+ * vector: a few million requests with unique keys is a few million retained records. On
+ * overflow the map is swept of expired records first, and only genuinely live buckets are
+ * evicted — oldest-reset first — so an attacker cannot cheaply flush a legitimate client's
+ * counter by flooding new keys.
+ */
+const _MAX_KEYS = 100_000;
+
+/** Identity of a concrete throttle class — used only as a `WeakMap` key. */
+type ThrottleClass = abstract new (...args: never[]) => ThrottleMiddleware;
+
+/** Per-class hit counters. Keyed on the class so `.with()` subclasses stay isolated. */
+const _stores = new WeakMap<ThrottleClass, Map<string, HitRecord>>();
+
+function _storeFor(cls: ThrottleClass): Map<string, HitRecord> {
+  let store = _stores.get(cls);
+  if (!store) {
+    store = new Map<string, HitRecord>();
+    _stores.set(cls, store);
+  }
+  return store;
+}
+
+/**
+ * Keep the store bounded. Called after each insert; O(1) in the common case because the
+ * size check short-circuits until the cap is actually reached.
+ */
+export function _pruneStore(store: Map<string, HitRecord>, now: number): void {
+  if (store.size <= _MAX_KEYS) return;
+  for (const [key, record] of store) {
+    if (now >= record.resetsAt) store.delete(key);
+  }
+  if (store.size <= _MAX_KEYS) return;
+  // Still over after sweeping expired entries: drop the buckets that reset soonest, since
+  // those are closest to being discarded anyway.
+  const live = [...store.entries()].sort((a, b) => a[1].resetsAt - b[1].resetsAt);
+  for (let i = 0; i < live.length - _MAX_KEYS; i++) store.delete(live[i]![0]);
+}
+
+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.
+  //
+  // This used to fall through to the leftmost X-Forwarded-For entry when `trustedProxies` was
+  // undefined — and undefined is the default. Because the header was consulted *before* the
+  // socket address, even a direct connection could pick its own bucket, so rotating
+  // `X-Forwarded-For: 1.2.3.<n>` defeated every limiter built on this, including the documented
+  // login throttle. Trusting a forwarded header is now strictly opt-in, which matches how
+  // RateLimiter._resolveIp and LoginRateLimiter._ip already behaved.
+  if (trustedProxies === undefined || trustedProxies === 0) {
+    return ctx.ip() ?? ctx.header("x-real-ip") ?? "unknown";
+  }
+
+  // Behind one or more *trusted* reverse proxies — parse X-Forwarded-For.
+  const forwardedFor = ctx.header("x-forwarded-for");
+  if (!forwardedFor) return ctx.ip() ?? ctx.header("x-real-ip") ?? "unknown";
+
+  const addresses = forwardedFor.split(",").map((entry) => entry.trim());
+
+  // trustedProxies > 0: client IP is that many entries from the right.
+  const clientIndex = addresses.length - 1 - trustedProxies;
+  return (clientIndex >= 0 ? addresses[clientIndex] : addresses[0]) ?? "unknown";
+}