serverless-ircd 0.3.0 → 0.4.0

package/packages/cf-adapter/src/d1-account-store.ts

@@ -0,0 +1,198 @@
+/**
+ * D1-backed SASL account store primitives for the Cloudflare adapter.
+ *
+ * Mirrors the AWS `dynamo-account-store.ts` / `account-store.ts` pair:
+ * credentials are stored as scrypt hashes (never plaintext) in a D1
+ * `accounts` table and pre-loaded at {@link ConnectionDO} construction
+ * into the shared {@link HashedAccountStore}.
+ *
+ * Table-then-config precedence is implemented by {@link resolveAccountStore}:
+ * when the D1 table has rows it is authoritative; when it is empty (or
+ * unreachable, or the binding is absent) the code falls back to the
+ * `SASL_ACCOUNTS` env-var seed — preserving the config-seed behaviour for
+ * deployments that have not migrated to D1.
+ *
+ * The adapters diverge only at the scan/put boundary; the hashing helpers
+ * and the synchronous {@link HashedAccountStore} are shared via `irc-core`.
+ */
+
+import {
+  type AccountStore,
+  type HashedAccountCredential,
+  HashedAccountStore,
+  InMemoryAccountStore,
+  hashAccountCredential,
+} from '@serverless-ircd/irc-core';
+
+/**
+ * SQL to create the `accounts` table. Exported so the seed tool and
+ * provisioning docs reference one schema definition.
+ */
+export const CREATE_ACCOUNTS_TABLE_SQL =
+  'CREATE TABLE IF NOT EXISTS accounts (account TEXT PRIMARY KEY, algorithm TEXT NOT NULL, salt TEXT NOT NULL, hash TEXT NOT NULL)';
+
+/**
+ * A raw D1 row — the untyped shape returned by `prepare().all()`. Each
+ * column is `unknown` until validated into a {@link HashedAccountCredential}.
+ */
+type AccountsRow = Record<string, unknown>;
+
+/**
+ * Coerces a raw D1 row into a {@link HashedAccountCredential}, or returns
+ * `undefined` when the row is missing required columns or has the wrong
+ * types. Mirrors the silent-skip behaviour of the DynamoDB loader.
+ */
+function coerceRow(row: AccountsRow): HashedAccountCredential | undefined {
+  const { account, algorithm, salt, hash } = row;
+  if (
+    typeof account !== 'string' ||
+    typeof algorithm !== 'string' ||
+    typeof salt !== 'string' ||
+    typeof hash !== 'string'
+  ) {
+    return undefined;
+  }
+  return {
+    account,
+    algorithm: algorithm as HashedAccountCredential['algorithm'],
+    salt,
+    hash,
+  };
+}
+
+/**
+ * Queries the D1 `accounts` table and returns a fully-populated
+ * {@link HashedAccountStore}, or `undefined` when the table has no rows.
+ *
+ * Rows missing required attributes are silently skipped. Callers that need
+ * the table-then-config fallback should use {@link resolveAccountStore}
+ * rather than catching `undefined` themselves.
+ *
+ * @param db The D1 binding (may be `undefined` when D1 is not configured).
+ */
+export async function loadD1AccountStore(
+  db: D1Database | undefined,
+): Promise<HashedAccountStore | undefined> {
+  if (db === undefined) return undefined;
+  const result = await db
+    .prepare('SELECT account, algorithm, salt, hash FROM accounts')
+    .all<AccountsRow>();
+  const entries: HashedAccountCredential[] = [];
+  for (const row of result.results ?? []) {
+    const entry = coerceRow(row);
+    if (entry !== undefined) entries.push(entry);
+  }
+  if (entries.length === 0) return undefined;
+  return new HashedAccountStore(entries);
+}
+
+/**
+ * Writes (or re-seeds) a SASL PLAIN account into the D1 `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(
+  db: D1Database,
+  username: string,
+  password: string,
+): Promise<HashedAccountCredential> {
+  const entry = hashAccountCredential(username, password);
+  await db
+    .prepare('INSERT OR REPLACE INTO accounts (account, algorithm, salt, hash) VALUES (?, ?, ?, ?)')
+    .bind(entry.account, entry.algorithm, entry.salt, entry.hash)
+    .run();
+  return entry;
+}
+
+/**
+ * Builds a self-contained `INSERT OR REPLACE` SQL statement that writes a
+ * scrypt-hashed account row, suitable for `wrangler d1 execute --command`.
+ *
+ * The password is hashed via {@link hashAccountCredential}; the plaintext
+ * never appears in the SQL. The values are single-quoted with embedded
+ * single quotes doubled (`'` → `''`) to avoid injection through the
+ * username or the base64 output.
+ *
+ * This is the pure (non-IO) half of {@link putAccountCredential}; the seed
+ * CLI (`tools/seed-cf-accounts.ts`) calls this and pipes the result to
+ * `wrangler d1 execute`, while the runtime `ConnectionDO` path uses the
+ * bound-parameter {@link putAccountCredential}.
+ *
+ * @returns The hashed credential and the executable SQL string.
+ */
+export function buildAccountPutStatement(
+  username: string,
+  password: string,
+): { entry: HashedAccountCredential; sql: string } {
+  const entry = hashAccountCredential(username, password);
+  const sql = `INSERT OR REPLACE INTO accounts (account, algorithm, salt, hash) VALUES ('${sqlEscape(entry.account)}', '${sqlEscape(entry.algorithm)}', '${sqlEscape(entry.salt)}', '${sqlEscape(entry.hash)}')`;
+  return { entry, sql };
+}
+
+/** Doubles single quotes for safe embedding in a D1 SQL string literal. */
+function sqlEscape(value: string): string {
+  return value.replace(/'/g, "''");
+}
+
+/**
+ * Resolves the SASL account store for a CF deployment, applying the
+ * table-then-config precedence.
+ *
+ *   1. Queries the D1 `accounts` table (pre-loading every hashed credential
+ *      into a {@link HashedAccountStore}). 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 (or the binding is absent), falls back to
+ *      the `SASL_ACCOUNTS` env-var seed (an {@link InMemoryAccountStore})
+ *      so existing deployments that have not migrated to D1 keep working.
+ *   3. Returns `undefined` when neither source has accounts so the actor's
+ *      `ctx.accounts` stays unset (`AUTHENTICATE PLAIN` → `904`).
+ *
+ * Query failures are swallowed and treated as an empty table, falling
+ * through to the config seed — mirroring `resolveAccountStore` on AWS.
+ *
+ * @param db  The D1 binding (`undefined` when D1 is not configured).
+ * @param saslAccountsRaw The raw `SASL_ACCOUNTS` env var (newline-delimited
+ *   `username:password` pairs), or `undefined` when unset.
+ */
+export async function resolveAccountStore(
+  db: D1Database | undefined,
+  saslAccountsRaw: string | undefined,
+): Promise<AccountStore | undefined> {
+  try {
+    const store = await loadD1AccountStore(db);
+    if (store !== undefined) return store;
+  } catch {
+    // Table might not exist yet or be unreachable; fall through to seed.
+  }
+  const seed = parseSeed(saslAccountsRaw);
+  if (seed.length === 0) return undefined;
+  return new InMemoryAccountStore(seed);
+}
+
+/**
+ * Parses the `SASL_ACCOUNTS` env var into credential entries for the
+ * config-seed fallback. Re-exported from the in-memory account-store module
+ * so the precedence resolver is self-contained.
+ */
+function parseSeed(raw: string | undefined): Array<{ username: string; password: string }> {
+  if (raw === undefined || raw.length === 0) return [];
+  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;
+}

package/packages/cf-adapter/src/env.ts

@@ -8,10 +8,11 @@
 
 /**
  * The production {@link Env} for `apps/cf-worker`. ConnectionDO uses the
- * three DO namespaces below to coordinate with the registry and channel
- * authorities. 036 (CfRuntime) is where the full wiring lives;
- * 033 (ConnectionDO) only needs `CONNECTION_DO` itself plus the
- * two collaborator namespaces.
+ * four DO namespaces below to coordinate with the registry, channel, and
+ * channel-registry authorities. The CfRuntime (036) wires them together
+ * behind the platform-agnostic {@link IrcRuntime} port; ConnectionDO
+ * (033) only needs `CONNECTION_DO` itself plus the three collaborator
+ * namespaces.
  *
  * RPC method shapes on {@link RegistryRpc} and {@link ChannelRpc} are
  * implemented by both the production DOs and the test stubs in
@@ -22,17 +23,20 @@ export interface Env {
   CONNECTION_DO: DurableObjectNamespace;
   /**
    * Nick registry authority. RPC: reserveNick / changeNick / releaseNick /
-   * lookupNick. Stubbed now (033); real impl in 034.
+   * lookupNick. Backed by the sharded {@link RegistryDO} (034), which keys
+   * instances by `hash(nick) % N` so the single-threaded DO gives the nick
+   * uniqueness invariant for free.
    *
    * Note: the production DO class is what's brand-typed; here we keep the
-   * namespace unparameterized and cast to the RPC surface at the call
-   * site. The full type plumbing lands with 034.
+   * namespace unparameterized and cast to the RPC surface at the call site.
    */
   REGISTRY_DO: DurableObjectNamespace;
   /**
    * Channel authority, keyed by lowercased channel name. RPC: broadcast /
-   * applyChannelDelta / getChannelSnapshot / listMembers. Stubbed now;
-   * real in 035.
+   * applyChannelDelta / getChannelSnapshot / listMembers. Backed by the
+   * {@link ChannelDO} (035), which owns the authoritative roster, modes,
+   * topic, and ban list and fans out broadcasts to each member's
+   * ConnectionDO.
    */
   CHANNEL_DO: DurableObjectNamespace;
   /**
@@ -42,9 +46,29 @@ export interface Env {
    * unregister / list.
    */
   CHANNEL_REGISTRY_DO: DurableObjectNamespace;
+  /**
+   * D1 database backing persistent SASL account credentials. The `accounts`
+   * table holds scrypt-hashed rows (`{ account PK, algorithm, salt, hash }`),
+   * loaded at {@link ConnectionDO} construction by `loadD1AccountStore`.
+   *
+   * Optional so deployments that have not migrated to D1 keep working: when
+   * unset, the precedence resolver falls straight through to the
+   * `SASL_ACCOUNTS` env-var seed (the legacy `InMemoryAccountStore`).
+   */
+  ACCOUNTS_DB?: D1Database;
   /** Server-level config knobs (name, MOTD lines, limits). */
   SERVER_NAME: string;
   NETWORK_NAME: string;
+  /**
+   * Server version surfaced in `002`/`004`/`351`/`371`. Optional; when unset
+   * the reducer falls back to the irc-core default version.
+   */
+  SERVER_VERSION?: string;
+  /**
+   * "Created" text for `003 RPL_CREATED`. Optional; when unset the reducer
+   * falls back to the default created text.
+   */
+  CREATED_AT?: string;
   MOTD_LINES: string;
   /**
    * SASL PLAIN accounts seeded into the in-worker `AccountStore`.

package/packages/cf-adapter/src/index.ts

@@ -2,14 +2,9 @@
  * @serverless-ircd/cf-adapter
  *
  * Cloudflare Workers adapter for ServerlessIRCd. Implements the three
- * Durable Objects (ConnectionDO, RegistryDO, ChannelDO) and a
- * CfRuntime that bridges them behind the platform-agnostic
- * {@link IrcRuntime} port.
- *
- * 033 shipped the {@link ConnectionDO} + a stub CfRuntime.
- * 034 ships the {@link RegistryDO} (real nick registry with
- * sharding). The {@link ChannelDO} (roster + modes + fanout) ships
- * here. The full CfRuntime lands in 036.
+ * Durable Objects (ConnectionDO, RegistryDO, ChannelDO), the
+ * ChannelRegistryDO index, and a CfRuntime that bridges them behind the
+ * platform-agnostic {@link IrcRuntime} port.
  */
 
 export {
@@ -29,6 +24,12 @@ export {
 export { makeCfRuntime } from './cf-runtime.js';
 export type { CfConnectionHandlers } from './cf-runtime.js';
 export type { ChannelRpc, ChannelRegistryRpc, Env, RegistryRpc } from './env.js';
+export {
+  CREATE_ACCOUNTS_TABLE_SQL,
+  loadD1AccountStore,
+  putAccountCredential,
+  resolveAccountStore,
+} from './d1-account-store.js';
 export {
   PERSISTED_STATE_VERSION,
   STATE_STORAGE_KEY,

package/packages/cf-adapter/tests/cf-harness.ts

@@ -65,7 +65,8 @@ export interface CfHarnessEnv {
  */
 export function makeCfHarnessFactory(opts: CfHarnessFactoryOptions): IrcHarnessFactory {
   return Object.freeze({
-    name: 'cf',
+    name: 'cf+ws',
+    transport: 'ws',
     async create() {
       return new CfHarness(opts);
     },
@@ -204,6 +205,15 @@ class CfClientHandle implements ClientHarness {
     this.ws.send(`${line}\r\n`);
   }
 
+  async feed(chunk: string): Promise<void> {
+    if (this.closed) return;
+    // The CF harness speaks the WebSocket transport end-to-end (a real WS
+    // to a ConnectionDO), so one feed() is one text frame — identical to
+    // send() minus the framing. A CF+tcp factory (Spectrum + container
+    // origin) would route this through a TCP byte stream.
+    this.ws.send(chunk);
+  }
+
   async waitForLine(
     predicate: (line: string) => boolean,
     timeoutMs: number = DEFAULT_TIMEOUT_MS,

package/packages/cf-adapter/tests/cf-integration.test.ts

@@ -62,7 +62,8 @@ afterAll(async () => {
 // guaranteed to be initialized.
 runIrcScenarios([
   {
-    name: 'cf',
+    name: 'cf+ws',
+    transport: 'ws',
     async create() {
       if (factory === undefined) {
         factory = makeCfHarnessFactory({ env });

package/packages/cf-adapter/tests/config-loader.test.ts

@@ -101,6 +101,28 @@ describe('loadServerConfigFromCfEnv — valid env', () => {
     });
     expect(cfg.quitMessage).toBe('Bye from CF');
   });
+
+  it('threads SERVER_VERSION into serverVersion', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), SERVER_VERSION: '1.2.3' });
+    expect(cfg.serverVersion).toBe('1.2.3');
+  });
+
+  it('passes CREATED_AT verbatim when it is non-numeric', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), CREATED_AT: '2024-06-01' });
+    expect(cfg.createdAt).toBe('2024-06-01');
+  });
+
+  it('parses a numeric CREATED_AT string into an epoch-ms number', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), CREATED_AT: '1700000000000' });
+    expect(cfg.createdAt).toBe(1_700_000_000_000);
+  });
+
+  it('applies the schema defaults for serverVersion/createdAt when unset', () => {
+    const cfg = loadServerConfigFromCfEnv(baseEnv());
+    expect(typeof cfg.serverVersion).toBe('string');
+    expect(cfg.serverVersion.length).toBeGreaterThan(0);
+    expect(cfg.createdAt).toBeDefined();
+  });
 });
 
 describe('loadServerConfigFromCfEnv — failure modes', () => {

package/packages/cf-adapter/tests/connection-do-channel-registration.test.ts

@@ -0,0 +1,37 @@
+/**
+ * 085 — CF `webSocketMessage` channel-registration: wire ChannelDO
+ * registration OR remove the dead loop.
+ *
+ * Spike conclusion (documented in the ticket): the dead loop that
+ * iterated `state.joinedChannels` to "register" the ConnectionDO with
+ * each ChannelDO is redundant. Channel membership — and therefore
+ * broadcast fan-out registration — is driven solely by the
+ * `ApplyChannelDelta` effect the joinReducer emits. The CfRuntime
+ * forwards that effect to the authoritative ChannelDO
+ * (`cf-runtime.ts` → `channel-do.ts#applyChannelDelta`), whose roster
+ * is the single source of truth used by `ChannelDO.broadcast`. The
+ * `connection-do.test.ts` "QUIT fanout to each joined channel" test
+ * proves this end-to-end (alice JOINs, closes, and bob observes the
+ * QUIT that only the ChannelDO roster could have routed).
+ *
+ * Because the removed loop was a no-op (`void chan;`), there is no
+ * behaviour to assert — these are source-level regression guards that
+ * prevent the redundant registration loop from creeping back in.
+ */
+
+import { describe, expect, it } from 'vitest';
+import connectionDoSource from '../src/connection-do.ts?raw';
+
+describe('ConnectionDO — no redundant channel-registration loop', () => {
+  it('webSocketMessage contains no dead `void chan` no-op registration body', () => {
+    // The joinReducer's `ApplyChannelDelta` effect is the sole channel
+    // registration path; a per-ConnectionDO loop here is dead code.
+    expect(connectionDoSource).not.toContain('void chan');
+  });
+
+  it('documents that no explicit per-ConnectionDO registration step is needed', () => {
+    // The absence of the loop must be explained so it is not mistaken
+    // for a missing feature.
+    expect(connectionDoSource).toContain('No per-ConnectionDO channel-registration step is needed');
+  });
+});

package/packages/cf-adapter/tests/connection-do-no-batching-reservation.test.ts

@@ -0,0 +1,52 @@
+/**
+ * 087 — CF outbound batching: implement OR drop the reserved optimization.
+ *
+ * Spike conclusion (documented in the ticket): the speculative per-microtask
+ * outbound drain that was reserved as a commented-out field in
+ * `ConnectionDO` is dropped. Per-call batching is already implemented —
+ * `ConnectionDO.deliver()` joins every line of a ChannelDO broadcast into
+ * a single `WebSocket.send()`, and the actor `send` handler
+ * (`buildActor`) joins every line of one frame's response the same way.
+ * What the reservation speculated about was *cross-call* coalescing —
+ * queueing lines emitted by independent `deliver` / `send` invocations
+ * within the same microtask and flushing them in one write. That adds a
+ * drain queue, a `queueMicrotask` scheduler, and ordering hazards between
+ * independent fan-out calls, in exchange for no measured benefit: nothing
+ * in the load-test report or the ChannelDO fan-out path shows WS
+ * round-trips as a bottleneck. The AWS adapter batches at a
+ * different layer (per-invocation `outbound: string[]` accumulated then
+ * posted once), so there is no shared abstraction worth extracting.
+ *
+ * Because the removed reservation was a comment with no runtime
+ * behaviour, these are source-level regression guards (mirroring the
+ * pattern used for other dropped reservations) that prevent the
+ * speculative field from creeping back in and keep the deferral
+ * documented at the point a reader would otherwise expect the batching
+ * hook.
+ */
+
+import { describe, expect, it } from 'vitest';
+import connectionDoSource from '../src/connection-do.ts?raw';
+
+describe('ConnectionDO — no reserved outbound-batching field', () => {
+  it('does not contain the deferred "Reserved for a future batching optimization" comment', () => {
+    // The reservation is dropped; per-call batching in `deliver()` and
+    // the actor `send` handler is the implemented strategy.
+    expect(connectionDoSource).not.toContain('Reserved for a future batching optimization');
+  });
+
+  it('does not reintroduce a speculative outbound-drain field declaration', () => {
+    // Guards against any variant of the commented-out reservation. The
+    // implemented batching is per-call (join lines then `send` once);
+    // there is no instance-level drain queue.
+    expect(connectionDoSource).not.toContain('Outstanding outbound lines');
+    expect(connectionDoSource).not.toContain('drop the reservation');
+  });
+
+  it('documents the deferral decision at the point the reservation used to live', () => {
+    // The absence of the field must be explained so it is not mistaken
+    // for a missing feature, and a reader is pointed at the perf ADR.
+    expect(connectionDoSource).toContain('batched per call');
+    expect(connectionDoSource).toContain('ADR-003');
+  });
+});

package/packages/cf-adapter/tests/connection-do-sasl-d1.test.ts

@@ -0,0 +1,166 @@
+/**
+ * End-to-end SASL PLAIN through ConnectionDO with D1-backed accounts.
+ *
+ * Verifies the full precedence matrix:
+ *   - D1 has rows → table is authoritative (900/903 for seeded account,
+ *     904 for the env-seed account which the table shadows).
+ *   - D1 empty → the `SASL_ACCOUNTS` env-var seed still works (fallback).
+ *
+ * Each test file gets its own isolated D1 database from miniflare, so the
+ * table state set up here does not leak into `connection-do.test.ts`.
+ */
+
+import { env } from 'cloudflare:test';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { CREATE_ACCOUNTS_TABLE_SQL, putAccountCredential } from '../src/d1-account-store';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      CONNECTION_DO: DurableObjectNamespace;
+      REGISTRY_DO: DurableObjectNamespace;
+      CHANNEL_DO: DurableObjectNamespace;
+      ACCOUNTS_DB: D1Database;
+    }
+  }
+}
+
+class IrcWsClient {
+  readonly received: string[] = [];
+  readonly ws: WebSocket;
+
+  constructor(ws: WebSocket) {
+    this.ws = ws;
+    ws.addEventListener('message', (ev: MessageEvent) => {
+      const d = ev.data as string;
+      for (const line of d.split('\r\n')) {
+        if (line.length > 0) this.received.push(line);
+      }
+    });
+  }
+
+  send(line: string): void {
+    this.ws.send(line);
+  }
+
+  waitForMessage(predicate: (line: string) => boolean, timeoutMs = 2000): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      const start = Date.now();
+      const tick = (): void => {
+        const hit = this.received.find(predicate);
+        if (hit !== undefined) {
+          resolve(hit);
+          return;
+        }
+        if (Date.now() - start > timeoutMs) {
+          reject(new Error(`timeout waiting for message; got: ${JSON.stringify(this.received)}`));
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this.ws.addEventListener('close', () => resolve());
+      this.ws.close();
+    });
+  }
+}
+
+async function connect(connId: string): Promise<IrcWsClient> {
+  const doId = env.CONNECTION_DO.idFromName(connId);
+  const stub = env.CONNECTION_DO.get(doId);
+  const response = await stub.fetch('https://do/upgrade', {
+    headers: { Upgrade: 'websocket' },
+  });
+  const ws = response.webSocket;
+  if (ws === undefined || ws === null) {
+    throw new Error('ConnectionDO.fetch did not return a WebSocket');
+  }
+  ws.accept();
+  return new Promise<IrcWsClient>((resolve) => {
+    setTimeout(() => resolve(new IrcWsClient(ws as WebSocket)), 0);
+  });
+}
+
+/** base64(`\0authcid\0password`) — the PLAIN payload format. */
+function plainB64(authcid: string, password: string): string {
+  const raw = `\0${authcid}\0${password}`;
+  let latin1 = '';
+  for (let i = 0; i < raw.length; i++) latin1 += String.fromCharCode(raw.charCodeAt(i));
+  return (globalThis as unknown as { btoa: (s: string) => string }).btoa(latin1);
+}
+
+/** Negotiates `CAP sasl` and sends an AUTHENTICATE PLAIN payload. */
+async function authenticatePlain(
+  client: IrcWsClient,
+  authcid: string,
+  password: string,
+): Promise<void> {
+  client.send('CAP REQ :sasl\r\n');
+  await client.waitForMessage((l) => / CAP \S+ ACK :sasl/.test(l));
+  client.send('AUTHENTICATE PLAIN\r\n');
+  await client.waitForMessage((l) => l === 'AUTHENTICATE +');
+  client.send(`AUTHENTICATE ${plainB64(authcid, password)}\r\n`);
+}
+
+describe('ConnectionDO — SASL PLAIN with D1-backed accounts', () => {
+  beforeEach(async () => {
+    await env.ACCOUNTS_DB.exec(CREATE_ACCOUNTS_TABLE_SQL);
+  });
+  afterEach(async () => {
+    await env.ACCOUNTS_DB.exec('DROP TABLE IF EXISTS accounts');
+  });
+
+  it('completes SASL PLAIN with 900/903 for a D1-seeded account', async () => {
+    await putAccountCredential(env.ACCOUNTS_DB, 'd1-alice', 'd1-s3cret');
+    const client = await connect('conn-d1-sasl-1');
+    await authenticatePlain(client, 'd1-alice', 'd1-s3cret');
+    await client.waitForMessage((l) => l.includes(' 900 '));
+    const success = await client.waitForMessage((l) => l.includes(' 903 '));
+    expect(success).toContain(' 903 ');
+    await client.close();
+  });
+
+  it('rejects SASL PLAIN with 904 for a wrong password (D1 account)', async () => {
+    await putAccountCredential(env.ACCOUNTS_DB, 'd1-alice', 'd1-s3cret');
+    const client = await connect('conn-d1-sasl-2');
+    await authenticatePlain(client, 'd1-alice', 'wrong');
+    const fail = await client.waitForMessage((l) => l.includes(' 904 '));
+    expect(fail).toContain(' 904 ');
+    await client.close();
+  });
+
+  it('table shadows the env-seed account (table wins)', async () => {
+    // SASL_ACCOUNTS env seeds "cf-sasl:s3cret" but D1 has no such row.
+    await putAccountCredential(env.ACCOUNTS_DB, 'd1-alice', 'd1-s3cret');
+    const client = await connect('conn-d1-sasl-3');
+    // env-seed account does NOT verify (table is authoritative).
+    await authenticatePlain(client, 'cf-sasl', 's3cret');
+    const fail = await client.waitForMessage((l) => l.includes(' 904 '));
+    expect(fail).toContain(' 904 ');
+    await client.close();
+  });
+});
+
+describe('ConnectionDO — SASL PLAIN in-memory fallback (D1 empty)', () => {
+  // The table exists but has zero rows → resolver falls back to SASL_ACCOUNTS.
+  beforeEach(async () => {
+    await env.ACCOUNTS_DB.exec(CREATE_ACCOUNTS_TABLE_SQL);
+  });
+  afterEach(async () => {
+    await env.ACCOUNTS_DB.exec('DROP TABLE IF EXISTS accounts');
+  });
+
+  it('falls back to SASL_ACCOUNTS seed when D1 is empty', async () => {
+    const client = await connect('conn-d1-sasl-fallback');
+    await authenticatePlain(client, 'cf-sasl', 's3cret');
+    await client.waitForMessage((l) => l.includes(' 900 '));
+    const success = await client.waitForMessage((l) => l.includes(' 903 '));
+    expect(success).toContain(' 903 ');
+    await client.close();
+  });
+});