serverless-ircd 0.3.0 → 0.4.0

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(

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;
@@ -53,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');
   }
@@ -97,6 +114,21 @@ export function buildLambdaConfigInput(env: LambdaConfigEnv): Record<string, unk
   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)

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

@@ -16,108 +16,37 @@
  * `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 { 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;
+import {
+  type HashedAccountCredential,
+  HashedAccountStore,
+  hashAccountCredential,
+  verifyHashedPassword,
+} from '@serverless-ircd/irc-core';
 
-/**
- * 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'),
-  };
-}
+// 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 };
 
 /**
- * Verifies a plaintext password against a {@link HashedAccountCredential}
- * using `timingSafeEqual` (no short-circuit on first mismatched byte).
+ * Synchronous {@link AccountStore} backed by pre-loaded hashed credentials.
  *
- * Returns `false` for malformed entries rather than throwing — a corrupt
- * row should not crash the SASL exchange.
+ * 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 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;
-  }
-}
+export { HashedAccountStore as DynamoAccountStore };
 
 /**
  * Scans the `Accounts` table and returns a fully-populated
@@ -130,7 +59,7 @@ export class DynamoAccountStore implements AccountStore {
 export async function loadDynamoAccountStore(
   docClient: DynamoDBDocumentClient,
   tableName: string,
-): Promise<DynamoAccountStore | undefined> {
+): Promise<HashedAccountStore | undefined> {
   const entries: HashedAccountCredential[] = [];
   let exclusiveStartKey: Record<string, unknown> | undefined = undefined;
   do {
@@ -145,12 +74,22 @@ export async function loadDynamoAccountStore(
       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 });
+      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);
+  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

@@ -19,6 +19,8 @@ import {
   type IdFactory,
   type MessageStore,
   type MotdProvider,
+  type MtlsIdentityProvider,
+  type NickHistoryStore,
   type ParsedServerConfig,
   SystemClock,
   UuidIdFactory,
@@ -53,6 +55,30 @@ export interface DefaultParams {
    * — 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;
@@ -98,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,
   };
@@ -124,6 +155,8 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
     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/index.ts

@@ -16,10 +16,13 @@ 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';
@@ -29,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,
@@ -50,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;
 }
@@ -81,6 +98,13 @@ export interface HandlerDeps {
    * 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;
 }
 
 /**
@@ -132,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({
@@ -165,6 +191,7 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
           motd: deps.motd,
           messages: deps.messages,
           ...(deps.accounts !== undefined ? { accounts: deps.accounts } : {}),
+          ...(deps.history !== undefined ? { history: deps.history } : {}),
           managementApi: deps.managementApi,
         });
         return result;
@@ -245,6 +272,43 @@ 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`.
  *
@@ -267,6 +331,7 @@ export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Pr
   }
   const motd = cfg.motdLines.length > 0 ? new StaticMotdProvider(cfg.motdLines) : EmptyMotdProvider;
   const messages = bindMessageStore(cfg);
+  const history = new InMemoryNickHistoryStore(SystemClock);
   const accounts = await resolveAccountStore(dynamo, tables.Accounts, cfg);
   return {
     dynamo,
@@ -275,6 +340,7 @@ export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Pr
     motd,
     managementApi,
     messages,
+    history,
     ...(accounts !== undefined ? { accounts } : {}),
   };
 }