serverless-ircd 0.5.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

@@ -53,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,
 
@@ -64,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

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

@@ -126,6 +126,14 @@ export function enforceLineLimit(
  * 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.
  *
@@ -142,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}` };
 }

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,