serverless-ircd 0.2.0 → 0.4.0

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

@@ -19,6 +19,17 @@ import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc
 export interface LambdaConfigEnv {
   SERVER_NAME?: string;
   NETWORK_NAME?: string;
+  /**
+   * Server version surfaced in `002`/`004`/`351`/`371`. When unset the
+   * schema default ({@link DEFAULT_SERVER_VERSION}) applies.
+   */
+  SERVER_VERSION?: string;
+  /**
+   * "Created" text for `003 RPL_CREATED`. A numeric string is parsed into
+   * an epoch-ms number so the reducer formats it as a UTC timestamp; any
+   * other value is passed through verbatim.
+   */
+  CREATED_AT?: string;
   MOTD?: string;
   MAX_CLIENTS?: string;
   CHANNEL_PREFIXES?: string;
@@ -31,6 +42,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;
 }
 
 /**
@@ -46,6 +64,12 @@ export function buildLambdaConfigInput(env: LambdaConfigEnv): Record<string, unk
     serverName: env.SERVER_NAME,
     networkName: env.NETWORK_NAME,
   };
+  if (env.SERVER_VERSION !== undefined) {
+    input.serverVersion = env.SERVER_VERSION;
+  }
+  if (env.CREATED_AT !== undefined) {
+    input.createdAt = parseCreatedAt(env.CREATED_AT);
+  }
   if (env.MOTD !== undefined && env.MOTD.length > 0) {
     input.motdLines = env.MOTD.split('\n');
   }
@@ -84,9 +108,47 @@ 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 the `CREATED_AT` env var into the schema's `createdAt` field.
+ *
+ * A purely numeric string is treated as epoch-ms (returned as a number so
+ * the reducer formats it as a UTC timestamp); any other value is returned
+ * verbatim as a human-readable string.
+ */
+function parseCreatedAt(raw: string): string | number {
+  if (/^\d+$/.test(raw.trim())) {
+    const n = Number(raw.trim());
+    if (Number.isFinite(n)) return n;
+  }
+  return raw;
+}
+
+/**
+ * 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,95 @@
+/**
+ * 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.
+ *
+ * The scrypt hashing helpers (`hashAccountCredential` /
+ * `verifyHashedPassword` + the `HashedAccountCredential` type) live in
+ * `irc-core` and are shared with the CF adapter's `D1AccountStore`. They
+ * are re-exported below so existing call sites importing from this module
+ * keep working.
+ */
+
+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 HashedAccountCredential,
+  HashedAccountStore,
+  hashAccountCredential,
+  verifyHashedPassword,
+} from '@serverless-ircd/irc-core';
+
+// Re-export so callers importing these from `@serverless-ircd/aws-adapter`
+// (the historical home of the hashing helpers) keep compiling.
+export { type HashedAccountCredential, hashAccountCredential, verifyHashedPassword };
+
+/**
+ * Synchronous {@link AccountStore} backed by pre-loaded hashed credentials.
+ *
+ * Now a re-export of the shared `HashedAccountStore` from `irc-core` —
+ * both adapters use one store implementation. The AWS-specific surface
+ * (`loadDynamoAccountStore`) lives below; it diverges from CF only at the
+ * scan boundary.
+ */
+export { HashedAccountStore as DynamoAccountStore };
+
+/**
+ * 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<HashedAccountStore | 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 HashedAccountStore(entries);
+}

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

@@ -4,11 +4,18 @@
  * Persists a fresh `Connections` row keyed by the APIGW connection id.
  * Subsequent `$default` invocations load this row, run the actor, and
  * persist the mutated state back.
+ *
+ * Admission gate: before writing the row, the handler counts the live
+ * `Connections` rows and rejects the upgrade with `429 Too Many Requests`
+ * once `serverConfig.maxClients` is reached. A `429` (not `403`) is used
+ * because the rejection is a capacity / back-pressure signal — the client
+ * is welcome to retry — rather than an authorisation failure.
  */
 
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import { PutCommand, ScanCommand } from '@aws-sdk/lib-dynamodb';
 import type { ParsedServerConfig } from '@serverless-ircd/irc-core';
+import { type AdmissionOutcome, decideConnectAdmission } from '../admission.js';
 import { marshalConnection } from '../serialize.js';
 import type { TablesConfig } from '../tables.js';
 import { createInitialConnectionState } from './state.js';
@@ -20,20 +27,43 @@ export interface ConnectParams {
   connectionId: string;
   /** Wall clock used to seed `connectedSince` / `idleSince` (default: now). */
   now?: number;
-  /** Reserved for future use; required so the signature mirrors `$default`. */
-  serverConfig?: ParsedServerConfig;
+  /** Server config — consulted for the `maxClients` admission cap. */
+  serverConfig: ParsedServerConfig;
 }
 
+/** Re-exported so the dispatcher imports the outcome type from one place. */
+export type { AdmissionOutcome as ConnectOutcome } from '../admission.js';
+
 /**
- * Inserts the Connections row for a fresh WebSocket upgrade.
+ * Enforces the `maxClients` admission cap, then inserts the Connections
+ * row for a fresh WebSocket upgrade.
+ *
+ * Idempotent on success: APIGW retries `$connect` on transient failures,
+ * so the write uses `PutCommand` (overwrites) rather than a conditional
+ * insert.
+ *
+ * TOCTOU note: DynamoDB cannot conditionally write based on a row count,
+ * so the count-then-put sequence has a race window. This is an accepted
+ * trade-off for an admission cap — it bounds growth under steady load
+ * rather than enforcing a hard invariant. Two concurrent upgrades that
+ * both observe `count == cap - 1` will both be admitted.
  *
- * Idempotent: APIGW retries `$connect` on transient failures, so we
- * use `PutCommand` (overwrites) rather than a conditional insert.
+ * Per-IP admission (`maxConnectionsPerIp`) is intentionally NOT enforced
+ * here. irc-core's in-memory `AdmissionStats` is unsuitable for Lambda
+ * (each invocation is a fresh process with no shared counters), and a
+ * filtered full-table `Scan` per `$connect` would double the DynamoDB
+ * cost on every connect (and `maxConnectionsPerIp` is on by default).
+ * The correct fix is to persist `sourceIp` on the Connections row and
+ * add a DynamoDB GSI keyed by `sourceIp`, then feed the GSI's count
+ * into {@link decideConnectAdmission}'s `perIp` branch. That schema
+ * change is tracked as a follow-up; the pure policy already supports it.
  */
-export async function handleConnect(params: ConnectParams): Promise<void> {
+export async function handleConnect(params: ConnectParams): Promise<AdmissionOutcome> {
   const now = params.now ?? Date.now();
+  const total = await countConnections(params.dynamo, params.tables.Connections);
+  const outcome = decideConnectAdmission({ total }, { maxClients: params.serverConfig.maxClients });
+  if (!outcome.admitted) return outcome;
   const state = createInitialConnectionState(params.connectionId, now);
-  void params.serverConfig; // reserved for max-clients gating (later ticket)
   const row = marshalConnection(state, now);
   await params.dynamo.send(
     new PutCommand({
@@ -41,4 +71,30 @@ export async function handleConnect(params: ConnectParams): Promise<void> {
       Item: row,
     }),
   );
+  return outcome;
+}
+
+/**
+ * Paginated `Scan` with `Select: COUNT` over the `Connections` table.
+ * A single Scan page caps at 1MB, so the loop follows
+ * `LastEvaluatedKey` until every page has been summed.
+ */
+async function countConnections(
+  dynamo: DynamoDBDocumentClient,
+  tableName: string,
+): Promise<number> {
+  let total = 0;
+  let lastKey: unknown = undefined;
+  do {
+    const res = await dynamo.send(
+      new ScanCommand({
+        TableName: tableName,
+        Select: 'COUNT',
+        ...(lastKey !== undefined ? { ExclusiveStartKey: lastKey as never } : {}),
+      }),
+    );
+    total += res.Count ?? 0;
+    lastKey = res.LastEvaluatedKey;
+  } while (lastKey !== undefined);
+  return total;
 }

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

@@ -12,12 +12,15 @@ 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,
   type IdFactory,
   type MessageStore,
   type MotdProvider,
+  type MtlsIdentityProvider,
+  type NickHistoryStore,
   type ParsedServerConfig,
   SystemClock,
   UuidIdFactory,
@@ -46,6 +49,36 @@ 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;
+  /**
+   * mTLS client-cert identity source for SASL EXTERNAL. When omitted the
+   * actor runs with `ctx.mtlsIdentity` undefined so `AUTHENTICATE EXTERNAL`
+   * fails with `904` — preserves the behaviour of callers that have not
+   * opted in.
+   *
+   * AWS APIGW custom-domain mTLS setup:
+   * 1. Upload a PEM trust store to S3 (the CA bundle clients must present).
+   * 2. Create a custom domain with `mutualTlsAuthentication` pointing at the
+   *    S3 trust store URI.
+   * 3. Map the custom domain to the WebSocket API stage.
+   * 4. The `$connect` event's `requestContext.identity.clientCertSubjectDN`
+   *    carries the verified cert subject — capture it at connect time and
+   *    persist it alongside the connection row, then construct an
+   *    {@link MtlsIdentityProvider} that resolves it by connection ID.
+   */
+  mtlsIdentity?: MtlsIdentityProvider;
+  /**
+   * Nick-history source for the `WHOWAS` command. When omitted the actor
+   * runs with `ctx.history` undefined so `WHOWAS` always returns
+   * `406`+`369` — preserves the behaviour of callers that have not opted
+   * in. A DynamoDB-backed persistent variant is a documented follow-up.
+   */
+  history?: NickHistoryStore;
   managementApi: ApiGatewayManagementApi | PostToConnection | null;
   /** Injected for tests; defaults to {@link SystemClock}. */
   clock?: Clock;
@@ -91,8 +124,13 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
       for (const l of lines) outbound.push(l.text);
     },
     disconnect: () => {
-      // Lambda cannot close its own socket from inside the handler
-      // (the `$disconnect` route fires when APIGW observes the close).
+      // No-op: a Lambda `$default` invocation cannot close its own APIGW
+      // socket. The canonical teardown is the `$disconnect` route (which
+      // fires when APIGW observes the close) plus the sweeper/ping-checker
+      // for connections that vanish without one. The actor's state
+      // mutations (nick release, roster deltas) are persisted below before
+      // this invocation returns, so the eventual `$disconnect` completes
+      // the fanout. See docs/AWS-Deployment.md §14.1.
     },
     snapshot: () => state,
   };
@@ -116,6 +154,9 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
     ids,
     motd: params.motd,
     ...(params.messages !== undefined ? { messages: params.messages } : {}),
+    ...(params.accounts !== undefined ? { accounts: params.accounts } : {}),
+    ...(params.mtlsIdentity !== undefined ? { mtlsIdentity: params.mtlsIdentity } : {}),
+    ...(params.history !== undefined ? { history: params.history } : {}),
   });
 
   try {

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

@@ -2,13 +2,15 @@
  * `$disconnect` handler — Lambda entry for `event.requestContext.routeKey === '$disconnect'`.
  *
  * Tears down the connection via {@link cleanupConnection} — deletes the
- * Connections row, every ChannelMembers row owned by it, and the nick
- * reservation if any. Idempotent: every step tolerates a missing row.
+ * Connections row, every ChannelMembers row owned by it, the nick
+ * reservation if any, and broadcasts a `QUIT` line to every peer sharing
+ * a channel with the disconnecting connection. Idempotent: every step
+ * tolerates a missing row.
  */
 
 import type { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanagementapi';
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-import { cleanupConnection } from '../aws-runtime.js';
+import { type PostToConnection, cleanupConnection } from '../aws-runtime.js';
 import type { TablesConfig } from '../tables.js';
 
 /** Parameters accepted by {@link handleDisconnect}. */
@@ -16,14 +18,31 @@ export interface DisconnectParams {
   dynamo: DynamoDBDocumentClient;
   tables: TablesConfig;
   connectionId: string;
-  /** Reserved for future "broadcast QUIT to peers" work; unused today. */
-  managementApi?: ApiGatewayManagementApi | null;
+  /**
+   * Backend used to push the `QUIT` fanout to peers. `null` skips the
+   * fanout (the socket is already gone, but peers still need the QUIT
+   * line so their rosters prune the ghost member).
+   */
+  managementApi?: ApiGatewayManagementApi | PostToConnection | null;
+  /**
+   * QUIT reason advertised to peers on fanout. Defaults to
+   * `'Client Quit'` (the same default the QUIT reducer uses when a
+   * client sends `QUIT` with no reason).
+   */
+  quitMessage?: string;
 }
 
 /**
- * Cleans up the connection state. Safe to call after APIGW has already
- * torn the WebSocket down — the management API is best-effort only.
+ * Cleans up the connection state and broadcasts QUIT to shared-channel
+ * peers. Safe to call after APIGW has already torn the WebSocket down —
+ * the management API is best-effort only.
  */
 export async function handleDisconnect(params: DisconnectParams): Promise<void> {
-  await cleanupConnection(params.dynamo, params.tables, params.connectionId, null);
+  await cleanupConnection(
+    params.dynamo,
+    params.tables,
+    params.connectionId,
+    params.managementApi ?? null,
+    params.quitMessage,
+  );
 }

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

@@ -14,12 +14,17 @@
 import { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanagementapi';
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import {
+  type AccountStore,
   EmptyMotdProvider,
+  InMemoryNickHistoryStore,
   type MessageStore,
   type MotdProvider,
+  type NickHistoryStore,
   type ParsedServerConfig,
   StaticMotdProvider,
+  SystemClock,
 } from '@serverless-ircd/irc-core';
+import { resolveAccountStore } from '../account-store.js';
 import { type LambdaConfigEnv, loadServerConfigFromLambdaEnv } from '../config-loader.js';
 import { createDynamoDocumentClient } from '../dynamo.js';
 import { bindMessageStore } from '../message-store.js';
@@ -27,6 +32,13 @@ import { TABLE_KEYS, type TablesConfig } from '../tables.js';
 import { handleConnect } from './connect.js';
 import { handleDefault } from './default.js';
 import { handleDisconnect } from './disconnect.js';
+import {
+  type NlbStreamEvent,
+  type NlbStreamParams,
+  type NlbStreamResponse,
+  deriveNlbConnectionId,
+  handleNlbStream,
+} from './nlb-stream.js';
 import {
   DEFAULT_PING_INTERVAL_MS,
   DEFAULT_PONG_TIMEOUT_MS,
@@ -48,6 +60,13 @@ export interface WebSocketEvent {
     connectionId: string;
     domainName?: string;
     stage?: string;
+    /**
+     * Source IP of the connecting client. APIGW populates
+     * `requestContext.identity.sourceIp` on every `$connect`. Carried on
+     * the event type so the (currently deferred) per-IP admission gate
+     * can consume it without reshaping the handler signature.
+     */
+    identity?: { sourceIp?: string };
   };
   body?: string;
 }
@@ -72,6 +91,20 @@ export interface HandlerDeps {
    * DynamoDB-backed variant is a documented follow-up.
    */
   messages: MessageStore;
+  /**
+   * SASL account verification source bound to every actor. Constructed
+   * once per cold start (memoised via {@link cachedDeps}) so it survives
+   * across warm Lambda invocations. `undefined` when no accounts are
+   * configured (the default) so `ctx.accounts` stays unset.
+   */
+  accounts?: AccountStore;
+  /**
+   * Nick-history source bound to every actor. Constructed once per cold
+   * start (memoised via {@link cachedDeps}) as an in-memory store so it
+   * survives across warm Lambda invocations. A DynamoDB-backed persistent
+   * variant is a documented follow-up.
+   */
+  history?: NickHistoryStore;
 }
 
 /**
@@ -90,6 +123,15 @@ export type DefaultEvent = {
 /** Memoised `HandlerDeps`; built on the first cold-start invocation. */
 let cachedDeps: HandlerDeps | undefined;
 
+/**
+ * In-flight cold-start build. `buildDepsFromEnv` is async (it scans the
+ * `Accounts` DynamoDB table for SASL credentials), so under concurrent
+ * warm-up two events could race past the `cachedDeps` check and each
+ * trigger a full scan. Memoising the promise guarantees the scan runs
+ * exactly once per cold start.
+ */
+let cachedDepsPromise: Promise<HandlerDeps> | undefined;
+
 /**
  * The Lambda entry point. Routes on `event.requestContext.routeKey`.
  *
@@ -98,7 +140,11 @@ let cachedDeps: HandlerDeps | undefined;
  */
 export const handler = async (event: WebSocketEvent): Promise<LambdaResponse> => {
   if (cachedDeps === undefined) {
-    cachedDeps = buildDepsFromEnv();
+    if (cachedDepsPromise === undefined) {
+      cachedDepsPromise = buildDepsFromEnv();
+    }
+    cachedDeps = await cachedDepsPromise;
+    cachedDepsPromise = undefined;
   }
   const deps = cachedDeps;
   return dispatch(event, deps);
@@ -110,14 +156,16 @@ export const handler = async (event: WebSocketEvent): Promise<LambdaResponse> =>
 export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promise<LambdaResponse> {
   const connId = event.requestContext.connectionId;
   switch (event.requestContext.routeKey) {
-    case '$connect':
-      await handleConnect({
+    case '$connect': {
+      const outcome = await handleConnect({
         dynamo: deps.dynamo,
         tables: deps.tables,
         connectionId: connId,
         serverConfig: deps.serverConfig,
       });
-      return { statusCode: 200 };
+      if (outcome.admitted) return { statusCode: 200 };
+      return { statusCode: outcome.statusCode, body: outcome.reason };
+    }
 
     case '$disconnect':
       await handleDisconnect({
@@ -125,6 +173,7 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
         tables: deps.tables,
         connectionId: connId,
         managementApi: deps.managementApi,
+        quitMessage: deps.serverConfig.quitMessage,
       });
       return { statusCode: 200 };
 
@@ -141,6 +190,8 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
           serverConfig: deps.serverConfig,
           motd: deps.motd,
           messages: deps.messages,
+          ...(deps.accounts !== undefined ? { accounts: deps.accounts } : {}),
+          ...(deps.history !== undefined ? { history: deps.history } : {}),
           managementApi: deps.managementApi,
         });
         return result;
@@ -159,6 +210,7 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
  */
 export function __resetHandlerCacheForTests(): void {
   cachedDeps = undefined;
+  cachedDepsPromise = undefined;
 }
 
 /**
@@ -172,7 +224,11 @@ export function __resetHandlerCacheForTests(): void {
  */
 export async function sweeperHandler(_event: unknown): Promise<SweepResult> {
   if (cachedDeps === undefined) {
-    cachedDeps = buildDepsFromEnv();
+    if (cachedDepsPromise === undefined) {
+      cachedDepsPromise = buildDepsFromEnv();
+    }
+    cachedDeps = await cachedDepsPromise;
+    cachedDepsPromise = undefined;
   }
   const deps = cachedDeps;
   return handleSweep({ dynamo: deps.dynamo, tables: deps.tables });
@@ -190,7 +246,11 @@ export async function sweeperHandler(_event: unknown): Promise<SweepResult> {
  */
 export async function pingCheckerHandler(_event: unknown): Promise<PingCheckResult> {
   if (cachedDeps === undefined) {
-    cachedDeps = buildDepsFromEnv();
+    if (cachedDepsPromise === undefined) {
+      cachedDepsPromise = buildDepsFromEnv();
+    }
+    cachedDeps = await cachedDepsPromise;
+    cachedDepsPromise = undefined;
   }
   const deps = cachedDeps;
   return handlePingCheck({
@@ -212,13 +272,53 @@ export {
   type SweepResult,
 };
 
+/**
+ * Lambda entry for the NLB TCP+TLS streaming target. Wired
+ * to the NLB target group in the CDK stack. Shares the cached
+ * {@link HandlerDeps} with the wss {@link handler} — same tables, same
+ * config, same management API (when available). Each NLB client chunk
+ * arrives as one invocation; the handler returns the outbound bytes for
+ * the NLB to stream back over the held-open TCP connection.
+ */
+export async function nlbStreamHandler(event: NlbStreamEvent): Promise<NlbStreamResponse> {
+  if (cachedDeps === undefined) {
+    if (cachedDepsPromise === undefined) {
+      cachedDepsPromise = buildDepsFromEnv();
+    }
+    cachedDeps = await cachedDepsPromise;
+    cachedDepsPromise = undefined;
+  }
+  const deps = cachedDeps;
+  return handleNlbStream(event, {
+    dynamo: deps.dynamo,
+    tables: deps.tables,
+    serverConfig: deps.serverConfig,
+    motd: deps.motd,
+    messages: deps.messages,
+    managementApi: deps.managementApi,
+    ...(deps.accounts !== undefined ? { accounts: deps.accounts } : {}),
+    ...(deps.history !== undefined ? { history: deps.history } : {}),
+  });
+}
+
+export {
+  handleNlbStream,
+  deriveNlbConnectionId,
+  type NlbStreamEvent,
+  type NlbStreamParams,
+  type NlbStreamResponse,
+};
+
 /**
  * Builds a {@link HandlerDeps} from the current `process.env`.
  *
  * Exposed so tests can construct production-shaped deps without re-running
- * the env parsing.
+ * the env parsing. Async because it scans the `Accounts` DynamoDB table
+ * (via {@link resolveAccountStore}) to pre-load SASL credentials at cold
+ * start — the {@link AccountStore} port is synchronous, so the scan must
+ * complete before any reducer calls `verify`.
  */
-export function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): HandlerDeps {
+export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Promise<HandlerDeps> {
   const cfg = loadServerConfigFromLambdaEnv(env as LambdaConfigEnv);
   const tables = tablesConfigFromEnv(env);
   const region = typeof env.AWS_REGION === 'string' ? env.AWS_REGION : undefined;
@@ -231,7 +331,18 @@ export function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): HandlerD
   }
   const motd = cfg.motdLines.length > 0 ? new StaticMotdProvider(cfg.motdLines) : EmptyMotdProvider;
   const messages = bindMessageStore(cfg);
-  return { dynamo, tables, serverConfig: cfg, motd, managementApi, messages };
+  const history = new InMemoryNickHistoryStore(SystemClock);
+  const accounts = await resolveAccountStore(dynamo, tables.Accounts, cfg);
+  return {
+    dynamo,
+    tables,
+    serverConfig: cfg,
+    motd,
+    managementApi,
+    messages,
+    history,
+    ...(accounts !== undefined ? { accounts } : {}),
+  };
 }
 
 function tablesConfigFromEnv(env: NodeJS.ProcessEnv): TablesConfig {