serverless-ircd 0.1.0

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

@@ -0,0 +1,20 @@
+/**
+ * @serverless-ircd/irc-core
+ *
+ * Platform-agnostic IRC protocol core: parser, serializer, numeric registry,
+ * state shapes, Effect taxonomy, reducer signature, and injected ports.
+ */
+export * from './protocol/index.js';
+export * from './state/index.js';
+export * from './caps/index.js';
+export * from './commands/index.js';
+export * from './effects.js';
+export * from './ports.js';
+export type {
+  BuildCtxOptions,
+  Ctx,
+  Reducer,
+  ReducerResult,
+  ServerConfig,
+} from './types.js';
+export { buildCtx } from './types.js';

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

@@ -0,0 +1,153 @@
+/**
+ * Injected ports for deterministic time and IDs.
+ *
+ * Reducers MUST NOT call `Date.now()`, `Math.random()`, or `crypto` directly:
+ * they take a {@link Clock} and {@link IdFactory} via {@link Ctx} so tests
+ * can pin the timeline and identity space (PLAN §8 determinism rules).
+ */
+
+/** Read-only wall clock, epoch milliseconds. */
+export interface Clock {
+  now(): number;
+}
+
+/** Real-system clock. Used in production; never in unit tests. */
+export const SystemClock: Clock = {
+  now(): number {
+    return Date.now();
+  },
+};
+
+/**
+ * Fake clock for tests. Deterministic, manually advanced.
+ *
+ *   const clock = new FakeClock(1000);
+ *   clock.advance(50);
+ *   clock.now() === 1050;
+ */
+export class FakeClock implements Clock {
+  private current: number;
+  constructor(start = 0) {
+    this.current = start;
+  }
+  now(): number {
+    return this.current;
+  }
+  advance(ms: number): void {
+    this.current += ms;
+  }
+  set(ms: number): void {
+    this.current = ms;
+  }
+}
+
+/** Factory for the various opaque identifiers reducers and dispatch emit. */
+export interface IdFactory {
+  /** `BATCH` reference id (IRCv3 batch). */
+  batchId(): string;
+  /** Per-message nonce / tag id (e.g. msgid). */
+  nonce(): string;
+  /** SASL / session-scoped id. */
+  sessionId(): string;
+}
+
+/**
+ * Production id factory. Generates UUIDv4-shaped strings without relying
+ * on `crypto` so the same code runs on Node 20, Cloudflare Workers, and
+ * Lambda without per-platform type wrangling. Uniqueness is statistical;
+ * for cryptographic IDs, adapters can supply their own {@link IdFactory}.
+ */
+export class UuidIdFactory implements IdFactory {
+  batchId(): string {
+    return uuidV4();
+  }
+  nonce(): string {
+    return uuidV4();
+  }
+  sessionId(): string {
+    return uuidV4();
+  }
+}
+
+// RFC 4122 v4 shape (random). Six fixed bits identify the version/variant;
+// the remaining 122 bits come from Math.random. Good enough for non-security
+// identifiers like BATCH ref ids and msgid tags.
+const HEX = '0123456789abcdef';
+function uuidV4(): string {
+  let out = '';
+  for (let i = 0; i < 36; i++) {
+    if (i === 8 || i === 13 || i === 18 || i === 23) {
+      out += '-';
+    } else if (i === 14) {
+      out += '4';
+    } else if (i === 19) {
+      out += HEX[(Math.random() * 4) | 0 | 0x8];
+    } else {
+      out += HEX[(Math.random() * 16) | 0];
+    }
+  }
+  return out;
+}
+
+/**
+ * Deterministic id factory for tests. A single counter is shared across
+ * methods so the output is fully predictable regardless of which method
+ * is called first.
+ */
+export class SequentialIdFactory implements IdFactory {
+  private counter = 0;
+  batchId(): string {
+    return `batch-${this.counter++}`;
+  }
+  nonce(): string {
+    return `nonce-${this.counter++}`;
+  }
+  sessionId(): string {
+    return `session-${this.counter++}`;
+  }
+}
+
+/**
+ * Port supplying the server's Message-of-the-Day text.
+ *
+ * The MOTD reducer is pure and synchronous; it cannot read
+ * KV / D1 / SecretsManager itself. Adapters pre-load the MOTD at startup
+ * (e.g. when a `ConnectionDO` wakes or a Lambda cold-starts) and inject a
+ * synchronously-readable {@link MotdProvider} into {@link Ctx}. This keeps
+ * the reducer free of cloud deps and deterministic for tests.
+ *
+ * Each call to {@link lines} must return a fresh snapshot of the MOTD as
+ * the reducer sees it: an empty array signals "no MOTD configured" and
+ * produces `422 ERR_NOMOTD`. Each returned string is one logical MOTD
+ * line; over-long lines are hard-wrapped by the reducer to fit the
+ * 512-byte wire limit.
+ */
+export interface MotdProvider {
+  /** Returns the MOTD lines (empty array = no MOTD configured). */
+  lines(): string[];
+}
+
+/**
+ * Reference in-memory {@link MotdProvider} backed by a mutable array.
+ *
+ * Used by adapters that pre-load the MOTD into memory (the local CLI, CF
+ * Worker with KV-cached MOTD, AWS Lambda with env/SSM-cached MOTD) and by
+ * tests. The backing array is mutable so a deployment can hot-reload the
+ * MOTD without rebuilding the provider.
+ */
+export class StaticMotdProvider implements MotdProvider {
+  private motdLines: string[];
+  constructor(lines: string[] = []) {
+    this.motdLines = [...lines];
+  }
+  lines(): string[] {
+    return this.motdLines;
+  }
+  /** Replaces the backing MOTD lines (used for hot-reload + tests). */
+  setLines(lines: string[]): void {
+    this.motdLines = [...lines];
+  }
+}
+
+/** Convenience: a {@link MotdProvider} that always reports "no MOTD". */
+export const EmptyMotdProvider: MotdProvider = new StaticMotdProvider([]);

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

@@ -0,0 +1,85 @@
+/**
+ * IRCv3 `batch` framing helper.
+ *
+ * Spec: https://ircv3.net/specs/extensions/batch-3.3
+ *
+ * `wrapBatch` is a pure transformation: given an ordered list of inner
+ * {@link RawLine}s and a batch reference id, it returns a new line list
+ * bounded by `BATCH +id type [args]` (start) and `BATCH -id` (end). The
+ * caller is responsible for allocating the id (via {@link IdFactory}) so
+ * the function remains deterministic and free of side effects.
+ *
+ * Nested batches are simply an outer `wrapBatch` call whose `lines`
+ * argument is the result of an inner `wrapBatch` call: the framing is
+ * composable by design. The caller MUST allocate distinct ids per batch
+ * (the spec forbids reuse of a ref id while the batch is open).
+ *
+ * Without the `batch` cap negotiated, the dispatch layer omits the
+ * wrapping entirely and the recipient observes the inner lines verbatim.
+ */
+
+import type { RawLine } from '../effects.js';
+
+/** Output of {@link wrapBatch}: the framing plus the inner body as one list. */
+export interface BatchFrame extends Array<RawLine> {
+  /** The reference id used in the `+id`/`-id` markers. */
+  readonly id: string;
+  /** The batch type token (e.g. `names`, `join`, `netjoin`). */
+  readonly type: string;
+  /** The `BATCH +id type [args]` start marker. */
+  readonly start: RawLine;
+  /** The original inner lines, unmodified. */
+  readonly body: RawLine[];
+  /** The `BATCH -id` end marker. */
+  readonly end: RawLine;
+}
+
+/**
+ * Wraps `lines` in IRCv3 `BATCH` framing.
+ *
+ * @param lines  Inner batch contents (in send order). Empty input returns an
+ *               empty array unchanged — callers should not emit empty batches.
+ * @param id     Batch reference id (allocate via `IdFactory.batchId()`).
+ * @param type   Batch type token (opaque to clients; known types like
+ *               `netjoin`, `netsplit`, `chghost`, `topic` are honoured by
+ *               clients that understand them).
+ * @param args   Optional trailing parameters appended after the type token
+ *               (e.g. the channel name for a `netjoin #foo` batch). Omitted
+ *               entirely when `undefined`.
+ * @returns      A new {@link BatchFrame} (array) suitable to be sent in order.
+ */
+export function wrapBatch(
+  lines: readonly RawLine[],
+  id: string,
+  type: string,
+  args?: string,
+): BatchFrame {
+  if (lines.length === 0) {
+    // Return an empty BatchFrame so the caller's array shape is stable.
+    // Empty batches are forbidden by the spec; we silently elide them.
+    const empty = [] as unknown as BatchFrame;
+    Object.defineProperties(empty, {
+      id: { value: id },
+      type: { value: type },
+      start: { value: { text: '' } },
+      body: { value: [] },
+      end: { value: { text: '' } },
+    });
+    return empty;
+  }
+
+  const startText = args !== undefined ? `BATCH +${id} ${type} ${args}` : `BATCH +${id} ${type}`;
+  const start: RawLine = { text: startText };
+  const end: RawLine = { text: `BATCH -${id}` };
+  const body = [...lines];
+
+  const out = [start, ...body, end] as unknown as BatchFrame;
+  Object.defineProperties(out, {
+    id: { value: id },
+    type: { value: type },
+    start: { value: start },
+    body: { value: body },
+    end: { value: end },
+  });
+  return out;
+}

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

@@ -0,0 +1,18 @@
+export type { IrcMessage, IrcSource } from './messages.js';
+export { IrcParseError, parse, unescapeTagValue } from './parser.js';
+export { escapeTagValue, serialize, serializeFrame } from './serializer.js';
+export {
+  MAX_LINE_BYTES,
+  applyServerTime,
+  enforceLineLimit,
+  filterClientTags,
+  formatServerTime,
+} from './outbound.js';
+export { wrapBatch, type BatchFrame } from './batch.js';
+export {
+  formatNumeric,
+  isNumericCommand,
+  type NumericCode,
+  numericToName,
+  Numerics,
+} from './numerics.js';

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

@@ -0,0 +1,36 @@
+/**
+ * Structured shapes for a parsed IRC message.
+ *
+ * These types are wire-format concepts only. Higher layers (command handlers,
+ * runtime effects) build on top of {@link IrcMessage} but add their own
+ * semantics.
+ */
+
+/**
+ * Message source ("prefix"). For a user it is `nick!user@host`; for a server
+ * it is just `name`. When `user`/`host` are absent the source is server-like.
+ */
+export interface IrcSource {
+  /** Nickname (for a user) or server name. */
+  name: string;
+  /** Ident/user name. Present only for user sources. */
+  user?: string;
+  /** Hostname. Present for user sources and some server sources. */
+  host?: string;
+}
+
+/**
+ * A single IRC protocol message, parsed from one wire line.
+ *
+ * - `tags` is always present (empty record when none were on the wire). A
+ *   valueless tag is represented as the empty string.
+ * - `command` is normalized: letters are upper-cased; numeric commands keep
+ *   their three-digit string form.
+ * - `params` includes the trailing parameter (if any) as its last element.
+ */
+export interface IrcMessage {
+  tags: Readonly<Record<string, string>>;
+  source?: IrcSource;
+  command: string;
+  params: string[];
+}

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

@@ -0,0 +1,155 @@
+/**
+ * IRC numeric reply/error codes (RFC 1459/2812 + common modern extensions).
+ *
+ * One canonical name per code (no aliases) so the reverse map is unambiguous.
+ * @see PLAN.md §3 for the supported subset.
+ */
+export const Numerics = {
+  // Welcome / registration
+  RPL_WELCOME: 1,
+  RPL_YOURHOST: 2,
+  RPL_CREATED: 3,
+  RPL_MYINFO: 4,
+  RPL_ISUPPORT: 5,
+  RPL_BOUNCE: 10,
+
+  // Capability / stats admin
+  RPL_ADMINME: 256,
+
+  // Away / userhost / ison
+  RPL_AWAY: 301,
+  RPL_USERHOST: 302,
+  RPL_ISON: 303,
+  RPL_UNAWAY: 305,
+  RPL_NOWAWAY: 306,
+
+  // WHOIS
+  RPL_WHOISUSER: 311,
+  RPL_WHOISSERVER: 312,
+  RPL_WHOISOPERATOR: 313,
+  RPL_WHOISIDLE: 317,
+  RPL_ENDOFWHOIS: 318,
+  RPL_WHOISCHANNELS: 319,
+  RPL_WHOISACCOUNT: 330,
+
+  // LIST
+  RPL_LISTSTART: 321,
+  RPL_LIST: 322,
+  RPL_LISTEND: 323,
+
+  // Channel mode / metadata
+  RPL_CHANNELMODEIS: 324,
+  RPL_CREATIONTIME: 329,
+  RPL_NOTOPIC: 331,
+  RPL_TOPIC: 332,
+  RPL_TOPICWHOTIME: 333,
+
+  // Invite / except lists
+  RPL_INVITING: 341,
+  RPL_INVITELIST: 346,
+  RPL_ENDOFINVITELIST: 347,
+  RPL_EXCEPTLIST: 348,
+  RPL_ENDOFEXCEPTLIST: 349,
+
+  // WHO / NAMES
+  RPL_WHOREPLY: 352,
+  RPL_ENDOFWHO: 315,
+  RPL_NAMREPLY: 353,
+  RPL_ENDOFNAMES: 366,
+
+  // Links / ban / whowas
+  RPL_LINKS: 364,
+  RPL_ENDOFLINKS: 365,
+  RPL_BANLIST: 367,
+  RPL_ENDOFBANLIST: 368,
+  RPL_ENDOFWHOWAS: 369,
+
+  // Info / MOTD
+  RPL_INFO: 371,
+  RPL_ENDOFINFO: 374,
+  RPL_MOTD: 372,
+  RPL_MOTDSTART: 375,
+  RPL_ENDOFMOTD: 376,
+
+  // Oper
+  RPL_YOUREOPER: 381,
+  RPL_REHASHING: 382,
+  RPL_YOURESERVICE: 383,
+  RPL_TIME: 391,
+
+  // Errors
+  ERR_NOSUCHNICK: 401,
+  ERR_NOSUCHSERVER: 402,
+  ERR_NOSUCHCHANNEL: 403,
+  ERR_CANNOTSENDTOCHAN: 404,
+  ERR_TOOMANYCHANNELS: 405,
+  ERR_WASNOSUCHNICK: 406,
+  ERR_TOOMANYTARGETS: 407,
+  ERR_NOSUCHSERVICE: 408,
+  ERR_INVALIDCAPCMD: 410,
+  ERR_NORECIPIENT: 411,
+  ERR_NOTEXTTOSEND: 412,
+  ERR_NOTOPLEVEL: 413,
+  ERR_WILDTOPLEVEL: 414,
+  ERR_UNKNOWNCOMMAND: 421,
+  ERR_NOMOTD: 422,
+  ERR_NOADMININFO: 423,
+  ERR_FILEERROR: 424,
+  ERR_NONICKNAMEGIVEN: 431,
+  ERR_ERRONEUSNICKNAME: 432,
+  ERR_NICKNAMEINUSE: 433,
+  ERR_NICKCOLLISION: 436,
+  ERR_UNAVAILRESOURCE: 437,
+  ERR_USERNOTINCHANNEL: 441,
+  ERR_NOTONCHANNEL: 442,
+  ERR_USERONCHANNEL: 443,
+  ERR_NOLOGIN: 444,
+  ERR_SUMMONDISABLED: 445,
+  ERR_USERSDISABLED: 446,
+  ERR_NOTREGISTERED: 451,
+  ERR_NEEDMOREPARAMS: 461,
+  ERR_ALREADYREGISTRED: 462,
+  ERR_NOPERMFORHOST: 463,
+  ERR_PASSWDMISMATCH: 464,
+  ERR_YOUREBANNEDCREEP: 465,
+  ERR_KEYSET: 467,
+  ERR_CHANNELISFULL: 471,
+  ERR_UNKNOWNMODE: 472,
+  ERR_INVITEONLYCHAN: 473,
+  ERR_BANNEDFROMCHAN: 474,
+  ERR_BADCHANNELKEY: 475,
+  ERR_BADCHANMASK: 476,
+  ERR_NOCHANMODES: 477,
+  ERR_BANLISTFULL: 478,
+  ERR_NOPRIVILEGES: 481,
+  ERR_CHANOPRIVSNEEDED: 482,
+  ERR_CANTKILLSERVER: 483,
+  ERR_NOOPERHOST: 491,
+  ERR_UMODEUNKNOWNFLAG: 501,
+  ERR_USERSDONTMATCH: 502,
+} as const;
+
+export type NumericCode = keyof typeof Numerics;
+
+/** Reverse lookup: numeric code -> canonical name. */
+export const numericToName: ReadonlyMap<number, NumericCode> = new Map(
+  (Object.entries(Numerics) as ReadonlyArray<[NumericCode, number]>).map(([name, code]) => [
+    code,
+    name,
+  ]),
+);
+
+const NUMERIC_COMMAND_RE = /^[0-9]{3}$/;
+
+/** A command token is a numeric iff it is exactly three digits. */
+export function isNumericCommand(command: string): boolean {
+  return NUMERIC_COMMAND_RE.test(command);
+}
+
+/**
+ * Formats a numeric by name as its three-digit wire representation.
+ * Zero-pads codes below 100.
+ */
+export function formatNumeric(name: NumericCode): string {
+  return Numerics[name].toString().padStart(3, '0');
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Per-recipient outbound transformations for IRCv3 capabilities.
+ *
+ * Reducers emit {@link RawLine} strings already formatted; they cannot know
+ * which caps each downstream recipient has negotiated. These pure helpers
+ * are called by the dispatch / runtime layer when delivering lines to a
+ * specific connection, applying (or omitting) the IRCv3 `server-time` and
+ * `message-tags` decorations according to that recipient's cap set.
+ *
+ * Spec references:
+ *   - IRCv3 Server-Time:  the time tag is `time` and uses ISO-8601 with
+ *     millisecond precision (`yyyy-MM-ddTHH:mm:ss.sssZ`).
+ *   - IRCv3 Message Tags: the 512-byte IRC line limit INCLUDES the tag
+ *     section for clients that negotiated `message-tags`. Legacy clients
+ *     never see tags so the budget applies to the body only.
+ */
+
+import type { RawLine } from '../effects.js';
+
+/**
+ * RFC 1459 §2.3: maximum IRC line length in bytes, including the trailing
+ * CR-LF. Adapters append `\r\n` after the lines produced here, so the
+ * budget for the {@link RawLine} text itself is 510 bytes. We retain the
+ * 512 symbolic constant because every other place that enforces the limit
+ * (CAP LS splitting, MOTD wrapping) does the same subtraction locally.
+ */
+export const MAX_LINE_BYTES = 512;
+
+/** Length of the trailing CR-LF the wire layer appends to each line. */
+const TRAILING_CRLF_LEN = 2;
+
+/**
+ * Formats epoch milliseconds as the IRCv3 Server-Time tag value:
+ * `yyyy-MM-ddTHH:mm:ss.sssZ` (ISO-8601, UTC, millisecond precision).
+ *
+ * Implemented via `Date#toISOString`, which is the canonical form required
+ * by the spec and already zero-pads every field.
+ */
+export function formatServerTime(now: number): string {
+  return new Date(now).toISOString();
+}
+
+/**
+ * Prepends the `@time=...` server-time tag to `line.text` iff the recipient
+ * negotiated the `server-time` cap. Returns the original line object
+ * unchanged otherwise.
+ *
+ * The returned {@link RawLine} is always a fresh object so callers never
+ * observe accidental mutation of the input.
+ *
+ * Note: when `line.text` already begins with a tag section (`@...`), the
+ * `time` tag is merged into the existing section so we never emit two `@`
+ * prefixes. This matches how the dispatch layer composes per-recipient
+ * decorations from multiple cap helpers.
+ */
+export function applyServerTime(line: RawLine, caps: ReadonlySet<string>, now: number): RawLine {
+  if (!caps.has('server-time')) return line;
+  const stamp = formatServerTime(now);
+  if (line.text.startsWith('@')) {
+    // Insert `time=<stamp>;` immediately after the leading `@`.
+    const merged = `@time=${stamp};${line.text.slice(1)}`;
+    return { text: merged };
+  }
+  return { text: `@time=${stamp} ${line.text}` };
+}
+
+/**
+ * Enforces the IRC 512-byte line limit on `line.text`.
+ *
+ * For recipients that negotiated `message-tags`, the tag section (the
+ * leading `@... ` prefix) is part of the wire budget and is preserved
+ * intact; truncation happens at the end of the trailing parameter only.
+ * For legacy recipients the entire `line.text` is the body and may be
+ * truncated from the right.
+ *
+ * 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;
+  if (line.text.length <= budget) return line;
+
+  const hasTags = caps.has('message-tags') && line.text.startsWith('@');
+  if (!hasTags) {
+    return { text: line.text.slice(0, budget) };
+  }
+
+  // Preserve the tag section verbatim; truncate only the post-tag body.
+  const spaceIdx = line.text.indexOf(' ');
+  if (spaceIdx === -1) {
+    // Malformed: a `@`-prefixed line with no space. Truncate from the right.
+    return { text: line.text.slice(0, budget) };
+  }
+  const tagSection = line.text.slice(0, spaceIdx + 1); // include trailing space
+  const body = line.text.slice(spaceIdx + 1);
+  const bodyBudget = budget - tagSection.length;
+  if (bodyBudget < 0) {
+    // Pathological: the tag section alone exceeds the budget. Drop the body
+    // entirely and truncate the tag section itself so the wire contract
+    // (≤ budget bytes) still holds.
+    return { text: line.text.slice(0, budget) };
+  }
+  return { text: `${tagSection}${body.slice(0, bodyBudget)}` };
+}
+
+/**
+ * Strips IRCv3 message-tags client-only tags (keys prefixed with `+`) from
+ * the line's tag section when the recipient did NOT negotiate the
+ * `message-tags` capability. Recipients that negotiated `message-tags`
+ * receive the line verbatim.
+ *
+ * Per the IRCv3 Message Tags spec, `+`-prefixed tags are client-only and
+ * MUST NOT be delivered to clients that lack the `message-tags` cap.
+ * Server-defined tags (no `+` prefix) are left in place — each is gated by
+ * its own capability (server-time, account-tag, …) applied elsewhere.
+ *
+ * When filtering removes every tag, the leading `@... ` section is dropped
+ * entirely so legacy clients never observe a bare tag prefix.
+ *
+ * The input {@link RawLine} is never mutated; the original object is
+ * returned unchanged when no client tag needs removing.
+ */
+export function filterClientTags(line: RawLine, caps: ReadonlySet<string>): RawLine {
+  if (caps.has('message-tags')) return line;
+  if (!line.text.startsWith('@')) return line;
+  const spaceIdx = line.text.indexOf(' ');
+  if (spaceIdx === -1) return line;
+
+  const tagSection = line.text.slice(1, spaceIdx);
+  const rest = line.text.slice(spaceIdx + 1);
+  const entries = tagSection.split(';');
+
+  const hasClientTag = entries.some((entry) => clientTagKey(entry).startsWith('+'));
+  if (!hasClientTag) return line;
+
+  const kept = entries.filter((entry) => !clientTagKey(entry).startsWith('+'));
+  if (kept.length === 0) return { text: rest };
+  return { text: `@${kept.join(';')} ${rest}` };
+}
+
+/** Returns the key portion of a raw `key` or `key=value` tag entry. */
+function clientTagKey(entry: string): string {
+  const eq = entry.indexOf('=');
+  return eq === -1 ? entry : entry.slice(0, eq);
+}