serverless-ircd 0.9.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, 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, 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),
@@ -145,6 +145,9 @@ export class D1ServicesStore extends PersistentServicesStore {
               r.email,
               r.createdAt,
               r.enforce,
+              JSON.stringify(r.certSubjects ?? []),
+              JSON.stringify(r.identifyFailures ?? []),
+              r.pendingIdentifyFailureNotice ?? 0,
               r.credential.algorithm,
               r.credential.salt,
               r.credential.hash,
@@ -361,12 +364,15 @@ async function loadNicks(db: D1QueryClient): Promise<ServicesNickRow[]> {
     email: unknown;
     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, 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) {
@@ -388,6 +394,10 @@ async function loadNicks(db: D1QueryClient): Promise<ServicesNickRow[]> {
       email: r.email,
       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',
@@ -399,6 +409,41 @@ async function loadNicks(db: D1QueryClient): Promise<ServicesNickRow[]> {
   return out;
 }
 
+/**
+ * Parses the `cert_subjects` TEXT column (JSON-encoded array) into a
+ * `string[]`. Tolerates `undefined` (a row written before the column
+ * existed), `null`, or malformed JSON — all collapse to `[]` so a stale or
+ * partially-migrated row loads cleanly.
+ */
+function parseCertSubjects(raw: unknown): string[] {
+  if (typeof raw !== 'string' || raw.length === 0) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((s): s is string => typeof s === 'string');
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 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;
@@ -603,8 +648,13 @@ async function loadJupes(db: D1QueryClient): Promise<JupeEntry[]> {
  * table does not exist yet (fresh deploy) or the binding is unreachable.
  * Silent-skip mirrors the DynamoDB loader: a missing table is treated as
  * an empty section rather than a fatal boot error.
+ *
+ * Exported so the catch-block fallback is unit-testable directly with a
+ * throwing D1 stub (the real binding does not fail on queries that target
+ * existing tables, so the catch arm is unreachable through integration
+ * tests).
  */
-async function safeSelect<R>(db: D1QueryClient, sql: string): Promise<R[]> {
+export async function safeSelect<R>(db: D1QueryClient, sql: string): Promise<R[]> {
   try {
     const result = await db.prepare(sql).all<R>();
     return result.results;
@@ -648,35 +698,64 @@ async function ensureServicesTables(db: D1QueryClient): Promise<void> {
 }
 
 /**
- * One-time schema migration for the `algorithm/salt/hash` unification
- * (commit cfa5a3c). `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 `nickserv_accounts (... enforce, password)` schema. Every
- * current SELECT/INSERT references `algorithm`, so reads throw
- * "no such column: algorithm" (masked by `safeSelect` as an empty
- * snapshot) and writes throw inside `flush()` (after the success NOTICE).
+ * One-time schema migrations for `nickserv_accounts`.
  *
- * Detection: `PRAGMA table_info`. If `nickserv_accounts` lacks
- * `algorithm`, it is the pre-unification schema. Those rows stored a
- * non-scrypt `password` the current `verifyNick` cannot validate, so the
- * table is dropped and recreated with the current schema (data loss is
- * intentional and limited to already-unusable credentials). Idempotent:
- * once the new schema is in place, `algorithm` is present and this is a
- * no-op.
+ * `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.
+ * Three additive migrations run idempotently, each gated on `PRAGMA
+ * table_info`:
+ *
+ *   1. **algorithm/salt/hash unification** (commit cfa5a3c). If the table
+ *      lacks `algorithm`, it has the pre-unification `password` column
+ *      whose credentials the current `verifyNick` cannot validate. The
+ *      table is dropped and recreated with the current schema (data loss
+ *      is intentional and limited to already-unusable credentials).
+ *   2. **cert_subjects**. If the table has `algorithm` but lacks
+ *      `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
     .prepare('PRAGMA table_info(nickserv_accounts)')
     .all<{ name: string }>();
   const nickservCols = new Set(nickservInfo.results.map((r) => r.name));
-  if (nickservCols.has('algorithm')) return;
-  // 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.
-  await db.batch([
-    db.prepare('DROP TABLE nickserv_accounts'),
-    db.prepare(CREATE_NICKSERV_ACCOUNTS_SQL),
-  ]);
+  if (!nickservCols.has('algorithm')) {
+    // 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 + the identify-throttle columns).
+    await db.batch([
+      db.prepare('DROP TABLE nickserv_accounts'),
+      db.prepare(CREATE_NICKSERV_ACCOUNTS_SQL),
+    ]);
+    return;
+  }
+  // algorithm present — check for the additive cert_subjects column.
+  if (!nickservCols.has('cert_subjects')) {
+    await db.batch([
+      db.prepare(
+        "ALTER TABLE nickserv_accounts ADD COLUMN cert_subjects TEXT NOT NULL DEFAULT '[]'",
+      ),
+    ]);
+  }
+  // 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

@@ -47,13 +47,32 @@ export interface Env {
    */
   CHANNEL_REGISTRY_DO: DurableObjectNamespace;
   /**
-   * D1 database backing persistent SASL account credentials. The `accounts`
-   * table holds scrypt-hashed rows (`{ account PK, algorithm, salt, hash }`),
-   * loaded at {@link ConnectionDO} construction by `loadD1AccountStore`.
+   * 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
+   * `nickserv_accounts` table holds scrypt-hashed credential rows, loaded at
+   * {@link ConnectionDO} construction by `loadD1ServicesStore`.
    *
-   * Optional so deployments that have not migrated to D1 keep working: when
-   * unset, the precedence resolver falls straight through to the
-   * `SASL_ACCOUNTS` env-var seed (the legacy `InMemoryAccountStore`).
+   * Optional: when unset, services are unbound (no NickServ routing, no
+   * SASL/PASS credential verify).
    */
   ACCOUNTS_DB?: D1Database;
   /** Server-level config knobs (name, MOTD lines, limits). */
@@ -71,10 +90,11 @@ export interface Env {
   CREATED_AT?: string;
   MOTD_LINES: string;
   /**
-   * SASL PLAIN accounts seeded into the in-worker `AccountStore`.
-   * Newline-delimited `username:password` pairs; the connection-do parses
-   * these into an `InMemoryAccountStore` so `AUTHENTICATE PLAIN` works
-   * end-to-end. Empty/undefined disables SASL account verification.
+   * SASL PLAIN seed accounts. Newline-delimited `username:password` pairs;
+   * the connection-do ingests these into the `ServicesStore` at boot via
+   * `registerNick` (idempotent — existing registrations win) so
+   * `AUTHENTICATE PLAIN`, `PASS <nick>:<password>`, and NickServ `IDENTIFY`
+   * all verify for the listed accounts.
    */
   SASL_ACCOUNTS?: string;
   /**
@@ -97,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;
 }
 
 /**
@@ -142,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,13 +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 {
-  CREATE_ACCOUNTS_TABLE_SQL,
-  loadD1AccountStore,
-  putAccountCredential,
-  resolveAccountStore,
-} from './d1-account-store.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 };
+  }
+}