serverless-ircd 0.2.0 → 0.4.0

package/packages/irc-test-support/src/scenarios.ts

@@ -1,13 +1,22 @@
 /**
  * Reusable IRC scenario runner — exported so adapter packages (cf-adapter,
  * aws-stack) can register their own {@link IrcHarnessFactory} and re-run
- * the exact same scenario suite under their native runtime.
+ * the exact same scenario suite under their native runtime AND transport.
  *
  * Each scenario is written once against the {@link IrcHarness} seam. The
  * runner takes a list of factories and produces one `describe` block per
  * factory, mirroring the parametrized matrix called for in PLAN §8
  * ("Runtime contract: vitest parametrized over IrcRuntime. Same scenarios
- * pass in-memory + CF + AWS.").
+ * pass in-memory + CF + AWS.") extended to cover the transport dimension
+ * ("Same scenarios pass in-memory+WS, in-memory+TCP, CF+WS, CF+TCP,
+ * AWS+WS, AWS+TCP.").
+ *
+ * The general scenario block runs against every factory regardless of
+ * transport. The TCP-framing block (chunk boundaries, slow-loris partial
+ * sends, mixed line endings) runs ONLY against factories declaring
+ * `transport: 'tcp'` — those cases are meaningless (and behave
+ * differently) under the WebSocket text-frame transport where every
+ * `feed()` is a complete unit.
  */
 
 import { describe, expect, it } from 'vitest';
@@ -491,5 +500,126 @@ export function runIrcScenarios(factories: readonly IrcHarnessFactory[]): void {
         await harness.close();
       });
     });
+
+    // -------------------------------------------------------------------------
+    // TCP-framing scenarios.
+    //
+    // These cases exercise the stateful `\r\n` byte-stream transport
+    // (PLAN §9, ADR-009): chunk boundaries, partial-line buffering across
+    // chunks, slow-loris-style one-byte sends, bare `\n` tolerance, and
+    // multi-message chunks. They are meaningless under the WebSocket
+    // text-frame transport (where every feed() is a complete unit), so
+    // they only run against factories declaring `transport: 'tcp'`.
+    // -------------------------------------------------------------------------
+    if (factory.transport === 'tcp') {
+      describe(`TCP framing — ${factory.name}`, () => {
+        let harness: IrcHarness;
+
+        it('tcp 01: message split across two chunks produces one command', async () => {
+          harness = await factory.create();
+          const c = await harness.spawnClient({ nick: 'alice' });
+          await c.waitForNumeric('001');
+          c.received.length = 0;
+          // Feed the first half — incomplete, must buffer without dispatching.
+          await c.feed('PI');
+          // Nothing has terminated yet: no PONG, no 421.
+          expect(c.received.length).toBe(0);
+          await c.feed('NG :split\r\n');
+          await c.waitForLine((l) => l === 'PONG :split');
+          await harness.close();
+        });
+
+        it('tcp 02: partial line buffered across many one-byte chunks (slow-loris style)', async () => {
+          harness = await factory.create();
+          const c = await harness.spawnClient({ nick: 'alice' });
+          await c.waitForNumeric('001');
+          c.received.length = 0;
+          const line = 'PING :slow';
+          for (const ch of line) {
+            await c.feed(ch);
+            // No terminator yet — nothing dispatches.
+            expect(c.received.length).toBe(0);
+          }
+          await c.feed('\r\n');
+          await c.waitForLine((l) => l === 'PONG :slow');
+          await harness.close();
+        });
+
+        it('tcp 03: bare LF line ending is tolerated (legacy/mixed clients)', async () => {
+          harness = await factory.create();
+          const c = await harness.spawnClient({ nick: 'alice' });
+          await c.waitForNumeric('001');
+          c.received.length = 0;
+          await c.feed('PING :bare\n');
+          await c.waitForLine((l) => l === 'PONG :bare');
+          await harness.close();
+        });
+
+        it('tcp 04: multiple CRLF-terminated messages in one chunk dispatch in order', async () => {
+          harness = await factory.create();
+          const c = await harness.spawnClient({ nick: 'alice' });
+          await c.waitForNumeric('001');
+          c.received.length = 0;
+          await c.feed('PING :one\r\nPING :two\r\nPING :three\r\n');
+          await c.waitForLine((l) => l === 'PONG :three');
+          const pongs = c.received.filter((l) => l.startsWith('PONG :'));
+          expect(pongs).toEqual(['PONG :one', 'PONG :two', 'PONG :three']);
+          await harness.close();
+        });
+
+        it('tcp 05: mixed CRLF and LF terminators in one chunk both frame', async () => {
+          harness = await factory.create();
+          const c = await harness.spawnClient({ nick: 'alice' });
+          await c.waitForNumeric('001');
+          c.received.length = 0;
+          await c.feed('PING :crlf\r\nPING :lf\n');
+          await c.waitForLine((l) => l === 'PONG :lf');
+          const toks = c.received
+            .filter((l) => l.startsWith('PONG :'))
+            .map((l) => l.slice('PONG :'.length));
+          expect(toks).toEqual(['crlf', 'lf']);
+          await harness.close();
+        });
+
+        it('tcp 06: CRLF terminator split across chunks (CR in one, LF in next)', async () => {
+          harness = await factory.create();
+          const c = await harness.spawnClient({ nick: 'alice' });
+          await c.waitForNumeric('001');
+          c.received.length = 0;
+          await c.feed('PING :cr\r');
+          expect(c.received.length).toBe(0);
+          await c.feed('\n');
+          await c.waitForLine((l) => l === 'PONG :cr');
+          await harness.close();
+        });
+
+        it('tcp 07: an empty chunk is a no-op (no dispatch, no crash)', async () => {
+          harness = await factory.create();
+          const c = await harness.spawnClient({ nick: 'alice' });
+          await c.waitForNumeric('001');
+          c.received.length = 0;
+          await c.feed('');
+          expect(c.received.length).toBe(0);
+          // The connection is still usable after the empty chunk.
+          await c.feed('PING :after-empty\r\n');
+          await c.waitForLine((l) => l === 'PONG :after-empty');
+          await harness.close();
+        });
+
+        it('tcp 08: a complete line followed by a partial line buffers the tail', async () => {
+          harness = await factory.create();
+          const c = await harness.spawnClient({ nick: 'alice' });
+          await c.waitForNumeric('001');
+          c.received.length = 0;
+          await c.feed('PING :first\r\nPI');
+          await c.waitForLine((l) => l === 'PONG :first');
+          // The trailing partial 'PI' must not have dispatched yet.
+          expect(c.received.some((l) => l === 'PONG :')).toBe(false);
+          await c.feed('NG :second\r\n');
+          await c.waitForLine((l) => l === 'PONG :second');
+          await harness.close();
+        });
+      });
+    }
   }
 }

package/packages/irc-test-support/tests/in-memory-harness.test.ts

@@ -12,7 +12,8 @@ import { InMemoryHarness, inMemoryHarnessFactory } from '../src/index.js';
 
 describe('inMemoryHarnessFactory', () => {
   it('exposes a stable name for the describe.each matrix', () => {
-    expect(inMemoryHarnessFactory.name).toBe('in-memory');
+    expect(inMemoryHarnessFactory.name).toBe('in-memory+ws');
+    expect(inMemoryHarnessFactory.transport).toBe('ws');
   });
 
   it('create() returns a fresh, independent InMemoryHarness each call', async () => {

package/packages/irc-test-support/tests/in-memory-scenarios.test.ts

@@ -1,19 +1,33 @@
 /**
- * Parametrized IRC scenarios — 032.
+ * Parametrized IRC scenarios — 032 + 057.
  *
  * The scenario bodies live in `src/scenarios.ts` (now re-exported as
  * `runIrcScenarios`) so adapter packages can register their own
  * {@link IrcHarnessFactory} against the exact same suite under their
  * native vitest configuration (CF runs in `workerd`, AWS runs in node
- * with dynamodb-local, etc.). This file is the in-memory entry point —
- * it registers only {@link inMemoryHarnessFactory}.
+ * with dynamodb-local, etc.). This file is the in-memory entry point.
  *
- * Adding a runtime to the in-memory suite = appending one entry to the
- * `FACTORIES` array (acceptance criterion: "adding a new runtime
- * requires only registering a factory").
+ * The transport dimension extends the matrix: every scenario runs
+ * against (runtime × transport). The in-memory runtime
+ * registers both transports — `inMemoryWsHarnessFactory` (WebSocket
+ * text-frame framing) and `inMemoryTcpHarnessFactory` (raw TCP+TLS
+ * byte-stream framing) — proving the same scenario suite is green across
+ * both transports on the reference runtime. CF and AWS append their own
+ * factories (per transport) to their package suites.
+ *
+ * Adding a runtime OR a transport to the in-memory suite = appending one
+ * entry to the `FACTORIES` array (acceptance criterion: "adding a new
+ * transport requires only registering a factory").
  */
 
-import { inMemoryHarnessFactory, runIrcScenarios } from '../src/index.js';
+import {
+  inMemoryTcpHarnessFactory,
+  inMemoryWsHarnessFactory,
+  runIrcScenarios,
+} from '../src/index.js';
 
-/** The runtime matrix. Adding a runtime = appending one entry here. */
-runIrcScenarios([inMemoryHarnessFactory]);
+/**
+ * The (runtime × transport) matrix. Adding a runtime or transport =
+ * appending one entry here.
+ */
+runIrcScenarios([inMemoryWsHarnessFactory, inMemoryTcpHarnessFactory]);

package/pnpm-workspace.yaml

@@ -2,3 +2,12 @@ packages:
   - "packages/*"
   - "apps/*"
   - "tools/*"
+linkWorkspacePackages: true
+allowBuilds:
+  '@biomejs/biome': true
+  cpu-features: true
+  esbuild: true
+  protobufjs: true
+  sharp: true
+  ssh2: true
+  workerd: true

package/tools/ci-hardening/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/ci-hardening",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": true,
   "description": "CI hardening helpers: coverage-gate config validator + mutation-testing driver for irc-core",
   "license": "BSD-3-Clause",

package/tools/package.json

@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "type": "module"
+}

package/tools/seed-aws-accounts.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Seed SASL PLAIN accounts into the DynamoDB `Accounts` table.
+ *
+ * Usage:
+ *   node --import tsx tools/seed-aws-accounts.ts \
+ *     --table StagingAccounts \
+ *     --endpoint http://localhost:8000 \
+ *     --accounts alice:s3cret bob:password2
+ *
+ * Or read from a file (newline-delimited `username:password`):
+ *   node --import tsx tools/seed-aws-accounts.ts \
+ *     --table StagingAccounts \
+ *     --file accounts.txt
+ *
+ * The script hashes each password with scrypt (never writes plaintext).
+ * Re-running with the same username overwrites the prior row.
+ */
+
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { createDynamoDocumentClient, putAccountCredential } from '@serverless-ircd/aws-adapter';
+
+const { values } = parseArgs({
+  options: {
+    table: { type: 'string' },
+    endpoint: { type: 'string', default: undefined },
+    region: { type: 'string', default: undefined },
+    accounts: { type: 'string', multiple: true, default: [] },
+    file: { type: 'string', default: undefined },
+  },
+});
+
+if (values.table === undefined) {
+  console.error(
+    'Usage: seed-aws-accounts --table <TableName> [--endpoint <url>] [--accounts user:pass ...] [--file <path>]',
+  );
+  process.exit(1);
+}
+
+const clientOptions: Record<string, string> = {};
+if (values.endpoint !== undefined) clientOptions.endpoint = values.endpoint;
+if (values.region !== undefined) clientOptions.region = values.region;
+
+const docClient = createDynamoDocumentClient(clientOptions);
+
+const pairs: Array<{ username: string; password: string }> = [];
+
+for (const pair of values.accounts) {
+  const sep = pair.indexOf(':');
+  if (sep <= 0) {
+    console.error(`Skipping malformed entry (no colon): ${pair}`);
+    continue;
+  }
+  pairs.push({ username: pair.slice(0, sep), password: pair.slice(sep + 1) });
+}
+
+if (values.file !== undefined) {
+  const content = readFileSync(values.file, 'utf-8');
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    const sep = trimmed.indexOf(':');
+    if (sep <= 0) continue;
+    pairs.push({ username: trimmed.slice(0, sep), password: trimmed.slice(sep + 1) });
+  }
+}
+
+if (pairs.length === 0) {
+  console.error('No accounts to seed. Use --accounts or --file.');
+  process.exit(1);
+}
+
+for (const { username, password } of pairs) {
+  const entry = await putAccountCredential(docClient, values.table, username, password);
+  console.log(`Seeded ${username} (algorithm=${entry.algorithm})`);
+}
+
+console.log(`Done: ${pairs.length} account(s) written to ${values.table}.`);

package/tools/seed-cf-accounts.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Seed SASL PLAIN accounts into a Cloudflare D1 `accounts` table.
+ *
+ * Usage:
+ *   node --import tsx tools/seed-cf-accounts.ts \
+ *     --database serverless-ircd-accounts-staging \
+ *     --env staging \
+ *     --remote \
+ *     --accounts alice:s3cret bob:password2
+ *
+ * Or read from a file (newline-delimited `username:password`):
+ *   node --import tsx tools/seed-cf-accounts.ts \
+ *     --database serverless-ircd-accounts-staging \
+ *     --env staging \
+ *     --remote \
+ *     --file accounts.txt
+ *
+ * The script hashes each password with scrypt (never writes plaintext) and
+ * executes the resulting `INSERT OR REPLACE` via `wrangler d1 execute`.
+ * Re-running with the same username overwrites the prior row. The `accounts`
+ * table is created (IF NOT EXISTS) on the first run.
+ *
+ * Flags:
+ *   --database   D1 database name (as declared in wrangler.toml). Required.
+ *   --env        Wrangler environment (e.g. `staging`). Optional.
+ *   --remote     Target the remote D1 (default: local preview).
+ *   --local      Target local D1 (explicit; default).
+ *   --accounts   One or more `username:password` pairs.
+ *   --file       Path to a newline-delimited `username:password` file.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { CREATE_ACCOUNTS_TABLE_SQL, buildAccountPutStatement } from '@serverless-ircd/cf-adapter';
+
+const { values } = parseArgs({
+  options: {
+    database: { type: 'string' },
+    env: { type: 'string', default: undefined },
+    remote: { type: 'boolean', default: false },
+    local: { type: 'boolean', default: false },
+    accounts: { type: 'string', multiple: true, default: [] },
+    file: { type: 'string', default: undefined },
+  },
+});
+
+if (values.database === undefined) {
+  console.error(
+    'Usage: seed-cf-accounts --database <d1-name> [--env staging] [--remote] [--accounts user:pass ...] [--file <path>]',
+  );
+  process.exit(1);
+}
+
+const pairs: Array<{ username: string; password: string }> = [];
+
+for (const pair of values.accounts) {
+  const sep = pair.indexOf(':');
+  if (sep <= 0) {
+    console.error(`Skipping malformed entry (no colon): ${pair}`);
+    continue;
+  }
+  pairs.push({ username: pair.slice(0, sep), password: pair.slice(sep + 1) });
+}
+
+if (values.file !== undefined) {
+  const content = readFileSync(values.file, 'utf-8');
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    const sep = trimmed.indexOf(':');
+    if (sep <= 0) continue;
+    pairs.push({ username: trimmed.slice(0, sep), password: trimmed.slice(sep + 1) });
+  }
+}
+
+if (pairs.length === 0) {
+  console.error('No accounts to seed. Use --accounts or --file.');
+  process.exit(1);
+}
+
+/** Runs `wrangler d1 execute` with the supplied SQL command. */
+function runD1Execute(sql: string): void {
+  const args = ['d1', 'execute', values.database as string, '--command', sql];
+  if (values.env !== undefined) {
+    args.push('--env', values.env);
+  }
+  if (values.remote) {
+    args.push('--remote');
+  }
+  execFileSync('npx', ['wrangler', ...args], { stdio: 'inherit' });
+}
+
+// Ensure the table exists (idempotent).
+runD1Execute(CREATE_ACCOUNTS_TABLE_SQL);
+
+for (const { username, password } of pairs) {
+  const { entry, sql } = buildAccountPutStatement(username, password);
+  runD1Execute(sql);
+  console.log(`Seeded ${username} (algorithm=${entry.algorithm})`);
+}
+
+console.log(`Done: ${pairs.length} account(s) written to D1 database ${values.database}.`);

package/tools/tcp-ws-forwarder/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/tcp-ws-forwarder",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": true,
   "description": "Local TCP to ws/wss forwarder so standard IRC clients can reach the WebSocket-only ServerlessIRCd transport",
   "license": "BSD-3-Clause",

package/AGENTS.md

@@ -1,5 +0,0 @@
-# AGENTS.md
-
-## Code Style
-
-- **Do not reference ticket IDs in source files.** Never put `TICKET-###` or similar ticket-tracker tokens in `.ts` or `.js` files (code or comments). Describe the intent or cross-reference by feature/command name instead. Ticket tracking lives in `progress.md` / `tickets.md`, not in source.

package/MOTD.txt

@@ -1,3 +0,0 @@
-Welcome to the test network for Serverless IRCd project.
-
-Join #general for chat.