serverless-ircd 0.10.0 → 0.11.0

package/packages/irc-core/src/config.ts

@@ -18,18 +18,119 @@
 
 import { z } from 'zod';
 import { BUILD_DATE, PACKAGE_VERSION } from './build-info.js';
-import { DEFAULT_MULTILINE_MAX_BYTES } from './caps/capabilities.js';
+import { DEFAULT_MULTILINE_MAX_BYTES, DEFAULT_MULTILINE_MAX_ENTRIES } from './caps/capabilities.js';
+import type { OperCred } from './types.js';
+
+/**
+ * Narrows the schema's loose `{user, password?, salt?, hash?}` parse
+ * output into the discriminated {@link OperCred} union so the parsed
+ * config is directly assignable to `ServerConfig.operCreds`.
+ *
+ * When `password` is present the entry narrows to the legacy plaintext
+ * shape; otherwise the entry narrows to the hashed shape. The
+ * {@link OperCredSchema} `superRefine` guarantees exactly one of the two
+ * arms holds for any input that reaches parse success; the `?? ''`
+ * fallbacks below are defensive only (unreachable through
+ * `parseServerConfig`) and exist so the helper is total.
+ */
+export function narrowOperCred(data: {
+  user: string;
+  password?: string | undefined;
+  salt?: string | undefined;
+  hash?: string | undefined;
+}): OperCred {
+  if (data.password !== undefined) {
+    return { user: data.user, password: data.password };
+  }
+  return {
+    user: data.user,
+    salt: data.salt ?? '',
+    hash: data.hash ?? '',
+  };
+}
 
 /**
  * Schema for a single IRC operator credential.
  *
- * Both fields are non-empty strings; the adapter is responsible for any
- * hashing/constant-time comparison at the OPER auth boundary.
+ * Accepts EITHER the at-rest hashed form (`{ user, salt, hash }`,
+ * recommended) OR the legacy plaintext form (`{ user, password }`,
+ * deprecated). The two shapes are mutually exclusive: a credential that
+ * supplies both `password` and `{salt, hash}` is rejected so operators
+ * cannot accidentally configure an ambiguous credential. The OPER auth
+ * path consults whichever shape is present.
+ *
+ * The plaintext form is DEPRECATED: retained for a single
+ * deprecation-cycle window so deployments can rotate to the hashed form
+ * without downtime. Adapters and `OPER` authentication still verify it,
+ * but emit a one-shot `warn` per boot when it is encountered. Migrate
+ * via `tools/hash-oper-cred.ts`; the plaintext form will be removed in a
+ * future release.
+ *
+ * Implemented as a unified object schema with `superRefine` rather than
+ * `z.union` so the rejection error messages name the offending field
+ * (Zod unions emit a generic "Invalid input" that hides which half is
+ * malformed). The trailing {@link narrowOperCred} transform narrows the
+ * loose parse output back into the {@link OperCred} union so
+ * `ParsedServerConfig.operCreds` is assignable to `ServerConfig`.
  */
-export const OperCredSchema = z.object({
-  user: z.string().min(1),
-  password: z.string().min(1),
-});
+export const OperCredSchema = z
+  .object({
+    user: z.string().min(1),
+    password: z.string().min(1).optional(),
+    salt: z.string().min(1).optional(),
+    hash: z.string().min(1).optional(),
+  })
+  .superRefine((data, ctx) => {
+    const hasPassword = data.password !== undefined;
+    const hasSalt = data.salt !== undefined;
+    const hasHash = data.hash !== undefined;
+
+    // The plaintext form requires `password` and forbids `salt`/`hash`.
+    // The hashed form requires BOTH `salt` and `hash` and forbids
+    // `password`. Anything else is ambiguous and rejected with a
+    // field-named error so operators can fix the config without
+    // round-tripping through Zod's error tree.
+    if (hasPassword && (hasSalt || hasHash)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          'Oper cred must be either {user,password} (legacy plaintext) or {user,salt,hash} (hashed), not a mix',
+        path: ['password'],
+      });
+      return;
+    }
+    if (!hasPassword && !(hasSalt && hasHash)) {
+      // Either salt or hash (or both) is missing on the hashed arm.
+      if (!hasSalt) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            'Required for the hashed form (or supply `password` for the legacy plaintext form)',
+          path: ['salt'],
+        });
+      }
+      if (!hasHash) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            'Required for the hashed form (or supply `password` for the legacy plaintext form)',
+          path: ['hash'],
+        });
+      }
+      if (!hasSalt && !hasHash) {
+        // Neither salt nor hash AND no password: the cred is missing
+        // every authentication field. Surface `password` so operators
+        // coming from the legacy schema see the familiar error.
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            'Required for the legacy plaintext form (or supply `salt` + `hash` for the hashed form)',
+          path: ['password'],
+        });
+      }
+    }
+  })
+  .transform(narrowOperCred);
 
 /**
  * Schema for a single SASL PLAIN account credential. The `username` is also
@@ -142,6 +243,22 @@ export const DEFAULT_FLOOD_CONTROL_CONFIG: {
   disconnectThreshold: 0,
 };
 
+/**
+ * Default number of consecutive failed `OPER` attempts (from one source
+ * host, within {@link DEFAULT_OPER_FAILURE_WINDOW_SECONDS}) before the
+ * per-IP lockout gate starts rejecting `OPER` with `491 ERR_NOOPERHOST`
+ * without consulting the credential store. Overridable per deployment via
+ * `ServerConfig.oper.maxFailures`.
+ */
+export const DEFAULT_OPER_MAX_FAILURES = 3;
+
+/**
+ * Default sliding window (seconds) for the per-IP failed-`OPER` counter.
+ * Failures older than the window no longer count towards the lockout.
+ * Overridable per deployment via `ServerConfig.oper.failureWindowSeconds`.
+ */
+export const DEFAULT_OPER_FAILURE_WINDOW_SECONDS = 300;
+
 /**
  * Default server version surfaced in `002`/`004`/`351`/`371` when a deployment
  * does not supply one. Sourced from `irc-core/package.json` at build time via
@@ -182,12 +299,130 @@ export const DEFAULT_NICK_ENFORCE_GRACE_MS = 30_000;
  */
 export const DEFAULT_MIN_PASSWORD_LENGTH = 8;
 
+/**
+ * Default number of failed `AUTHENTICATE` attempts (per connection, within
+ * the sliding failure window) before the SASL reducer disconnects the
+ * connection. Overridable per deployment via
+ * `ServerConfig.sasl.maxFailures`.
+ */
+export const DEFAULT_SASL_MAX_FAILURES = 3;
+
+/**
+ * Default sliding-window length (seconds) the SASL failure tracker counts
+ * within; older failures no longer count toward the lockout. Overridable per
+ * deployment via `ServerConfig.sasl.failureWindowSeconds`.
+ */
+export const DEFAULT_SASL_FAILURE_WINDOW_SECONDS = 60;
+
+/**
+ * Default failed-IDENTIFY threshold that freezes a NickServ account.
+ * After this many failed `IDENTIFY` attempts against one registered nick
+ * inside the freeze window, further attempts are rejected with a freeze
+ * notice BEFORE the scrypt verification runs. Overridable per deployment
+ * via `ServerConfig.nickServ.maxIdentifyFailures`.
+ */
+export const DEFAULT_MAX_IDENTIFY_FAILURES = 5;
+
+/**
+ * Default identify-freeze window (seconds). Failed `IDENTIFY` attempts
+ * older than this window stop counting towards the freeze (sliding
+ * window), so the freeze lifts once the failures age out. Overridable per
+ * deployment via `ServerConfig.nickServ.identifyFreezeSeconds`.
+ */
+export const DEFAULT_IDENTIFY_FREEZE_SECONDS = 300;
+
+/**
+ * Default ceiling for the per-connection inbound frame window enforced
+ * at the adapter boundary (see `frame-rate-limit.ts`). Overridable per
+ * deployment via `ServerConfig.adapter.maxFramesPerWindow`.
+ */
+export const DEFAULT_MAX_FRAMES_PER_WINDOW = 50;
+
+/**
+ * Default sliding-window length (seconds) for the per-connection inbound
+ * frame limit at the adapter boundary. Frames older than the window stop
+ * counting, so a connection that pauses longer than the window starts
+ * fresh. Overridable per deployment via
+ * `ServerConfig.adapter.frameWindowSeconds`.
+ */
+export const DEFAULT_FRAME_WINDOW_SECONDS = 5;
+
+/**
+ * Default ceiling for a client-supplied `CHATHISTORY` limit. A request
+ * like `CHATHISTORY LATEST #chan * 999999999` is silently capped at this
+ * many messages so a future higher-capacity `MessageStore` cannot be
+ * tricked into materializing a huge result set. Overridable per
+ * deployment via `ServerConfig.chathistory.maxLimit`.
+ */
+export const DEFAULT_MAX_CHATHISTORY_LIMIT = 100;
+
+/**
+ * `draft/chathistory` tunables. The client-supplied query limit is
+ * silently capped at `maxLimit`; the cap guards the `MessageStore.query`
+ * seam against oversized materialization regardless of the store's
+ * backing capacity.
+ */
+export const ChathistoryConfigSchema = z.object({
+  /**
+   * Maximum number of messages one `CHATHISTORY` query may return.
+   * Defaults to {@link DEFAULT_MAX_CHATHISTORY_LIMIT} (100).
+   */
+  maxLimit: z.number().int().positive().default(DEFAULT_MAX_CHATHISTORY_LIMIT),
+});
+
+/**
+ * Adapter-boundary tunables. These knobs are consumed by the adapters'
+ * inbound-frame gates (the CF Durable Object's `webSocketMessage` and the
+ * AWS `$default` handler) — NOT by the reducers — so they live in their
+ * own section rather than on the reducer-facing limit list. The
+ * per-connection frame window fires BEFORE the actor / storage write,
+ * compounding the in-actor flood control with a hard cost ceiling.
+ */
+export const AdapterConfigSchema = z.object({
+  /**
+   * Maximum inbound frames one connection may deliver inside the sliding
+   * window before the adapter closes it with RFC 6455 close code 1008
+   * after an `ERROR :Closing link (flooding)` line. Defaults to
+   * {@link DEFAULT_MAX_FRAMES_PER_WINDOW} (50).
+   */
+  maxFramesPerWindow: z.number().int().positive().default(DEFAULT_MAX_FRAMES_PER_WINDOW),
+  /**
+   * Sliding-window length in seconds. Defaults to
+   * {@link DEFAULT_FRAME_WINDOW_SECONDS} (5).
+   */
+  frameWindowSeconds: z.number().int().positive().default(DEFAULT_FRAME_WINDOW_SECONDS),
+});
+
+/**
+ * Per-IP failed-`OPER` lockout tunables. After `maxFailures` credential
+ * failures from one source host within `failureWindowSeconds`, further
+ * `OPER` attempts from that host are rejected with `491 ERR_NOOPERHOST`
+ * before the credential store is consulted (online brute-force throttle).
+ */
+export const OperThrottleConfigSchema = z.object({
+  /**
+   * Consecutive failed `OPER` attempts (per host, per window) that trip
+   * the lockout. Defaults to {@link DEFAULT_OPER_MAX_FAILURES} (3).
+   */
+  maxFailures: z.number().int().positive().default(DEFAULT_OPER_MAX_FAILURES),
+  /**
+   * Sliding window length in seconds. Failures older than the window no
+   * longer count. Defaults to {@link DEFAULT_OPER_FAILURE_WINDOW_SECONDS}
+   * (300).
+   */
+  failureWindowSeconds: z.number().int().positive().default(DEFAULT_OPER_FAILURE_WINDOW_SECONDS),
+});
+
 /**
  * The full server-config schema. Optional fields default to deployment-
  * sensible values so a minimal `{ serverName, networkName }` config is
  * enough to boot; production deployments override the defaults.
+ *
+ * Composed as a plain object schema that the exported
+ * {@link ServerConfigSchema} wraps with cross-field refinements (the
+ * HostServ auto-approve allowlist boot guard).
  */
-export const ServerConfigSchema = z.object({
+const ServerConfigSchemaObject = z.object({
   /** Server hostname shown in numerics (`:serverName 001 nick ...`). */
   serverName: z.string().min(1),
   /** Network name advertised in `005 NETWORK=...` and WHOIS replies. */
@@ -279,6 +514,15 @@ export const ServerConfigSchema = z.object({
    */
   operCreds: z.array(OperCredSchema).default([]),
 
+  /**
+   * Per-IP failed-`OPER` lockout tunables (online brute-force throttle).
+   * Omit entirely to inherit the documented defaults (3 failures / 300s).
+   */
+  oper: OperThrottleConfigSchema.default({
+    maxFailures: DEFAULT_OPER_MAX_FAILURES,
+    failureWindowSeconds: DEFAULT_OPER_FAILURE_WINDOW_SECONDS,
+  }),
+
   /**
    * SASL PLAIN seed credentials. The adapter ingests these into the
    * `ServicesStore` at boot via `registerNick` (idempotent — existing
@@ -336,6 +580,14 @@ export const ServerConfigSchema = z.object({
    */
   multilineMaxBytes: z.number().int().positive().default(DEFAULT_MULTILINE_MAX_BYTES),
 
+  /**
+   * Per-batch entry ceiling for IRCv3 `draft/multiline`, enforced
+   * incrementally on each accumulated inner line (defense-in-depth against
+   * a client that streams many tiny lines and never closes the batch).
+   * Defaults to {@link DEFAULT_MULTILINE_MAX_ENTRIES} (100).
+   */
+  multilineMaxEntries: z.number().int().positive().default(DEFAULT_MULTILINE_MAX_ENTRIES),
+
   /**
    * Per-connection MONITOR watchlist ceiling, advertised as `MONITOR=<n>`
    * in `005 RPL_ISUPPORT`. Omit to inherit the monitor reducer's built-in
@@ -366,10 +618,10 @@ export const ServerConfigSchema = z.object({
   nickEnforceGraceMs: z.number().int().nonnegative().optional(),
 
   /**
-   * NickServ-specific tunables. Currently only the minimum length enforced
-   * by `SET PASSWORD` is configurable; the maximum (256) is fixed to bound
-   * the scrypt input budget. Omit entirely to inherit the documented
-   * defaults.
+   * NickServ-specific tunables. The minimum length enforced by
+   * `SET PASSWORD` and the IDENTIFY freeze thresholds are configurable;
+   * the password maximum (256) is fixed to bound the scrypt input
+   * budget. Omit entirely to inherit the documented defaults.
    */
   nickServ: z
     .object({
@@ -380,20 +632,141 @@ export const ServerConfigSchema = z.object({
        * with `Password is too short (minimum <n> characters).`.
        */
       minPasswordLength: z.number().int().positive().optional(),
+      /**
+       * Failed-IDENTIFY threshold that freezes the account. After this
+       * many failed `IDENTIFY` attempts against one registered nick
+       * within {@link identifyFreezeSeconds}, further attempts are
+       * rejected with a freeze notice before scrypt runs. Defaults to
+       * {@link DEFAULT_MAX_IDENTIFY_FAILURES} (5) when unset.
+       */
+      maxIdentifyFailures: z.number().int().positive().optional(),
+      /**
+       * Sliding window (seconds) the failed-IDENTIFY threshold counts
+       * within. Failures older than the window stop counting, so the
+       * freeze lifts once they age out. Defaults to
+       * {@link DEFAULT_IDENTIFY_FREEZE_SECONDS} (300) when unset.
+       */
+      identifyFreezeSeconds: z.number().int().positive().optional(),
     })
     .optional(),
 
   /**
-   * HostServ approval mode for `REQUEST <vhost>`. `true` (the default)
-   * preserves the legacy auto-approve behaviour — the requested vhost is
-   * recorded against the account immediately (no oper review). `false`
-   * switches HostServ into oper-queue mode: `REQUEST` records a pending
-   * request that an oper must `APPROVE` (or `REJECT`) via HostServ. The
-   * queue + the `APPROVE` / `REJECT` / `LIST` (oper-only) commands are
-   * available in either mode, but only `false` routes `REQUEST` through
-   * them.
+   * SASL brute-force hardening tunables. The SASL reducer disconnects a
+   * connection after `maxFailures` failed `AUTHENTICATE` attempts within
+   * `failureWindowSeconds` (a sliding window; a successful login resets
+   * the count). Omit entirely (or omit either knob) to inherit the
+   * documented defaults (3 failures / 60 s).
+   */
+  sasl: z
+    .object({
+      /**
+       * Failed `AUTHENTICATE` attempts (per connection, within the
+       * window) before the connection is disconnected with
+       * `ERROR :Closing link: too many failed SASL attempts`. Defaults to
+       * {@link DEFAULT_SASL_MAX_FAILURES} (3) when unset.
+       */
+      maxFailures: z.number().int().positive().optional(),
+      /**
+       * Sliding-window length (seconds) the failure tracker counts
+       * within. Failures older than the window no longer count. Defaults
+       * to {@link DEFAULT_SASL_FAILURE_WINDOW_SECONDS} (60) when unset.
+       */
+      failureWindowSeconds: z.number().int().positive().optional(),
+      /**
+       * Operator opt-in for the certificate-backed SASL EXTERNAL
+       * mechanism. Unset (the default) keeps EXTERNAL off: the mechanism
+       * is neither advertised in the `sasl` cap / `908 ERR_SASLMECHS`
+       * list nor accepted by `AUTHENTICATE EXTERNAL`, so deployments
+       * that have not wired edge mTLS (CF API Shield / AWS APIGW
+       * client certs) never see half-configured exchanges. Enabling
+       * requires all three of: this flag, a bound mTLS identity source,
+       * and a secure (TLS) connection — see the SASL reducer.
+       *
+       * The adapters surface this as the `EXTERNAL_ENABLED` env var
+       * ('true'/'1' to enable). Accounts opt into EXTERNAL per-binding
+       * (cert fingerprint / subject DN on the NickServ record), not via
+       * this flag.
+       */
+      externalEnabled: z.boolean().optional(),
+      /**
+       * Transport-level EXTERNAL non-support override (see
+       * `SaslConfig.externalUnsupportedMessage`): when set, the
+       * deployment's transport cannot surface a client-cert identity,
+       * so `AUTHENTICATE EXTERNAL` is rejected up front with a
+       * `904 ERR_SASLFAIL` carrying this message and the mechanism is
+       * never advertised. Takes precedence over `externalEnabled`.
+       */
+      externalUnsupportedMessage: z.string().min(1).optional(),
+    })
+    .optional(),
+
+  /**
+   * Adapter-boundary tunables (inbound frame-rate window). Omit entirely
+   * to inherit the documented defaults (50 frames / 5 s).
+   */
+  adapter: AdapterConfigSchema.default({
+    maxFramesPerWindow: DEFAULT_MAX_FRAMES_PER_WINDOW,
+    frameWindowSeconds: DEFAULT_FRAME_WINDOW_SECONDS,
+  }),
+
+  /**
+   * `draft/chathistory` tunables (client-supplied limit ceiling). Omit
+   * entirely to inherit the documented default (100).
+   */
+  chathistory: ChathistoryConfigSchema.default({
+    maxLimit: DEFAULT_MAX_CHATHISTORY_LIMIT,
+  }),
+
+  /**
+   * HostServ approval mode for `REQUEST <vhost>`. `false` (the default) is
+   * oper-queue mode: `REQUEST` records a pending request that an oper must
+   * `APPROVE` (or `REJECT`) via HostServ — this is the recommended (and
+   * long-term only) mode. `true` preserves the legacy auto-approve
+   * behaviour — the requested vhost is recorded against the account
+   * immediately (no oper review).
+   *
+   * Auto-approve is hard-constrained for security: a non-empty
+   * {@link hostservAutoApproveAllowlist} MUST accompany `true` or config
+   * parsing fails at boot, and every auto-approved vhost must still clear
+   * the built-in denylist (reserved labels + this server's own hostname).
+   *
+   * @deprecated Auto-approve is deprecated. Queue mode (`false`, the
+   *   default) is the long-term path; a future release will remove the
+   *   auto-approve arm entirely. Migrate deployments to oper review.
    */
   hostservAutoApproveVhosts: z.boolean().default(false),
+
+  /**
+   * Explicit allowlist constraining which vhosts HostServ may auto-approve
+   * when {@link hostservAutoApproveVhosts} is `true`. An entry is either an
+   * exact hostname (`users.example.com`) or a wildcard suffix
+   * (`*.users.example.com`, matching any depth beneath it but not the bare
+   * suffix). Matching is case-insensitive.
+   *
+   * Ignored in queue mode (opers vet requests themselves). Required and
+   * non-empty when auto-approve is enabled — parsing fails at boot
+   * otherwise, because an unconstrained allowlist would let any identified
+   * user self-assign arbitrary hostnames.
+   */
+  hostservAutoApproveAllowlist: z.array(z.string().min(1)).default([]),
+});
+
+/**
+ * Cross-field boot guard: auto-approve mode must declare a non-empty
+ * vhost allowlist. Applied at the schema level so every adapter's
+ * `parseServerConfig` boot path refuses the combination with a clear,
+ * field-named error instead of silently running an unconstrained
+ * auto-approver.
+ */
+export const ServerConfigSchema = ServerConfigSchemaObject.superRefine((data, ctx) => {
+  if (data.hostservAutoApproveVhosts === true && data.hostservAutoApproveAllowlist.length === 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message:
+        'Required and must be non-empty when hostservAutoApproveVhosts is true (auto-approve without an allowlist would let any identified user self-assign arbitrary vhosts); prefer queue mode (hostservAutoApproveVhosts: false)',
+      path: ['hostservAutoApproveAllowlist'],
+    });
+  }
 });
 
 /** Input type: what adapters supply (fields with defaults may be omitted). */

package/packages/irc-core/src/effects.ts

@@ -132,6 +132,24 @@ export interface BroadcastWallopsEffect {
   except?: ConnId;
 }
 
+/**
+ * Oper-only notice fanout. Emitted by the OPER reducer's per-IP lockout
+ * gate (`:<server> NOTICE * :OPER lockout triggered for <host>`) so every
+ * online operator learns a brute-force attempt is being throttled.
+ *
+ * Like {@link BroadcastWallopsEffect} this is global cross-connection
+ * fanout (not channel-scoped), but the recipient gate is user mode `+o`
+ * rather than `+w`: the bound runtime's `broadcastOperNotice` method owns
+ * the enumeration (in-memory: scan of the connection map; CF: registry
+ * shard walk; AWS: `Connections` table scan) and filters on
+ * `userModes.oper`.
+ */
+export interface BroadcastOperNoticeEffect {
+  tag: 'BroadcastOperNotice';
+  lines: RawLine[];
+  except?: ConnId;
+}
+
 /**
  * NickServ nick-enforcement directive.
  *
@@ -176,6 +194,7 @@ export type Effect =
   | ApplyChannelDeltaEffect
   | SendToNickEffect
   | BroadcastWallopsEffect
+  | BroadcastOperNoticeEffect
   | EnforceNickEffect;
 
 /** Literal string tag of every {@link Effect} variant. */
@@ -245,6 +264,11 @@ export const Effect = {
     if (except !== undefined) e.except = except;
     return e;
   },
+  broadcastOperNotice(lines: RawLine[], except?: ConnId): Effect {
+    const e: BroadcastOperNoticeEffect = { tag: 'BroadcastOperNotice', lines };
+    if (except !== undefined) e.except = except;
+    return e;
+  },
   enforceNick(
     conn: ConnId,
     nick: Nick,

package/packages/irc-core/src/flood-control.ts

@@ -54,7 +54,8 @@ export interface FloodControlConfig {
    * When omitted, every command is charged the flat {@link MESSAGE_COST}
    * (`1`) — i.e. the original wrapper behaviour is preserved bit-for-bit.
    * Compose with {@link defaultCommandCost} to exempt control-plane
-   * traffic (`PING`/`PONG`/`CAP`/`AUTHENTICATE`/`QUIT`).
+   * traffic (`PING`/`PONG`/`CAP`/`QUIT`; `AUTHENTICATE` is charged — see
+   * {@link EXEMPT_COMMANDS}).
    *
    * A cost of `0` neither decrements the bucket nor triggers the disconnect
    * path; the inner reducer is called as normal. Negative costs are rejected
@@ -66,18 +67,17 @@ export interface FloodControlConfig {
 /**
  * Control-plane commands that mainstream ircds (charybdis, hybrid, Unreal) exempt
  * from flood control. A client exchanging `PING`/`PONG` with the server or
- * negotiating `CAP` / `AUTHENTICATE` during SASL must not flood itself out
- * through no fault of its own.
+ * negotiating `CAP` during registration must not flood itself out through no
+ * fault of its own.
+ *
+ * `AUTHENTICATE` is deliberately NOT exempt: SASL attempts consume the
+ * normal bucket so an in-connection SASL brute force is rate-limited by
+ * the same token bucket as every other command. The SASL reducer layers a
+ * per-connection failed-attempt lockout on top (see `commands/sasl.ts`).
  *
  * Override the set by composing your own cost function on top of this one.
  */
-const EXEMPT_COMMANDS: ReadonlySet<string> = new Set([
-  'PING',
-  'PONG',
-  'CAP',
-  'AUTHENTICATE',
-  'QUIT',
-]);
+const EXEMPT_COMMANDS: ReadonlySet<string> = new Set(['PING', 'PONG', 'CAP', 'QUIT']);
 
 /**
  * Ready-made per-command cost: `0` for the exempt control-plane set, `1`

package/packages/irc-core/src/frame-rate-limit.ts

@@ -0,0 +1,82 @@
+/**
+ * Per-connection inbound frame-rate window for the adapter boundary.
+ *
+ * Client-side flood control (the token bucket in `flood-control.ts`)
+ * lives in the actor and only fires AFTER the frame has been parsed and
+ * dispatched — which on the serverless adapters means the frame has
+ * already cost a Durable Object storage write (Cloudflare) or a DynamoDB
+ * write (AWS). This module is the cheaper, earlier gate: a pure
+ * sliding-window admission decision the adapters consult BEFORE invoking
+ * the actor, so a hostile client spamming low-cost commands is cut off at
+ * the connection boundary instead of driving outsized storage cost.
+ *
+ * Semantics: a connection may deliver at most `maxFrames` frames inside
+ * any sliding `windowMs` window. Timestamps older than the window decay
+ * out lazily (they stop counting as soon as `now - t >= windowMs`), so a
+ * connection that pauses longer than the window starts fresh. The frame
+ * that would exceed the budget is rejected — the caller closes the
+ * connection with RFC 6455 close code 1008 (Policy Violation) after
+ * delivering the canonical `ERROR :Closing link (flooding)` line.
+ *
+ * Determinism invariant: the decision is a pure function of
+ * `(times, now, maxFrames, windowMs)`; the caller owns the timestamp
+ * list (in-memory on the CF Durable Object, persisted on the AWS
+ * Connections row) and the clock.
+ */
+
+/**
+ * RFC 6455 close code used when the inbound frame window is exceeded
+ * (Policy Violation).
+ */
+export const FRAME_FLOOD_CLOSE_CODE = 1008;
+
+/**
+ * The `ERROR` line delivered to the client just before the flood close,
+ * matching the canonical ircd convention for connection-level flood
+ * kills.
+ */
+export const FRAME_FLOOD_ERROR_LINE = 'ERROR :Closing link (flooding)';
+
+/** Result of {@link admitFrameWindow}. */
+export interface FrameWindowDecision {
+  /**
+   * `true` when the frame fits the window (the caller processes it);
+   * `false` when the window is full (the caller closes the connection).
+   */
+  readonly admitted: boolean;
+  /**
+   * The post-decision window state the caller should retain: the
+   * previous entries pruned of decayed timestamps, plus — when
+   * admitted — the current frame's `now` appended. Never mutated in
+   * place; a fresh array is returned on every call.
+   */
+  readonly times: number[];
+}
+
+/**
+ * Decides whether the frame arriving at `now` fits inside the
+ * `maxFrames`-per-`windowMs` sliding window.
+ *
+ * Entries with `t < now - windowMs` decay out first (an entry at exactly
+ * `now - windowMs` still counts — inclusive boundary, mirroring
+ * `AdmissionStats.recentAdmissions`). The decision then reduces to:
+ * if the pruned window already holds `maxFrames` entries, reject;
+ * otherwise admit and record `now`.
+ */
+export function admitFrameWindow(
+  times: readonly number[],
+  now: number,
+  maxFrames: number,
+  windowMs: number,
+): FrameWindowDecision {
+  const cutoff = now - windowMs;
+  const kept: number[] = [];
+  for (const t of times) {
+    if (t >= cutoff) kept.push(t);
+  }
+  if (kept.length >= maxFrames) {
+    return { admitted: false, times: kept };
+  }
+  kept.push(now);
+  return { admitted: true, times: kept };
+}

package/packages/irc-core/src/index.ts

@@ -10,20 +10,28 @@ export * from './caps/index.js';
 export * from './commands/index.js';
 export * from './effects.js';
 export * from './ports.js';
+export * from './certfp.js';
 export * from './credential-hashing.js';
 export * from './account-migration.js';
+export * from './oper-hashing.js';
 export * from './flood-control.js';
+export * from './frame-rate-limit.js';
 export * from './cloak.js';
 export * from './case-fold.js';
 export * from './ws-subprotocol.js';
 export * from './ws-framing.js';
 export * from './admission.js';
+export * from './oper-lockout.js';
 export * from './config.js';
 export type {
   BuildCtxOptions,
+  ChathistoryConfig,
   CloakingConfig,
   Ctx,
   OperCred,
+  OperCredHashed,
+  OperCredPlaintext,
+  OperThrottleConfig,
   Reducer,
   ReducerResult,
   ServerConfig,