serverless-ircd 0.10.0 → 0.11.0

package/packages/cf-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-adapter",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": true,
   "description": "Cloudflare Workers adapter: Durable Objects (ConnectionDO, RegistryDO, ChannelDO) and CfRuntime implementing IrcRuntime",
   "license": "BSD-3-Clause",

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

@@ -162,6 +162,30 @@ export class CfRuntime implements IrcRuntime {
    * round-trip for the enumeration phase.
    */
   async broadcastWallops(lines: RawLine[], except?: ConnId): Promise<void> {
+    await this.fanOutByUserMode(lines, except, 'wallops');
+  }
+
+  /**
+   * Oper-only global notice fan-out (e.g. the OPER reducer's per-IP
+   * lockout notice). Identical enumeration to {@link broadcastWallops};
+   * the recipient gate is user mode `+o` instead of `+w`.
+   */
+  async broadcastOperNotice(lines: RawLine[], except?: ConnId): Promise<void> {
+    await this.fanOutByUserMode(lines, except, 'oper');
+  }
+
+  /**
+   * Shared fan-out behind {@link broadcastWallops} and
+   * {@link broadcastOperNotice}: enumerate every connId across all
+   * registry shards, fetch each candidate's state, gate on the requested
+   * user mode, and deliver via the ConnectionDO `deliver` RPC.
+   * `except` (the originator) and the bound connection are skipped.
+   */
+  private async fanOutByUserMode(
+    lines: RawLine[],
+    except: ConnId | undefined,
+    mode: 'wallops' | 'oper',
+  ): Promise<void> {
     // Phase 1 — enumerate every connId across all registry shards.
     const shardEntries = await Promise.all(
       Array.from({ length: this.registryShards }, (_, i) => this.registryShardRpc(i).listEntries()),
@@ -173,18 +197,19 @@ export class CfRuntime implements IrcRuntime {
       }
     }
 
-    // Phase 2 — fetch each candidate's state, filter +w, deliver.
+    // Phase 2 — fetch each candidate's state, filter by mode, deliver.
     // Bound the per-call fan-out by skipping the excepted/bound connection
-    // up front (the bound connection's own +w never needs a self-RPC).
+    // up front (the bound connection's own mode never needs a self-RPC).
     await Promise.all(
       Array.from(seen, async (connId) => {
         if (connId === except || connId === this.connId) return;
         const stub = this.env.CONNECTION_DO.get(this.env.CONNECTION_DO.idFromString(connId));
         const dto = await (stub as unknown as ConnectionRpc).getConnState();
-        await this.deliverWallopsToCandidate(
+        await this.deliverToCandidateByMode(
           stub as unknown as { deliver(lines: RawLine[]): Promise<unknown> },
           dto,
           lines,
+          mode,
         );
       }),
     );
@@ -322,11 +347,11 @@ export class CfRuntime implements IrcRuntime {
   /**
    * Phase 2 of {@link broadcastWallops}: rehydrates the candidate's
    * persisted state, gates on user mode `+w`, and dispatches `lines`
-   * via the target stub's `deliver` RPC. Extracted as a public test
-   * seam because every real ConnectionDO's `getConnState` always
-   * returns a non-null DTO (the storage layer is the source of truth
-   * and always has an entry post-`loadState`), so the `dto === null`
-   * and `!+w` defensive arms are unreachable through end-to-end RPC.
+   * via the target stub's `deliver` RPC. Kept as a public test seam
+   * because every real ConnectionDO's `getConnState` always returns a
+   * non-null DTO (the storage layer is the source of truth and always
+   * has an entry post-`loadState`), so the `dto === null` and `!+w`
+   * defensive arms are unreachable through end-to-end RPC.
    *
    * Behavioural contract:
    *   - `dto === null`           → no-op (candidate reported no state).
@@ -337,10 +362,24 @@ export class CfRuntime implements IrcRuntime {
     stub: { deliver(lines: RawLine[]): Promise<unknown> },
     dto: PersistedConnectionState | null,
     lines: RawLine[],
+  ): Promise<void> {
+    await this.deliverToCandidateByMode(stub, dto, lines, 'wallops');
+  }
+
+  /**
+   * Mode-parameterised gate behind {@link deliverWallopsToCandidate} and
+   * {@link fanOutByUserMode}: rehydrate the DTO, check the requested
+   * user mode (`+w` wallops / `+o` oper), deliver when it is set.
+   */
+  private async deliverToCandidateByMode(
+    stub: { deliver(lines: RawLine[]): Promise<unknown> },
+    dto: PersistedConnectionState | null,
+    lines: RawLine[],
+    mode: 'wallops' | 'oper',
   ): Promise<void> {
     if (dto === null) return;
     const state = deserialize(dto);
-    if (!state.userModes.wallops) return;
+    if (!state.userModes[mode]) return;
     await stub.deliver(lines);
   }
 

package/packages/cf-adapter/src/config-loader.ts

@@ -13,6 +13,15 @@
 
 import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc-core';
 
+/**
+ * Documented schema defaults for `perIpConnectionRate`. Duplicated here
+ * (the schema inlines its `.default(...)`) so an operator setting only
+ * one half of the knob via env gets the documented default for the other
+ * half rather than a parse error.
+ */
+const DEFAULT_PER_IP_RATE_MAX = 5;
+const DEFAULT_PER_IP_RATE_WINDOW_MS = 60_000;
+
 /**
  * The subset of the Workers `Env` that this loader reads. Mirrors the
  * production {@link Env} in `env.ts` plus the optional knobs the schema
@@ -38,6 +47,20 @@ export interface CfConfigEnv {
   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. The hashed form is preferred when both
+   * are present so deployments can rotate without removing the legacy
+   * vars in the same step. Generate via `tools/hash-oper-cred.ts`.
+   */
+  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
@@ -59,6 +82,40 @@ export interface CfConfigEnv {
    * path (vs the connection-do's direct env read) stays consistent.
    */
   SASL_ACCOUNTS?: string;
+  /**
+   * Per-connection inbound frame window ceiling enforced by
+   * `ConnectionDO.webSocketMessage` BEFORE the actor / storage write.
+   * Parsed into `ServerConfig.adapter.maxFramesPerWindow`.
+   */
+  MAX_FRAMES_PER_WINDOW?: string;
+  /**
+   * Sliding-window length (seconds) for the inbound frame limit; frames
+   * older than the window stop counting. Parsed into
+   * `ServerConfig.adapter.frameWindowSeconds`.
+   */
+  FRAME_WINDOW_SECONDS?: string;
+  /**
+   * Per-IP simultaneous-connection cap (`maxConnectionsPerIp`). Enforced
+   * by the adapters' admission gates; mirrors the Lambda loader's var of
+   * the same name.
+   */
+  MAX_CONNECTIONS_PER_IP?: string;
+  /**
+   * Per-IP connection-rate budget (`perIpConnectionRate.max`) — how many
+   * new connections one source IP may open per sliding window. The unset
+   * half of the knob falls back to the schema default.
+   */
+  PER_IP_CONNECTION_RATE_MAX?: string;
+  /** Sliding window length in ms (`perIpConnectionRate.windowMs`). */
+  PER_IP_CONNECTION_RATE_WINDOW_MS?: string;
+  /**
+   * Operator opt-in for certificate-backed SASL EXTERNAL. 'true'/'1'
+   * (case-insensitive) map to `sasl.externalEnabled: true`; any other
+   * value (and unset) leaves the mechanism off. EXTERNAL additionally
+   * requires edge mTLS (API Shield client certs) and a secure (TLS)
+   * connection — the flag alone advertises nothing.
+   */
+  EXTERNAL_ENABLED?: string;
 }
 
 /**
@@ -91,14 +148,36 @@ function buildConfigInput(env: CfConfigEnv): Record<string, unknown> {
     input.channelPrefixes = env.CHANNEL_PREFIXES;
   }
   if (env.OPER_USER !== undefined || env.OPER_PASSWORD !== undefined) {
-    // Build the cred object from whatever was supplied; the schema
-    // surfaces a `user`/`password` error if only one half was provided.
-    input.operCreds = [
-      {
-        user: env.OPER_USER ?? '',
-        password: env.OPER_PASSWORD ?? '',
-      },
-    ];
+    // Hashed form (OPER_USER + OPER_SALT + OPER_HASH) is preferred when
+    // both salt + hash are supplied — even if OPER_PASSWORD is also set,
+    // so a deployment can rotate to the hashed form without dropping the
+    // legacy var in the same release. The legacy plaintext
+    // `{user, password}` shape is retained for a single deprecation-
+    // cycle window.
+    const hasHashed = env.OPER_SALT !== undefined && env.OPER_HASH !== undefined;
+    if (hasHashed) {
+      input.operCreds = [
+        {
+          user: env.OPER_USER ?? '',
+          salt: env.OPER_SALT ?? '',
+          hash: env.OPER_HASH ?? '',
+        },
+      ];
+    } else {
+      // Build the legacy cred object from whatever was supplied; the
+      // schema surfaces a `user`/`password` error if only one half was
+      // provided. If only OPER_SALT/OPER_HASH (partial) are set, the
+      // schema will surface the missing hashed-form field via the
+      // superRefine error path.
+      input.operCreds = [
+        {
+          user: env.OPER_USER ?? '',
+          password: env.OPER_PASSWORD ?? '',
+          ...(env.OPER_SALT !== undefined ? { salt: env.OPER_SALT } : {}),
+          ...(env.OPER_HASH !== undefined ? { hash: env.OPER_HASH } : {}),
+        },
+      ];
+    }
   }
   if (env.SERVER_PASSWORD !== undefined) {
     input.serverPassword = env.SERVER_PASSWORD;
@@ -127,9 +206,55 @@ function buildConfigInput(env: CfConfigEnv): Record<string, unknown> {
   if (env.SASL_ACCOUNTS !== undefined && env.SASL_ACCOUNTS.length > 0) {
     input.saslAccounts = parseSaslAccountsLines(env.SASL_ACCOUNTS);
   }
+  if (env.MAX_FRAMES_PER_WINDOW !== undefined || env.FRAME_WINDOW_SECONDS !== undefined) {
+    // Partial sections are fine: the per-field schema defaults fill the
+    // knob(s) the env did not supply.
+    input.adapter = {
+      ...(env.MAX_FRAMES_PER_WINDOW !== undefined
+        ? { maxFramesPerWindow: Number.parseInt(env.MAX_FRAMES_PER_WINDOW, 10) }
+        : {}),
+      ...(env.FRAME_WINDOW_SECONDS !== undefined
+        ? { frameWindowSeconds: Number.parseInt(env.FRAME_WINDOW_SECONDS, 10) }
+        : {}),
+    };
+  }
+  if (env.MAX_CONNECTIONS_PER_IP !== undefined) {
+    input.maxConnectionsPerIp = Number.parseInt(env.MAX_CONNECTIONS_PER_IP, 10);
+  }
+  if (
+    env.PER_IP_CONNECTION_RATE_MAX !== undefined ||
+    env.PER_IP_CONNECTION_RATE_WINDOW_MS !== undefined
+  ) {
+    // The schema requires both halves; the unset one falls back to the
+    // documented schema defaults so an operator can tune just the budget
+    // (or just the window) without restating the other.
+    input.perIpConnectionRate = {
+      max:
+        env.PER_IP_CONNECTION_RATE_MAX !== undefined
+          ? Number.parseInt(env.PER_IP_CONNECTION_RATE_MAX, 10)
+          : DEFAULT_PER_IP_RATE_MAX,
+      windowMs:
+        env.PER_IP_CONNECTION_RATE_WINDOW_MS !== undefined
+          ? Number.parseInt(env.PER_IP_CONNECTION_RATE_WINDOW_MS, 10)
+          : DEFAULT_PER_IP_RATE_WINDOW_MS,
+    };
+  }
+  if (env.EXTERNAL_ENABLED !== undefined) {
+    input.sasl = { externalEnabled: parseEnabledFlag(env.EXTERNAL_ENABLED) };
+  }
   return input;
 }
 
+/**
+ * Parses a boolean feature-flag env var: 'true' / '1' (case-insensitive,
+ * whitespace-trimmed) are truthy; every other value is false. Flags
+ * default off, so a typo must never silently enable the feature.
+ */
+function parseEnabledFlag(raw: string): boolean {
+  const normalized = raw.trim().toLowerCase();
+  return normalized === 'true' || normalized === '1';
+}
+
 /**
  * Parses the `CREATED_AT` env var into the schema's `createdAt` field.
  *

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

@@ -29,12 +29,15 @@
 
 import { DurableObject } from 'cloudflare:workers';
 import {
+  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,
@@ -51,6 +54,8 @@ import {
   SystemClock,
   UuidIdFactory,
   type WsFrameMode,
+  admitFrameWindow,
+  certIdentityFromSubject,
   createChannel,
   createConnection,
   frameToLines,
@@ -65,8 +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 { 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';
@@ -155,19 +161,22 @@ export class ConnectionDO extends DurableObject<Env> {
   /** 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
@@ -179,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;
@@ -241,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.
@@ -341,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);
   }
 
@@ -455,6 +495,37 @@ export class ConnectionDO extends DurableObject<Env> {
     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;
@@ -516,8 +587,8 @@ export class ConnectionDO extends DurableObject<Env> {
     const logger: Logger = new ConsoleLogger({ connectionId: state.id }, undefined, LogLevel.Info);
     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,
@@ -588,6 +659,7 @@ export class ConnectionDO extends DurableObject<Env> {
     await actor.receiveTextFrame('QUIT\r\n');
     await this.releaseAndPersist(state);
     await this.flushServices();
+    await this.releaseConnectionSlot();
     this.closeIfStillOpen(ws);
     try {
       await this.ctx.storage.deleteAlarm();
@@ -623,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,
@@ -789,6 +887,7 @@ export class ConnectionDO extends DurableObject<Env> {
     await actor.receiveTextFrame('QUIT\r\n');
     await this.releaseAndPersist(state);
     await this.flushServices();
+    await this.releaseConnectionSlot();
     try {
       await this.ctx.storage.deleteAlarm();
     } catch {
@@ -835,26 +934,26 @@ export class ConnectionDO extends DurableObject<Env> {
    * test runtime).
    */
   /**
-   * Captures the verified mTLS cert subject off an inbound request and
+   * 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 cf = extractMtlsSubject(request);
-    if (cf !== undefined) {
-      this.mtlsCertSubject = cf;
+    const identity = extractMtlsSubject(request);
+    if (identity !== undefined) {
+      this.mtlsCert = identity;
     }
   }
 
   public __setMtlsCertSubject(subject: string | undefined): void {
-    this.mtlsCertSubject = subject;
+    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.mtlsCertSubject;
+    return this.mtlsCert?.subject;
   }
 
   /**
@@ -932,22 +1031,56 @@ export class ConnectionDO extends DurableObject<Env> {
 const DEFAULT_MOTD: string[] = ['Welcome to the ServerlessIRCd Cloudflare adapter.'];
 
 /**
- * Reads the verified mTLS client-cert subject off an inbound Request, when
+ * 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` branch is 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). Returns the subject string when present, or
- * `undefined` when mTLS is not configured.
+ * `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): string | undefined {
+export function extractMtlsSubject(request: Request): CertIdentity | undefined {
   const cf = (request as Request & { cf?: Record<string, unknown> }).cf;
-  if (cf !== undefined && typeof cf.tlsClientAuthCertSubject === 'string') {
+  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