serverless-ircd 0.3.0 → 0.5.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';
@@ -183,7 +192,15 @@ export function runIrcScenarios(factories: readonly IrcHarnessFactory[]): void {
         await alice.waitForLine((l) => l.includes('JOIN #bar'));
         alice.received.length = 0;
         await alice.send('JOIN 0');
-        await alice.waitForLine((l) => l.includes('PART'));
+        // The two PART echoes arrive as separate deliveries (one per
+        // channel, with an ApplyChannelDelta in between). On distributed
+        // runtimes (cf-adapter) they land in distinct WS messages with
+        // cross-DO latency between them, so waiting for the first generic
+        // PART and then snapshotting `received` races the second one.
+        // Wait for each channel's PART explicitly to make the observation
+        // deterministic across in-memory and DO-backed runtimes.
+        await alice.waitForLine((l) => l.includes('PART') && l.includes('#foo'));
+        await alice.waitForLine((l) => l.includes('PART') && l.includes('#bar'));
         const parts = alice.received.filter((l) => l.includes('PART'));
         expect(parts.length).toBe(2);
         expect(parts.some((l) => l.includes('#foo'))).toBe(true);
@@ -491,5 +508,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.
  *
  * 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

@@ -1,5 +1,14 @@
-linkedWorkspacePackages: true
 packages:
   - "packages/*"
   - "apps/*"
+  - "tools"
   - "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.5.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,9 @@
+{
+  "name": "@serverless-ircd/tools",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@serverless-ircd/aws-adapter": "workspace:*",
+    "@serverless-ircd/cf-adapter": "workspace:*"
+  }
+}

package/tools/seed-aws-accounts.ts

@@ -17,12 +17,9 @@
  * Re-running with the same username overwrites the prior row.
  */
 
-import { parseArgs } from 'node:util';
 import { readFileSync } from 'node:fs';
-import {
-  createDynamoDocumentClient,
-  putAccountCredential,
-} from '@serverless-ircd/aws-adapter';
+import { parseArgs } from 'node:util';
+import { createDynamoDocumentClient, putAccountCredential } from '@serverless-ircd/aws-adapter';
 
 const { values } = parseArgs({
   options: {
@@ -35,7 +32,9 @@ const { values } = parseArgs({
 });
 
 if (values.table === undefined) {
-  console.error('Usage: seed-aws-accounts --table <TableName> [--endpoint <url>] [--accounts user:pass ...] [--file <path>]');
+  console.error(
+    'Usage: seed-aws-accounts --table <TableName> [--endpoint <url>] [--accounts user:pass ...] [--file <path>]',
+  );
   process.exit(1);
 }
 

package/tools/seed-cf-accounts.ts

@@ -0,0 +1,107 @@
+#!/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/accounts';
+
+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.5.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/tools/tcp-ws-forwarder/src/forwarder.ts

@@ -11,16 +11,25 @@
  *   IRC client  ──TCP──▶  forwarder  ──WS──▶  ServerlessIRCd endpoint
  *   IRC client  ◀─TCP──  forwarder  ◀─WS──  ServerlessIRCd endpoint
  *
+ * IRCv3 WebSocket subprotocol: every dial offers
+ * `['binary.ircv3.net', 'text.ircv3.net']` so a spec-capable upstream
+ * (e.g. the CF `ConnectionDO`) agrees on one-message-per-frame framing. A
+ * server that supports neither simply leaves the subprotocol unset and the
+ * bridge keeps working with its tolerant line-split framing.
+ *
  * Framing:
  *   • TCP→WS: the TCP byte stream is reassembled into IRC lines with the
  *     byte-accurate {@link LineScanner} (tolerant of CRLF and bare LF per
  *     PLAN §9). Each complete line is sent as one bare WebSocket text frame
  *     — the canonical "one message per frame" convention the server's
- *     `ConnectionActor` expects.
+ *     `ConnectionActor` expects — with any trailing CR-LF stripped by
+ *     {@link toWsMessagePayload} per the IRCv3 spec ("no trailing CR-LF on
+ *     the wire").
  *   • WS→TCP: each inbound WS frame is split on line terminators and every
  *     non-empty line is written back to the TCP socket with a trailing
- *     CRLF, normalizing whatever framing the server used (single message,
- *     `\r\n`-joined, or bare) into canonical IRC wire format.
+ *     CRLF via {@link toTcpWire}, normalizing whatever framing the server
+ *     used (single message, `\r\n`-joined, or bare) into canonical IRC wire
+ *     format.
  *
  * Lifetime: closing either side tears down the whole bridge. The forwarder
  * itself is transport-agnostic and has no `@serverless-ircd/*` dependency.
@@ -31,6 +40,16 @@ import { type RawData, WebSocket } from 'ws';
 import { LineScanner } from './line-scanner.js';
 import { ConsoleLogger, LogLevel, type Logger } from './logger.js';
 
+/**
+ * IRCv3 WebSocket subprotocols the forwarder offers when dialing the upstream
+ * IRCd, in preference order. `binary.ircv3.net` is offered first so a
+ * spec-capable server agrees on binary framing; `text.ircv3.net` is the
+ * fallback. A server that supports neither (e.g. a legacy deployment) leaves
+ * the subprotocol unset and the bridge keeps working with its tolerant
+ * line-split framing.
+ */
+export const FORWARDER_WS_SUBPROTOCOLS = ['binary.ircv3.net', 'text.ircv3.net'] as const;
+
 /** Options accepted by {@link startForwarder}. */
 export interface StartForwarderOptions {
   /** TCP port to listen on. Use 0 for an ephemeral port. */
@@ -157,7 +176,7 @@ function bridgeConnection(
   logger: Logger,
   connId: number,
 ): () => void {
-  const ws = new WebSocket(targetHref);
+  const ws = new WebSocket(targetHref, [...FORWARDER_WS_SUBPROTOCOLS]);
   const outgoing = new LineScanner();
   const pending: string[] = [];
   let wsReady = false;
@@ -167,8 +186,8 @@ function bridgeConnection(
   logger.info('bridge.accepted', { conn: connId, remote });
 
   const sendLine = (line: string): void => {
-    if (wsReady) ws.send(line);
-    else pending.push(line);
+    if (wsReady) ws.send(toWsMessagePayload(line));
+    else pending.push(toWsMessagePayload(line));
   };
 
   tcp.on('data', (chunk: Buffer) => {
@@ -191,9 +210,7 @@ function bridgeConnection(
   ws.on('message', (data: RawData) => {
     const text = toBuffer(data).toString('utf8');
     logger.debug('ws.frame', { conn: connId, frame: text });
-    for (const line of splitFrameLines(text)) {
-      if (line.length > 0) tcp.write(`${line}\r\n`);
-    }
+    for (const chunk of toTcpWire(text)) tcp.write(chunk);
   });
 
   const teardown = (reason: CloseReason): void => {
@@ -241,6 +258,37 @@ export function splitFrameLines(text: string): string[] {
   return text.split(/\r?\n/u);
 }
 
+/**
+ * Translates a TCP IRC line into the WebSocket message payload for the
+ * upstream send direction. Strips a single trailing CR-LF (or bare LF) so
+ * the WS message carries the bare IRC line, per the IRCv3 WebSocket spec
+ * ("no trailing CR-LF on the wire"). Idempotent on already-bare lines
+ * (the {@link LineScanner} output), so callers can apply it unconditionally
+ * without inspecting the line first. Exported so the CRLF-strip contract is
+ * unit-testable in isolation.
+ */
+export function toWsMessagePayload(line: string): string {
+  if (line.endsWith('\r\n')) return line.slice(0, -2);
+  if (line.endsWith('\n')) return line.slice(0, -1);
+  return line;
+}
+
+/**
+ * Translates an inbound WebSocket message payload into the CRLF-terminated
+ * TCP chunk(s) to write back to the IRC client. Each non-empty IRC line is
+ * returned as its own entry ending in CRLF, ready for `socket.write`. A
+ * single trailing CR-LF on the message (defensive against servers that emit
+ * one) is collapsed rather than doubled. Exported so the CRLF-re-append
+ * contract is unit-testable in isolation.
+ */
+export function toTcpWire(text: string): string[] {
+  const out: string[] = [];
+  for (const line of splitFrameLines(text)) {
+    if (line.length > 0) out.push(`${line}\r\n`);
+  }
+  return out;
+}
+
 /**
  * Normalizes a `ws` `RawData` payload into a single UTF-8 `Buffer`. Exported
  * so the `ArrayBuffer` / `Uint8Array` / `Buffer[]` variants — which ws only

package/tools/tcp-ws-forwarder/tests/forwarder.test.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import http from 'node:http';
+import http, { type IncomingHttpHeaders } from 'node:http';
 import { type Socket, createConnection, createServer as createNetServer } from 'node:net';
 import type { AddressInfo } from 'node:net';
 import { afterEach, describe, expect, it, vi } from 'vitest';
@@ -51,6 +51,12 @@ interface Target {
   readonly frames: string[];
   readonly connections: WebSocket[];
   waitForConnection(): Promise<WebSocket>;
+  /**
+   * Resolves the next inbound upgrade request, in arrival order. Used to
+   * assert headers the forwarder sends during the WS handshake (e.g. the
+   * offered `Sec-WebSocket-Protocol`).
+   */
+  waitForUpgradeRequest(): Promise<{ headers: IncomingHttpHeaders }>;
   close(): Promise<void>;
 }
 
@@ -69,8 +75,14 @@ function startDelayedTarget(delayMs: number): Promise<Target> {
   // arrival order; queue waiters that resolve one-for-one as connections land.
   const waiters: Array<(ws: WebSocket) => void> = [];
   let waitForCount = 0;
+  // Likewise for upgrade requests, captured before the WS is handed off so
+  // headers can be asserted even when the caller never awaits a connection.
+  const upgradeReqWaiters: Array<(req: { headers: IncomingHttpHeaders }) => void> = [];
 
   server.on('upgrade', (req, socket, head) => {
+    const captured = { headers: req.headers };
+    const waiter = upgradeReqWaiters.shift();
+    if (waiter) waiter(captured);
     const finish = () => {
       wss.handleUpgrade(req, socket, head, (ws) => {
         connections.push(ws);
@@ -97,6 +109,10 @@ function startDelayedTarget(delayMs: number): Promise<Target> {
             if (connections.length > want) res(connections[want] as WebSocket);
             else waiters.push(res);
           }),
+        waitForUpgradeRequest: () =>
+          new Promise((res) => {
+            upgradeReqWaiters.push(res);
+          }),
         close: () =>
           new Promise<void>((r) => {
             for (const ws of connections) ws.close();
@@ -260,6 +276,23 @@ describe('startForwarder — lifecycle', () => {
     openServers.push(fwd);
     expect(fwd.targetUrl).toBe('wss://example.invalid/');
   });
+
+  it('offers binary.ircv3.net and text.ircv3.net in the upstream WS handshake', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+
+    const req = await target.waitForUpgradeRequest();
+    const offered = req.headers['sec-websocket-protocol'];
+    expect(typeof offered).toBe('string');
+    const list = (offered as string).split(',').map((s) => s.trim());
+    expect(list).toEqual(['binary.ircv3.net', 'text.ircv3.net']);
+  });
 });
 
 describe('forwarder — TCP→WS framing', () => {

package/tools/tcp-ws-forwarder/tests/framing.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, it } from 'vitest';
 import type { RawData } from 'ws';
-import { splitFrameLines, toBuffer } from '../src/forwarder';
+import {
+  FORWARDER_WS_SUBPROTOCOLS,
+  splitFrameLines,
+  toBuffer,
+  toTcpWire,
+  toWsMessagePayload,
+} from '../src/forwarder';
 
 /**
  * Pure-function unit tests for the WS-side framing helpers. These edges
@@ -49,3 +55,61 @@ describe('toBuffer', () => {
     expect(toBuffer(src as RawData).toString('utf8')).toBe('ABC');
   });
 });
+
+describe('FORWARDER_WS_SUBPROTOCOLS', () => {
+  it('offers binary.ircv3.net first (preferred)', () => {
+    expect(FORWARDER_WS_SUBPROTOCOLS[0]).toBe('binary.ircv3.net');
+  });
+
+  it('offers text.ircv3.net as the fallback', () => {
+    expect(FORWARDER_WS_SUBPROTOCOLS).toContain('text.ircv3.net');
+  });
+
+  it('offers exactly the two IRCv3 subprotocols', () => {
+    expect([...FORWARDER_WS_SUBPROTOCOLS].sort()).toEqual(['binary.ircv3.net', 'text.ircv3.net']);
+  });
+});
+
+describe('toWsMessagePayload — TCP line → WS message (CRLF stripped)', () => {
+  it('strips a trailing CRLF from a TCP IRC line', () => {
+    expect(toWsMessagePayload('PING :tok\r\n')).toBe('PING :tok');
+  });
+
+  it('strips a trailing bare LF', () => {
+    expect(toWsMessagePayload('PING :bare\n')).toBe('PING :bare');
+  });
+
+  it('leaves an already-bare line unchanged (idempotent on LineScanner output)', () => {
+    expect(toWsMessagePayload('NICK alice')).toBe('NICK alice');
+  });
+
+  it('strips only one trailing terminator, keeping embedded content', () => {
+    expect(toWsMessagePayload('PRIVMSG #foo :a\r\nb\r\n')).toBe('PRIVMSG #foo :a\r\nb');
+  });
+
+  it('returns the empty string unchanged', () => {
+    expect(toWsMessagePayload('')).toBe('');
+  });
+});
+
+describe('toTcpWire — WS message → TCP bytes (CRLF re-appended)', () => {
+  it('appends CRLF to a bare spec-mode WS message', () => {
+    expect(toTcpWire(':srv 001 nick :Welcome')).toEqual([':srv 001 nick :Welcome\r\n']);
+  });
+
+  it('collapses a single trailing CRLF instead of doubling it', () => {
+    expect(toTcpWire(':srv 001 nick :Hi\r\n')).toEqual([':srv 001 nick :Hi\r\n']);
+  });
+
+  it('emits no bytes for an empty WS message', () => {
+    expect(toTcpWire('')).toEqual([]);
+  });
+
+  it('emits no bytes for a message that is only a terminator', () => {
+    expect(toTcpWire('\r\n')).toEqual([]);
+  });
+
+  it('re-appends CRLF to each line of a legacy joined multi-message frame', () => {
+    expect(toTcpWire(':srv 001\r\n:srv 376')).toEqual([':srv 001\r\n', ':srv 376\r\n']);
+  });
+});