serverless-ircd 0.3.0 → 0.5.0

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

@@ -0,0 +1,137 @@
+/**
+ * Pure reducer for the IRC `TRACE` command (RFC 2812 §4.6.3).
+ *
+ * PLAN §2.1 location-of-authority: TRACE is a query-only diagnostic. The
+ * actor layer resolves the optional `<target>` and — when it is a nick —
+ * hands the resolved {@link ConnectionState} here. The reducer never
+ * mutates anything but the requester's `lastSeen`.
+ *
+ * In a single-server serverless IRCd, multi-hop routing collapses to the
+ * local server. The classic `200 RPL_TRACELINK` / `206 RPL_TRACESERVER`
+ * server-link dump is therefore trivial (one server, zero hops); modern
+ * daemons emit just the per-connection `205`/`204` lines and the
+ * terminating `262 RPL_ENDOFTRACE`. This reducer follows that convention.
+ *
+ * Wire format (RFC 2812 §4.6.3 + modern practice):
+ *   - `TRACE [<target>]`
+ *   - `205 RPL_TRACEUSER`:
+ *     `:<server> 205 <nick> User <hops> <user> <host>` (per matched conn)
+ *   - `204 RPL_TRACEOPERATOR`:
+ *     `:<server> 204 <nick> Oper <hops> <user> <host>` (oper conns only)
+ *   - `262 RPL_ENDOFTRACE`:
+ *     `:<server> 262 <nick> <target> :End of TRACE`
+ *   - `402 ERR_NOSUCHSERVER`:
+ *     `:<server> 402 <nick> <server> :No such server`
+ *
+ * Detail visibility is oper-gated:
+ *   - Non-opers see only the `262` terminator (no per-connection detail),
+ *     so a non-oper cannot use `TRACE` to enumerate online users. This
+ *     also implicitly enforces `+i` invisibility for non-opers.
+ *   - Opers see one `205`/`204` line per matched connection and bypass
+ *     the `+i` filter (RFC 2812 §4.6.3).
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx } from '../types.js';
+
+/** Fixed text emitted for `402 ERR_NOSUCHSERVER`. */
+const NOSUCHSERVER_TRAILING_TEXT = 'No such server';
+
+/** Fixed text emitted for `262 RPL_ENDOFTRACE`. */
+const ENDOFTRACE_TRAILING_TEXT = 'End of TRACE';
+
+/**
+ * Builds a `:<server> <code> <nick> <Class> <hops> <nick> <user> <host>`
+ * line for one matched connection. `<Class>` is `Oper` for an oper,
+ * otherwise `User` (matching RFC 2812 §4.6.3 + common client rendering).
+ * `<hops>` is always 0 in a single-server deployment.
+ */
+function traceDetailLine(ctx: Ctx, code: number, cls: string, target: ConnectionState): RawLine {
+  const requesterNick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const tNick = target.nick ?? '*';
+  const tUser = target.user ?? '?';
+  const tHost = target.host ?? '?';
+  return {
+    text: `:${ctx.serverName} ${codeStr} ${requesterNick} ${cls} 0 ${tNick} ${tUser} ${tHost}`,
+  };
+}
+
+/**
+ * Builds a `:<server> <code> <nick> [<middle>] :<trailing>` numeric line
+ * addressed to the requester. When `middle` is empty the middle field is
+ * omitted entirely.
+ */
+function numericLine(ctx: Ctx, code: number, trailing: string, middle: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const parts = [`:${ctx.serverName}`, codeStr, nick];
+  if (middle !== '') parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}
+
+/**
+ * Handles `TRACE [<target>]`.
+ *
+ * The actor layer resolves `<target>`:
+ *   - Empty / absent / equal to the local server name → `target` is
+ *     `undefined` and `serverTarget` is unset; the reducer emits only the
+ *     terminating `262`.
+ *   - A nick that resolves → `target` is the live
+ *     {@link ConnectionState}; the reducer emits `205`/`204` (oper
+ *     requester only) then `262`.
+ *   - A nick that does not resolve → `target` is `undefined`; the reducer
+ *     emits only the `262` (carrying the requested nick).
+ *   - A name that is not the local server (treated as a remote server) →
+ *     the actor passes `serverTarget = '<name>'`; the reducer emits
+ *     `402 ERR_NOSUCHSERVER`.
+ *
+ * @param target        The resolved target connection, or `undefined`.
+ * @param msg           The parsed `TRACE` message.
+ * @param ctx           The per-invocation context.
+ * @param serverTarget  When set, the actor determined `<target>` names a
+ *   non-local server; the reducer emits `402` against this name.
+ */
+export function traceReducer(
+  target: ConnectionState | undefined,
+  msg: { command: string; params: readonly string[] },
+  ctx: Ctx,
+  serverTarget?: string,
+): { effects: EffectType[] } {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+  const rawTarget = msg.params[0] ?? '';
+
+  if (serverTarget !== undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NOSUCHSERVER, NOSUCHSERVER_TRAILING_TEXT, serverTarget),
+      ]),
+    );
+    return { effects };
+  }
+
+  const isOper = ctx.connection.userModes.oper;
+  if (target !== undefined && isOper) {
+    // Per-connection detail is oper-gated, which also implicitly enforces
+    // `+i` invisibility for non-opers (they never receive detail). Opers
+    // bypass `+i` per RFC 2812 §4.6.3 and always see the matched conn.
+    const code = target.userModes.oper ? Numerics.RPL_TRACEOPERATOR : Numerics.RPL_TRACEUSER;
+    const cls = target.userModes.oper ? 'Oper' : 'User';
+    effects.push(Effect.send(ctx.connId, [traceDetailLine(ctx, code, cls, target)]));
+  }
+
+  const endMiddle = rawTarget.length > 0 ? rawTarget : '';
+  effects.push(
+    Effect.send(ctx.connId, [
+      numericLine(ctx, Numerics.RPL_ENDOFTRACE, ENDOFTRACE_TRAILING_TEXT, endMiddle),
+    ]),
+  );
+
+  return { effects };
+}

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

@@ -0,0 +1,84 @@
+/**
+ * Pure reducer for the IRC `USERHOST` command.
+ *
+ * PLAN §2.1 location-of-authority: USERHOST is read-only — it queries nick
+ * → connection state and emits a single `302 RPL_USERHOST` line. The reducer
+ * itself does not perform lookups (those are async and belong to the actor /
+ * runtime layer); it receives the pre-resolved snapshots and formats the
+ * reply.
+ *
+ * Wire format (RFC 2812 §5.5):
+ *   - `USERHOST <nick>{ <nick>}` (up to {@link ServerConfig.maxTargetsPerCommand})
+ *   - `302 RPL_USERHOST`:
+ *     `:<server> 302 <nick> :<reply1> <reply2> …`
+ *   - Each reply: `<nick>[*]=<+|-><user>@<host>`
+ *     - `*` between nick and `=` marks an IRC operator.
+ *     - `+` means available; `-` means away.
+ *   - Offline nicks are omitted from the reply entirely.
+ *
+ * The actor resolves each requested nick via `runtime.lookupNick` +
+ * `runtime.getConnection` before calling this reducer, passing `null` for
+ * nicks that are offline.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnSnapshot, ConnectionState } from '../state/connection.js';
+import type { Ctx, ReducerResult } from '../types.js';
+
+/**
+ * Formats a single USERHOST reply token for a resolved connection snapshot.
+ *
+ * `nick[*]=[+|-]user@host` — `*` for operators, `+` for available, `-` for
+ * away. Returns `null` for snapshots missing the required `nick` / `user` /
+ * `host` fields (should not happen for registered connections, but guarded).
+ */
+export function formatUserhostReply(snap: ConnSnapshot): string | null {
+  if (snap.nick === undefined || snap.user === undefined || snap.host === undefined) {
+    return null;
+  }
+  const operMark = snap.userModes.oper ? '*' : '';
+  const awayMark = snap.away !== undefined ? '-' : '+';
+  return `${snap.nick}${operMark}=${awayMark}${snap.user}@${snap.host}`;
+}
+
+/**
+ * Handles `USERHOST <nick>{ <nick>}`.
+ *
+ * `resolved` maps each requested nick (original case) to its snapshot, or
+ * `null` when the nick is offline. The reducer formats each online entry into
+ * a USERHOST reply token and emits a single `302` line. Offline nicks are
+ * omitted. The number of queried nicks is capped at
+ * `ctx.serverConfig.maxTargetsPerCommand`.
+ *
+ * Signature is bespoke (not {@link Reducer}) because the actor must resolve
+ * the nicks asynchronously before formatting — mirrors `whoReducer` /
+ * `whoisReducer`.
+ */
+export function userhostReducer(
+  resolved: ReadonlyMap<string, ConnSnapshot | null>,
+  msg: { params: readonly string[] },
+  ctx: Ctx,
+): ReducerResult<ConnectionState> {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const cap = ctx.serverConfig.maxTargetsPerCommand;
+  const requested = msg.params.slice(0, cap);
+  const tokens: string[] = [];
+  for (const nick of requested) {
+    if (nick.length === 0) continue;
+    const snap = resolved.get(nick);
+    if (snap === null || snap === undefined) continue;
+    const token = formatUserhostReply(snap);
+    if (token !== null) tokens.push(token);
+  }
+
+  const ircNick = ctx.connection.nick ?? '*';
+  const codeStr = Numerics.RPL_USERHOST.toString().padStart(3, '0');
+  const trailing = tokens.join(' ');
+  const line: RawLine = { text: `:${ctx.serverName} ${codeStr} ${ircNick} :${trailing}` };
+
+  const effects: EffectType[] = [Effect.send(ctx.connId, [line])];
+  return { state: ctx.connection, effects };
+}

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

@@ -0,0 +1,118 @@
+/**
+ * Pure reducer for the IRC `WALLOPS` command (oper-only global broadcast).
+ *
+ * PLAN §2.1 location-of-authority: WALLOPS runs in the Connection entity.
+ * The reducer is pure — it enforces the oper gate, validates the message,
+ * and emits a single {@link BroadcastWallopsEffect}. The bound runtime's
+ * `broadcastWallops` method owns the cross-connection enumeration that
+ * the gate cannot observe purely (it does not see which other
+ * connections carry the `+w` user mode).
+ *
+ * Wire format (RFC 2812 §4.7):
+ *   - `WALLOPS :<message>`
+ *   - `481 ERR_NOPRIVILEGES`:
+ *     `:<server> 481 <nick> :Permission Denied - You're not an IRC operator`
+ *   - `412 ERR_NOTEXTTOSEND`:
+ *     `:<server> 412 <nick> :No text to send`
+ *
+ * Behaviour:
+ *   - Non-oper sender → `481` (checked before the message is inspected, so
+ *     a non-oper cannot probe the command shape).
+ *   - Empty / missing message → `412 ERR_NOTEXTTOSEND`. We pick `412` over
+ *     `461 ERR_NEEDMOREPARAMS` to match the message-bearing commands
+ *     PRIVMSG/NOTICE, which use `412` for "no text to send". WALLOPS is a
+ *     single-param message command, so the semantically closer numeric wins.
+ *   - Otherwise emit `BroadcastWallops([:<oper> WALLOPS :<message>], sender)`
+ *     so the runtime fans the line out to every `+w` connection.
+ *
+ * Delivery / skip-self: the originator is ALWAYS passed as `except`. This
+ * matches NOTICE/PRIVMSG channel-broadcast semantics (the sender never
+ * receives their own message back) and avoids a redundant echo to the
+ * oper who just typed it. The `+w` user mode is the *recipient* gate,
+ * owned by the runtime — the sender's own `+w` is therefore irrelevant
+ * under this default. An oper who wants a delivery receipt can query
+ * logs. (RFC leaves delivery to `+w` regardless of oper; we deliberately
+ * diverge to match the rest of the codebase's broadcast primitives.)
+ *
+ * The `+w` user mode is accepted by the MODE reducer (`w → 'wallops'`)
+ * and advertised in `004 RPL_MYINFO`, but no command consumed it before
+ * this one — setting `+w` used to be a silent no-op. This reducer lights
+ * up the consumer.
+ */
+
+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 { Ctx, Reducer } from '../types.js';
+
+/** Fixed text emitted for `481 ERR_NOPRIVILEGES` (matches `kill.ts` / `mode.ts`). */
+const NOPRIVILEGES_TRAILING_TEXT = "Permission Denied - You're not an IRC operator";
+
+/** Fixed text emitted for `412 ERR_NOTEXTTOSEND` (matches `privmsg.ts`). */
+const NOTEXTTOSEND_TRAILING_TEXT = 'No text to send';
+
+/**
+ * Renders the `:<source> WALLOPS :<message>` wire line that every `+w`
+ * connection receives. `<source>` is the oper's full hostmask
+ * (`nick!user@host`), consistent with how PRIVMSG/NOTICE/QUIT attribute
+ * user-originated messages. When the hostmask is incomplete (e.g. no
+ * `user`/`host` yet, which should not happen for a registered oper but is
+ * defended against) the bare nick is used, falling back to `*` only when
+ * no nick is set at all.
+ */
+export function wallopsLine(state: ConnectionState, message: string): RawLine {
+  const source = hostmaskOf(state) ?? state.nick ?? '*';
+  return { text: `:${source} WALLOPS :${message}` };
+}
+
+/**
+ * Handles `WALLOPS :<message>`.
+ *
+ * Enforces the oper gate, stamps `lastSeen`, and on success emits a single
+ * {@link BroadcastWallopsEffect} addressed to every `+w` connection. The
+ * sender is always excluded (skip-self). The reducer never performs IO.
+ */
+export const wallopsReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  if (!state.userModes.oper) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NOPRIVILEGES, NOPRIVILEGES_TRAILING_TEXT),
+        ]),
+      ],
+    };
+  }
+
+  const message = msg.params[0];
+  if (message === undefined || message.length === 0) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NOTEXTTOSEND, NOTEXTTOSEND_TRAILING_TEXT),
+        ]),
+      ],
+    };
+  }
+
+  return {
+    state,
+    effects: [Effect.broadcastWallops([wallopsLine(state, message)], ctx.connId)],
+  };
+};
+
+/**
+ * Builds a `:<server> <code> <nick> :<trailing>` line. The nick falls back
+ * to `*` when the connection has not yet registered one, matching the rest
+ * of the codebase's numeric formatting.
+ */
+function numericLine(ctx: Ctx, code: number, trailing: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: [`:${ctx.serverName}`, codeStr, nick, `:${trailing}`].join(' ') };
+}

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

@@ -0,0 +1,113 @@
+/**
+ * Pure reducer for the IRC `WHOWAS` command.
+ *
+ * PLAN §2.1 location-of-authority: WHOWAS reads the nick-history store but
+ * does not mutate connection or channel state. The actor layer resolves
+ * `ctx.history` (a synchronously-readable {@link NickHistoryStore}) and
+ * passes it here. The requester is `ctx.connection`.
+ *
+ * Wire format (RFC 1459/2812 §3.6.3):
+ *   - `314 RPL_WHOWASUSER`:
+ *     `:<server> 314 <nick> <target> <user> <host> * :<real>`
+ *   - `369 RPL_ENDOFWHOWAS`:
+ *     `:<server> 369 <nick> <target> :End of WHOWAS`
+ *   - `406 ERR_WASNOSUCHNICK`:
+ *     `:<server> 406 <nick> <target> :There was no such nickname`
+ *   - `431 ERR_NONICKNAMEGIVEN`:
+ *     `:<server> 431 <nick> :No nickname given`
+ *
+ * The reducer takes a bespoke signature (mirroring {@link whoisReducer})
+ * because it queries runtime-provided state (the history store) rather than
+ * the `Reducer<S>` state argument.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { NickHistoryEntry, NickHistoryStore } from '../ports.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { Ctx } from '../types.js';
+
+/** Formats a numeric line addressed to the requester. */
+function numericLine(ctx: Ctx, code: number, trailing: string, middle?: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const parts = [`:${ctx.serverName}`, codeStr, nick];
+  if (middle !== undefined) parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}
+
+/** Builds the `314 RPL_WHOWASUSER` line for one sign-off entry. */
+function whowasUserLine(ctx: Ctx, entry: NickHistoryEntry): RawLine {
+  const requesterNick = ctx.connection.nick ?? '*';
+  const nick = entry.nick;
+  const user = entry.username ?? '?';
+  const host = entry.hostname ?? '?';
+  const real = entry.realname ?? nick;
+  const code = Numerics.RPL_WHOWASUSER.toString().padStart(3, '0');
+  return { text: `:${ctx.serverName} ${code} ${requesterNick} ${nick} ${user} ${host} * :${real}` };
+}
+
+/**
+ * Handles `WHOWAS <nick>{,<nick>} [<count>]`.
+ *
+ * The actor layer resolves `ctx.history` (absent when no nick-history store
+ * is bound) and passes the store (or `undefined`) here. For each queried
+ * nick the reducer emits one `314 RPL_WHOWASUSER` per matching history
+ * entry (capped at `count`, most-recent-first), then exactly one
+ * `369 RPL_ENDOFWHOWAS`. When a nick has no matches it emits
+ * `406 ERR_WASNOSUCHNICK` before the `369`. When no nick argument is
+ * supplied it emits `431 ERR_NONICKNAMEGIVEN` and returns.
+ */
+export function whowasReducer(
+  history: NickHistoryStore | undefined,
+  msg: { command: string; params: string[] },
+  ctx: Ctx,
+): { effects: EffectType[] } {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+  const nickParam = msg.params[0];
+  if (nickParam === undefined || nickParam.length === 0) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NONICKNAMEGIVEN, 'No nickname given'),
+      ]),
+    );
+    return { effects };
+  }
+
+  const countParam = msg.params[1];
+  const nicks = nickParam.split(',').filter((n) => n.length > 0);
+  const count = countParam !== undefined ? parseCount(countParam) : Number.POSITIVE_INFINITY;
+
+  for (const nick of nicks) {
+    const matches = history === undefined ? [] : history.query(nick, count);
+    for (const entry of matches) {
+      effects.push(Effect.send(ctx.connId, [whowasUserLine(ctx, entry)]));
+    }
+    if (matches.length === 0) {
+      effects.push(
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_WASNOSUCHNICK, 'There was no such nickname', nick),
+        ]),
+      );
+    }
+    effects.push(
+      Effect.send(ctx.connId, [numericLine(ctx, Numerics.RPL_ENDOFWHOWAS, 'End of WHOWAS', nick)]),
+    );
+  }
+
+  return { effects };
+}
+
+/**
+ * Parses the `WHOWAS` count argument. RFC 1459 allows a non-positive or
+ * missing count to mean "unlimited"; a malformed (non-numeric) count is
+ * treated as unlimited as well so the command still answers.
+ */
+function parseCount(raw: string): number {
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) return Number.POSITIVE_INFINITY;
+  return n;
+}

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

@@ -17,6 +17,7 @@
  */
 
 import { z } from 'zod';
+import { BUILD_DATE } from './build-info.js';
 
 /**
  * Schema for a single IRC operator credential.
@@ -113,6 +114,26 @@ export const DEFAULT_FLOOD_CONTROL_CONFIG: {
   disconnectThreshold: 0,
 };
 
+/**
+ * Default server version surfaced in `002`/`004`/`351`/`371` when a deployment
+ * does not supply one. Kept in sync with `irc-core/package.json` `version`;
+ * adapters inject the deploy-time version via the `serverVersion` config
+ * knob (see the per-adapter config loaders).
+ */
+export const DEFAULT_SERVER_VERSION = '0.3.0';
+
+/**
+ * Default "created" text for `003 RPL_CREATED` when a deployment does not
+ * supply one. Baked into `dist/index.js` at build time by
+ * `scripts/generate-build-info.mjs` (run via `prebuild`); the value is the
+ * ISO timestamp of the build that produced the artifact, so a deployed
+ * Worker/Lambda reports the date it was built rather than a static
+ * placeholder. Production deployments may still override via the `createdAt`
+ * config knob (a human-readable string or an epoch-ms number that the
+ * reducer formats).
+ */
+export const DEFAULT_CREATED_TEXT: string = BUILD_DATE;
+
 /**
  * The full server-config schema. Optional fields default to deployment-
  * sensible values so a minimal `{ serverName, networkName }` config is
@@ -124,6 +145,22 @@ export const ServerConfigSchema = z.object({
   /** Network name advertised in `005 NETWORK=...` and WHOIS replies. */
   networkName: z.string().min(1),
 
+  /**
+   * Server version surfaced in the `002`/`004` welcome numerics, `351
+   * RPL_VERSION`, and `371 RPL_INFO`. Defaults to the irc-core package
+   * version ({@link DEFAULT_SERVER_VERSION}); deployments inject the
+   * deploy-time version (e.g. via a build-time constant or env var).
+   */
+  serverVersion: z.string().min(1).default(DEFAULT_SERVER_VERSION),
+
+  /**
+   * "Created" text for `003 RPL_CREATED` (`This server was created in
+   * <text>`). Either a human-readable string used verbatim, or an epoch-ms
+   * number that the reducer formats as a UTC timestamp. Defaults to
+   * {@link DEFAULT_CREATED_TEXT}; deployments inject the deploy/build time.
+   */
+  createdAt: z.union([z.string().min(1), z.number()]).default(DEFAULT_CREATED_TEXT),
+
   /**
    * Server password. Empty string or undefined disables the password
    * gate. When set, every connection must supply the same value via
@@ -219,6 +256,13 @@ export const ServerConfigSchema = z.object({
   channelLen: z.number().int().positive().default(50),
   /** Maximum topic length (advertised as `TOPICLEN=`). */
   topicLen: z.number().int().nonnegative().default(390),
+  /**
+   * Maximum realname (GECOS) length enforced by `SETNAME`. There is no
+   * standard ISUPPORT token for this; registration-time `USER` does not
+   * enforce a cap, so the knob is optional on {@link ServerConfig} and the
+   * reducer falls back to a built-in default when unset.
+   */
+  realnameLen: z.number().int().nonnegative().default(50),
   /** Default QUIT reason when the client disconnects without one. */
   quitMessage: z.string().default('Client Quit'),
 
@@ -268,3 +312,24 @@ export const DEFAULT_SERVER_CONFIG: ParsedServerConfig = ServerConfigSchema.pars
   serverName: 'irc.example.com',
   networkName: 'ServerlessIRCd',
 });
+
+/**
+ * Resolves the effective server version for wire output: the configured
+ * value when present, otherwise {@link DEFAULT_SERVER_VERSION}. Used by the
+ * registration and server-info reducers so they share one source of truth.
+ */
+export function resolveServerVersion(cfg: { readonly serverVersion?: string | undefined }): string {
+  return cfg.serverVersion ?? DEFAULT_SERVER_VERSION;
+}
+
+/**
+ * Formats the `003 RPL_CREATED` text from the configured `createdAt`:
+ * a string is used verbatim, a number is treated as epoch-ms and rendered
+ * as a UTC timestamp, and `undefined` falls back to
+ * {@link DEFAULT_CREATED_TEXT}.
+ */
+export function formatCreatedAt(createdAt: string | number | undefined): string {
+  if (createdAt === undefined) return DEFAULT_CREATED_TEXT;
+  if (typeof createdAt === 'number') return new Date(createdAt).toUTCString();
+  return createdAt;
+}

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

@@ -0,0 +1,124 @@
+/**
+ * Shared SASL credential hashing primitives.
+ *
+ * Both the AWS adapter (`DynamoAccountStore`) and the CF adapter
+ * (`D1AccountStore`) store SASL PLAIN credentials as **scrypt hashes**.
+ * These helpers live in `irc-core` so both adapters share one hashing
+ * implementation — the AWS path previously owned the only copy.
+ *
+ * Uses `node:crypto` (`scryptSync`), which is available on Node (AWS Lambda)
+ * natively and on Cloudflare Workers via the `nodejs_compat` flag. The public
+ * API surface is platform-agnostic: salts are passed as `Uint8Array` and the
+ * stored `HashedAccountCredential` carries only base64 `string` fields, so
+ * consuming packages never need `@types/node` to use these helpers.
+ */
+
+import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
+import type { AccountStore, SaslPayload, SaslResult } from './ports.js';
+
+const SCRYPT_KEY_LEN = 64;
+const SALT_LEN = 16;
+
+/**
+ * A single SASL PLAIN credential stored as a scrypt hash.
+ *
+ * Every field is a persistence-backend attribute — this object IS the table
+ * row (DynamoDB `Accounts` item / D1 `accounts` row, keyed by `account`).
+ * `algorithm` is retained so future migrations to Argon2/bcrypt can be
+ * detected and handled gracefully by {@link verifyHashedPassword}.
+ */
+export interface HashedAccountCredential {
+  readonly account: string;
+  readonly algorithm: 'scrypt';
+  readonly salt: string;
+  readonly hash: string;
+}
+
+/**
+ * Hashes a plaintext password into a {@link HashedAccountCredential}
+ * suitable for writing to the accounts backend (`putAccountCredential` /
+ * `seed-cf-accounts`).
+ *
+ * Uses `scryptSync` (memory-hard, GPU-resistant) with a random salt.
+ * Pass `{ salt }` for deterministic test scenarios; pass `{ keyLen }` to
+ * override the default 64-byte derived-key length.
+ *
+ * @param opts.salt  Optional salt (deterministic for tests). When omitted a
+ *   fresh cryptographically-random salt is generated. Typed as `Uint8Array`
+ *   to keep the public API free of node-specific `Buffer` types.
+ */
+export function hashAccountCredential(
+  username: string,
+  password: string,
+  opts?: { salt?: Uint8Array; keyLen?: number },
+): HashedAccountCredential {
+  const salt = opts?.salt ?? randomBytes(SALT_LEN);
+  const keyLen = opts?.keyLen ?? SCRYPT_KEY_LEN;
+  const hash = scryptSync(password, salt, keyLen);
+  return {
+    account: username,
+    algorithm: 'scrypt',
+    salt: Buffer.from(salt).toString('base64'),
+    hash: hash.toString('base64'),
+  };
+}
+
+/**
+ * Verifies a plaintext password against a {@link HashedAccountCredential}
+ * using `timingSafeEqual` (no short-circuit on first mismatched byte).
+ *
+ * Returns `false` for malformed entries rather than throwing — a corrupt
+ * row should not crash the SASL exchange.
+ */
+export function verifyHashedPassword(password: string, entry: HashedAccountCredential): boolean {
+  if (entry.algorithm !== 'scrypt') return false;
+  const salt = Buffer.from(entry.salt, 'base64');
+  const expected = Buffer.from(entry.hash, 'base64');
+  if (expected.length === 0) return false;
+  const computed = scryptSync(password, salt, expected.length);
+  return computed.length === expected.length && timingSafeEqual(computed, expected);
+}
+
+/**
+ * Synchronous {@link AccountStore} backed by pre-loaded hashed credentials.
+ *
+ * Construct with entries produced by {@link hashAccountCredential} (for unit
+ * tests / seeding) or pre-loaded from a persistence backend at boot. Both
+ * adapters use this class:
+ *
+ *   - AWS: `loadDynamoAccountStore` scans the `Accounts` table at Lambda
+ *     cold start and constructs this store; `DynamoAccountStore` is a
+ *     re-export alias for back-compat.
+ *   - CF: `loadD1AccountStore` queries the D1 `accounts` table at
+ *     `ConnectionDO` construction (mirroring the two-phase load pattern).
+ *
+ * The class has zero backend coupling — it works equally well with entries
+ * from any source. The `AccountStore.verify` port stays synchronous, so
+ * the async pre-load MUST complete before the first frame dispatches.
+ */
+export class HashedAccountStore implements AccountStore {
+  private readonly entries: ReadonlyMap<string, HashedAccountCredential>;
+
+  constructor(entries: ReadonlyArray<HashedAccountCredential>) {
+    this.entries = new Map(entries.map((e) => [e.account, e]));
+  }
+
+  verify(mech: string, payload: SaslPayload): SaslResult {
+    if (mech.toUpperCase() !== 'PLAIN' || payload.kind !== 'PLAIN') {
+      return { ok: false, reason: `unsupported mechanism: ${mech}` };
+    }
+    const entry = this.entries.get(payload.username);
+    if (entry === undefined) {
+      return { ok: false, reason: 'invalid credentials' };
+    }
+    if (!verifyHashedPassword(payload.password, entry)) {
+      return { ok: false, reason: 'invalid credentials' };
+    }
+    return { ok: true, account: payload.username };
+  }
+
+  /** Number of loaded accounts (diagnostics / logging). */
+  get size(): number {
+    return this.entries.size;
+  }
+}