akanjs 3.0.0-alpha.8 → 3.0.0-alpha.80

package/client/types.ts

@@ -1,5 +1,5 @@
 import type { BaseInsight } from "akanjs/constant";
-import type { FetchInitForm, SliceMeta } from "akanjs/fetch";
+import type { FetchInitForm, QuerySetting, SliceMeta } from "akanjs/fetch";
 import type { ReactElement, ReactNode } from "react";
 
 export type ReactFontStyle = "normal" | "italic" | "oblique";
@@ -109,7 +109,7 @@ const slugFontPart = (value: string) =>
 export interface ModelsProps<M extends { id: string }> {
   className?: string;
   slice?: SliceMeta;
-  query?: Record<string, unknown>;
+  query?: QuerySetting;
   init?: FetchInitForm<any, any>;
   onClickItem?: (model: M) => unknown;
 }
@@ -127,7 +127,7 @@ export type ModelProps<T extends string, L extends { id: string }> = { [key in T
 export interface ModelDashboardProps<Summary> {
   className?: string;
   summary: Summary;
-  queryMap?: Record<string, unknown>;
+  queryMap?: { [column: string]: QuerySetting };
   columns?: (keyof Summary)[];
   hidePresents?: boolean;
   slice?: SliceMeta;

package/common/Logger.ts

@@ -1,17 +1,64 @@
 import dayjs from "dayjs";
+import { type LogContextSnapshot, readLogContext } from "./logContext";
 
-const logLevels = ["trace", "verbose", "debug", "log", "info", "warn", "error"] as const;
+export const logLevels = ["trace", "verbose", "debug", "info", "warn", "error"] as const;
 export type LogLevel = (typeof logLevels)[number];
+export type LogLevelInput = LogLevel | "log";
+
+export const logSeverity = { trace: 1, verbose: 3, debug: 5, info: 9, warn: 13, error: 17 } as const satisfies {
+  [key in LogLevel]: number;
+};
+
+/** `text` is the human console line; the `ndjson` pair make the container's stdout one JSON record per line. */
+export const logFormats = ["text", "ndjson", "ndjson-only"] as const;
+export type LogFormat = (typeof logFormats)[number];
+
+export type LogAttrValue = string | number | boolean | null;
+export interface LogAttrs {
+  [key: string]: LogAttrValue;
+}
+
+export interface LogRecord {
+  at: number;
+  /** Milliseconds since the producing process started — what the `+Nms` in the rendered line shows. */
+  elapsedMs: number;
+  level: LogLevel | null;
+  sev: number;
+  name: string;
+  context: string;
+  message: string;
+  stream: "stdout" | "stderr";
+  pid: number | null;
+  replicaIdx: number | null;
+  role: string | null;
+  origin: string | null;
+  traceId: string | null;
+  endpoint: string | null;
+  attrs?: LogAttrs;
+}
 
 export interface LoggerSinkEntry {
   stream: "stdout" | "stderr";
   level?: LogLevel;
   message: string;
   plainMessage: string;
+  record: LogRecord;
 }
 
 export type LoggerSink = (entry: LoggerSinkEntry) => void | Promise<void>;
 
+export interface LoggerSinkOptions {
+  minLevel?: LogLevelInput;
+}
+
+export interface LoggerEmitInput {
+  level: LogLevel;
+  name: string;
+  message: string;
+  context?: string;
+  attrs?: LogAttrs;
+}
+
 const clc = {
   bold: (text: string) => `\x1B[1m${text}\x1B[0m`,
   green: (text: string) => `\x1B[32m${text}\x1B[39m`,
@@ -25,7 +72,6 @@ const colorizeMap: { [key in LogLevel]: (text: string) => string } = {
   trace: clc.bold,
   verbose: clc.cyanBright,
   debug: clc.magentaBright,
-  log: clc.green,
   info: clc.green,
   warn: clc.yellow,
   error: clc.red,
@@ -33,36 +79,129 @@ const colorizeMap: { [key in LogLevel]: (text: string) => string } = {
 
 const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
 
+const redactedAttrKey = /password|passwd|token|jwt|authorization|cookie|secret|api[-_]?key|private[-_]?key/i;
+
+/**
+ * `process.env?.X` guards only `env` being absent, never `process` itself — an undeclared `process` is a
+ * ReferenceError, and at module scope that takes the whole client bundle with it. This is the most widely
+ * imported file in `common/`, and the unguarded form works today only because the browser build ships a shim.
+ */
+const envValue = (key: string): string | undefined => (typeof process === "undefined" ? undefined : process.env?.[key]);
+
 /** Log-level aware logger used by Akan runtime, CLI, and application services. */
 export class Logger {
-  static level: LogLevel = (process.env?.AKAN_PUBLIC_LOG_LEVEL as LogLevel | undefined) ?? "log";
-  static #levelIdx = logLevels.findIndex((l) => l === (process.env?.AKAN_PUBLIC_LOG_LEVEL ?? "log"));
-  static fileLevel: LogLevel = (process.env?.AKAN_LOG_FILE_LEVEL as LogLevel | undefined) ?? "trace";
-  static #fileLevelIdx = logLevels.findIndex((l) => l === (process.env?.AKAN_LOG_FILE_LEVEL ?? "trace"));
-  static #startAt = dayjs();
-  static #sinks = new Set<LoggerSink>();
-
-  static setLevel(level: LogLevel) {
-    Logger.level = level;
-    Logger.#levelIdx = logLevels.indexOf(level);
-  }
-  static addSink(sink: LoggerSink) {
-    Logger.#sinks.add(sink);
+  /** `AKAN_LOG_STDOUT_LEVEL` names what the container's stdout carries; without it the console level is that. */
+  static level: LogLevel = Logger.#levelFromEnv(
+    envValue("AKAN_LOG_STDOUT_LEVEL"),
+    Logger.#levelFromEnv(envValue("AKAN_PUBLIC_LOG_LEVEL"), "info"),
+  );
+  static fileLevel: LogLevel = Logger.#levelFromEnv(envValue("AKAN_LOG_FILE_LEVEL"), "trace");
+  static format: LogFormat = Logger.#formatFromEnv(envValue("AKAN_LOG_FORMAT"));
+  /** Which process this is (`gateway`, `all`, `batch`, `rsc-worker`); the owner sets it at boot. */
+  static role: string | null = envValue("SERVER_MODE") ?? null;
+  /**
+   * Whether this process writes its own lines to the terminal. Off in every server process of an ndjson
+   * deployment: the hub owner writes the one JSON stream, and a text line from anyone would corrupt it.
+   */
+  static consoleOutput = true;
+  /** Set by the trace layer when a flight recorder or a per-request debug floor can be active. */
+  static contextGate = false;
+  static readonly startAt = Date.now();
+  static #consoleSev: number = logSeverity[Logger.level];
+  static #fileSev: number = logSeverity[Logger.fileLevel];
+  static #sinkFloorSev = Number.POSITIVE_INFINITY;
+  static #sinks = new Map<LoggerSink, number | null>();
+
+  static setLevel(level: LogLevelInput) {
+    Logger.level = Logger.normalizeLevel(level);
+    Logger.#consoleSev = logSeverity[Logger.level];
+  }
+  static setFileLevel(level: LogLevelInput) {
+    Logger.fileLevel = Logger.normalizeLevel(level);
+    Logger.#fileSev = logSeverity[Logger.fileLevel];
+    Logger.#refreshSinkFloor();
+  }
+  static addSink(sink: LoggerSink, { minLevel }: LoggerSinkOptions = {}) {
+    Logger.#sinks.set(sink, minLevel === undefined ? null : logSeverity[Logger.normalizeLevel(minLevel)]);
+    Logger.#refreshSinkFloor();
     return () => Logger.removeSink(sink);
   }
   static removeSink(sink: LoggerSink) {
     Logger.#sinks.delete(sink);
-  }
-  static setFileLevel(level: LogLevel) {
-    Logger.fileLevel = level;
-    Logger.#fileLevelIdx = logLevels.indexOf(level);
+    Logger.#refreshSinkFloor();
   }
   static isVerbose() {
-    return Logger.#levelIdx <= 1;
+    return Logger.#consoleSev <= logSeverity.verbose;
+  }
+  static get isNdjson() {
+    return Logger.format !== "text";
   }
   /** For hot-path callers that would otherwise build a message the level is about to discard. */
-  static shouldLog(logLevel: LogLevel) {
-    return Logger.#shouldLog(logLevel);
+  static shouldLog(logLevel: LogLevelInput) {
+    return Logger.#shouldLog(Logger.normalizeLevel(logLevel));
+  }
+  static normalizeLevel(level: LogLevelInput): LogLevel {
+    return level === "log" ? "info" : level;
+  }
+  /** The lowest named level whose severity is at least `sev`. */
+  static levelAtOrAbove(sev: number): LogLevel {
+    return logLevels.find((level) => logSeverity[level] >= sev) ?? "error";
+  }
+  static render(record: LogRecord): string {
+    const level = record.level;
+    if (level === null) return record.message;
+    const replicaMsg = record.replicaIdx === null ? "" : `#${record.replicaIdx} `;
+    const processMsg = Logger.#colorize(`[${record.name}] ${replicaMsg}${record.pid ?? "window"} -`, level);
+    const timestampMsg = dayjs(record.at).format("MM/DD/YYYY, HH:mm:ss A");
+    const logLevelMsg = Logger.#colorize(level.toUpperCase().padStart(7, " "), level);
+    const contextMsg = record.context ? clc.yellow(`[${record.context}] `) : "";
+    const contentMsg = Logger.#colorize(record.message, level);
+    const attrsMsg = record.attrs ? Logger.formatAttrs(record.attrs) : "";
+    const timeDiffMsg = clc.yellow(`+${record.elapsedMs}ms`);
+    return `${processMsg} ${timestampMsg} ${logLevelMsg} ${contextMsg} ${contentMsg}${attrsMsg ? ` ${attrsMsg}` : ""} ${timeDiffMsg}\n`;
+  }
+  /** `key=value` pairs; a string with whitespace is quoted so the line stays splittable. */
+  static formatAttrs(attrs: LogAttrs): string {
+    return Object.entries(attrs)
+      .map(
+        ([key, value]) =>
+          `${key}=${typeof value === "string" && /\s/.test(value) ? JSON.stringify(value) : String(value)}`,
+      )
+      .join(" ");
+  }
+  /**
+   * A record somebody asked for below the level — a failed call's flight recorder, a request carrying
+   * `x-akan-debug` — passes every floor between here and the reader; the floors exist to drop what nobody asked for.
+   */
+  static isPromoted(record: LogRecord) {
+    return record.attrs?.flight === true || record.attrs?.debug === true;
+  }
+  static redactAttrs(attrs: LogAttrs): LogAttrs {
+    let redacted: LogAttrs | null = null;
+    for (const key of Object.keys(attrs)) {
+      if (!redactedAttrKey.test(key)) continue;
+      redacted ??= { ...attrs };
+      redacted[key] = "[redacted]";
+    }
+    return redacted ?? attrs;
+  }
+  /** A structured record from a caller that has more than a sentence to say — the canonical request line. */
+  static emit({ level, name, message, context = "", attrs }: LoggerEmitInput) {
+    if (Logger.#shouldLog(level)) Logger.#write(name, message, context, level, attrs);
+  }
+  /**
+   * Writes records that were captured below the gate and are now promoted — a failed request's flight
+   * recorder. They bypass the console level, since not showing them is what the recorder was for, and reach
+   * sinks under their own floors; each is marked `flight` so a reader knows why a trace line appears at info.
+   */
+  static replay(records: LogRecord[], { evicted = 0 }: { evicted?: number } = {}) {
+    records.forEach((record, idx) => {
+      const attrs: LogAttrs = { ...record.attrs, flight: true };
+      if (idx === 0 && evicted > 0) attrs.flightEvicted = evicted;
+      const entry = Logger.#entry({ ...record, attrs });
+      Logger.#emit(entry);
+      Logger.#writeConsole(entry);
+    });
   }
 
   name?: string;
@@ -70,25 +209,26 @@ export class Logger {
     this.name = name;
   }
   trace(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("trace")) Logger.#printMessages(name, msg, context, "trace");
+    if (Logger.#shouldLog("trace")) Logger.#write(name, msg, context, "trace");
   }
   verbose(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("verbose")) Logger.#printMessages(name, msg, context, "verbose");
+    if (Logger.#shouldLog("verbose")) Logger.#write(name, msg, context, "verbose");
   }
   debug(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("debug")) Logger.#printMessages(name, msg, context, "debug");
+    if (Logger.#shouldLog("debug")) Logger.#write(name, msg, context, "debug");
   }
+  /** @deprecated Emits at `info`; call `info()`. */
   log(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("log")) Logger.#printMessages(name, msg, context, "log");
+    if (Logger.#shouldLog("info")) Logger.#write(name, msg, context, "info");
   }
   info(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("info")) Logger.#printMessages(name, msg, context, "info");
+    if (Logger.#shouldLog("info")) Logger.#write(name, msg, context, "info");
   }
   warn(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("warn")) Logger.#printMessages(name, msg, context, "warn");
+    if (Logger.#shouldLog("warn")) Logger.#write(name, msg, context, "warn");
   }
   error(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("error")) Logger.#printMessages(name, msg, context, "error");
+    if (Logger.#shouldLog("error")) Logger.#write(name, msg, context, "error");
   }
   raw(msg: string, method?: "console" | "process") {
     Logger.rawLog(msg, method);
@@ -96,86 +236,166 @@ export class Logger {
   rawLog(msg: string, method?: "console" | "process") {
     Logger.rawLog(msg, method);
   }
-  
   static trace(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("trace")) Logger.#printMessages(name, msg, context, "trace");
+    if (Logger.#shouldLog("trace")) Logger.#write(name, msg, context, "trace");
   }
   static verbose(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("verbose")) Logger.#printMessages(name, msg, context, "verbose");
+    if (Logger.#shouldLog("verbose")) Logger.#write(name, msg, context, "verbose");
   }
   static debug(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("debug")) Logger.#printMessages(name, msg, context, "debug");
+    if (Logger.#shouldLog("debug")) Logger.#write(name, msg, context, "debug");
   }
+  /** @deprecated Emits at `info`; call `info()`. */
   static log(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("log")) Logger.#printMessages(name, msg, context, "log");
+    if (Logger.#shouldLog("info")) Logger.#write(name, msg, context, "info");
   }
   static info(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("info")) Logger.#printMessages(name, msg, context, "info");
+    if (Logger.#shouldLog("info")) Logger.#write(name, msg, context, "info");
   }
   static warn(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("warn")) Logger.#printMessages(name, msg, context, "warn");
+    if (Logger.#shouldLog("warn")) Logger.#write(name, msg, context, "warn");
   }
   static error(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("error")) Logger.#printMessages(name, msg, context, "error");
+    if (Logger.#shouldLog("error")) Logger.#write(name, msg, context, "error");
+  }
+  static #levelFromEnv(value: string | undefined, fallback: LogLevel): LogLevel {
+    if (value === "log") return "info";
+    return (logLevels as readonly string[]).includes(value ?? "") ? (value as LogLevel) : fallback;
+  }
+  static #formatFromEnv(value: string | undefined): LogFormat {
+    return (logFormats as readonly string[]).includes(value ?? "") ? (value as LogFormat) : "text";
+  }
+  static #refreshSinkFloor() {
+    let floor = Number.POSITIVE_INFINITY;
+    for (const minSev of Logger.#sinks.values()) floor = Math.min(floor, minSev ?? Logger.#fileSev);
+    Logger.#sinkFloorSev = floor;
   }
   static #colorize(msg: string, logLevel: LogLevel) {
     return colorizeMap[logLevel](msg);
   }
-  static #stripAnsi(msg: string) {
+  static stripAnsi(msg: string) {
     return msg.replace(ansiPattern, "");
   }
   static #shouldLog(logLevel: LogLevel) {
-    return Logger.#shouldWriteConsole(logLevel) || Logger.#shouldEmitSink(logLevel);
+    if (Logger.#shouldWriteConsole(logLevel) || Logger.#shouldEmitSink(logLevel)) return true;
+    return Logger.contextGate && Logger.#contextFloor(readLogContext()) <= logSeverity[logLevel];
   }
   static #shouldWriteConsole(logLevel: LogLevel) {
-    return Logger.#levelIdx <= logLevels.indexOf(logLevel);
+    return Logger.consoleOutput && logSeverity[logLevel] >= Logger.#consoleSev;
   }
   static #shouldEmitSink(logLevel: LogLevel) {
-    return Logger.#sinks.size > 0 && Logger.#fileLevelIdx <= logLevels.indexOf(logLevel);
+    return logSeverity[logLevel] >= Logger.#sinkFloorSev;
+  }
+  /** The lowest severity the ambient request wants captured or shown, or +∞ outside one. */
+  static #contextFloor(ctx: LogContextSnapshot | undefined) {
+    if (!ctx) return Number.POSITIVE_INFINITY;
+    return Math.min(ctx.flight?.minSev ?? Number.POSITIVE_INFINITY, ctx.debugSev ?? Number.POSITIVE_INFINITY);
+  }
+  static #buildRecord(
+    name: string | undefined,
+    message: string,
+    context: string,
+    level: LogLevel | null,
+    stream: "stdout" | "stderr",
+    ctx: LogContextSnapshot | undefined,
+    attrs?: LogAttrs,
+  ): LogRecord {
+    const proc = process as unknown as NodeJS.Process | undefined;
+    const replicaIdx = Number(proc?.env?.AKAN_REPLICA_IDX ?? Number.NaN);
+    const at = Date.now();
+    return {
+      at,
+      elapsedMs: at - Logger.startAt,
+      level,
+      sev: level === null ? 0 : logSeverity[level],
+      name: name ?? "App",
+      context,
+      message,
+      stream,
+      pid: proc?.pid ?? null,
+      replicaIdx: Number.isNaN(replicaIdx) ? null : replicaIdx,
+      role: Logger.role,
+      origin: ctx?.origin ?? null,
+      traceId: ctx?.traceId ?? null,
+      endpoint: ctx?.endpoint ?? null,
+      ...(attrs ? { attrs: Logger.redactAttrs(attrs) } : {}),
+    };
+  }
+  static #entry(record: LogRecord, text?: string): LoggerSinkEntry {
+    let message = text;
+    let plainMessage: string | undefined;
+    return {
+      stream: record.stream,
+      level: record.level ?? undefined,
+      record,
+      get message() {
+        message ??= Logger.render(record);
+        return message;
+      },
+      get plainMessage() {
+        plainMessage ??= Logger.stripAnsi(this.message);
+        return plainMessage;
+      },
+    };
   }
   static #emit(entry: LoggerSinkEntry) {
-    for (const sink of Logger.#sinks) {
+    for (const [sink, minSev] of Logger.#sinks) {
+      
+      if (
+        entry.record.level !== null &&
+        entry.record.sev < (minSev ?? Logger.#fileSev) &&
+        !Logger.isPromoted(entry.record)
+      )
+        continue;
       try {
         void Promise.resolve(sink(entry)).catch(() => undefined);
       } catch {
       }
     }
   }
-  static #printMessages(
-    name: string | undefined,
-    content: string,
-    context: string,
-    logLevel: LogLevel,
-    writeStreamType: "stdout" | "stderr" = logLevel === "error" ? "stderr" : "stdout",
-  ) {
-    const now = dayjs();
-    const replicaIdx = (process as unknown as NodeJS.Process | undefined)?.env?.AKAN_REPLICA_IDX;
-    const replicaMsg = replicaIdx === undefined ? "" : `#${replicaIdx} `;
-    const processMsg = Logger.#colorize(
-      `[${name ?? "App"}] ${replicaMsg}${(process as unknown as NodeJS.Process | undefined)?.pid ?? "window"} -`,
+  static #writeConsole(entry: LoggerSinkEntry) {
+    if (!Logger.consoleOutput) return;
+    if (typeof window === "undefined")
+      (process[entry.stream] as unknown as NodeJS.WriteStream | undefined)?.write(entry.message);
+    else console.log(entry.message);
+  }
+  static #write(name: string | undefined, message: string, context: string, logLevel: LogLevel, attrs?: LogAttrs) {
+    const stream = logLevel === "error" ? "stderr" : "stdout";
+    const ctx = readLogContext();
+    const sev = logSeverity[logLevel];
+    const debug = ctx?.debugSev !== undefined && ctx.debugSev !== null && sev >= ctx.debugSev;
+
+    const promoted = debug && sev < Logger.#consoleSev;
+    const record = Logger.#buildRecord(
+      name,
+      message,
+      context,
       logLevel,
+      stream,
+      ctx,
+      promoted ? { ...attrs, debug: true } : attrs,
     );
-    const timestampMsg = now.format("MM/DD/YYYY, HH:mm:ss A");
-    const logLevelMsg = Logger.#colorize(logLevel.toUpperCase().padStart(7, " "), logLevel);
-    const contextMsg = context ? clc.yellow(`[${context}] `) : "";
-    const contentMsg = Logger.#colorize(content, logLevel);
-    const timeDiffMsg = clc.yellow(`+${now.diff(Logger.#startAt, "ms")}ms`);
-    const message = `${processMsg} ${timestampMsg} ${logLevelMsg} ${contextMsg} ${contentMsg} ${timeDiffMsg}\n`;
-    if (Logger.#shouldEmitSink(logLevel))
-      Logger.#emit({ stream: writeStreamType, level: logLevel, message, plainMessage: Logger.#stripAnsi(message) });
-    if (!Logger.#shouldWriteConsole(logLevel)) return;
-    if (typeof window === "undefined")
-      (process[writeStreamType] as unknown as NodeJS.WriteStream | undefined)?.write(message);
-    else console.log(message);
+    const toConsole = Logger.#shouldWriteConsole(logLevel) || (debug && Logger.consoleOutput);
+    const toSinks = Logger.#shouldEmitSink(logLevel) || debug;
+    ctx?.flight?.capture(record, toConsole || toSinks);
+    if (!toConsole && !toSinks) return;
+    const entry = Logger.#entry(record);
+    if (toSinks) Logger.#emit(entry);
+    if (toConsole) Logger.#writeConsole(entry);
   }
   static rawLog(msg = "", method?: "console" | "process", outputStream?: "log" | "error") {
     Logger.raw(`${msg}\n`, method, outputStream);
   }
   static raw(msg = "", method?: "console" | "process", outputStream?: "log" | "error") {
     const stream = outputStream === "error" ? "stderr" : "stdout";
-    Logger.#emit({ stream, message: msg, plainMessage: Logger.#stripAnsi(msg) });
+    Logger.#emit(Logger.#entry(Logger.#buildRecord(undefined, msg, "", null, stream, readLogContext()), msg));
+    if (!Logger.consoleOutput) return;
     if (typeof window === "undefined" && method !== "console" && (process as unknown as NodeJS.Process | undefined))
       process[stream].write(msg);
     else console[outputStream === "error" ? "error" : "log"](msg.trim());
   }
+  static {
+    if (envValue("AKAN_PUBLIC_LOG_LEVEL") === "log" && typeof window === "undefined")
+      Logger.warn("AKAN_PUBLIC_LOG_LEVEL=log is deprecated and now means info; set AKAN_PUBLIC_LOG_LEVEL=info.");
+  }
 }

package/common/TrustedProxy.ts

@@ -0,0 +1,134 @@
+import { normalizeIpAddress } from "./clientAddress";
+
+/**
+ * Whether the hop that connected is allowed to name the caller.
+ *
+ * `x-real-ip` and `x-forwarded-for` are just request headers: anyone can send them. They are the truth only when
+ * the peer that sent them is a proxy we put there — otherwise a client forges its own address and walks past
+ * every `.with(Ip)` guard, rate limit and audit line at once.
+ *
+ * The default trusts a private, loopback or link-local peer and nothing else, because that is exactly the shape
+ * of a proxy on the same network: an ingress, a service mesh, the dev machine. A gateway reachable from the
+ * internet sees a public peer, so a header from there is dropped rather than believed. `AKAN_TRUSTED_PROXIES`
+ * takes a comma-separated CIDR list for the case the proxy is not private — and `*` for "the deployment
+ * guarantees nothing untrusted can reach this port", which is the old behaviour, written down.
+ */
+export class TrustedProxy {
+  static #cidrs: { bytes: Uint8Array; bits: number }[] | null = null;
+  static #trustAll: boolean | null = null;
+
+  static configure(list: string | null | undefined) {
+    TrustedProxy.#trustAll = list?.trim() === "*";
+    TrustedProxy.#cidrs = (list ?? "")
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry && entry !== "*")
+      .flatMap((entry) => {
+        const parsed = TrustedProxy.#parseCidr(entry);
+        return parsed ? [parsed] : [];
+      });
+  }
+
+  static reset() {
+    TrustedProxy.#cidrs = null;
+    TrustedProxy.#trustAll = null;
+  }
+
+  static #load() {
+    if (TrustedProxy.#cidrs === null) TrustedProxy.configure(process.env.AKAN_TRUSTED_PROXIES);
+  }
+
+  static isTrusted(address: string | null | undefined): boolean {
+    if (!address) return false;
+    TrustedProxy.#load();
+    if (TrustedProxy.#trustAll) return true;
+    const bytes = TrustedProxy.#toBytes(normalizeIpAddress(address));
+    if (!bytes) return false;
+    if (TrustedProxy.#isLocalRange(bytes)) return true;
+    return (TrustedProxy.#cidrs ?? []).some((cidr) => TrustedProxy.#inRange(bytes, cidr));
+  }
+
+  /**
+   * The caller's address as recorded by a proxy, but only when the peer is one. Falls back to the peer itself,
+   * which is the right answer for a process nothing is proxying, and `null` when there is no peer either.
+   */
+  static clientAddress(headers: Headers, peerAddress: string | null | undefined): string | null {
+    if (TrustedProxy.isTrusted(peerAddress)) {
+      const realIp = headers.get("x-real-ip")?.trim();
+      if (realIp) return normalizeIpAddress(realIp);
+      const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+      if (forwarded) return normalizeIpAddress(forwarded);
+    }
+    return peerAddress ? normalizeIpAddress(peerAddress) : null;
+  }
+
+  /** `10/8`, `172.16/12`, `192.168/16`, `127/8`, `169.254/16`, and their IPv6 counterparts `::1`, `fc00::/7`, `fe80::/10`. */
+  static #isLocalRange(bytes: Uint8Array): boolean {
+    if (bytes.length === 4) {
+      const [a = 0, b = 0] = bytes;
+      if (a === 10 || a === 127) return true;
+      if (a === 192 && b === 168) return true;
+      if (a === 172 && b >= 16 && b <= 31) return true;
+      return a === 169 && b === 254;
+    }
+    const [first = 0, second = 0] = bytes;
+    if ((first & 0xfe) === 0xfc) return true;
+    if (first === 0xfe && (second & 0xc0) === 0x80) return true;
+    return bytes.every((byte, idx) => (idx === 15 ? byte === 1 : byte === 0));
+  }
+
+  static #parseCidr(entry: string): { bytes: Uint8Array; bits: number } | null {
+    const [address, prefix] = entry.split("/");
+    const bytes = TrustedProxy.#toBytes(address ?? "");
+    if (!bytes) return null;
+    const bits = prefix === undefined ? bytes.length * 8 : Number(prefix);
+    if (!Number.isInteger(bits) || bits < 0 || bits > bytes.length * 8) return null;
+    return { bytes, bits };
+  }
+
+  static #inRange(bytes: Uint8Array, cidr: { bytes: Uint8Array; bits: number }): boolean {
+    if (bytes.length !== cidr.bytes.length) return false;
+    const wholeBytes = cidr.bits >> 3;
+    for (let idx = 0; idx < wholeBytes; idx += 1) if (bytes[idx] !== cidr.bytes[idx]) return false;
+    const restBits = cidr.bits & 7;
+    if (!restBits) return true;
+    const mask = 0xff << (8 - restBits);
+    return ((bytes[wholeBytes] ?? 0) & mask) === ((cidr.bytes[wholeBytes] ?? 0) & mask);
+  }
+
+  static #toBytes(address: string): Uint8Array | null {
+    if (address.includes(".") && !address.includes(":")) {
+      const parts = address.split(".");
+      if (parts.length !== 4) return null;
+      const bytes = new Uint8Array(4);
+      for (const [idx, part] of parts.entries()) {
+        const value = Number(part);
+        if (!/^\d{1,3}$/.test(part) || value > 255) return null;
+        bytes[idx] = value;
+      }
+      return bytes;
+    }
+    return address.includes(":") ? TrustedProxy.#ipv6ToBytes(address) : null;
+  }
+
+  static #ipv6ToBytes(address: string): Uint8Array | null {
+
+    const bare = address.split("%")[0] ?? "";
+    const halves = bare.split("::");
+    if (halves.length > 2) return null;
+    const groupsOf = (text: string) => (text ? text.split(":").filter((group) => group !== "") : []);
+    const head = groupsOf(halves[0] ?? "");
+    const tail = halves.length === 2 ? groupsOf(halves[1] ?? "") : [];
+    const filled = halves.length === 2 ? 8 - head.length - tail.length : 0;
+    if (filled < 0 || head.length + tail.length + filled !== 8) return null;
+    const groups = [...head, ...new Array(filled).fill("0"), ...tail];
+    const bytes = new Uint8Array(16);
+    for (const [idx, group] of groups.entries()) {
+      if (!/^[0-9a-f]{1,4}$/i.test(group)) return null;
+      const value = Number.parseInt(group, 16);
+      bytes[idx * 2] = value >> 8;
+      bytes[idx * 2 + 1] = value & 0xff;
+    }
+    return bytes;
+  }
+}

package/common/clamp.ts

@@ -0,0 +1,2 @@
+/** Constrains a value to `[min, max]`. */
+export const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max);

package/common/clientAddress.ts

@@ -0,0 +1,40 @@
+/** Headers a proxy hop writes so the next hop can still name the original caller. */
+export const forwardedHeaders = [
+  "x-real-ip",
+  "x-forwarded-for",
+  "x-forwarded-port",
+  "x-forwarded-host",
+  "x-forwarded-proto",
+] as const;
+
+/**
+ * An IPv4 client reaching a dual-stack listener is reported as `::ffff:203.0.113.10`. That form is not a
+ * valid destination for a `udp4` socket and does not compare equal to the same address written plainly, so
+ * it is unwrapped at every boundary rather than at each call site that happens to remember.
+ */
+export const normalizeIpAddress = (address: string): string => {
+  const trimmed = address.trim();
+  const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(trimmed);
+  return mapped?.[1] ?? trimmed;
+};
+
+/**
+ * The caller's address as the nearest proxy recorded it. `x-real-ip` is one hop's word for who the client is
+ * and wins; `x-forwarded-for` is a chain appended left to right, so its *first* entry is the original client
+ * and everything after it is a proxy.
+ *
+ * Returns `null` rather than a placeholder. A socket peer behind a proxy is the proxy, so `127.0.0.1` here
+ * would be indistinguishable from a genuinely local caller — and that is the failure this exists to prevent.
+ */
+export const clientAddressFromHeaders = (headers: Headers): string | null => {
+  const realIp = headers.get("x-real-ip")?.trim();
+  if (realIp) return normalizeIpAddress(realIp);
+  const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+  return forwarded ? normalizeIpAddress(forwarded) : null;
+};
+
+/** The client port the nearest proxy recorded, for correlating a connection with a peer's own logs. */
+export const clientPortFromHeaders = (headers: Headers): number | null => {
+  const port = Number(headers.get("x-forwarded-port"));
+  return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
+};