serverless-ircd 0.4.0 → 0.6.0

package/packages/irc-core/src/protocol/labeled-response.ts

@@ -0,0 +1,133 @@
+/**
+ * IRCv3 `labeled-response` — correlate a request with its replies.
+ *
+ * Spec: https://ircv3.net/specs/extensions/labeled-response
+ *
+ * A client tags an inbound message with the `+label=<id>` client tag; the
+ * server then wraps every reply caused by that message (addressed back to
+ * the requester) in a single `BATCH +id labeled-response … BATCH -id`
+ * frame. If the request produces no reply for the requester, the server
+ * emits an empty batch so the client can still correlate the label with a
+ * definitive "no replies" answer.
+ *
+ * Unlike the generic {@link wrapBatch} helper — which elides empty batches
+ * because the IRCv3 `batch` spec forbids them — {@link wrapLabeledResponse}
+ * ALWAYS emits the start/end markers. The empty-batch case is the whole
+ * point of labeled-response: it is the correlation signal when there is
+ * nothing else to send.
+ *
+ * This module is pure data transformation. The actor layer:
+ *   1. extracts the label from the parsed message tags,
+ *   2. plumbs it onto {@link Ctx.label} so every reducer's emitted effects
+ *      are uniformly attributable to the labeled request, and
+ *   3. runs {@link applyLabelToEffects} over the reducer's `Effect[]` to
+ *      gather every `Send`-to-self and wrap them (or emit an empty batch).
+ *
+ * Only `Send` effects addressed to the originating connection are wrapped.
+ * Broadcasts / `SendToNick` / `BroadcastWallops` reach OTHER connections
+ * and are left in place; the label correlation applies solely to the
+ * requester's own reply stream.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { ConnId } from '../state/connection.js';
+
+/** Wire name of the `labeled-response` capability. */
+export const LABELED_RESPONSE_CAP_NAME = 'labeled-response';
+
+/** Wire name of the `+label` client tag carried on the inbound message. */
+export const LABEL_TAG = '+label';
+
+/** Batch type token used for every labeled-response frame. */
+const LABELED_RESPONSE_BATCH_TYPE = 'labeled-response';
+
+/**
+ * Reads the `+label` client tag from a parsed message's tag map.
+ *
+ * Returns `undefined` when the tag is absent OR present-but-empty, so callers
+ * can treat a missing label and a bare `+label` (no value) identically: both
+ * mean "this request is unlabeled".
+ */
+export function extractLabel(tags: Readonly<Record<string, string>>): string | undefined {
+  const value = tags[LABEL_TAG];
+  if (value === undefined || value.length === 0) return undefined;
+  return value;
+}
+
+/**
+ * Wraps `lines` in IRCv3 `BATCH +label labeled-response … BATCH -label`
+ * framing. ALWAYS emits the start and end markers — even when `lines` is
+ * empty — because the labeled-response spec requires an empty batch when a
+ * labeled request produces no reply (it is the correlation signal).
+ */
+export function wrapLabeledResponse(label: string, lines: readonly RawLine[]): RawLine[] {
+  const start: RawLine = { text: `BATCH +${label} ${LABELED_RESPONSE_BATCH_TYPE}` };
+  const end: RawLine = { text: `BATCH -${label}` };
+  return [start, ...lines, end];
+}
+
+/**
+ * Options for {@link applyLabelToEffects}.
+ *
+ * `label` is `string | undefined` (NOT an optional field) so the helper can
+ * be a clean no-op under `exactOptionalPropertyTypes` when the inbound
+ * request carried no label.
+ */
+export interface LabelApplyOptions {
+  /** The label extracted from the inbound `+label` tag, or `undefined`. */
+  readonly label: string | undefined;
+  /** The originating connection id (replies wrapped are addressed here). */
+  readonly connId: ConnId;
+}
+
+/**
+ * Gathers every `Send` effect addressed to `connId` and replaces them with a
+ * single `Send` whose lines are wrapped in one `labeled-response` batch.
+ *
+ * Behaviour:
+ *   - When `label` is `undefined` the effect list is returned unchanged
+ *     (copy) — the request was not labeled.
+ *   - All `Send`-to-`connId` effects, wherever they appear, are accumulated
+ *     in original order into one batch.
+ *   - The wrapped batch is placed at the position of the FIRST collected
+ *     `Send`-to-self, so the reducer's intended ordering relative to other
+ *     effects (broadcasts, etc.) is preserved.
+ *   - When NO `Send`-to-self exists, an empty labeled batch is appended at
+ *     the end — the requester still observes the label correlation.
+ *   - Every other effect (Broadcast, SendToNick, Disconnect, …) is left in
+ *     place and in order; only the requester's own reply stream is wrapped.
+ */
+export function applyLabelToEffects(
+  effects: readonly EffectType[],
+  opts: LabelApplyOptions,
+): EffectType[] {
+  const { label, connId } = opts;
+  if (label === undefined) return [...effects];
+
+  const selfLines: RawLine[] = [];
+  let firstSelfIdx = -1;
+  for (const [i, effect] of effects.entries()) {
+    if (effect.tag === 'Send' && effect.to === connId) {
+      if (firstSelfIdx === -1) firstSelfIdx = i;
+      selfLines.push(...effect.lines);
+    }
+  }
+
+  const batchEffect: EffectType = Effect.send(connId, wrapLabeledResponse(label, selfLines));
+
+  // No self-send to anchor on: append the empty labeled batch at the end.
+  if (firstSelfIdx === -1) {
+    return [...effects, batchEffect];
+  }
+
+  const out: EffectType[] = [];
+  for (const [i, effect] of effects.entries()) {
+    // Emit the single wrapped batch where the first self-send lived.
+    if (i === firstSelfIdx) out.push(batchEffect);
+    // Drop every original self-send (they are now inside the batch).
+    if (effect.tag === 'Send' && effect.to === connId) continue;
+    out.push(effect);
+  }
+  return out;
+}

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

@@ -16,6 +16,36 @@ export const Numerics = {
   // Capability / stats admin / version
   RPL_ADMINME: 256,
 
+  // LUSERS (RFC 2812 §4.6.2). Network-wide user/channel/server counts.
+  // 251 is the human-readable summary; 252–254 are emitted only when their
+  // count is non-zero (per RFC). 255 is the local-server summary. 265/266
+  // carry the optional local/global max-connection context.
+  RPL_LUSERCLIENT: 251,
+  RPL_LUSEROP: 252,
+  RPL_LUSERUNKNOWN: 253,
+  RPL_LUSERCHANNELS: 254,
+  RPL_LUSERME: 255,
+  RPL_LOCALUSERS: 265,
+  RPL_GLOBALUSERS: 266,
+
+  // STATS (RFC 2812 §4.6.3 / §5.1). 211 is link-info (the `l` query),
+  // 242 is the uptime line (the `u` query), and 219 terminates every
+  // STATS reply regardless of query letter. The remaining RPL_STATS*
+  // codes (212–218, 240–248) are deferred behind per-letter tests.
+  RPL_STATSLINKINFO: 211,
+  RPL_ENDOFSTATS: 219,
+  RPL_STATSUPTIME: 242,
+
+  // TRACE (RFC 2812 §4.6.3). In a single-server deployment TRACE collapses
+  // to a local-server line (200/206) plus optional per-connection detail
+  // (204 oper / 205 user), terminated by 262. Multi-hop S2S tracing is a
+  // PLAN non-goal.
+  RPL_TRACELINK: 200,
+  RPL_TRACEOPERATOR: 204,
+  RPL_TRACEUSER: 205,
+  RPL_TRACESERVER: 206,
+  RPL_ENDOFTRACE: 262,
+
   // Away / userhost / ison
   RPL_AWAY: 301,
   RPL_USERHOST: 302,
@@ -23,6 +53,15 @@ export const Numerics = {
   RPL_UNAWAY: 305,
   RPL_NOWAWAY: 306,
 
+  // IRCv3 MONITOR (modern ISON replacement). The watchlist lives on
+  // {@link ConnectionState.monitorList}; transitions push 730/731
+  // asynchronously via the actor's nick-registry hooks.
+  RPL_MONONLINE: 730,
+  RPL_MONOFFLINE: 731,
+  RPL_MONLIST: 732,
+  RPL_ENDOFMONLIST: 733,
+  ERR_MONLISTFULL: 734,
+
   // Version
   RPL_VERSION: 351,
 
@@ -34,6 +73,12 @@ export const Numerics = {
   RPL_ENDOFWHOIS: 318,
   RPL_WHOISCHANNELS: 319,
   RPL_WHOISACCOUNT: 330,
+  /**
+   * `276 RPL_WHOISSECURE` — target is connected over TLS (user mode `S`).
+   * Surfaced between the oper/account lines and the idle line so clients
+   * render it as part of the secure-connection WHOIS block.
+   */
+  RPL_WHOISSECURE: 276,
   RPL_WHOWASUSER: 314,
 
   // LIST
@@ -61,10 +106,8 @@ export const Numerics = {
   RPL_NAMREPLY: 353,
   RPL_ENDOFNAMES: 366,
 
-  // Links / ban / whowas. RPL_LINKS/RPL_ENDOFLINKS retained for the deferred
-  // LINKS verb (S2S server list — PLAN non-goal; see actor default-route triage).
-  RPL_LINKS: 364,
-  RPL_ENDOFLINKS: 365,
+  // Ban / whowas. (The S2S `LINKS` verb and its `RPL_LINKS`/`RPL_ENDOFLINKS`
+  // numerics were dropped — S2S is a PLAN non-goal.)
   RPL_BANLIST: 367,
   RPL_ENDOFBANLIST: 368,
   RPL_ENDOFWHOWAS: 369,
@@ -76,11 +119,12 @@ export const Numerics = {
   RPL_MOTDSTART: 375,
   RPL_ENDOFMOTD: 376,
 
-  // Oper. RPL_REHASHING retained for the deferred REHASH verb (no runtime
-  // config-reload path in serverless; see actor default-route triage).
+  // Oper. RPL_REHASHING is emitted by the oper-gated `REHASH` reducer when a
+  // config reload is requested (the actor re-invokes the adapter's loader).
+  // (The RFC 2812 `SERVICE` verb and its `RPL_YOURESERVICE` numeric were
+  // dropped — obsolete, never widely implemented.)
   RPL_YOUREOPER: 381,
   RPL_REHASHING: 382,
-  RPL_YOURESERVICE: 383,
   RPL_TIME: 391,
 
   // SASL (IRCv3 sasl-3.2)
@@ -102,7 +146,8 @@ export const Numerics = {
   ERR_TOOMANYCHANNELS: 405,
   ERR_WASNOSUCHNICK: 406,
   ERR_TOOMANYTARGETS: 407,
-  ERR_NOSUCHSERVICE: 408, // retained: deferred SERVICE verb (RFC 2812 obsolete)
+  // `ERR_NOSUCHSERVICE` (408) was dropped with the obsolete RFC 2812 `SERVICE`
+  // verb.
   ERR_INVALIDCAPCMD: 410,
   ERR_NORECIPIENT: 411,
   ERR_NOTEXTTOSEND: 412,
@@ -121,8 +166,8 @@ export const Numerics = {
   ERR_NOTONCHANNEL: 442,
   ERR_USERONCHANNEL: 443,
   ERR_NOLOGIN: 444,
-  ERR_SUMMONDISABLED: 445, // retained: deferred SUMMON verb (RFC 2812 obsolete)
-  ERR_USERSDISABLED: 446, // retained: deferred USERS verb (RFC 2812 obsolete)
+  // `ERR_SUMMONDISABLED` (445) / `ERR_USERSDISABLED` (446) were dropped with
+  // the obsolete RFC 2812 `SUMMON`/`USERS` verbs.
   ERR_NOTREGISTERED: 451,
   ERR_NEEDMOREPARAMS: 461,
   ERR_ALREADYREGISTRED: 462,
@@ -140,7 +185,8 @@ export const Numerics = {
   ERR_BANLISTFULL: 478,
   ERR_NOPRIVILEGES: 481,
   ERR_CHANOPRIVSNEEDED: 482,
-  ERR_CANTKILLSERVER: 483, // retained: deferred SQUIT verb (S2S, PLAN non-goal)
+  // `ERR_CANTKILLSERVER` (483) was dropped with the S2S `SQUIT` verb — S2S is
+  // a PLAN non-goal.
   ERR_NOOPERHOST: 491,
   ERR_UMODEUNKNOWNFLAG: 501,
   ERR_USERSDONTMATCH: 502,

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('@');
@@ -114,6 +126,14 @@ export function enforceLineLimit(line: RawLine, caps: ReadonlySet<string>): RawL
  * Server-defined tags (no `+` prefix) are left in place — each is gated by
  * its own capability (server-time, account-tag, …) applied elsewhere.
  *
+ * Spec exception: IRCv3 `draft/typing` carves out a whitelist for the
+ * `+draft/typing` client tag. A recipient that announced `draft/typing`
+ * (but NOT `message-tags`) still receives `+draft/typing` so typing
+ * indicators work without the broader message-tags cap. `draft/read-marker`
+ * carves out the same exception for its `+draft/read-marker` tag so a
+ * read-marker update reaches the user's other connections. Every other
+ * client tag remains stripped for such recipients.
+ *
  * When filtering removes every tag, the leading `@... ` section is dropped
  * entirely so legacy clients never observe a bare tag prefix.
  *
@@ -130,10 +150,17 @@ export function filterClientTags(line: RawLine, caps: ReadonlySet<string>): RawL
   const rest = line.text.slice(spaceIdx + 1);
   const entries = tagSection.split(';');
 
+  const typingWhitelisted = caps.has('draft/typing');
+  const readMarkerWhitelisted = caps.has('draft/read-marker');
   const hasClientTag = entries.some((entry) => clientTagKey(entry).startsWith('+'));
   if (!hasClientTag) return line;
 
-  const kept = entries.filter((entry) => !clientTagKey(entry).startsWith('+'));
+  const kept = entries.filter((entry) => {
+    const key = clientTagKey(entry);
+    if (!key.startsWith('+')) return true;
+    if (typingWhitelisted && key === '+draft/typing') return true;
+    return readMarkerWhitelisted && key === '+draft/read-marker';
+  });
   if (kept.length === 0) return { text: rest };
   return { text: `@${kept.join(';')} ${rest}` };
 }
@@ -143,3 +170,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/protocol/standard-replies.ts

@@ -0,0 +1,277 @@
+/**
+ * IRCv3 `standard-replies` — `FAIL` / `WARN` / `NOTE` dispatch helper.
+ *
+ * Spec: https://ircv3.net/specs/extensions/standard-replies-3.0
+ *
+ * Modern IRC clients that negotiated the `standard-replies` cap accept the
+ * structured reply form
+ *
+ *     :<server> FAIL   <command> <code> [<context>...] :<description>
+ *     :<server> WARN   <command> <code> [<context>...] :<description>
+ *     :<server> NOTE   <command> <code> [<context>...] :<description>
+ *
+ * in place of the legacy `:server NNN nick ... :trailing` numerics for a
+ * curated subset of errors. Numeric-only replies (MOTD lines, NAMES,
+ * welcome block, …) stay on the numeric form — only the curated error
+ * numerics are translated.
+ *
+ * This module is the data-driven mapping plus a single pure dispatch
+ * helper ({@link toStandardReply}) that the dispatch / outbound layer
+ * applies per recipient. Translating at the outbound layer (rather than
+ * scattering `if (caps.has('standard-replies'))` through every reducer)
+ * keeps the reducer code cap-agnostic, matching the model already used
+ * for `server-time` and `message-tags`.
+ *
+ * Reducers keep emitting the canonical numeric line; the dispatch layer
+ * runs this helper to translate the curated numerics for cap-enabled
+ * recipients and passes everything else through verbatim.
+ */
+
+import type { RawLine } from '../effects.js';
+import { Numerics } from './numerics.js';
+
+/** One of the IRCv3 standard-reply verbs. */
+export type ReplyKind = 'FAIL' | 'WARN' | 'NOTE';
+
+/**
+ * One row of the {@link numericToStandardReply} table, as a discriminated
+ * union over where the COMMAND token comes from on the wire.
+ *
+ *  - When {@link CommandFromMiddle.commandFromMiddle} is `true`, the
+ *    numeric's middle parameter IS the failed command name (true for
+ *    `461 ERR_NEEDMOREPARAMS`, whose middle is the command the client
+ *    undersupplied).
+ *  - When {@link CommandFixed.commandFromMiddle} is `false`, a fixed
+ *    {@link CommandFixed.command} is emitted (true for `432`/`433`,
+ *    always `NICK`, and for SASL failures, always `AUTHENTICATE`).
+ *
+ * The discriminated union lets `pickCommand` return `mapping.command`
+ * directly in the fixed branch with no defensive `?? null` — the type
+ * system proves `command` is always set there.
+ */
+export type StandardReplyMapping = CommandFromMiddle | CommandFixed;
+
+/** A row whose COMMAND token comes from the numeric's middle parameter. */
+export interface CommandFromMiddle {
+  /** Discriminant: true → read COMMAND from `parsed.middle[0]`. */
+  commandFromMiddle: true;
+  /** Which of `FAIL`/`WARN`/`NOTE` to emit. */
+  kind: ReplyKind;
+  /** Stable wire code (`INVALID_PARAMS`, …). */
+  code: string;
+  /** Always false here — the middle is consumed as the command, not context. */
+  contextFromMiddle: false;
+}
+
+/** A row whose COMMAND token is a fixed string. */
+export interface CommandFixed {
+  /** Discriminant: false → read COMMAND from {@link command}. */
+  commandFromMiddle: false;
+  /** Which of `FAIL`/`WARN`/`NOTE` to emit. */
+  kind: ReplyKind;
+  /** Stable wire code (`NO_SUCH_CHANNEL`, `INVALID_NICK`, …). */
+  code: string;
+  /** Fixed command token emitted after the FAIL/WARN/NOTE verb. */
+  command: string;
+  /**
+   * True iff the numeric's middle parameter carries a context token
+   * (the bad nick, the bad channel) that should follow the code.
+   */
+  contextFromMiddle: boolean;
+}
+
+/**
+ * The curated numeric → standard-reply mapping.
+ *
+ * Only a deliberately small subset of error numerics is translated —
+ * the ones that carry enough context for the structured form to be a
+ * strict improvement over the bare numeric. Numeric-only families
+ * (MOTD, NAMES, the welcome block, mode replies, …) stay on the
+ * numeric form per the spec.
+ */
+export const numericToStandardReply: ReadonlyMap<number, StandardReplyMapping> = new Map<
+  number,
+  StandardReplyMapping
+>([
+  [
+    Numerics.ERR_NEEDMOREPARAMS,
+    {
+      kind: 'FAIL',
+      code: 'INVALID_PARAMS',
+      commandFromMiddle: true,
+      contextFromMiddle: false,
+    },
+  ],
+  [
+    Numerics.ERR_NOSUCHCHANNEL,
+    {
+      kind: 'FAIL',
+      code: 'NO_SUCH_CHANNEL',
+      commandFromMiddle: false,
+      command: 'JOIN',
+      contextFromMiddle: true,
+    },
+  ],
+  [
+    Numerics.ERR_ERRONEUSNICKNAME,
+    {
+      kind: 'FAIL',
+      code: 'INVALID_NICK',
+      commandFromMiddle: false,
+      command: 'NICK',
+      contextFromMiddle: true,
+    },
+  ],
+  [
+    Numerics.ERR_NICKNAMEINUSE,
+    {
+      kind: 'FAIL',
+      code: 'NICKNAME_IN_USE',
+      commandFromMiddle: false,
+      command: 'NICK',
+      contextFromMiddle: true,
+    },
+  ],
+  [
+    Numerics.ERR_SASLFAIL,
+    {
+      kind: 'FAIL',
+      code: 'SASL_FAILED',
+      commandFromMiddle: false,
+      command: 'AUTHENTICATE',
+      contextFromMiddle: false,
+    },
+  ],
+]);
+
+/**
+ * Translates a single outbound {@link RawLine} for a recipient whose
+ * negotiated caps are `caps`.
+ *
+ *  - If the recipient lacks the `standard-replies` cap, the line is
+ *    returned unchanged (the legacy numeric still ships).
+ *  - If the line is not a `:server NNN …` numeric, it is returned
+ *    unchanged (PRIVMSG, BATCH, FAIL/WARN/NOTE already emitted by
+ *    reducers, etc.).
+ *  - If the numeric is not in {@link numericToStandardReply}, the line
+ *    is returned unchanged.
+ *  - Otherwise the line is rewritten into the structured
+ *    `FAIL`/`WARN`/`NOTE` form using the table.
+ *
+ * The input is never mutated; the original object is returned whenever
+ * no translation occurred so callers can cheaply detect "no change".
+ */
+export function toStandardReply(line: RawLine, caps: ReadonlySet<string>): RawLine {
+  if (!caps.has('standard-replies')) return line;
+  if (!line.text.startsWith(':')) return line;
+
+  const parsed = parseNumericLine(line.text);
+  if (parsed === null) return line;
+
+  const mapping = numericToStandardReply.get(parsed.code);
+  if (mapping === undefined) return line;
+
+  const command = pickCommand(parsed, mapping);
+  if (command === null) return line;
+
+  // The structured form requires a `:description` token. A curated numeric
+  // missing its trailing parameter (malformed input that never ships from a
+  // reducer) is left on the bare numeric so we never emit an empty FAIL.
+  if (parsed.trailing === undefined) return line;
+
+  const context = pickContext(parsed, mapping);
+  const trailing = parsed.trailing;
+
+  const head = `:${parsed.server} ${mapping.kind} ${command} ${mapping.code}`;
+  const withContext = context !== null ? `${head} ${context}` : head;
+  return { text: `${withContext} :${trailing}` };
+}
+
+/** Internal: the parsed shape of a `:server NNN nick [middle] [:trailing]` line. */
+interface ParsedNumeric {
+  server: string;
+  code: number;
+  /** Every token between the nick and the trailing `:`-parameter. May be empty. */
+  middle: string[];
+  /** The trailing `:`-prefixed parameter, with the leading `:` stripped. */
+  trailing: string | undefined;
+}
+
+/**
+ * Parses a single `:server NNN ...` line into its components.
+ *
+ * Returns `null` for any shape this server does not emit for numerics:
+ * lines without a server prefix, lines whose second token is not a
+ * three-digit numeric, and lines with no nick token. The trailing
+ * `:`-parameter is optional (a handful of numerics — currently none in
+ * the curated set — ship without one).
+ */
+function parseNumericLine(text: string): ParsedNumeric | null {
+  // Strip the leading `:server ` prefix.
+  const firstSpace = text.indexOf(' ');
+  if (firstSpace === -1) return null;
+  const server = text.slice(1, firstSpace);
+
+  const rest = text.slice(firstSpace + 1);
+  const secondSpace = rest.indexOf(' ');
+  if (secondSpace === -1) return null;
+  const codeTok = rest.slice(0, secondSpace);
+  if (!/^\d{3}$/.test(codeTok)) return null;
+  const code = Number.parseInt(codeTok, 10);
+
+  const afterCode = rest.slice(secondSpace + 1);
+
+  // The nick token is mandatory between the code and the optional trailing.
+  // Empty after-code or an `:`-prefixed after-code (the trailing param
+  // immediately following the code) is malformed for a numeric this server
+  // emits; bail so the caller passes the line through verbatim.
+  if (afterCode.length === 0) return null;
+  if (afterCode[0] === ':') return null;
+
+  // Split off the trailing `:`-parameter if present.
+  const trailingIdx = findTrailingColon(afterCode);
+  let head = afterCode;
+  let trailing: string | undefined;
+  if (trailingIdx !== -1) {
+    head = afterCode.slice(0, trailingIdx).trimEnd();
+    trailing = afterCode.slice(trailingIdx + 1);
+  }
+
+  // head starts with the nick and optional middle params.
+  const tokens = head.length === 0 ? [] : head.split(' ');
+  if (tokens.length === 0) return null;
+  // Drop the nick — it is not used in the structured form (the reply is
+  // routed to a specific recipient, not addressed by nick).
+  const middle = tokens.slice(1);
+
+  return { server, code, middle, trailing };
+}
+
+/**
+ * Returns the index of the ` :` that introduces the trailing parameter,
+ * or `-1` when the line has no trailing. The leading space is required
+ * so a `:` inside a middle token (e.g. a malformed channel name) is not
+ * misread.
+ */
+function findTrailingColon(s: string): number {
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === ' ' && s[i + 1] === ':') return i + 1;
+  }
+  return -1;
+}
+
+/** Resolves the COMMAND token for the structured reply per the mapping. */
+function pickCommand(parsed: ParsedNumeric, mapping: StandardReplyMapping): string | null {
+  if (mapping.commandFromMiddle) {
+    const cmd = parsed.middle[0];
+    return cmd === undefined ? null : cmd;
+  }
+  return mapping.command;
+}
+
+/** Resolves the optional CONTEXT token for the structured reply per the mapping. */
+function pickContext(parsed: ParsedNumeric, mapping: StandardReplyMapping): string | null {
+  if (!mapping.contextFromMiddle) return null;
+  const ctx = parsed.middle[0];
+  return ctx ?? null;
+}

package/packages/irc-core/src/state/connection.ts

@@ -20,13 +20,21 @@ export type RegistrationState = 'pre-registration' | 'registering' | 'registered
 
 /**
  * User modes applied to a connection. The IRC user-mode letters are
- * `i` (invisible), `o` (oper), `w` (wallops), `s` (server notices).
+ * `i` (invisible), `o` (oper), `w` (wallops), `s` (server notices),
+ * `S` (TLS connected — read-only, set by the transport at registration).
  */
 export interface UserModes {
   invisible: boolean;
   oper: boolean;
   wallops: boolean;
   serverNotices: boolean;
+  /**
+   * User mode `S` — the connection arrived over TLS (wss or irc+tls).
+   * Read-only: set once by the registration reducer from
+   * {@link ConnectionState.secure} and never mutated afterwards. Not
+   * settable via `MODE` (the parser rejects `+S`/`-S` with `501`).
+   */
+  tls: boolean;
 }
 
 /**
@@ -84,6 +92,15 @@ export interface ConnectionState {
    * `CAP END` arrives (per IRCv3 capability-negotiation spec).
    */
   capNegotiating: boolean;
+  /**
+   * Transport-level fact: true when the connection arrived over TLS
+   * (`wss://` WebSocket or `irc+tls://` raw TCP). Set once by the adapter
+   * at construction from the platform's transport metadata and read by the
+   * registration reducer to surface user mode `S` ({@link UserModes.tls}).
+   * Defaults to `false` so existing callers (plain ws test harnesses) keep
+   * the pre-TLS-mode behaviour.
+   */
+  secure: boolean;
   /** IRCv3 capabilities negotiated via `CAP`. */
   caps: Set<string>;
   /** Away reason; absent when not away. */
@@ -109,6 +126,18 @@ export interface ConnectionState {
    * PART/re-JOIN cycle with no new activity replays nothing.
    */
   lastReadMarkers?: Map<string, string>;
+  /**
+   * Per-connection MONITOR watchlist (IRCv3 `MONITOR`). Each entry is the
+   * case-folded (rfc1459) spelling of a watched nick; the display spelling
+   * is resolved at emission time via the nick registry. Lazily allocated
+   * on first `MONITOR +`; persisted verbatim so a reconnect can restore
+   * the watchlist without re-issuing every `MONITOR` line.
+   *
+   * Capped at the deployment's `MONITOR=<n>` ISUPPORT value (default 30);
+   * the {@link monitorReducer} enforces the cap and emits `734
+   * ERR_MONLISTFULL` for rejected nicks.
+   */
+  monitorList?: Set<string>;
 }
 
 /**
@@ -147,6 +176,7 @@ export function createConnection(opts: CreateConnectionOptions): ConnectionState
     id: opts.id,
     registration: 'pre-registration',
     capNegotiating: false,
+    secure: false,
     caps: new Set<string>(),
     joinedChannels: new Set<ChanName>(),
     userModes: {
@@ -154,6 +184,7 @@ export function createConnection(opts: CreateConnectionOptions): ConnectionState
       oper: false,
       wallops: false,
       serverNotices: false,
+      tls: false,
     },
     lastSeen: opts.lastSeen ?? opts.connectedSince,
     connectedSince: opts.connectedSince,