serverless-ircd 0.1.0 → 0.3.0

package/packages/irc-core/src/ports.ts

@@ -6,6 +6,8 @@
  * can pin the timeline and identity space (PLAN §8 determinism rules).
  */
 
+import { caseFold } from './case-fold.js';
+
 /** Read-only wall clock, epoch milliseconds. */
 export interface Clock {
   now(): number;
@@ -49,6 +51,8 @@ export interface IdFactory {
   nonce(): string;
   /** SASL / session-scoped id. */
   sessionId(): string;
+  /** Per-request observability trace id, propagated via {@link Ctx}. */
+  traceId(): string;
 }
 
 /**
@@ -67,6 +71,9 @@ export class UuidIdFactory implements IdFactory {
   sessionId(): string {
     return uuidV4();
   }
+  traceId(): string {
+    return uuidV4();
+  }
 }
 
 // RFC 4122 v4 shape (random). Six fixed bits identify the version/variant;
@@ -105,6 +112,9 @@ export class SequentialIdFactory implements IdFactory {
   sessionId(): string {
     return `session-${this.counter++}`;
   }
+  traceId(): string {
+    return `trace-${this.counter++}`;
+  }
 }
 
 /**
@@ -151,3 +161,712 @@ export class StaticMotdProvider implements MotdProvider {
 
 /** Convenience: a {@link MotdProvider} that always reports "no MOTD". */
 export const EmptyMotdProvider: MotdProvider = new StaticMotdProvider([]);
+
+/**
+ * Parsed SASL credentials handed to an {@link AccountStore}.
+ *
+ * `PLAIN` is the structured form produced by base64-decoding and splitting
+ * the `\0authzid\0authcid\0passwd` payload. `RAW` carries the decoded bytes
+ * for any other mechanism the server wants to forward verbatim.
+ */
+export type SaslPayload =
+  | { kind: 'PLAIN'; username: string; password: string }
+  | { kind: 'RAW'; data: string };
+
+/**
+ * Outcome of an {@link AccountStore.verify} call: either the canonical
+ * account name to record on the connection, or a human-readable reason
+ * for the failure that surfaces as `904 ERR_SASLFAIL`.
+ */
+export type SaslResult = { ok: true; account: string } | { ok: false; reason: string };
+
+/**
+ * Port that verifies SASL credentials against the deployment's account
+ * backend.
+ *
+ * The method is **synchronous** on purpose: reducers must stay pure and
+ * cannot await. Adapters that need an async lookup (D1, DynamoDB, Secrets
+ * Manager) pre-load the credentials they need into a synchronously-readable
+ * store (mirroring the {@link MotdProvider} pattern). For Phase 1 the
+ * in-memory reference adapter and tests inject a fake directly.
+ */
+export interface AccountStore {
+  verify(mech: string, payload: SaslPayload): SaslResult;
+}
+
+/**
+ * One SASL PLAIN credential entry seeded into an {@link InMemoryAccountStore}.
+ * The `username` is also the canonical account name recorded on the
+ * connection for `extended-join` / `account-tag`.
+ */
+export interface SaslAccountCredential {
+  username: string;
+  password: string;
+}
+
+/**
+ * Reference in-memory {@link AccountStore} backed by a static list of PLAIN
+ * credentials seeded at construction.
+ *
+ * Mirrors the {@link InMemoryMessageStore} / {@link StaticMotdProvider}
+ * pattern: the port is synchronous, so adapters that need an async backend
+ * (D1, DynamoDB, Secrets Manager) pre-load their credentials into this store
+ * at boot. All three adapters (local-cli, CF, AWS) use this as the minimum
+ * viable `AccountStore`; a persistent variant (DynamoDB `Accounts` table, D1)
+ * is a documented follow-up that swaps in by replacing the construction call.
+ *
+ * Password comparison is constant-time to avoid the early-return timing
+ * oracle a naive `===` would expose. Only `PLAIN` is verified; any other
+ * mechanism returns failure (matching the reducer's mech gating).
+ */
+export class InMemoryAccountStore implements AccountStore {
+  private readonly creds: ReadonlyMap<string, string>;
+
+  constructor(credentials: ReadonlyArray<SaslAccountCredential>) {
+    this.creds = new Map(credentials.map((c) => [c.username, c.password]));
+  }
+
+  verify(mech: string, payload: SaslPayload): SaslResult {
+    if (mech.toUpperCase() !== 'PLAIN' || payload.kind !== 'PLAIN') {
+      return { ok: false, reason: `unsupported mechanism: ${mech}` };
+    }
+    const expected = this.creds.get(payload.username);
+    if (expected === undefined) {
+      return { ok: false, reason: 'invalid credentials' };
+    }
+    if (!constantTimeEquals(payload.password, expected)) {
+      return { ok: false, reason: 'invalid credentials' };
+    }
+    return { ok: true, account: payload.username };
+  }
+}
+
+/**
+ * Constant-time string equality. Compares every byte regardless of early
+ * mismatches so a remote attacker cannot short-circuit the comparison via a
+ * timing side-channel. Returns `false` when the lengths differ (the length
+ * is not considered secret for SASL PLAIN passwords).
+ */
+function constantTimeEquals(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+// ============================================================================
+// Chat-history persistence (IRCv3 draft/chathistory)
+// ============================================================================
+
+/** IRC message commands that chathistory can replay. */
+export type StoredCommand = 'PRIVMSG' | 'NOTICE' | 'TAGMSG';
+
+/**
+ * One persisted channel message, as recorded by the PRIVMSG/NOTICE/TAGMSG
+ * reducers and replayed by chathistory.
+ *
+ * `chan` is the lowercased channel name (the storage key); the display name
+ * is reconstructed by the reducer from the authoritative {@link ChannelState}
+ * when building replay lines. `time` is epoch milliseconds from the injected
+ * {@link Clock}; `msgid` is a fresh nonce from {@link IdFactory}.
+ */
+export interface StoredMessage {
+  msgid: string;
+  time: number;
+  chan: string;
+  command: StoredCommand;
+  nick: string;
+  user?: string;
+  host?: string;
+  text: string;
+}
+
+/** Subcommands of `CHATHISTORY` that select a slice of the backlog. */
+export type HistoryDirection = 'latest' | 'before' | 'after' | 'between' | 'around';
+
+/**
+ * One chathistory query. The reducer builds this from the parsed command and
+ * hands it to {@link MessageStore.query}; results come back synchronously.
+ *
+ * `msgid` is the pivot for `before` / `after` / `around` and the first bound
+ * for `between`; `msgid2` is the second bound for `between`. For `latest`,
+ * `msgid` may be omitted or the literal `*` to mean "most recent".
+ */
+export interface HistoryQuery {
+  chan: string;
+  direction: HistoryDirection;
+  limit: number;
+  msgid?: string;
+  msgid2?: string;
+}
+
+/** One entry in a `CHATHISTORY TARGETS` reply: a channel with recent activity. */
+export interface TargetEntry {
+  /** Lowercased channel name. */
+  chan: string;
+  /** Epoch ms of the most recent in-window message for this channel. */
+  time: number;
+}
+
+/**
+ * Persistence port for IRCv3 `draft/chathistory` playback.
+ *
+ * Mirrors the {@link MotdProvider} / {@link AccountStore} pattern: the port
+ * is **synchronous** (reducers must stay pure and free of IO) and injected
+ * via {@link Ctx}. Adapters that need async storage (D1, R2, DynamoDB)
+ * pre-load the relevant slice into a synchronously-readable store; Phase 1
+ * ships the in-memory reference implementation only.
+ *
+ * `query` always returns messages oldest-first (chronological order), the
+ * shape `BATCH chathistory` expects on the wire.
+ */
+export interface MessageStore {
+  /** Appends a message to the channel's history (eviction policy is impl-defined). */
+  record(message: StoredMessage): void;
+  /** Returns the slice described by `query`, oldest-first. */
+  query(q: HistoryQuery): StoredMessage[];
+  /**
+   * Returns the most recent `limit` messages strictly after `sinceMsgid`
+   * (or the most recent `limit` overall when `sinceMsgid` is undefined or
+   * no longer retained), oldest-first. This is the JOIN auto-playback query
+   * and differs from the `after` direction, which returns the *first* `limit`
+   * messages after a pivot.
+   */
+  recent(chan: string, sinceMsgid: string | undefined, limit: number): StoredMessage[];
+  /** Returns true iff `msgid` is currently retained for `chan`. */
+  hasMsgid(chan: string, msgid: string): boolean;
+  /** Enumerates channels with activity inside `[since, until]`, newest-first. */
+  targets(since: number, until: number): TargetEntry[];
+}
+
+/** Default per-channel retention cap when none is supplied. */
+const DEFAULT_MAX_PER_CHANNEL = 100;
+
+/** Sentinel meaning "most recent" for the `LATEST` direction pivot. */
+const LATEST_WILDCARD = '*';
+
+/**
+ * Reference in-memory {@link MessageStore} backed by a per-channel ring
+ * buffer with a configurable cap.
+ *
+ * Used by the local CLI and by tests. Each channel keeps its messages in a
+ * chronological array; once the array exceeds `maxPerChannel` the oldest
+ * entries are dropped. A `msgid → message` index accelerates pivot lookups
+ * and {@link hasMsgid}.
+ */
+export class InMemoryMessageStore implements MessageStore {
+  private readonly byChan = new Map<string, StoredMessage[]>();
+  private readonly maxPerChannel: number;
+
+  constructor(maxPerChannel: number = DEFAULT_MAX_PER_CHANNEL) {
+    this.maxPerChannel = maxPerChannel;
+  }
+
+  record(message: StoredMessage): void {
+    const key = caseFold('rfc1459', message.chan);
+    let arr = this.byChan.get(key);
+    if (arr === undefined) {
+      arr = [];
+      this.byChan.set(key, arr);
+    }
+    arr.push(message);
+    if (arr.length > this.maxPerChannel) {
+      arr.splice(0, arr.length - this.maxPerChannel);
+    }
+  }
+
+  query(q: HistoryQuery): StoredMessage[] {
+    if (q.limit <= 0) return [];
+    const arr = this.byChan.get(caseFold('rfc1459', q.chan));
+    if (arr === undefined || arr.length === 0) return [];
+
+    switch (q.direction) {
+      case 'latest':
+        return this.queryLatest(arr, q);
+      case 'before':
+        return this.queryBefore(arr, q);
+      case 'after':
+        return this.queryAfter(arr, q);
+      case 'around':
+        return this.queryAround(arr, q);
+      case 'between':
+        return this.queryBetween(arr, q);
+      default:
+        return [];
+    }
+  }
+
+  hasMsgid(chan: string, msgid: string): boolean {
+    const arr = this.byChan.get(caseFold('rfc1459', chan));
+    if (arr === undefined) return false;
+    return arr.some((m) => m.msgid === msgid);
+  }
+
+  recent(chan: string, sinceMsgid: string | undefined, limit: number): StoredMessage[] {
+    if (limit <= 0) return [];
+    const arr = this.byChan.get(caseFold('rfc1459', chan));
+    if (arr === undefined || arr.length === 0) return [];
+    let start = 0;
+    if (sinceMsgid !== undefined) {
+      const idx = indexOfMsgid(arr, sinceMsgid);
+      // If the marker was evicted, fall back to the most recent `limit`
+      // overall rather than skipping playback entirely.
+      if (idx !== -1) start = idx + 1;
+    }
+    return tail(arr.slice(start), limit);
+  }
+
+  targets(since: number, until: number): TargetEntry[] {
+    const out: TargetEntry[] = [];
+    for (const [chan, arr] of this.byChan) {
+      let best = -1;
+      for (const m of arr) {
+        if (m.time >= since && m.time <= until && m.time > best) best = m.time;
+      }
+      if (best !== -1) out.push({ chan, time: best });
+    }
+    out.sort((a, b) => b.time - a.time);
+    return out;
+  }
+
+  private queryLatest(arr: StoredMessage[], q: HistoryQuery): StoredMessage[] {
+    if (q.msgid !== undefined && q.msgid !== LATEST_WILDCARD) {
+      const idx = indexOfMsgid(arr, q.msgid);
+      if (idx === -1) return [];
+      const slice = arr.slice(0, idx + 1);
+      return tail(slice, q.limit);
+    }
+    return tail(arr, q.limit);
+  }
+
+  private queryBefore(arr: StoredMessage[], q: HistoryQuery): StoredMessage[] {
+    const pivot = q.msgid;
+    if (pivot === undefined) return [];
+    const idx = indexOfMsgid(arr, pivot);
+    if (idx === -1) return [];
+    return tail(arr.slice(0, idx), q.limit);
+  }
+
+  private queryAfter(arr: StoredMessage[], q: HistoryQuery): StoredMessage[] {
+    const pivot = q.msgid;
+    if (pivot === undefined) return [];
+    const idx = indexOfMsgid(arr, pivot);
+    if (idx === -1) return [];
+    return arr.slice(idx + 1, idx + 1 + q.limit);
+  }
+
+  private queryAround(arr: StoredMessage[], q: HistoryQuery): StoredMessage[] {
+    const pivot = q.msgid;
+    if (pivot === undefined) return [];
+    const idx = indexOfMsgid(arr, pivot);
+    if (idx === -1) return [];
+    const half = Math.floor(q.limit / 2);
+    // Center a `limit`-sized window on the pivot, then slide it to stay in
+    // bounds so boundaries fill from the available side instead of shrinking.
+    let start = idx - half;
+    if (start < 0) start = 0;
+    if (start + q.limit > arr.length) start = arr.length - q.limit;
+    if (start < 0) start = 0;
+    return arr.slice(start, start + q.limit);
+  }
+
+  private queryBetween(arr: StoredMessage[], q: HistoryQuery): StoredMessage[] {
+    const lo = q.msgid;
+    const hi = q.msgid2;
+    if (lo === undefined || hi === undefined) return [];
+    const loIdx = indexOfMsgid(arr, lo);
+    const hiIdx = indexOfMsgid(arr, hi);
+    if (loIdx === -1 || hiIdx === -1) return [];
+    if (loIdx >= hiIdx) return [];
+    return arr.slice(loIdx + 1, hiIdx + 1);
+  }
+}
+
+/** Returns the index of the first message with `msgid`, or -1. */
+function indexOfMsgid(arr: readonly StoredMessage[], msgid: string): number {
+  for (let i = 0; i < arr.length; i++) {
+    const entry = arr[i];
+    if (entry !== undefined && entry.msgid === msgid) return i;
+  }
+  return -1;
+}
+
+/** Returns the last (newest) up-to-`n` entries of `arr`, in original order. */
+function tail<T>(arr: readonly T[], n: number): T[] {
+  // Callers (query/recent) pre-validate `n > 0`; the Math.max below also
+  // clamps to a valid slice, so an explicit `n <= 0` branch is unreachable.
+  const start = Math.max(0, arr.length - n);
+  return arr.slice(start);
+}
+
+// ============================================================================
+// Observability — structured logger
+// ============================================================================
+
+/**
+ * Log severity level. Ordering matters: a logger configured with
+ * {@link LogLevel.Info} suppresses {@link LogLevel.Debug} records.
+ */
+export enum LogLevel {
+  Debug = 10,
+  Info = 20,
+  Warn = 30,
+  Error = 40,
+}
+
+/**
+ * Human-readable label for a {@link LogLevel}, used as `level` in output.
+ *
+ * Exhaustive over the {@link LogLevel} enum — TypeScript verifies the
+ * switch covers every variant. Any unknown value would be a type hole,
+ * which is precisely what we want: callers cannot construct a fifth
+ * level without updating this mapping.
+ */
+function levelLabel(level: LogLevel): string {
+  switch (level) {
+    case LogLevel.Debug:
+      return 'debug';
+    case LogLevel.Info:
+      return 'info';
+    case LogLevel.Warn:
+      return 'warn';
+    case LogLevel.Error:
+      return 'error';
+  }
+}
+
+/**
+ * One structured log record.
+ *
+ * `traceId` and `connectionId` are the cross-cutting identifiers
+ * (observability contract); reducers / dispatch / adapter layers
+ * stamp them via the bound {@link Logger} so a single request's path
+ * through the actor → dispatch → runtime pipeline can be reconstructed
+ * end-to-end.
+ *
+ * `fields` carries any per-record structured context beyond those two
+ * (channel name, command, byte length, error detail, …).
+ */
+export interface LogRecord {
+  /** Epoch milliseconds from the injected {@link Clock}. */
+  ts: number;
+  /** Severity. */
+  level: LogLevel;
+  /** Short human-readable event name (e.g. `"receive"`, `"dispatch"`). */
+  msg: string;
+  /** Per-request trace id, propagated through {@link Ctx}. */
+  traceId?: string;
+  /** Connection id the event concerns, when relevant. */
+  connectionId?: string;
+  /** Per-event structured context. */
+  fields?: Record<string, unknown>;
+}
+
+/**
+ * Sink callback for low-level log routing (used by tests and adapters
+ * that want to layer metrics on top of each record).
+ */
+export type LogSink = (record: LogRecord) => void;
+
+/**
+ * Structured logger port.
+ *
+ * Reducers are pure and therefore must not call this directly; the
+ * actor / dispatch / adapter layers do. Each adapter injects a concrete
+ * implementation:
+ *
+ *   - tests: {@link CapturingLogger}
+ *   - local-cli / Lambda: {@link ConsoleLogger}
+ *   - Cloudflare Workers: a `ConsoleLogger` whose sink writes to `console`
+ *     (Workers' `console.log` streams into Workers Analytics Observability)
+ *
+ * `child()` returns a new logger bound to extra context fields — the
+ * canonical pattern is to bind `traceId` + `connectionId` once when the
+ * actor is constructed, then every record the actor emits carries them
+ * automatically.
+ */
+export interface Logger {
+  debug(msg: string, fields?: Record<string, unknown>): void;
+  info(msg: string, fields?: Record<string, unknown>): void;
+  warn(msg: string, fields?: Record<string, unknown>): void;
+  error(msg: string, fields?: Record<string, unknown>): void;
+  /** Logs at the supplied level. Used by plumbing that maps levels dynamically. */
+  on(level: LogLevel, msg: string, fields?: Record<string, unknown>): void;
+  /** Returns a logger that stamps `fields` onto every record in addition to its parent's. */
+  child(fields: LoggerContext): Logger;
+}
+
+/** Cross-cutting fields every logger implementation recognises. */
+export interface LoggerContext {
+  traceId?: string;
+  connectionId?: string;
+  // Allow arbitrary structured fields alongside the cross-cutting ones.
+  [key: string]: unknown;
+}
+
+/** Logger that drops every record. Default for unit tests of pure code. */
+export class NoopLogger implements Logger {
+  constructor(private readonly minLevel: LogLevel = LogLevel.Debug) {}
+  debug(msg: string, fields?: Record<string, unknown>): void {
+    this.on(LogLevel.Debug, msg, fields);
+  }
+  info(msg: string, fields?: Record<string, unknown>): void {
+    this.on(LogLevel.Info, msg, fields);
+  }
+  warn(msg: string, fields?: Record<string, unknown>): void {
+    this.on(LogLevel.Warn, msg, fields);
+  }
+  error(msg: string, fields?: Record<string, unknown>): void {
+    this.on(LogLevel.Error, msg, fields);
+  }
+  on(level: LogLevel, _msg: string, _fields?: Record<string, unknown>): void {
+    if (level < this.minLevel) return;
+    // No-op: unit tests of pure code do not want I/O during the run.
+  }
+  child(_fields: LoggerContext): Logger {
+    return this;
+  }
+}
+
+/**
+ * Shared singleton: a {@link NoopLogger} with the lowest possible
+ * threshold. The canonical default for reducers / dispatch / actor paths
+ * when no concrete logger is supplied — every call becomes a no-op.
+ */
+export const NoopLoggerInstance: Logger = new NoopLogger();
+
+/**
+ * Test logger that retains every record in `records`. The `records` array
+ * is intentionally mutable so tests can assert ordering and shape directly.
+ *
+ * `traceId` / `connectionId` supplied in the constructor are stamped on
+ * every record — same pattern as production loggers. `child()` returns a
+ * new logger bound to extra context fields that shares the parent's
+ * `records` sink, so records emitted on a child are visible from the root.
+ */
+export class CapturingLogger implements Logger {
+  readonly records: LogRecord[] = [];
+  private readonly ctx: LoggerContext;
+  private readonly minLevel: LogLevel;
+  private readonly clock: Clock;
+  /** @internal shared sink so child loggers push into the parent's array. */
+  readonly sink: LogRecord[];
+
+  constructor(ctx: LoggerContext = {}, minLevel: LogLevel = LogLevel.Debug, clock?: Clock) {
+    this.ctx = ctx;
+    this.minLevel = minLevel;
+    this.clock = clock ?? SystemClock;
+    this.sink = this.records;
+  }
+  debug(msg: string, fields?: Record<string, unknown>): void {
+    this.capture(LogLevel.Debug, msg, fields);
+  }
+  info(msg: string, fields?: Record<string, unknown>): void {
+    this.capture(LogLevel.Info, msg, fields);
+  }
+  warn(msg: string, fields?: Record<string, unknown>): void {
+    this.capture(LogLevel.Warn, msg, fields);
+  }
+  error(msg: string, fields?: Record<string, unknown>): void {
+    this.capture(LogLevel.Error, msg, fields);
+  }
+  on(level: LogLevel, msg: string, fields?: Record<string, unknown>): void {
+    this.capture(level, msg, fields);
+  }
+  child(fields: LoggerContext): Logger {
+    // Share the parent's records sink so a child's emissions are visible
+    // from the root logger the test holds.
+    return CapturingLogger.withSink(
+      this.sink,
+      { ...this.ctx, ...fields },
+      this.minLevel,
+      this.clock,
+    );
+  }
+  private static withSink(
+    sink: LogRecord[],
+    ctx: LoggerContext,
+    minLevel: LogLevel,
+    clock: Clock,
+  ): CapturingLogger {
+    const inst = new CapturingLogger(ctx, minLevel, clock);
+    // Reassign the per-instance `records`/`sink` to the shared parent sink
+    // so child records land in the parent's array.
+    (inst as { records: LogRecord[] }).records = sink;
+    (inst as { sink: LogRecord[] }).sink = sink;
+    return inst;
+  }
+  private capture(level: LogLevel, msg: string, fields?: Record<string, unknown>): void {
+    if (level < this.minLevel) return;
+    const ids = extractIds(this.ctx, fields);
+    const merged = mergeFields(this.ctx, fields);
+    const rec: LogRecord = {
+      ts: this.clock.now(),
+      level,
+      msg,
+      ...(ids.traceId !== undefined ? { traceId: ids.traceId } : {}),
+      ...(ids.connectionId !== undefined ? { connectionId: ids.connectionId } : {}),
+      ...(Object.keys(merged).length > 0 ? { fields: merged } : {}),
+    };
+    this.sink.push(rec);
+  }
+}
+
+/**
+ * Extracts the cross-cutting identifiers from the logger
+ * context plus the per-call fields. Per-call values win — a child logger
+ * bound to `connectionId: c-1` can still override it on a single record.
+ */
+function extractIds(
+  ctx: LoggerContext,
+  call: Record<string, unknown> | undefined,
+): { traceId?: string; connectionId?: string } {
+  const out: { traceId?: string; connectionId?: string } = {};
+  if (typeof ctx.traceId === 'string') out.traceId = ctx.traceId;
+  if (typeof ctx.connectionId === 'string') out.connectionId = ctx.connectionId;
+  if (call !== undefined) {
+    if (typeof call.traceId === 'string') out.traceId = call.traceId;
+    if (typeof call.connectionId === 'string') out.connectionId = call.connectionId;
+  }
+  return out;
+}
+
+/**
+ * Merges the per-context fields (excluding the cross-cutting ids) with the
+ * per-call fields. Call fields win on conflict. Cross-cutting ids are
+ * promoted to top-level `LogRecord` fields by the caller, so they are
+ * stripped from the merged `fields` bag to avoid duplication.
+ */
+function mergeFields(
+  ctx: LoggerContext,
+  call: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(ctx)) {
+    if (k === 'traceId' || k === 'connectionId') continue;
+    out[k] = v;
+  }
+  if (call !== undefined) {
+    for (const [k, v] of Object.entries(call)) {
+      if (k === 'traceId' || k === 'connectionId') continue;
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * Sink typealias for the four `console.*` methods. Adapters that want to
+ * fan-out to CloudWatch Logs or Workers Analytics can supply a custom
+ * sink; the default is the global `console`.
+ */
+export interface ConsoleLoggerSinks {
+  debug(payload: string): void;
+  info(payload: string): void;
+  warn(payload: string): void;
+  error(payload: string): void;
+}
+
+/** Minimal structural shape of the global `console`. */
+type GlobalConsole = Pick<ConsoleLoggerSinks, 'debug' | 'info' | 'warn' | 'error'>;
+
+/**
+ * Logger that serialises each record as a single-line JSON string and
+ * writes it to the matching console sink.
+ *
+ * Used in production by `apps/local-cli` (Node), AWS Lambda (Node), and
+ * Cloudflare Workers (where `console.log` is captured by Workers
+ * Analytics Observability and surfaced in theWorkers Logpush / wrangler
+ * tail pipeline).
+ *
+ * Output shape: `{ ts, level, msg, traceId?, connectionId?, ...fields }`
+ * — one physical line per record (no embedded newlines) so downstream
+ * log shippers can split cleanly.
+ */
+export class ConsoleLogger implements Logger {
+  private readonly ctx: LoggerContext;
+  private readonly minLevel: LogLevel;
+  private readonly clock: Clock;
+  private readonly sinks: ConsoleLoggerSinks;
+
+  constructor(
+    ctx: LoggerContext = {},
+    sinks?: ConsoleLoggerSinks,
+    minLevel: LogLevel = LogLevel.Debug,
+    clock?: Clock,
+  ) {
+    this.ctx = ctx;
+    this.minLevel = minLevel;
+    this.clock = clock ?? SystemClock;
+    this.sinks = sinks ?? globalThisConsoleSinks();
+  }
+  debug(msg: string, fields?: Record<string, unknown>): void {
+    this.write(LogLevel.Debug, msg, fields);
+  }
+  info(msg: string, fields?: Record<string, unknown>): void {
+    this.write(LogLevel.Info, msg, fields);
+  }
+  warn(msg: string, fields?: Record<string, unknown>): void {
+    this.write(LogLevel.Warn, msg, fields);
+  }
+  error(msg: string, fields?: Record<string, unknown>): void {
+    this.write(LogLevel.Error, msg, fields);
+  }
+  on(level: LogLevel, msg: string, fields?: Record<string, unknown>): void {
+    this.write(level, msg, fields);
+  }
+  child(fields: LoggerContext): Logger {
+    return new ConsoleLogger({ ...this.ctx, ...fields }, this.sinks, this.minLevel, this.clock);
+  }
+  private write(level: LogLevel, msg: string, fields?: Record<string, unknown>): void {
+    if (level < this.minLevel) return;
+    const ids = extractIds(this.ctx, fields);
+    const merged = mergeFields(this.ctx, fields);
+    const payload: Record<string, unknown> = {
+      ts: new Date(this.clock.now()).toISOString(),
+      level: levelLabel(level),
+      msg,
+      ...merged,
+    };
+    if (ids.traceId !== undefined) payload.traceId = ids.traceId;
+    if (ids.connectionId !== undefined) payload.connectionId = ids.connectionId;
+    const line = JSON.stringify(payload);
+    // Exhaustive over the LogLevel enum; TS verifies every variant is
+    // routed to its matching sink.
+    switch (level) {
+      case LogLevel.Debug:
+        this.sinks.debug(line);
+        return;
+      case LogLevel.Info:
+        this.sinks.info(line);
+        return;
+      case LogLevel.Warn:
+        this.sinks.warn(line);
+        return;
+      case LogLevel.Error:
+        this.sinks.error(line);
+        return;
+    }
+  }
+}
+
+/** Returns the global `console` as a {@link ConsoleLoggerSinks}. */
+function globalThisConsoleSinks(): ConsoleLoggerSinks {
+  // `globalThis.console` is universal across Node 20, Workers, and Lambda.
+  // Reference it lazily so tests that stub the logger do not need to
+  // replace the global.
+  const c = (globalThis as { console?: GlobalConsole }).console;
+  if (c === undefined) {
+    // Defensive: a runtime without `globalThis.console`. Every level drops.
+    const drop = (): void => {};
+    return { debug: drop, info: drop, warn: drop, error: drop };
+  }
+  return {
+    debug: (p) => c.debug(p),
+    info: (p) => c.info(p),
+    warn: (p) => c.warn(p),
+    error: (p) => c.error(p),
+  };
+}