serverless-ircd 0.9.0 → 0.11.0

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

@@ -14,7 +14,6 @@
 import { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanagementapi';
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import {
-  type AccountStore,
   EmptyMotdProvider,
   InMemoryNickHistoryStore,
   type MessageStore,
@@ -25,11 +24,11 @@ import {
   StaticMotdProvider,
   SystemClock,
 } from '@serverless-ircd/irc-core';
-import { resolveAccountStore } from '../account-store.js';
 import { type LambdaConfigEnv, loadServerConfigFromLambdaEnv } from '../config-loader.js';
 import { type DynamoServicesStore, loadDynamoServicesStore } from '../dynamo-services-store.js';
 import { createDynamoDocumentClient } from '../dynamo.js';
 import { bindMessageStore } from '../message-store.js';
+import { parseWebOrigins } from '../origin-allowlist.js';
 import { TABLE_KEYS, type TablesConfig } from '../tables.js';
 import { handleConnect } from './connect.js';
 import { handleDefault } from './default.js';
@@ -105,20 +104,15 @@ 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;
   /**
    * Persistent services store (NickServ / ChanServ / HostServ / MemoServ /
-   * OperServ + read-marker), hydrated once per cold start from the
-   * `Services` DynamoDB table into a write-behind cache. `undefined` when
-   * `SERVICES_TABLE` is unset (services unbound → no NickServ/ChanServ
-   * routing). The handler flushes pending writes after each `$default` /
-   * NLB frame so a Lambda freeze / evict does not lose services state.
+   * OperServ + read-marker + the unified SASL/PASS credential home),
+   * hydrated once per cold start from the `Services` DynamoDB table into a
+   * write-behind cache. `undefined` when `SERVICES_TABLE` is unset
+   * (services unbound → no NickServ/ChanServ routing, no SASL/PASS
+   * credential verify). The handler flushes pending writes after each
+   * `$default` / NLB frame so a Lambda freeze / evict does not lose
+   * services state.
    */
   services?: DynamoServicesStore;
   /**
@@ -136,6 +130,16 @@ export interface HandlerDeps {
    * path applies (error-suffixed `382`).
    */
   configLoader?: () => Promise<ServerConfig>;
+  /**
+   * Parsed `WEB_ORIGINS` allowlist for the `$connect` CSWSH defence.
+   * Empty set (the default) disables the check; non-empty causes
+   * {@link handleConnect} to reject browser-sent `Origin` headers that
+   * are not in the set with `403`. Built once per cold start from
+   * `process.env.WEB_ORIGINS` via {@link parseWebOrigins}; non-browser
+   * clients (curl, WeeChat, the `tcp-ws-forwarder`) never send `Origin`
+   * and always proceed regardless.
+   */
+  webOrigins?: Set<string> | undefined;
 }
 
 /**
@@ -143,7 +147,12 @@ export interface HandlerDeps {
  * construct events directly.
  */
 export type ConnectEvent = {
-  requestContext: { routeKey: '$connect'; connectionId: string };
+  requestContext: {
+    routeKey: '$connect';
+    connectionId: string;
+    /** Client source IP — feeds the per-IP admission gates. */
+    identity?: { sourceIp?: string };
+  };
   headers?: Record<string, string>;
 };
 export type DisconnectEvent = {
@@ -196,7 +205,16 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
         tables: deps.tables,
         connectionId: connId,
         serverConfig: deps.serverConfig,
-        secWebSocketProtocol: event.headers?.['Sec-WebSocket-Protocol'] ?? null,
+        secWebSocketProtocol: readHeader(event.headers, 'Sec-WebSocket-Protocol'),
+        // APIGW normalises header keys to lowercase, but readHeader
+        // tolerates either casing so a future proxy / stage mutation
+        // cannot silently bypass the CSWSH defence.
+        originHeader: readHeader(event.headers, 'Origin'),
+        webOrigins: deps.webOrigins,
+        // Per-IP admission: APIGW stamps the client IP on every
+        // `$connect` event; absent (older shapes) the per-IP gates
+        // stay dormant.
+        sourceIp: event.requestContext.identity?.sourceIp,
       });
       if (outcome.admitted) {
         if (outcome.subprotocol !== null) {
@@ -233,7 +251,6 @@ 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.services !== undefined ? { services: deps.services } : {}),
           ...(deps.history !== undefined ? { history: deps.history } : {}),
           ...(deps.configLoader !== undefined ? { configLoader: deps.configLoader } : {}),
@@ -333,7 +350,24 @@ export async function nlbStreamHandler(event: NlbStreamEvent): Promise<NlbStream
     cachedDeps = await cachedDepsPromise;
     cachedDepsPromise = undefined;
   }
-  const deps = cachedDeps;
+  return dispatchNlbStream(event, cachedDeps);
+}
+
+/**
+ * Pure NLB dispatcher — exported for unit tests that inject deps directly
+ * (mirrors {@link dispatch} on the wss path).
+ *
+ * The CDK stack wires this Lambda target exclusively behind a
+ * `Protocol.TLS` NLB listener (an ACM-cert-terminated `irc+tls://`
+ * listener — see `aws-stack.ts`), so every connection routed here is
+ * TLS-protected at the edge. The secure fact is asserted so the actor
+ * surfaces read-only user mode `S`, STS advertises the duration-only
+ * TLS form, and SASL EXTERNAL is negotiable.
+ */
+export async function dispatchNlbStream(
+  event: NlbStreamEvent,
+  deps: HandlerDeps,
+): Promise<NlbStreamResponse> {
   return handleNlbStream(event, {
     dynamo: deps.dynamo,
     tables: deps.tables,
@@ -341,9 +375,11 @@ export async function nlbStreamHandler(event: NlbStreamEvent): Promise<NlbStream
     motd: deps.motd,
     messages: deps.messages,
     managementApi: deps.managementApi,
-    ...(deps.accounts !== undefined ? { accounts: deps.accounts } : {}),
     ...(deps.services !== undefined ? { services: deps.services } : {}),
     ...(deps.history !== undefined ? { history: deps.history } : {}),
+    // TLS fact: the NLB listener terminates TLS before the target sees
+    // the flow (mirrors the wss handler's hard-coded `secure: true`).
+    secure: true,
   });
 }
 
@@ -359,10 +395,16 @@ export {
  * Builds a {@link HandlerDeps} from the current `process.env`.
  *
  * Exposed so tests can construct production-shaped deps without re-running
- * 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`.
+ * the env parsing. Async because it scans the `Services` DynamoDB table
+ * (via {@link loadDynamoServicesStore}) to pre-load the services snapshot
+ * at cold start — the {@link ServicesStore} port is synchronous, so the
+ * scan must complete before any reducer calls `verifyNick` /
+ * `verifyCertFP`.
+ *
+ * After the services scan, the `SASL_ACCOUNTS` env-var seed is ingested
+ * into the services store via `registerNick` (idempotent — existing
+ * registrations, including NickServ-registered nicks, win over the env
+ * seed).
  */
 export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Promise<HandlerDeps> {
   const cfg = loadServerConfigFromLambdaEnv(env as LambdaConfigEnv);
@@ -378,13 +420,24 @@ 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);
   const servicesTable = typeof env.SERVICES_TABLE === 'string' ? env.SERVICES_TABLE : undefined;
   const services = await loadDynamoServicesStore(dynamo, servicesTable, SystemClock);
+  if (services !== undefined) {
+    for (const acct of cfg.saslAccounts) {
+      services.registerNick(acct.username, acct.password, '');
+    }
+  }
   // REHASH reload source: re-read the live env so a rotated oper password
   // or MOTD takes effect on the next REHASH without a redeploy.
   const configLoader = async (): Promise<ServerConfig> =>
     loadServerConfigFromLambdaEnv(env as LambdaConfigEnv);
+  // CSWSH defence — parsed once per cold start so every `$connect`
+  // reuses the same set. Empty set (the default when `WEB_ORIGINS` is
+  // unset) disables the check; non-empty denies browser-sent origins
+  // that are not in the set. Non-browser clients never send `Origin`.
+  const webOrigins = parseWebOrigins(
+    typeof env.WEB_ORIGINS === 'string' ? env.WEB_ORIGINS : undefined,
+  );
   return {
     dynamo,
     tables,
@@ -394,7 +447,7 @@ export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Pr
     messages,
     history,
     configLoader,
-    ...(accounts !== undefined ? { accounts } : {}),
+    ...(webOrigins.size > 0 ? { webOrigins } : {}),
     ...(services !== undefined ? { services } : {}),
   };
 }
@@ -411,3 +464,23 @@ function tablesConfigFromEnv(env: NodeJS.ProcessEnv): TablesConfig {
   }
   return out;
 }
+
+/**
+ * Case-insensitive header lookup against an APIGW `event.headers` record.
+ *
+ * API Gateway WebSocket normalises header keys to lowercase, but HTTP
+ * proxies in front of it (ALB, CloudFront, custom domains) can preserve
+ * the original case. A case-sensitive lookup would silently miss the
+ * header under one of those routes — for the `Origin` CSWSH check that
+ * is a security hole, so this helper walks both casings. Returns `null`
+ * when absent so callers can pass it straight to handlers that
+ * distinguish "header absent" from "header empty".
+ */
+function readHeader(headers: Record<string, string> | undefined, name: string): string | null {
+  if (headers === undefined) return null;
+  const direct = headers[name];
+  if (typeof direct === 'string') return direct;
+  const lower = headers[name.toLowerCase()];
+  if (typeof lower === 'string') return lower;
+  return null;
+}

package/packages/aws-adapter/src/handlers/nlb-stream.ts

@@ -12,13 +12,21 @@
  * `x-forwarded-port` headers. {@link deriveNlbConnectionId} maps that tuple
  * to the existing `connectionId` scheme (`nlb-<ip>-<port>`) so the same
  * DynamoDB-backed state path serves both the wss and TCP+TLS transports.
+ * A flow arriving without both headers in well-formed shape (missing,
+ * non-IP, or non-numeric-port — e.g. a misconfigured integration) is
+ * rejected with a 400 before any state is read or written; every such
+ * flow would otherwise share one `nlb-unknown-0` Connections row.
  *
  * Transport buffer persistence: the `TcpByteStreamTransport` buffers
  * partial lines (a chunk may split an IRC command at an arbitrary byte
  * boundary). Because each chunk arrives in a fresh Lambda invocation, the
  * buffered tail is snapshotted to a `transportBuffer` attribute on the
  * Connections row and rehydrated on the next invocation — no bytes are lost
- * across the compute boundary.
+ * across the compute boundary. The tail is capped at MAX_BUFFER_BYTES
+ * (shared constant from irc-core): a body over the cap is rejected with a
+ * 400 before any processing, and an accumulated tail over the cap closes
+ * the connection (ERROR line + Connections row deleted) so the buffer can
+ * never grow unboundedly or persist oversized.
  *
  * Outbound bytes: self-send lines (PONG, welcome block, error numerics, …)
  * are collected and returned as the Lambda response body (base64-encoded so
@@ -40,15 +48,16 @@
  *     underlying flow may be rebalanced by the NLB at any time.
  */
 
+import { isIP } from 'node:net';
 import type { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanagementapi';
-import { GetCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
+import { DeleteCommand, GetCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import {
-  type AccountStore,
   type ChannelState,
   type Clock,
   type ConnectionState,
   type IdFactory,
+  MAX_BUFFER_BYTES,
   type MessageStore,
   type MotdProvider,
   type NickHistoryStore,
@@ -56,6 +65,7 @@ import {
   type ServerConfig,
   SystemClock,
   UuidIdFactory,
+  byteLength,
 } from '@serverless-ircd/irc-core';
 import {
   type ActorChannelAccess,
@@ -65,6 +75,7 @@ import {
 import { TcpByteStreamTransport } from '@serverless-ircd/irc-server';
 import { AwsRuntime, type AwsRuntimeHandlers, type PostToConnection } from '../aws-runtime.js';
 import type { DynamoServicesStore } from '../dynamo-services-store.js';
+import { countConnectionsForIp } from '../ip-admission.js';
 import type { MarshalledConnection } from '../serialize.js';
 import { CONNECTION_VERSION } from '../serialize.js';
 import type { TablesConfig } from '../tables.js';
@@ -125,6 +136,30 @@ export function deriveNlbConnectionId(sourceIp: string, sourcePort: string): str
   return `${NLB_CONN_PREFIX}${safeIp}-${sourcePort}`;
 }
 
+/**
+ * Parses and validates the NLB flow headers (`x-forwarded-for` /
+ * `x-forwarded-port`) that identify a connection.
+ *
+ * A flow the NLB cannot identify — missing header, a non-IP
+ * `x-forwarded-for` (including a comma-separated proxy list; NLB sends
+ * exactly one client IP), or a `x-forwarded-port` that is not a plain
+ * decimal in `1..65535` — yields `null`. Such an invocation must be
+ * rejected by the caller: admitting it would map every such client onto
+ * one shared connection id and a single DynamoDB `Connections` row whose
+ * `ConnectionState` they overwrite per frame.
+ */
+export function parseNlbFlowHeaders(
+  event: NlbStreamEvent,
+): { sourceIp: string; sourcePort: string } | null {
+  const ip = readHeader(event, 'x-forwarded-for');
+  if (ip === undefined || isIP(ip) === 0) return null;
+  const port = readHeader(event, 'x-forwarded-port');
+  if (port === undefined || !/^\d{1,5}$/u.test(port) || Number(port) < 1 || Number(port) > 65535) {
+    return null;
+  }
+  return { sourceIp: ip, sourcePort: port };
+}
+
 // ---------------------------------------------------------------------------
 // Handler
 // ---------------------------------------------------------------------------
@@ -137,12 +172,11 @@ export interface NlbStreamParams {
   motd: MotdProvider;
   /** Chat-history persistence source (same as the wss `$default` path). */
   messages?: MessageStore;
-  /** SASL account verification source. */
-  accounts?: AccountStore;
   /**
    * Persistent services store (NickServ / ChanServ / HostServ / MemoServ /
-   * OperServ + read-marker). Flushed after each frame so a Lambda freeze
-   * does not lose services state.
+   * OperServ + read-marker + the unified SASL/PASS credential home).
+   * Flushed after each frame so a Lambda freeze does not lose services
+   * state.
    */
   services?: DynamoServicesStore;
   /** mTLS identity source for SASL EXTERNAL. */
@@ -169,7 +203,9 @@ export interface NlbStreamParams {
    * Whether the NLB listener terminates TLS for this flow. Set to `true`
    * when the target group fronts a TLS listener (the `irc+tls://` port) so
    * the connection surfaces user mode `S`; omit / set `false` for a plain
-   * TCP listener. The stack code sets this from the listener protocol.
+   * TCP listener. The Lambda entry ({@link dispatchNlbStream}) asserts
+   * `true` because the stack wires this target exclusively behind a TLS
+   * listener.
    */
   secure?: boolean;
 }
@@ -197,9 +233,27 @@ export async function handleNlbStream(
     ? Buffer.from(event.body, 'base64').toString('utf8')
     : event.body;
 
-  // 2. Derive the connection id from NLB flow metadata.
-  const sourceIp = readHeader(event, 'x-forwarded-for') ?? 'unknown';
-  const sourcePort = readHeader(event, 'x-forwarded-port') ?? '0';
+  // 1a. Payload pre-check: a body decoding to more than MAX_BUFFER_BYTES
+  // can never be legal IRC traffic (the line limit is 512 bytes), so it is
+  // rejected with a 400 to the NLB integration BEFORE any row read, actor
+  // invocation, or state write — an oversized payload must not even reach
+  // the transport buffer. Separate guard from the accumulation cap below:
+  // this one bounds a single invocation's input.
+  if (byteLength(data) > MAX_BUFFER_BYTES) {
+    return { statusCode: 400, body: '', isBase64Encoded: false };
+  }
+
+  // 2. Derive the connection id from NLB flow metadata. A flow missing
+  // either header — or carrying a malformed IP / port — cannot be
+  // identified: admitting it would collapse every such client onto one
+  // shared Connections row (the retired `nlb-unknown-0` fallback) whose
+  // state they overwrite per frame. Reject with a 400 before any row
+  // read, actor invocation, or state write.
+  const flow = parseNlbFlowHeaders(event);
+  if (flow === null) {
+    return { statusCode: 400, body: '', isBase64Encoded: false };
+  }
+  const { sourceIp, sourcePort } = flow;
   const connId = deriveNlbConnectionId(sourceIp, sourcePort);
 
   // 3. Load the existing row (if any) and split the transport buffer.
@@ -207,8 +261,30 @@ export async function handleNlbStream(
   let state: ConnectionState;
   let transportBuffer: string;
   if (existing === null) {
+    // 3a. Per-IP new-flow rate limit. The NLB path has no `$connect`
+    // event — flow establishment IS this first chunk — so the
+    // `perIpConnectionRate` budget is enforced here, counting the
+    // source IP's in-window establishments against the `sourceIp` GSI
+    // (the same index `$connect` consults). Over-budget flows get 429
+    // (the NLB closes the TCP flow on a non-200 target response) and NO
+    // row is written. Only establishment is budgeted: every subsequent
+    // chunk of an established flow is also an invocation, and
+    // rate-limiting those would starve an active IRC session.
+    if (sourceIp !== 'unknown') {
+      const rate = params.serverConfig.perIpConnectionRate;
+      const ipCounts = await countConnectionsForIp(
+        params.dynamo,
+        params.tables.Connections,
+        sourceIp,
+        now,
+        rate.windowMs,
+      );
+      if (ipCounts.recent >= rate.max) {
+        return { statusCode: 429, body: '', isBase64Encoded: false };
+      }
+    }
     state = createInitialConnectionState(connId, now);
-    if (sourceIp !== 'unknown') state.host = sourceIp;
+    state.host = sourceIp;
     transportBuffer = '';
   } else {
     state = unmarshalState(existing);
@@ -216,11 +292,39 @@ export async function handleNlbStream(
   }
 
   // 4. Frame the chunk through the persistent TCP transport.
-  const transport = new TcpByteStreamTransport();
+  let overflowed = false;
+  const transport = new TcpByteStreamTransport({
+    onOverflow: () => {
+      overflowed = true;
+    },
+  });
   transport.restore(transportBuffer);
   const lines = transport.feed(data);
   const newBuffer = transport.getBuffer();
 
+  // 4a. Buffer-cap teardown: the retained tail (restored buffer + this
+  // chunk, minus complete lines) exceeded MAX_BUFFER_BYTES. The peer can
+  // never produce a legal line from those bytes, so the connection is
+  // closed: the ERROR line is streamed back as the response body and the
+  // Connections row is DELETED (not persisted) — the oversized buffer
+  // never reaches a write, and the flow's bookkeeping is dropped. A fresh
+  // chunk from the same 4-tuple starts a clean connection row.
+  if (overflowed) {
+    await params.dynamo.send(
+      new DeleteCommand({
+        TableName: params.tables.Connections,
+        Key: { connectionId: connId },
+      }),
+    );
+    return {
+      statusCode: 200,
+      body: Buffer.from('ERROR :Closing link: input buffer overflow\r\n', 'utf8').toString(
+        'base64',
+      ),
+      isBase64Encoded: true,
+    };
+  }
+
   // Mark activity.
   state.lastSeen = now;
 
@@ -264,7 +368,6 @@ export async function handleNlbStream(
     // WsTextFrameTransport splits on \r\n (no-op for already-split lines).
     transport: new WsTextFrameTransport(),
     ...(params.messages !== undefined ? { messages: params.messages } : {}),
-    ...(params.accounts !== undefined ? { accounts: params.accounts } : {}),
     ...(params.services !== undefined ? { services: params.services } : {}),
     ...(params.mtlsIdentity !== undefined ? { mtlsIdentity: params.mtlsIdentity } : {}),
     ...(params.history !== undefined ? { history: params.history } : {}),
@@ -288,6 +391,7 @@ export async function handleNlbStream(
     state,
     now,
     newBuffer,
+    sourceIp !== 'unknown' ? sourceIp : undefined,
   );
 
   // Drain any services write-behind ops so a Lambda freeze / evict does
@@ -365,6 +469,14 @@ function unmarshalConnectionTyped(row: MarshalledConnection): ConnectionState {
  * UpdateCommand. The buffer is written as a plain string attribute — when
  * empty it is REMOVE'd so stale buffers from a previous chunk do not
  * linger after the line completes.
+ *
+ * `connectedSince` + `sourceIp` (when known) are stamped on every write:
+ * the upsert creates the row on a flow's first chunk, and both key
+ * attributes MUST be present for the row to surface in the `sourceIp`
+ * GSI the per-IP admission gates consult. For rows the update creates
+ * the establishment timestamp is stable (`state.connectedSince` is only
+ * absent on legacy rows written before this stamping shipped, where
+ * `now` is the best available fallback).
  */
 async function persistStateAndBuffer(
   dynamo: DynamoDBDocumentClient,
@@ -373,6 +485,7 @@ async function persistStateAndBuffer(
   state: ConnectionState,
   now: number,
   transportBuffer: string,
+  sourceIp?: string,
 ): Promise<void> {
   // Build the standard persist expression (same fields as handleDefault's
   // buildPersistUpdate, minus the joinedChannels which the membership
@@ -382,19 +495,27 @@ async function persistStateAndBuffer(
     ':capN': state.capNegotiating,
     ':caps': [...state.caps],
     ':um': { ...state.userModes },
+    ':sec': state.secure,
     ':ls': state.lastSeen,
     ':is': now,
     ':v': CONNECTION_VERSION,
+    ':cs': state.connectedSince ?? now,
   };
   const setNames = [
     'registration = :reg',
     'capNegotiating = :capN',
     'caps = :caps',
     'userModes = :um',
+    'secure = :sec',
     'lastSeen = :ls',
     'idleSince = :is',
     'version = :v',
+    'connectedSince = :cs',
   ];
+  if (sourceIp !== undefined) {
+    values[':sip'] = sourceIp;
+    setNames.push('sourceIp = :sip');
+  }
   const removeNames: string[] = [];
   const nameMap: Record<string, string> = {};
 

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

@@ -16,17 +16,15 @@ export { cleanupConnection } from './aws-runtime.js';
 export { TABLE_KEYS, TABLE_NAMES, tablesConfigFromNames } from './tables.js';
 export type { TableName, TablesConfig } from './tables.js';
 export { createDynamoDocumentClient } from './dynamo.js';
-export {
-  DynamoAccountStore,
-  type HashedAccountCredential,
-  hashAccountCredential,
-  loadDynamoAccountStore,
-} from './dynamo-account-store.js';
-export { bindAccountStore, putAccountCredential, resolveAccountStore } from './account-store.js';
 export {
   DynamoServicesStore,
   loadDynamoServicesStore,
 } from './dynamo-services-store.js';
+export {
+  type HashedAccountCredential,
+  hashAccountCredential,
+  verifyHashedPassword,
+} from '@serverless-ircd/irc-core';
 export { AwsStats } from './stats.js';
 export type { AwsStatsOptions } from './stats.js';
 export {

package/packages/aws-adapter/src/ip-admission.ts

@@ -0,0 +1,79 @@
+/**
+ * Per-IP connection counting against the `Connections` table's
+ * `sourceIp` GSI (`sourceIp` partition + `connectedSince` sort).
+ *
+ * Feeds the per-IP admission gates on both AWS transports:
+ *   - `$connect`: simultaneous per-IP cap (`maxConnectionsPerIp`) and
+ *     the per-IP connection-rate window (`perIpConnectionRate`).
+ *   - NLB streaming: the rate window for new flows (flow establishment
+ *     is the first chunk — there is no `$connect` event on that path).
+ *
+ * One paginated Query per call, projecting only `connectedSince`; the
+ * walk computes both counts (total + recent-inside-window) in a single
+ * pass. Per-IP partitions are bounded in steady state by the caps the
+ * gate itself enforces, so the walk is a handful of items in practice.
+ *
+ * Consistency caveat: GSI reads are eventually consistent (DynamoDB does
+ * not support strongly-consistent secondary-index reads), so a burst of
+ * concurrent connects from one IP can race past the per-IP caps — the
+ * same best-effort TOCTOU contract as the global connection counter.
+ *
+ * Legacy rows: items appear in the GSI only when BOTH key attributes are
+ * present. Rows written before this field shipped carry no `sourceIp`,
+ * so they are invisible to the index — the caps apply to connections
+ * registered from this change forward.
+ */
+
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { QueryCommand } from '@aws-sdk/lib-dynamodb';
+import { SOURCE_IP_INDEX_NAME } from './tables.js';
+
+/** Per-IP counts derived from the GSI walk. */
+export interface IpConnectionCounts {
+  /** Live connections currently attributed to the IP (GSI item count). */
+  readonly total: number;
+  /** Connections whose `connectedSince` falls inside the window. */
+  readonly recent: number;
+}
+
+/**
+ * Counts a source IP's connections: total (simultaneous) and recent
+ * (established within the last `windowMs`, i.e. still inside the
+ * sliding-window rate budget). Admissions exactly `windowMs` old still
+ * count (`connectedSince >= now - windowMs`), mirroring irc-core's
+ * `recentAdmissions` boundary.
+ */
+export async function countConnectionsForIp(
+  dynamo: DynamoDBDocumentClient,
+  tableName: string,
+  sourceIp: string,
+  now: number,
+  windowMs: number,
+): Promise<IpConnectionCounts> {
+  const cutoff = now - windowMs;
+  let total = 0;
+  let recent = 0;
+  let exclusiveStartKey: Record<string, unknown> | undefined = undefined;
+  do {
+    const result = await dynamo.send(
+      new QueryCommand({
+        TableName: tableName,
+        IndexName: SOURCE_IP_INDEX_NAME,
+        KeyConditionExpression: '#ip = :ip',
+        ExpressionAttributeNames: { '#ip': 'sourceIp' },
+        ExpressionAttributeValues: { ':ip': sourceIp },
+        ProjectionExpression: 'connectedSince',
+        ...(exclusiveStartKey !== undefined ? { ExclusiveStartKey: exclusiveStartKey } : {}),
+      }),
+    );
+    for (const item of result.Items ?? []) {
+      total++;
+      const since = (item as { connectedSince?: unknown }).connectedSince;
+      if (typeof since === 'number' && since >= cutoff) {
+        recent++;
+      }
+    }
+    exclusiveStartKey = result.LastEvaluatedKey as Record<string, unknown> | undefined;
+  } while (exclusiveStartKey !== undefined);
+  return { total, recent };
+}