@schlessera/brain-ui-server 0.15.0 → 0.16.0

package/src/middleware/auth.ts

@@ -1,3 +1,4 @@
+import type { Logger } from "@opentelemetry/api-logs";
 import { Hono } from "hono";
 import type { Context, MiddlewareHandler } from "hono";
 import { getSignedCookie, setSignedCookie, deleteCookie } from "hono/cookie";
@@ -48,12 +49,14 @@ const LOGIN_RATE_WINDOW_MS = 60_000; // per minute
 // attacker could weaponize to deny the owner access.
 export const GLOBAL_LOGIN_RATE_LIMIT = 20; // attempts per window, all IPs combined
 
-export function resolveAuthMode(auth: AuthRuntime): AuthMode {
+export function resolveAuthMode(auth: AuthRuntime, log?: Logger): AuthMode {
   if (auth.mode) return auth.mode;
   if (auth.invalidMode) {
-    console.warn(
-      `[auth] Unknown AUTH_MODE="${auth.invalidMode}"; auto-detecting instead.`
-    );
+    log?.emit({
+      severityText: "WARN",
+      body: "unknown AUTH_MODE; auto-detecting instead",
+      attributes: { requested: auth.invalidMode },
+    });
   }
   if (auth.passwordHash) return "password";
   return "tailscale";
@@ -63,7 +66,7 @@ export function resolveAuthMode(auth: AuthRuntime): AuthMode {
  * Validate the auth configuration at startup. Throws (refusing to boot) on an
  * unsafe or unusable configuration.
  */
-export function assertAuthConfig(mode: AuthMode, auth: AuthRuntime): void {
+export function assertAuthConfig(mode: AuthMode, auth: AuthRuntime, log?: Logger): void {
   const host = auth.host;
   const loopback = host === "127.0.0.1" || host === "::1" || host === "localhost";
 
@@ -87,11 +90,17 @@ export function assertAuthConfig(mode: AuthMode, auth: AuthRuntime): void {
   // exposed to the network".
   if (mode === "none" && !loopback) {
     if (auth.dangerouslyDisableAuth) {
-      console.warn(
-        "[auth] AUTH_MODE=none on a non-loopback host, allowed by " +
+      // ERROR, not WARN: this is a safety that has been deliberately switched
+      // off, and the severity must survive any sane BRAIN_UI_LOG_LEVEL. A log
+      // threshold must never be the reason nobody saw this.
+      log?.emit({
+        severityText: "ERROR",
+        body:
+          "AUTH_MODE=none on a non-loopback host, allowed by " +
           "BRAIN_UI_DANGEROUSLY_DISABLE_AUTH=1 — every network peer has full " +
-          "agent access. Do not run this on anything but a trusted network."
-      );
+          "agent access. Do not run this on anything but a trusted network.",
+        attributes: { "auth.mode": "none", host },
+      });
     } else {
       throw new Error(
         "AUTH_MODE=none refuses to start unless HOST is loopback " +
@@ -112,13 +121,20 @@ export function assertAuthConfig(mode: AuthMode, auth: AuthRuntime): void {
           "any client-supplied copy. Set TRUST_PROXY=1 once that holds."
       );
     }
-    console.log(
-      `[auth] mode: proxy (trusting header "${auth.proxyAuthHeader}"; ensure your ` +
-        "upstream proxy sets it and strips any client-supplied copy)"
-    );
+    log?.emit({
+      severityText: "INFO",
+      body:
+        "auth mode resolved: proxy — ensure the upstream proxy sets this header " +
+        "and strips any client-supplied copy",
+      attributes: { "auth.mode": "proxy", header: auth.proxyAuthHeader },
+    });
     return;
   }
-  console.log(`[auth] mode: ${mode}`);
+  log?.emit({
+    severityText: "INFO",
+    body: "auth mode resolved",
+    attributes: { "auth.mode": mode },
+  });
 }
 
 /** Middleware guarding /api/* according to the resolved mode. */

package/src/middleware/passkeys.ts

@@ -1,3 +1,5 @@
+import type { Logger } from "@opentelemetry/api-logs";
+import type { Counter } from "@opentelemetry/api";
 import { Hono } from "hono";
 import type { Context } from "hono";
 import type { Database } from "bun:sqlite";
@@ -45,6 +47,14 @@ export interface PasskeyContext {
   auth: AuthRuntime;
   /** ALLOWED_ORIGINS — split-topology origins also valid for ceremonies. */
   allowedOrigins: string[];
+  /** Where ceremony failures are reported; absent means silence. */
+  log?: Logger;
+  /**
+   * Counts failed ceremonies, split by reason. A rate of these is the signal
+   * that distinguishes one fumbled login from someone working through a list,
+   * and it is not recoverable from a log line nobody is tailing.
+   */
+  failures?: Counter;
 }
 
 const CHALLENGE_TTL_MS = 120_000; // > the 60s ceremony timeout
@@ -362,11 +372,20 @@ export function passkeyPublicRoutes(
       // credential. Cloud passkeys legitimately sit at 0, so warn, don't
       // revoke.
       if (/counter/i.test(message)) {
-        console.warn(
-          `[passkeys] counter regression for credential ${row.id} — possible cloned credential`
-        );
+        ctx.failures?.add(1, { reason: "counter_regression", ceremony: "authentication" });
+        ctx.log?.emit({
+          severityText: "WARN",
+          body: "counter regression — possible cloned credential",
+          attributes: { "credential.id": row.id },
+        });
       } else {
-        console.warn(`[passkeys] authentication failed: ${message}`);
+        ctx.failures?.add(1, { reason: "verification_failed", ceremony: "authentication" });
+        // The message is the library's, never the assertion payload.
+        ctx.log?.emit({
+          severityText: "WARN",
+          body: "passkey authentication failed",
+          attributes: { error: message },
+        });
       }
       return fail();
     }
@@ -471,7 +490,12 @@ export function passkeyManagementRoutes(
       return c.json({ ok: true, credential: row ? toSummary(row) : null });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      console.warn(`[passkeys] registration failed: ${message}`);
+      ctx.failures?.add(1, { reason: "verification_failed", ceremony: "registration" });
+      ctx.log?.emit({
+        severityText: "WARN",
+        body: "passkey registration failed",
+        attributes: { error: message },
+      });
       return c.json({ error: "Passkey registration failed" }, 400);
     }
   });

package/src/observability/index.ts

@@ -0,0 +1,150 @@
+/**
+ * Observability for the chat-UI server: what it reports, and who receives it.
+ *
+ * The split is deliberate and is the whole design. The PRODUCING side is the
+ * standard OpenTelemetry API — `logger.emit(...)`, `counter.add(...)` — so
+ * instrumentation is portable and a real SDK can take over later without a
+ * single call site changing. The CONSUMING side is ours: a console consumer in
+ * production, a recording consumer in tests, an in-memory meter feeding
+ * `/api/status`. That is what keeps the dependency surface to two packages and
+ * makes "what did the server report?" answerable as data.
+ *
+ * An `Observability` is a value you construct and own, like the app's database
+ * handle or a `ScrapeClient`'s rate limiter — NOT a process-global. The
+ * OpenTelemetry globals are supported (`installGlobally`) for instrumentation
+ * that cannot be reached with an argument, but nothing in this package
+ * requires them, so two differently-configured apps can share a process and a
+ * test never inherits the previous test's sinks.
+ */
+import { metrics, type Meter, type MeterProvider } from "@opentelemetry/api";
+import { logs, type Logger, type LoggerProvider } from "@opentelemetry/api-logs";
+
+import {
+  createConsoleLoggerProvider,
+  createRecordingLoggerProvider,
+  createSilentLoggerProvider,
+  type LogReader,
+  type RecordingLoggerProvider,
+} from "./loggers.js";
+import { createInMemoryMeterProvider, type InMemoryMeterProvider, type MetricsReader } from "./meter.js";
+import type { Severity } from "./types.js";
+
+export interface ObservabilityOptions {
+  /** Where logs go. Default: the console consumer at `minSeverity`. */
+  loggerProvider?: LoggerProvider;
+  /** Where metrics go. Default: an in-memory recorder (what /api/status reads). */
+  meterProvider?: MeterProvider;
+  /** Threshold for the DEFAULT console consumer; ignored if one is passed in. */
+  minSeverity?: Severity;
+}
+
+/** What the app holds, and hands to anything that reports. */
+export interface Observability {
+  /** A logger for one instrumentation scope — the `[ws]` / `[auth]` prefix. */
+  logger(scope: string): Logger;
+  /** A meter for one instrumentation scope. */
+  meter(scope: string): Meter;
+  /** Recorded metrics, when the meter provider supports reading. */
+  metrics?: MetricsReader;
+  /** Captured logs, when the logger provider supports reading (tests). */
+  logs?: LogReader;
+  /**
+   * Register these providers as the OpenTelemetry globals, so code that cannot
+   * be handed an argument still reports somewhere. Returns a function that
+   * restores whatever was there before — a test that installs globally must be
+   * able to put the process back.
+   */
+  installGlobally(): () => void;
+}
+
+function hasMetricsReader(p: MeterProvider): p is MeterProvider & MetricsReader {
+  return typeof (p as Partial<MetricsReader>).snapshot === "function";
+}
+
+function hasLogReader(p: LoggerProvider): p is LoggerProvider & LogReader {
+  return typeof (p as Partial<LogReader>).records === "function";
+}
+
+export function createObservability(options: ObservabilityOptions = {}): Observability {
+  const loggerProvider =
+    options.loggerProvider ?? createConsoleLoggerProvider({ minSeverity: options.minSeverity });
+  const meterProvider = options.meterProvider ?? createInMemoryMeterProvider();
+
+  return {
+    logger: (scope) => loggerProvider.getLogger(scope),
+    meter: (scope) => meterProvider.getMeter(scope),
+    metrics: hasMetricsReader(meterProvider) ? meterProvider : undefined,
+    logs: hasLogReader(loggerProvider) ? loggerProvider : undefined,
+    installGlobally() {
+      // The API exposes no "read the current provider object" that round-trips
+      // through disable(), so restoration is a disable rather than a swap-back.
+      // Good enough for the one case that needs it — a test cleaning up.
+      logs.setGlobalLoggerProvider(loggerProvider);
+      metrics.setGlobalMeterProvider(meterProvider);
+      return () => {
+        logs.disable();
+        metrics.disable();
+      };
+    },
+  };
+}
+
+/**
+ * The test flavour: recording consumers on both signals, with the read APIs
+ * guaranteed present so a test does not have to narrow them.
+ *
+ * Same code path as production — only the sink differs — so an assertion here
+ * is an assertion about the real emission, not about a double.
+ */
+export interface RecordingObservability extends Observability {
+  metrics: InMemoryMeterProvider;
+  logs: RecordingLoggerProvider;
+  /** Forget everything captured so far. */
+  reset(): void;
+}
+
+export function createRecordingObservability(): RecordingObservability {
+  const loggerProvider = createRecordingLoggerProvider();
+  const meterProvider = createInMemoryMeterProvider();
+  const base = createObservability({ loggerProvider, meterProvider });
+  return {
+    ...base,
+    metrics: meterProvider,
+    logs: loggerProvider,
+    reset() {
+      loggerProvider.clear();
+      meterProvider.reset();
+    },
+  };
+}
+
+/** An observability that reports nowhere — for a consumer that wants silence. */
+export function createSilentObservability(): Observability {
+  return createObservability({
+    loggerProvider: createSilentLoggerProvider(),
+    meterProvider: createInMemoryMeterProvider(),
+  });
+}
+
+export {
+  createConsoleLoggerProvider,
+  createRecordingLoggerProvider,
+  createSilentLoggerProvider,
+} from "./loggers.js";
+export type {
+  ConsoleLoggerProviderOptions,
+  RecordingLoggerProviderOptions,
+  RecordingLoggerProvider,
+  LogReader,
+  LogWriter,
+} from "./loggers.js";
+export { createInMemoryMeterProvider } from "./meter.js";
+export type { InMemoryMeterProvider, MetricsReader } from "./meter.js";
+export { SEVERITIES, severityRank, seriesKey } from "./types.js";
+export type {
+  Severity,
+  CapturedLog,
+  LogQuery,
+  MetricPoint,
+  MetricSnapshot,
+} from "./types.js";

package/src/observability/loggers.ts

@@ -0,0 +1,174 @@
+/**
+ * The two log consumers: one that writes, one that remembers.
+ *
+ * Both implement `LoggerProvider` from `@opentelemetry/api-logs`, so they are
+ * interchangeable at the one call site that installs them, and so a real
+ * OpenTelemetry SDK is a third option that needs no change to any
+ * instrumentation.
+ *
+ * Why `@opentelemetry/api-logs` is pinned to an EXACT version in package.json
+ * rather than caretted: the logs API is still 0.x. That was checked rather
+ * than assumed — the producing surface used here (`getLogger().emit()`) is
+ * unchanged across the 0.57 → 0.221 range, and the global registration
+ * handshake is keyed on a backwards-compatibility constant that has stayed at
+ * 1 throughout, so two copies at different versions still interoperate. The
+ * churn that does exist is in `@opentelemetry/sdk-logs`, whose
+ * `SimpleLogRecordProcessor` changed constructor shape — which is precisely
+ * why the consumers below are ours and that package is not a dependency. If
+ * upstream ever breaks the producing surface, the whole API is ~137 lines and
+ * forking it is the stated fallback.
+ */
+import type { Logger, LoggerProvider, LogRecord } from "@opentelemetry/api-logs";
+
+import {
+  bodyToString,
+  flattenAttributes,
+  severityRank,
+  type CapturedLog,
+  type LogQuery,
+  type Severity,
+} from "./types.js";
+
+/** Where a console consumer sends a formatted line. Injected so tests capture it. */
+export interface LogWriter {
+  (severity: Severity, line: string): void;
+}
+
+const defaultWriter: LogWriter = (severity, line) => {
+  if (severity === "ERROR" || severity === "FATAL") console.error(line);
+  else if (severity === "WARN") console.warn(line);
+  else console.log(line);
+};
+
+export interface ConsoleLoggerProviderOptions {
+  /** Records below this severity are dropped before formatting. Default INFO. */
+  minSeverity?: Severity;
+  write?: LogWriter;
+}
+
+/**
+ * Formats to the `[scope] message key=value` shape this repo already logs in,
+ * so adopting structured emission does not churn every existing log line's
+ * appearance at the same time.
+ */
+function formatLine(record: CapturedLog): string {
+  const attrs = Object.entries(record.attributes)
+    .filter(([, v]) => v !== undefined)
+    .map(([k, v]) => `${k}=${String(v)}`);
+  return `[${record.scope}] ${record.body}${attrs.length ? ` ${attrs.join(" ")}` : ""}`;
+}
+
+function toCaptured(scope: string, record: LogRecord): CapturedLog {
+  return {
+    scope,
+    severity: (record.severityText ?? "INFO") as Severity,
+    body: bodyToString(record.body),
+    attributes: flattenAttributes(record.attributes),
+    timestamp: Date.now(),
+  };
+}
+
+/** The production consumer: severity-filtered lines on stdout/stderr. */
+export function createConsoleLoggerProvider(
+  options: ConsoleLoggerProviderOptions = {}
+): LoggerProvider {
+  const threshold = severityRank(options.minSeverity ?? "INFO");
+  const write = options.write ?? defaultWriter;
+
+  return {
+    getLogger(name: string): Logger {
+      return {
+        emit(record: LogRecord) {
+          if (severityRank(record.severityText) < threshold) return;
+          const captured = toCaptured(name, record);
+          write(captured.severity, formatLine(captured));
+        },
+        enabled(opts?: { severityNumber?: number }) {
+          void opts;
+          return true;
+        },
+      } as Logger;
+    },
+  };
+}
+
+/** Read side of the recording consumer. */
+export interface LogReader {
+  /** Everything captured, in emit order. */
+  records(): CapturedLog[];
+  /** Records matching every field of the query. */
+  find(query?: LogQuery): CapturedLog[];
+  /** How many records match — the common assertion. */
+  count(query?: LogQuery): number;
+  clear(): void;
+}
+
+export interface RecordingLoggerProvider extends LoggerProvider, LogReader {}
+
+function matches(record: CapturedLog, query: LogQuery): boolean {
+  if (query.scope !== undefined && record.scope !== query.scope) return false;
+  if (query.severity !== undefined && record.severity !== query.severity) return false;
+  if (query.minSeverity !== undefined && severityRank(record.severity) < severityRank(query.minSeverity)) {
+    return false;
+  }
+  if (query.body !== undefined && !record.body.includes(query.body)) return false;
+  for (const [key, value] of Object.entries(query.attributes ?? {})) {
+    if (record.attributes[key] !== value) return false;
+  }
+  return true;
+}
+
+export interface RecordingLoggerProviderOptions {
+  /**
+   * Cap on retained records. A test asserts on a handful; a long-lived process
+   * that installed this by accident should not grow without bound. Oldest are
+   * dropped first. Default 1000.
+   */
+  limit?: number;
+}
+
+/**
+ * The consumer a test installs. Because it implements the same interface the
+ * production consumer does, a test asserts against the real emission path —
+ * the instrumentation under test cannot tell the difference.
+ */
+export function createRecordingLoggerProvider(
+  options: RecordingLoggerProviderOptions = {}
+): RecordingLoggerProvider {
+  const limit = options.limit ?? 1000;
+  const captured: CapturedLog[] = [];
+
+  return {
+    getLogger(name: string): Logger {
+      return {
+        emit(record: LogRecord) {
+          captured.push(toCaptured(name, record));
+          if (captured.length > limit) captured.splice(0, captured.length - limit);
+        },
+        enabled() {
+          return true;
+        },
+      } as Logger;
+    },
+    records: () => [...captured],
+    find: (query = {}) => captured.filter((r) => matches(r, query)),
+    count: (query = {}) => captured.reduce((n, r) => n + (matches(r, query) ? 1 : 0), 0),
+    clear: () => {
+      captured.length = 0;
+    },
+  };
+}
+
+/** A consumer that discards everything — the default when nothing is installed. */
+export function createSilentLoggerProvider(): LoggerProvider {
+  return {
+    getLogger(): Logger {
+      return {
+        emit() {},
+        enabled() {
+          return false;
+        },
+      } as Logger;
+    },
+  };
+}

package/src/observability/meter.ts

@@ -0,0 +1,190 @@
+/**
+ * An in-process `MeterProvider` — the counters behind `/api/status`, and the
+ * assertion surface for tests.
+ *
+ * One implementation serves both on purpose. A test double that is a different
+ * implementation from the production one only proves the double works; this
+ * way, the thing a test asserts against is the thing that actually counts in
+ * production.
+ *
+ * It is NOT `@opentelemetry/sdk-metrics`. The producing side is the standard
+ * API, so instrumentation is portable and a real SDK can replace this without
+ * touching a single `counter.add()` call — but the consuming side is ours,
+ * which is what keeps the dependency surface to one stable package.
+ *
+ * Synchronous instruments (counter, up-down counter, histogram, gauge) record.
+ * The observable/async instruments satisfy the interface and do nothing: they
+ * require a collection cycle to be meaningful, and nothing here runs one. A
+ * caller reaching for one is a signal to bring in a real SDK, not to grow this.
+ */
+import type {
+  Attributes,
+  BatchObservableCallback,
+  Counter,
+  Gauge,
+  Histogram,
+  Meter,
+  MeterOptions,
+  MeterProvider,
+  MetricOptions,
+  Observable,
+  ObservableCounter,
+  ObservableGauge,
+  ObservableUpDownCounter,
+  UpDownCounter,
+} from "@opentelemetry/api";
+
+import {
+  flattenAttributes,
+  seriesKey,
+  type MetricPoint,
+  type MetricSnapshot,
+} from "./types.js";
+
+/** Read side of the recorded metrics. */
+export interface MetricsReader {
+  /** Every recorded series, sorted by name then attribute key. */
+  snapshot(): MetricSnapshot;
+  /** One series' value, or undefined when nothing recorded it. */
+  value(name: string, attributes?: Attributes): number | undefined;
+  /** Summed across every attribute combination of an instrument. */
+  total(name: string): number;
+  reset(): void;
+}
+
+interface Series extends MetricPoint {
+  key: string;
+}
+
+class Recorder {
+  private readonly series = new Map<string, Series>();
+
+  record(
+    name: string,
+    kind: MetricPoint["kind"],
+    value: number,
+    attributes: Attributes | undefined
+  ): void {
+    const key = seriesKey(name, attributes);
+    const existing = this.series.get(key);
+    if (existing) {
+      // A gauge is a level, not an accumulation.
+      existing.value = kind === "gauge" ? value : existing.value + value;
+      return;
+    }
+    this.series.set(key, { key, name, kind, value, attributes: flattenAttributes(attributes) });
+  }
+
+  snapshot(): MetricSnapshot {
+    return [...this.series.values()]
+      .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+      .map(({ name, attributes, value, kind }) => ({ name, attributes, value, kind }));
+  }
+
+  value(name: string, attributes?: Attributes): number | undefined {
+    return this.series.get(seriesKey(name, attributes))?.value;
+  }
+
+  total(name: string): number {
+    let sum = 0;
+    for (const s of this.series.values()) if (s.name === name) sum += s.value;
+    return sum;
+  }
+
+  reset(): void {
+    this.series.clear();
+  }
+}
+
+/** Instruments that do nothing, for the async half of the Meter interface. */
+function noopObservable<T>(): T {
+  return {
+    addCallback() {},
+    removeCallback() {},
+  } as T;
+}
+
+class InMemoryMeter implements Meter {
+  constructor(private readonly recorder: Recorder) {}
+
+  createCounter<A extends Attributes = Attributes>(
+    name: string,
+    _options?: MetricOptions
+  ): Counter<A> {
+    return {
+      add: (value: number, attributes?: A) =>
+        this.recorder.record(name, "counter", value, attributes),
+    } as Counter<A>;
+  }
+
+  createUpDownCounter<A extends Attributes = Attributes>(
+    name: string,
+    _options?: MetricOptions
+  ): UpDownCounter<A> {
+    return {
+      add: (value: number, attributes?: A) =>
+        this.recorder.record(name, "updowncounter", value, attributes),
+    } as UpDownCounter<A>;
+  }
+
+  createHistogram<A extends Attributes = Attributes>(
+    name: string,
+    _options?: MetricOptions
+  ): Histogram<A> {
+    return {
+      // Count of observations, not the distribution: a real SDK owns buckets.
+      record: (_value: number, attributes?: A) =>
+        this.recorder.record(name, "histogram", 1, attributes),
+    } as Histogram<A>;
+  }
+
+  createGauge<A extends Attributes = Attributes>(
+    name: string,
+    _options?: MetricOptions
+  ): Gauge<A> {
+    return {
+      record: (value: number, attributes?: A) =>
+        this.recorder.record(name, "gauge", value, attributes),
+    } as Gauge<A>;
+  }
+
+  createObservableGauge<A extends Attributes = Attributes>(): ObservableGauge<A> {
+    return noopObservable<ObservableGauge<A>>();
+  }
+  createObservableCounter<A extends Attributes = Attributes>(): ObservableCounter<A> {
+    return noopObservable<ObservableCounter<A>>();
+  }
+  createObservableUpDownCounter<
+    A extends Attributes = Attributes,
+  >(): ObservableUpDownCounter<A> {
+    return noopObservable<ObservableUpDownCounter<A>>();
+  }
+  addBatchObservableCallback<A extends Attributes = Attributes>(
+    _callback: BatchObservableCallback<A>,
+    _observables: Observable<A>[]
+  ): void {}
+  removeBatchObservableCallback<A extends Attributes = Attributes>(
+    _callback: BatchObservableCallback<A>,
+    _observables: Observable<A>[]
+  ): void {}
+}
+
+export interface InMemoryMeterProvider extends MeterProvider, MetricsReader {}
+
+/**
+ * A provider whose meters all write into one recorder, so a snapshot spans
+ * every instrumentation scope in the process.
+ */
+export function createInMemoryMeterProvider(): InMemoryMeterProvider {
+  const recorder = new Recorder();
+  const meter = new InMemoryMeter(recorder);
+  return {
+    getMeter(_name: string, _version?: string, _options?: MeterOptions): Meter {
+      return meter;
+    },
+    snapshot: () => recorder.snapshot(),
+    value: (name, attributes) => recorder.value(name, attributes),
+    total: (name) => recorder.total(name),
+    reset: () => recorder.reset(),
+  };
+}