serverless-ircd 0.10.0 → 0.11.0

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,14 +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 ChannelState,
   type Clock,
   type ConnectionState,
   type IdFactory,
+  MAX_BUFFER_BYTES,
   type MessageStore,
   type MotdProvider,
   type NickHistoryStore,
@@ -55,6 +65,7 @@ import {
   type ServerConfig,
   SystemClock,
   UuidIdFactory,
+  byteLength,
 } from '@serverless-ircd/irc-core';
 import {
   type ActorChannelAccess,
@@ -64,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';
@@ -124,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
 // ---------------------------------------------------------------------------
@@ -167,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;
 }
@@ -195,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.
@@ -205,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);
@@ -214,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;
 
@@ -285,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
@@ -362,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,
@@ -370,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
@@ -379,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/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 };
+}

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

@@ -107,6 +107,14 @@ export interface MarshalledConnection {
    * subsequent frame.
    */
   wsMode?: WsFrameMode;
+  /**
+   * Source IP of the connecting client, persisted at `$connect` (and on
+   * NLB flow creation) so the `sourceIp` GSI (`sourceIp-connectedSince`)
+   * carries the row for the per-IP admission walks. Absent on rows
+   * written before this field shipped — those are invisible to the
+   * index (a GSI item requires both key attributes).
+   */
+  sourceIp?: string;
 }
 
 /**

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

@@ -71,3 +71,12 @@ export function tablesConfigFromNames(names: {
   const out: TablesConfig = { ...names };
   return out;
 }
+
+/**
+ * Name of the per-IP admission GSI on the `Connections` table
+ * (partition key `sourceIp`, sort key `connectedSince`). Consulted by the
+ * `$connect` and NLB handlers' per-IP admission gates; declared on the
+ * deployed table by `TABLE_DEFS` in `cdk-table-defs.ts`. Shared here so
+ * the runtime (this module) and the CDK definition reference one name.
+ */
+export const SOURCE_IP_INDEX_NAME = 'sourceIp-connectedSince';

package/packages/aws-adapter/tests/admission.test.ts

@@ -1,8 +1,8 @@
 /**
  * Pure unit tests for the AWS `$connect` admission policy
  * (`src/admission.ts`). No DynamoDB — these exercise every branch of
- * {@link decideConnectAdmission} directly so the per-IP branch is covered
- * even though the AWS handler does not yet feed it a `perIp` count.
+ * {@link decideConnectAdmission} directly so the per-IP branches are
+ * covered without standing up DynamoDB Local.
  */
 
 import { describe, expect, it } from 'vitest';
@@ -67,4 +67,62 @@ describe('decideConnectAdmission', () => {
       reason: 'server full',
     });
   });
+
+  it('admits when a rate budget is set but no recent count is supplied', () => {
+    expect(
+      decideConnectAdmission(
+        { total: 0 },
+        { maxClients: 10, perIpRate: { max: 5, windowMs: 60_000 } },
+      ),
+    ).toEqual({ admitted: true });
+  });
+
+  it('admits when the recent per-IP count is below the rate budget', () => {
+    expect(
+      decideConnectAdmission(
+        { total: 0, recentPerIp: 4 },
+        { maxClients: 10, perIpRate: { max: 5, windowMs: 60_000 } },
+      ),
+    ).toEqual({ admitted: true });
+  });
+
+  it('rejects with 429 once the recent per-IP count reaches the rate budget', () => {
+    expect(
+      decideConnectAdmission(
+        { total: 0, recentPerIp: 5 },
+        { maxClients: 10, perIpRate: { max: 5, windowMs: 60_000 } },
+      ),
+    ).toEqual({
+      admitted: false,
+      statusCode: 429,
+      reason: 'connection rate exceeded for this IP',
+    });
+  });
+
+  it('checks the per-IP simultaneous cap before the rate budget', () => {
+    // A caller supplying both over-budget counts gets the simultaneous-
+    // cap reason: the more specific signal for an already-connected IP.
+    expect(
+      decideConnectAdmission(
+        { total: 0, perIp: 3, recentPerIp: 5 },
+        { maxClients: 10, maxConnectionsPerIp: 3, perIpRate: { max: 5, windowMs: 60_000 } },
+      ),
+    ).toEqual({
+      admitted: false,
+      statusCode: 429,
+      reason: 'too many connections from this IP',
+    });
+  });
+
+  it('ignores a stale recent count (window decayed) and admits', () => {
+    // Window-reset behaviour at the policy seam: a recent count of 0
+    // (every prior admission aged out of the window) never trips the
+    // rate branch even at a budget of 1.
+    expect(
+      decideConnectAdmission(
+        { total: 0, recentPerIp: 0 },
+        { maxClients: 10, perIpRate: { max: 1, windowMs: 60_000 } },
+      ),
+    ).toEqual({ admitted: true });
+  });
 });

package/packages/aws-adapter/tests/aws-harness.ts

@@ -211,7 +211,7 @@ export class AwsHarness implements IrcHarness {
       const pkName = props.partitionKey?.name;
       const skName = props.sortKey?.name;
       if (pkName === undefined) throw new Error(`table ${logical} missing partitionKey`);
-      const attributeDefinitions: Array<{ AttributeName: string; AttributeType: 'S' }> = [
+      const attributeDefinitions: Array<{ AttributeName: string; AttributeType: 'S' | 'N' }> = [
         { AttributeName: pkName, AttributeType: 'S' },
       ];
       const keySchema: Array<{ AttributeName: string; KeyType: 'HASH' | 'RANGE' }> = [
@@ -221,11 +221,33 @@ export class AwsHarness implements IrcHarness {
         attributeDefinitions.push({ AttributeName: skName, AttributeType: 'S' });
         keySchema.push({ AttributeName: skName, KeyType: 'RANGE' });
       }
+      // Mirror the CDK-declared secondary indexes (the Connections
+      // per-IP admission GSI) so the fixture matches the deployed schema.
+      const globalSecondaryIndexes = (props.globalSecondaryIndexes ?? []).map((g) => {
+        const gpk = g.partitionKey;
+        if (gpk === undefined) throw new Error(`index ${g.indexName} missing partitionKey`);
+        const gsiKeySchema: Array<{ AttributeName: string; KeyType: 'HASH' | 'RANGE' }> = [
+          { AttributeName: gpk.name, KeyType: 'HASH' },
+        ];
+        attributeDefinitions.push({ AttributeName: gpk.name, AttributeType: 'S' });
+        if (g.sortKey !== undefined) {
+          gsiKeySchema.push({ AttributeName: g.sortKey.name, KeyType: 'RANGE' });
+          attributeDefinitions.push({ AttributeName: g.sortKey.name, AttributeType: 'N' });
+        }
+        return {
+          IndexName: g.indexName,
+          KeySchema: gsiKeySchema,
+          Projection: { ProjectionType: 'ALL' as const },
+        };
+      });
       await this.client.send(
         new CreateTableCommand({
           TableName: `${this.prefix}${logical}`,
           AttributeDefinitions: attributeDefinitions,
           KeySchema: keySchema,
+          ...(globalSecondaryIndexes.length > 0
+            ? { GlobalSecondaryIndexes: globalSecondaryIndexes }
+            : {}),
           BillingMode: 'PAY_PER_REQUEST',
         }),
       );

package/packages/aws-adapter/tests/aws-runtime.test.ts

@@ -471,6 +471,70 @@ describe.skipIf(!available)('AwsRuntime', () => {
     });
   });
 
+  // -------------------------------------------------------------------------
+  // broadcastOperNotice — Scan-based fan-out to every +o connection (the
+  // OPER lockout gate's oper notice)
+  // -------------------------------------------------------------------------
+
+  describe('broadcastOperNotice', () => {
+    it('delivers to every +o connection and skips the except id', async () => {
+      const receivedA: string[] = [];
+      const receivedB: string[] = [];
+      const stateA = createConnection({ id: 'o-a', connectedSince: 0 });
+      stateA.userModes.oper = true;
+      const stateB = createConnection({ id: 'o-b', connectedSince: 0 });
+      stateB.userModes.oper = true;
+
+      const mgmt = new LocalPostToConnection();
+      mgmt.register('o-a', (data) => {
+        for (const line of data.split('\r\n')) {
+          if (line.length > 0) receivedA.push(line);
+        }
+      });
+      mgmt.register('o-b', (data) => {
+        for (const line of data.split('\r\n')) {
+          if (line.length > 0) receivedB.push(line);
+        }
+      });
+
+      const rtA = makeRuntime('o-a', handlersSink(receivedA, stateA), undefined, mgmt);
+      const rtB = makeRuntime('o-b', handlersSink(receivedB, stateB), undefined, mgmt);
+
+      await rtA.persistConnectionState(stateA);
+      await rtB.persistConnectionState(stateB);
+
+      // Caller 'o-a' is excepted; only 'o-b' should receive the notice.
+      await rtA.broadcastOperNotice(
+        [{ text: ':srv NOTICE * :OPER lockout triggered for h' }],
+        'o-a',
+      );
+      expect(receivedA).toEqual([]);
+      expect(receivedB).toEqual([':srv NOTICE * :OPER lockout triggered for h']);
+    });
+
+    it('does not deliver to a +w-only connection (the gate is +o)', async () => {
+      const received: string[] = [];
+      const state = createConnection({ id: 'o-wonly', connectedSince: 0 });
+      state.userModes.wallops = true;
+      const rt = makeRuntime('o-caller', handlersSink(received, state), undefined, null);
+      await rt.persistConnectionState(state);
+      await rt.broadcastOperNotice([{ text: ':srv NOTICE * :hi' }]);
+      expect(received).toEqual([]);
+    });
+
+    it('delivers to the bound connection via in-process handlers when not excepted', async () => {
+      // The bound connection's own +o delivery goes through handlers.send,
+      // not APIGW. With no `except`, the bound oper conn is a recipient.
+      const received: string[] = [];
+      const state = createConnection({ id: 'self', connectedSince: 0 });
+      state.userModes.oper = true;
+      const rt = makeRuntime('self', handlersSink(received, state), undefined, null);
+      await rt.persistConnectionState(state);
+      await rt.broadcastOperNotice([{ text: ':srv NOTICE * :hi' }]);
+      expect(received).toEqual([':srv NOTICE * :hi']);
+    });
+  });
+
   // -------------------------------------------------------------------------
   // Nick registry — error propagation
   // -------------------------------------------------------------------------