serverless-ircd 0.3.0 → 0.5.0

package/packages/irc-core/src/protocol/outbound.ts

@@ -16,6 +16,7 @@
  */
 
 import type { RawLine } from '../effects.js';
+import { MAX_WS_MESSAGE_BYTES, type WsFrameMode } from '../ws-framing.js';
 
 /**
  * RFC 1459 §2.3: maximum IRC line length in bytes, including the trailing
@@ -65,7 +66,7 @@ export function applyServerTime(line: RawLine, caps: ReadonlySet<string>, now: n
 }
 
 /**
- * Enforces the IRC 512-byte line limit on `line.text`.
+ * Enforces the IRC line-length budget on `line.text`.
  *
  * For recipients that negotiated `message-tags`, the tag section (the
  * leading `@... ` prefix) is part of the wire budget and is preserved
@@ -73,11 +74,22 @@ export function applyServerTime(line: RawLine, caps: ReadonlySet<string>, now: n
  * For legacy recipients the entire `line.text` is the body and may be
  * truncated from the right.
  *
+ * The optional `mode` selects which byte budget applies: an IRCv3
+ * WebSocket spec mode (`spec-text` / `spec-binary`) caps the message at
+ * {@link MAX_WS_MESSAGE_BYTES} (510) directly, because WebSocket messages
+ * carry no trailing CR-LF; legacy mode (the default) caps at
+ * `MAX_LINE_BYTES - 2` (512 − 2 = 510). Both resolve to 510 today, but the
+ * mode-aware call sites need no edits if either constant ever changes.
+ *
  * The returned {@link RawLine} is the original object when no truncation
  * was needed, otherwise a fresh object with the truncated text.
  */
-export function enforceLineLimit(line: RawLine, caps: ReadonlySet<string>): RawLine {
-  const budget = MAX_LINE_BYTES - TRAILING_CRLF_LEN;
+export function enforceLineLimit(
+  line: RawLine,
+  caps: ReadonlySet<string>,
+  mode?: WsFrameMode,
+): RawLine {
+  const budget = isSpecMode(mode) ? MAX_WS_MESSAGE_BYTES : MAX_LINE_BYTES - TRAILING_CRLF_LEN;
   if (line.text.length <= budget) return line;
 
   const hasTags = caps.has('message-tags') && line.text.startsWith('@');
@@ -143,3 +155,8 @@ function clientTagKey(entry: string): string {
   const eq = entry.indexOf('=');
   return eq === -1 ? entry : entry.slice(0, eq);
 }
+
+/** True when `mode` is an IRCv3 WebSocket spec framing mode (not legacy/absent). */
+function isSpecMode(mode: WsFrameMode | undefined): boolean {
+  return mode === 'spec-text' || mode === 'spec-binary';
+}

package/packages/irc-core/src/types.ts

@@ -8,7 +8,15 @@
 
 import type { Effect } from './effects.js';
 import type { FloodControlConfig } from './flood-control.js';
-import type { AccountStore, Clock, IdFactory, MessageStore, MotdProvider } from './ports.js';
+import type {
+  AccountStore,
+  Clock,
+  IdFactory,
+  MessageStore,
+  MotdProvider,
+  MtlsIdentityProvider,
+  NickHistoryStore,
+} from './ports.js';
 import type { IrcMessage } from './protocol/messages.js';
 import type { ConnectionState } from './state/connection.js';
 
@@ -40,12 +48,24 @@ export interface OperCred {
  * Per-deployment server configuration. Adapters load this from a KV store
  * (CF) or Secrets Manager / SSM (AWS); the core only reads it.
  *
- * This is the minimum the Phase 1 reducers need; later tickets (SASL,
+ * This is the minimum the Phase 1 reducers need; later phases (SASL,
  * MOTD provider, channel-prefix policy) extend it.
  */
 export interface ServerConfig {
   serverName: string;
   networkName: string;
+  /**
+   * Server version surfaced in `002`/`004`/`351`/`371`. When undefined the
+   * reducer falls back to {@link DEFAULT_SERVER_VERSION} (the irc-core
+   * package version); adapters inject the deploy-time version via config.
+   */
+  readonly serverVersion?: string | undefined;
+  /**
+   * "Created" text for `003 RPL_CREATED`. A string is used verbatim; a
+   * number is treated as epoch-ms and formatted as a UTC timestamp. When
+   * undefined the reducer falls back to {@link DEFAULT_CREATED_TEXT}.
+   */
+  readonly createdAt?: string | number | undefined;
   /**
    * Server password gate. Empty string or undefined disables enforcement.
    * When set, registration refuses to complete until the connection
@@ -81,6 +101,13 @@ export interface ServerConfig {
   nickLen: number;
   channelLen: number;
   topicLen: number;
+  /**
+   * Maximum realname (GECOS) length enforced by `SETNAME`. Optional because
+   * registration-time `USER` does not enforce a cap; the parsed config always
+   * supplies a value (schema default), but inline `ServerConfig` literals in
+   * tests may omit it — `SETNAME` then falls back to its built-in default.
+   */
+  readonly realnameLen?: number | undefined;
   quitMessage: string;
   /**
    * Per-connection message-rate flood control. `undefined` → the actor
@@ -115,6 +142,12 @@ export interface Ctx {
   readonly motd: MotdProvider;
   /** SASL account verification source (absent when no accounts are configured). */
   readonly accounts?: AccountStore;
+  /**
+   * mTLS client-cert identity source for SASL EXTERNAL (absent when mTLS
+   * is not configured). When present, `AUTHENTICATE EXTERNAL` resolves the
+   * connection's verified certificate subject through this port.
+   */
+  readonly mtlsIdentity?: MtlsIdentityProvider;
   /**
    * Chat-history persistence source (absent when chathistory playback is
    * disabled for this deployment). When present, the PRIVMSG/NOTICE channel
@@ -122,6 +155,13 @@ export interface Ctx {
    * cap-enabled joiners.
    */
   readonly messages?: MessageStore;
+  /**
+   * Nick-history source for the `WHOWAS` command (absent when WHOWAS
+   * history retention is disabled for this deployment). When present, the
+   * QUIT and post-registration NICK-change reducers record sign-off
+   * entries and the WHOWAS reducer replays them.
+   */
+  readonly history?: NickHistoryStore;
   /** The connection invoking the command. Reducers mutate this freely. */
   readonly connection: ConnectionState;
   /** Convenience: `connection.id`. */
@@ -147,7 +187,9 @@ export interface BuildCtxOptions {
   ids: IdFactory;
   motd: MotdProvider;
   accounts?: AccountStore;
+  mtlsIdentity?: MtlsIdentityProvider;
   messages?: MessageStore;
+  history?: NickHistoryStore;
   connection: ConnectionState;
 }
 
@@ -163,7 +205,9 @@ export function buildCtx(opts: BuildCtxOptions): Ctx {
     connection: opts.connection,
     connId: opts.connection.id,
     ...(opts.accounts !== undefined ? { accounts: opts.accounts } : {}),
+    ...(opts.mtlsIdentity !== undefined ? { mtlsIdentity: opts.mtlsIdentity } : {}),
     ...(opts.messages !== undefined ? { messages: opts.messages } : {}),
+    ...(opts.history !== undefined ? { history: opts.history } : {}),
   };
   return ctx;
 }

package/packages/irc-core/src/ws-framing.ts

@@ -0,0 +1,132 @@
+/**
+ * WebSocket IRC-message framing and the IRCv3 510-byte message budget.
+ *
+ * The IRCv3 WebSocket spec
+ * (https://ircv3.net/specs/websockets.html) changes two things about how a
+ * WebSocket text/binary message maps to an IRC message, relative to the
+ * legacy framing a raw-TCP-tolerant adapter uses:
+ *
+ *   1. **One IRC message per WebSocket message.** A frame never carries
+ *      several `\r\n`-joined messages, so framing MUST NOT split on an
+ *      embedded line break. A single optional trailing CR-LF (or bare LF)
+ *      is stripped and the remainder is treated as exactly one IRC line.
+ *
+ *   2. **No trailing CR-LF on the wire.** The 512-byte IRC line limit
+ *      therefore applies to the message content only, giving a hard cap of
+ *      {@link MAX_WS_MESSAGE_BYTES} (510) bytes per WebSocket message.
+ *
+ * The legacy framing (`WsFrameMode === 'legacy'`) preserves the original
+ * adapter behaviour: split the whole frame on `/\r?\n/` so older clients
+ * that concatenate messages into one frame keep working. That is the same
+ * `splitFrameLines` logic the transport layer shipped before subprotocol
+ * negotiation existed.
+ *
+ * Everything here is pure and platform-agnostic so it runs unchanged on
+ * every WebSocket runtime (Node `ws`, Cloudflare Durable Objects, Lambda).
+ */
+
+import type { WsSubprotocol } from './ws-subprotocol.js';
+
+/**
+ * How a WebSocket message is framed into IRC lines.
+ *
+ *   - `spec-text`   — `text.ircv3.net`: one IRC message per frame, trailing
+ *                     CR-LF stripped, never split.
+ *   - `spec-binary` — `binary.ircv3.net`: same framing as `spec-text`.
+ *   - `legacy`      — no IRCv3 subprotocol negotiated: split the frame on
+ *                     `/\r?\n/` (the original adapter behaviour).
+ */
+export type WsFrameMode = 'spec-text' | 'spec-binary' | 'legacy';
+
+/**
+ * Maximum number of bytes allowed in a single IRCv3 WebSocket message.
+ *
+ * The IRC line limit is 512 bytes *including* the trailing CR-LF. WebSocket
+ * messages omit the trailing CR-LF, so the content budget is `512 - 2 = 510`.
+ * Inbound messages exceeding this MUST be rejected.
+ */
+export const MAX_WS_MESSAGE_BYTES = 510;
+
+/**
+ * Maps a negotiated IRCv3 subprotocol onto the matching {@link WsFrameMode}.
+ * `undefined` (no subprotocol) maps to the legacy-tolerant framing.
+ */
+export function wsFrameModeFor(subproto: WsSubprotocol | undefined): WsFrameMode {
+  if (subproto === 'text.ircv3.net') return 'spec-text';
+  if (subproto === 'binary.ircv3.net') return 'spec-binary';
+  return 'legacy';
+}
+
+/**
+ * Strips a single trailing `\r\n` (or bare `\n`) from `s`. Leaves every
+ * other character — including leading or embedded terminators — untouched.
+ * Used by the spec-mode framing to yield one bare IRC line per frame.
+ */
+export function stripTrailingCrLf(s: string): string {
+  if (s.endsWith('\r\n')) return s.slice(0, -2);
+  if (s.endsWith('\n')) return s.slice(0, -1);
+  return s;
+}
+
+/**
+ * Splits a WebSocket text frame into IRC lines using the legacy-tolerant
+ * contract: split the whole frame on `/\r?\n/`, returning every part
+ * (including a possible trailing empty string). The empty frame yields no
+ * lines.
+ *
+ * This is the exact behaviour the transport layer shipped before IRCv3
+ * subprotocol negotiation; spec-mode framing ({@link frameToLines}) does
+ * NOT use it.
+ */
+export function splitFrameLines(text: string): string[] {
+  if (text.length === 0) return [];
+  return text.split(/\r?\n/u);
+}
+
+/**
+ * Frames `frame` into IRC lines according to `mode`.
+ *
+ *   - `spec-text` / `spec-binary`: one IRC message per frame. A single
+ *     trailing CR-LF (or bare LF) is stripped and the remainder is returned
+ *     as the sole element. The frame is never split on an embedded line
+ *     break. An empty frame (or a frame that is only a terminator) yields
+ *     no lines.
+ *   - `legacy`: delegates to {@link splitFrameLines} (split on `/\r?\n/`).
+ */
+export function frameToLines(frame: string, mode: WsFrameMode): string[] {
+  if (mode === 'legacy') return splitFrameLines(frame);
+  const line = stripTrailingCrLf(frame);
+  if (line.length === 0) return [];
+  return [line];
+}
+
+/**
+ * Returns `true` when `frame` fits within the IRCv3 WebSocket 510-byte
+ * message budget, `false` when it exceeds it and MUST be rejected by the
+ * inbound path. Measured in UTF-16 code units, consistent with how
+ * {@link enforceLineLimit} and the input parser cap line length across this
+ * package (every supported runtime exposes `.length`).
+ */
+export function isWithinWsByteBudget(frame: string): boolean {
+  return frame.length <= MAX_WS_MESSAGE_BYTES;
+}
+
+/**
+ * Replaces every unpaired UTF-16 surrogate in `str` with U+FFFD (the
+ * Unicode replacement character).
+ *
+ * `text.ircv3.net` frames are UTF-8 text. A lone surrogate (half of a
+ * surrogate pair) has no valid UTF-8 encoding, so per the Unicode
+ * recommendation it is substituted with U+FFFD before the frame is handed
+ * to the parser. Valid surrogate pairs (supplementary-plane code points)
+ * are preserved unchanged, as is all BMP text.
+ */
+export function sanitizeForTextMode(str: string): string {
+  // A lone high surrogate (0xD800–0xDBFF) NOT followed by a low surrogate,
+  // and a lone low surrogate (0xDC00–0xDFFF) NOT preceded by a high
+  // surrogate. Both are replaced with U+FFFD.
+  return str.replace(
+    /(?:[\uD800-\uDBFF](?![\uDC00-\uDFFF]))|(?:(?<![\uD800-\uDBFF])[\uDC00-\uDFFF])/gu,
+    '\uFFFD',
+  );
+}

package/packages/irc-core/src/ws-subprotocol.ts

@@ -0,0 +1,66 @@
+/**
+ * WebSocket subprotocol negotiation for IRC connections (IRCv3).
+ *
+ * The IRCv3 WebSocket specification defines two subprotocols a client may
+ * offer in its opening handshake via the `Sec-WebSocket-Protocol` header:
+ *
+ *   - `text.ircv3.net`   — UTF-8 text frames, one IRC message per WebSocket
+ *                          message, no trailing CR-LF.
+ *   - `binary.ircv3.net` — binary frames, one IRC message per WebSocket
+ *                          message, no trailing CR-LF.
+ *
+ * The header is a comma-separated list offered in client-preference order.
+ * These pure helpers parse the header and select the single subprotocol the
+ * server should agree to (the first supported entry, honouring the client's
+ * preference). They are dependency-free so they run unchanged on every
+ * runtime (Node, Workers, Lambda).
+ */
+
+/** The IRCv3 binary WebSocket subprotocol. */
+export const WS_SUBPROTO_BINARY = 'binary.ircv3.net';
+
+/** The IRCv3 text WebSocket subprotocol. */
+export const WS_SUBPROTO_TEXT = 'text.ircv3.net';
+
+/** A supported IRCv3 WebSocket subprotocol name. */
+export type WsSubprotocol = typeof WS_SUBPROTO_TEXT | typeof WS_SUBPROTO_BINARY;
+
+/**
+ * Parses the `Sec-WebSocket-Protocol` header value into an ordered list of
+ * offered protocols (client-preference order). Whitespace around each item is
+ * trimmed and empty entries (stray/leading/trailing commas) are dropped.
+ * Duplicate entries are preserved in their original order.
+ *
+ * `null`, `undefined`, or an empty string yield an empty array.
+ *
+ * @param header The raw `Sec-WebSocket-Protocol` header value, if present.
+ */
+export function parseSecWsProtocolOffers(header: string | null | undefined): string[] {
+  if (header === null || header === undefined || header === '') {
+    return [];
+  }
+  const offers: string[] = [];
+  for (const raw of header.split(',')) {
+    const item = raw.trim();
+    if (item !== '') {
+      offers.push(item);
+    }
+  }
+  return offers;
+}
+
+/**
+ * Selects the supported subprotocol to agree to from a list of client offers
+ * (in client-preference order). Returns the first offer that matches a
+ * supported subprotocol, or `null` when none match.
+ *
+ * @param offers The ordered list of offered protocols.
+ */
+export function selectSubprotocol(offers: readonly string[]): WsSubprotocol | null {
+  for (const offer of offers) {
+    if (offer === WS_SUBPROTO_TEXT || offer === WS_SUBPROTO_BINARY) {
+      return offer as WsSubprotocol;
+    }
+  }
+  return null;
+}

package/packages/irc-core/tests/account-store.test.ts

@@ -65,9 +65,9 @@ describe('InMemoryAccountStore — PLAIN', () => {
 });
 
 describe('InMemoryAccountStore — mechanism handling', () => {
-  it('rejects any non-PLAIN mechanism with a failure result', () => {
+  it('rejects an unsupported mechanism with a failure result', () => {
     const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
-    const out = store.verify('EXTERNAL', { kind: 'RAW', data: 'cert-subject' });
+    const out = store.verify('CRAM-MD5', { kind: 'RAW', data: 'whatever' });
     expect(out.ok).toBe(false);
   });
 
@@ -78,6 +78,49 @@ describe('InMemoryAccountStore — mechanism handling', () => {
   });
 });
 
+describe('InMemoryAccountStore — EXTERNAL (mTLS)', () => {
+  it('maps a known cert subject to its account', () => {
+    const store = new InMemoryAccountStore([
+      { username: 'alice', password: 'secret', certSubject: 'CN=alice' },
+    ]);
+    const out = store.verify('EXTERNAL', { kind: 'EXTERNAL', identity: 'CN=alice' });
+    expect(out).toEqual<SaslResult>({ ok: true, account: 'alice' });
+  });
+
+  it('rejects an unknown cert subject', () => {
+    const store = new InMemoryAccountStore([
+      { username: 'alice', password: 'secret', certSubject: 'CN=alice' },
+    ]);
+    const out = store.verify('EXTERNAL', { kind: 'EXTERNAL', identity: 'CN=evil' });
+    expect(out.ok).toBe(false);
+  });
+
+  it('rejects EXTERNAL when no cert subjects are configured', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('EXTERNAL', { kind: 'EXTERNAL', identity: 'CN=alice' });
+    expect(out.ok).toBe(false);
+  });
+
+  it('treats the mechanism name case-insensitively for EXTERNAL', () => {
+    const store = new InMemoryAccountStore([
+      { username: 'alice', password: 'secret', certSubject: 'CN=alice' },
+    ]);
+    const out = store.verify('external', { kind: 'EXTERNAL', identity: 'CN=alice' });
+    expect(out).toEqual<SaslResult>({ ok: true, account: 'alice' });
+  });
+
+  it('maps multiple accounts with distinct cert subjects', () => {
+    const store = new InMemoryAccountStore([
+      { username: 'alice', password: 'a', certSubject: 'CN=alice' },
+      { username: 'bob', password: 'b', certSubject: 'CN=bob' },
+    ]);
+    expect(store.verify('EXTERNAL', { kind: 'EXTERNAL', identity: 'CN=bob' })).toEqual<SaslResult>({
+      ok: true,
+      account: 'bob',
+    });
+  });
+});
+
 describe('InMemoryAccountStore — failure reason', () => {
   it('returns a human-readable reason on failure', () => {
     const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);

package/packages/irc-core/tests/admission.test.ts

@@ -211,6 +211,24 @@ describe('AdmissionStats — release', () => {
     const stats = makeStats(clock);
     expect(() => stats.release('unknown')).not.toThrow();
   });
+
+  it('deletes the per-IP and per-user keys when the last admission is released', () => {
+    // Covers the `next <= 0` delete branch in `release`: a single recorded
+    // admission, when released, must clear the keys entirely rather than
+    // leaving a zero entry in the maps.
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    const d = decideAdmission('5.6.7.8', 'carol', stats, BASE_CONFIG);
+    if (!d.ok) throw new Error('precondition: d should admit');
+    stats.recordAdmission('5.6.7.8', 'carol', d.recordId);
+
+    stats.release(d.recordId);
+
+    // A fresh admission from the same IP/user must be allowed (counts are
+    // back to zero because the keys were deleted, not just decremented).
+    const after = decideAdmission('5.6.7.8', 'carol', stats, BASE_CONFIG);
+    expect(after.ok).toBe(true);
+  });
 });
 
 describe('AdmissionStats — determinism', () => {

package/packages/irc-core/tests/caps/capabilities.test.ts

@@ -31,10 +31,10 @@ describe('SUPPORTED_CAPABILITIES', () => {
     );
   });
 
-  it('declares the sasl value as the advertised mechanism list', () => {
+  it('declares the sasl value as the base mechanism list (PLAIN only by default)', () => {
     const sasl = SUPPORTED_CAPABILITIES.find((c) => c.name === 'sasl');
     expect(sasl).toBeDefined();
-    expect(sasl?.value).toBe('PLAIN,EXTERNAL');
+    expect(sasl?.value).toBe('PLAIN');
   });
 
   it('does not attach a value to caps that have no parameter', () => {
@@ -107,7 +107,8 @@ describe('getLsString', () => {
   });
 
   it('contains the sasl token with its value', () => {
-    expect(getLsString()).toContain('sasl=PLAIN,EXTERNAL');
+    expect(getLsString()).toContain('sasl=PLAIN');
+    expect(getLsString()).not.toContain('sasl=PLAIN,EXTERNAL');
   });
 
   it('contains server-time as a bare name', () => {

package/packages/irc-core/tests/commands/cap.test.ts

@@ -4,6 +4,7 @@ import { capReducer } from '../../src/commands/cap';
 import { userReducer } from '../../src/commands/registration';
 import { Effect } from '../../src/effects';
 import type { Effect as EffectType, RawLine } from '../../src/effects';
+import type { MtlsIdentityProvider } from '../../src/ports';
 import { EmptyMotdProvider, FakeClock, SequentialIdFactory } from '../../src/ports';
 import { type ConnectionState, createConnection } from '../../src/state/connection';
 import { type Ctx, type ServerConfig, buildCtx } from '../../src/types';
@@ -20,13 +21,18 @@ const serverConfig: ServerConfig = {
   quitMessage: 'Client Quit',
 };
 
-function makeCtx(state: ConnectionState, cfg: ServerConfig = serverConfig): Ctx {
+function makeCtx(
+  state: ConnectionState,
+  cfg: ServerConfig = serverConfig,
+  mtlsIdentity?: MtlsIdentityProvider,
+): Ctx {
   return buildCtx({
     serverConfig: cfg,
     clock: new FakeClock(1_000),
     ids: new SequentialIdFactory(),
     motd: EmptyMotdProvider,
     connection: state,
+    ...(mtlsIdentity !== undefined ? { mtlsIdentity } : {}),
   });
 }
 
@@ -110,6 +116,32 @@ describe('capReducer — LS', () => {
     }
   });
 
+  it('advertises sasl=PLAIN when no mTLS provider is configured', () => {
+    const state = makeState();
+    const ctx = makeCtx(state);
+    const out = capReducer(state, { command: 'CAP', params: ['LS'], tags: {} }, ctx);
+    const send = out.effects[0];
+    expect(send).toBeDefined();
+    if (send?.tag === 'Send') {
+      const body = send.lines[0]?.text ?? '';
+      expect(body).toContain('sasl=PLAIN');
+      expect(body).not.toContain('sasl=PLAIN,EXTERNAL');
+    }
+  });
+
+  it('advertises sasl=PLAIN,EXTERNAL when an mTLS provider is configured', () => {
+    const state = makeState();
+    const provider: MtlsIdentityProvider = { getIdentity: () => 'CN=alice' };
+    const ctx = makeCtx(state, serverConfig, provider);
+    const out = capReducer(state, { command: 'CAP', params: ['LS'], tags: {} }, ctx);
+    const send = out.effects[0];
+    expect(send).toBeDefined();
+    if (send?.tag === 'Send') {
+      const body = send.lines[0]?.text ?? '';
+      expect(body).toContain('sasl=PLAIN,EXTERNAL');
+    }
+  });
+
   it('marks the connection as in CAP negotiation so the welcome is deferred', () => {
     const state = makeState();
     const ctx = makeCtx(state);