serverless-ircd 0.9.0 → 0.11.0

package/packages/irc-core/src/commands/oper.ts

@@ -16,6 +16,8 @@
  *   - `OPER <name> <password>` — authenticates and (on success) grants oper.
  *   - `381 RPL_YOUREOPER`:
  *     `:<server> 381 <nick> :You are now an IRC operator`
+ *   - `451 ERR_NOTREGISTERED`:
+ *     `:<server> 451 <nick> :You have not registered`
  *   - `461 ERR_NEEDMOREPARAMS`:
  *     `:<server> 461 <nick> OPER :Not enough parameters`
  *   - `464 ERR_PASSWDMISMATCH`:
@@ -24,25 +26,61 @@
  *     `:<server> 491 <nick> :No O-lines for your host`
  *
  * Behaviour:
+ *   - Connection not yet registered (`state.registration !==
+ *     'registered'`) → `451 ERR_NOTREGISTERED`, mirroring the SETNAME
+ *     gate. A pre-registration client has no nick yet, so an oper grant
+ *     here would produce an unattributable `nick === undefined` oper
+ *     (WHOIS/audit hostmasks degrade); the gate also keeps the lockout
+ *     counters and credential store untouched for unregistered callers.
  *   - Missing `<name>` or `<password>` → `461 ERR_NEEDMOREPARAMS`.
  *   - Already an operator → graceful idempotent no-op that re-confirms with
  *     `381` (no re-authentication required; the connection is already privy).
  *     No `MODE` echo is emitted because the user mode did not change.
  *   - No operator credentials configured (absent or empty) →
  *     `491 ERR_NOOPERHOST`.
+ *   - Per-IP lockout tripped (see below) → `491 ERR_NOOPERHOST` WITHOUT
+ *     consulting the credential store, plus a `BroadcastOperNotice` effect
+ *     (`:<server> NOTICE * :OPER lockout triggered for <host>`) so every
+ *     online oper learns a brute-force attempt is being throttled.
  *   - Matching credential pair → grant oper, emit `381`, then emit a
  *     `:<hostmask> MODE <nick> +o` notification to the connection so the
  *     client learns its user mode changed (mirrors the user `MODE` echo).
  *   - Wrong password / unknown name → `464 ERR_PASSWDMISMATCH`.
+ *
+ * Brute-force throttle (per-IP lockout):
+ *   When a `ctx.operFailures` tracker is bound (the runtime owns one
+ *   shared counter, `AdmissionStats`-style), every `464` records a
+ *   failure for the connection's source host and every success resets it.
+ *   Once `serverConfig.oper.maxFailures` failures (default 3) accumulate
+ *   within `oper.failureWindowSeconds` (default 300s), subsequent `OPER`
+ *   from that host are short-circuited above — the credential store (and
+ *   its scrypt cost) is never consulted for a locked-out host, so online
+ *   guessing is capped at maxFailures attempts per window per host.
+ *
+ *   Lockout key: `state.host`. `ConnectionState` carries no dedicated IP
+ *   field; transports stamp the peer address into `host` at connect time
+ *   (AWS NLB / raw TCP supply the source IP verbatim). With cloaking
+ *   enabled `host` holds the deterministic cloak — a pure function of the
+ *   real IP — so per-IP grouping still holds; a HostServ vhost active on
+ *   the connection re-keys that one connection. A connection with no host
+ *   set is never tracked (no key → no counter → the credential gate alone
+ *   applies).
  */
 
+import { timingSafeEqual } from 'node:crypto';
+import { DEFAULT_OPER_FAILURE_WINDOW_SECONDS, DEFAULT_OPER_MAX_FAILURES } from '../config.js';
+import {
+  type HashedAccountCredential,
+  hashAccountCredential,
+  verifyHashedPassword,
+} from '../credential-hashing.js';
 import { Effect } from '../effects.js';
 import type { RawLine } from '../effects.js';
 import { Numerics } from '../protocol/numerics.js';
 import { hostmaskOf } from '../state/connection.js';
 import type { ConnectionState } from '../state/connection.js';
-import type { OperCred } from '../types.js';
-import type { Ctx, Reducer } from '../types.js';
+import type { OperCred, OperCredHashed, OperCredPlaintext } from '../types.js';
+import type { Ctx, Reducer, ReducerResult } from '../types.js';
 
 /** Fixed text emitted for `381 RPL_YOUREOPER`. */
 const YOUREOPER_TRAILING_TEXT = 'You are now an IRC operator';
@@ -56,18 +94,235 @@ const NOOPERHOST_TRAILING_TEXT = 'No O-lines for your host';
 /** Fixed text emitted for `461 ERR_NEEDMOREPARAMS`. */
 const NEEDMOREPARAMS_TRAILING_TEXT = 'Not enough parameters';
 
+/** Fixed text emitted for `451 ERR_NOTREGISTERED` (matches `SETNAME`). */
+const NOTREGISTERED_TRAILING_TEXT = 'You have not registered';
+
+/** Fixed prefix of the oper-notice broadcast when the lockout gate trips. */
+const OPER_LOCKOUT_NOTICE_PREFIX = 'OPER lockout triggered for';
+
+// ============================================================================
+// Hashed-oper credential verify — scrypt + timing-safe user compare.
+// ============================================================================
+
+/**
+ * Fixed salt used to bake the precomputed fixture entries below. 16 bytes
+ * of `0x42` so the resulting scrypt derivations are deterministic across
+ * Node versions and test runs (the salt is never used to verify real
+ * attacker traffic — only the fixture entries).
+ */
+const OPER_FIXTURE_SALT = new Uint8Array(16).fill(0x42);
+
+/**
+ * User name baked into the precomputed dummy hashed entry. Never matches a
+ * real oper name (contains a NUL) so the dummy verify never collides with
+ * a configured credential.
+ */
+const OPER_DUMMY_USER = '\u0000oper-timing-dummy';
+
+/**
+ * Plaintext password baked into the precomputed dummy hashed entry. Never
+ * matches a real oper password (contains a NUL) so the dummy verify always
+ * fails — its purpose is to spend the same scrypt work as the
+ * known-user-with-wrong-password path, NOT to authenticate.
+ */
+const OPER_DUMMY_PASSWORD = '\u0000oper-timing-dummy';
+
+/** User name baked into {@link OPER_PRECOMPUTED_HASHED_CRED}. */
+export const OPER_HASHED_USER = 'oper-hashed-fixture-user';
+
+/** Password that verifies against {@link OPER_PRECOMPUTED_HASHED_CRED}. */
+export const OPER_HASHED_VALID_PASSWORD = 'oper-hashed-fixture-password';
+
+/** Password that does NOT verify against {@link OPER_PRECOMPUTED_HASHED_CRED}. */
+export const OPER_HASHED_WRONG_PASSWORD = 'definitely-not-the-right-password';
+
+/**
+ * Fixed scrypt-hashed credential used to equalise timing on the
+ * user-unknown path. {@link matchOperCred} always invokes exactly one
+ * verify — against this entry when no configured user matches, or against
+ * the matching cred when one does — so a remote attacker cannot
+ * distinguish "user exists, wrong password" from "user unknown" via
+ * wall-clock cost. Mirrors the {@link PASS_AUTH_DUMMY_NICK} pattern in
+ * `account-auth.ts`.
+ */
+export const OPER_PRECOMPUTED_DUMMY_HASHED: HashedAccountCredential = hashAccountCredential(
+  OPER_DUMMY_USER,
+  OPER_DUMMY_PASSWORD,
+  {
+    salt: OPER_FIXTURE_SALT,
+  },
+);
+
+/**
+ * The precomputed hashed {@link OperCredHashed} used by tests to exercise
+ * the hashed-verify arm of {@link matchOperCred} deterministically without
+ * paying scrypt cost in the test fixture setup. The salt is fixed (the
+ * {@link OPER_FIXTURE_SALT} vector) so the resulting `hash` is stable
+ * across runs and Node versions; the password is
+ * {@link OPER_HASHED_VALID_PASSWORD}.
+ */
+export const OPER_PRECOMPUTED_HASHED_CRED: OperCredHashed = (() => {
+  const entry = hashAccountCredential(OPER_HASHED_USER, OPER_HASHED_VALID_PASSWORD, {
+    salt: OPER_FIXTURE_SALT,
+  });
+  return { user: entry.account, salt: entry.salt, hash: entry.hash };
+})();
+
+/**
+ * Type-narrowing predicate: true iff `cred` is the legacy plaintext shape.
+ */
+function isLegacyPlaintext(cred: OperCred): cred is OperCredPlaintext {
+  return (cred as OperCredPlaintext).password !== undefined;
+}
+
+/**
+ * Timing-safe byte-wise string comparison. Returns false immediately on
+ * length mismatch (the length is itself public — it is observable in the
+ * user-name field on the wire — so leaking it does not aid the attacker).
+ * For equal-length inputs every byte is compared via `timingSafeEqual`
+ * with no short-circuit.
+ */
+function timingSafeStringEqual(a: string, b: string): boolean {
+  const aBuf = Buffer.from(a, 'utf8');
+  const bBuf = Buffer.from(b, 'utf8');
+  if (aBuf.length !== bBuf.length) return false;
+  return timingSafeEqual(aBuf, bBuf);
+}
+
+/**
+ * Indirection over {@link verifyHashedPassword} so tests can swap in a
+ * stub to assert call counts (timing-equalisation test). Defaults to the
+ * real primitive; `null` restores the default.
+ */
+let verifyHashedPasswordFn: (password: string, entry: HashedAccountCredential) => boolean =
+  verifyHashedPassword;
+
+/**
+ * Test seam: replaces the verify primitive with `fn` (or restores the
+ * default when `fn === null`). Exported for tests; production callers
+ * MUST NOT use.
+ *
+ * @internal
+ */
+export function setOperVerifyHashedPassword(
+  fn: ((password: string, entry: HashedAccountCredential) => boolean) | null,
+): void {
+  verifyHashedPasswordFn = fn ?? verifyHashedPassword;
+}
+
+/** @internal test seam: clears any spy registered above. */
+export function resetOperTimingSpy(): void {
+  verifyHashedPasswordFn = verifyHashedPassword;
+}
+
+/**
+ * Per-boot flag guarding the legacy-plaintext deprecation warning so the
+ * message is emitted exactly once per process (the configured cred list
+ * rarely changes within a single boot, and per-call spam would drown the
+ * signal).
+ */
+let legacyPlaintextWarnEmitted = false;
+
+/**
+ * Default warner: `console.warn` on every platform the project ships
+ * (Node for Lambda / local-cli, `nodejs_compat` on Cloudflare Workers).
+ * `console.warn` is intentionally the sink rather than a structured
+ * logger because `matchOperCred` is a pure helper with no logger
+ * injection seam; adapters that want richer routing can wrap the boot
+ * config inspection separately.
+ */
+let operLegacyPlaintextWarner: (msg: string) => void = (msg) => {
+  console.warn(msg);
+};
+
+/** Fixed deprecation text emitted once per boot when a legacy cred is seen. */
+const LEGACY_PLAINTEXT_WARNING =
+  'Oper credentials configured in the deprecated {user,password} plaintext form. ' +
+  'Run tools/hash-oper-cred.ts to migrate to the scrypt-hashed {user,salt,hash} form ' +
+  'before the next release; the plaintext form will be removed.';
+
+/**
+ * @internal test seam: replaces the warner sink. Pass `null` to restore
+ * the default `console.warn` sink.
+ */
+export function setOperLegacyPlaintextWarner(fn: ((msg: string) => void) | null): void {
+  operLegacyPlaintextWarner =
+    fn ??
+    ((msg) => {
+      console.warn(msg);
+    });
+}
+
+/** @internal test seam: clears the per-boot warning flag. */
+export function resetOperLegacyPlaintextWarning(): void {
+  legacyPlaintextWarnEmitted = false;
+}
+
 /**
- * Returns true iff a credential pair in `creds` matches `name` / `password`
- * exactly. Extracted as a pure helper so the match logic is testable in
- * isolation and independent of connection state. Comparison is case
- * sensitive and byte-exact (case-mapping is owned elsewhere).
+ * Returns true iff a credential pair in `creds` matches `name` / `password`.
+ *
+ * Extracted as a pure helper so the match logic is testable in isolation
+ * and independent of connection state. Verification is timing-safe end to
+ * end:
+ *   - The `user` field is compared via `timingSafeEqual` byte-wise (with
+ *     a length precheck; the length is public on the wire).
+ *   - For the at-rest hashed form, the password is verified via the shared
+ *     {@link verifyHashedPassword} scrypt primitive (already
+ *     `timingSafeEqual`-based).
+ *   - For the deprecated legacy plaintext form, the password is verified
+ *     via `timingSafeEqual` byte-wise as well.
+ *   - When the user is unknown, a dummy scrypt verify runs against a
+ *     fixed precomputed entry ({@link OPER_PRECOMPUTED_DUMMY_HASHED}) so
+ *     the wall-clock cost is indistinguishable from the known-user path —
+ *     a remote attacker cannot enumerate oper names via timing.
+ *
+ * The legacy plaintext form triggers a one-shot `warn` per boot so
+ * operators notice and rotate; the deprecation cycle removes the form
+ * entirely in a future release.
  */
 export function matchOperCred(
   creds: ReadonlyArray<OperCred>,
   name: string,
   password: string,
 ): boolean {
-  return creds.some((c) => c.user === name && c.password === password);
+  // Locate the cred whose user matches `name` (timing-safe on the user
+  // field). Iterate the WHOLE list — never short-circuit on a match — so
+  // the iteration count does not leak which entry matched.
+  let candidate: OperCred | undefined;
+  let sawLegacyPlaintext = false;
+  for (const c of creds) {
+    if (isLegacyPlaintext(c)) sawLegacyPlaintext = true;
+    if (timingSafeStringEqual(c.user, name)) {
+      candidate = c;
+    }
+  }
+
+  if (sawLegacyPlaintext && !legacyPlaintextWarnEmitted) {
+    legacyPlaintextWarnEmitted = true;
+    operLegacyPlaintextWarner(LEGACY_PLAINTEXT_WARNING);
+  }
+
+  if (candidate === undefined) {
+    // Unknown user: equalise timing with a dummy scrypt verify against a
+    // fixed precomputed entry. The result is discarded; the cost is the
+    // point.
+    verifyHashedPasswordFn(password, OPER_PRECOMPUTED_DUMMY_HASHED);
+    return false;
+  }
+
+  if (!isLegacyPlaintext(candidate)) {
+    // At-rest hashed form: delegate to the shared scrypt verify.
+    const entry: HashedAccountCredential = {
+      account: candidate.user,
+      algorithm: 'scrypt',
+      salt: candidate.salt,
+      hash: candidate.hash,
+    };
+    return verifyHashedPasswordFn(password, entry);
+  }
+
+  // Legacy plaintext (deprecation cycle): timing-safe byte compare.
+  return timingSafeStringEqual(candidate.password, password);
 }
 
 /**
@@ -75,11 +330,27 @@ export function matchOperCred(
  *
  * Verifies the supplied pair against `serverConfig.operCreds` and, on
  * success, grants the oper user mode. Emits the appropriate numeric reply
- * in every branch. See the file header for the full decision table.
+ * in every branch. See the file header for the full decision table
+ * (including the per-IP brute-force lockout).
  */
 export const operReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
   state.lastSeen = ctx.clock.now();
 
+  // Registration gate (mirrors the SETNAME reducer): OPER is meaningless —
+  // and unattributable — before the welcome block. Runs first so a
+  // pre-registration caller never reaches the credential store, the
+  // lockout counters, or the oper-grant path.
+  if (state.registration !== 'registered') {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NOTREGISTERED, NOTREGISTERED_TRAILING_TEXT),
+        ]),
+      ],
+    };
+  }
+
   const name = msg.params[0];
   const password = msg.params[1];
 
@@ -95,6 +366,8 @@ export const operReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
   }
 
   // Already an operator: graceful idempotent re-confirm, no re-auth needed.
+  // Runs BEFORE the lockout gate — an authenticated oper never loses 381
+  // because a (possibly different) connection from their host is throttled.
   if (state.userModes.oper) {
     return {
       state,
@@ -106,6 +379,15 @@ export const operReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
     };
   }
 
+  // Per-IP brute-force gate: once the source host has exhausted its failure
+  // budget, reject without consulting the credential store and notify every
+  // oper. Runs before the creds-configured check so the locked-out path
+  // performs zero credential work of any kind.
+  const lockout = operLockoutResult(state, ctx);
+  if (lockout !== undefined) {
+    return lockout;
+  }
+
   const creds = ctx.serverConfig.operCreds;
   if (creds === undefined || creds.length === 0) {
     return {
@@ -120,6 +402,8 @@ export const operReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
 
   if (matchOperCred(creds, name, password)) {
     state.userModes.oper = true;
+    // A legitimate oper's success never contributes to a later lockout.
+    resetOperFailures(state, ctx);
     return {
       state,
       effects: [
@@ -131,6 +415,8 @@ export const operReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
     };
   }
 
+  // Credential failure: count it against the source host's budget.
+  recordOperFailure(state, ctx);
   return {
     state,
     effects: [
@@ -141,6 +427,73 @@ export const operReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
   };
 };
 
+/**
+ * Returns the lockout rejection ({@link ReducerResult}) when the source
+ * host has exhausted its failed-OPER budget, or `undefined` when the
+ * credential path should proceed. No-ops (returns `undefined`) when no
+ * tracker is bound, the connection has no host, or the in-window failure
+ * count is still below the configured threshold.
+ */
+function operLockoutResult(
+  state: ConnectionState,
+  ctx: Ctx,
+): ReducerResult<ConnectionState> | undefined {
+  const tracker = ctx.operFailures;
+  if (tracker === undefined) return undefined;
+  const key = state.host;
+  if (key === undefined) return undefined;
+
+  const { maxFailures, windowMs } = operLockoutThresholds(ctx);
+  if (tracker.recentFailures(key, windowMs) < maxFailures) return undefined;
+
+  return {
+    state,
+    effects: [
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NOOPERHOST, NOOPERHOST_TRAILING_TEXT),
+      ]),
+      Effect.broadcastOperNotice([operLockoutNoticeLine(ctx, key)]),
+    ],
+  };
+}
+
+/**
+ * Resolves the lockout thresholds from `serverConfig.oper`, falling back
+ * to the documented defaults when the config (or an individual field) is
+ * omitted.
+ */
+function operLockoutThresholds(ctx: Ctx): { maxFailures: number; windowMs: number } {
+  const cfg = ctx.serverConfig.oper;
+  const maxFailures = cfg?.maxFailures ?? DEFAULT_OPER_MAX_FAILURES;
+  const failureWindowSeconds = cfg?.failureWindowSeconds ?? DEFAULT_OPER_FAILURE_WINDOW_SECONDS;
+  return { maxFailures, windowMs: failureWindowSeconds * 1000 };
+}
+
+/**
+ * Builds the `:<server> NOTICE * :OPER lockout triggered for <host>` line
+ * fanned out to every oper. Target `*` (not a nick) because the notice is
+ * server-authored and addressed to the oper corps as a whole.
+ */
+function operLockoutNoticeLine(ctx: Ctx, host: string): RawLine {
+  return { text: `:${ctx.serverName} NOTICE * :${OPER_LOCKOUT_NOTICE_PREFIX} ${host}` };
+}
+
+/** Records a credential failure against the host's budget (no-op untracked). */
+function recordOperFailure(state: ConnectionState, ctx: Ctx): void {
+  const tracker = ctx.operFailures;
+  const key = state.host;
+  if (tracker === undefined || key === undefined) return;
+  tracker.recordFailure(key);
+}
+
+/** Clears the host's failure budget after a successful authentication. */
+function resetOperFailures(state: ConnectionState, ctx: Ctx): void {
+  const tracker = ctx.operFailures;
+  const key = state.host;
+  if (tracker === undefined || key === undefined) return;
+  tracker.reset(key);
+}
+
 /**
  * Builds a `:<server> <code> <nick> [<middle>] :<trailing>` line. The nick
  * falls back to `*` when the connection has not yet registered one, matching

package/packages/irc-core/src/commands/part.ts

@@ -8,26 +8,20 @@
  * `ctx.connection.joinedChannels` (the connection's joined list) are
  * expressed as effects / cross-authority mutations the actor layer persists.
  *
- * Multi-channel PART (`PART #a,#b :reason`) is split by the actor layer;
- * this reducer handles one channel per invocation.
+ * Multi-channel PART (`PART #a,#b :reason`) is split by the actor layer,
+ * which also enforces `maxTargetsPerCommand` (dropped channels get a
+ * `407 ERR_TOOMANYTARGETS`); this reducer handles one channel per invocation.
  */
 
 import { Effect } from '../effects.js';
 import type { Effect as EffectType, RawLine } from '../effects.js';
+import { isValidChannelName } from '../protocol/channel-name.js';
 import { Numerics } from '../protocol/numerics.js';
 import type { ChannelState } from '../state/channel.js';
 import { hostmaskOf } from '../state/connection.js';
 import type { ConnectionState } from '../state/connection.js';
 import type { Ctx, Reducer } from '../types.js';
 
-/** Channel-name validation mirrors JOIN: same grammar, same length cap. */
-const CHANNEL_NAME_RE = /^[#&][^\s,:]+$/u;
-
-function isValidChannelName(name: string, maxLen: number): boolean {
-  if (name.length === 0 || name.length > maxLen) return false;
-  return CHANNEL_NAME_RE.test(name);
-}
-
 /**
  * Formats a single numeric error line addressed to the connection's current
  * nick (or `*` when unregistered). Optional `middle` is emitted before the

package/packages/irc-core/src/commands/privmsg.ts

@@ -25,16 +25,20 @@
 
 import { Effect } from '../effects.js';
 import type { Effect as EffectType, RawLine } from '../effects.js';
+import { CHANNEL_NAME_RE } from '../protocol/channel-name.js';
 import { Numerics } from '../protocol/numerics.js';
 import type { ChannelState } from '../state/channel.js';
 import { hostmaskOf } from '../state/connection.js';
 import type { ConnectionState } from '../state/connection.js';
 import type { Ctx, Reducer } from '../types.js';
 
-/** Channel-name grammar; mirrors {@link isValidChannelName} in `join.ts`. */
-const CHANNEL_NAME_RE = /^[#&][^\s,:]+$/u;
-
-/** Returns true iff `name` looks like a channel target (vs. a nick target). */
+/**
+ * Returns true iff `name` looks like a channel target (vs. a nick target).
+ * Routing-only check against the shared channel-name grammar: it applies no
+ * byte-length cap, so an over-long `#name` still routes to the channel path
+ * (where the channel cannot exist) rather than silently becoming a nick
+ * message.
+ */
 function isChannelTarget(name: string): boolean {
   return CHANNEL_NAME_RE.test(name);
 }