serverless-ircd 0.10.0 → 0.11.0

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

@@ -0,0 +1,142 @@
+/**
+ * `CounterDO` — global live-connection admission counter.
+ *
+ * A single Durable Object instance (fixed name {@link COUNTER_INSTANCE_NAME})
+ * maintains one admission entry per live WebSocket connection, keyed by the
+ * owning ConnectionDO's hex id. The worker edge reserves a slot via
+ * `admit` before forwarding an upgrade (enforcing `maxClients`); the
+ * ConnectionDO releases the slot via `release` on every teardown path
+ * (clean close, transport error, socketless teardown) and refreshes it
+ * via `heartbeat` from its PING alarm.
+ *
+ * Storage layout:
+ *   - One key per connection: `conn:<connId>` → lastSeen epoch ms
+ *
+ * Housekeeping (DO-instance eviction): teardown relies on the close /
+ * error events reaching the ConnectionDO. When an isolate is dropped
+ * without delivering either (platform failure mode), `release` never
+ * fires and the entry would go stale, permanently consuming a slot.
+ * Instead of a periodic alarm sweep, every `admit` call first reaps
+ * entries whose `lastSeen` is older than the TTL — a lazy reconcile
+ * that keeps admission O(live connections) with no extra infrastructure.
+ * Live connections are safe from the reap because the ConnectionDO's
+ * PING alarm (60s cadence) heartbeats their entry ~5x within the
+ * 5-minute TTL window; only DOs that stopped heartbeating (crashed or
+ * evicted) let their entries age out.
+ *
+ * Atomicity: the DO's serialized event loop linearises concurrent
+ * `admit` calls, so the check-then-register sequence is race-free —
+ * exactly one of N concurrent upgrades can take the last slot. This
+ * mirrors the AWS adapter's atomic `__meta:connectionCount__` counter
+ * semantics without needing a conditional-write primitive.
+ */
+
+import { DurableObject } from 'cloudflare:workers';
+import type { CounterAdmissionResult, CounterRpc } from './env.js';
+
+/** Storage key prefix for per-connection admission entries. */
+const CONN_KEY_PREFIX = 'conn:';
+
+/**
+ * Fixed instance name for the single global counter. The worker edge and
+ * every ConnectionDO address the same instance via
+ * `COUNTER_DO.idFromName(COUNTER_INSTANCE_NAME)`.
+ */
+export const COUNTER_INSTANCE_NAME = 'global';
+
+/**
+ * Default TTL (ms) after which an admission entry is considered stale and
+ * reaped. Comfortably above the ConnectionDO PING alarm cadence (60s) so
+ * a live connection refreshes its entry several times per window; short
+ * enough that a crashed DO's slot self-heals within minutes.
+ */
+export const DEFAULT_CONNECTION_TTL_MS = 300_000;
+
+/** Returns the storage key for `connId`. */
+function connKey(connId: string): string {
+  return `${CONN_KEY_PREFIX}${connId}`;
+}
+
+/**
+ * Global live-connection counter authority.
+ *
+ * The class is exported as a binding target in `wrangler.toml`; the
+ * Workers runtime instantiates it with `(ctx, env)`. Implements the
+ * {@link CounterRpc} contract the worker edge and ConnectionDO call.
+ */
+export class CounterDO extends DurableObject implements CounterRpc {
+  /**
+   * Admission check + slot reservation in one serialized step.
+   *
+   * Stale entries (aged past the TTL — their ConnectionDO stopped
+   * heartbeating) are reaped first, so a crashed DO frees capacity for
+   * the newcomer instead of wedgeing the cap shut. When the surviving
+   * live count is at or above `maxClients` the caller is rejected and
+   * nothing is registered; otherwise the connection's entry is written
+   * with `now` as its initial `lastSeen`.
+   */
+  async admit(
+    connId: string,
+    maxClients: number,
+    now: number = Date.now(),
+    ttlMs: number = DEFAULT_CONNECTION_TTL_MS,
+  ): Promise<CounterAdmissionResult> {
+    const { live } = await this.sweep(now, ttlMs);
+    if (live >= maxClients) {
+      return { admitted: false, live };
+    }
+    await this.ctx.storage.put(connKey(connId), now);
+    return { admitted: true, live: live + 1 };
+  }
+
+  /**
+   * Releases a connection's slot. Idempotent: deleting an absent key is
+   * a no-op, so teardown of a connection that never registered (direct
+   * DO access outside the worker edge) is harmless.
+   */
+  async release(connId: string): Promise<void> {
+    await this.ctx.storage.delete(connKey(connId));
+  }
+
+  /**
+   * Refreshes a live entry's `lastSeen` so the TTL reap spares it.
+   * No-op for unknown ids — a late heartbeat racing a release must not
+   * resurrect the slot (that would overcount).
+   */
+  async heartbeat(connId: string, now: number = Date.now()): Promise<void> {
+    const key = connKey(connId);
+    const existing = await this.ctx.storage.get<number>(key);
+    if (existing === undefined) return;
+    await this.ctx.storage.put(key, now);
+  }
+
+  /**
+   * Reconcile sweep: deletes every entry strictly older than the TTL and
+   * reports how many were reaped vs. how many remain live. Invoked
+   * lazily by {@link admit}; exposed as an RPC so operators (and tests)
+   * can reconcile explicitly.
+   */
+  async sweep(
+    now: number = Date.now(),
+    ttlMs: number = DEFAULT_CONNECTION_TTL_MS,
+  ): Promise<{ reaped: number; live: number }> {
+    const entries = await this.ctx.storage.list({ prefix: CONN_KEY_PREFIX });
+    let reaped = 0;
+    let live = 0;
+    for (const [key, seenAt] of entries) {
+      if (now - (seenAt as number) > ttlMs) {
+        await this.ctx.storage.delete(key);
+        reaped++;
+      } else {
+        live++;
+      }
+    }
+    return { reaped, live };
+  }
+
+  /** Returns the raw entry count (no reap). Observability / tests. */
+  async liveCount(): Promise<number> {
+    const entries = await this.ctx.storage.list({ prefix: CONN_KEY_PREFIX });
+    return entries.size;
+  }
+}

package/packages/cf-adapter/src/d1-services-store.ts

@@ -78,7 +78,7 @@ interface D1QueryClient {
  * the list on a warm deploy is a no-op.
  */
 export const CREATE_NICKSERV_ACCOUNTS_SQL =
-  "CREATE TABLE IF NOT EXISTS nickserv_accounts (nick_key TEXT PRIMARY KEY, nick TEXT NOT NULL, account TEXT NOT NULL, email TEXT NOT NULL, created_at INTEGER NOT NULL, enforce TEXT NOT NULL, cert_subjects TEXT NOT NULL DEFAULT '[]', algorithm TEXT NOT NULL, salt TEXT NOT NULL, hash TEXT NOT NULL)";
+  "CREATE TABLE IF NOT EXISTS nickserv_accounts (nick_key TEXT PRIMARY KEY, nick TEXT NOT NULL, account TEXT NOT NULL, email TEXT NOT NULL, created_at INTEGER NOT NULL, enforce TEXT NOT NULL, cert_subjects TEXT NOT NULL DEFAULT '[]', identify_failures TEXT NOT NULL DEFAULT '[]', pending_identify_notice INTEGER NOT NULL DEFAULT 0, algorithm TEXT NOT NULL, salt TEXT NOT NULL, hash TEXT NOT NULL)";
 
 export const CREATE_SERVICES_TABLES_SQL: readonly string[] = [
   CREATE_NICKSERV_ACCOUNTS_SQL,
@@ -136,7 +136,7 @@ export class D1ServicesStore extends PersistentServicesStore {
         return [
           this.db
             .prepare(
-              'INSERT OR REPLACE INTO nickserv_accounts (nick_key, nick, account, email, created_at, enforce, cert_subjects, algorithm, salt, hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+              'INSERT OR REPLACE INTO nickserv_accounts (nick_key, nick, account, email, created_at, enforce, cert_subjects, identify_failures, pending_identify_notice, algorithm, salt, hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
             )
             .bind(
               fold(r.nick),
@@ -146,6 +146,8 @@ export class D1ServicesStore extends PersistentServicesStore {
               r.createdAt,
               r.enforce,
               JSON.stringify(r.certSubjects ?? []),
+              JSON.stringify(r.identifyFailures ?? []),
+              r.pendingIdentifyFailureNotice ?? 0,
               r.credential.algorithm,
               r.credential.salt,
               r.credential.hash,
@@ -363,12 +365,14 @@ async function loadNicks(db: D1QueryClient): Promise<ServicesNickRow[]> {
     created_at: unknown;
     enforce: unknown;
     cert_subjects: unknown;
+    identify_failures: unknown;
+    pending_identify_notice: unknown;
     algorithm: unknown;
     salt: unknown;
     hash: unknown;
   }>(
     db,
-    'SELECT nick, account, email, created_at, enforce, cert_subjects, algorithm, salt, hash FROM nickserv_accounts',
+    'SELECT nick, account, email, created_at, enforce, cert_subjects, identify_failures, pending_identify_notice, algorithm, salt, hash FROM nickserv_accounts',
   );
   const out: ServicesNickRow[] = [];
   for (const r of rows) {
@@ -391,6 +395,9 @@ async function loadNicks(db: D1QueryClient): Promise<ServicesNickRow[]> {
       createdAt: r.created_at,
       enforce: r.enforce as NickEnforcePolicy,
       certSubjects: parseCertSubjects(r.cert_subjects),
+      identifyFailures: parseIdentifyFailures(r.identify_failures),
+      pendingIdentifyFailureNotice:
+        typeof r.pending_identify_notice === 'number' ? r.pending_identify_notice : 0,
       credential: {
         account: r.account,
         algorithm: 'scrypt',
@@ -419,6 +426,24 @@ function parseCertSubjects(raw: unknown): string[] {
   }
 }
 
+/**
+ * Parses the `identify_failures` TEXT column (JSON-encoded array of
+ * epoch-ms timestamps) into a `number[]`. Tolerates `undefined` (a row
+ * written before the column existed), `null`, non-numeric entries, or
+ * malformed JSON — all collapse to `[]` so a stale or partially-migrated
+ * row loads cleanly.
+ */
+function parseIdentifyFailures(raw: unknown): number[] {
+  if (typeof raw !== 'string' || raw.length === 0) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((t): t is number => typeof t === 'number');
+  } catch {
+    return [];
+  }
+}
+
 async function loadChannels(db: D1QueryClient): Promise<RegisteredChannel[]> {
   const rows = await safeSelect<{
     channel: unknown;
@@ -677,7 +702,7 @@ async function ensureServicesTables(db: D1QueryClient): Promise<void> {
  *
  * `CREATE TABLE IF NOT EXISTS` does NOT add columns to an existing table,
  * so a D1 first provisioned by an older deploy keeps the original schema.
- * Two additive migrations run idempotently, each gated on `PRAGMA
+ * Three additive migrations run idempotently, each gated on `PRAGMA
  * table_info`:
  *
  *   1. **algorithm/salt/hash unification** (commit cfa5a3c). If the table
@@ -689,6 +714,11 @@ async function ensureServicesTables(db: D1QueryClient): Promise<void> {
  *      `cert_subjects`, the column is added with `NOT NULL DEFAULT '[]'`
  *      so existing rows load with an empty cert-subject list. No data
  *      loss — the column is additive.
+ *   3. **identify throttle**. If the table lacks `identify_failures`, the
+ *      `identify_failures` (JSON timestamp array) and
+ *      `pending_identify_notice` (queued owner-notice count) columns are
+ *      added with neutral defaults so pre-existing rows load unfrozen.
+ *      No data loss — the columns are additive.
  */
 async function migrateServicesSchema(db: D1QueryClient): Promise<void> {
   const nickservInfo = await db
@@ -699,7 +729,7 @@ async function migrateServicesSchema(db: D1QueryClient): Promise<void> {
     // Old schema detected (has `password`, lacks `algorithm`). The table is
     // guaranteed to exist (ensureServicesTables just ran CREATE IF NOT
     // EXISTS); recreate it with the current schema (which includes
-    // cert_subjects).
+    // cert_subjects + the identify-throttle columns).
     await db.batch([
       db.prepare('DROP TABLE nickserv_accounts'),
       db.prepare(CREATE_NICKSERV_ACCOUNTS_SQL),
@@ -714,6 +744,18 @@ async function migrateServicesSchema(db: D1QueryClient): Promise<void> {
       ),
     ]);
   }
+  // cert_subjects present (or just added) — check for the additive
+  // identify-throttle columns.
+  if (!nickservCols.has('identify_failures')) {
+    await db.batch([
+      db.prepare(
+        "ALTER TABLE nickserv_accounts ADD COLUMN identify_failures TEXT NOT NULL DEFAULT '[]'",
+      ),
+      db.prepare(
+        'ALTER TABLE nickserv_accounts ADD COLUMN pending_identify_notice INTEGER NOT NULL DEFAULT 0',
+      ),
+    ]);
+  }
 }
 
 export async function loadD1ServicesStore(

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

@@ -46,6 +46,25 @@ export interface Env {
    * unregister / list.
    */
   CHANNEL_REGISTRY_DO: DurableObjectNamespace;
+  /**
+   * Global live-connection counter authority. A single `CounterDO`
+   * instance (fixed name `global`) maintains one admission entry per
+   * live connection, keyed by the ConnectionDO hex id. The worker edge
+   * calls `admit` before forwarding an upgrade (enforcing
+   * `maxClients`); ConnectionDO calls `release` on every teardown path
+   * and `heartbeat` from its PING alarm so the counter's lazy TTL reap
+   * only evicts entries from DOs that stopped heartbeating.
+   */
+  COUNTER_DO: DurableObjectNamespace;
+  /**
+   * Per-IP upgrade rate limiter authority. A single `RateLimitDO`
+   * instance (fixed name `global`) maintains one sliding-window
+   * admission-timestamp list per source IP (the `CF-Connecting-IP` the
+   * edge stamps). The worker edge calls `check` before forwarding an
+   * upgrade (enforcing `perIpConnectionRate`) and rejects over-budget
+   * IPs with 429.
+   */
+  RATE_LIMIT_DO: DurableObjectNamespace;
   /**
    * D1 database backing persistent services (NickServ / ChanServ / HostServ /
    * MemoServ / OperServ + the unified SASL credential store). The
@@ -98,6 +117,20 @@ export interface Env {
    * `001 RPL_WELCOME`. Undefined / empty disables the gate.
    */
   SERVER_PASSWORD?: string;
+  /**
+   * Per-connection inbound frame window ceiling enforced by
+   * `ConnectionDO.webSocketMessage` BEFORE the actor / storage write.
+   * Parsed into `ServerConfig.adapter.maxFramesPerWindow`; unset falls
+   * back to the schema default (50).
+   */
+  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`; unset falls back to the
+   * schema default (5).
+   */
+  FRAME_WINDOW_SECONDS?: string;
 }
 
 /**
@@ -143,3 +176,58 @@ export interface ChannelRegistryRpc {
   unregister(name: string): Promise<void>;
   list(): Promise<string[]>;
 }
+
+/** Result of a {@link CounterRpc.admit} admission check. */
+export interface CounterAdmissionResult {
+  /** Whether the connection may proceed to the ConnectionDO upgrade. */
+  readonly admitted: boolean;
+  /** Live connection count after any lazy reap (excludes a rejection). */
+  readonly live: number;
+}
+
+/** Result of a {@link RateLimitRpc.check} budget check. */
+export interface RateLimitResult {
+  /** Whether the caller is within the per-IP budget for this window. */
+  readonly allowed: boolean;
+  /** Admissions from this IP inside the sliding window (post-prune). */
+  readonly count: number;
+}
+
+/**
+ * RPC contract the worker edge expects from the per-IP rate limiter.
+ * The real {@link RateLimitDO} implements this.
+ */
+export interface RateLimitRpc {
+  /**
+   * Prunes admissions aged out of the window, then allows (stamping
+   * `now`) only while the surviving count is under `max`. `now` is
+   * overridable for deterministic window tests.
+   */
+  check(ip: string, max: number, windowMs: number, now?: number): Promise<RateLimitResult>;
+}
+
+/**
+ * RPC contract ConnectionDO / the worker edge expect from the global
+ * connection counter. The real {@link CounterDO} implements this.
+ */
+export interface CounterRpc {
+  /**
+   * Reaps stale entries, then registers `connId` when the surviving live
+   * count is under `maxClients`. `now` / `ttlMs` are overridable for
+   * deterministic TTL tests.
+   */
+  admit(
+    connId: string,
+    maxClients: number,
+    now?: number,
+    ttlMs?: number,
+  ): Promise<CounterAdmissionResult>;
+  /** Frees the connection's slot (idempotent). */
+  release(connId: string): Promise<void>;
+  /** Refreshes the entry's lastSeen (no-op for unknown ids). */
+  heartbeat(connId: string, now?: number): Promise<void>;
+  /** Deletes entries older than the TTL; reports reaped vs. live. */
+  sweep(now?: number, ttlMs?: number): Promise<{ reaped: number; live: number }>;
+  /** Raw entry count (no reap). */
+  liveCount(): Promise<number>;
+}

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

@@ -15,6 +15,12 @@ export {
 export { RegistryDO } from './registry-do.js';
 export { ChannelDO } from './channel-do.js';
 export { ChannelRegistryDO } from './channel-registry-do.js';
+export {
+  COUNTER_INSTANCE_NAME,
+  CounterDO,
+  DEFAULT_CONNECTION_TTL_MS,
+} from './counter-do.js';
+export { RATE_LIMIT_INSTANCE_NAME, RateLimitDO } from './rate-limit-do.js';
 export type { DeliverResult, ConnectionDeliveryRpc } from './channel-do.js';
 export {
   DEFAULT_REGISTRY_SHARDS,
@@ -25,7 +31,17 @@ 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 type {
+  ChannelRpc,
+  ChannelRegistryRpc,
+  CounterAdmissionResult,
+  CounterRpc,
+  Env,
+  RateLimitResult,
+  RateLimitRpc,
+  RegistryRpc,
+} from './env.js';
+export { loadServerConfigFromCfEnv } from './config-loader.js';
 export {
   CREATE_SERVICES_TABLES_SQL,
   D1ServicesStore,

package/packages/cf-adapter/src/rate-limit-do.ts

@@ -0,0 +1,87 @@
+/**
+ * `RateLimitDO` — per-IP upgrade rate limiter.
+ *
+ * A single Durable Object instance (fixed name {@link
+ * RATE_LIMIT_INSTANCE_NAME}) maintains one sliding-window admission
+ * timestamp list per source IP, keyed by the `CF-Connecting-IP` the
+ * Cloudflare edge stamps on every request. The worker edge calls
+ * {@link RateLimitDO.check} before forwarding a WebSocket upgrade and
+ * rejects over-budget IPs with `429` — capping how fast a single host
+ * can drive connection setup (brute-forcing `PASS` / SASL credentials
+ * requires exactly that setup rate).
+ *
+ * Storage layout:
+ *   - One key per source IP: `rate:<ip>` → array of admission epoch ms
+ *
+ * Sliding window: an admission stops counting once it is strictly older
+ * than `now - windowMs` (an entry exactly `windowMs` old still counts).
+ * This mirrors irc-core's in-memory `AdmissionStats.recentAdmissions`
+ * boundary (`t >= cutoff`), so the DO and the single-process runtimes
+ * reject the same sequence of connects identically.
+ *
+ * Window semantics on rejected checks: a rejected check prunes stale
+ * timestamps but MUST NOT append one of its own — otherwise a blocked
+ * IP consumes budget from rejection attempts and can never recover.
+ *
+ * Atomicity: the DO's serialized event loop linearises concurrent
+ * `check` calls for the same IP, so N racing upgrades can never all
+ * squeeze under a budget of N-1 — mirroring the CounterDO admission
+ * semantics without a conditional-write primitive.
+ */
+
+import { DurableObject } from 'cloudflare:workers';
+import type { RateLimitResult, RateLimitRpc } from './env.js';
+
+/** Storage key prefix for per-IP admission-timestamp lists. */
+const RATE_KEY_PREFIX = 'rate:';
+
+/**
+ * Fixed instance name for the single global limiter. The worker edge
+ * addresses the same instance via
+ * `RATE_LIMIT_DO.idFromName(RATE_LIMIT_INSTANCE_NAME)`.
+ */
+export const RATE_LIMIT_INSTANCE_NAME = 'global';
+
+/** Returns the storage key for `ip`. */
+function rateKey(ip: string): string {
+  return `${RATE_KEY_PREFIX}${ip}`;
+}
+
+/**
+ * Per-IP upgrade rate authority.
+ *
+ * The class is exported as a binding target in `wrangler.toml`; the
+ * Workers runtime instantiates it with `(ctx, env)`. Implements the
+ * {@link RateLimitRpc} contract the worker edge calls.
+ */
+export class RateLimitDO extends DurableObject implements RateLimitRpc {
+  /**
+   * Sliding-window budget check + admission stamp in one serialized step.
+   *
+   * Prunes timestamps that aged out of the window, then allows the check
+   * (appending `now`) only while the surviving count is under `max`. A
+   * rejected check leaves the timestamp list at the pruned count —
+   * rejections never consume budget. `now` is overridable for
+   * deterministic window tests.
+   */
+  async check(
+    ip: string,
+    max: number,
+    windowMs: number,
+    now: number = Date.now(),
+  ): Promise<RateLimitResult> {
+    const key = rateKey(ip);
+    const stored = await this.ctx.storage.get<number[]>(key);
+    const cutoff = now - windowMs;
+    const recent = (stored ?? []).filter((t) => t >= cutoff);
+    if (recent.length >= max) {
+      // Persist the pruned list even on rejection so an IP that stops
+      // connecting does not keep stale timestamps alive indefinitely.
+      await this.ctx.storage.put(key, recent);
+      return { allowed: false, count: recent.length };
+    }
+    recent.push(now);
+    await this.ctx.storage.put(key, recent);
+    return { allowed: true, count: recent.length };
+  }
+}

package/packages/cf-adapter/tests/cf-runtime.test.ts

@@ -46,6 +46,8 @@ declare global {
       CHANNEL_DO_REAL: DurableObjectNamespace;
       CHANNEL_DO_STUB: DurableObjectNamespace;
       CHANNEL_REGISTRY_DO: DurableObjectNamespace;
+      COUNTER_DO: DurableObjectNamespace;
+      RATE_LIMIT_DO: DurableObjectNamespace;
     }
   }
 }
@@ -65,6 +67,8 @@ function envWithRealDOs(): Env {
     REGISTRY_DO: env.REGISTRY_DO_REAL,
     CHANNEL_DO: env.CHANNEL_DO_REAL,
     CHANNEL_REGISTRY_DO: env.CHANNEL_REGISTRY_DO,
+    COUNTER_DO: env.COUNTER_DO,
+    RATE_LIMIT_DO: env.RATE_LIMIT_DO,
     SERVER_NAME: 'irc.example.com',
     NETWORK_NAME: 'ExampleNet',
     MOTD_LINES: '',
@@ -82,6 +86,8 @@ function envWithChannelStub(): Env {
     REGISTRY_DO: env.REGISTRY_DO_REAL,
     CHANNEL_DO: env.CHANNEL_DO_STUB,
     CHANNEL_REGISTRY_DO: env.CHANNEL_REGISTRY_DO,
+    COUNTER_DO: env.COUNTER_DO,
+    RATE_LIMIT_DO: env.RATE_LIMIT_DO,
     SERVER_NAME: 'irc.example.com',
     NETWORK_NAME: 'ExampleNet',
     MOTD_LINES: '',
@@ -660,41 +666,54 @@ describe('CfRuntime — reloadConfig (REHASH)', () => {
 
 /**
  * Opens a ConnectionDO, registers it with the given nick, and optionally
- * flips user mode `w` on via a direct state mutation (avoids driving the
- * full MODE handshake through the actor). Returns the live WebSocket and
- * the connection's canonical hex id.
+ * flips user mode `w`/`o` on via a direct state mutation (avoids driving
+ * the full MODE/OPER handshake through the actor). Returns the live
+ * WebSocket and the connection's canonical hex id.
  */
 async function openWallopsCapableConn(
   name: string,
-  opts: { wallops: boolean },
+  opts: { wallops?: boolean; oper?: boolean },
 ): Promise<{ ws: WebSocket; hexId: string; received: string[] }> {
   const ws = await openConnection(name);
   await new Promise<void>((r) => setTimeout(r, 20));
   ws.send(`NICK ${name}\r\n`);
-  ws.send(`USER ${name} 0 * :${name}\r\n`);
+  // Fixed short username: the server caps USER at 16 bytes, and several
+  // connection names in these suites are longer — interpolating the name
+  // here made the server reject USER and close the link before the
+  // wallops/oper fan-out ever ran.
+  ws.send('USER chat 0 * :chat\r\n');
   // Drain the registration numerics so they don't interfere with the
-  // assertions on wallops delivery below.
+  // assertions on wallops/oper-notice delivery below.
   await new Promise<void>((r) => setTimeout(r, 100));
 
   const hexId = await getConnectionHexId(name);
   const received = drainSocket(ws);
 
-  if (opts.wallops) {
-    // Flip the +w mode directly on the live cached state. The DO is the
-    // authority for this state; broadcastWallops reads it back via
-    // getConnState() so what we mutate here is exactly what the fan-out
-    // will see.
+  if (opts.wallops === true || opts.oper === true) {
+    // Flip the mode(s) directly on the live cached state. The DO is the
+    // authority for this state; broadcastWallops/broadcastOperNotice read
+    // it back via getConnState() so what we mutate here is exactly what
+    // the fan-out will see.
     const stub = env.CONNECTION_DO.get(env.CONNECTION_DO.idFromString(hexId));
     await runInDurableObject(stub, async (instance: unknown) => {
       const doi = instance as {
         __peekState?: () => Promise<
           import('@serverless-ircd/irc-core').ConnectionState | undefined
         >;
-        __pokeState?: (s: import('@serverless-ircd/irc-core').ConnectionState) => void;
       };
       const state = await doi.__peekState?.();
-      if (state !== undefined) state.userModes.wallops = true;
+      if (state !== undefined) {
+        if (opts.wallops === true) state.userModes.wallops = true;
+        if (opts.oper === true) state.userModes.oper = true;
+      }
     });
+    // Persist the mutated mode: the DO persists state only after a frame
+    // dispatches, and a DO eviction between here and the fan-out would
+    // otherwise reload the unmutated persisted copy (the cause of a
+    // pre-existing intermittent failure in the excepted-originator
+    // tests). One client PING forces the persist.
+    ws.send('PING :pin\r\n');
+    await new Promise<void>((r) => setTimeout(r, 150));
   }
 
   // Reserve the nick in the REAL registry under its hex id so
@@ -752,7 +771,7 @@ describe('CfRuntime — broadcastWallops', () => {
     await rt.broadcastWallops([{ text: ':oper!u@h WALLOPS :except me' }], sender.hexId);
 
     await new Promise<void>((resolve) => {
-      const deadline = Date.now() + 1000;
+      const deadline = Date.now() + 4000;
       const tick = (): void => {
         if (other.received.some((l) => l.includes('except me'))) {
           resolve();
@@ -802,7 +821,7 @@ describe('CfRuntime — broadcastWallops', () => {
     ).resolves.toBeUndefined();
 
     await new Promise<void>((resolve) => {
-      const deadline = Date.now() + 1000;
+      const deadline = Date.now() + 4000;
       const tick = (): void => {
         if (other.received.some((l) => l.includes('ghost friendly'))) {
           resolve();
@@ -822,6 +841,76 @@ describe('CfRuntime — broadcastWallops', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Tests — broadcastOperNotice (global +o fan-out for oper-only notices)
+// ---------------------------------------------------------------------------
+
+describe('CfRuntime — broadcastOperNotice', () => {
+  it('delivers to every +o connection and skips non-opers', async () => {
+    const realEnv = envWithRealDOs();
+
+    const oper = await openWallopsCapableConn('opernote-oper', { oper: true });
+    // +w without +o must NOT receive an oper notice.
+    const wallopsOnly = await openWallopsCapableConn('opernote-wallops', { wallops: true });
+
+    const rt = new CfRuntime(realEnv, 'conn-opernote-sender', recordingHandlers());
+    await rt.broadcastOperNotice([{ text: ':server NOTICE * :*** oper lockout tripped' }]);
+
+    await new Promise<void>((resolve) => {
+      const deadline = Date.now() + 1500;
+      const tick = (): void => {
+        if (oper.received.some((l) => l.includes('oper lockout tripped'))) {
+          resolve();
+          return;
+        }
+        if (Date.now() > deadline) {
+          resolve();
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+
+    expect(oper.received.some((l) => l.includes('oper lockout tripped'))).toBe(true);
+    expect(wallopsOnly.received.some((l) => l.includes('oper lockout tripped'))).toBe(false);
+
+    oper.ws.close();
+    wallopsOnly.ws.close();
+  });
+
+  it('skips the excepted originator', async () => {
+    const realEnv = envWithRealDOs();
+    const sender = await openWallopsCapableConn('opernote-except-sender', { oper: true });
+    const other = await openWallopsCapableConn('opernote-except-other', { oper: true });
+
+    const rt = new CfRuntime(realEnv, sender.hexId, recordingHandlers());
+    await rt.broadcastOperNotice([{ text: ':server NOTICE * :*** except me' }], sender.hexId);
+
+    await new Promise<void>((resolve) => {
+      const deadline = Date.now() + 4000;
+      const tick = (): void => {
+        if (other.received.some((l) => l.includes('except me'))) {
+          resolve();
+          return;
+        }
+        if (Date.now() > deadline) {
+          resolve();
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+
+    expect(other.received.some((l) => l.includes('except me'))).toBe(true);
+    expect(sender.received.some((l) => l.includes('except me'))).toBe(false);
+
+    sender.ws.close();
+    other.ws.close();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Tests — changeNick shard routing + failure paths
 // ---------------------------------------------------------------------------