serverless-ircd 0.1.0 → 0.2.0

package/apps/local-cli/tests/security-e2e.test.ts

@@ -0,0 +1,239 @@
+/**
+ * End-to-end tests for the production-hardening security features:
+ *   server password enforcement, hostmask cloaking, and
+ *   the connection-admission gate.
+ *
+ * These tests boot a real `startLocalServer` with the relevant config
+ * knobs and drive it over WebSocket — the same path a real IRC client
+ * takes. The unit-test coverage for each limit lives next to the
+ * implementation; this file verifies the wiring through the local CLI.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { WebSocket } from 'ws';
+import { type LocalServer, startLocalServer } from '../src/server';
+
+class TestClient {
+  readonly ws: WebSocket;
+  readonly received: string[] = [];
+
+  constructor(url: string) {
+    this.ws = new WebSocket(url);
+    this.ws.on('message', (data) => {
+      const text = data.toString('utf8');
+      for (const line of text.split(/\r?\n/u)) {
+        if (line.length > 0) this.received.push(line);
+      }
+    });
+  }
+
+  opened(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.ws.readyState === WebSocket.OPEN) resolve();
+      else if (this.ws.readyState === WebSocket.CLOSED)
+        reject(new Error('socket closed before open'));
+      else {
+        this.ws.once('open', () => resolve());
+        this.ws.once('error', reject);
+        this.ws.once('close', () => reject(new Error('socket closed before open')));
+      }
+    });
+  }
+
+  /** Resolves once the underlying socket closes. */
+  closed(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.ws.readyState === WebSocket.CLOSED) resolve();
+      else this.ws.once('close', () => resolve());
+    });
+  }
+
+  send(line: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws.send(`${line}\r\n`, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  waitFor(predicate: (line: string) => boolean, timeoutMs = 1_000): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error(`timeout; received: ${JSON.stringify(this.received)}`));
+      }, timeoutMs);
+      const check = (line: string) => {
+        if (predicate(line)) {
+          clearTimeout(timeout);
+          this.ws.off('message', onMessage);
+          resolve(line);
+        }
+      };
+      const onMessage = (data: { toString: (enc: string) => string }): void => {
+        const text = data.toString('utf8');
+        for (const line of text.split(/\r?\n/u)) {
+          if (line.length > 0) check(line);
+        }
+      };
+      for (const line of this.received) {
+        if (predicate(line)) {
+          clearTimeout(timeout);
+          resolve(line);
+          return;
+        }
+      }
+      this.ws.on('message', onMessage);
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      this.ws.once('close', () => resolve());
+      this.ws.close();
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Server password
+// ---------------------------------------------------------------------------
+
+describe('local-cli e2e — server password', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'pwd.example.com',
+      networkName: 'PwdNet',
+      serverPassword: 's3cret',
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('rejects a client that registers without the password', async () => {
+    const client = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('NICK alice');
+    await client.send('USER alice 0 * :Alice');
+    // 464 ERR_PASSWDMISMATCH followed by ERROR :Closing link.
+    await client.waitFor((l) => l.includes(' 464 '));
+    await client.waitFor((l) => l.startsWith('ERROR :Closing link'));
+    await client.close();
+  });
+
+  it('rejects a client that supplies the wrong password', async () => {
+    const client = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('PASS wrong');
+    await client.send('NICK bob');
+    await client.send('USER bob 0 * :Bob');
+    await client.waitFor((l) => l.includes(' 464 '));
+    await client.close();
+  });
+
+  it('admits a client that supplies the correct password', async () => {
+    const client = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('PASS s3cret');
+    await client.send('NICK carol');
+    await client.send('USER carol 0 * :Carol');
+    await client.waitFor((l) => l.startsWith(':pwd.example.com 001 '));
+    await client.close();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Hostmask cloaking
+// ---------------------------------------------------------------------------
+
+describe('local-cli e2e — hostmask cloaking', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'cloak.example.com',
+      networkName: 'CloakNet',
+      cloaking: { enabled: true, secret: 'hunter2', cloakedSuffix: 'hidden.lan' },
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('emits the cloaked host in the 001 welcome line', async () => {
+    const client = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('NICK alice');
+    await client.send('USER alice 0 * :Alice');
+    const welcome = await client.waitFor((l) => l.startsWith(':cloak.example.com 001 '));
+    // The cloaked host ends in the configured suffix and is NOT the raw IP.
+    expect(welcome.endsWith('.hidden.lan')).toBe(true);
+    // 001 format: :server 001 nick :Welcome to the Network IRC Network, nick!user@host
+    const hostSegment = welcome.split('@').slice(-1)[0] ?? '';
+    expect(hostSegment.endsWith('.hidden.lan')).toBe(true);
+    await client.close();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Admission gate — per-IP connection cap
+// ---------------------------------------------------------------------------
+
+describe('local-cli e2e — admission gate (per-IP cap)', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'cap.example.com',
+      networkName: 'CapNet',
+      // Tight caps so the e2e test can saturate them quickly.
+      maxConnectionsPerIp: 2,
+      maxConnectionsPerUser: 100,
+      perIpConnectionRate: { max: 1_000, windowMs: 60_000 },
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('admits connections up to the cap then refuses further admissions', async () => {
+    const url = `ws://127.0.0.1:${server.port}/`;
+    const c1 = new TestClient(url);
+    const c2 = new TestClient(url);
+    await c1.opened();
+    await c2.opened();
+    // First two register fine.
+    await c1.send('NICK a1');
+    await c1.send('USER a1 0 * :A');
+    await c1.waitFor((l) => l.startsWith(':cap.example.com 001 '));
+    await c2.send('NICK a2');
+    await c2.send('USER a2 0 * :A');
+    await c2.waitFor((l) => l.startsWith(':cap.example.com 001 '));
+
+    // Third exceeds the per-IP cap (maxConnectionsPerIp: 2). The server
+    // sends an ERROR notice and closes the socket. Either opened() rejects
+    // (close-before-open) or the ERROR line arrives before close.
+    const c3 = new TestClient(url);
+    // Wait for either rejection path without racing into an unhandled
+    // rejection: opened() rejects on close, and we catch it.
+    await c3.opened().catch(() => {
+      // Expected: server closed the socket during/before handshake.
+    });
+    // If the socket did open, the server still sends ERROR then closes.
+    if (c3.ws.readyState === WebSocket.OPEN) {
+      await c3.waitFor((l) => l.startsWith('ERROR :Closing link'));
+    }
+    await c3.closed();
+
+    await c1.close();
+    await c2.close();
+  });
+});

package/biome.json

@@ -12,7 +12,9 @@
       "**/coverage/**",
       "**/node_modules/**",
       "**/.turbo/**",
-      "pnpm-lock.yaml"
+      "pnpm-lock.yaml",
+      "cdk.out/",
+      "*.template.json"
     ]
   },
   "formatter": {

package/dashboards/cloudwatch-irc.json

@@ -0,0 +1,139 @@
+{
+  "widgets": [
+    {
+      "type": "metric",
+      "x": 0,
+      "y": 0,
+      "width": 12,
+      "height": 6,
+      "properties": {
+        "view": "timeSeries",
+        "stacked": false,
+        "metrics": [
+          ["AWS/ApiGateway", "ConnectCount", "ApiId", "${API_ID}"],
+          [".", "DisconnectCount", ".", "."]
+        ],
+        "region": "${AWS_REGION}",
+        "title": "Connections per second",
+        "period": 60,
+        "stat": "Sum"
+      }
+    },
+    {
+      "type": "metric",
+      "x": 12,
+      "y": 0,
+      "width": 12,
+      "height": 6,
+      "properties": {
+        "view": "timeSeries",
+        "stacked": false,
+        "metrics": [
+          [
+            "AWS/Lambda",
+            "Duration",
+            "FunctionName",
+            "${LAMBDA_NAME}",
+            "Resource",
+            "${LAMBDA_NAME}:$default"
+          ]
+        ],
+        "region": "${AWS_REGION}",
+        "title": "$default handler latency (p50/p95/p99)",
+        "period": 60,
+        "stat": ["p50", "p95", "p99"]
+      }
+    },
+    {
+      "type": "metric",
+      "x": 0,
+      "y": 6,
+      "width": 12,
+      "height": 6,
+      "properties": {
+        "view": "timeSeries",
+        "stacked": false,
+        "metrics": [["AWS/Lambda", "Errors", "FunctionName", "${LAMBDA_NAME}"]],
+        "region": "${AWS_REGION}",
+        "title": "Lambda errors per minute",
+        "period": 60,
+        "stat": "Sum"
+      }
+    },
+    {
+      "type": "log",
+      "x": 12,
+      "y": 6,
+      "width": 12,
+      "height": 6,
+      "properties": {
+        "view": "logs",
+        "stacked": false,
+        "query": "SOURCE '${LOG_GROUP_ARN}' | fields @timestamp, msg, level, traceId, connectionId, effect\n| filter level = \"error\" or msg = \"dispatch.error\" or msg = \"frame.parse-error\"\n| sort @timestamp desc\n| limit 100",
+        "region": "${AWS_REGION}",
+        "title": "Recent errors (level=error / dispatch.error / frame.parse-error)",
+        "period": 60
+      }
+    },
+    {
+      "type": "log",
+      "x": 0,
+      "y": 12,
+      "width": 24,
+      "height": 6,
+      "properties": {
+        "view": "logs",
+        "stacked": false,
+        "query": "SOURCE '${LOG_GROUP_ARN}' | filter msg = \"dispatch\"\n| stats count(*) as effects_per_minute by histogram(@timestamp, 1m)\n| sort @timestamp desc",
+        "region": "${AWS_REGION}",
+        "title": "Dispatched effects per minute (from structured log msg=dispatch)",
+        "period": 60
+      }
+    }
+  ],
+  "dashboardNameTemplate": "ServerlessIRCd-${ENVIRONMENT}",
+  "dashboardFilters": {
+    "variables": [
+      {
+        "name": "ENVIRONMENT",
+        "type": "Pattern",
+        "value": "staging",
+        "input": {
+          "id": "input/text"
+        }
+      },
+      {
+        "name": "API_ID",
+        "type": "Pattern",
+        "value": "",
+        "input": {
+          "id": "input/text"
+        }
+      },
+      {
+        "name": "LAMBDA_NAME",
+        "type": "Pattern",
+        "value": "serverless-ircd-handler",
+        "input": {
+          "id": "input/text"
+        }
+      },
+      {
+        "name": "LOG_GROUP_ARN",
+        "type": "Pattern",
+        "value": "",
+        "input": {
+          "id": "input/text"
+        }
+      },
+      {
+        "name": "AWS_REGION",
+        "type": "Pattern",
+        "value": "us-east-1",
+        "input": {
+          "id": "input/text"
+        }
+      }
+    ]
+  }
+}