serverless-ircd 0.9.0 → 0.11.0

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

@@ -5,7 +5,12 @@
  * new connection row. The admission policy itself is covered by
  * `admission.test.ts`; the counter primitives by `connection-counter.test.ts`.
  */
-import { type DynamoDBDocumentClient, PutCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
+import {
+  type DynamoDBDocumentClient,
+  PutCommand,
+  QueryCommand,
+  UpdateCommand,
+} from '@aws-sdk/lib-dynamodb';
 import { makeTestServerConfig } from '@serverless-ircd/irc-test-support';
 import { describe, expect, it } from 'vitest';
 import { handleConnect } from '../src/handlers/connect.js';
@@ -17,7 +22,6 @@ const TABLES: TablesConfig = {
   ChannelMeta: 'ChannelMeta',
   ChannelMembers: 'ChannelMembers',
   Nicks: 'Nicks',
-  Accounts: 'Accounts',
 };
 
 interface Stub {
@@ -31,16 +35,27 @@ interface Stub {
   decrements: number;
   /** Commands issued, in order (for asserting no Scan is used). */
   commands: string[];
+  /** QueryCommand inputs issued (for asserting the GSI consultation). */
+  queries: Array<Record<string, unknown>>;
 }
 
+/**
+ * Rows the stub's GSI Query pages return, per call (an outer array entry
+ * per page). Defaults to a single empty page.
+ */
+type QueryPages = Array<Array<{ connectedSince: number }>>;
+
 /**
  * Builds a stub client with an initial admission counter value. The stub
  * honours the floor-at-0 decrement condition the real handler relies on.
+ * `gsiPages` simulates the sourceIp-GSI Query result pages.
  */
-function makeStub(initialCount: number): Stub {
+function makeStub(initialCount: number, gsiPages: QueryPages = [[]]): Stub {
   const state = { count: initialCount, puts: 0, increments: 0, decrements: 0 };
   let lastPutItem: Record<string, unknown> | undefined;
   const commands: string[] = [];
+  const queries: Array<Record<string, unknown>> = [];
+  let queryCall = 0;
   const dynamo = {
     send: async (cmd: unknown) => {
       if (cmd instanceof UpdateCommand) {
@@ -65,8 +80,22 @@ function makeStub(initialCount: number): Stub {
           }
           return { Attributes: { count: state.count } };
         }
+        // Non-counter Update expressions are not expected on this path.
         throw new Error(`unexpected Update expression: ${expr}`);
       }
+      if (cmd instanceof QueryCommand) {
+        commands.push('Query');
+        queries.push(cmd.input as Record<string, unknown>);
+        const page = gsiPages[queryCall] ?? [];
+        const last = queryCall;
+        queryCall += 1;
+        return {
+          Items: page,
+          // Multi-page when the scripted result says so and more calls follow.
+          LastEvaluatedKey:
+            last + 1 < gsiPages.length ? { connectionId: `page-${last}` } : undefined,
+        };
+      }
       if (cmd instanceof PutCommand) {
         commands.push('Put');
         state.puts += 1;
@@ -97,6 +126,9 @@ function makeStub(initialCount: number): Stub {
     get commands() {
       return commands;
     },
+    get queries() {
+      return queries;
+    },
   };
 }
 
@@ -298,3 +330,291 @@ describe('handleConnect — IRCv3 WebSocket subprotocol negotiation', () => {
     expect(stub.puts).toBe(0);
   });
 });
+
+describe('handleConnect — Origin allowlist (CSWSH defence)', () => {
+  // The same lowercase / trim / comma-split semantics as the CF Worker's
+  // policy (`apps/cf-worker/src/origin-allowlist.ts`); the parsed set is
+  // built once per cold start and injected via `ConnectParams.webOrigins`.
+  const allowlist = new Set(['https://app.example.com']);
+
+  it('denies a disallowed Origin with 403 before touching the counter', async () => {
+    // A denied upgrade must NOT consume an admission slot — the Origin
+    // check runs before the counter increment so a CSWSH flood from a
+    // hostile origin cannot exhaust the `maxClients` cap.
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-cswsh',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: 'https://attacker.example.com',
+      webOrigins: allowlist,
+    });
+    expect(outcome).toEqual({
+      admitted: false,
+      statusCode: 403,
+      reason: expect.stringMatching(/origin/iu),
+    });
+    expect(stub.puts).toBe(0);
+    expect(stub.increments).toBe(0);
+    expect(stub.decrements).toBe(0);
+  });
+
+  it('admits an allowed Origin (existing connect path)', async () => {
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-ok',
+      now: 42,
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: 'https://app.example.com',
+      webOrigins: allowlist,
+    });
+    expect(outcome).toEqual({ admitted: true, subprotocol: null });
+    expect(stub.puts).toBe(1);
+  });
+
+  it('case-insensitively matches a mixed-case allowed Origin', async () => {
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-case',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: 'https://APP.Example.COM',
+      webOrigins: allowlist,
+    });
+    expect(outcome.admitted).toBe(true);
+  });
+
+  it('admits a missing Origin (non-browser client: curl, WeeChat, tcp-ws-forwarder)', async () => {
+    // The defence only fires when `Origin` is present; non-browser
+    // tooling never sends it and must pass through unchanged.
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-cli',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: null,
+      webOrigins: allowlist,
+    });
+    expect(outcome.admitted).toBe(true);
+    expect(stub.puts).toBe(1);
+  });
+
+  it('admits a missing Origin when the header key is absent from the event', async () => {
+    // APIGW may omit the header entirely on some non-browser flows;
+    // `undefined` is treated the same as `null`.
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-noheader',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: undefined,
+      webOrigins: allowlist,
+    });
+    expect(outcome.admitted).toBe(true);
+  });
+
+  it('skips the check when WEB_ORIGINS is unset (defence is opt-in)', async () => {
+    // An empty allowlist means the deployment has not opted in; every
+    // Origin (including an obviously hostile one) must proceed so
+    // existing AWS deployments without a web frontend are unchanged
+    // on upgrade.
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-unset',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: 'https://attacker.example.com',
+      webOrigins: new Set(),
+    });
+    expect(outcome.admitted).toBe(true);
+    expect(stub.puts).toBe(1);
+  });
+
+  it('denies an Origin that matches a listed origin except for the scheme', async () => {
+    // Origins are case-sensitive on scheme+host+port; an `http://`
+    // form MUST NOT be admitted against an `https://`-only allowlist
+    // (defends against a stripped-TLS attacker on the same hostname).
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-scheme',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: 'http://app.example.com',
+      webOrigins: allowlist,
+    });
+    expect(outcome.admitted).toBe(false);
+    expect(outcome.admitted === false && outcome.statusCode).toBe(403);
+  });
+});
+
+describe('handleConnect — per-IP admission (sourceIp GSI)', () => {
+  /** Fixed epoch base so window membership is deterministic. */
+  const NOW = 1_700_000_000_000;
+
+  it('consults the sourceIp GSI when sourceIp is present', async () => {
+    const stub = makeStub(0, [[{ connectedSince: NOW - 1000 }]]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-gsi',
+      now: NOW,
+      sourceIp: '203.0.113.20',
+      serverConfig: makeTestServerConfig({ maxClients: 5, maxConnectionsPerIp: 3 }),
+    });
+    expect(outcome.admitted).toBe(true);
+    expect(stub.queries.length).toBe(1);
+    const q = stub.queries[0];
+    expect(q?.IndexName).toBe('sourceIp-connectedSince');
+    expect(q?.ExpressionAttributeValues).toMatchObject({ ':ip': '203.0.113.20' });
+  });
+
+  it('rejects with 429 once the per-IP count reaches maxConnectionsPerIp', async () => {
+    const stub = makeStub(0, [
+      [
+        { connectedSince: NOW - 1000 },
+        { connectedSince: NOW - 2000 },
+        { connectedSince: NOW - 3000 },
+      ],
+    ]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-perip',
+      now: NOW,
+      sourceIp: '203.0.113.21',
+      serverConfig: makeTestServerConfig({ maxClients: 50, maxConnectionsPerIp: 3 }),
+    });
+    expect(outcome).toEqual({
+      admitted: false,
+      statusCode: 429,
+      reason: 'too many connections from this IP',
+    });
+    expect(stub.puts).toBe(0);
+  });
+
+  it('rolls back the counter reservation when the per-IP cap rejects', async () => {
+    const stub = makeStub(0, [[{ connectedSince: NOW - 1000 }]]);
+    await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-perip-rb',
+      now: NOW,
+      sourceIp: '203.0.113.22',
+      serverConfig: makeTestServerConfig({ maxClients: 50, maxConnectionsPerIp: 1 }),
+    });
+    expect(stub.increments).toBe(1);
+    expect(stub.decrements).toBe(1);
+    expect(stub.count).toBe(0);
+  });
+
+  it('admits below the per-IP cap and persists sourceIp on the row', async () => {
+    const stub = makeStub(0, [[{ connectedSince: NOW - 1000 }]]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-perip-ok',
+      now: NOW,
+      sourceIp: '203.0.113.23',
+      serverConfig: makeTestServerConfig({ maxClients: 5, maxConnectionsPerIp: 3 }),
+    });
+    expect(outcome).toEqual({ admitted: true, subprotocol: null });
+    expect(stub.lastPutItem?.sourceIp).toBe('203.0.113.23');
+  });
+
+  it('rejects with 429 once the recent-window count reaches the rate budget', async () => {
+    // Five admissions from this IP inside the window (and one stale row
+    // outside it — the stale one must not count toward the budget).
+    const rows = [
+      { connectedSince: NOW - 1000 },
+      { connectedSince: NOW - 2000 },
+      { connectedSince: NOW - 3000 },
+      { connectedSince: NOW - 4000 },
+      { connectedSince: NOW - 5000 },
+      { connectedSince: NOW - 120_000 },
+    ];
+    const stub = makeStub(0, [rows]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-rate',
+      now: NOW,
+      sourceIp: '203.0.113.24',
+      serverConfig: makeTestServerConfig({
+        maxClients: 50,
+        maxConnectionsPerIp: 50,
+        perIpConnectionRate: { max: 5, windowMs: 60_000 },
+      }),
+    });
+    expect(outcome).toEqual({
+      admitted: false,
+      statusCode: 429,
+      reason: 'connection rate exceeded for this IP',
+    });
+    expect(stub.puts).toBe(0);
+  });
+
+  it('window-reset: admissions older than the window no longer trip the rate budget', async () => {
+    // Same five admissions, but all outside the 60 s window → the recent
+    // count is 0 and the rate branch must not fire.
+    const rows = Array.from({ length: 5 }, (_, i) => ({ connectedSince: NOW - 120_000 - i }));
+    const stub = makeStub(0, [rows]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-reset',
+      now: NOW,
+      sourceIp: '203.0.113.25',
+      serverConfig: makeTestServerConfig({
+        maxClients: 50,
+        maxConnectionsPerIp: 50,
+        perIpConnectionRate: { max: 5, windowMs: 60_000 },
+      }),
+    });
+    expect(outcome).toEqual({ admitted: true, subprotocol: null });
+    expect(stub.puts).toBe(1);
+  });
+
+  it('paginates the GSI query when the per-IP partition spans pages', async () => {
+    const stub = makeStub(0, [
+      [{ connectedSince: NOW - 1000 }, { connectedSince: NOW - 2000 }],
+      [{ connectedSince: NOW - 3000 }, { connectedSince: NOW - 4000 }],
+    ]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-pages',
+      now: NOW,
+      sourceIp: '203.0.113.26',
+      serverConfig: makeTestServerConfig({ maxClients: 50, maxConnectionsPerIp: 3 }),
+    });
+    // 4 existing connections across two pages ≥ cap 3 → rejected.
+    expect(outcome).toEqual({
+      admitted: false,
+      statusCode: 429,
+      reason: 'too many connections from this IP',
+    });
+    expect(stub.queries.length).toBe(2);
+  });
+
+  it('skips the per-IP checks entirely when no sourceIp is present (no GSI query)', async () => {
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-noip',
+      now: NOW,
+      serverConfig: makeTestServerConfig({ maxClients: 5, maxConnectionsPerIp: 1 }),
+    });
+    expect(outcome).toEqual({ admitted: true, subprotocol: null });
+    expect(stub.queries.length).toBe(0);
+    expect(stub.commands).not.toContain('Query');
+  });
+});

package/packages/aws-adapter/tests/default-frame-limit.test.ts

@@ -0,0 +1,231 @@
+/**
+ * AWS `$default` handler — per-connection inbound frame-rate window at
+ * the adapter boundary.
+ *
+ * The gate fires BEFORE the actor run / state write: a connection that
+ * delivered more than `adapter.maxFramesPerWindow` frames inside the
+ * `adapter.frameWindowSeconds` sliding window receives
+ * `ERROR :Closing link (flooding)` via the management API, is closed via
+ * `DeleteConnection` (which fires the `$disconnect` cleanup), and the
+ * invocation skips the actor + persist entirely.
+ *
+ * The window state persists as the `frameTimes` attribute on the
+ * Connections row (a short list of epoch-ms timestamps), so the limit
+ * holds across Lambda invocations and isolates. Admitted frames persist
+ * their window in the SAME conditional write as the actor state, so the
+ * optimistic-concurrency revision guard makes each frame count exactly
+ * once.
+ */
+
+import { GetCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import {
+  FakeClock,
+  type ParsedServerConfig,
+  StaticMotdProvider,
+  createConnection,
+} from '@serverless-ircd/irc-core';
+import { makeTestServerConfig } from '@serverless-ircd/irc-test-support';
+import { describe, expect, it } from 'vitest';
+import { handleDefault } from '../src/handlers/default.js';
+import { marshalConnection } from '../src/serialize.js';
+import type { TablesConfig } from '../src/tables.js';
+
+const SERVER_CONFIG: ParsedServerConfig = makeTestServerConfig({
+  serverName: 'irc.example.com',
+  networkName: 'ExampleNet',
+  motdLines: ['Welcome'],
+  adapter: { maxFramesPerWindow: 3, frameWindowSeconds: 5 },
+});
+const MOTD = new StaticMotdProvider(SERVER_CONFIG.motdLines);
+const TABLES: TablesConfig = {
+  Connections: 'Connections',
+  ChannelMeta: 'ChannelMeta',
+  ChannelMembers: 'ChannelMembers',
+  Nicks: 'Nicks',
+  Services: 'Services',
+};
+
+/**
+ * Minimal fake document client: returns the seeded row on GetCommand and
+ * applies the pieces of the persist expression the frame-limit
+ * assertions care about (revision bump, frameTimes SET, capNegotiating).
+ */
+class FakeDynamo {
+  readonly items = new Map<string, Record<string, unknown>>();
+  updateCalls = 0;
+  getCalls = 0;
+
+  async send(cmd: unknown): Promise<{ Item?: Record<string, unknown> } | Record<string, never>> {
+    if (cmd instanceof GetCommand) {
+      this.getCalls += 1;
+      const input = (cmd as unknown as { input: { Key: { connectionId: string } } }).input;
+      const item = this.items.get(input.Key.connectionId);
+      return item === undefined ? {} : { Item: structuredClone(item) };
+    }
+    if (cmd instanceof UpdateCommand) {
+      this.updateCalls += 1;
+      const input = (
+        cmd as unknown as {
+          input: {
+            Key: { connectionId: string };
+            ExpressionAttributeValues?: Record<string, unknown>;
+          };
+        }
+      ).input;
+      const cur = this.items.get(input.Key.connectionId);
+      if (cur !== undefined) {
+        cur.revision = ((cur.revision as number | undefined) ?? 0) + 1;
+        const vals = input.ExpressionAttributeValues ?? {};
+        if (vals[':capN'] !== undefined) cur.capNegotiating = vals[':capN'];
+        if (vals[':ft'] !== undefined) cur.frameTimes = vals[':ft'];
+      }
+      return {};
+    }
+    return {};
+  }
+}
+
+/** Management-API double that records posts AND connection deletes. */
+class RecordingMgmt {
+  readonly posted: string[] = [];
+  readonly deleted: string[] = [];
+
+  async postToConnection(input: { ConnectionId: string; Data: string }): Promise<unknown> {
+    this.posted.push(input.Data);
+    return {};
+  }
+
+  async deleteConnection(input: { ConnectionId: string }): Promise<unknown> {
+    this.deleted.push(input.ConnectionId);
+    return {};
+  }
+}
+
+/** `PostToConnection`-shaped double with NO deleteConnection arm. */
+class PostOnlyMgmt {
+  readonly posted: string[] = [];
+
+  async postToConnection(input: { ConnectionId: string; Data: string }): Promise<unknown> {
+    this.posted.push(input.Data);
+    return {};
+  }
+}
+
+/** Management double whose postToConnection rejects (socket already gone). */
+class FailingMgmt {
+  async postToConnection(): Promise<unknown> {
+    throw new Error('GoneException');
+  }
+}
+
+interface Fixture {
+  dynamo: FakeDynamo;
+  clock: FakeClock;
+  connId: string;
+}
+
+function seed(connId: string, startMs = 1_000): Fixture {
+  const dynamo = new FakeDynamo();
+  const state = createConnection({ id: connId, connectedSince: startMs });
+  state.capNegotiating = true;
+  dynamo.items.set(connId, { ...marshalConnection(state, startMs) });
+  return { dynamo, clock: new FakeClock(startMs), connId };
+}
+
+function run(
+  fixture: Fixture,
+  body: string,
+  mgmt: unknown = null,
+): Promise<{ statusCode: number }> {
+  return handleDefault({
+    dynamo: fixture.dynamo as unknown as DynamoDBDocumentClient,
+    tables: TABLES,
+    connectionId: fixture.connId,
+    body,
+    serverConfig: SERVER_CONFIG,
+    motd: MOTD,
+    managementApi: mgmt as never,
+    clock: fixture.clock,
+  });
+}
+
+describe('handleDefault — inbound frame-rate window (3 frames / 5 s)', () => {
+  it('admits frames under and at the ceiling, persisting the window on the row', async () => {
+    const fx = seed('c-admit');
+    for (let i = 1; i <= 3; i++) {
+      const res = await run(fx, `PING :${i}\r\n`);
+      expect(res.statusCode).toBe(200);
+    }
+    expect(fx.dynamo.updateCalls).toBe(3);
+    const row = fx.dynamo.items.get('c-admit');
+    expect((row?.frameTimes as number[]).length).toBe(3);
+  });
+
+  it('closes the connection on the over-threshold frame without running the actor or persisting', async () => {
+    const fx = seed('c-flood');
+    const mgmt = new RecordingMgmt();
+    for (let i = 1; i <= 3; i++) {
+      await run(fx, `PING :${i}\r\n`, mgmt);
+    }
+    const before = fx.dynamo.items.get('c-flood');
+
+    const res = await run(fx, 'PING :4\r\n', mgmt);
+    expect(res.statusCode).toBe(200);
+    // No actor run, no state write: the row is untouched.
+    expect(fx.dynamo.updateCalls).toBe(3);
+    expect(fx.dynamo.items.get('c-flood')).toEqual(before);
+    // The ERROR line was delivered, then the socket was closed via the
+    // management API (DeleteConnection fires the $disconnect cleanup).
+    expect(mgmt.posted).toContain('ERROR :Closing link (flooding)');
+    expect(mgmt.deleted).toEqual(['c-flood']);
+  });
+
+  it('admits a fresh burst after the window decays (sliding window)', async () => {
+    const fx = seed('c-decay');
+    for (let i = 1; i <= 3; i++) {
+      await run(fx, `PING :${i}\r\n`);
+    }
+    // 50 frames, wait 6 s, more frames — per the ticket's decay contract.
+    fx.clock.advance(6_000);
+    const res = await run(fx, 'PING :post-window\r\n');
+    expect(res.statusCode).toBe(200);
+    const row = fx.dynamo.items.get('c-decay');
+    // The aged burst decayed out; only the fresh frame's timestamp
+    // remains in the persisted window.
+    expect((row?.frameTimes as number[]).length).toBe(1);
+  });
+
+  it('skips the actor and close when managementApi is null (no post, no delete, no write)', async () => {
+    const fx = seed('c-null-mgmt');
+    for (let i = 1; i <= 3; i++) {
+      await run(fx, `PING :${i}\r\n`);
+    }
+    const res = await run(fx, 'PING :4\r\n');
+    expect(res.statusCode).toBe(200);
+    expect(fx.dynamo.updateCalls).toBe(3);
+  });
+
+  it('delivers the ERROR line but skips the delete when the api double has no deleteConnection', async () => {
+    const fx = seed('c-post-only');
+    const mgmt = new PostOnlyMgmt();
+    for (let i = 1; i <= 3; i++) {
+      await run(fx, `PING :${i}\r\n`, mgmt);
+    }
+    const res = await run(fx, 'PING :4\r\n', mgmt);
+    expect(res.statusCode).toBe(200);
+    expect(mgmt.posted).toContain('ERROR :Closing link (flooding)');
+    expect(fx.dynamo.updateCalls).toBe(3);
+  });
+
+  it('still returns 200 when the flood-close post fails (socket already gone)', async () => {
+    const fx = seed('c-post-fail');
+    const mgmt = new FailingMgmt();
+    for (let i = 1; i <= 3; i++) {
+      await run(fx, `PING :${i}\r\n`, mgmt);
+    }
+    const res = await run(fx, 'PING :4\r\n', mgmt);
+    expect(res.statusCode).toBe(200);
+    expect(fx.dynamo.updateCalls).toBe(3);
+  });
+});