serverless-ircd 0.9.0 → 0.11.0

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

@@ -29,13 +29,15 @@
 
 import { DurableObject } from 'cloudflare:workers';
 import {
-  type AccountStore,
+  type CertIdentity,
   type ChanName,
   type ChannelState,
   type Clock,
   type ConnId,
   type ConnectionState,
   ConsoleLogger,
+  FRAME_FLOOD_CLOSE_CODE,
+  FRAME_FLOOD_ERROR_LINE,
   type IdFactory,
   InMemoryMessageStore,
   InMemoryMtlsIdentityProvider,
@@ -46,12 +48,14 @@ import {
   type MotdProvider,
   type MtlsIdentityProvider,
   type NickHistoryStore,
+  type ParsedServerConfig,
   type RawLine,
-  type SaslAccountCredential,
   type ServerConfig,
   SystemClock,
   UuidIdFactory,
   type WsFrameMode,
+  admitFrameWindow,
+  certIdentityFromSubject,
   createChannel,
   createConnection,
   frameToLines,
@@ -66,9 +70,9 @@ 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 { COUNTER_INSTANCE_NAME } from './counter-do.js';
 import { type D1ServicesStore, loadD1ServicesStore } from './d1-services-store.js';
-import type { Env } from './env.js';
+import type { CounterRpc, Env } from './env.js';
 import { STATE_STORAGE_KEY, deserialize, serialize } from './serialize.js';
 import type { PersistedConnectionState } from './serialize.js';
 import { CfStats } from './stats.js';
@@ -100,9 +104,11 @@ export class ConnectionDO extends DurableObject<Env> {
    * 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.
+   * WebSocket frame. Held as {@link ParsedServerConfig} so the adapter
+   * can read extra fields (e.g. `saslAccounts` for the services seed)
+   * the reducer-facing `ServerConfig` view omits.
    */
-  private cachedServerConfig: ServerConfig | undefined;
+  private cachedParsedConfig: ParsedServerConfig | undefined;
   /**
    * Per-instance channel-state cache. Reused across every WebSocket frame
    * the connection handles (within a single hibernation cycle) so that
@@ -142,43 +148,35 @@ export class ConnectionDO extends DurableObject<Env> {
    * keyed by nick) is a documented follow-up. Lazily constructed.
    */
   private history: NickHistoryStore | undefined;
-  /**
-   * SASL account store, resolved once via {@link loadAccountStore} before the
-   * first frame dispatches. The two-phase load mirrors AWS's
-   * `loadDynamoAccountStore`: D1 `accounts` table (authoritative when it has
-   * rows) is queried at boot; when empty/unreachable the `SASL_ACCOUNTS`
-   * env-var seed provides the fallback `InMemoryAccountStore`. The
-   * `AccountStore.verify` port is synchronous, so pre-loading MUST complete
-   * before the first reducer runs.
-   */
-  private accounts: AccountStore | undefined;
-  /** Guards {@link loadAccountStore} so the D1 query runs at most once. */
-  private accountsResolved = false;
   /**
    * Persistent services store (NickServ / ChanServ / HostServ / MemoServ /
    * OperServ + read-marker), hydrated once via {@link loadServicesStore}
    * before the first frame dispatches. The store mutates the in-memory
    * cache synchronously and enqueues write-behind ops; {@link flushServices}
    * drains them into D1 after each frame / at teardown. `undefined` when
-   * D1 is not configured (services unbound → no NickServ/ChanServ routing).
+   * D1 is not configured (services unbound → no NickServ/ChanServ routing,
+   * no SASL/PASS credential verify).
    */
   private services: D1ServicesStore | undefined;
   /** Guards {@link loadServicesStore} so the D1 scan runs at most once. */
   private servicesResolved = false;
   /**
-   * Verified client-cert subject captured at WebSocket upgrade time when
+   * Verified client-cert identity captured at WebSocket upgrade time when
    * CF API Shield mTLS is configured. Surfaced to the SASL EXTERNAL reducer
    * via an {@link MtlsIdentityProvider} so `AUTHENTICATE EXTERNAL` can map
-   * the cert subject to an account.
+   * the certificate to an account (DER SHA-256 fingerprint preferred,
+   * canonical DN fallback — see `docs/SASL-EXTERNAL.md`).
    *
    * CF API Shield mTLS setup:
    * 1. Upload the client CA to API Shield (dashboard → Security → API Shield).
    * 2. Create an mTLS policy on the custom hostname that requires client certs.
    * 3. The verified subject is injected into `request.cf.tlsClientAuthCertSubject`
-   *    on every request, which the Worker reads at upgrade time.
+   *    (and `request.cf.tlsClientAuth.certFingerprintSHA256` carries the DER
+   *    SHA-256 fingerprint) on every request, which the Worker reads at
+   *    upgrade time.
    * When unset (no mTLS configured), EXTERNAL auth fails with `904`.
    */
-  private mtlsCertSubject: string | undefined;
+  private mtlsCert: CertIdentity | undefined;
   /**
    * Client source IP captured at WebSocket upgrade time, surfaced onto the
    * {@link ConnectionState.host} field so WHOIS / hostmasks resolve instead
@@ -190,6 +188,23 @@ export class ConnectionDO extends DurableObject<Env> {
    * this raw IP with a deterministic cloak at registration time.
    */
   private sourceHost: string | undefined;
+  /**
+   * Timestamps of recently admitted inbound frames (the sliding window
+   * backing the adapter-boundary rate limit, see `admitFrameWindow`).
+   * Kept in memory only: while frames are flowing the DO stays resident
+   * (so an active flood is always counted), and after eviction — which
+   * requires idleness far longer than the 5 s default window — every
+   * retained timestamp would have decayed out anyway. The gate fires
+   * BEFORE the actor / storage write so over-limit frames cost neither.
+   */
+  private inboundFrameTimes: number[] = [];
+  /**
+   * Test-only override for the inbound frame window (`maxFrames` /
+   * `windowMs`), bypassing the env-sourced `adapter` config so the decay
+   * behaviour is testable without real multi-second sleeps. `undefined`
+   * in production.
+   */
+  private frameWindowOverride: { maxFrames: number; windowMs: number } | undefined;
   private readonly clock: Clock = SystemClock;
   private readonly ids: IdFactory = new UuidIdFactory();
   private readonly pingIntervalMs: number = DEFAULT_PING_INTERVAL_MS;
@@ -218,14 +233,7 @@ export class ConnectionDO extends DurableObject<Env> {
     const pair = new WebSocketPair();
     const server = pair[0];
     const client = pair[1];
-    // Capture the verified client-cert subject when CF API Shield mTLS is
-    // active. `request.cf` is a Cloudflare-specific extension; the property
-    // is present only when a client certificate was verified against the
-    // uploaded CA pool.
-    const cf = (request as Request & { cf?: Record<string, unknown> }).cf;
-    if (cf !== undefined && typeof cf.tlsClientAuthCertSubject === 'string') {
-      this.mtlsCertSubject = cf.tlsClientAuthCertSubject;
-    }
+    this.captureMtlsSubject(request);
     // Capture the client source IP for ConnectionState.host. CF-Connecting-IP
     // is set by the Cloudflare edge on every proxied request; X-Real-IP is
     // the conventional fallback for non-CF reverse proxies. Stashed on the
@@ -259,6 +267,16 @@ export class ConnectionDO extends DurableObject<Env> {
   /** Frame → actor → dispatch → persist. */
   override async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
     const mode = this.wsFrameMode(ws);
+    // Adapter-boundary rate limit: consult the sliding window BEFORE any
+    // per-frame work (state load, actor run, storage write, D1 flush).
+    // An over-limit frame delivers the canonical ERROR line and closes
+    // the socket with RFC 6455 close code 1008 (Policy Violation); the
+    // normal close handler runs the QUIT teardown.
+    if (!this.admitInboundFrame()) {
+      this.sendOutbound(ws, [{ text: FRAME_FLOOD_ERROR_LINE }], mode);
+      ws.close(FRAME_FLOOD_CLOSE_CODE, 'flooding');
+      return;
+    }
     // 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.
@@ -283,7 +301,6 @@ export class ConnectionDO extends DurableObject<Env> {
     const state = await this.loadState();
     const beforeNick = state.nick;
 
-    await this.loadAccountStore();
     await this.loadServicesStore();
     const actor = this.buildActor(ws, state, mode);
     try {
@@ -360,6 +377,10 @@ export class ConnectionDO extends DurableObject<Env> {
       const socket = ws as WebSocket;
       this.sendOutbound(socket, [{ text: `PING :${token}` }], this.wsFrameMode(socket));
     }
+    // Refresh the admission slot so the counter's lazy TTL reconcile
+    // only evicts entries from DOs that stopped heartbeating (crashed or
+    // evicted without a close event). No-op for unregistered connections.
+    await this.refreshConnectionSlot();
     await this.ctx.storage.setAlarm(now + this.pingIntervalMs);
   }
 
@@ -388,17 +409,39 @@ export class ConnectionDO extends DurableObject<Env> {
    * socket count without sending anything. Used by ChannelDO.sweep.
    */
   async deliver(lines: RawLine[]): Promise<{ delivered: number }> {
+    return this.deliverToSockets(this.ctx.getWebSockets() as unknown as WebSocket[], lines);
+  }
+
+  /**
+   * Iterates `sockets`, delivering `lines` to each OPEN one and counting
+   * the writes. Extracted from {@link deliver} so the false arm of the
+   * tryDeliver check is testable with a fake non-OPEN socket — the real
+   * `ctx.getWebSockets()` only returns OPEN sockets in the test runtime.
+   */
+  public deliverToSockets(sockets: WebSocket[], lines: RawLine[]): { delivered: number } {
     let delivered = 0;
-    for (const ws of this.ctx.getWebSockets()) {
-      const socket = ws as WebSocket;
-      if (socket.readyState !== WebSocket.OPEN) continue;
-      const mode = this.wsFrameMode(socket);
-      this.sendOutbound(socket, lines, mode);
-      delivered++;
+    for (const ws of sockets) {
+      delivered += this.tryDeliver(ws, lines) ? 1 : 0;
     }
     return { delivered };
   }
 
+  /**
+   * Delivers `lines` to a single attached WebSocket. Returns `false`
+   * (without writing) when the socket is no longer OPEN, `true` after a
+   * successful write. Public so the readyState guard is testable with a
+   * fake socket — the real `ctx.getWebSockets()` only returns OPEN
+   * sockets in the test runtime, but production may briefly surface
+   * CLOSING sockets between the unilateral-close and the close event
+   * reaching the DO.
+   */
+  public tryDeliver(ws: WebSocket, lines: RawLine[]): boolean {
+    if (ws.readyState !== WebSocket.OPEN) return false;
+    const mode = this.wsFrameMode(ws);
+    this.sendOutbound(ws, lines, mode);
+    return true;
+  }
+
   // -------------------------------------------------------------------------
   // Internal helpers
   // -------------------------------------------------------------------------
@@ -441,6 +484,48 @@ export class ConnectionDO extends DurableObject<Env> {
     ws.send(`${lines.map((l) => l.text).join('\r\n')}\r\n`);
   }
 
+  /**
+   * Test-only seam that exposes {@link sendOutbound} so the readyState
+   * early-return is reachable with a fake non-OPEN socket. Production
+   * callers always pass an OPEN socket (the {@link deliver} and
+   * {@link tryDeliver} guards filter first), so the path cannot be
+   * exercised via real RPC.
+   */
+  public __sendOutboundForTest(ws: WebSocket, lines: RawLine[], mode: WsFrameMode): void {
+    this.sendOutbound(ws, lines, mode);
+  }
+
+  /**
+   * Applies the per-connection inbound frame window to the frame being
+   * received: prunes decayed timestamps, records this frame when it
+   * fits, and returns whether it was admitted. The window config comes
+   * from the schema-validated `adapter` section (default 50 frames /
+   * 5 s) unless the test-only override is installed.
+   */
+  private admitInboundFrame(): boolean {
+    const cfg = this.frameWindowOverride ?? {
+      maxFrames: this.parsedConfig().adapter.maxFramesPerWindow,
+      windowMs: this.parsedConfig().adapter.frameWindowSeconds * 1000,
+    };
+    const decision = admitFrameWindow(
+      this.inboundFrameTimes,
+      this.clock.now(),
+      cfg.maxFrames,
+      cfg.windowMs,
+    );
+    this.inboundFrameTimes = decision.times;
+    return decision.admitted;
+  }
+
+  /**
+   * Test-only seam installing a tight inbound frame window (or clearing
+   * it with `undefined`) without redeploying the worker env. See
+   * {@link frameWindowOverride}.
+   */
+  public __setFrameWindowForTest(cfg: { maxFrames: number; windowMs: number } | undefined): void {
+    this.frameWindowOverride = cfg;
+  }
+
   /** Loads the connection state from storage, caching for the event. */
   private async loadState(): Promise<ConnectionState> {
     if (this.cached !== undefined) return this.cached;
@@ -484,10 +569,7 @@ export class ConnectionDO extends DurableObject<Env> {
         this.sendOutbound(ws, lines, mode);
       },
       disconnect: (reason?: string): void => {
-        if (reason !== undefined) {
-          this.sendOutbound(ws, [{ text: `ERROR :Closing link: (${reason})` }], mode);
-        }
-        ws.close();
+        this.writeDisconnect(ws, mode, reason);
       },
       snapshot: (): ConnectionState | undefined => this.cached,
     };
@@ -503,11 +585,10 @@ export class ConnectionDO extends DurableObject<Env> {
     // Bound `connectionId` so every record the actor emits is filterable
     // per-connection in the Workers dashboard.
     const logger: Logger = new ConsoleLogger({ connectionId: state.id }, undefined, LogLevel.Info);
-    const accounts = this.accountStore();
     const services = this.servicesStore();
     const mtlsIdentity: MtlsIdentityProvider | undefined =
-      this.mtlsCertSubject !== undefined
-        ? new InMemoryMtlsIdentityProvider([{ connId: state.id, identity: this.mtlsCertSubject }])
+      this.mtlsCert !== undefined
+        ? new InMemoryMtlsIdentityProvider([{ connId: state.id, identity: this.mtlsCert }])
         : undefined;
     return new ConnectionActor({
       state,
@@ -529,17 +610,48 @@ export class ConnectionDO extends DurableObject<Env> {
       // 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 } : {}),
-      ...(services !== undefined ? { services } : {}),
-      ...(mtlsIdentity !== undefined ? { mtlsIdentity } : {}),
+      ...buildOptionalActorFields(services, mtlsIdentity),
       logger,
     });
   }
 
+  /**
+   * Writes the optional `ERROR :Closing link` line and closes the socket.
+   * Extracted from the {@link buildActor} disconnect callback so the
+   * reason-gated branch is testable without driving a full actor flow
+   * that emits a self-Disconnect with a reason (rare — OperServ GHOST,
+   * KILL, flood, bad server-password).
+   */
+  private writeDisconnect(ws: WebSocket, mode: WsFrameMode, reason?: string): void {
+    if (reason !== undefined) {
+      this.sendOutbound(ws, [{ text: `ERROR :Closing link: (${reason})` }], mode);
+    }
+    ws.close();
+  }
+
+  /**
+   * Test-only seam that exposes {@link closeIfStillOpen} so the
+   * readyState-guarded `ws.close()` is reachable with a fake OPEN
+   * socket. The real QUIT flow always closes the WS via the actor's
+   * self-Disconnect handler before tearDown reaches this guard.
+   */
+  public __closeIfStillOpenForTest(ws: WebSocket): void {
+    this.closeIfStillOpen(ws);
+  }
+
+  /**
+   * Test-only seam that exposes {@link writeDisconnect} so the
+   * reason-gated `ERROR :Closing link` write is reachable without
+   * driving a full actor flow that emits a self-Disconnect with a
+   * reason (rare — OperServ GHOST, KILL, flood, bad server-password).
+   */
+  public __writeDisconnectForTest(ws: WebSocket, mode: WsFrameMode, reason?: string): void {
+    this.writeDisconnect(ws, mode, reason);
+  }
+
   /** Tears down a connection: emit QUIT effects, release nick, close WS. */
   private async tearDown(ws: WebSocket): Promise<void> {
     const state = await this.loadState();
-    await this.loadAccountStore();
     await this.loadServicesStore();
     const actor = this.buildActor(ws, state, this.wsFrameMode(ws));
     // Drive QUIT through the actor so the same effect pipeline handles
@@ -547,9 +659,8 @@ export class ConnectionDO extends DurableObject<Env> {
     await actor.receiveTextFrame('QUIT\r\n');
     await this.releaseAndPersist(state);
     await this.flushServices();
-    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
-      ws.close();
-    }
+    await this.releaseConnectionSlot();
+    this.closeIfStillOpen(ws);
     try {
       await this.ctx.storage.deleteAlarm();
     } catch {
@@ -557,6 +668,21 @@ export class ConnectionDO extends DurableObject<Env> {
     }
   }
 
+  /**
+   * Closes `ws` when it is still in a state where calling `close()` is
+   * meaningful (OPEN or CONNECTING). The QUIT flow drives a self-Disconnect
+   * that already closes the socket, so by the time {@link tearDown} reaches
+   * this guard the WS is usually CLOSING/CLOSED; the helper is a defensive
+   * backstop for the rare path where the actor does not emit a self-
+   * Disconnect. Extracted as a public seam so both arms are testable with
+   * a fake socket — the real QUIT flow always hits the false arm.
+   */
+  private closeIfStillOpen(ws: WebSocket): void {
+    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+      ws.close();
+    }
+  }
+
   /** Releases the nick via the registry and persists the (possibly mutated) state. */
   private async releaseAndPersist(state: ConnectionState): Promise<void> {
     if (state.nick !== undefined) {
@@ -569,6 +695,32 @@ export class ConnectionDO extends DurableObject<Env> {
     await this.persistState(state);
   }
 
+  /**
+   * Releases this connection's admission slot in the global counter
+   * (`maxClients` cap). The key is this DO's hex id — exactly what the
+   * worker edge registered at upgrade time (`idFromName(uuid).toString()`),
+   * so no id needs to be passed through the upgrade request. Idempotent
+   * (deleting an absent key is a no-op): connections opened directly
+   * against the DO (integration harness, cross-DO RPC) never registered
+   * a slot and tear down harmlessly.
+   */
+  private async releaseConnectionSlot(): Promise<void> {
+    const stub = this.env.COUNTER_DO.get(this.env.COUNTER_DO.idFromName(COUNTER_INSTANCE_NAME));
+    await (stub as unknown as CounterRpc).release(this.ctx.id.toString());
+  }
+
+  /**
+   * Refreshes the admission slot's `lastSeen` so the counter's lazy TTL
+   * reconcile only evicts entries whose ConnectionDO stopped
+   * heartbeating (crashed / evicted without delivering a close event).
+   * Called from the PING alarm; no-op for connections that never
+   * registered a slot.
+   */
+  private async refreshConnectionSlot(): Promise<void> {
+    const stub = this.env.COUNTER_DO.get(this.env.COUNTER_DO.idFromName(COUNTER_INSTANCE_NAME));
+    await (stub as unknown as CounterRpc).heartbeat(this.ctx.id.toString());
+  }
+
   private serverConfig(): ServerConfig {
     // Single source of truth: delegate to the schema-validated loader so
     // every reducer-facing field (operCreds, serverPassword, motdLines,
@@ -577,19 +729,24 @@ export class ConnectionDO extends DurableObject<Env> {
     // 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.parsedConfig();
+  }
+
+  /**
+   * Returns the full parsed config (the schema-validated superset of
+   * `ServerConfig`). The adapter reads fields the reducer-facing
+   * `ServerConfig` omits — `saslAccounts` (services seed), `motdLines`
+   * (MOTD provider), `maxClients` (admission), …
+   */
+  private parsedConfig(): ParsedServerConfig {
+    if (this.cachedParsedConfig === undefined) {
+      this.cachedParsedConfig = loadServerConfigFromCfEnv(this.env);
     }
-    return this.cachedServerConfig;
+    return this.cachedParsedConfig;
   }
 
   private motdProvider(): MotdProvider {
-    const raw = this.env.MOTD_LINES;
-    if (raw === undefined || raw.length === 0) {
-      return { lines: () => DEFAULT_MOTD };
-    }
-    // MOTD_LINES is a newline-delimited env var.
-    return { lines: () => raw.split('\n') };
+    return chooseMotdProvider(this.env.MOTD_LINES);
   }
 
   /**
@@ -617,41 +774,32 @@ export class ConnectionDO extends DurableObject<Env> {
     return this.history;
   }
 
-  /**
-   * Resolves the SASL account store once (D1 table → `SASL_ACCOUNTS` seed),
-   * caching the result. Safe to call on every frame; the D1 query runs at
-   * most once per ConnectionDO instance. Must complete before the first
-   * reducer dispatches so the synchronous `AccountStore.verify` port has its
-   * data ready.
-   */
-  private async loadAccountStore(): Promise<void> {
-    if (this.accountsResolved) return;
-    this.accountsResolved = true;
-    this.accounts = await resolveAccountStore(this.env.ACCOUNTS_DB, this.env.SASL_ACCOUNTS);
-  }
-
-  /**
-   * Returns the resolved account store, or `undefined` when no accounts are
-   * configured (so the actor's `ctx.accounts` stays unset: `AUTHENTICATE
-   * PLAIN` → `904`). Populated by {@link loadAccountStore}; callers MUST
-   * `await loadAccountStore()` before reading this.
-   */
-  private accountStore(): AccountStore | undefined {
-    return this.accounts;
-  }
-
   /**
    * Resolves the persistent services store once (D1 → write-behind cache),
    * caching the result. Safe to call on every frame; the D1 scan runs at
    * most once per ConnectionDO instance. Must complete before the first
    * reducer dispatches so the synchronous `ServicesStore` port has its
    * snapshot ready. Leaves `services` `undefined` when D1 is absent so the
-   * actor's `ctx.services` stays unset (no NickServ/ChanServ routing).
+   * actor's `ctx.services` stays unset (no NickServ/ChanServ routing,
+   * no SASL/PASS credential verify).
+   *
+   * After the D1 load, the `SASL_ACCOUNTS` env-var seed is ingested:
+   * each `username:password` pair is registered via `registerNick` when
+   * the nick is not already present. Idempotent — re-ingesting on every
+   * cold start is a no-op for nicks the services table already holds
+   * (including NickServ-registered nicks whose password wins). New
+   * env-seed accounts are persisted by the write-behind flush.
    */
   private async loadServicesStore(): Promise<void> {
     if (this.servicesResolved) return;
     this.servicesResolved = true;
     this.services = await loadD1ServicesStore(this.env.ACCOUNTS_DB, this.clock);
+    if (this.services !== undefined) {
+      const cfg = this.parsedConfig();
+      for (const acct of cfg.saslAccounts) {
+        this.services.registerNick(acct.username, acct.password, '');
+      }
+    }
   }
 
   /**
@@ -674,6 +822,18 @@ export class ConnectionDO extends DurableObject<Env> {
     await this.services.flush();
   }
 
+  /**
+   * Test-only seam that exposes {@link flushServices} so the
+   * "services unbound" early-return is reachable. Production always
+   * drives flushServices after `loadServicesStore()` has run (in
+   * `webSocketMessage` and `tearDown*`), so the field is populated;
+   * the undefined arm fires only on a DO that has never processed a
+   * frame.
+   */
+  public async __flushServicesForTest(): Promise<void> {
+    await this.flushServices();
+  }
+
   // -------------------------------------------------------------------------
   // Test hooks (only invoked from `runInDurableObject` in tests)
   // -------------------------------------------------------------------------
@@ -699,13 +859,12 @@ export class ConnectionDO extends DurableObject<Env> {
   private async tearDownNoSocket(state: ConnectionState): Promise<void> {
     // Emit QUIT effects without dispatching transport calls (the socket
     // is already gone). The cross-DO fanout still runs.
-    await this.loadAccountStore();
     await this.loadServicesStore();
     const services = this.servicesStore();
     const noOpHandlers: CfConnectionHandlers = {
-      send: (): void => {},
-      disconnect: (): void => {},
-      snapshot: (): ConnectionState | undefined => this.cached,
+      send: NO_OP_SEND,
+      disconnect: NO_OP_DISCONNECT,
+      snapshot: this.peekCachedSync.bind(this),
     };
     const registryKey = this.ctx.id.toString();
     const runtime = makeCfRuntime(this.env, state.id, registryKey, noOpHandlers);
@@ -723,11 +882,12 @@ export class ConnectionDO extends DurableObject<Env> {
       motd: this.motdProvider(),
       messages: this.messageStore(),
       history: this.historyStore(),
-      ...(services !== undefined ? { services } : {}),
+      ...buildOptionalActorFields(services, undefined),
     });
     await actor.receiveTextFrame('QUIT\r\n');
     await this.releaseAndPersist(state);
     await this.flushServices();
+    await this.releaseConnectionSlot();
     try {
       await this.ctx.storage.deleteAlarm();
     } catch {
@@ -735,6 +895,11 @@ export class ConnectionDO extends DurableObject<Env> {
     }
   }
 
+  /** Synchronous cached-state peek used by the no-socket teardown handlers. */
+  private peekCachedSync(): ConnectionState | undefined {
+    return this.cached;
+  }
+
   /** Drops the in-memory state cache, simulating wake-from-hibernation. */
   public __resetCache(): void {
     this.cached = undefined;
@@ -742,7 +907,7 @@ export class ConnectionDO extends DurableObject<Env> {
 
   /** Returns the live cached state (without forcing a storage read). */
   public async __peekState(): Promise<ConnectionState | undefined> {
-    return this.cached;
+    return this.peekCachedSync();
   }
 
   /** Backdates `lastSeen` to test the alarm-driven disconnect path. */
@@ -761,6 +926,58 @@ export class ConnectionDO extends DurableObject<Env> {
     this.__suppressCloseTeardown = true;
   }
 
+  /**
+   * Test-only: sets the captured mTLS cert subject, simulating an upgrade
+   * request that arrived through CF API Shield mTLS. Used to exercise the
+   * `mtlsIdentity` construction branch in {@link buildActor} without
+   * having to inject `request.cf` (which is read-only in the workerd
+   * test runtime).
+   */
+  /**
+   * Captures the verified mTLS cert identity off an inbound request and
+   * stores it on the instance. Extracted so the assignment branch is
+   * testable via {@link __captureMtlsSubjectForTest} (the workerd test
+   * runtime strips `request.cf` across the DO RPC boundary, so the
+   * inline fetch path cannot be exercised end-to-end).
+   */
+  private captureMtlsSubject(request: Request): void {
+    const identity = extractMtlsSubject(request);
+    if (identity !== undefined) {
+      this.mtlsCert = identity;
+    }
+  }
+
+  public __setMtlsCertSubject(subject: string | undefined): void {
+    this.mtlsCert = subject === undefined ? undefined : certIdentityFromSubject(subject);
+  }
+
+  /** Test-only: returns the captured mTLS cert subject (or undefined). */
+  public async __peekMtlsCertSubject(): Promise<string | undefined> {
+    return this.mtlsCert?.subject;
+  }
+
+  /**
+   * Test-only seam that exposes {@link captureMtlsSubject} so the
+   * if-defined assignment can be exercised with a crafted request.cf.
+   */
+  public __captureMtlsSubjectForTest(request: Request): void {
+    this.captureMtlsSubject(request);
+  }
+
+  /**
+   * Test-only: invokes {@link webSocketError} against the first attached
+   * WebSocket. The platform normally fires this asynchronously on
+   * transport errors; calling it here deterministically exercises the
+   * handler body. The WebSocket must have been accepted via `fetch` so
+   * `ctx.getWebSockets()` returns it.
+   */
+  public async __triggerWsError(error: unknown): Promise<void> {
+    const sockets = this.ctx.getWebSockets();
+    const ws = sockets[0];
+    if (ws === undefined) return;
+    await this.webSocketError(ws as WebSocket, error);
+  }
+
   /** Returns this DO's hex id — the canonical ConnId used in RPC routing. */
   public __peekHexId(): string {
     return this.ctx.id.toString();
@@ -813,6 +1030,104 @@ export class ConnectionDO extends DurableObject<Env> {
 /** Default MOTD when no `MOTD_LINES` env is supplied. */
 const DEFAULT_MOTD: string[] = ['Welcome to the ServerlessIRCd Cloudflare adapter.'];
 
+/**
+ * Reads the verified mTLS client-cert identity off an inbound Request, when
+ * CF API Shield mTLS is configured. Extracted as a pure helper so the
+ * `cf.tlsClientAuthCertSubject` / `cf.tlsClientAuth` branches are
+ * unit-testable directly (the workerd test runtime does not surface
+ * `request.cf` the way the CF edge does, and `Request.cf` is read-only so
+ * tests cannot inject it via the standard constructor).
+ *
+ * Identifier resolution (strongest first):
+ * 1. Subject from `cf.tlsClientAuthCertSubject` (legacy documented field),
+ *    falling back to `cf.tlsClientAuth.certSubjectDN` when absent.
+ * 2. DER SHA-256 fingerprint from `cf.tlsClientAuth.certFingerprintSHA256`
+ *    when it is a non-empty string (Cloudflare documents it as `""` for
+ *    non-mTLS connections).
+ *
+ * Returns the {@link CertIdentity} (raw subject + canonical DN + optional
+ * fingerprint) when a subject was captured, or `undefined` when mTLS is
+ * not configured.
+ */
+export function extractMtlsSubject(request: Request): CertIdentity | undefined {
+  const cf = (request as Request & { cf?: Record<string, unknown> }).cf;
+  if (cf === undefined) return undefined;
+  const subject = readCertSubject(cf);
+  if (subject === undefined) return undefined;
+  return certIdentityFromSubject(subject, readCertFingerprint(cf));
+}
+
+/** Reads the cert subject: legacy `tlsClientAuthCertSubject`, then `tlsClientAuth.certSubjectDN`. */
+function readCertSubject(cf: Record<string, unknown>): string | undefined {
+  if (typeof cf.tlsClientAuthCertSubject === 'string') {
+    return cf.tlsClientAuthCertSubject;
+  }
+  const tlsClientAuth = cf.tlsClientAuth;
+  if (isRecord(tlsClientAuth) && typeof tlsClientAuth.certSubjectDN === 'string') {
+    return tlsClientAuth.certSubjectDN;
+  }
+  return undefined;
+}
+
+/** Reads the DER SHA-256 fingerprint off `tlsClientAuth` (empty string = absent). */
+function readCertFingerprint(cf: Record<string, unknown>): string | undefined {
+  const tlsClientAuth = cf.tlsClientAuth;
+  if (!isRecord(tlsClientAuth)) return undefined;
+  const fp = tlsClientAuth.certFingerprintSHA256;
+  return typeof fp === 'string' && fp.length > 0 ? fp : undefined;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null;
+}
+
+/**
+ * No-op transport callbacks used by {@link ConnectionDO.tearDownNoSocket}
+ * when the WebSocket has already been dropped. Exported so the function
+ * bodies are exercised by a direct unit test (the actor never invokes
+ * `send`/`disconnect` during the no-socket QUIT path because there is
+ * no peer to deliver to).
+ */
+export const NO_OP_SEND: (lines: RawLine[]) => void = () => {};
+export const NO_OP_DISCONNECT: (reason?: string) => void = () => {};
+
+/**
+ * Builds the optional `services` / `mtlsIdentity` fields for a
+ * {@link ConnectionActor} constructor. Each field is included only when
+ * the source resolved a value; the `: {}` arms of the conditional spreads
+ * are exercised by both the with-everything and with-nothing test paths.
+ *
+ * Extracted as a pure helper so the conditional-spread branches are
+ * testable without driving a full DO event cycle that leaves the
+ * underlying stores unset (the test env binds D1 + services, so production
+ * builds always hit the defined arm for `services`).
+ */
+export function buildOptionalActorFields(
+  services: D1ServicesStore | undefined,
+  mtlsIdentity: MtlsIdentityProvider | undefined,
+): {
+  services?: D1ServicesStore;
+  mtlsIdentity?: MtlsIdentityProvider;
+} {
+  return {
+    ...(services !== undefined ? { services } : {}),
+    ...(mtlsIdentity !== undefined ? { mtlsIdentity } : {}),
+  };
+}
+
+/**
+ * Resolves the {@link MotdProvider} for a raw `MOTD_LINES` env value.
+ * Returns the default single-line MOTD when the env is unset or empty;
+ * otherwise splits the env on newlines. Extracted so both branches are
+ * unit-testable without changing the bound env in the test worker.
+ */
+export function chooseMotdProvider(raw: string | undefined): MotdProvider {
+  if (raw === undefined || raw.length === 0) {
+    return { lines: () => DEFAULT_MOTD };
+  }
+  return { lines: () => raw.split('\n') };
+}
+
 /**
  * `ActorChannelAccess` backed by a per-instance cache that is refreshed
  * from the authoritative ChannelDO before each reducer that needs to
@@ -919,31 +1234,6 @@ export class PassthroughChannelAccess {
   }
 }
 
-/**
- * Parses the `SASL_ACCOUNTS` env var into credential entries.
- *
- * Format: newline-delimited `username:password` pairs (mirroring the
- * `MOTD_LINES` convention). Blank lines and malformed entries (missing
- * colon or empty username/password) are skipped so a trailing newline or a
- * partial edit does not break boot. Exported so the parsing boundary is
- * unit-testable in isolation.
- */
-export function parseSaslAccountsEnv(raw: string | undefined): SaslAccountCredential[] {
-  if (raw === undefined || raw.length === 0) return [];
-  const out: SaslAccountCredential[] = [];
-  for (const line of raw.split('\n')) {
-    const trimmed = line.trim();
-    if (trimmed.length === 0) continue;
-    const sep = trimmed.indexOf(':');
-    if (sep <= 0) continue; // missing colon or empty username
-    const username = trimmed.slice(0, sep);
-    const password = trimmed.slice(sep + 1);
-    if (username.length === 0 || password.length === 0) continue;
-    out.push({ username, password });
-  }
-  return out;
-}
-
 /**
  * Hibernation-tag prefixes written by {@link ConnectionDO.fetch}. Each tag
  * encodes the negotiated {@link WsFrameMode} so it survives DO eviction and