serverless-ircd 0.10.0 → 0.11.0

package/packages/cf-adapter/tests/config-loader.test.ts

@@ -17,6 +17,18 @@ interface CfEnvLike {
   CHANNEL_PREFIXES?: string;
   OPER_USER?: string;
   OPER_PASSWORD?: string;
+  /**
+   * Scrypt salt (base64) for the hashed oper credential form. When set
+   * alongside `OPER_USER` + `OPER_HASH`, the loader builds a hashed
+   * `{user, salt, hash}` cred instead of the legacy plaintext
+   * `{user, password}` shape.
+   */
+  OPER_SALT?: string;
+  /**
+   * Scrypt hash (base64) for the hashed oper credential form. See
+   * `OPER_SALT` for the full set of vars.
+   */
+  OPER_HASH?: string;
   /**
    * Server-password gate. Treat as a wrangler secret in production
    * (never a plaintext `[vars]` entry); the loader threads it through
@@ -30,6 +42,8 @@ interface CfEnvLike {
   TOPIC_LEN?: string;
   MAX_LIST_ENTRIES?: string;
   QUIT_MESSAGE?: string;
+  /** SASL EXTERNAL operator opt-in ('true'/'1' enable; default off). */
+  EXTERNAL_ENABLED?: string;
 }
 
 function baseEnv(): CfEnvLike {
@@ -82,6 +96,49 @@ describe('loadServerConfigFromCfEnv — valid env', () => {
     expect(cfg.operCreds).toEqual([{ user: 'admin', password: 'hunter2' }]);
   });
 
+  it('builds a hashed operCred from OPER_USER + OPER_SALT + OPER_HASH', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      OPER_USER: 'admin',
+      OPER_SALT: 'c2FsdA==',
+      OPER_HASH: 'aGFzaA==',
+    });
+    expect(cfg.operCreds).toEqual([{ user: 'admin', salt: 'c2FsdA==', hash: 'aGFzaA==' }]);
+  });
+
+  it('prefers the hashed form when both OPER_PASSWORD and OPER_HASH/OPER_SALT are set', () => {
+    // Hashed form takes precedence so operators can rotate to it without
+    // removing the legacy OPER_PASSWORD var in the same deploy.
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      OPER_USER: 'admin',
+      OPER_PASSWORD: 'legacy',
+      OPER_SALT: 'c2FsdA==',
+      OPER_HASH: 'aGFzaA==',
+    });
+    expect(cfg.operCreds).toEqual([{ user: 'admin', salt: 'c2FsdA==', hash: 'aGFzaA==' }]);
+  });
+
+  it('throws when OPER_USER + OPER_SALT are set but OPER_HASH is missing', () => {
+    expect(() =>
+      loadServerConfigFromCfEnv({
+        ...baseEnv(),
+        OPER_USER: 'admin',
+        OPER_SALT: 'c2FsdA==',
+      }),
+    ).toThrowError(/hash/u);
+  });
+
+  it('throws when OPER_USER + OPER_HASH are set but OPER_SALT is missing', () => {
+    expect(() =>
+      loadServerConfigFromCfEnv({
+        ...baseEnv(),
+        OPER_USER: 'admin',
+        OPER_HASH: 'aGFzaA==',
+      }),
+    ).toThrowError(/salt/u);
+  });
+
   it('threads SERVER_PASSWORD through to serverPassword', () => {
     const cfg = loadServerConfigFromCfEnv({
       ...baseEnv(),
@@ -237,3 +294,105 @@ describe('loadServerConfigFromCfEnv — SASL_ACCOUNTS parsing', () => {
     expect(cfg.createdAt).toBe(huge);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Adapter frame-rate limit (per-connection inbound frame window).
+// ---------------------------------------------------------------------------
+
+describe('loadServerConfigFromCfEnv — adapter frame-rate limit', () => {
+  it('defaults the adapter frame window when the vars are unset', () => {
+    const cfg = loadServerConfigFromCfEnv(baseEnv());
+    expect(cfg.adapter).toEqual({ maxFramesPerWindow: 50, frameWindowSeconds: 5 });
+  });
+
+  it('maps MAX_FRAMES_PER_WINDOW + FRAME_WINDOW_SECONDS to the adapter section', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      MAX_FRAMES_PER_WINDOW: '10',
+      FRAME_WINDOW_SECONDS: '2',
+    });
+    expect(cfg.adapter).toEqual({ maxFramesPerWindow: 10, frameWindowSeconds: 2 });
+  });
+
+  it('fills the unset knob with its schema default when only one var is set', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), MAX_FRAMES_PER_WINDOW: '25' });
+    expect(cfg.adapter).toEqual({ maxFramesPerWindow: 25, frameWindowSeconds: 5 });
+  });
+
+  it('throws when MAX_FRAMES_PER_WINDOW is non-numeric', () => {
+    expect(() =>
+      loadServerConfigFromCfEnv({ ...baseEnv(), MAX_FRAMES_PER_WINDOW: 'lots' }),
+    ).toThrowError(/maxFramesPerWindow/u);
+  });
+
+  it('throws when FRAME_WINDOW_SECONDS is non-positive', () => {
+    expect(() =>
+      loadServerConfigFromCfEnv({ ...baseEnv(), FRAME_WINDOW_SECONDS: '0' }),
+    ).toThrowError(/frameWindowSeconds/u);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// EXTERNAL_ENABLED — SASL EXTERNAL operator opt-in (default off).
+// ---------------------------------------------------------------------------
+
+describe('loadServerConfigFromCfEnv — EXTERNAL_ENABLED (SASL EXTERNAL opt-in)', () => {
+  it('leaves SASL EXTERNAL off when EXTERNAL_ENABLED is unset', () => {
+    const cfg = loadServerConfigFromCfEnv(baseEnv());
+    expect(cfg.sasl?.externalEnabled ?? false).toBe(false);
+  });
+
+  it('maps EXTERNAL_ENABLED=true to sasl.externalEnabled', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), EXTERNAL_ENABLED: 'true' });
+    expect(cfg.sasl?.externalEnabled).toBe(true);
+  });
+
+  it('maps EXTERNAL_ENABLED=1 to sasl.externalEnabled', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), EXTERNAL_ENABLED: '1' });
+    expect(cfg.sasl?.externalEnabled).toBe(true);
+  });
+
+  it('maps EXTERNAL_ENABLED=false (and any other value) to false', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), EXTERNAL_ENABLED: 'false' });
+    expect(cfg.sasl?.externalEnabled).toBe(false);
+    const junk = loadServerConfigFromCfEnv({ ...baseEnv(), EXTERNAL_ENABLED: 'yes please' });
+    expect(junk.sasl?.externalEnabled ?? false).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Per-IP admission knobs — edge throttling is operator-tunable via env vars.
+// ---------------------------------------------------------------------------
+
+describe('loadServerConfigFromCfEnv — per-IP admission knobs', () => {
+  it('defaults maxConnectionsPerIp / perIpConnectionRate from the schema', () => {
+    const cfg = loadServerConfigFromCfEnv(baseEnv());
+    expect(cfg.maxConnectionsPerIp).toBe(10);
+    expect(cfg.perIpConnectionRate).toEqual({ max: 5, windowMs: 60_000 });
+  });
+
+  it('parses MAX_CONNECTIONS_PER_IP as an integer', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), MAX_CONNECTIONS_PER_IP: '3' });
+    expect(cfg.maxConnectionsPerIp).toBe(3);
+  });
+
+  it('parses PER_IP_CONNECTION_RATE_MAX / _WINDOW_MS into the rate knob', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      PER_IP_CONNECTION_RATE_MAX: '10',
+      PER_IP_CONNECTION_RATE_WINDOW_MS: '30000',
+    });
+    expect(cfg.perIpConnectionRate).toEqual({ max: 10, windowMs: 30000 });
+  });
+
+  it('fills the unset half of the rate knob with the schema default', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), PER_IP_CONNECTION_RATE_MAX: '9' });
+    expect(cfg.perIpConnectionRate).toEqual({ max: 9, windowMs: 60_000 });
+  });
+
+  it('rejects a non-positive rate budget', () => {
+    expect(() =>
+      loadServerConfigFromCfEnv({ ...baseEnv(), PER_IP_CONNECTION_RATE_MAX: '0' }),
+    ).toThrowError(/perIpConnectionRate/u);
+  });
+});

package/packages/cf-adapter/tests/connection-do-counter.test.ts

@@ -0,0 +1,165 @@
+/**
+ * `ConnectionDO` × `CounterDO` — admission-slot teardown wiring.
+ *
+ * TDD outline:
+ *   "Red: the counter is not decremented on close; assert it is. Green:
+ *    decrement on close + error. Red: a crashed DO leaves the counter
+ *    sticky; assert the reconcile sweep reduces it (covered in
+ *    counter-do.test.ts — here we assert the live-side of that
+ *    contract: the PING alarm heartbeats the entry so the sweep spares
+ *    healthy connections)."
+ *
+ * The worker edge registers each upgrade in the global counter keyed by
+ * the ConnectionDO's hex id. These tests pre-register that key directly
+ * (simulating the worker), drive every ConnectionDO teardown path, and
+ * assert the slot is released.
+ */
+
+import { env, reset, runDurableObjectAlarm, runInDurableObject } from 'cloudflare:test';
+import { afterEach, describe, expect, it } from 'vitest';
+import { COUNTER_INSTANCE_NAME, DEFAULT_CONNECTION_TTL_MS } from '../src/counter-do';
+import type { CounterRpc } from '../src/env';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      CONNECTION_DO: DurableObjectNamespace;
+      COUNTER_DO: DurableObjectNamespace;
+    }
+  }
+}
+
+afterEach(async () => {
+  await reset();
+});
+
+/** RPC handle on the single global counter instance. */
+function counter(): CounterRpc {
+  const stub = env.COUNTER_DO.get(env.COUNTER_DO.idFromName(COUNTER_INSTANCE_NAME));
+  return stub as unknown as CounterRpc;
+}
+
+/** Stub for the ConnectionDO instance named `name`. */
+function connStub(name: string): DurableObjectStub {
+  return env.CONNECTION_DO.get(env.CONNECTION_DO.idFromName(name));
+}
+
+/**
+ * The canonical conn id used by the admission counter: the ConnectionDO's
+ * hex id. This is exactly what the worker registers
+ * (`idFromName(uuid).toString()`) and what the DO computes from `ctx.id`,
+ * so both sides agree on the key without passing it explicitly.
+ */
+function hexId(name: string): string {
+  return env.CONNECTION_DO.idFromName(name).toString();
+}
+
+/** Opens a real WebSocket to the ConnectionDO named `name`. */
+async function openSocket(name: string): Promise<WebSocket> {
+  const response = await connStub(name).fetch('https://do/upgrade', {
+    headers: { Upgrade: 'websocket' },
+  });
+  const ws = response.webSocket;
+  if (ws === undefined || ws === null) {
+    throw new Error('ConnectionDO.fetch did not return a WebSocket');
+  }
+  ws.accept();
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  return ws as WebSocket;
+}
+
+/** Simulates the worker edge: registers the connection's slot. */
+async function registerSlot(name: string, now?: number): Promise<void> {
+  const result = await counter().admit(hexId(name), 10_000, now);
+  if (!result.admitted) throw new Error('test setup admit unexpectedly rejected');
+}
+
+describe('ConnectionDO — admission-slot release on teardown', () => {
+  it('a clean close releases the slot (webSocketClose → tearDown)', async () => {
+    await registerSlot('slot-close-1');
+    const ws = await openSocket('slot-close-1');
+    expect(await counter().liveCount()).toBe(1);
+
+    // Deterministic close-teardown (the platform's close event lags in
+    // the test runtime; __triggerClose runs the same code path).
+    await runInDurableObject(connStub('slot-close-1'), async (instance: unknown) => {
+      const doi = instance as { __triggerClose?: () => Promise<void> };
+      await doi.__triggerClose?.();
+    });
+
+    expect(await counter().liveCount()).toBe(0);
+    ws.close();
+  });
+
+  it('a transport error releases the slot (webSocketError → tearDown)', async () => {
+    await registerSlot('slot-error-1');
+    const ws = await openSocket('slot-error-1');
+    expect(await counter().liveCount()).toBe(1);
+
+    await runInDurableObject(connStub('slot-error-1'), async (instance: unknown) => {
+      const doi = instance as { __triggerWsError?: (error: unknown) => Promise<void> };
+      await doi.__triggerWsError?.(new Error('boom'));
+    });
+
+    expect(await counter().liveCount()).toBe(0);
+    ws.close();
+  });
+
+  it('a socketless teardown releases the slot (disconnect RPC → tearDownNoSocket)', async () => {
+    await registerSlot('slot-nosock-1');
+    expect(await counter().liveCount()).toBe(1);
+
+    await (
+      connStub('slot-nosock-1') as unknown as { disconnect: () => Promise<void> }
+    ).disconnect();
+
+    expect(await counter().liveCount()).toBe(0);
+  });
+
+  it('the PING alarm heartbeats the slot so the TTL reconcile spares live connections', async () => {
+    // Register with a timestamp that is ALREADY stale — only the alarm's
+    // heartbeat can rescue the entry from the next sweep. This is the
+    // live-side complement of the crashed-DO reap test: a ConnectionDO
+    // that keeps running must keep its slot alive.
+    await registerSlot('slot-beat-1', Date.now() - DEFAULT_CONNECTION_TTL_MS - 60_000);
+    const ws = await openSocket('slot-beat-1');
+
+    expect(await runDurableObjectAlarm(connStub('slot-beat-1'))).toBe(true);
+
+    const swept = await counter().sweep();
+    expect(swept.reaped).toBe(0);
+    expect(swept.live).toBe(1);
+    ws.close();
+  });
+
+  it('an idle-timeout alarm teardown releases the slot (alarm → tearDown)', async () => {
+    await registerSlot('slot-idle-1');
+    const ws = await openSocket('slot-idle-1');
+    expect(await counter().liveCount()).toBe(1);
+
+    // Backdate lastSeen past the PONG timeout so the alarm takes the
+    // idle-teardown branch.
+    await runInDurableObject(connStub('slot-idle-1'), async (instance: unknown) => {
+      const doi = instance as { __backdateLastSeen?: (ms: number) => Promise<void> };
+      await doi.__backdateLastSeen?.(48 * 60 * 60 * 1000);
+    });
+    expect(await runDurableObjectAlarm(connStub('slot-idle-1'))).toBe(true);
+
+    expect(await counter().liveCount()).toBe(0);
+    ws.close();
+  });
+
+  it('teardown of a never-registered connection is a harmless no-op', async () => {
+    // Direct-to-DO paths (integration harness, RPC callers) never
+    // registered a slot; teardown must not throw and the counter must
+    // stay untouched.
+    const ws = await openSocket('slot-unreg-1');
+    await runInDurableObject(connStub('slot-unreg-1'), async (instance: unknown) => {
+      const doi = instance as { __triggerClose?: () => Promise<void> };
+      await doi.__triggerClose?.();
+    });
+
+    expect(await counter().liveCount()).toBe(0);
+    ws.close();
+  });
+});

package/packages/cf-adapter/tests/connection-do-frame-limit.test.ts

@@ -0,0 +1,177 @@
+/**
+ * CF adapter — per-connection inbound frame-rate window at the adapter
+ * boundary (`ConnectionDO.webSocketMessage`).
+ *
+ * The gate fires BEFORE the actor / storage write: a connection that
+ * delivers more than `adapter.maxFramesPerWindow` frames inside the
+ * `adapter.frameWindowSeconds` sliding window is closed with RFC 6455
+ * close code 1008 (Policy Violation) after receiving the canonical
+ * `ERROR :Closing link (flooding)` line.
+ *
+ * The default window (50 frames / 5 s) exercises the under/at/over
+ * thresholds; the sliding-window decay uses the `__setFrameWindowForTest`
+ * seam to install a tight window so the test does not sleep for real
+ * seconds.
+ */
+
+import { env, runInDurableObject } from 'cloudflare:test';
+import { describe, expect, it } from 'vitest';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      CONNECTION_DO: DurableObjectNamespace;
+      REGISTRY_DO: DurableObjectNamespace;
+      CHANNEL_DO: DurableObjectNamespace;
+    }
+  }
+}
+
+/** Poll interval (ms) for the waitFor* helpers. */
+const POLL_MS = 10;
+/** Default timeout (ms) for the waitFor* helpers. */
+const DEFAULT_TIMEOUT_MS = 4000;
+
+class FrameWsClient {
+  readonly lines: string[] = [];
+  readonly ws: WebSocket;
+  closedCode: number | undefined;
+
+  constructor(ws: WebSocket) {
+    this.ws = ws;
+    ws.addEventListener('message', (ev: MessageEvent) => {
+      const data = typeof ev.data === 'string' ? ev.data : new TextDecoder().decode(ev.data);
+      for (const line of data.split('\r\n')) {
+        if (line.length > 0) this.lines.push(line);
+      }
+    });
+    ws.addEventListener('close', (ev: CloseEvent) => {
+      this.closedCode = ev.code;
+    });
+  }
+
+  send(line: string): void {
+    this.ws.send(`${line}\r\n`);
+  }
+
+  countPongs(): number {
+    return this.lines.filter((l) => l.startsWith('PONG')).length;
+  }
+
+  async waitForPongs(n: number, timeoutMs = DEFAULT_TIMEOUT_MS): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (this.countPongs() >= n) return;
+      await new Promise((r) => setTimeout(r, POLL_MS));
+    }
+    throw new Error(`waitForPongs(${n}) timed out; lines: ${JSON.stringify(this.lines)}`);
+  }
+
+  async waitForClose(timeoutMs = DEFAULT_TIMEOUT_MS): Promise<number> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (this.closedCode !== undefined) return this.closedCode;
+      await new Promise((r) => setTimeout(r, POLL_MS));
+    }
+    throw new Error(`waitForClose timed out; lines: ${JSON.stringify(this.lines)}`);
+  }
+}
+
+async function openConnection(
+  connId: string,
+): Promise<{ client: FrameWsClient; stub: DurableObjectStub }> {
+  const stub = env.CONNECTION_DO.get(env.CONNECTION_DO.idFromName(connId));
+  const response = await stub.fetch('https://do/upgrade', { headers: { Upgrade: 'websocket' } });
+  const ws = response.webSocket;
+  if (ws === undefined || ws === null) {
+    throw new Error('ConnectionDO.fetch did not return a WebSocket');
+  }
+  ws.accept();
+  const client = await new Promise<FrameWsClient>((resolve) => {
+    setTimeout(() => resolve(new FrameWsClient(ws as WebSocket)), 0);
+  });
+  return { client, stub };
+}
+
+/** RPC shape of the `ConnectionDO` test seam used for the decay test. */
+interface FrameWindowSeam {
+  __setFrameWindowForTest(cfg: { maxFrames: number; windowMs: number } | undefined): void;
+}
+
+describe('ConnectionDO — inbound frame-rate window (default 50 / 5 s)', () => {
+  it('admits frames while the window is under the ceiling and at the ceiling (no close)', async () => {
+    const { client } = await openConnection('conn-frame-under');
+    // 50 frames = exactly the default ceiling; every one is admitted and
+    // answered (each PING is one WebSocket frame through the actor).
+    for (let i = 1; i <= 50; i++) {
+      client.send(`PING :u${i}`);
+    }
+    await client.waitForPongs(50);
+    // Grace window: a close would have landed by now if the 50th frame
+    // had tripped the gate.
+    await new Promise((r) => setTimeout(r, 150));
+    expect(client.closedCode).toBeUndefined();
+    client.ws.close();
+  });
+
+  it('closes with RFC 6455 code 1008 after ERROR :Closing link (flooding) on frame 51', async () => {
+    const { client } = await openConnection('conn-frame-over');
+    for (let i = 1; i <= 50; i++) {
+      client.send(`PING :o${i}`);
+    }
+    await client.waitForPongs(50);
+
+    // Frame 51 exceeds the window: no actor run (no PONG), the ERROR
+    // line is delivered, then the socket is closed with 1008.
+    client.send('PING :o51');
+    const code = await client.waitForClose();
+    expect(code).toBe(1008);
+    expect(client.lines).toContain('ERROR :Closing link (flooding)');
+    expect(client.lines.some((l) => l.startsWith('PONG :o51'))).toBe(false);
+  });
+
+  it('admits a fresh burst after the window decays (sliding window)', async () => {
+    const { client, stub } = await openConnection('conn-frame-decay');
+    // Tight window (5 frames / 400 ms) via the test seam so the decay
+    // wait is fast instead of a real 5-second sleep.
+    await runInDurableObject(stub, (instance: unknown) => {
+      (instance as FrameWindowSeam).__setFrameWindowForTest({
+        maxFrames: 5,
+        windowMs: 400,
+      });
+    });
+
+    for (let i = 1; i <= 5; i++) {
+      client.send(`PING :d1-${i}`);
+    }
+    await client.waitForPongs(5);
+
+    // Wait past the window: the first burst decays out entirely.
+    await new Promise((r) => setTimeout(r, 500));
+    for (let i = 1; i <= 5; i++) {
+      client.send(`PING :d2-${i}`);
+    }
+    await client.waitForPongs(10);
+    await new Promise((r) => setTimeout(r, 150));
+    expect(client.closedCode).toBeUndefined();
+    expect(client.countPongs()).toBe(10);
+    client.ws.close();
+  });
+
+  it('still floods out mid-burst once the tight window is full (seam sanity)', async () => {
+    const { client, stub } = await openConnection('conn-frame-tight');
+    await runInDurableObject(stub, (instance: unknown) => {
+      (instance as FrameWindowSeam).__setFrameWindowForTest({
+        maxFrames: 2,
+        windowMs: 60_000,
+      });
+    });
+    client.send('PING :t1');
+    client.send('PING :t2');
+    client.send('PING :t3');
+    const code = await client.waitForClose();
+    expect(code).toBe(1008);
+    expect(client.lines).toContain('ERROR :Closing link (flooding)');
+    expect(client.countPongs()).toBe(2);
+  });
+});

package/packages/cf-adapter/tests/connection-do-pure.test.ts

@@ -233,16 +233,78 @@ describe('NO_OP_SEND / NO_OP_DISCONNECT', () => {
 });
 
 // ============================================================================
-// extractMtlsSubject — request.cf.tlsClientAuthCertSubject capture
+// extractMtlsSubject — request.cf mTLS identity capture
+// (cf.tlsClientAuthCertSubject + cf.tlsClientAuth.certFingerprintSHA256)
 // ============================================================================
 
 describe('extractMtlsSubject', () => {
-  it('returns the subject when cf.tlsClientAuthCertSubject is a string', () => {
+  it('returns the subject identity when cf.tlsClientAuthCertSubject is a string', () => {
     // The CF edge injects request.cf on every proxied request. We can't
     // mutate Request.cf in workerd tests (it's read-only), so the
     // upgrade-time capture is exercised via this pure seam.
     const fake = { cf: { tlsClientAuthCertSubject: 'CN=alice' } } as unknown as Request;
-    expect(extractMtlsSubject(fake)).toBe('CN=alice');
+    expect(extractMtlsSubject(fake)).toEqual({
+      subject: 'CN=alice',
+      canonicalDn: 'cn=alice',
+    });
+  });
+
+  it('includes the fingerprint from cf.tlsClientAuth.certFingerprintSHA256 when present', () => {
+    const fake = {
+      cf: {
+        tlsClientAuthCertSubject: 'CN=alice',
+        tlsClientAuth: { certFingerprintSHA256: 'af363dc85bc942a8' },
+      },
+    } as unknown as Request;
+    expect(extractMtlsSubject(fake)).toEqual({
+      subject: 'CN=alice',
+      canonicalDn: 'cn=alice',
+      fingerprint: 'af363dc85bc942a8',
+    });
+  });
+
+  it('omits the fingerprint when certFingerprintSHA256 is the documented empty default', () => {
+    // Cloudflare documents certFingerprintSHA256 as `""` when the
+    // connection is not mTLS — treat that as "no fingerprint".
+    const fake = {
+      cf: {
+        tlsClientAuthCertSubject: 'CN=alice',
+        tlsClientAuth: { certFingerprintSHA256: '' },
+      },
+    } as unknown as Request;
+    expect(extractMtlsSubject(fake)?.fingerprint).toBeUndefined();
+  });
+
+  it('ignores a non-string certFingerprintSHA256', () => {
+    const fake = {
+      cf: {
+        tlsClientAuthCertSubject: 'CN=alice',
+        tlsClientAuth: { certFingerprintSHA256: 42 },
+      },
+    } as unknown as Request;
+    expect(extractMtlsSubject(fake)?.fingerprint).toBeUndefined();
+  });
+
+  it('falls back to cf.tlsClientAuth.certSubjectDN when the legacy subject field is absent', () => {
+    const fake = {
+      cf: {
+        tlsClientAuth: { certSubjectDN: 'CN=alice,O=Example', certFingerprintSHA256: 'aa11' },
+      },
+    } as unknown as Request;
+    const identity = extractMtlsSubject(fake);
+    expect(identity?.subject).toBe('CN=alice,O=Example');
+    expect(identity?.canonicalDn).toBe('cn=alice,o=Example');
+    expect(identity?.fingerprint).toBe('aa11');
+  });
+
+  it('prefers the legacy subject field over tlsClientAuth.certSubjectDN', () => {
+    const fake = {
+      cf: {
+        tlsClientAuthCertSubject: 'CN=legacy',
+        tlsClientAuth: { certSubjectDN: 'CN=newer' },
+      },
+    } as unknown as Request;
+    expect(extractMtlsSubject(fake)?.subject).toBe('CN=legacy');
   });
 
   it('returns undefined when cf is absent', () => {
@@ -250,8 +312,10 @@ describe('extractMtlsSubject', () => {
     expect(extractMtlsSubject(fake)).toBeUndefined();
   });
 
-  it('returns undefined when cf is present but lacks tlsClientAuthCertSubject', () => {
-    const fake = { cf: { country: 'US' } } as unknown as Request;
+  it('returns undefined when cf is present but carries no cert subject', () => {
+    const fake = {
+      cf: { country: 'US', tlsClientAuth: { certVerified: 'NONE' } },
+    } as unknown as Request;
     expect(extractMtlsSubject(fake)).toBeUndefined();
   });
 
@@ -259,4 +323,9 @@ describe('extractMtlsSubject', () => {
     const fake = { cf: { tlsClientAuthCertSubject: 42 } } as unknown as Request;
     expect(extractMtlsSubject(fake)).toBeUndefined();
   });
+
+  it('returns undefined when tlsClientAuth is not an object', () => {
+    const fake = { cf: { tlsClientAuth: 'nope' } } as unknown as Request;
+    expect(extractMtlsSubject(fake)).toBeUndefined();
+  });
 });

package/packages/cf-adapter/tests/connection-do-ws-spec-contract.test.ts

@@ -223,12 +223,15 @@ describe('ConnectionDO — IRCv3 WebSocket spec contract (end-to-end)', () => {
     client.messages.length = 0;
 
     // One WS message that LOOKS like two PING lines. In spec mode the frame
-    // is a single IRC message, so exactly ONE PONG is emitted.
+    // is a single IRC message, so it is never split into two commands: the
+    // embedded CR makes the line unparseable (bare-CR rejection) and the
+    // actor answers with exactly ONE 421 — never a PONG, let alone two.
     client.sendRaw('PING one\r\nPING two');
-    await client.waitForMessages((m) => countCommand([m], 'PONG') === 1, 1);
-    // Give a grace window for a (incorrect) second PONG to arrive.
+    await client.waitForLine((l) => l.includes(' 421 '));
+    // Give a grace window for a (incorrect) PONG or second reply to arrive.
     await new Promise((r) => setTimeout(r, 100));
-    expect(countCommand(client.messages, 'PONG')).toBe(1);
+    expect(countCommand(client.messages, 'PONG')).toBe(0);
+    expect(client.messages.filter((m) => m.includes(' 421 '))).toHaveLength(1);
     client.ws.close();
   });