serverless-ircd 0.2.0 → 0.4.0

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

@@ -0,0 +1,205 @@
+/**
+ * Pure reducer for the IRCv3 `message-tags` `TAGMSG` command.
+ *
+ * Spec: https://ircv3.net/specs/extensions/message-tags#the-tagmsg-command
+ *
+ * TAGMSG carries ONLY message tags — no text body. Wire format:
+ *   `@+client-tag=value;vendor/tag=value :nick!user@host TAGMSG #target`
+ *
+ * The command is gated behind the `message-tags` capability: clients that
+ * did not negotiate it see `421 ERR_UNKNOWNCOMMAND` (matching the spec's
+ * permitted "unknown command" fallback, same as `draft/chathistory`).
+ *
+ * After the cap gate passes, TAGMSG follows NOTICE semantics: **no numeric
+ * error replies are ever emitted.** All rejection paths (+n, +m, +b,
+ * missing target) silently return an empty effect list.
+ *
+ * Recording mirrors the PRIVMSG/NOTICE channel path so chathistory replay
+ * (which already handles `command === 'TAGMSG'` in `formatReplayLine`)
+ * picks up TAGMSG lines for free.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import { escapeTagValue } from '../protocol/serializer.js';
+import type { ChannelState } from '../state/channel.js';
+import { hostmaskOf } from '../state/connection.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer } from '../types.js';
+
+/** The cap name advertising message-tags support. */
+const MESSAGE_TAGS_CAP = 'message-tags';
+
+/**
+ * Returns true iff `hostmask` matches the IRC ban mask `mask`. Identical to
+ * the implementation in `privmsg.ts`; duplicated to keep the message path
+ * self-contained (ban-matching consolidation is planned).
+ */
+function matchesBanMask(mask: string, hostmask: string): boolean {
+  let pattern = '^';
+  for (const ch of mask) {
+    if (ch === '*') {
+      pattern += '.*';
+    } else if (ch === '?') {
+      pattern += '.';
+    } else if (/[A-Za-z0-9]/.test(ch)) {
+      pattern += ch;
+    } else {
+      pattern += `\\${ch}`;
+    }
+  }
+  pattern += '$';
+  return new RegExp(pattern, 'i').test(hostmask);
+}
+
+/** 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(' ') };
+}
+
+/** Resolves the sender's hostmask, falling back to nick then `?`. */
+function senderHostmask(conn: ConnectionState): string {
+  return hostmaskOf(conn) ?? conn.nick ?? '?';
+}
+
+/**
+ * Returns true iff `entry` may speak on a moderated channel: ops and voiced
+ * members pass; everyone else is blocked.
+ */
+function maySpeakOnModerated(entry: { op: boolean; voice: boolean } | undefined): boolean {
+  if (entry === undefined) return false;
+  return entry.op || entry.voice;
+}
+
+/**
+ * Serializes `tags` into the `@key=val;… ` wire prefix used by TAGMSG.
+ * Returns an empty string when there are no tags (so the line has no `@…`
+ * prefix at all). A valueless tag (empty string) renders as just the key.
+ */
+function serializeTags(tags: Readonly<Record<string, string>>): string {
+  const entries = Object.entries(tags);
+  if (entries.length === 0) return '';
+  const section = entries
+    .map(([key, value]) => (value === '' ? key : `${key}=${escapeTagValue(value)}`))
+    .join(';');
+  return `@${section} `;
+}
+
+/** Reducer for `TAGMSG <channel>`. Authority: ChannelState. */
+export const tagmsgChannelReducer: Reducer<ChannelState> = (state, msg, ctx) => {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  // Cap gate: clients that did not negotiate message-tags see RFC 2812 only.
+  if (!ctx.connection.caps.has(MESSAGE_TAGS_CAP)) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericErr(ctx, Numerics.ERR_UNKNOWNCOMMAND, 'Unknown command', 'TAGMSG'),
+        ]),
+      ],
+    };
+  }
+
+  const effects: EffectType[] = [];
+
+  const target = msg.params[0];
+
+  // NOTICE-style silence: missing target → empty effects.
+  if (target === undefined) {
+    return { state, effects };
+  }
+
+  const senderEntry = state.members.get(ctx.connId);
+  const hostmask = senderHostmask(ctx.connection);
+
+  // +n (no external messages): sender must be a member. Silent.
+  if (state.modes.noExternal && senderEntry === undefined) {
+    return { state, effects };
+  }
+
+  // +m (moderated): sender must be op or voiced. Silent.
+  if (state.modes.moderated && !maySpeakOnModerated(senderEntry)) {
+    return { state, effects };
+  }
+
+  // +b (ban): sender's hostmask must not match any ban mask. Silent.
+  if (state.banMasks.size > 0) {
+    for (const mask of state.banMasks) {
+      if (matchesBanMask(mask, hostmask)) {
+        return { state, effects };
+      }
+    }
+  }
+
+  // Persist for chathistory playback when a MessageStore is bound.
+  if (ctx.messages !== undefined) {
+    ctx.messages.record({
+      msgid: ctx.ids.nonce(),
+      time: ctx.clock.now(),
+      chan: state.nameLower,
+      command: 'TAGMSG',
+      nick: ctx.connection.nick as string,
+      user: ctx.connection.user as string,
+      host: ctx.connection.host as string,
+      text: '',
+    });
+  }
+
+  // Broadcast the tag-bearing line to message-tags-enabled members only.
+  const tagPrefix = serializeTags(msg.tags);
+  const line: RawLine = { text: `${tagPrefix}:${hostmask} TAGMSG ${state.name}` };
+  effects.push(Effect.broadcast(state.name, [line], ctx.connId, MESSAGE_TAGS_CAP));
+
+  // IRCv3 echo-message: echo the same line back to the sender, after
+  // the broadcast effect so clients observe their own message last.
+  if (ctx.connection.caps.has('echo-message')) {
+    effects.push(Effect.send(ctx.connId, [line]));
+  }
+
+  return { state, effects };
+};
+
+/** Reducer for `TAGMSG <nick>`. Authority: sender's ConnectionState. */
+export const tagmsgUserReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  // Cap gate: clients that did not negotiate message-tags see RFC 2812 only.
+  if (!ctx.connection.caps.has(MESSAGE_TAGS_CAP)) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericErr(ctx, Numerics.ERR_UNKNOWNCOMMAND, 'Unknown command', 'TAGMSG'),
+        ]),
+      ],
+    };
+  }
+
+  const effects: EffectType[] = [];
+
+  const target = msg.params[0];
+
+  // NOTICE-style silence: missing target → empty effects.
+  if (target === undefined) {
+    return { state, effects };
+  }
+
+  const hostmask = senderHostmask(state);
+  const tagPrefix = serializeTags(msg.tags);
+  const line: RawLine = { text: `${tagPrefix}:${hostmask} TAGMSG ${target}` };
+
+  // No notFoundLines — TAGMSG is silent like NOTICE for offline recipients.
+  effects.push(Effect.sendToNick(target, ctx.connId, [line]));
+
+  // IRCv3 echo-message: echo the same line back to the sender, after
+  // the SendToNick effect so clients observe their own message last.
+  if (ctx.connection.caps.has('echo-message')) {
+    effects.push(Effect.send(ctx.connId, [line]));
+  }
+
+  return { state, 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/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

@@ -10,12 +10,14 @@
  *
  * The reducer-facing {@link ServerConfig} (in `types.ts`) is a strict
  * subset of this schema — the reducers do not care about MOTD text,
- * channel-prefix policy, max-clients, or oper creds (those are consumed
- * by adapter-side plumbing: the MOTD provider, the JOIN validator's
- * prefix table, the connection admission gate, and the OPER auth path).
+ * channel-prefix policy, or max-clients (those are consumed by
+ * adapter-side plumbing: the MOTD provider, the JOIN validator's prefix
+ * table, and the connection admission gate). Oper credentials ARE surfaced
+ * on the reducer-facing config so the OPER reducer can authenticate.
  */
 
 import { z } from 'zod';
+import { BUILD_DATE } from './build-info.js';
 
 /**
  * Schema for a single IRC operator credential.
@@ -28,6 +30,17 @@ export const OperCredSchema = z.object({
   password: z.string().min(1),
 });
 
+/**
+ * Schema for a single SASL PLAIN account credential. The `username` is also
+ * the canonical account name recorded on the connection (for `extended-join`
+ * / `account-tag`). Both fields are non-empty strings; adapters seed an
+ * {@link InMemoryAccountStore} from this list at boot.
+ */
+export const SaslAccountSchema = z.object({
+  username: z.string().min(1),
+  password: z.string().min(1),
+});
+
 /**
  * Cloaking configuration. When enabled, the visible hostmask of every
  * connecting client is replaced by `<cloak>.<suffix>` where `<cloak>` is a
@@ -101,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
@@ -112,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
@@ -182,6 +231,17 @@ export const ServerConfigSchema = z.object({
    */
   operCreds: z.array(OperCredSchema).default([]),
 
+  /**
+   * SASL PLAIN account credentials. The adapter seeds an
+   * `InMemoryAccountStore` from this list at boot so `AUTHENTICATE PLAIN`
+   * succeeds end-to-end for the listed accounts. Empty array (the default)
+   * disables SASL account verification: `ctx.accounts` is then omitted and
+   * a client completing `AUTHENTICATE PLAIN` receives `904 ERR_SASLFAIL`.
+   * A persistent variant (DynamoDB `Accounts`, D1) is a documented
+   * follow-up; swapping it in means replacing the construction call.
+   */
+  saslAccounts: z.array(SaslAccountSchema).default([]),
+
   // --- Reducer-facing limit knobs (mirrored on `ServerConfig`) ---
 
   /** Maximum channels a single connection may JOIN. */
@@ -245,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;
+  }
+}