serverless-ircd 0.10.0 → 0.11.0

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

@@ -0,0 +1,43 @@
+/**
+ * Pure helper for `tools/hash-oper-cred.ts`.
+ *
+ * Wraps {@link hashAccountCredential}'s scrypt derivation in the
+ * `{user, salt, hash}` shape the oper config consumes (see
+ * {@link OperCredSchema}). The CLI entry point (arg parsing, console
+ * output) lives in the tools script; this helper is side-effect-free
+ * and fully unit-testable, mirroring the
+ * `account-migration.ts` / `tools/migrate-accounts-to-services.ts`
+ * split.
+ */
+
+import { hashAccountCredential } from './credential-hashing.js';
+import type { OperCredHashed } from './types.js';
+
+export type { OperCredHashed };
+
+/**
+ * Hashes a plaintext oper `{user, password}` pair into the at-rest
+ * `{user, salt, hash}` shape operators paste into secrets.
+ *
+ * The `salt` is cryptographically random by default; pass `{ salt }`
+ * for deterministic test scenarios. The `hash` is scrypt-derived via
+ * {@link hashAccountCredential} (memory-hard, GPU-resistant) and both
+ * `salt` and `hash` are base64 strings safe to embed in JSON / env
+ * vars / wrangler secrets.
+ *
+ * Round-trips via {@link matchOperCred} (the OPER reducer's verify
+ * path) — the resulting {@link OperCredHashed} is directly assignable
+ * to the {@link OperCredSchema} array on `ServerConfig`.
+ */
+export function hashOperCredential(
+  user: string,
+  password: string,
+  opts?: { salt?: Uint8Array },
+): OperCredHashed {
+  const entry = hashAccountCredential(user, password, opts);
+  return {
+    user: entry.account,
+    salt: entry.salt,
+    hash: entry.hash,
+  };
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Per-IP failed-`OPER` counter — the failed-authentication counterpart of
+ * {@link AdmissionStats}.
+ *
+ * Online brute force against `OPER` is bounded by this sliding-window
+ * counter: once a single source host accumulates `oper.maxFailures`
+ * credential failures within `oper.failureWindowSeconds`, every further
+ * `OPER` from that host is rejected with `491 ERR_NOOPERHOST` before the
+ * credential store is consulted (see `commands/oper.ts`).
+ *
+ * Ownership + injection follows the {@link AdmissionStats} precedent: the
+ * runtime (in-memory reference runtime, local CLI) constructs exactly one
+ * instance per process and shares it across every connection via the
+ * `ctx.operFailures` port, so the counter is per-IP across the whole
+ * deployment rather than per-connection. The instance MUST be constructed
+ * with the same {@link Clock} the actors use so window arithmetic is
+ * coherent.
+ *
+ * Determinism: same Clock + same call stream → same answers. There are no
+ * ambient inputs (never `Date.now`).
+ */
+
+import type { Clock } from './ports.js';
+
+/** Per-IP failed-`OPER` counter owned by the runtime (sliding window). */
+export class OperFailureStats {
+  private readonly clock: Clock;
+  /**
+   * Per-IP timestamps of recent OPER credential failures, used by the
+   * lockout gate. Stored ascending; entries older than the queried window
+   * are pruned lazily (identical bookkeeping to `AdmissionStats`'
+   * `perIpAdmitTimes`).
+   */
+  private readonly failureTimes = new Map<string, number[]>();
+
+  constructor(clock: Clock) {
+    this.clock = clock;
+  }
+
+  /**
+   * Returns the number of `OPER` credential failures recorded for `ip`
+   * within the last `windowMs` milliseconds (inclusive of the moment
+   * returned by `clock.now()`). Stale entries are pruned as a side effect,
+   * so an IP whose every failure has expired drops out of the map
+   * entirely.
+   */
+  recentFailures(ip: string, windowMs: number): number {
+    const times = this.failureTimes.get(ip);
+    if (times === undefined) return 0;
+    const cutoff = this.clock.now() - windowMs;
+    let writeIdx = 0;
+    // `times` is dense (only ever appended to via push), so iterating
+    // values via for-of avoids the noUncheckedIndexedAccess trap while
+    // still allowing in-place compaction of stale entries.
+    for (const t of times) {
+      if (t >= cutoff) {
+        times[writeIdx++] = t;
+      }
+    }
+    if (writeIdx === 0) {
+      this.failureTimes.delete(ip);
+      return 0;
+    }
+    times.length = writeIdx;
+    return writeIdx;
+  }
+
+  /**
+   * Records one `OPER` credential failure for `ip`, stamped with the
+   * injected clock's current time. Called by the OPER reducer on the
+   * `464 ERR_PASSWDMISMATCH` path.
+   */
+  recordFailure(ip: string): void {
+    const times = this.failureTimes.get(ip) ?? [];
+    times.push(this.clock.now());
+    this.failureTimes.set(ip, times);
+  }
+
+  /**
+   * Clears every recorded failure for `ip`. Called by the OPER reducer on
+   * successful authentication so a legitimate oper's success never
+   * contributes to a later lockout.
+   */
+  reset(ip: string): void {
+    this.failureTimes.delete(ip);
+  }
+}