serverless-ircd 0.2.0 → 0.3.0

package/docs/Home.md

@@ -1 +1,11 @@
-Welcome to the Wiki.
+Welcome to the Wiki.
+
+## Pages
+
+- [AWS Adapter Architecture](AWS-Adapter-Architecture)
+- [AWS Deployment Guide](AWS-Deployment)
+- [Cloudflare Deployment Guide](Cloudflare-Deployment-Guide)
+- [Observability](Observability)
+- [IRCv3 WebSocket Extension Plan](PlanIRCv3Websocket)
+- [Web Client Plan](PlanWebClient)
+- [Release Process](Release-Process)

package/docs/Release-Process.md

@@ -110,11 +110,15 @@ pnpm typecheck                   # tsc --noEmit across workspace
 pnpm test                        # full suite
 pnpm build                       # every package produces dist/
 
-# 4. Coverage gate.
-#    NOTE: the 90% coverage gate (TICKET-048) is not yet wired in CI.
-#    Until it lands, manually inspect packages/*/coverage/ for regressions
-#    vs. the previous release. Any drop > 2 percentage points blocks the
-#    release unless explicitly justified in CHANGELOG.md.
+# 4. Coverage gate (enforced in CI per package).
+#    The per-package coverage gate (TICKET-048) runs in CI via
+#    `pnpm coverage`; Vitest fails the build on any threshold regression.
+#    Thresholds: 100% (lines/functions/branches/statements) on
+#    irc-core / irc-server / in-memory-runtime, and ≥90% on every
+#    other package (cf-adapter / local-cli / tcp-ws-forwarder). See the
+#    "Coverage gate" step in .github/workflows/ci.yml. CI must already
+#    be green (step 2), so locally re-run `pnpm coverage` as a
+#    belt-and-braces check before tagging.
 
 # 5. Staging smoke e2e passes against the deployed tip-of-main.
 node apps/cf-worker/scripts/smoke.mjs \
@@ -135,7 +139,6 @@ checklist — do not tag over a broken tip.
 - Flood control (TICKET-028).
 - Server password / rate limits / cloaking (TICKET-046).
 - Config loader (TICKET-047).
-- CI coverage gate ≥90% (TICKET-048).
 
 These belong in a later 0.x release. Their absence is **not** a
 blocker and should be called out under "Known limitations" in the

package/package.json

@@ -1,13 +1,22 @@
 {
   "name": "serverless-ircd",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "description": "Serverless IRC daemon with a platform-agnostic core and Cloudflare Workers + AWS adapters",
   "license": "BSD-3-Clause",
-  "packageManager": "pnpm@9.15.9",
   "engines": {
     "node": ">=20"
   },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "fast-check": "^3.19.0",
+    "rimraf": "^6.0.0",
+    "turbo": "^2.0.0",
+    "typescript": "^5.6.0",
+    "vite": "^7.3.0",
+    "vitest": "^4.1.0"
+  },
   "scripts": {
     "build": "turbo run build",
     "typecheck": "turbo run typecheck",
@@ -24,18 +33,8 @@
     "deploy:cf:staging": "pnpm --filter @serverless-ircd/cf-worker deploy:staging",
     "deploy:cf:prod": "pnpm --filter @serverless-ircd/cf-worker deploy:prod",
     "smoke:cf:staging": "pnpm --filter @serverless-ircd/cf-worker smoke:staging",
-    "deploy:aws:staging": "pnpm --filter @serverless-ircd/aws-stack deploy:staging",
-    "deploy:aws:prod": "pnpm --filter @serverless-ircd/aws-stack deploy:prod",
+    "deploy:aws:staging": "pnpm build && pnpm --filter @serverless-ircd/aws-stack deploy:staging",
+    "deploy:aws:prod": "pnpm build && pnpm --filter @serverless-ircd/aws-stack deploy:prod",
     "smoke:aws:staging": "pnpm --filter @serverless-ircd/aws-stack smoke:staging"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^1.9.0",
-    "@vitest/coverage-v8": "^4.1.0",
-    "fast-check": "^3.19.0",
-    "rimraf": "^6.0.0",
-    "turbo": "^2.0.0",
-    "typescript": "^5.6.0",
-    "vite": "^7.3.0",
-    "vitest": "^4.1.0"
   }
-}
+}

package/packages/aws-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-adapter",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "description": "AWS Lambda + DynamoDB adapter: AwsRuntime implementing IrcRuntime + $connect/$disconnect/$default handlers",
   "license": "BSD-3-Clause",

package/packages/aws-adapter/src/account-store.ts

@@ -0,0 +1,121 @@
+/**
+ * SASL account store construction + resolution for the AWS adapter.
+ *
+ * Centralises `AccountStore` creation so the actor-construction site
+ * (`handleDefault`) binds a single helper rather than constructing the
+ * store inline. Two sources of credentials are reconciled here:
+ *
+ *   1. The DynamoDB `Accounts` table (authoritative when populated) —
+ *      loaded at cold start into a {@link DynamoAccountStore} by
+ *      {@link resolveAccountStore}. Credentials are stored as scrypt
+ *      hashes, never plaintext.
+ *   2. The parsed server config (`saslAccounts`, sourced from the
+ *      `SASL_ACCOUNTS` env var) — the legacy/config fallback used only
+ *      when the table is empty, preserving the config-seed behaviour for
+ *      deployments that have not migrated to the table.
+ *
+ * The resolved store is scoped to the Lambda execution context: it
+ * persists across warm invocations (via the memoised `HandlerDeps`) but
+ * is rebuilt on cold start, picking up account changes made since the
+ * last cold start.
+ */
+
+import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import {
+  type AccountStore,
+  InMemoryAccountStore,
+  type ParsedServerConfig,
+} from '@serverless-ircd/irc-core';
+import {
+  type HashedAccountCredential,
+  DynamoAccountStore,
+  hashAccountCredential,
+  loadDynamoAccountStore,
+} from './dynamo-account-store.js';
+
+// Re-export so callers can import everything from one module.
+export {
+  DynamoAccountStore,
+  type HashedAccountCredential,
+  hashAccountCredential,
+  loadDynamoAccountStore,
+};
+
+/**
+ * Constructs the config-seeded in-memory account store (the legacy
+ * fallback). Returns `undefined` when no accounts are configured so the
+ * actor's `ctx.accounts` stays unset (preserving the no-store behaviour:
+ * `AUTHENTICATE PLAIN` → `904`).
+ *
+ * @param serverConfig Parsed config carrying the `saslAccounts` seed list.
+ */
+export function bindAccountStore(serverConfig?: ParsedServerConfig): AccountStore | undefined {
+  if (serverConfig === undefined || serverConfig.saslAccounts.length === 0) {
+    return undefined;
+  }
+  return new InMemoryAccountStore(serverConfig.saslAccounts);
+}
+
+/**
+ * Resolves the SASL account store for a deployment, applying the
+ * table-then-config precedence.
+ *
+ *   1. Scans the DynamoDB `Accounts` table (pre-loading every hashed
+ *      credential into a {@link DynamoAccountStore}). When the table has
+ *      one or more rows it is authoritative — the table wins and the
+ *      config seed is ignored.
+ *   2. When the table is empty, falls back to {@link bindAccountStore}
+ *      (the `SASL_ACCOUNTS` env-var seed) so existing deployments that
+ *      have not migrated to the table keep working unchanged.
+ *   3. Returns `undefined` when neither source has accounts (the default)
+ *      so `ctx.accounts` stays unset and `AUTHENTICATE PLAIN` → `904`.
+ *
+ * Scan failures (table not found, network error) are swallowed and
+ * treated as an empty table, falling through to the config seed.
+ *
+ * @param docClient DynamoDB client addressed at the deployment's tables.
+ * @param tableName Physical name of the `Accounts` table for this env.
+ * @param serverConfig Parsed config (the config-seed fallback source).
+ */
+export async function resolveAccountStore(
+  docClient: DynamoDBDocumentClient,
+  tableName: string,
+  serverConfig?: ParsedServerConfig,
+): Promise<AccountStore | undefined> {
+  try {
+    const store = await loadDynamoAccountStore(docClient, tableName);
+    if (store !== undefined) return store;
+  } catch {
+    // Table might not exist or be unreachable; fall through to config seed.
+  }
+  return bindAccountStore(serverConfig);
+}
+
+/**
+ * Writes (or re-seeds) a SASL PLAIN account into the `Accounts` table.
+ *
+ * The password is hashed via {@link hashAccountCredential} (scrypt,
+ * random salt) and stored as a {@link HashedAccountCredential} row —
+ * plaintext is never written. A repeat call for the same `username`
+ * overwrites the prior row (the PK is `account`), so this is the
+ * canonical CRUD/seed entry point for oper and SASL account
+ * provisioning.
+ *
+ * @returns The stored {@link HashedAccountCredential} (for tooling/tests).
+ */
+export async function putAccountCredential(
+  docClient: DynamoDBDocumentClient,
+  tableName: string,
+  username: string,
+  password: string,
+): Promise<HashedAccountCredential> {
+  const entry = hashAccountCredential(username, password);
+  await docClient.send(
+    new PutCommand({
+      TableName: tableName,
+      Item: entry,
+    }),
+  );
+  return entry;
+}

package/packages/aws-adapter/src/aws-runtime.ts

@@ -627,56 +627,144 @@ export class AwsRuntime implements IrcRuntime {
 
 /**
  * Tears down a connection: deletes its Connections row, removes every
- * ChannelMembers row owned by it, and releases its nick (if any).
+ * ChannelMembers row owned by it, releases its nick (if any), and — when
+ * a `managementApi` is supplied — broadcasts a `QUIT` line to every peer
+ * that shares a channel with the disconnecting connection.
  *
  * Idempotent: every step tolerates a missing row. Safe to call from
- * `$disconnect`, from the `send` GoneException path, and from the
- * future sweeper Lambda.
+ * `$disconnect`, from the `send`/`broadcast` `GoneException` path, and
+ * from the sweeper Lambda.
  *
- * `managementApi` is optional because the cleanup path itself does not
- * send WebSocket bytes (the socket is, by definition, gone).
+ * Recursion safety: the Connections row is deleted *before* the QUIT
+ * fanout so a recursive `cleanupConnection` triggered by a gone peer
+ * during fanout finds the row already gone and returns immediately —
+ * no unbounded recursion.
+ *
+ * `managementApi` is optional because callers that never need fanout
+ * (the sweeper Lambda, or a no-op test) may pass `null`.
  */
 export async function cleanupConnection(
   dynamo: DynamoDBDocumentClient,
   tables: TablesConfig,
   connId: ConnId,
   managementApi: ApiGatewayManagementApi | PostToConnection | null,
+  quitMessage = 'Client Quit',
 ): Promise<void> {
-  void managementApi; // reserved for a future "broadcast QUIT to peers" step
   const connRow = await dynamo.send(
     new GetCommand({ TableName: tables.Connections, Key: { connectionId: connId } }),
   );
   const item = connRow.Item as unknown as MarshalledConnection | undefined;
-  if (item !== undefined) {
-    if (item.nick !== undefined) {
-      try {
-        await dynamo.send(
-          new DeleteCommand({
-            TableName: tables.Nicks,
-            Key: { nickLower: item.nick.toLowerCase() },
-          }),
-        );
-      } catch {
-        // Idempotent — the nick may have been released already.
-      }
+  if (item === undefined) return; // idempotent — already cleaned up
+
+  // Delete the Connections row FIRST. A recursive cleanup triggered by
+  // a gone peer during QUIT fanout reads this same row, finds it gone,
+  // and returns — bounding the recursion at one extra hop.
+  await dynamo.send(
+    new DeleteCommand({ TableName: tables.Connections, Key: { connectionId: connId } }),
+  );
+
+  if (item.nick !== undefined) {
+    try {
+      await dynamo.send(
+        new DeleteCommand({
+          TableName: tables.Nicks,
+          Key: { nickLower: item.nick.toLowerCase() },
+        }),
+      );
+    } catch {
+      // Idempotent — the nick may have been released already.
+    }
+  }
+
+  // Broadcast QUIT to peers in shared channels *before* removing the
+  // disconnecting connection's membership rows — the roster query needs
+  // those rows to resolve the fanout targets.
+  if (item.nick !== undefined && managementApi !== null) {
+    await broadcastQuitToChannels(dynamo, tables, connId, item, managementApi, quitMessage);
+  }
+
+  const joined = item.joinedChannels ?? [];
+  for (const chan of joined) {
+    try {
+      await dynamo.send(
+        new DeleteCommand({
+          TableName: tables.ChannelMembers,
+          Key: { channelName: chan.toLowerCase(), connectionId: connId },
+        }),
+      );
+    } catch {
+      // Idempotent — the membership may have been removed already.
     }
-    const joined = item.joinedChannels ?? [];
-    for (const chan of joined) {
+  }
+}
+
+/**
+ * Builds the canonical `:nick!user@host QUIT :<reason>` line for the
+ * disconnecting connection and fans it out to every *other* member of
+ * each channel the connection had joined. A peer whose APIGW socket is
+ * already gone raises `GoneException`, which is caught and routed back
+ * through {@link cleanupConnection} for lazy cleanup — a partially
+ * torn-down roster never crashes the fanout loop.
+ *
+ * Shared by both the `$disconnect` route and the `send()`/`broadcast()`
+ * `GoneException` cleanup path.
+ */
+async function broadcastQuitToChannels(
+  dynamo: DynamoDBDocumentClient,
+  tables: TablesConfig,
+  connId: ConnId,
+  item: MarshalledConnection,
+  managementApi: ApiGatewayManagementApi | PostToConnection,
+  quitMessage: string,
+): Promise<void> {
+  const hostmask = buildHostmask(item);
+  if (hostmask === undefined) return; // no nick → nothing to attribute the QUIT to
+  const line = `:${hostmask} QUIT :${quitMessage}`;
+  const joined = item.joinedChannels ?? [];
+  for (const chan of joined) {
+    const members = await queryChannelMembersRows(dynamo, tables, chan.toLowerCase());
+    for (const member of members) {
+      if (member.connectionId === connId) continue; // never echo to self
       try {
-        await dynamo.send(
-          new DeleteCommand({
-            TableName: tables.ChannelMembers,
-            Key: { channelName: chan.toLowerCase(), connectionId: connId },
-          }),
-        );
-      } catch {
-        // Idempotent — the membership may have been removed already.
+        await managementApi.postToConnection({ ConnectionId: member.connectionId, Data: line });
+      } catch (err: unknown) {
+        if (err instanceof GoneException || isGone(err)) {
+          await cleanupConnection(dynamo, tables, member.connectionId, managementApi, quitMessage);
+        } else {
+          throw err;
+        }
       }
     }
   }
-  await dynamo.send(
-    new DeleteCommand({ TableName: tables.Connections, Key: { connectionId: connId } }),
+}
+
+/**
+ * Builds the `nick!user@host` hostmask from a stored connection row,
+ * omitting the absent parts. Mirrors {@link hostmaskOf} in irc-core but
+ * operates on the marshalled shape (no full unmarshal needed).
+ */
+function buildHostmask(item: MarshalledConnection): string | undefined {
+  if (item.nick === undefined) return undefined;
+  let out: string = item.nick;
+  if (item.user !== undefined) out = `${out}!${item.user}`;
+  if (item.host !== undefined) out = `${out}@${item.host}`;
+  return out;
+}
+
+/** Queries the raw `ChannelMembers` rows for one channel (by lowercased key). */
+async function queryChannelMembersRows(
+  dynamo: DynamoDBDocumentClient,
+  tables: TablesConfig,
+  key: string,
+): Promise<MarshalledChannelMember[]> {
+  const result = await dynamo.send(
+    new QueryCommand({
+      TableName: tables.ChannelMembers,
+      KeyConditionExpression: 'channelName = :k',
+      ExpressionAttributeValues: { ':k': key },
+    }),
   );
+  return (result.Items ?? []) as unknown as MarshalledChannelMember[];
 }
 
 // ---------------------------------------------------------------------------

package/packages/aws-adapter/src/cdk-table-defs.ts

@@ -18,7 +18,11 @@
  *     so a future `TransactWriteItems` can span Connections ↔ membership
  *     atomically. (Atomicity across Connections/ChannelMembers lands in the
  *     membership-transaction follow-up.)
- *   • `Accounts` never stores plaintext credentials (hash only).
+ *   • `Accounts` stores SASL PLAIN credentials as scrypt
+ *     `HashedAccountCredential` rows (`{ account, algorithm, salt,
+ *     hash }`, base64) — never plaintext. Loaded at Lambda cold start
+ *     by `loadDynamoAccountStore` and seeded via
+ *     `putAccountCredential`.
  *   • `Connections.idleSince` is the DynamoDB TTL attribute; idle connections
  *     are reaped automatically in addition to the explicit sweeper.
  */

package/packages/aws-adapter/src/config-loader.ts

@@ -31,6 +31,13 @@ export interface LambdaConfigEnv {
   TOPIC_LEN?: string;
   MAX_LIST_ENTRIES?: string;
   QUIT_MESSAGE?: string;
+  /**
+   * SASL PLAIN accounts. Newline-delimited `username:password` pairs
+   * (same convention as the CF adapter's `SASL_ACCOUNTS`). Parsed into
+   * the `saslAccounts` config field so {@link bindAccountStore} can seed
+   * an `InMemoryAccountStore` at boot.
+   */
+  SASL_ACCOUNTS?: string;
 }
 
 /**
@@ -84,9 +91,32 @@ export function buildLambdaConfigInput(env: LambdaConfigEnv): Record<string, unk
   if (env.QUIT_MESSAGE !== undefined) {
     input.quitMessage = env.QUIT_MESSAGE;
   }
+  if (env.SASL_ACCOUNTS !== undefined && env.SASL_ACCOUNTS.length > 0) {
+    input.saslAccounts = parseSaslAccountsLines(env.SASL_ACCOUNTS);
+  }
   return input;
 }
 
+/**
+ * Parses a newline-delimited `username:password` string into the config's
+ * `saslAccounts` shape. Malformed entries (missing colon, empty fields)
+ * are skipped so a trailing newline or partial edit does not break boot.
+ */
+function parseSaslAccountsLines(raw: string): Array<{ username: string; password: string }> {
+  const out: Array<{ username: string; password: string }> = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    const sep = trimmed.indexOf(':');
+    if (sep <= 0) continue;
+    const username = trimmed.slice(0, sep);
+    const password = trimmed.slice(sep + 1);
+    if (username.length === 0 || password.length === 0) continue;
+    out.push({ username, password });
+  }
+  return out;
+}
+
 /**
  * Loads and validates the server config from a Lambda env. Throws a
  * readable `Error` listing every invalid field on failure.

package/packages/aws-adapter/src/dynamo-account-store.ts

@@ -0,0 +1,156 @@
+/**
+ * DynamoDB-backed {@link AccountStore} primitives for the AWS adapter.
+ *
+ * The `Accounts` DynamoDB table stores SASL PLAIN credentials as
+ * **scrypt hashes** (never plaintext). Each row is a flat
+ * {@link HashedAccountCredential} (`{ account, algorithm, salt, hash }`).
+ *
+ * Two-phase construction keeps the `AccountStore` port synchronous:
+ *   1. {@link loadDynamoAccountStore} (async) scans the table at Lambda
+ *      cold start and returns a fully-populated `DynamoAccountStore`.
+ *   2. `DynamoAccountStore(entries)` (sync constructor) takes the
+ *      pre-loaded entries. The class itself has zero DynamoDB
+ *      coupling — it works equally well with entries from any source.
+ *
+ * This mirrors the pre-load pattern documented in
+ * `irc-core/src/ports.ts` and used by `MotdProvider` / `MessageStore`:
+ * adapters that need an async backend pre-load the data at boot into a
+ * synchronously-readable store.
+ */
+
+import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
+import type { ScanCommandOutput } from '@aws-sdk/client-dynamodb';
+import { ScanCommand } from '@aws-sdk/lib-dynamodb';
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import type { AccountStore, SaslPayload, SaslResult } from '@serverless-ircd/irc-core';
+
+const SCRYPT_KEY_LEN = 64;
+const SALT_LEN = 16;
+
+/**
+ * A single SASL PLAIN credential stored as a scrypt hash.
+ *
+ * Every field is a DynamoDB attribute — this object IS the table row
+ * (plus the PK `account`). `algorithm` is retained so future migrations
+ * to Argon2/bcrypt can be detected and handled gracefully.
+ */
+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` table via `putAccountCredential`.
+ *
+ * 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.
+ */
+export function hashAccountCredential(
+  username: string,
+  password: string,
+  opts?: { salt?: Buffer; 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: 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;
+  let salt: Buffer;
+  let expected: Buffer;
+  try {
+    salt = Buffer.from(entry.salt, 'base64');
+    expected = Buffer.from(entry.hash, 'base64');
+  } catch {
+    return false;
+  }
+  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 from {@link loadDynamoAccountStore}
+ * (or {@link hashAccountCredential} for unit tests).
+ */
+export class DynamoAccountStore 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;
+  }
+}
+
+/**
+ * Scans the `Accounts` table and returns a fully-populated
+ * {@link DynamoAccountStore}, or `undefined` when the table has no rows.
+ *
+ * Handles pagination (`LastEvaluatedKey`) so tables larger than the 1 MB
+ * scan page are fully loaded. Rows missing required attributes are
+ * silently skipped.
+ */
+export async function loadDynamoAccountStore(
+  docClient: DynamoDBDocumentClient,
+  tableName: string,
+): Promise<DynamoAccountStore | undefined> {
+  const entries: HashedAccountCredential[] = [];
+  let exclusiveStartKey: Record<string, unknown> | undefined = undefined;
+  do {
+    const result: ScanCommandOutput = await docClient.send(
+      new ScanCommand({
+        TableName: tableName,
+        ExclusiveStartKey: exclusiveStartKey,
+      }),
+    );
+    for (const item of result.Items ?? []) {
+      const account = typeof item.account === 'string' ? item.account : undefined;
+      const algorithm = typeof item.algorithm === 'string' ? item.algorithm : undefined;
+      const salt = typeof item.salt === 'string' ? item.salt : undefined;
+      const hash = typeof item.hash === 'string' ? item.hash : undefined;
+      if (account !== undefined && algorithm !== undefined && salt !== undefined && hash !== undefined) {
+        entries.push({ account, algorithm: algorithm as HashedAccountCredential['algorithm'], salt, hash });
+      }
+    }
+    exclusiveStartKey = result.LastEvaluatedKey;
+  } while (exclusiveStartKey !== undefined);
+  if (entries.length === 0) return undefined;
+  return new DynamoAccountStore(entries);
+}

package/packages/aws-adapter/src/handlers/default.ts

@@ -12,6 +12,7 @@ import type { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanageme
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import { GetCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
 import {
+  type AccountStore,
   type ChannelState,
   type Clock,
   type ConnectionState,
@@ -46,6 +47,12 @@ export interface DefaultParams {
    * behaviour of callers that have not opted in.
    */
   messages?: MessageStore;
+  /**
+   * SASL account verification source. When omitted the actor runs with
+   * `ctx.accounts` undefined so `AUTHENTICATE PLAIN` fails with `904`
+   * — preserves the behaviour of callers that have not opted in.
+   */
+  accounts?: AccountStore;
   managementApi: ApiGatewayManagementApi | PostToConnection | null;
   /** Injected for tests; defaults to {@link SystemClock}. */
   clock?: Clock;
@@ -116,6 +123,7 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
     ids,
     motd: params.motd,
     ...(params.messages !== undefined ? { messages: params.messages } : {}),
+    ...(params.accounts !== undefined ? { accounts: params.accounts } : {}),
   });
 
   try {