serverless-ircd 0.9.0 → 0.11.0

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,19 +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,

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);
+  }
+}