serverless-ircd 0.4.0 → 0.6.0

package/packages/cf-adapter/src/connection-do.ts

@@ -16,9 +16,8 @@
  *   - `alarm()`                       PING sweep; missing PONG disconnects.
  *
  * Cross-DO coordination:
- *   - `REGISTRY_DO` — sharded nick registry (034).
- *   - `CHANNEL_DO` per lowercased channel — authoritative roster/modes
- *     (035).
+ *   - `REGISTRY_DO` — sharded nick registry.
+ *   - `CHANNEL_DO` per lowercased channel — authoritative roster/modes.
  *
  * The actor's `ActorChannelAccess` is a passthrough that returns
  * throwaway {@link ChannelState} objects — reducers mutate the local
@@ -52,35 +51,40 @@ import {
   type ServerConfig,
   SystemClock,
   UuidIdFactory,
+  type WsFrameMode,
   createChannel,
   createConnection,
+  frameToLines,
+  isWithinWsByteBudget,
+  parseSecWsProtocolOffers,
+  sanitizeForTextMode,
+  selectSubprotocol,
   toSnapshot,
+  wsFrameModeFor,
 } from '@serverless-ircd/irc-core';
-import { ConnectionActor } from '@serverless-ircd/irc-server';
+import { ConnectionActor, type Transport } from '@serverless-ircd/irc-server';
 import { makeCfRuntime } from './cf-runtime.js';
 import type { CfConnectionHandlers } from './cf-runtime.js';
+import { loadServerConfigFromCfEnv } from './config-loader.js';
 import { resolveAccountStore } from './d1-account-store.js';
 import type { Env } from './env.js';
 import { STATE_STORAGE_KEY, deserialize, serialize } from './serialize.js';
 import type { PersistedConnectionState } from './serialize.js';
+import { CfStats } from './stats.js';
 
 /** Default PING cadence (ms) — tuned for typical IRC client behavior. */
 export const DEFAULT_PING_INTERVAL_MS = 60_000;
 /** Default no-PONG disconnect threshold (ms). */
 export const DEFAULT_PONG_TIMEOUT_MS = 90_000;
 
-/** Server config defaults; production deployments override via env. */
-const DEFAULT_SERVER_CONFIG: ServerConfig = {
-  serverName: 'irc.example.com',
-  networkName: 'ServerlessIRCd',
-  maxChannelsPerUser: 30,
-  maxTargetsPerCommand: 10,
-  maxListEntries: 50,
-  nickLen: 30,
-  channelLen: 50,
-  topicLen: 390,
-  quitMessage: 'Client Quit',
-};
+/**
+ * Wall-clock timestamp captured at this worker isolate's first module load
+ * (cold start). Used as the `uptimeStartedAt` anchor for {@link CfStats} so
+ * `STATS u` reports uptime for the current isolate. A dedicated stats DO
+ * would supply a deployment-wide uptime (future work); for now each
+ * isolate reports its own.
+ */
+const WORKER_STARTUP_AT = Date.now();
 
 /**
  * ConnectionDO instance.
@@ -91,6 +95,13 @@ const DEFAULT_SERVER_CONFIG: ServerConfig = {
 export class ConnectionDO extends DurableObject<Env> {
   /** Cached connection state; reloaded from storage after hibernation. */
   private cached: ConnectionState | undefined;
+  /**
+   * Cached reducer-facing server config. Parsed once from `this.env`
+   * (bindings are stable for the DO's lifetime) so the schema-validated
+   * `loadServerConfigFromCfEnv` runs a single time rather than on every
+   * WebSocket frame.
+   */
+  private cachedServerConfig: ServerConfig | undefined;
   /**
    * Per-instance channel-state cache. Reused across every WebSocket frame
    * the connection handles (within a single hibernation cycle) so that
@@ -150,15 +161,17 @@ export class ConnectionDO extends DurableObject<Env> {
   private readonly ids: IdFactory = new UuidIdFactory();
   private readonly pingIntervalMs: number = DEFAULT_PING_INTERVAL_MS;
   private readonly pongTimeoutMs: number = DEFAULT_PONG_TIMEOUT_MS;
-  // Outbound lines are batched per call, not via a reserved instance
-  // field: `deliver()` joins every line of a ChannelDO broadcast into a
-  // single `WebSocket.send()`, and the actor `send` handler in
-  // `buildActor` does the same for one frame's response. Cross-call
-  // per-microtask coalescing (the optimization previously reserved here)
-  // was dropped — it would add a drain queue and ordering hazards between
-  // independent fan-out calls for no measured benefit (see ADR-003 and
-  // the CF adapter load-test report). Revisit only if WS round-trips
-  // become a demonstrated bottleneck.
+  // Outbound lines are batched per call (legacy mode), not via a reserved
+  // instance field: a legacy `deliver()` joins every line of a ChannelDO
+  // broadcast into a single `WebSocket.send()`, and the legacy actor `send`
+  // handler in `buildActor` does the same for one frame's response. An
+  // IRCv3 spec-mode connection instead sends one line per WS message with
+  // no trailing CR-LF (see `sendOutbound`). Cross-call per-microtask
+  // coalescing (the optimization previously reserved here) was dropped — it
+  // would add a drain queue and ordering hazards between independent
+  // fan-out calls for no measured benefit (see ADR-003 and the CF adapter
+  // load-test report). Revisit only if WS round-trips become a demonstrated
+  // bottleneck.
 
   // -------------------------------------------------------------------------
   // WebSocket upgrade
@@ -180,12 +193,23 @@ export class ConnectionDO extends DurableObject<Env> {
     if (cf !== undefined && typeof cf.tlsClientAuthCertSubject === 'string') {
       this.mtlsCertSubject = cf.tlsClientAuthCertSubject;
     }
+    // IRCv3 WebSocket subprotocol negotiation: read the offered
+    // `Sec-WebSocket-Protocol` list, select the first supported entry, and
+    // echo it back when one was agreed. The negotiated frame mode is tagged
+    // onto the hibernated socket so it survives eviction and can be
+    // recovered in every event handler (webSocketMessage / deliver / alarm).
+    const offerHeader = request.headers.get('Sec-WebSocket-Protocol');
+    const chosen = selectSubprotocol(parseSecWsProtocolOffers(offerHeader));
+    const mode = wsFrameModeFor(chosen ?? undefined);
     // Hibernation: `acceptWebSocket` accepts the server side implicitly.
-    // Calling `server.accept()` first throws "already accepted".
-    this.ctx.acceptWebSocket(server);
+    // Calling `server.accept()` first throws "already accepted". The tag
+    // records the negotiated frame mode for the outbound + inbound paths.
+    this.ctx.acceptWebSocket(server, [`ws:${mode}`]);
     // Schedule the first PING sweep.
     await this.ctx.storage.setAlarm(Date.now() + this.pingIntervalMs);
-    return new Response(null, { status: 101, webSocket: client });
+    const headers = new Headers();
+    if (chosen !== null) headers.set('Sec-WebSocket-Protocol', chosen);
+    return new Response(null, { status: 101, webSocket: client, headers });
   }
 
   // -------------------------------------------------------------------------
@@ -194,12 +218,33 @@ export class ConnectionDO extends DurableObject<Env> {
 
   /** Frame → actor → dispatch → persist. */
   override async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
-    const text = typeof message === 'string' ? message : new TextDecoder().decode(message);
+    const mode = this.wsFrameMode(ws);
+    // text.ircv3.net is a text-only subprotocol: a binary frame on such a
+    // connection is a protocol violation. RFC 6455 close code 1003 (unsupported
+    // data) is the spec-mandated response.
+    if (mode === 'spec-text' && typeof message !== 'string') {
+      ws.close(1003, 'binary frame not permitted on text.ircv3.net');
+      return;
+    }
+    const raw = typeof message === 'string' ? message : new TextDecoder().decode(message);
+    // IRCv3 WebSocket spec: a single message MUST fit the 510-byte budget
+    // (the 512-byte IRC line limit minus the omitted trailing CR-LF). An
+    // oversize message is a protocol violation; RFC 6455 close code 1009
+    // (Message Too Big) is the spec-mandated response. Legacy connections
+    // keep the parser's existing 512-byte line cap, so the budget is
+    // enforced for negotiated spec modes only.
+    if ((mode === 'spec-text' || mode === 'spec-binary') && !isWithinWsByteBudget(raw)) {
+      ws.close(1009, 'Message Too Big');
+      return;
+    }
+    // text.ircv3.net frames are UTF-8 text; lone surrogates have no valid
+    // encoding and are substituted with U+FFFD before framing.
+    const text = mode === 'spec-text' ? sanitizeForTextMode(raw) : raw;
     const state = await this.loadState();
     const beforeNick = state.nick;
 
     await this.loadAccountStore();
-    const actor = this.buildActor(ws, state);
+    const actor = this.buildActor(ws, state, mode);
     try {
       await actor.receiveTextFrame(text);
     } finally {
@@ -242,7 +287,7 @@ export class ConnectionDO extends DurableObject<Env> {
    * been idle past the PONG timeout, closes it.
    *
    * PLAN §6.1 — DO alarms are the canonical PING/idle mechanism on CF;
-   * equivalent to EventBridge Scheduler on AWS (042).
+   * equivalent to EventBridge Scheduler on AWS.
    */
   override async alarm(): Promise<void> {
     const state = await this.loadState();
@@ -260,7 +305,8 @@ export class ConnectionDO extends DurableObject<Env> {
     // Send PING. PONG replies update lastSeen via the actor.
     const token = this.ids.nonce();
     for (const ws of this.ctx.getWebSockets()) {
-      (ws as WebSocket).send(`PING :${token}\r\n`);
+      const socket = ws as WebSocket;
+      this.sendOutbound(socket, [{ text: `PING :${token}` }], this.wsFrameMode(socket));
     }
     await this.ctx.storage.setAlarm(now + this.pingIntervalMs);
   }
@@ -291,14 +337,11 @@ export class ConnectionDO extends DurableObject<Env> {
    */
   async deliver(lines: RawLine[]): Promise<{ delivered: number }> {
     let delivered = 0;
-    let text: string | undefined;
-    if (lines.length > 0) {
-      text = `${lines.map((l) => l.text).join('\r\n')}\r\n`;
-    }
     for (const ws of this.ctx.getWebSockets()) {
       const socket = ws as WebSocket;
       if (socket.readyState !== WebSocket.OPEN) continue;
-      if (text !== undefined) socket.send(text);
+      const mode = this.wsFrameMode(socket);
+      this.sendOutbound(socket, lines, mode);
       delivered++;
     }
     return { delivered };
@@ -308,6 +351,44 @@ export class ConnectionDO extends DurableObject<Env> {
   // Internal helpers
   // -------------------------------------------------------------------------
 
+  /**
+   * Recovers the negotiated WebSocket frame mode for `ws` from its
+   * hibernation tag. The tag is written once in `fetch` and survives DO
+   * eviction, so this returns the correct mode on every wake. Defaults to
+   * the legacy-tolerant mode when no tag is present (e.g. a socket accepted
+   * before subprotocol negotiation existed).
+   */
+  private wsFrameMode(ws: WebSocket): WsFrameMode {
+    return wsFrameModeFromTags(this.ctx.getTags(ws));
+  }
+
+  /**
+   * Writes `lines` to `ws` according to `mode`:
+   *   - `spec-text`   — one `ws.send` per line, no trailing CR-LF, lone
+   *                     surrogates substituted with U+FFFD (UTF-8 safety).
+   *   - `spec-binary` — one `ws.send` per line as a UTF-8 binary frame,
+   *                     no trailing CR-LF.
+   *   - `legacy`      — all lines joined with `\r\n` plus a trailing
+   *                     `\r\n`, sent as a single WebSocket message.
+   *
+   * No-ops when the socket is closed or `lines` is empty (preserving the
+   * empty-payload probe contract of {@link deliver}).
+   */
+  private sendOutbound(ws: WebSocket, lines: RawLine[], mode: WsFrameMode): void {
+    if (ws.readyState !== WebSocket.OPEN) return;
+    if (lines.length === 0) return;
+    if (mode === 'spec-text') {
+      for (const line of lines) ws.send(sanitizeForTextMode(line.text));
+      return;
+    }
+    if (mode === 'spec-binary') {
+      const enc = new TextEncoder();
+      for (const line of lines) ws.send(enc.encode(line.text));
+      return;
+    }
+    ws.send(`${lines.map((l) => l.text).join('\r\n')}\r\n`);
+  }
+
   /** Loads the connection state from storage, caching for the event. */
   private async loadState(): Promise<ConnectionState> {
     if (this.cached !== undefined) return this.cached;
@@ -330,27 +411,28 @@ export class ConnectionDO extends DurableObject<Env> {
   }
 
   /**
-   * Constructs an actor wired to this DO's CfRuntime.
+   * Constructs an actor wired to this DO's CfRuntime. `mode` drives both the
+   * inbound line-framing transport (spec mode: one IRC message per frame,
+   * never split; legacy: split on `\r\n`) and the outbound delivery shape
+   * (spec mode: one `WebSocket.send` per line, no trailing CR-LF; legacy:
+   * batched into a single `\r\n`-joined frame).
    */
-  private buildActor(ws: WebSocket, state: ConnectionState): ConnectionActor {
+  private buildActor(ws: WebSocket, state: ConnectionState, mode: WsFrameMode): ConnectionActor {
     const serverConfig = this.serverConfig();
     const motd = this.motdProvider();
     const handlers = {
       send: (lines: RawLine[]): void => {
-        if (ws.readyState === WebSocket.OPEN) {
-          const text = `${lines.map((l) => l.text).join('\r\n')}\r\n`;
-          ws.send(text);
-        }
+        this.sendOutbound(ws, lines, mode);
       },
       disconnect: (reason?: string): void => {
-        if (reason !== undefined && ws.readyState === WebSocket.OPEN) {
-          ws.send(`ERROR :Closing link: (${reason})\r\n`);
+        if (reason !== undefined) {
+          this.sendOutbound(ws, [{ text: `ERROR :Closing link: (${reason})` }], mode);
         }
         ws.close();
       },
       snapshot: (): ConnectionState | undefined => this.cached,
     };
-    // The CfRuntime shards the registry by nick (034); the per-connection
+    // The CfRuntime shards the registry by nick; the per-connection
     // key passed here is ignored by `makeCfRuntime` (kept in the signature
     // for call-site stability).
     const registryKey = this.ctx.id.toString();
@@ -372,11 +454,21 @@ export class ConnectionDO extends DurableObject<Env> {
       runtime,
       channels: this.channelAccess,
       serverConfig,
+      configSource: 'KV',
       clock: this.clock,
       ids: this.ids,
       motd,
       messages: this.messageStore(),
       history: this.historyStore(),
+      // CfStats fans out across the channel + connection RPCs the runtime
+      // already exposes. `uptimeStartedAt` is captured at the worker's
+      // module load (cold start); a dedicated stats DO would give a
+      // deployment-wide uptime, tracked as future work.
+      stats: new CfStats(runtime, WORKER_STARTUP_AT),
+      transport: makeWsFrameTransport(mode),
+      // Cloudflare terminates TLS at the edge before the WebSocket reaches
+      // the DO, so every WS connection is secure → user mode `S`.
+      secure: true,
       ...(accounts !== undefined ? { accounts } : {}),
       ...(mtlsIdentity !== undefined ? { mtlsIdentity } : {}),
       logger,
@@ -387,7 +479,7 @@ export class ConnectionDO extends DurableObject<Env> {
   private async tearDown(ws: WebSocket): Promise<void> {
     const state = await this.loadState();
     await this.loadAccountStore();
-    const actor = this.buildActor(ws, state);
+    const actor = this.buildActor(ws, state, this.wsFrameMode(ws));
     // Drive QUIT through the actor so the same effect pipeline handles
     // fanout as during normal operation.
     await actor.receiveTextFrame('QUIT\r\n');
@@ -415,13 +507,17 @@ export class ConnectionDO extends DurableObject<Env> {
   }
 
   private serverConfig(): ServerConfig {
-    return {
-      ...DEFAULT_SERVER_CONFIG,
-      ...(this.env.SERVER_NAME !== undefined ? { serverName: this.env.SERVER_NAME } : {}),
-      ...(this.env.NETWORK_NAME !== undefined ? { networkName: this.env.NETWORK_NAME } : {}),
-      ...(this.env.SERVER_VERSION !== undefined ? { serverVersion: this.env.SERVER_VERSION } : {}),
-      ...(this.env.CREATED_AT !== undefined ? { createdAt: this.env.CREATED_AT } : {}),
-    };
+    // Single source of truth: delegate to the schema-validated loader so
+    // every reducer-facing field (operCreds, serverPassword, motdLines,
+    // limit knobs, …) is populated from `this.env` exactly as the shared
+    // `ServerConfigSchema` prescribes. The previous hand-rolled literal
+    // silently dropped fields like operCreds, which left OPER unable to
+    // authenticate (491 ERR_NOOPERHOST) even when OPER_USER/OPER_PASSWORD
+    // were bound. See config-loader.ts and config.ts.
+    if (this.cachedServerConfig === undefined) {
+      this.cachedServerConfig = loadServerConfigFromCfEnv(this.env);
+    }
+    return this.cachedServerConfig;
   }
 
   private motdProvider(): MotdProvider {
@@ -522,6 +618,7 @@ export class ConnectionDO extends DurableObject<Env> {
       runtime,
       channels: this.channelAccess,
       serverConfig: this.serverConfig(),
+      configSource: 'KV',
       clock: this.clock,
       ids: this.ids,
       motd: this.motdProvider(),
@@ -724,3 +821,37 @@ export function parseSaslAccountsEnv(raw: string | undefined): SaslAccountCreden
   }
   return out;
 }
+
+/**
+ * Hibernation-tag prefixes written by {@link ConnectionDO.fetch}. Each tag
+ * encodes the negotiated {@link WsFrameMode} so it survives DO eviction and
+ * can be recovered in every WebSocket event handler via `ctx.getTags(ws)`.
+ */
+const WS_TAG_LEGACY = 'ws:legacy';
+const WS_TAG_SPEC_TEXT = 'ws:spec-text';
+const WS_TAG_SPEC_BINARY = 'ws:spec-binary';
+
+/**
+ * Recovers the {@link WsFrameMode} from a hibernated socket's tags.
+ * Defaults to the legacy-tolerant mode when no recognized tag is present.
+ */
+export function wsFrameModeFromTags(tags: readonly string[]): WsFrameMode {
+  for (const tag of tags) {
+    if (tag === WS_TAG_SPEC_TEXT) return 'spec-text';
+    if (tag === WS_TAG_SPEC_BINARY) return 'spec-binary';
+    if (tag === WS_TAG_LEGACY) return 'legacy';
+  }
+  return 'legacy';
+}
+
+/**
+ * Builds the inbound line-framing {@link Transport} for `mode`. Spec modes
+ * treat one WebSocket message as exactly one IRC line (a single trailing
+ * CR-LF is stripped and the frame is never split); legacy mode splits the
+ * frame on `\r\n` so older clients that concatenate messages keep working.
+ */
+export function makeWsFrameTransport(mode: WsFrameMode): Transport {
+  return {
+    feed: (chunk: string): string[] => frameToLines(chunk, mode),
+  };
+}

package/packages/cf-adapter/src/env.ts

@@ -9,9 +9,9 @@
 /**
  * The production {@link Env} for `apps/cf-worker`. ConnectionDO uses the
  * four DO namespaces below to coordinate with the registry, channel, and
- * channel-registry authorities. The CfRuntime (036) wires them together
+ * channel-registry authorities. The CfRuntime wires them together
  * behind the platform-agnostic {@link IrcRuntime} port; ConnectionDO
- * (033) only needs `CONNECTION_DO` itself plus the three collaborator
+ * only needs `CONNECTION_DO` itself plus the three collaborator
  * namespaces.
  *
  * RPC method shapes on {@link RegistryRpc} and {@link ChannelRpc} are
@@ -23,7 +23,7 @@ export interface Env {
   CONNECTION_DO: DurableObjectNamespace;
   /**
    * Nick registry authority. RPC: reserveNick / changeNick / releaseNick /
-   * lookupNick. Backed by the sharded {@link RegistryDO} (034), which keys
+   * lookupNick. Backed by the sharded {@link RegistryDO}, which keys
    * instances by `hash(nick) % N` so the single-threaded DO gives the nick
    * uniqueness invariant for free.
    *
@@ -34,7 +34,7 @@ export interface Env {
   /**
    * Channel authority, keyed by lowercased channel name. RPC: broadcast /
    * applyChannelDelta / getChannelSnapshot / listMembers. Backed by the
-   * {@link ChannelDO} (035), which owns the authoritative roster, modes,
+   * {@link ChannelDO}, which owns the authoritative roster, modes,
    * topic, and ban list and fans out broadcasts to each member's
    * ConnectionDO.
    */
@@ -77,22 +77,41 @@ export interface Env {
    * end-to-end. Empty/undefined disables SASL account verification.
    */
   SASL_ACCOUNTS?: string;
+  /**
+   * IRC operator name consulted by the `OPER` reducer. Pair with
+   * {@link OPER_PASSWORD}; when either is set the connection-do threads
+   * both into the reducer-facing `ServerConfig.operCreds` via
+   * `loadServerConfigFromCfEnv`.
+   */
+  OPER_USER?: string;
+  /**
+   * IRC operator password paired with {@link OPER_USER}. Treat as a
+   * Cloudflare secret (never a plaintext `[vars]` entry) in production.
+   */
+  OPER_PASSWORD?: string;
 }
 
 /**
  * RPC contract ConnectionDO expects from the registry. The real
- * RegistryDO (034) and the test stub both implement this.
+ * RegistryDO and the test stub both implement this.
  */
 export interface RegistryRpc {
   reserveNick(nick: string, conn: string): Promise<{ ok: true } | { ok: false }>;
   changeNick(conn: string, oldNick: string, newNick: string): Promise<boolean>;
   releaseNick(nick: string): Promise<void>;
   lookupNick(nick: string): Promise<string | null>;
+  /**
+   * Enumerates every `(nickLower, connectionId)` entry in this shard. Used
+   * by global fan-out paths (e.g. `WALLOPS`) that need to reach connections
+   * regardless of shared channel membership. Returns a plain array so the
+   * RPC marshals cleanly across the DO boundary.
+   */
+  listEntries(): Promise<Array<[nickLower: string, connId: string]>>;
 }
 
 /**
  * RPC contract ConnectionDO expects from each channel instance. The real
- * ChannelDO (035) and the test stub both implement this.
+ * ChannelDO and the test stub both implement this.
  *
  * Note: `broadcast` accepts already-formatted raw line texts (no
  * `RawLine` wrapper) because that's what `cf-runtime.broadcast`

package/packages/cf-adapter/src/index.ts

@@ -23,6 +23,8 @@ export {
 } from './sharding.js';
 export { makeCfRuntime } from './cf-runtime.js';
 export type { CfConnectionHandlers } from './cf-runtime.js';
+export { CfStats } from './stats.js';
+export type { CfStatsRuntime } from './stats.js';
 export type { ChannelRpc, ChannelRegistryRpc, Env, RegistryRpc } from './env.js';
 export {
   CREATE_ACCOUNTS_TABLE_SQL,

package/packages/cf-adapter/src/registry-do.ts

@@ -23,8 +23,8 @@
  * and the second sees the new owner and fails.
  *
  * RPC surface — implements {@link RegistryRpc}, the same shape the
- * stub `RecordingRegistryDO` exposed for 033. Consumers
- * (`CfRuntime`, 036) call these methods via `env.REGISTRY_DO`
+ * stub `RecordingRegistryDO` exposed for the connection tests. Consumers
+ * (`CfRuntime`) call these methods via `env.REGISTRY_DO`
  * after computing the shard key with {@link registryKeyForNick}.
  */
 
@@ -85,7 +85,7 @@ export class RegistryDO extends DurableObject implements RegistryRpc {
    *     `oldNick` after this conn abandoned it (defence in depth).
    *
    * Cross-shard changes (old and new hash to different shards) are
-   * orchestrated by `CfRuntime` in 036 as a two-phase
+   * orchestrated by `CfRuntime` as a two-phase
    * reserve-new-then-release-old. This DO only sees single-shard
    * changes and crash-recovery paths (where `oldNick` may not be
    * present); the latter is why the conditional delete is a soft check.
@@ -127,4 +127,23 @@ export class RegistryDO extends DurableObject implements RegistryRpc {
     const owner = await this.ctx.storage.get<string>(nickKey(nick.toLowerCase()));
     return owner ?? null;
   }
+
+  /**
+   * Enumerates every `(nickLower, connectionId)` pair in this shard.
+   * Backs the global WALLOPS fan-out: the caller scans every shard, collects
+   * all connection ids, and delivers to those carrying the `+w` mode. The
+   * walk is a single `list` over the `nick:` prefix; cost is proportional to
+   * the slice's live nick count (sharded, so bounded per DO).
+   */
+  async listEntries(): Promise<Array<[nickLower: string, connId: string]>> {
+    const out: Array<[nickLower: string, connId: string]> = [];
+    // `storage.list` resolves to a Map of `key → value` for the prefix.
+    // Each key is `nick:<lower>`; we strip the prefix to recover the nick.
+    const entries = await this.ctx.storage.list<string>({ prefix: NICK_KEY_PREFIX });
+    for (const [key, connId] of entries) {
+      const nickLower = key.slice(NICK_KEY_PREFIX.length);
+      out.push([nickLower, connId]);
+    }
+    return out;
+  }
 }

package/packages/cf-adapter/src/serialize.ts

@@ -34,6 +34,13 @@ export interface PersistedConnectionState {
   id: string;
   registration: RegistrationState;
   capNegotiating: boolean;
+  /**
+   * Transport TLS fact (user mode `S`). Optional on the persisted shape so
+   * records written before the field shipped (schema is otherwise
+   * unchanged) deserialize with a `false` default via the coalescing in
+   * {@link deserialize}. Always written by {@link serialize}.
+   */
+  secure?: boolean;
   caps: string[];
   joinedChannels: ChanName[];
   userModes: UserModes;
@@ -61,6 +68,7 @@ export function serialize(state: ConnectionState): PersistedConnectionState {
     id: state.id,
     registration: state.registration,
     capNegotiating: state.capNegotiating,
+    secure: state.secure,
     caps: [...state.caps],
     joinedChannels: [...state.joinedChannels],
     userModes: { ...state.userModes },
@@ -88,6 +96,9 @@ export function deserialize(record: unknown): ConnectionState {
     id: migrated.id,
     registration: migrated.registration,
     capNegotiating: migrated.capNegotiating,
+    // `secure` is absent on records persisted before user mode `S` shipped;
+    // `migrate` backfills it to false so the cast below is truthful.
+    secure: migrated.secure ?? false,
     caps: new Set<string>(migrated.caps),
     joinedChannels: new Set<ChanName>(migrated.joinedChannels),
     userModes: { ...migrated.userModes },
@@ -119,8 +130,19 @@ export function migrate(record: unknown): PersistedConnectionState {
   if (!isPlainObject(record)) {
     throw new Error('persisted connection state is not an object');
   }
+  // Backfill additive fields introduced by user mode `S` (TLS connected):
+  // `secure` and `userModes.tls`. Both default to false (plain transport),
+  // preserving the pre-feature behaviour for records persisted before the
+  // mode shipped. The schema version is unchanged because the additions are
+  // purely additive with safe defaults — no row transformation is needed
+  // beyond coalescing the missing keys.
+  if (record.secure === undefined) record.secure = false;
+  if (isPlainObject(record.userModes)) {
+    const um = record.userModes as Record<string, unknown>;
+    if (um.tls === undefined) um.tls = false;
+  }
   const version = typeof record.version === 'number' ? record.version : 0;
-  // No migrations yet — v1 is the initial schema. Future work adds steps:
+  // No versioned migrations yet — v1 is the initial schema. Future work:
   //   if (version < 2) record = migrate_v1_v2(record);
   //   if (version < 3) record = migrate_v2_v3(record);
   if (version > PERSISTED_STATE_VERSION) {
@@ -131,9 +153,8 @@ export function migrate(record: unknown): PersistedConnectionState {
   }
   // The cast below is safe: we accept any JSON shape the storage layer
   // returns; production code wrote it via `serialize`, tests wrote it
-  // through the same path. If a future field is missing, the
-  // `exactOptionalPropertyTypes` discipline in `serialize` keeps
-  // undefined keys out of the persisted record entirely.
+  // through the same path. Backfilling above keeps the additive
+  // `secure` / `userModes.tls` keys present even on pre-feature records.
   return record as unknown as PersistedConnectionState;
 }
 

package/packages/cf-adapter/src/sharding.ts

@@ -22,8 +22,7 @@
  * `N` defaults to {@link DEFAULT_REGISTRY_SHARDS} (32) and is
  * configurable per deployment via the worker env. Changing N after
  * production traffic requires a migration (re-sharding every existing
- * nick→conn mapping); document this in `docs/deployment-cf.md`
- * (038).
+ * nick→conn mapping); document this in `docs/deployment-cf.md`.
  */
 
 /**

package/packages/cf-adapter/src/stats.ts

@@ -0,0 +1,65 @@
+/**
+ * Cloudflare Workers-flavoured {@link ServerStats} backend.
+ *
+ * Aggregates the network-wide counts the `LUSERS` / `STATS` reducers need
+ * by fanning out across the existing CF RPC surface: `listChannels` (via
+ * the {@link ChannelRegistryDO}) plus per-channel `listMembers` and
+ * per-member `getConnState`. Classification (oper / invisible / unknown)
+ * is delegated to the shared {@link computeStatsSnapshot} helper in
+ * irc-core so the classification rules live in exactly one place.
+ *
+ * **Limitation:** the CF runtime does not currently expose an
+ * "enumerate all connections" RPC, so a connection that has not joined
+ * any channel is not counted. This matches the ticket's "aggregate via
+ * listChannels / connection-enumeration RPCs" guidance; a future
+ * dedicated stats DO would close the gap (every connection would be
+ * counted regardless of channel membership).
+ *
+ * Constructed per `LUSERS` / `STATS` invocation alongside the
+ * {@link CfRuntime}; cheap to build, no caching. `uptimeStartedAt` is
+ * supplied by the caller (typically the worker's startup timestamp).
+ */
+
+import type {
+  ChanName,
+  ConnId,
+  ConnectionState,
+  ServerStatsSnapshot,
+} from '@serverless-ircd/irc-core';
+import { computeStatsSnapshot } from '@serverless-ircd/irc-core';
+
+/**
+ * The minimal slice of {@link CfRuntime} (or any adapter runtime) that
+ * {@link CfStats} needs. Defined structurally so unit tests can pass a
+ * stub without spinning up workerd / miniflare.
+ */
+export interface CfStatsRuntime {
+  listChannels(): Promise<ReadonlyArray<{ nameLower: string }>>;
+  getChannelConnections(name: ChanName): Promise<ReadonlyMap<ConnId, ConnectionState>>;
+}
+
+export class CfStats {
+  private readonly runtime: CfStatsRuntime;
+  private readonly uptimeStartedAt: number;
+
+  constructor(runtime: CfStatsRuntime, uptimeStartedAt: number) {
+    this.runtime = runtime;
+    this.uptimeStartedAt = uptimeStartedAt;
+  }
+
+  async getStats(): Promise<ServerStatsSnapshot> {
+    const channels = await this.runtime.listChannels();
+    // Fan out: gather every channel's members into one deduplicated map.
+    // A user in N channels is counted once.
+    const unique = new Map<ConnId, ConnectionState>();
+    await Promise.all(
+      channels.map(async (chan) => {
+        const members = await this.runtime.getChannelConnections(chan.nameLower as ChanName);
+        for (const [id, state] of members) {
+          unique.set(id, state);
+        }
+      }),
+    );
+    return computeStatsSnapshot(unique.values(), channels.length, this.uptimeStartedAt);
+  }
+}

package/packages/cf-adapter/tests/cf-harness.ts

@@ -1,6 +1,6 @@
 /**
  * CF-side {@link IrcHarnessFactory} — registers the parametrized IRC
- * scenario suite (032) against the Cloudflare adapter.
+ * scenario suite from `@serverless-ircd/irc-test-support` against the Cloudflare adapter.
  *
  * Each {@link CfHarness} instance is hermetic at the vitest-pool-workers
  * level: every test gets an isolated storage namespace