serverless-ircd 0.10.0 → 0.11.0

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

@@ -239,15 +239,42 @@ export class AwsRuntime implements IrcRuntime {
    * phase — the APIGW call count is bounded by the genuine recipient set.
    */
   async broadcastWallops(lines: RawLine[], except?: ConnId): Promise<void> {
+    await this.fanOutByUserMode(lines, except, 'wallops');
+  }
+
+  /**
+   * Oper-only notice fanout (the OPER reducer's per-IP lockout notice).
+   * Identical enumeration to {@link broadcastWallops} but the recipient
+   * gate is user mode `+o`: a filtered `Scan` of the `Connections` table
+   * followed by a `PostToConnection` per oper. The same cost note applies
+   * — the scan reads the whole table — but lockout notices only fire when
+   * a host trips the failed-OPER budget, so the rate is bounded by
+   * attacker behaviour, not by legitimate traffic.
+   */
+  async broadcastOperNotice(lines: RawLine[], except?: ConnId): Promise<void> {
+    await this.fanOutByUserMode(lines, except, 'oper');
+  }
+
+  /**
+   * Shared fan-out for {@link broadcastWallops} / {@link broadcastOperNotice}:
+   * paginated filtered `Scan` over `userModes.<mode>`, skipping `except`,
+   * delivering via `send` (which short-cuts the bound connection through
+   * the in-process handlers and tolerates vanished sockets).
+   */
+  private async fanOutByUserMode(
+    lines: RawLine[],
+    except: ConnId | undefined,
+    mode: 'wallops' | 'oper',
+  ): Promise<void> {
     let startKey: Record<string, NativeAttributeValue> | undefined;
     // Paginate the scan: DynamoDB caps a single Scan at 1 MB. Loop until
-    // no `LastEvaluatedKey` remains so every +w connection is reached.
+    // no `LastEvaluatedKey` remains so every matching connection is reached.
     do {
       const result = await this.dynamo.send(
         new ScanCommand({
           TableName: this.tables.Connections,
           FilterExpression: 'userModes.#m = :true',
-          ExpressionAttributeNames: { '#m': 'wallops' },
+          ExpressionAttributeNames: { '#m': mode },
           ExpressionAttributeValues: { ':true': true },
           ...(startKey !== undefined ? { ExclusiveStartKey: startKey } : {}),
         }),
@@ -259,7 +286,7 @@ export class AwsRuntime implements IrcRuntime {
         // `send` short-cuts the bound connection through the in-process
         // handlers and catches GoneException so vanished sockets are
         // cleaned up rather than aborting the fan-out mid-loop.
-        if (row.userModes.wallops) {
+        if (mode === 'wallops' ? row.userModes.wallops : row.userModes.oper) {
           await this.send(connId, lines);
         }
       }

package/packages/aws-adapter/src/cdk-table-defs.ts

@@ -27,13 +27,25 @@
  *     are reaped automatically in addition to the explicit sweeper.
  */
 
-import { AttributeType, BillingMode } from 'aws-cdk-lib/aws-dynamodb';
-import type { TableProps } from 'aws-cdk-lib/aws-dynamodb';
-import type { TableName } from './tables.js';
+import { AttributeType, BillingMode, ProjectionType } from 'aws-cdk-lib/aws-dynamodb';
+import type { GlobalSecondaryIndexProps, TableProps } from 'aws-cdk-lib/aws-dynamodb';
+import { SOURCE_IP_INDEX_NAME, type TableName } from './tables.js';
 
 /**
- * All four tables keyed by their logical construct id. The id doubles as the
- * CloudFormation logical id; the physical `TableName` is set on each entry.
+ * A table definition: the CDK `TableProps` plus an optional side-channel
+ * for secondary indexes. Current aws-cdk-lib moved GSI declaration out
+ * of `TableProps` (indexes are added via `Table.addGlobalSecondaryIndex`
+ * after construction), so the index list rides alongside the construct
+ * props here — the stack pops it before constructing the `Table` and the
+ * DynamoDB Local fixtures read it when issuing raw `CreateTableCommand`s.
+ */
+export interface TableDef extends TableProps {
+  globalSecondaryIndexes?: GlobalSecondaryIndexProps[];
+}
+
+/**
+ * All four tables keyed by their logical construct id. The id doubles as
+ * the CloudFormation logical id; the physical `TableName` is set on each entry.
  *
  * NOTE: the deployed physical name is **environment-prefixed** by
  * `IrcAwsStack` (`<Env><LogicalId>`, e.g. `StagingConnections`) — the
@@ -42,12 +54,28 @@ import type { TableName } from './tables.js';
  * every physical name (to isolate parallel runs) consume the
  * `TABLE_DEFS` entries' key/attribute names only.
  */
-export const TABLE_DEFS: Record<TableName, TableProps> = {
+export const TABLE_DEFS: Record<TableName, TableDef> = {
   Connections: {
     tableName: 'Connections',
     partitionKey: { name: 'connectionId', type: AttributeType.STRING },
     billingMode: BillingMode.PAY_PER_REQUEST,
     timeToLiveAttribute: 'idleSince',
+    // Per-IP admission index: `$connect` counts an IP's live connections
+    // (maxConnectionsPerIp) and its in-window establishments
+    // (perIpConnectionRate) against this GSI; the NLB new-flow gate
+    // counts the window. Rows surface in the index only when both key
+    // attributes are present (handlers stamp `sourceIp` at
+    // connect/flow-establishment; legacy rows are invisible — the caps
+    // apply from this change forward). TTL-reaped rows leave the index
+    // with them, so the index self-cleans.
+    globalSecondaryIndexes: [
+      {
+        indexName: SOURCE_IP_INDEX_NAME,
+        partitionKey: { name: 'sourceIp', type: AttributeType.STRING },
+        sortKey: { name: 'connectedSince', type: AttributeType.NUMBER },
+        projectionType: ProjectionType.ALL,
+      },
+    ],
   },
   ChannelMeta: {
     tableName: 'ChannelMeta',

package/packages/aws-adapter/src/config-loader.ts

@@ -11,6 +11,15 @@
 
 import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc-core';
 
+/**
+ * Documented schema defaults for `perIpConnectionRate`. Duplicated here
+ * (the schema inlines its `.default(...)`) so an operator setting only
+ * one half of the knob via env gets the documented default for the other
+ * half rather than a parse error.
+ */
+const DEFAULT_PER_IP_RATE_MAX = 5;
+const DEFAULT_PER_IP_RATE_WINDOW_MS = 60_000;
+
 /**
  * The subset of `process.env` this loader reads. Optional members are
  * omitted from the input object when undefined so the schema's defaults
@@ -35,6 +44,20 @@ export interface LambdaConfigEnv {
   CHANNEL_PREFIXES?: string;
   OPER_USER?: string;
   OPER_PASSWORD?: string;
+  /**
+   * Scrypt salt (base64) for the hashed oper credential form. When set
+   * alongside `OPER_USER` + `OPER_HASH`, the loader builds a hashed
+   * `{user, salt, hash}` cred instead of the legacy plaintext
+   * `{user, password}` shape. The hashed form is preferred when both
+   * are present so deployments can rotate without removing the legacy
+   * vars in the same step. Generate via `tools/hash-oper-cred.ts`.
+   */
+  OPER_SALT?: string;
+  /**
+   * Scrypt hash (base64) for the hashed oper credential form. See
+   * `OPER_SALT` for the full set of vars.
+   */
+  OPER_HASH?: string;
   /**
    * Server-password gate. Treat as an AWS secret (Secrets Manager or
    * SSM `SecureString`); the loader threads it through to
@@ -74,6 +97,41 @@ export interface LambdaConfigEnv {
    * send `Origin` and always pass through regardless.
    */
   WEB_ORIGINS?: string;
+  /**
+   * Per-connection inbound frame window ceiling enforced by the
+   * `$default` handler BEFORE the actor / DynamoDB write. Parsed into
+   * `ServerConfig.adapter.maxFramesPerWindow`.
+   */
+  MAX_FRAMES_PER_WINDOW?: string;
+  /**
+   * Sliding-window length (seconds) for the inbound frame limit; frames
+   * older than the window stop counting. Parsed into
+   * `ServerConfig.adapter.frameWindowSeconds`.
+   */
+  FRAME_WINDOW_SECONDS?: string;
+  /**
+   * Per-IP simultaneous-connection cap (`maxConnectionsPerIp`). Enforced
+   * by the `$connect` admission gate against the `sourceIp` GSI; mirrors
+   * the CF loader's var of the same name.
+   */
+  MAX_CONNECTIONS_PER_IP?: string;
+  /**
+   * Per-IP connection-rate budget (`perIpConnectionRate.max`) — how many
+   * new connections one source IP may open per sliding window. Enforced
+   * by `$connect` and the NLB new-flow gate. The unset half of the knob
+   * falls back to the schema default.
+   */
+  PER_IP_CONNECTION_RATE_MAX?: string;
+  /** Sliding window length in ms (`perIpConnectionRate.windowMs`). */
+  PER_IP_CONNECTION_RATE_WINDOW_MS?: string;
+  /**
+   * Operator opt-in for certificate-backed SASL EXTERNAL. 'true'/'1'
+   * (case-insensitive) map to `sasl.externalEnabled: true`; any other
+   * value (and unset) leaves the mechanism off. EXTERNAL additionally
+   * requires edge mTLS (APIGW client certs on the custom domain) and a
+   * secure (TLS) connection — the flag alone advertises nothing.
+   */
+  EXTERNAL_ENABLED?: string;
 }
 
 /**
@@ -105,12 +163,36 @@ export function buildLambdaConfigInput(env: LambdaConfigEnv): Record<string, unk
     input.channelPrefixes = env.CHANNEL_PREFIXES;
   }
   if (env.OPER_USER !== undefined || env.OPER_PASSWORD !== undefined) {
-    input.operCreds = [
-      {
-        user: env.OPER_USER ?? '',
-        password: env.OPER_PASSWORD ?? '',
-      },
-    ];
+    // Hashed form (OPER_USER + OPER_SALT + OPER_HASH) is preferred when
+    // both salt + hash are supplied — even if OPER_PASSWORD is also set,
+    // so a deployment can rotate to the hashed form without dropping the
+    // legacy var in the same release. The legacy plaintext
+    // `{user, password}` shape is retained for a single deprecation-
+    // cycle window.
+    const hasHashed = env.OPER_SALT !== undefined && env.OPER_HASH !== undefined;
+    if (hasHashed) {
+      input.operCreds = [
+        {
+          user: env.OPER_USER ?? '',
+          salt: env.OPER_SALT ?? '',
+          hash: env.OPER_HASH ?? '',
+        },
+      ];
+    } else {
+      // Build the legacy cred object from whatever was supplied; the
+      // schema surfaces a `user`/`password` error if only one half was
+      // provided. If only OPER_SALT/OPER_HASH (partial) are set, the
+      // schema will surface the missing hashed-form field via the
+      // superRefine error path.
+      input.operCreds = [
+        {
+          user: env.OPER_USER ?? '',
+          password: env.OPER_PASSWORD ?? '',
+          ...(env.OPER_SALT !== undefined ? { salt: env.OPER_SALT } : {}),
+          ...(env.OPER_HASH !== undefined ? { hash: env.OPER_HASH } : {}),
+        },
+      ];
+    }
   }
   if (env.SERVER_PASSWORD !== undefined) {
     input.serverPassword = env.SERVER_PASSWORD;
@@ -139,9 +221,55 @@ export function buildLambdaConfigInput(env: LambdaConfigEnv): Record<string, unk
   if (env.SASL_ACCOUNTS !== undefined && env.SASL_ACCOUNTS.length > 0) {
     input.saslAccounts = parseSaslAccountsLines(env.SASL_ACCOUNTS);
   }
+  if (env.MAX_FRAMES_PER_WINDOW !== undefined || env.FRAME_WINDOW_SECONDS !== undefined) {
+    // Partial sections are fine: the per-field schema defaults fill the
+    // knob(s) the env did not supply.
+    input.adapter = {
+      ...(env.MAX_FRAMES_PER_WINDOW !== undefined
+        ? { maxFramesPerWindow: Number.parseInt(env.MAX_FRAMES_PER_WINDOW, 10) }
+        : {}),
+      ...(env.FRAME_WINDOW_SECONDS !== undefined
+        ? { frameWindowSeconds: Number.parseInt(env.FRAME_WINDOW_SECONDS, 10) }
+        : {}),
+    };
+  }
+  if (env.MAX_CONNECTIONS_PER_IP !== undefined) {
+    input.maxConnectionsPerIp = Number.parseInt(env.MAX_CONNECTIONS_PER_IP, 10);
+  }
+  if (
+    env.PER_IP_CONNECTION_RATE_MAX !== undefined ||
+    env.PER_IP_CONNECTION_RATE_WINDOW_MS !== undefined
+  ) {
+    // The schema requires both halves; the unset one falls back to the
+    // documented schema defaults (mirrors the CF loader's vars of the
+    // same names so operators tune both platforms identically).
+    input.perIpConnectionRate = {
+      max:
+        env.PER_IP_CONNECTION_RATE_MAX !== undefined
+          ? Number.parseInt(env.PER_IP_CONNECTION_RATE_MAX, 10)
+          : DEFAULT_PER_IP_RATE_MAX,
+      windowMs:
+        env.PER_IP_CONNECTION_RATE_WINDOW_MS !== undefined
+          ? Number.parseInt(env.PER_IP_CONNECTION_RATE_WINDOW_MS, 10)
+          : DEFAULT_PER_IP_RATE_WINDOW_MS,
+    };
+  }
+  if (env.EXTERNAL_ENABLED !== undefined) {
+    input.sasl = { externalEnabled: parseEnabledFlag(env.EXTERNAL_ENABLED) };
+  }
   return input;
 }
 
+/**
+ * Parses a boolean feature-flag env var: 'true' / '1' (case-insensitive,
+ * whitespace-trimmed) are truthy; every other value is false. Flags
+ * default off, so a typo must never silently enable the feature.
+ */
+function parseEnabledFlag(raw: string): boolean {
+  const normalized = raw.trim().toLowerCase();
+  return normalized === 'true' || normalized === '1';
+}
+
 /**
  * Parses the `CREATED_AT` env var into the schema's `createdAt` field.
  *

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

@@ -199,6 +199,8 @@ export class DynamoServicesStore extends PersistentServicesStore {
       createdAt: row.createdAt,
       enforce: row.enforce,
       certSubjects: row.certSubjects ?? [],
+      identifyFailures: row.identifyFailures ?? [],
+      pendingIdentifyFailureNotice: row.pendingIdentifyFailureNotice ?? 0,
       algorithm: row.credential.algorithm,
       salt: row.credential.salt,
       hash: row.credential.hash,
@@ -542,6 +544,14 @@ function coerceNick(item: Record<string, unknown>): ServicesNickRow | undefined
   const certSubjects = Array.isArray(item.certSubjects)
     ? item.certSubjects.filter((s): s is string => typeof s === 'string')
     : [];
+  // The identify-throttle fields are additive in the same way: absent (a
+  // pre-throttle item) or ill-typed attributes collapse to the neutral
+  // unfrozen defaults.
+  const identifyFailures = Array.isArray(item.identifyFailures)
+    ? item.identifyFailures.filter((t): t is number => typeof t === 'number')
+    : [];
+  const pendingIdentifyFailureNotice =
+    typeof item.pendingIdentifyFailureNotice === 'number' ? item.pendingIdentifyFailureNotice : 0;
   return {
     nick: item.nick,
     account: item.account,
@@ -549,6 +559,8 @@ function coerceNick(item: Record<string, unknown>): ServicesNickRow | undefined
     createdAt: item.createdAt,
     enforce: item.enforce as NickEnforcePolicy,
     certSubjects,
+    identifyFailures,
+    pendingIdentifyFailureNotice,
     credential: {
       account: item.account,
       algorithm: 'scrypt',

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

@@ -24,6 +24,7 @@ import {
 } from '@serverless-ircd/irc-core';
 import { type AdmissionOutcome, decideConnectAdmission } from '../admission.js';
 import { decrementConnectionCount, incrementConnectionCount } from '../connection-counter.js';
+import { countConnectionsForIp } from '../ip-admission.js';
 import { decideConnectOrigin } from '../origin-allowlist.js';
 import { marshalConnection } from '../serialize.js';
 import type { TablesConfig } from '../tables.js';
@@ -61,6 +62,16 @@ export interface ConnectParams {
    * the Origin check (the default — defence is opt-in).
    */
   webOrigins?: Set<string> | undefined;
+  /**
+   * Source IP of the connecting client (`event.requestContext.identity
+   * .sourceIp` on APIGW). When present, the per-IP admission gates run:
+   * a paginated Query against the `sourceIp` GSI supplies the IP's live
+   * count (`maxConnectionsPerIp`) and its in-window count
+   * (`perIpConnectionRate`), and the previously-dormant per-IP branch
+   * of {@link decideConnectAdmission} goes live. Absent (older event
+   * shapes) the per-IP checks are skipped entirely.
+   */
+  sourceIp?: string | null | undefined;
 }
 
 /**
@@ -109,11 +120,40 @@ export async function handleConnect(params: ConnectParams): Promise<ConnectOutco
     return { admitted: false, statusCode: 403, reason: 'origin not allowed' };
   }
 
+  // Per-IP admission counts (GSI walk). Runs before the global counter
+  // reservation so an over-budget IP never churns the meta-row counter.
+  // An empty/absent source IP skips the per-IP gates (branch stays
+  // dormant, matching pre-GSI event shapes).
+  let perIp: number | undefined;
+  let recentPerIp: number | undefined;
+  if (typeof params.sourceIp === 'string' && params.sourceIp.length > 0) {
+    const ipCounts = await countConnectionsForIp(
+      params.dynamo,
+      params.tables.Connections,
+      params.sourceIp,
+      now,
+      params.serverConfig.perIpConnectionRate.windowMs,
+    );
+    perIp = ipCounts.total;
+    recentPerIp = ipCounts.recent;
+  }
+
   // Reserve a slot atomically. The returned value includes this reservation,
   // so the pre-existing count (`total`, as expected by the policy) is one
   // less than the post-increment value.
   const reservedCount = await incrementConnectionCount(params.dynamo, params.tables.Connections);
-  const outcome = decideConnectAdmission({ total: reservedCount - 1 }, { maxClients });
+  const outcome = decideConnectAdmission(
+    {
+      total: reservedCount - 1,
+      ...(perIp !== undefined ? { perIp } : {}),
+      ...(recentPerIp !== undefined ? { recentPerIp } : {}),
+    },
+    {
+      maxClients,
+      maxConnectionsPerIp: params.serverConfig.maxConnectionsPerIp,
+      perIpRate: params.serverConfig.perIpConnectionRate,
+    },
+  );
   if (!outcome.admitted) {
     // Over capacity — release the reservation so the counter does not drift
     // upward on every rejected connect.
@@ -144,6 +184,12 @@ export async function handleConnect(params: ConnectParams): Promise<ConnectOutco
   if (mode !== 'legacy') {
     row.wsMode = mode;
   }
+  // Persist the source IP so the `sourceIp` GSI carries this connection
+  // for future per-IP admission walks (rows without it are invisible to
+  // the index — see ip-admission.ts).
+  if (typeof params.sourceIp === 'string' && params.sourceIp.length > 0) {
+    row.sourceIp = params.sourceIp;
+  }
   try {
     await params.dynamo.send(
       new PutCommand({

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

@@ -15,6 +15,7 @@ import {
   type ChannelState,
   type Clock,
   type ConnectionState,
+  FRAME_FLOOD_ERROR_LINE,
   type IdFactory,
   type MessageStore,
   type MotdProvider,
@@ -25,6 +26,7 @@ import {
   SystemClock,
   UuidIdFactory,
   type WsFrameMode,
+  admitFrameWindow,
   createConnection,
   frameToLines,
 } from '@serverless-ircd/irc-core';
@@ -220,12 +222,50 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
       );
       return { statusCode: 410 };
     }
-    const persisted = result.Item as unknown as MarshalledConnection;
+    const persisted = result.Item as unknown as MarshalledConnection & { frameTimes?: unknown };
     const state = unmarshalConnection(persisted);
     const expectedRevision = persisted.revision ?? 0;
     const wsMode: WsFrameMode = persisted.wsMode ?? 'legacy';
     wsModeHolder = wsMode;
 
+    // 1a. Adapter-boundary frame-rate gate. Each frame is a billed read +
+    // write (and the actor run); a hostile client must not be able to
+    // drive that cost unboundedly with low-cost commands. The sliding
+    // window persists on the row (admitted frames persist it atomically
+    // with the state write below), so the limit holds across
+    // invocations. An over-limit frame never reaches the actor: the
+    // canonical ERROR line is delivered, the socket is closed via
+    // DeleteConnection (which fires the $disconnect cleanup), and the
+    // invocation returns without a write.
+    const frameDecision = admitFrameWindow(
+      readFrameTimes(persisted),
+      clock.now(),
+      params.serverConfig.adapter.maxFramesPerWindow,
+      params.serverConfig.adapter.frameWindowSeconds * 1000,
+    );
+    if (!frameDecision.admitted) {
+      console.warn(
+        `[irc-handler] $default connId=${params.connectionId} frame limit exceeded ` +
+          `(${params.serverConfig.adapter.maxFramesPerWindow}/${params.serverConfig.adapter.frameWindowSeconds}s) -> closing`,
+      );
+      if (params.managementApi !== null) {
+        try {
+          await postOutbound(
+            params.managementApi,
+            params.connectionId,
+            [FRAME_FLOOD_ERROR_LINE],
+            wsMode,
+          );
+          await closeConnectionIfSupported(params.managementApi, params.connectionId);
+        } catch (err) {
+          // The socket may already be gone (close raced a concurrent
+          // over-limit frame) — surface for observability, nothing to retry.
+          console.error('[irc-handler] flood close post failed', err);
+        }
+      }
+      return { statusCode: 200 };
+    }
+
     // 2. Mark activity + run the actor. Self-sends reset per attempt.
     state.lastSeen = clock.now();
     outbound.length = 0;
@@ -235,16 +275,28 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
       console.error('[irc-handler] actor.receiveTextFrame failed', err);
       // Best-effort persist of partial state (swallow a conflict here —
       // the actor already failed, no point retrying).
-      await persistState(params.dynamo, params.tables, state, clock.now(), expectedRevision).catch(
-        () => {},
-      );
+      await persistState(
+        params.dynamo,
+        params.tables,
+        state,
+        clock.now(),
+        expectedRevision,
+        frameDecision.times,
+      ).catch(() => {});
       await params.services?.flush();
       return { statusCode: 500 };
     }
 
     // 3. Conditional persist.
     try {
-      await persistState(params.dynamo, params.tables, state, clock.now(), expectedRevision);
+      await persistState(
+        params.dynamo,
+        params.tables,
+        state,
+        clock.now(),
+        expectedRevision,
+        frameDecision.times,
+      );
       break; // committed — exit the retry loop.
     } catch (err: unknown) {
       if (isConditionalCheckFailed(err) && attempt < MAX_RETRIES) {
@@ -280,6 +332,35 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
   return { statusCode: 200 };
 }
 
+/**
+ * Reads the persisted inbound frame-window timestamps off a Connections
+ * row. Rows written before the frame gate shipped (or by paths that do
+ * not track frames, e.g. NLB chunks) carry no attribute — an empty
+ * window starts the connection fresh.
+ */
+function readFrameTimes(row: MarshalledConnection & { frameTimes?: unknown }): number[] {
+  const raw = row.frameTimes;
+  if (!Array.isArray(raw)) return [];
+  return raw as number[];
+}
+
+/**
+ * Closes the client's APIGW WebSocket via the management API
+ * (`DeleteConnection` — API Gateway observes the close and fires the
+ * `$disconnect` route, which runs the canonical QUIT cleanup). The
+ * `PostToConnection` test-double arm has no delete method; the close is
+ * skipped there (the ERROR post alone still informs the client).
+ */
+async function closeConnectionIfSupported(
+  api: ApiGatewayManagementApi | PostToConnection,
+  connectionId: string,
+): Promise<void> {
+  const deleter = api as Partial<Pick<ApiGatewayManagementApi, 'deleteConnection'>>;
+  if (typeof deleter.deleteConnection === 'function') {
+    await deleter.deleteConnection({ ConnectionId: connectionId });
+  }
+}
+
 /**
  * Delivers `lines` to `connectionId` via APIGW according to `mode`:
  *   - `legacy` — all lines joined with `\r\n` in a single `postToConnection`.
@@ -324,8 +405,9 @@ async function persistState(
   state: ConnectionState,
   now: number,
   expectedRevision: number,
+  frameTimes: readonly number[],
 ): Promise<void> {
-  const expr = buildPersistUpdate(state, now, expectedRevision);
+  const expr = buildPersistUpdate(state, now, expectedRevision, frameTimes);
   const hasNames = Object.keys(expr.expressionAttributeNames).length > 0;
   await dynamo.send(
     new UpdateCommand({
@@ -375,6 +457,7 @@ export function buildPersistUpdate(
   state: ConnectionState,
   now: number,
   expectedRevision: number,
+  frameTimes: readonly number[],
 ): {
   updateExpression: string;
   conditionExpression: string;
@@ -389,6 +472,11 @@ export function buildPersistUpdate(
     ':ls': state.lastSeen,
     ':is': now,
     ':v': CONNECTION_VERSION,
+    // Sliding-window timestamps for the adapter-boundary frame limit.
+    // Committed atomically with the state write (same revision
+    // condition), so each frame is counted exactly once even when
+    // concurrent invocations race through the retry loop.
+    ':ft': [...frameTimes],
     // Optimistic-concurrency: increment the revision counter, gated by
     // a condition that the row is still at the revision we read.
     ':revInc': 1,
@@ -402,6 +490,7 @@ export function buildPersistUpdate(
     'lastSeen = :ls',
     'idleSince = :is',
     'version = :v',
+    'frameTimes = :ft',
   ];
   const removeNames: string[] = [];
   const nameMap: Record<string, string> = { '#rev': 'revision' };

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

@@ -147,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 = {
@@ -206,6 +211,10 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
         // 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) {
@@ -341,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,
@@ -351,6 +377,9 @@ export async function nlbStreamHandler(event: NlbStreamEvent): Promise<NlbStream
     managementApi: deps.managementApi,
     ...(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,
   });
 }