serverless-ircd 0.3.0 → 0.4.0

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

@@ -4,10 +4,13 @@
  * PLAN §2.1 location-of-authority: SASL runs in the Connection entity.
  * The reducer drives the multi-frame SASL exchange purely:
  *
- *   1. `AUTHENTICATE <MECH>` — selects a mechanism. `PLAIN` is supported and
- *      answers with `AUTHENTICATE +` (requesting the payload). `EXTERNAL` is
- *      recognized but stubbed to `904` until mTLS lands. Anything else gets
- *      `908 ERR_SASLMECHS` listing what is available.
+ *   1. `AUTHENTICATE <MECH>` — selects a mechanism. `PLAIN` is always
+ *      supported and answers with `AUTHENTICATE +` (requesting the payload).
+ *      `EXTERNAL` is supported only when an mTLS identity provider is
+ *      configured for the connection; without one, EXTERNAL falls through
+ *      to `908 ERR_SASLMECHS` (mechanism not available) listing what is.
+ *      The verified client-cert subject is resolved at finalise time.
+ *      Anything else gets `908 ERR_SASLMECHS` listing what is available.
  *   2. `AUTHENTICATE <b64>` / `AUTHENTICATE +` — delivers the payload (whole
  *      or in `<=400`-byte chunks; `+` marks an empty/final chunk). The
  *      decoded bytes are handed to the injected {@link AccountStore}; on
@@ -26,6 +29,7 @@
 
 import { Effect } from '../effects.js';
 import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { SaslResult } from '../ports.js';
 import { decodeBase64 } from '../protocol/base64.js';
 import { Numerics } from '../protocol/numerics.js';
 import { hostmaskOf } from '../state/connection.js';
@@ -38,8 +42,17 @@ const SASL_CHUNK_BYTES = 400;
 /** Total decoded-payload cap before `905 ERR_SASLTOOLONG`. */
 const SASL_MAX_BYTES = 8192;
 
-/** Mechanisms this server will accept today (advertised verbatim by the cap). */
-const SUPPORTED_MECHS = 'PLAIN,EXTERNAL';
+/**
+ * Mechanisms advertised in `908 ERR_SASLMECHS` and the `sasl` cap value,
+ * derived from whether mTLS is configured for this connection.
+ *
+ * PLAIN is always available; EXTERNAL only when an `MtlsIdentityProvider`
+ * is bound. Operators enable EXTERNAL by configuring mTLS at the edge
+ * — no code change required.
+ */
+function supportedMechs(ctx: Ctx): string {
+  return ctx.mtlsIdentity !== undefined ? 'PLAIN,EXTERNAL' : 'PLAIN';
+}
 
 /**
  * Reducer for `AUTHENTICATE [<param>]`. See module docs for the state
@@ -93,7 +106,12 @@ function handleMechanism(
     return { state, effects: [Effect.send(ctx.connId, [L('AUTHENTICATE +')])] };
   }
   if (mech === 'EXTERNAL') {
-    return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };
+    if (ctx.mtlsIdentity === undefined) {
+      return { state, effects: [Effect.send(ctx.connId, [saslMechs(ctx)])] };
+    }
+    state.saslMech = 'EXTERNAL';
+    state.saslBuffer = '';
+    return { state, effects: [Effect.send(ctx.connId, [L('AUTHENTICATE +')])] };
   }
   return { state, effects: [Effect.send(ctx.connId, [saslMechs(ctx)])] };
 }
@@ -131,6 +149,18 @@ function finalize(
   payloadB64: string,
   mech: string,
   ctx: Ctx,
+): { state: ConnectionState; effects: EffectType[] } {
+  if (mech === 'EXTERNAL') {
+    return finalizeExternal(state, ctx);
+  }
+  return finalizePlain(state, payloadB64, ctx);
+}
+
+/** SASL PLAIN: decode base64 payload, verify username/password. */
+function finalizePlain(
+  state: ConnectionState,
+  payloadB64: string,
+  ctx: Ctx,
 ): { state: ConnectionState; effects: EffectType[] } {
   const parsed = parsePlain(payloadB64);
 
@@ -145,12 +175,45 @@ function finalize(
     return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };
   }
 
-  const result = store.verify(mech, {
+  const result = store.verify('PLAIN', {
     kind: 'PLAIN',
     username: parsed.username,
     password: parsed.password,
   });
 
+  return applyResult(state, result, ctx);
+}
+
+/** SASL EXTERNAL: resolve the mTLS cert subject and verify it. */
+function finalizeExternal(
+  state: ConnectionState,
+  ctx: Ctx,
+): { state: ConnectionState; effects: EffectType[] } {
+  const provider = ctx.mtlsIdentity;
+  const identity = provider?.getIdentity(ctx.connId);
+
+  if (identity === undefined) {
+    clearSasl(state);
+    return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };
+  }
+
+  const store = ctx.accounts;
+  if (store === undefined) {
+    clearSasl(state);
+    return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };
+  }
+
+  const result = store.verify('EXTERNAL', { kind: 'EXTERNAL', identity });
+
+  return applyResult(state, result, ctx);
+}
+
+/** Shared success/failure handling after a `verify` call. */
+function applyResult(
+  state: ConnectionState,
+  result: SaslResult,
+  ctx: Ctx,
+): { state: ConnectionState; effects: EffectType[] } {
   clearSasl(state);
 
   if (result.ok) {
@@ -228,7 +291,7 @@ function saslAlready(ctx: Ctx): RawLine {
 
 function saslMechs(ctx: Ctx): RawLine {
   return L(
-    `:${ctx.serverName} ${code(Numerics.ERR_SASLMECHS)} ${nickOf(ctx)} ${SUPPORTED_MECHS} :are the available SASL mechanisms`,
+    `:${ctx.serverName} ${code(Numerics.ERR_SASLMECHS)} ${nickOf(ctx)} ${supportedMechs(ctx)} :are the available SASL mechanisms`,
   );
 }
 

package/packages/irc-core/src/commands/server-info.ts

@@ -0,0 +1,129 @@
+/**
+ * Pure reducers for the server-information query commands `VERSION`, `TIME`,
+ * `ADMIN`, and `INFO`.
+ *
+ * PLAN §2.1 location-of-authority: these are read-only Connection-entity
+ * commands — they do not mutate connection or channel state, only emit
+ * `Send` numeric replies addressed to the requester. Each is a thin
+ * config/clock-derived reply, so they share a numeric-formatting helper.
+ *
+ * Wire format (RFC 1459/2812):
+ *   - `VERSION [server]` → `351 RPL_VERSION`:
+ *     `:<server> 351 <nick> <version> <server> :<comments>`
+ *   - `TIME [server]` → `391 RPL_TIME`:
+ *     `:<server> 391 <nick> <server> :<human-readable time>`
+ *   - `ADMIN [server]` → `256 RPL_ADMINME`:
+ *     `:<server> 256 <nick> <server> :Administrative info`
+ *   - `INFO [server]` → `371 RPL_INFO` ×N + `374 RPL_ENDOFINFO`:
+ *     `:<server> 371 <nick> :<info line>`
+ *     `:<server> 374 <nick> :End of INFO list`
+ *
+ * The optional `<server>` target parameter is ignored on all four: this is a
+ * single-server implementation (PLAN §1 non-goal: no S2S linking), so a
+ * request addressed to another server still gets the local info.
+ */
+
+import { resolveServerVersion } from '../config.js';
+import { Effect } from '../effects.js';
+import type { RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer, ReducerResult } from '../types.js';
+
+/** Fixed trailing text for `256 RPL_ADMINME`. */
+const ADMINME_TRAILING_TEXT = 'Administrative info';
+
+/** Fixed trailing text for `374 RPL_ENDOFINFO`. */
+const ENDOFINFO_TRAILING_TEXT = 'End of INFO list';
+
+/**
+ * Handles `VERSION [server]`. Emits `351 RPL_VERSION` with the server version,
+ * server name, and network name as the comment.
+ */
+export const versionReducer: Reducer<ConnectionState> = (state, _msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const nick = ctx.connection.nick ?? '*';
+  const version = resolveServerVersion(ctx.serverConfig);
+  const line: RawLine = numericLine(
+    ctx,
+    Numerics.RPL_VERSION,
+    nick,
+    `${version} ${ctx.serverName} :${ctx.networkName}`,
+  );
+  return {
+    state,
+    effects: [Effect.send(ctx.connId, [line])],
+  };
+};
+
+/**
+ * Handles `TIME [server]`. Emits `391 RPL_TIME` with an ISO-8601 timestamp
+ * derived from the injected {@link Clock} (deterministic under the fake clock).
+ */
+export const timeReducer: Reducer<ConnectionState> = (state, _msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const nick = ctx.connection.nick ?? '*';
+  const iso = new Date(ctx.clock.now()).toISOString();
+  const line = numericLine(ctx, Numerics.RPL_TIME, nick, `${ctx.serverName} :${iso}`);
+  return {
+    state,
+    effects: [Effect.send(ctx.connId, [line])],
+  };
+};
+
+/**
+ * Handles `ADMIN [server]`. Emits `256 RPL_ADMINME` with the server name.
+ * No admin contact info is configured in v1, so the deeper `257`/`258`/`259`
+ * numerics are omitted (the server has no admin-email data to report).
+ */
+export const adminReducer: Reducer<ConnectionState> = (state, _msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const nick = ctx.connection.nick ?? '*';
+  const line = numericLine(
+    ctx,
+    Numerics.RPL_ADMINME,
+    nick,
+    `${ctx.serverName} :${ADMINME_TRAILING_TEXT}`,
+  );
+  return {
+    state,
+    effects: [Effect.send(ctx.connId, [line])],
+  };
+};
+
+/**
+ * Handles `INFO [server]`. Emits one or more `371 RPL_INFO` lines with
+ * server metadata followed by the `374 RPL_ENDOFINFO` terminator.
+ */
+export const infoReducer: Reducer<ConnectionState> = (
+  state,
+  _msg,
+  ctx,
+): ReducerResult<ConnectionState> => {
+  state.lastSeen = ctx.clock.now();
+
+  const nick = ctx.connection.nick ?? '*';
+  const version = resolveServerVersion(ctx.serverConfig);
+  const out: RawLine[] = [
+    numericLine(ctx, Numerics.RPL_INFO, nick, `:ServerlessIRCd - version ${version}`),
+    numericLine(ctx, Numerics.RPL_INFO, nick, `:Running on network ${ctx.networkName}`),
+    numericLine(ctx, Numerics.RPL_ENDOFINFO, nick, `:${ENDOFINFO_TRAILING_TEXT}`),
+  ];
+  return {
+    state,
+    effects: [Effect.send(ctx.connId, out)],
+  };
+};
+
+/**
+ * Builds `:<server> <code> <nick> <rest>` where `rest` already carries its
+ * own leading colon / spacing for the trailing parameter. This keeps the
+ * three reducers DRY without duplicating the prefix logic.
+ */
+function numericLine(ctx: Ctx, code: number, nick: string, rest: string): RawLine {
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: `:${ctx.serverName} ${codeStr} ${nick} ${rest}` };
+}

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/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
@@ -268,3 +305,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;
+  }
+}