serverless-ircd 0.10.0 → 0.11.0

package/apps/cf-tcp-container/tests/container-server.test.ts

@@ -9,12 +9,18 @@ import { type ContainerServer, startContainerServer } from '../src/container-ser
 /**
  * Minimal IRC-over-TCP test client. Writes lines with CRLF, parses inbound
  * bytes into IRC lines (tolerant of CRLF and bare LF).
+ *
+ * By default it emulates the Cloudflare Spectrum edge: the connection
+ * opens with a PROXY protocol v1 header carrying `proxySourceIp` (the
+ * "real client IP" as the edge would report it). Pass
+ * `{ proxySourceIp: null }` for direct-connection scenarios where the
+ * client speaks raw IRC with no header.
  */
 class TcpClient extends EventEmitter {
   readonly socket: Socket;
   readonly received: string[] = [];
 
-  constructor(host: string, port: number) {
+  constructor(host: string, port: number, opts: { proxySourceIp?: string | null } = {}) {
     super();
     this.socket = createConnection({ host, port });
     this.socket.setEncoding('utf8');
@@ -26,6 +32,15 @@ class TcpClient extends EventEmitter {
         }
       }
     });
+    const src = opts.proxySourceIp === undefined ? '127.0.0.1' : opts.proxySourceIp;
+    if (src !== null) {
+      const family = src.includes(':') ? 'TCP6' : 'TCP4';
+      const dst = family === 'TCP6' ? '2001:db8::2' : '192.0.2.1';
+      // Writing on a connecting socket is safe: Node queues the bytes
+      // until the TCP connection is established, so the header always
+      // lands before any subsequent send().
+      this.socket.write(`PROXY ${family} ${src} ${dst} 40000 6697\r\n`);
+    }
   }
 
   opened(): Promise<void> {
@@ -93,7 +108,8 @@ describe('container-server — lifecycle', () => {
       serverName: 'irc.test',
       networkName: 'TestNet',
     });
-    expect(srv.port).toBeGreaterThan(0);
+    expect(srv.port).toBeDefined();
+    expect(srv.port as number).toBeGreaterThan(0);
     expect(srv.host).toBe('127.0.0.1');
     await srv.close();
   });
@@ -141,7 +157,7 @@ describe('container-server — option wiring (coverage matrix)', () => {
     });
     expect(srv.host).toBe('0.0.0.0');
     // Connecting via 127.0.0.1 still reaches the 0.0.0.0 listener.
-    const c = new TcpClient('127.0.0.1', srv.port);
+    const c = new TcpClient('127.0.0.1', srv.port as number);
     await c.opened();
     await c.close();
     await srv.close();
@@ -157,7 +173,7 @@ describe('container-server — option wiring (coverage matrix)', () => {
       networkName: 'AdmissionNet',
       maxConnectionsPerUser: 5,
     });
-    const c = new TcpClient('127.0.0.1', srv.port);
+    const c = new TcpClient('127.0.0.1', srv.port as number);
     await c.opened();
     await c.close();
     await srv.close();
@@ -173,7 +189,7 @@ describe('container-server — option wiring (coverage matrix)', () => {
       cloaking: { enabled: true, secret: 'cloak-secret', cloakedSuffix: '.hidden' },
       saslAccounts: [{ username: 'alice', password: 'pw' }],
     });
-    const c = new TcpClient('127.0.0.1', srv.port);
+    const c = new TcpClient('127.0.0.1', srv.port as number);
     await c.opened();
     await c.close();
     await srv.close();
@@ -197,8 +213,8 @@ describe('container-server — IRC flows over TCP', () => {
   });
 
   it('completes register → join → privmsg → quit', async () => {
-    const alice = new TcpClient('127.0.0.1', server.port);
-    const bob = new TcpClient('127.0.0.1', server.port);
+    const alice = new TcpClient('127.0.0.1', server.port as number);
+    const bob = new TcpClient('127.0.0.1', server.port as number);
     await alice.opened();
     await bob.opened();
 
@@ -223,7 +239,7 @@ describe('container-server — IRC flows over TCP', () => {
   });
 
   it('routes PING → PONG', async () => {
-    const client = new TcpClient('127.0.0.1', server.port);
+    const client = new TcpClient('127.0.0.1', server.port as number);
     await client.opened();
     await client.send('NICK pinger');
     await client.send('USER pinger 0 * :Pinger');
@@ -235,7 +251,7 @@ describe('container-server — IRC flows over TCP', () => {
   });
 
   it('reassembles a single IRC message split across two TCP chunks', async () => {
-    const client = new TcpClient('127.0.0.1', server.port);
+    const client = new TcpClient('127.0.0.1', server.port as number);
     await client.opened();
     await client.send('NICK splitter');
     await client.send('USER splitter 0 * :Splitter');
@@ -248,7 +264,7 @@ describe('container-server — IRC flows over TCP', () => {
   });
 
   it('processes multiple IRC lines delivered in a single TCP chunk', async () => {
-    const client = new TcpClient('127.0.0.1', server.port);
+    const client = new TcpClient('127.0.0.1', server.port as number);
     await client.opened();
     await client.writeRaw('NICK bundler\r\nUSER bundler 0 * :Bundler\r\n');
     await client.waitFor((l) => l.startsWith(':irc.example.com 001 bundler'));
@@ -256,7 +272,7 @@ describe('container-server — IRC flows over TCP', () => {
   });
 
   it('cleans up the runtime connection on abrupt socket termination', async () => {
-    const client = new TcpClient('127.0.0.1', server.port);
+    const client = new TcpClient('127.0.0.1', server.port as number);
     await client.opened();
     await client.send('NICK termUser');
     await client.send('USER termUser 0 * :Term');
@@ -272,7 +288,7 @@ describe('container-server — IRC flows over TCP', () => {
   });
 
   it('delivers an ERROR notice when a reducer supplies a disconnect reason', async () => {
-    const client = new TcpClient('127.0.0.1', server.port);
+    const client = new TcpClient('127.0.0.1', server.port as number);
     await client.opened();
     await client.send('NICK floodUser');
     await client.send('USER floodUser 0 * :Flood');
@@ -285,6 +301,35 @@ describe('container-server — IRC flows over TCP', () => {
     await expect(wait).resolves.toContain('Excess Flood');
     await client.close();
   });
+
+  it('closes the connection with ERROR when the input buffer cap is exceeded', async () => {
+    // A peer streaming > 8 KiB with no line terminator would grow the
+    // transport buffer unboundedly; the origin must answer with the
+    // RFC-style ERROR notice, destroy the socket, and unregister the
+    // connection from the runtime.
+    const client = new TcpClient('127.0.0.1', server.port as number);
+    await client.opened();
+    await client.send('NICK overflower');
+    await client.send('USER overflower 0 * :Over');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    const connId = await server.runtime.lookupNick('overflower');
+    expect(connId).not.toBeNull();
+    expect(server.runtime.hasConnection(connId as string)).toBe(true);
+
+    const closed = new Promise<void>((resolve) => client.socket.once('close', () => resolve()));
+    await client.writeRaw('x'.repeat(9 * 1024)); // no terminator anywhere
+    const errorLine = await client.waitFor(
+      (l) => l === 'ERROR :Closing link: input buffer overflow',
+      2_000,
+    );
+    expect(errorLine).toBe('ERROR :Closing link: input buffer overflow');
+    await closed;
+    expect(client.socket.destroyed).toBe(true);
+    // Cleanup ran: the runtime no longer tracks the connection.
+    await new Promise((r) => setTimeout(r, 100));
+    expect(server.runtime.hasConnection(connId as string)).toBe(false);
+  });
 });
 
 describe('container-server — persistence across restart', () => {
@@ -309,7 +354,7 @@ describe('container-server — persistence across restart', () => {
       networkName: 'PersistNet',
       persistencePath: statePath,
     });
-    const c1 = new TcpClient('127.0.0.1', srv1.port);
+    const c1 = new TcpClient('127.0.0.1', srv1.port as number);
     await c1.opened();
     await c1.send('NICK op');
     await c1.send('USER op 0 * :Op');
@@ -331,7 +376,7 @@ describe('container-server — persistence across restart', () => {
       networkName: 'PersistNet',
       persistencePath: statePath,
     });
-    const c2 = new TcpClient('127.0.0.1', srv2.port);
+    const c2 = new TcpClient('127.0.0.1', srv2.port as number);
     await c2.opened();
     await c2.send('NICK late');
     await c2.send('USER late 0 * :Late');
@@ -359,10 +404,15 @@ describe('container-server — admission gate', () => {
       networkName: 'GateNet',
       maxConnectionsPerIp: 1,
     });
-    const c1 = new TcpClient('127.0.0.1', srv.port);
+    const c1 = new TcpClient('127.0.0.1', srv.port as number);
     await c1.opened();
-    // Second connection from the same IP should be rejected.
-    const c2 = new TcpClient('127.0.0.1', srv.port);
+    // Admission is committed once the PROXY header has been parsed, so
+    // let c1 fully register before a second flow from the same IP.
+    await c1.send('NICK gateOne');
+    await c1.send('USER gateOne 0 * :Gate');
+    await c1.waitFor((l) => l.startsWith(':irc.gate 001 '), 2000);
+    // Second connection from the same source IP should be rejected.
+    const c2 = new TcpClient('127.0.0.1', srv.port as number);
     const error = await new Promise<string | null>((resolve) => {
       c2.socket.setEncoding('utf8');
       c2.socket.once('data', (d: string) => resolve(d));
@@ -389,7 +439,7 @@ describe('container-server — snapshot error resilience', () => {
       persistencePath: path,
     });
     // Server should still work — starts fresh.
-    const c = new TcpClient('127.0.0.1', srv.port);
+    const c = new TcpClient('127.0.0.1', srv.port as number);
     await c.opened();
     await c.send('NICK test');
     await c.send('USER test 0 * :Test');
@@ -410,7 +460,7 @@ describe('container-server — snapshot error resilience', () => {
       persistencePath: path,
       snapshotIntervalMs: 999_999,
     });
-    const c = new TcpClient('127.0.0.1', srv.port);
+    const c = new TcpClient('127.0.0.1', srv.port as number);
     await c.opened();
     // Wait for the server-side socket to be registered in the sockets set.
     for (let i = 0; i < 50 && srv.testSockets.size === 0; i++) {
@@ -435,7 +485,7 @@ describe('container-server — snapshot error resilience', () => {
       serverName: 'irc.skip',
       networkName: 'SkipNet',
     });
-    const c = new TcpClient('127.0.0.1', srv.port);
+    const c = new TcpClient('127.0.0.1', srv.port as number);
     await c.opened();
     for (let i = 0; i < 50 && srv.testSockets.size === 0; i++) {
       await new Promise((r) => setTimeout(r, 5));
@@ -466,7 +516,7 @@ describe('container-server — snapshot error resilience', () => {
       persistencePath: dirPath,
       snapshotIntervalMs: 999_999,
     });
-    const c = new TcpClient('127.0.0.1', srv.port);
+    const c = new TcpClient('127.0.0.1', srv.port as number);
     await c.opened();
     await c.send('NICK finalFail');
     await c.send('USER finalFail 0 * :FinalFail');
@@ -493,8 +543,11 @@ describe('container-server — error paths', () => {
     srv.runtime.send = async () => {
       throw new Error('synthetic send failure');
     };
-    const client = new TcpClient('127.0.0.1', srv.port);
+    const client = new TcpClient('127.0.0.1', srv.port as number);
     await client.opened();
+    // Settle so the PROXY header is consumed as its own chunk; every
+    // subsequent IRC line then flows through the post-attach data path.
+    await new Promise((r) => setTimeout(r, 50));
     await client.send('NICK errUser');
     await client.send('USER errUser 0 * :Err');
     // PING triggers a Send → synthetic throw → actor catch → logError.
@@ -503,8 +556,9 @@ describe('container-server — error paths', () => {
 
     srv.runtime.send = original;
     // Server should still serve new connections.
-    const next = new TcpClient('127.0.0.1', srv.port);
+    const next = new TcpClient('127.0.0.1', srv.port as number);
     await next.opened();
+    await new Promise((r) => setTimeout(r, 50));
     await next.send('NICK recover');
     await next.send('USER recover 0 * :Recover');
     await next.waitFor((l) => l.startsWith(':irc.err 001 '), 3000);
@@ -527,16 +581,18 @@ describe('container-server — error paths', () => {
       // eslint-disable-next-line no-throw-literal
       throw { code: 'SYNTHETIC', detail: 'not an Error' };
     };
-    const client = new TcpClient('127.0.0.1', srv.port);
+    const client = new TcpClient('127.0.0.1', srv.port as number);
     await client.opened();
+    await new Promise((r) => setTimeout(r, 50));
     await client.send('NICK nonErrUser');
     await client.send('USER nonErrUser 0 * :NonErr');
     await client.send('PING :will-throw-non-error');
     await new Promise((r) => setTimeout(r, 100));
 
     srv.runtime.send = original;
-    const next = new TcpClient('127.0.0.1', srv.port);
+    const next = new TcpClient('127.0.0.1', srv.port as number);
     await next.opened();
+    await new Promise((r) => setTimeout(r, 50));
     await next.send('NICK recover2');
     await next.send('USER recover2 0 * :Recover2');
     await next.waitFor((l) => l.startsWith(':irc.nonerr 001 '), 3000);
@@ -554,7 +610,7 @@ describe('container-server — error paths', () => {
       serverName: 'irc.noreason',
       networkName: 'NoReasonNet',
     });
-    const client = new TcpClient('127.0.0.1', srv.port);
+    const client = new TcpClient('127.0.0.1', srv.port as number);
     await client.opened();
     await client.send('NICK noReason');
     await client.send('USER noReason 0 * :NoReason');
@@ -580,7 +636,7 @@ describe('container-server — error paths', () => {
       serverName: 'irc.unwritable',
       networkName: 'UnwritableNet',
     });
-    const client = new TcpClient('127.0.0.1', srv.port);
+    const client = new TcpClient('127.0.0.1', srv.port as number);
     await client.opened();
     await client.send('NICK unwritable');
     await client.send('USER unwritable 0 * :Unwritable');
@@ -609,7 +665,7 @@ describe('container-server — error paths', () => {
       serverName: 'irc.sockerr',
       networkName: 'SockErrNet',
     });
-    const client = new TcpClient('127.0.0.1', srv.port);
+    const client = new TcpClient('127.0.0.1', srv.port as number);
     await client.opened();
     for (let i = 0; i < 50 && srv.testSockets.size === 0; i++) {
       await new Promise((r) => setTimeout(r, 5));
@@ -619,7 +675,7 @@ describe('container-server — error paths', () => {
     serverSideSocket.emit('error', new Error('synthetic socket failure'));
     await new Promise((r) => setImmediate(r));
     // Server should still serve new connections.
-    const next = new TcpClient('127.0.0.1', srv.port);
+    const next = new TcpClient('127.0.0.1', srv.port as number);
     await next.opened();
     await next.close();
     await client.close();
@@ -638,7 +694,7 @@ describe('container-server — error paths', () => {
       snapshotIntervalMs: 100,
     });
     // Create a channel so the snapshot has content.
-    const c = new TcpClient('127.0.0.1', srv.port);
+    const c = new TcpClient('127.0.0.1', srv.port as number);
     await c.opened();
     await c.send('NICK autoUser');
     await c.send('USER autoUser 0 * :Auto');
@@ -666,7 +722,7 @@ describe('container-server — draft/multiline BATCH to a nick target', () => {
 
   /** Negotiates `batch` + `draft/multiline`, then registers the nick. */
   async function registerMultilineCapable(srv: ContainerServer, nick: string): Promise<TcpClient> {
-    const c = new TcpClient('127.0.0.1', srv.port);
+    const c = new TcpClient('127.0.0.1', srv.port as number);
     await c.opened();
     await c.send('CAP LS 302');
     await c.waitFor((l) => l.startsWith(':irc.ml CAP * LS :'), 2000);
@@ -711,3 +767,274 @@ describe('container-server — draft/multiline BATCH to a nick target', () => {
     await srv.close();
   });
 });
+
+describe('container-server — PROXY protocol v1', () => {
+  // Spectrum is configured with `proxy_protocol = "v1"`: every forwarded
+  // flow starts with `PROXY TCP4|TCP6 <src> <dst> <sport> <dport>\r\n`.
+  // The origin must peel that header off before the bytes reach the IRC
+  // actor and must key per-IP admission on the recovered source IP.
+
+  it('admits a headered connection with no 421 on the first frame', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.proxy',
+      networkName: 'ProxyNet',
+    });
+    const c = new TcpClient('127.0.0.1', srv.port as number, { proxySourceIp: '203.0.113.5' });
+    await c.opened();
+    await c.send('NICK viaProxy');
+    await c.send('USER viaProxy 0 * :Via');
+    await c.waitFor((l) => l.startsWith(':irc.proxy 001 '), 2000);
+    // The PROXY line must never surface as an unknown IRC command.
+    expect(c.received.some((l) => l.includes(' 421 '))).toBe(false);
+    await c.close();
+    await srv.close();
+  });
+
+  it('surfaces the PROXY source IP as the connection host', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.hostip',
+      networkName: 'HostIpNet',
+    });
+    const c = new TcpClient('127.0.0.1', srv.port as number, { proxySourceIp: '203.0.113.77' });
+    await c.opened();
+    await c.send('NICK hostcheck');
+    await c.send('USER hostcheck 0 * :Host');
+    await c.waitFor((l) => l.startsWith(':irc.hostip 001 '), 2000);
+    const connId = await srv.runtime.lookupNick('hostcheck');
+    expect(connId).not.toBeNull();
+    const state = await srv.runtime.getConnection(connId as string);
+    // Not the socket peer address (127.0.0.1) — the PROXY-header IP.
+    expect(state?.host).toBe('203.0.113.77');
+    await c.close();
+    await srv.close();
+  });
+
+  it('parses TCP6-family headers', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.v6',
+      networkName: 'V6Net',
+    });
+    const c = new TcpClient('127.0.0.1', srv.port as number, { proxySourceIp: '2001:db8::1' });
+    await c.opened();
+    await c.send('NICK v6user');
+    await c.send('USER v6user 0 * :V6');
+    await c.waitFor((l) => l.startsWith(':irc.v6 001 '), 2000);
+    const connId = await srv.runtime.lookupNick('v6user');
+    expect(connId).not.toBeNull();
+    const state = await srv.runtime.getConnection(connId as string);
+    expect(state?.host).toBe('2001:db8::1');
+    await c.close();
+    await srv.close();
+  });
+
+  it('reassembles a header split across two TCP chunks', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.split',
+      networkName: 'SplitNet',
+    });
+    const c = new TcpClient('127.0.0.1', srv.port as number, { proxySourceIp: null });
+    await c.opened();
+    await c.writeRaw('PROXY TCP4 192.0.2.5');
+    // Let the partial header be delivered as its own chunk (the server
+    // must buffer it), then complete the header in a second chunk that
+    // also carries IRC bytes behind it.
+    await new Promise((r) => setTimeout(r, 50));
+    await c.writeRaw(' 198.51.100.7 40001 6697\r\nNICK hdrsplit\r\n');
+    await c.send('USER hdrsplit 0 * :Split');
+    await c.waitFor((l) => l.startsWith(':irc.split 001 '), 2000);
+    expect(c.received.some((l) => l.includes(' 421 '))).toBe(false);
+    const connId = await srv.runtime.lookupNick('hdrsplit');
+    expect(connId).not.toBeNull();
+    const state = await srv.runtime.getConnection(connId as string);
+    expect(state?.host).toBe('192.0.2.5');
+    await c.close();
+    await srv.close();
+  });
+
+  it('rejects a direct connection that speaks IRC without a PROXY header', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.direct',
+      networkName: 'DirectNet',
+    });
+    const c = new TcpClient('127.0.0.1', srv.port as number, { proxySourceIp: null });
+    await c.opened();
+    const closed = new Promise<void>((resolve) => c.socket.once('close', () => resolve()));
+    await c.send('NICK direct');
+    const errorLine = await c.waitFor((l) => l.startsWith('ERROR :Closing link:'), 2000);
+    expect(errorLine).toContain('PROXY');
+    await closed;
+    expect(c.socket.destroyed).toBe(true);
+    // No IRC identity was ever created for the rejected flow.
+    expect(await srv.runtime.lookupNick('direct')).toBeNull();
+    await srv.close();
+  });
+
+  it('rejects a malformed PROXY header', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.badhdr',
+      networkName: 'BadHdrNet',
+    });
+    const c = new TcpClient('127.0.0.1', srv.port as number, { proxySourceIp: null });
+    await c.opened();
+    const closed = new Promise<void>((resolve) => c.socket.once('close', () => resolve()));
+    await c.writeRaw('PROXY UNKNOWN\r\n');
+    const errorLine = await c.waitFor((l) => l.startsWith('ERROR :Closing link:'), 2000);
+    expect(errorLine).toContain('PROXY');
+    await closed;
+    expect(c.socket.destroyed).toBe(true);
+    await srv.close();
+  });
+
+  it('logs an actor failure for IRC bytes coalesced with the header', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.hdrerr',
+      networkName: 'HdrErrNet',
+    });
+    const original = srv.runtime.send.bind(srv.runtime);
+    srv.runtime.send = async () => {
+      throw new Error('synthetic send failure');
+    };
+    const c = new TcpClient('127.0.0.1', srv.port as number, { proxySourceIp: null });
+    await c.opened();
+    // One write: the header and the full registration share a single TCP
+    // chunk, so the welcome send fails inside the remainder receive.
+    await c.writeRaw(
+      'PROXY TCP4 203.0.113.99 192.0.2.1 40000 6697\r\nNICK hdrErr\r\nUSER hdrErr 0 * :E\r\n',
+    );
+    await new Promise((r) => setTimeout(r, 100));
+    srv.runtime.send = original;
+
+    // The server must survive the failure and serve a fresh connection.
+    const next = new TcpClient('127.0.0.1', srv.port as number);
+    await next.opened();
+    await new Promise((r) => setTimeout(r, 50));
+    await next.send('NICK hdrRecover');
+    await next.send('USER hdrRecover 0 * :R');
+    await next.waitFor((l) => l.startsWith(':irc.hdrerr 001 '), 2000);
+    await c.close();
+    await next.close();
+    await srv.close();
+  });
+
+  it('tracks admission counters per real source IP, not the edge address', async () => {
+    // With the pre-PROXY bug, every flow was admitted under the single
+    // Spectrum edge IP, so `maxConnectionsPerIp: 1` capped the aggregate.
+    // With per-real-IP counters, clients from distinct PROXY IPs are
+    // independent and only same-IP flows share a counter.
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.perip',
+      networkName: 'PerIpNet',
+      maxConnectionsPerIp: 1,
+    });
+    const a1 = new TcpClient('127.0.0.1', srv.port as number, { proxySourceIp: '203.0.113.10' });
+    await a1.opened();
+    await a1.send('NICK ipA');
+    await a1.send('USER ipA 0 * :A');
+    await a1.waitFor((l) => l.startsWith(':irc.perip 001 '), 2000);
+
+    // A client from a distinct PROXY IP: independently admitted.
+    const b = new TcpClient('127.0.0.1', srv.port as number, { proxySourceIp: '198.51.100.20' });
+    await b.opened();
+    await b.send('NICK ipB');
+    await b.send('USER ipB 0 * :B');
+    await b.waitFor((l) => l.startsWith(':irc.perip 001 '), 2000);
+
+    // A second flow from ipA's address: rejected by the per-IP cap.
+    const a2 = new TcpClient('127.0.0.1', srv.port as number, { proxySourceIp: '203.0.113.10' });
+    const error = await new Promise<string | null>((resolve) => {
+      a2.socket.once('data', (d: string) => resolve(d));
+      a2.socket.once('close', () => resolve(null));
+      setTimeout(() => resolve(null), 2000);
+    });
+    expect(error).toContain('Closing link');
+
+    await a1.close();
+    await b.close();
+    a2.destroy();
+    await srv.close();
+  });
+});
+
+describe('container-server — SASL EXTERNAL non-support', () => {
+  // The TCP container origin has no mTLS identity source (Spectrum
+  // speaks PROXY v1, which carries no client-cert subject), so SASL
+  // EXTERNAL is explicitly unsupported on this transport: the mechanism
+  // is rejected up front with a stable, transport-specific 904. The
+  // literal is asserted verbatim so the message cannot drift silently.
+  const EXTERNAL_904 =
+    ':irc.example.com 904 extuser :SASL EXTERNAL not supported on this transport';
+
+  let server: ContainerServer;
+
+  beforeAll(async () => {
+    server = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.example.com',
+      networkName: 'ExampleNet',
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('advertises sasl=PLAIN only (EXTERNAL excluded on this transport)', async () => {
+    const client = new TcpClient('127.0.0.1', server.port as number);
+    await client.opened();
+    await client.send('CAP LS 302');
+    // Wait for the final LS line (a `LS *` continuation is not last).
+    await client.waitFor((l) => /^:irc\.example\.com CAP \S+ LS :/u.test(l));
+    const lsBody = client.received.filter((l) => l.includes(' LS ')).join(' ');
+    expect(lsBody).toContain('sasl=PLAIN');
+    expect(lsBody).not.toContain('EXTERNAL');
+    await client.close();
+  });
+
+  it('rejects AUTHENTICATE EXTERNAL with the transport-specific 904', async () => {
+    const client = new TcpClient('127.0.0.1', server.port as number);
+    await client.opened();
+    await client.send('CAP LS 302');
+    await client.waitFor((l) => /^:irc\.example\.com CAP \S+ LS :/u.test(l));
+    await client.send('NICK extuser');
+    await client.send('AUTHENTICATE EXTERNAL');
+    await client.waitFor((l) => l === EXTERNAL_904);
+    await client.close();
+  });
+
+  it('does not trip the SASL failure lockout on repeated EXTERNAL attempts', async () => {
+    // The transport-level rejection is not a credential attempt: with
+    // the default lockout (3 failures) a counting implementation would
+    // disconnect by the third attempt. Four attempts must all be
+    // answered and the connection must stay alive.
+    const client = new TcpClient('127.0.0.1', server.port as number);
+    await client.opened();
+    await client.send('CAP LS 302');
+    await client.waitFor((l) => /^:irc\.example\.com CAP \S+ LS :/u.test(l));
+    await client.send('NICK extuser');
+    for (let i = 0; i < 4; i++) {
+      await client.send('AUTHENTICATE EXTERNAL');
+    }
+    await client.send('PING :lockout-probe');
+    await client.waitFor((l) => l === 'PONG :lockout-probe');
+    expect(client.received.filter((l) => l === EXTERNAL_904)).toHaveLength(4);
+    expect(client.received.some((l) => l.startsWith('ERROR :Closing link'))).toBe(false);
+    await client.close();
+  });
+});