serverless-ircd 0.2.0 → 0.4.0

package/apps/local-cli/src/server.ts

@@ -28,14 +28,18 @@ import { randomUUID } from 'node:crypto';
 import { type Server, type Socket, createServer } from 'node:net';
 import { InMemoryRuntime } from '@serverless-ircd/in-memory-runtime';
 import {
+  type AccountStore,
   type AdmissionConfig,
   type ChanName,
   type ConnectionState,
   ConsoleLogger,
+  InMemoryAccountStore,
   InMemoryMessageStore,
+  InMemoryNickHistoryStore,
   LogLevel,
   type Logger,
   type MessageStore,
+  type NickHistoryStore,
   type RawLine,
   createConnection,
 } from '@serverless-ircd/irc-core';
@@ -57,6 +61,7 @@ type ResolvedServerConfig = Omit<
   | 'maxConnectionsPerUser'
   | 'perIpConnectionRate'
   | 'historyMaxPerChannel'
+  | 'saslAccounts'
 > &
   Pick<
     LocalServerConfig,
@@ -65,6 +70,7 @@ type ResolvedServerConfig = Omit<
     | 'maxConnectionsPerIp'
     | 'maxConnectionsPerUser'
     | 'perIpConnectionRate'
+    | 'saslAccounts'
   >;
 
 /** Default per-IP / per-user caps used when callers don't override. */
@@ -121,6 +127,13 @@ export interface LocalServerConfig {
    * CLI — the store is bound unconditionally).
    */
   historyMaxPerChannel?: number;
+  /**
+   * SASL PLAIN account credentials. When non-empty the server seeds an
+   * in-memory {@link AccountStore} so `AUTHENTICATE PLAIN` succeeds for the
+   * listed accounts. When omitted/empty, SASL account verification is
+   * disabled (`ctx.accounts` undefined → `904 ERR_SASLFAIL`).
+   */
+  saslAccounts?: Array<{ username: string; password: string }>;
 }
 
 export interface StartServerOptions extends LocalServerConfig {
@@ -151,6 +164,12 @@ export interface LocalServer {
    * one client is replayable by another. Exposed for test assertions.
    */
   readonly messages: MessageStore;
+  /**
+   * The per-process nick-history store backing `WHOWAS`. Shared across
+   * every connection so a nick signed off by one client is queryable by
+   * another. Exposed for test assertions.
+   */
+  readonly history: NickHistoryStore;
   close(): Promise<void>;
   /**
    * Test-only seam: live server-side WebSockets. Exposed so tests can
@@ -178,6 +197,7 @@ const DEFAULT_CONFIG: Omit<
   | 'maxConnectionsPerUser'
   | 'perIpConnectionRate'
   | 'historyMaxPerChannel'
+  | 'saslAccounts'
 > = {
   serverName: 'irc.example.com',
   networkName: 'ExampleNet',
@@ -242,6 +262,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
       ...(opts.channelLen !== undefined ? { channelLen: opts.channelLen } : {}),
       ...(opts.topicLen !== undefined ? { topicLen: opts.topicLen } : {}),
       ...(opts.quitMessage !== undefined ? { quitMessage: opts.quitMessage } : {}),
+      ...(opts.saslAccounts !== undefined ? { saslAccounts: opts.saslAccounts } : {}),
     });
   } catch (err) {
     return Promise.reject(err);
@@ -268,6 +289,9 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     ...(opts.perIpConnectionRate !== undefined
       ? { perIpConnectionRate: opts.perIpConnectionRate }
       : {}),
+    ...(opts.saslAccounts !== undefined && opts.saslAccounts.length > 0
+      ? { saslAccounts: opts.saslAccounts }
+      : {}),
   };
   const hostname = opts.hostname ?? '127.0.0.1';
 
@@ -295,6 +319,20 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
   // is replayable when bob queries CHATHISTORY). The cap is config-driven.
   const messages = new InMemoryMessageStore(opts.historyMaxPerChannel);
 
+  // Per-process nick-history store: one TTL-buffer shared by every
+  // connection so cross-connection WHOWAS works (a nick alice quits is
+  // queryable by bob). Driven by the real-system clock so TTL eviction
+  // matches wall time.
+  const history = new InMemoryNickHistoryStore({ now: () => Date.now() });
+
+  // SASL account store: seeded from config so `AUTHENTICATE PLAIN` works
+  // end-to-end. `undefined` (no accounts configured) leaves the actor's
+  // `ctx.accounts` unset, preserving the no-store behaviour.
+  const accounts =
+    cfg.saslAccounts !== undefined && cfg.saslAccounts.length > 0
+      ? new InMemoryAccountStore(cfg.saslAccounts)
+      : undefined;
+
   const wss = new WebSocketServer({ port: opts.port, host: hostname });
   const wsConnections = new Map<WebSocket, ConnectionBindings>();
 
@@ -312,7 +350,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     const admissionRecordId = decision.recordId;
     runtime.commitAdmission(ip, undefined, admissionRecordId);
 
-    const { state, actor } = attachConnection(runtime, cfg, messages, {
+    const { state, actor } = attachConnection(runtime, cfg, messages, accounts, history, {
       sendText: (text) => {
         if (ws.readyState === WebSocket.OPEN) ws.send(text);
       },
@@ -389,7 +427,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
         const admissionRecordId = decision.recordId;
         runtime.commitAdmission(ip, undefined, admissionRecordId);
 
-        const { state, actor } = attachConnection(runtime, cfg, messages, {
+        const { state, actor } = attachConnection(runtime, cfg, messages, accounts, history, {
           sendText: (text) => {
             if (socket.writable) socket.write(text);
           },
@@ -454,6 +492,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
         hostname,
         runtime,
         messages,
+        history,
         testSockets: wss.clients,
         testTcpSockets: tcpSockets,
         close: () =>
@@ -481,6 +520,8 @@ function attachConnection(
   runtime: InMemoryRuntime,
   cfg: ResolvedServerConfig,
   messages: MessageStore,
+  accounts: AccountStore | undefined,
+  history: NickHistoryStore,
   transport: {
     sendText: (text: string) => void;
     closeTransport: () => void;
@@ -523,6 +564,8 @@ function attachConnection(
     ids: DEFAULT_ID_FACTORY,
     motd: { lines: () => cfg.motdLines },
     messages,
+    ...(accounts !== undefined ? { accounts } : {}),
+    history,
     logger,
   });
 
@@ -615,4 +658,4 @@ function stringifyErr(err: unknown): unknown {
 }
 
 // Suppress "ChanName imported but unused" — kept for type re-export ergonomics.
-export type { ChanName, ConnectionState };
+export type { ChanName, ConnectionState, NickHistoryStore };

package/apps/local-cli/tests/e2e.test.ts

@@ -418,3 +418,55 @@ describe('local-cli chathistory end-to-end', () => {
     await srv.close();
   });
 });
+
+describe('local-cli SASL PLAIN end-to-end', () => {
+  /** base64(`\0authcid\0password`) — the PLAIN payload format. */
+  function plainB64(authcid: string, password: string): string {
+    return Buffer.from(`\0${authcid}\0${password}`, 'utf8').toString('base64');
+  }
+
+  it('completes SASL PLAIN with 900/903 for valid seeded creds', async () => {
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      saslAccounts: [{ username: 'sasl-alice', password: 's3cret' }],
+    });
+
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    client.send('CAP REQ :sasl\r\n');
+    await client.waitFor((l) => / CAP \S+ ACK :sasl/.test(l));
+    client.send('AUTHENTICATE PLAIN\r\n');
+    await client.waitFor((l) => l === 'AUTHENTICATE +');
+    client.send(`AUTHENTICATE ${plainB64('sasl-alice', 's3cret')}\r\n`);
+    await client.waitFor((l) => l.includes(' 900 '));
+    const success = await client.waitFor((l) => l.includes(' 903 '));
+    expect(success).toContain(' 903 ');
+    client.send('NICK sasl-alice\r\n');
+    client.send('USER sasl-alice 0 * :Sasl Alice\r\n');
+    client.send('CAP END\r\n');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.close();
+    await srv.close();
+  });
+
+  it('rejects SASL PLAIN with 904 for invalid creds', async () => {
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      saslAccounts: [{ username: 'sasl-bob', password: 'right' }],
+    });
+
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    client.send('CAP REQ :sasl\r\n');
+    await client.waitFor((l) => / CAP \S+ ACK :sasl/.test(l));
+    client.send('AUTHENTICATE PLAIN\r\n');
+    await client.waitFor((l) => l === 'AUTHENTICATE +');
+    client.send(`AUTHENTICATE ${plainB64('sasl-bob', 'wrong')}\r\n`);
+    const fail = await client.waitFor((l) => l.includes(' 904 '));
+    expect(fail).toContain(' 904 ');
+    await client.close();
+    await srv.close();
+  });
+});

package/package.json

@@ -1,12 +1,23 @@
 {
   "name": "serverless-ircd",
-  "version": "0.2.0",
+  "version": "0.4.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"
+    "node": ">=24"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@vitest/coverage-v8": "^4.1.10",
+    "fast-check": "^3.23.2",
+    "rimraf": "^6.1.3",
+    "tsx": "^4.19.0",
+    "turbo": "^2.10.7",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.6",
+    "vitest": "^4.1.10",
+    "@serverless-ircd/aws-adapter": "0.4.0"
   },
   "scripts": {
     "build": "turbo run build",
@@ -24,18 +35,10 @@
     "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:cf-tcp:staging": "pnpm build && pnpm --filter @serverless-ircd/cf-tcp-container deploy:staging",
+    "deploy:cf-tcp:prod": "pnpm build && pnpm --filter @serverless-ircd/cf-tcp-container 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.4.0",
   "private": true,
   "description": "AWS Lambda + DynamoDB adapter: AwsRuntime implementing IrcRuntime + $connect/$disconnect/$default handlers",
   "license": "BSD-3-Clause",
@@ -38,7 +38,7 @@
     "@serverless-ircd/irc-test-support": "workspace:*",
     "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^4.1.0",
-    "aws-cdk-lib": "^2.160.0",
+    "aws-cdk-lib": "^2.262.0",
     "aws-sdk-client-mock": "^4.1.0",
     "constructs": "^10.4.0",
     "rimraf": "^6.0.0",
@@ -47,6 +47,6 @@
     "vitest": "^4.1.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   }
 }

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 {
+  DynamoAccountStore,
+  type HashedAccountCredential,
+  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/admission.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure admission policy for the AWS `$connect` handler.
+ *
+ * The I/O (counting live rows in DynamoDB) lives in `handlers/connect.ts`;
+ * the *decision* — "does this count fit under the caps?" — is a pure
+ * function extracted here so it is trivial to unit-test every branch
+ * without standing up DynamoDB Local.
+ *
+ * This is deliberately separate from irc-core's `decideAdmission` /
+ * `AdmissionStats`: that helper is an in-memory counter design that
+ * assumes a single long-lived process. AWS Lambda invocations are
+ * independent processes with no shared memory, so the authoritative
+ * counts MUST come from DynamoDB (the shared `Connections` table) and
+ * are fed into this pure policy.
+ */
+
+/**
+ * Live connection counts gathered from DynamoDB.
+ *
+ *   - `total` is always supplied (a paginated `Scan COUNT` over
+ *     `Connections`).
+ *   - `perIp` is optional: counting connections per source IP needs a
+ *     GSI on `sourceIp` (see `handlers/connect.ts` for the deferred
+ *     per-IP follow-up). Until that lands, callers omit `perIp` and the
+ *     per-IP branch of {@link decideConnectAdmission} is skipped.
+ */
+export interface ConnectionCounts {
+  readonly total: number;
+  readonly perIp?: number;
+}
+
+/**
+ * Effective caps sourced from {@link ParsedServerConfig}. `perIp` is
+ * optional because per-IP enforcement is not yet wired on the AWS path.
+ */
+export interface AdmissionLimits {
+  readonly maxClients: number;
+  readonly maxConnectionsPerIp?: number;
+}
+
+/**
+ * Outcome of an admission decision. Mirrors the {@link ConnectOutcome}
+ * shape returned by `handleConnect` so the handler can return the
+ * decision verbatim.
+ */
+export type AdmissionOutcome =
+  | { readonly admitted: true }
+  | { readonly admitted: false; readonly statusCode: number; readonly reason: string };
+
+/**
+ * Decides whether a new connection should be admitted given the live
+ * counts and the configured caps. Pure: same inputs ⇒ same output, no
+ * ambient state.
+ *
+ * Precedence: the global `maxClients` cap is checked first (it is the
+ * cheap, always-available gate), then the optional per-IP cap when both
+ * the limit and the `perIp` count are present.
+ */
+export function decideConnectAdmission(
+  counts: ConnectionCounts,
+  limits: AdmissionLimits,
+): AdmissionOutcome {
+  if (counts.total >= limits.maxClients) {
+    return { admitted: false, statusCode: 429, reason: 'server full' };
+  }
+  if (
+    limits.maxConnectionsPerIp !== undefined &&
+    counts.perIp !== undefined &&
+    counts.perIp >= limits.maxConnectionsPerIp
+  ) {
+    return { admitted: false, statusCode: 429, reason: 'too many connections from this IP' };
+  }
+  return { admitted: true };
+}

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

@@ -80,7 +80,8 @@ import type { TablesConfig } from './tables.js';
  *     is the in-memory `received` array.
  *   - `disconnect(reason?)` closes the bound transport. In Lambda this
  *     is a no-op — the canonical disconnect path is the APIGW `$disconnect`
- *     route, which fires after the socket is already gone.
+ *     route, which fires after the socket is already gone. See
+ *     `docs/AWS-Deployment.md` §14.1 for the full platform-limit write-up.
  *   - `snapshot()` returns the in-memory ConnectionState the actor is
  *     mutating this frame. Critical so `getConnection(boundId)` returns
  *     the live view (and dispatch's reducer-observable effects see
@@ -185,11 +186,12 @@ export class AwsRuntime implements IrcRuntime {
       this.handlers.disconnect(reason);
       return;
     }
-    // Cross-connection disconnect is a no-op in 040: the Lambda runtime
-    // cannot directly close another connection's WebSocket. The canonical
+    // Cross-connection disconnect is a no-op: the Lambda runtime cannot
+    // directly close another connection's WebSocket. The canonical
     // disconnect path is the APIGW `$disconnect` route, which fires when
     // the socket is already gone. KICK/PART remove membership rows but
-    // do not need to force-close the socket.
+    // do not need to force-close the socket. See docs/AWS-Deployment.md
+    // §14.1 for the full platform-limit write-up and the mitigations.
   }
 
   async sendToNick(
@@ -627,56 +629,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[];
 }
 
 // ---------------------------------------------------------------------------