serverless-ircd 0.1.0 → 0.2.0

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

@@ -0,0 +1,216 @@
+/**
+ * Connection-admission gate — pure policy + stateful counter.
+ *
+ * Guards the connection acceptance path against three classes of abuse:
+ *
+ *   1. **Per-IP connection cap** (`maxConnectionsPerIp`): caps how many
+ *      simultaneous connections a single source IP may hold. Distinct
+ *      from per-connection flood control: this is the "how many sockets
+ *.     at once" gate, not the "how many commands per socket" gate.
+ *
+ *   2. **Per-user connection cap** (`maxConnectionsPerUser`): same idea,
+ *      keyed by SASL account name when available, falling back to the
+ *      source IP when the connection has not authenticated.
+ *
+ *   3. **Per-IP connection-rate limit** (`perIpConnectionRate`): caps how
+ *      fast a single source IP may open new connections within a sliding
+ *      window. Defends against connection-flood attacks that recycle
+ *      sockets to evade the per-IP cap.
+ *
+ * The policy itself is a pure function {@link decideAdmission}; the
+ * accounting state lives in {@link AdmissionStats}, which is injected so
+ * tests can pin the timeline via {@link FakeClock} and inspect state in
+ * isolation. Both adapters (in-memory runtime, CF / AWS) construct one
+ * `AdmissionStats` per process / per worker invocation and share it
+ * across every connection acceptance decision.
+ *
+ * Determinism: same Clock + same call stream → same decisions. There are
+ * no ambient inputs.
+ */
+
+import type { Clock } from './ports.js';
+
+/**
+ * Static policy consulted by {@link decideAdmission}. Adapters source the
+ * values from `ServerConfig` but the gate consumes this narrow shape so
+ * the unit tests do not need to construct a full config.
+ */
+export interface AdmissionConfig {
+  /** Maximum simultaneous connections from a single source IP. */
+  readonly maxConnectionsPerIp: number;
+  /** Maximum simultaneous connections from a single authenticated user. */
+  readonly maxConnectionsPerUser: number;
+  /** Per-IP connection-rate limit (sliding window). */
+  readonly perIpConnectionRate: { readonly max: number; readonly windowMs: number };
+}
+
+/** Positive admission outcome — caller should {@link AdmissionStats.recordAdmission}. */
+export interface AdmitDecision {
+  readonly ok: true;
+  /**
+   * Opaque record id handed back to {@link AdmissionStats.release} when the
+   * connection terminates. Unique per admission.
+   */
+  readonly recordId: string;
+}
+
+/** Negative admission outcome — the caller MUST close the connection. */
+export interface RejectDecision {
+  readonly ok: false;
+  /** Machine-readable reason code for logs / metrics / `Disconnect` effect. */
+  readonly reason: AdmissionRejectReason;
+}
+
+export type AdmissionRejectReason =
+  | 'max_connections_per_ip'
+  | 'max_connections_per_user'
+  | 'rate_limited_per_ip';
+
+export type AdmissionDecision = AdmitDecision | RejectDecision;
+
+/** Per-IP / per-user / rate counters. Owned by the runtime / adapter. */
+export class AdmissionStats {
+  private readonly clock: Clock;
+  private readonly perIpCount = new Map<string, number>();
+  private readonly perUserCount = new Map<string, number>();
+  /**
+   * Per-IP timestamps of recent admissions, used by the rate-limit check.
+   * Stored ascending; entries older than the window are pruned lazily.
+   */
+  private readonly perIpAdmitTimes = new Map<string, number[]>();
+  /** Reverse index: recordId → { ip, user }, used by {@link release}. */
+  private readonly records = new Map<string, { ip: string; user: string }>();
+  private nextRecordId = 1;
+
+  constructor(clock: Clock) {
+    this.clock = clock;
+  }
+
+  /**
+   * Returns the current per-IP connection count. Exposed for diagnostics
+   * and tests; not used by {@link decideAdmission}.
+   */
+  countForIp(ip: string): number {
+    return this.perIpCount.get(ip) ?? 0;
+  }
+
+  /** Returns the current per-user connection count. */
+  countForUser(user: string): number {
+    return this.perUserCount.get(user) ?? 0;
+  }
+
+  /**
+   * Records an accepted admission. MUST be called exactly once per
+   * successful {@link decideAdmission} so the counters stay accurate.
+   */
+  recordAdmission(ip: string, user: string | undefined, recordId: string): void {
+    const effectiveUser = user ?? ip;
+    this.perIpCount.set(ip, (this.perIpCount.get(ip) ?? 0) + 1);
+    this.perUserCount.set(effectiveUser, (this.perUserCount.get(effectiveUser) ?? 0) + 1);
+    const now = this.clock.now();
+    const times = this.perIpAdmitTimes.get(ip) ?? [];
+    times.push(now);
+    this.perIpAdmitTimes.set(ip, times);
+    this.records.set(recordId, { ip, user: effectiveUser });
+  }
+
+  /**
+   * Releases a previously-recorded admission, decrementing the relevant
+   * counters. Idempotent: releasing an unknown id is a no-op.
+   */
+  release(recordId: string): void {
+    const rec = this.records.get(recordId);
+    if (rec === undefined) return;
+    this.records.delete(recordId);
+
+    const ipCount = this.perIpCount.get(rec.ip);
+    if (ipCount !== undefined) {
+      const next = ipCount - 1;
+      if (next <= 0) this.perIpCount.delete(rec.ip);
+      else this.perIpCount.set(rec.ip, next);
+    }
+    const userCount = this.perUserCount.get(rec.user);
+    if (userCount !== undefined) {
+      const next = userCount - 1;
+      if (next <= 0) this.perUserCount.delete(rec.user);
+      else this.perUserCount.set(rec.user, next);
+    }
+  }
+
+  /**
+   * Returns the number of admissions recorded for `ip` within the last
+   * `windowMs` milliseconds (inclusive of the moment returned by
+   * `clock.now()`). Stale entries are pruned as a side effect.
+   */
+  recentAdmissions(ip: string, windowMs: number): number {
+    const times = this.perIpAdmitTimes.get(ip);
+    if (times === undefined || times.length === 0) return 0;
+    const cutoff = this.clock.now() - windowMs;
+    let writeIdx = 0;
+    for (let i = 0; i < times.length; i++) {
+      const t = times[i];
+      if (t === undefined) continue;
+      if (t >= cutoff) {
+        times[writeIdx++] = t;
+      }
+    }
+    if (writeIdx === 0) {
+      this.perIpAdmitTimes.delete(ip);
+      return 0;
+    }
+    times.length = writeIdx;
+    return writeIdx;
+  }
+
+  /**
+   * Allocates the next unique record id. Public so {@link decideAdmission}
+   * can mint ids without breaking encapsulation.
+   */
+  nextRecord(): string {
+    const id = this.nextRecordId.toString(36);
+    this.nextRecordId += 1;
+    return id;
+  }
+}
+
+/**
+ * Decides whether a new connection should be admitted.
+ *
+ * The check is performed in a fixed precedence order so the rejection
+ * reason is deterministic:
+ *   1. Per-IP connection-rate limit (cheapest to test).
+ *   2. Per-IP simultaneous connection cap.
+ *   3. Per-user simultaneous connection cap.
+ *
+ * On success the caller MUST call {@link AdmissionStats.recordAdmission}
+ * with the returned `recordId` before admitting any further connection;
+ * on failure the caller MUST close the connection.
+ *
+ * The decision is pure with respect to `(ip, user, stats, config)` — same
+ * inputs yield the same outcome, including the assigned `recordId`.
+ */
+export function decideAdmission(
+  ip: string,
+  user: string | undefined,
+  stats: AdmissionStats,
+  config: AdmissionConfig,
+): AdmissionDecision {
+  // 1. Rate limit (per-IP, sliding window).
+  const recent = stats.recentAdmissions(ip, config.perIpConnectionRate.windowMs);
+  if (recent >= config.perIpConnectionRate.max) {
+    return { ok: false, reason: 'rate_limited_per_ip' };
+  }
+
+  // 2. Per-IP cap.
+  if (stats.countForIp(ip) >= config.maxConnectionsPerIp) {
+    return { ok: false, reason: 'max_connections_per_ip' };
+  }
+
+  // 3. Per-user cap (falls back to IP when no SASL identity is present).
+  const effectiveUser = user ?? ip;
+  if (stats.countForUser(effectiveUser) >= config.maxConnectionsPerUser) {
+    return { ok: false, reason: 'max_connections_per_user' };
+  }
+
+  return { ok: true, recordId: stats.nextRecord() };
+}

package/packages/irc-core/src/caps/capabilities.ts

@@ -26,6 +26,7 @@ export const SUPPORTED_CAPABILITIES: ReadonlyArray<Capability> = Object.freeze([
   { name: 'away-notify' },
   { name: 'batch' },
   { name: 'chghost' },
+  { name: 'draft/chathistory' },
   { name: 'echo-message' },
   { name: 'extended-join' },
   { name: 'invite-notify' },

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

@@ -0,0 +1,81 @@
+/**
+ * Hostmask cloaking — replaces a client's real source IP with a deterministic
+ * opaque identifier derived from the deployment secret + the IP.
+ *
+ * Goals (matching mainstream IRC daemon behaviour — charybdis / UnrealIRCd):
+ *   - The real IP is never revealed on the wire (in WHOIS, hostmasks, etc.).
+ *   - The same IP + secret always yields the same cloak (so per-IP
+ *     reputation/line enforcement still works).
+ *   - Two different IPs almost never collide.
+ *   - The cloak fits in a single DNS-label-safe segment.
+ *
+ * Implementation note: this uses a self-contained FNV-1a 32-bit hash plus a
+ * short base32 encoding so the module stays pure-TS and runs unchanged on
+ * Node 20, Cloudflare Workers, and Lambda. It is NOT a cryptographic MAC:
+ * an attacker who learns one cloak cannot recover the secret, but a
+ * determined attacker with the secret can forge cloaks. Deployments that
+ * need stronger unforgeability should override this module.
+ */
+
+import type { CloakingConfig } from './types.js';
+
+/**
+ * Returns the visible host for `realHost` after applying the deployment's
+ * cloaking policy.
+ *
+ *   - When `config.enabled === false`, `realHost` is returned verbatim.
+ *   - When `config.enabled === true`, a deterministic cloak of the form
+ *     `<hash>.<suffix>` is returned. The `<hash>` segment is derived from
+ *     `secret` + `realHost`; the `<suffix>` defaults to `defaultSuffix`
+ *     (typically the deployment's `networkName` lowercased) and may be
+ *     overridden via `config.cloakedSuffix`.
+ *
+ * The function is pure — same inputs always yield the same output. There
+ * is no ambient randomness or clock.
+ *
+ * @param realHost       The connection's real source IP (or any host string).
+ * @param config         Cloaking policy. See {@link CloakingConfig}.
+ * @param defaultSuffix  Suffix used when `config.cloakedSuffix` is absent.
+ */
+export function cloakHost(realHost: string, config: CloakingConfig, defaultSuffix: string): string {
+  if (!config.enabled) return realHost;
+  const suffix = config.cloakedSuffix ?? defaultSuffix;
+  // 64-bit hash assembled from two FNV-1a passes with different seeds so
+  // distinct IPs collide with probability ~ 1 / 2^64.
+  const hi = fnv1a32(`a:${config.secret}:${realHost}`);
+  const lo = fnv1a32(`b:${config.secret}:${realHost}`);
+  return `${base32(hi)}${base32(lo)}.${suffix}`;
+}
+
+/**
+ * FNV-1a 32-bit hash. Self-contained: no Node `crypto`, works on every
+ * serverless runtime. Output is an unsigned 32-bit integer.
+ */
+function fnv1a32(input: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    // 32-bit multiply by FNV prime using Math.imul to stay in u32 space.
+    h = Math.imul(h, 0x01000193);
+  }
+  // Force unsigned.
+  return h >>> 0;
+}
+
+/**
+ * Lowercase base32 (RFC 4648) encoding without padding, suitable for a
+ * DNS-safe identifier. Encodes 5 bits per character.
+ */
+const BASE32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+
+function base32(value: number): string {
+  // 32 bits -> 7 base32 chars (ceil(32/5) = 7 with one bit of padding,
+  // but we don't emit padding so 7 chars is the canonical length here).
+  let out = '';
+  let v = value;
+  for (let i = 0; i < 7; i++) {
+    out += BASE32_ALPHABET[v & 0x1f];
+    v = Math.floor(v / 32);
+  }
+  return out;
+}

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

@@ -199,8 +199,7 @@ function handleReq(
  */
 function handleEnd(state: ConnectionState, ctx: Ctx): ReducerResult<ConnectionState> {
   state.capNegotiating = false;
-  const welcome = emitWelcomeIfReady(state, ctx);
-  return { state, effects: welcome !== null ? [welcome] : [] };
+  return { state, effects: emitWelcomeIfReady(state, ctx) };
 }
 
 /**

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

@@ -0,0 +1,305 @@
+/**
+ * Pure reducer for the IRCv3 `draft/chathistory` command.
+ *
+ * Spec: https://ircv3.net/specs/extensions/chathistory
+ *
+ * Surface 1 (explicit query): `CHATHISTORY <sub> <target> [<args>...]`. The
+ * reducer reads the backlog from the {@link MessageStore} injected via
+ * {@link Ctx} (mirroring `MotdProvider` / `AccountStore`) and emits the
+ * matching `PRIVMSG`/`NOTICE`/`TAGMSG` lines wrapped in a single
+ * `BATCH chathistory <target>` frame. Each replay line carries the original
+ * `@time=…` (server-time) and `msgid=…` tags so the client can de-dup and
+ * place it on the timeline.
+ *
+ * The cap `draft/chathistory` MUST be negotiated before any query is
+ * accepted; clients without the cap get `421 ERR_UNKNOWNCOMMAND` (the spec's
+ * permitted "unknown command" fallback).
+ *
+ * Location-of-authority: chathistory is read-only and runs against the
+ * requester's connection. The target channel is passed in (resolved by the
+ * actor layer); `undefined` means "no such channel" → `403`.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { StoredMessage } from '../ports.js';
+import { wrapBatch } from '../protocol/batch.js';
+import type { IrcMessage } from '../protocol/messages.js';
+import { Numerics } from '../protocol/numerics.js';
+import { formatServerTime } from '../protocol/outbound.js';
+import type { ChannelState } from '../state/channel.js';
+import type { Ctx } from '../types.js';
+
+/** The cap name advertising chathistory support. */
+export const CHATHISTORY_CAP = 'draft/chathistory';
+
+/** Default query limit when the client omits one (spec recommends 50). */
+const DEFAULT_QUERY_LIMIT = 50;
+
+/** Sentinel the client uses to mean "most recent" / "now" / "beginning". */
+const WILDCARD = '*';
+
+/** Subcommands that operate on a single channel target. */
+type ChannelSubcommand = 'LATEST' | 'BEFORE' | 'AFTER' | 'AROUND' | 'BETWEEN';
+
+const CHANNEL_SUBCOMMANDS: ReadonlySet<string> = new Set<string>([
+  'LATEST',
+  'BEFORE',
+  'AFTER',
+  'AROUND',
+  'BETWEEN',
+]);
+
+/**
+ * Handles `CHATHISTORY <sub> <target> [<args>...]`.
+ *
+ * @param channel The authoritative ChannelState for `msg.params[1]`, or
+ *                `undefined` when no such channel exists (→ `403`).
+ */
+export function chathistoryReducer(
+  channel: ChannelState | undefined,
+  msg: IrcMessage,
+  ctx: Ctx,
+): { effects: EffectType[] } {
+  // Cap gate: clients that did not negotiate chathistory see RFC 2812 only.
+  if (!ctx.connection.caps.has(CHATHISTORY_CAP)) {
+    return {
+      effects: [
+        Effect.send(ctx.connId, [
+          numericErr(ctx, Numerics.ERR_UNKNOWNCOMMAND, 'Unknown command', 'CHATHISTORY'),
+        ]),
+      ],
+    };
+  }
+
+  const sub = (msg.params[0] ?? '').toUpperCase();
+  if (sub === '') {
+    return { effects: [Effect.send(ctx.connId, [needMoreParamsLine(ctx)])] };
+  }
+
+  if (sub === 'TARGETS') {
+    return handleTargets(msg, ctx);
+  }
+
+  if (!CHANNEL_SUBCOMMANDS.has(sub)) {
+    return { effects: [Effect.send(ctx.connId, [invalidParamsLine(ctx)])] };
+  }
+
+  return handleChannelSub(sub as ChannelSubcommand, channel, msg, ctx);
+}
+
+/** Handles the four channel-bound subcommands + BETWEEN. */
+function handleChannelSub(
+  sub: ChannelSubcommand,
+  channel: ChannelState | undefined,
+  msg: IrcMessage,
+  ctx: Ctx,
+): { effects: EffectType[] } {
+  const target = msg.params[1];
+  if (target === undefined) {
+    return { effects: [Effect.send(ctx.connId, [needMoreParamsLine(ctx)])] };
+  }
+
+  if (channel === undefined) {
+    return {
+      effects: [
+        Effect.send(ctx.connId, [
+          numericErr(ctx, Numerics.ERR_NOSUCHCHANNEL, 'No such channel', target),
+        ]),
+      ],
+    };
+  }
+
+  // +s/+p leak prevention: a non-member must not learn the channel has
+  // history. The spec says return an empty batch; we elide the batch entirely
+  // (empty batches are forbidden) so the requester observes nothing.
+  if ((channel.modes.secret || channel.modes.private) && !channel.members.has(ctx.connId)) {
+    return { effects: [] };
+  }
+
+  const chanLower = channel.nameLower;
+
+  if (sub === 'BETWEEN') {
+    const lo = msg.params[2];
+    const hi = msg.params[3];
+    if (lo === undefined || hi === undefined) {
+      return { effects: [Effect.send(ctx.connId, [needMoreParamsLine(ctx)])] };
+    }
+    if (!storeHas(ctx, chanLower, lo) || !storeHas(ctx, chanLower, hi)) {
+      return { effects: [Effect.send(ctx.connId, [invalidParamsLine(ctx)])] };
+    }
+    const result = storeQuery(ctx, {
+      chan: chanLower,
+      direction: 'between',
+      limit: DEFAULT_QUERY_LIMIT,
+      msgid: lo,
+      msgid2: hi,
+    });
+    return { effects: buildChathistoryBatch(ctx, channel.name, result) };
+  }
+
+  // LATEST / BEFORE / AFTER / AROUND
+  const pivot = msg.params[2];
+  const limitRaw = msg.params[3];
+  if (sub !== 'LATEST' && pivot === undefined) {
+    return { effects: [Effect.send(ctx.connId, [needMoreParamsLine(ctx)])] };
+  }
+  const limit = parseLimit(limitRaw);
+  if (limit === undefined) {
+    return { effects: [Effect.send(ctx.connId, [invalidParamsLine(ctx)])] };
+  }
+
+  if (sub === 'LATEST') {
+    const pivotArg = pivot === undefined || pivot === WILDCARD ? undefined : pivot;
+    if (pivotArg !== undefined && !storeHas(ctx, chanLower, pivotArg)) {
+      return { effects: [Effect.send(ctx.connId, [invalidParamsLine(ctx)])] };
+    }
+    const result = storeQuery(ctx, {
+      chan: chanLower,
+      direction: 'latest',
+      limit,
+      ...(pivotArg !== undefined ? { msgid: pivotArg } : {}),
+    });
+    return { effects: buildChathistoryBatch(ctx, channel.name, result) };
+  }
+
+  // BEFORE / AFTER / AROUND — pivot is required. The `sub !== 'LATEST' &&
+  // pivot === undefined` guard above already rejected the missing-pivot
+  // case and LATEST returned early just above; assert non-null for the
+  // type-checker without an unreachable branch.
+  const pivotMsgid = pivot as string;
+  if (!storeHas(ctx, chanLower, pivotMsgid)) {
+    return { effects: [Effect.send(ctx.connId, [invalidParamsLine(ctx)])] };
+  }
+  const result = storeQuery(ctx, {
+    chan: chanLower,
+    direction: sub.toLowerCase() as 'before' | 'after' | 'around',
+    limit,
+    msgid: pivotMsgid,
+  });
+  return { effects: buildChathistoryBatch(ctx, channel.name, result) };
+}
+
+/** Handles `CHATHISTORY TARGETS <since> <until>`. */
+function handleTargets(msg: IrcMessage, ctx: Ctx): { effects: EffectType[] } {
+  const sinceRaw = msg.params[1];
+  const untilRaw = msg.params[2];
+  if (sinceRaw === undefined || untilRaw === undefined) {
+    return { effects: [Effect.send(ctx.connId, [needMoreParamsLine(ctx)])] };
+  }
+  const since = parseTimestamp(sinceRaw, 0);
+  const until = parseTimestamp(untilRaw, ctx.clock.now());
+  if (since === undefined || until === undefined) {
+    return { effects: [Effect.send(ctx.connId, [invalidParamsLine(ctx)])] };
+  }
+
+  const entries = ctx.messages !== undefined ? ctx.messages.targets(since, until) : [];
+  if (entries.length === 0) {
+    return { effects: [] };
+  }
+
+  const body: RawLine[] = entries.map((e) => ({
+    text: `:${ctx.serverName} CHATHISTORY TARGETS ${formatServerTime(e.time)} ${e.chan}`,
+  }));
+  const frame = wrapBatch(body, ctx.ids.batchId(), 'chathistory');
+  return { effects: [Effect.send(ctx.connId, frame)] };
+}
+
+/**
+ * Wraps `messages` as replay lines in a `BATCH chathistory <chan>` frame
+ * addressed to the requester. Empty input elides the batch entirely (the
+ * spec forbids empty batches; the client interprets "no batch" as "no
+ * history").
+ *
+ * Shared by the explicit `CHATHISTORY` query and the JOIN auto-playback hook
+ * so both surfaces emit identical framing.
+ */
+export function buildChathistoryBatch(
+  ctx: Ctx,
+  displayChan: string,
+  messages: readonly StoredMessage[],
+): EffectType[] {
+  if (messages.length === 0) return [];
+  const body = messages.map((m) => formatReplayLine(m, displayChan));
+  const frame = wrapBatch(body, ctx.ids.batchId(), 'chathistory', displayChan);
+  return [Effect.send(ctx.connId, frame)];
+}
+
+/**
+ * Reconstructs the wire line for one stored message, decorated with the
+ * original server-time and msgid tags. PRIVMSG/NOTICE carry the trailing
+ * text; TAGMSG has no trailing parameter.
+ */
+export function formatReplayLine(m: StoredMessage, displayChan: string): RawLine {
+  const stamp = formatServerTime(m.time);
+  const prefix = storedHostmask(m);
+  const tag = `@time=${stamp};msgid=${m.msgid}`;
+  if (m.command === 'TAGMSG') {
+    return { text: `${tag} :${prefix} TAGMSG ${displayChan}` };
+  }
+  return { text: `${tag} :${prefix} ${m.command} ${displayChan} :${m.text}` };
+}
+
+/** Builds the `nick!user@host` source for a stored message. */
+function storedHostmask(m: StoredMessage): string {
+  if (m.user === undefined && m.host === undefined) return m.nick;
+  let out = m.nick;
+  if (m.user !== undefined) out = `${out}!${m.user}`;
+  if (m.host !== undefined) out = `${out}@${m.host}`;
+  return out;
+}
+
+/** Formats a numeric error line addressed to the connection's nick (or `*`). */
+function numericErr(ctx: Ctx, code: number, trailing: string, middle: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: [`:${ctx.serverName}`, codeStr, nick, middle, `:${trailing}`].join(' ') };
+}
+
+/** `461 CHATHISTORY :Not enough parameters`. */
+function needMoreParamsLine(ctx: Ctx): RawLine {
+  return numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Not enough parameters', 'CHATHISTORY');
+}
+
+/** `461 CHATHISTORY :Invalid parameters`. */
+function invalidParamsLine(ctx: Ctx): RawLine {
+  return numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Invalid parameters', 'CHATHISTORY');
+}
+
+/** Parses a non-negative integer limit; returns undefined on garbage. */
+function parseLimit(raw: string | undefined): number | undefined {
+  if (raw === undefined) return DEFAULT_QUERY_LIMIT;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0) return undefined;
+  return n;
+}
+
+/**
+ * Parses a CHATHISTORY timestamp bound. `*` resolves to `wildcardValue`
+ * (0 for `since`, `ctx.clock.now()` for `until`); an ISO-8601 string parses
+ * to epoch ms; anything else returns undefined (→ `461`).
+ */
+function parseTimestamp(raw: string, wildcardValue: number): number | undefined {
+  if (raw === WILDCARD) return wildcardValue;
+  const ms = Date.parse(raw);
+  return Number.isNaN(ms) ? undefined : ms;
+}
+
+/** store.hasMsgid that treats an unbound store as "the msgid is not known". */
+function storeHas(ctx: Ctx, chan: string, msgid: string): boolean {
+  return ctx.messages !== undefined ? ctx.messages.hasMsgid(chan, msgid) : false;
+}
+
+/** store.query that treats an unbound store as empty. */
+function storeQuery(
+  ctx: Ctx,
+  q: {
+    chan: string;
+    direction: 'latest' | 'before' | 'after' | 'around' | 'between';
+    limit: number;
+    msgid?: string;
+    msgid2?: string;
+  },
+): StoredMessage[] {
+  return ctx.messages !== undefined ? ctx.messages.query(q) : [];
+}

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

@@ -38,3 +38,10 @@ export { capReducer } from './cap.js';
 export { emitChghost } from './chghost.js';
 export type { ChgHostInput } from './chghost.js';
 export { awayReducer } from './away.js';
+export { authenticateReducer } from './sasl.js';
+export {
+  chathistoryReducer,
+  formatReplayLine,
+  buildChathistoryBatch,
+  CHATHISTORY_CAP,
+} from './chathistory.js';