serverless-ircd 0.5.0 → 0.6.0

package/packages/irc-core/src/commands/whois.ts

@@ -134,6 +134,11 @@ export function whoisReducer(
       text: `:${ctx.serverName} ${Numerics.RPL_WHOISOPERATOR.toString().padStart(3, '0')} ${requesterNick} ${tNick} :is an IRC operator`,
     });
   }
+  if (target.userModes.tls) {
+    lines.push({
+      text: `:${ctx.serverName} ${Numerics.RPL_WHOISSECURE.toString().padStart(3, '0')} ${requesterNick} ${tNick} :is using a secure connection`,
+    });
+  }
   if (target.account !== undefined) {
     lines.push({
       text: `:${ctx.serverName} ${Numerics.RPL_WHOISACCOUNT.toString().padStart(3, '0')} ${requesterNick} ${tNick} ${target.account} :is logged in as`,

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

@@ -18,6 +18,7 @@
 
 import { z } from 'zod';
 import { BUILD_DATE } from './build-info.js';
+import { DEFAULT_MULTILINE_MAX_BYTES } from './caps/capabilities.js';
 
 /**
  * Schema for a single IRC operator credential.
@@ -61,6 +62,33 @@ export const CloakingConfigSchema = z.object({
   cloakedSuffix: z.string().min(1).optional(),
 });
 
+/**
+ * IRCv3 `sts` (Strict Transport Security) policy. When supplied, the
+ * server advertises an `sts` capability whose value tells compliant
+ * clients how long to pin TLS and which port to upgrade to on a
+ * plaintext connection. Omit entirely (the default) to disable STS.
+ *
+ * Spec: https://ircv3.net/specs/extensions/sts
+ */
+export const StsConfigSchema = z.object({
+  /**
+   * Pin duration in seconds. Defaults to 30 days at the cap-builder layer
+   * when omitted; supply an explicit value in production.
+   */
+  duration: z.number().int().positive(),
+  /**
+   * TLS listener port advertised on plaintext connections. The canonical
+   * IRC-over-TLS port is 6697 (RFC 7193). Defaults to 6697 at the
+   * cap-builder layer when omitted.
+   */
+  port: z.number().int().positive(),
+  /**
+   * Optional preload directive. When true the policy may be hard-coded
+   * into a client preload list (only advertised on plaintext connections).
+   */
+  preload: z.boolean().optional(),
+});
+
 /**
  * Per-IP connection-rate limit. Caps how many new connections a single
  * source IP may open within a sliding `windowMs` window before the
@@ -272,6 +300,43 @@ export const ServerConfigSchema = z.object({
    * lower per deployment. Only consulted when a MessageStore is bound.
    */
   chatHistoryPlaybackLimit: z.number().int().positive().default(50),
+
+  /**
+   * IRCv3 `sts` (Strict Transport Security) policy. Omit entirely (the
+   * default) to disable STS advertisement; supply `{ duration, port }`
+   * (plus optional `preload`) to advertise the cap and let compliant
+   * clients upgrade from plaintext to TLS and pin the secure listener.
+   */
+  sts: StsConfigSchema.optional(),
+
+  /**
+   * IRCv3 `draft/multiline` byte budget. Advertised as
+   * `draft/multiline=<n>` in `CAP LS` and enforced on every finalized
+   * multi-line batch. Defaults to the IRCv3-recommended 4096; raise or
+   * lower per deployment.
+   */
+  multilineMaxBytes: z.number().int().positive().default(DEFAULT_MULTILINE_MAX_BYTES),
+
+  /**
+   * Per-connection MONITOR watchlist ceiling, advertised as `MONITOR=<n>`
+   * in `005 RPL_ISUPPORT`. Omit to inherit the monitor reducer's built-in
+   * ceiling (DEFAULT_MONITOR_LIMIT, 30).
+   */
+  monitorLimit: z.number().int().positive().optional(),
+
+  /**
+   * Extended-ban prefix sigil for `EXTBAN=<prefix>,…` in
+   * `005 RPL_ISUPPORT`. Omit for the IRC-standard `~`.
+   */
+  extbanPrefix: z.string().min(1).optional(),
+
+  /**
+   * Enables IRC-services-derived ISUPPORT tokens (currently
+   * `ACCOUNTEXTBAN=a`). Set to true once a `ServicesStore` is bound; until
+   * then account-name extended bans are suppressed because unregistered
+   * nicks make them meaningless.
+   */
+  servicesEnabled: z.boolean().optional(),
 });
 
 /** Input type: what adapters supply (fields with defaults may be omitted). */
@@ -303,16 +368,6 @@ export function parseServerConfig(input: unknown): ParsedServerConfig {
   return result.data;
 }
 
-/**
- * Default server config: the result of parsing an empty input. Useful as a
- * known-good baseline for tests and for adapters that want to overlay
- * per-deployment overrides via object spread.
- */
-export const DEFAULT_SERVER_CONFIG: ParsedServerConfig = ServerConfigSchema.parse({
-  serverName: 'irc.example.com',
-  networkName: 'ServerlessIRCd',
-});
-
 /**
  * Resolves the effective server version for wire output: the configured
  * value when present, otherwise {@link DEFAULT_SERVER_VERSION}. Used by the

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

@@ -43,6 +43,18 @@ export interface BroadcastEffect {
   except?: ConnId;
   cap?: string;
   capLines?: RawLine[];
+  /**
+   * OR-semantics cap list: the recipient receives `lines` iff they
+   * negotiated ANY of the listed caps. Used by capabilities whose delivery
+   * rule is the union of two caps — e.g. `draft/typing` TAGMSGs reach
+   * peers that announced `draft/typing` OR `message-tags` (the latter
+   * because every TAGMSG goes to message-tags peers regardless of tag).
+   *
+   * Mutually exclusive with {@link cap}: set one or the other, not both.
+   * When neither is set, dispatch takes the runtime's bulk broadcast fast
+   * path.
+   */
+  caps?: readonly string[];
 }
 
 export interface DisconnectEffect {
@@ -150,11 +162,13 @@ export const Effect = {
     except?: ConnId,
     cap?: string,
     capLines?: RawLine[],
+    caps?: readonly string[],
   ): Effect {
     const e: BroadcastEffect = { tag: 'Broadcast', chan, lines };
     if (except !== undefined) e.except = except;
     if (cap !== undefined) e.cap = cap;
     if (capLines !== undefined) e.capLines = capLines;
+    if (caps !== undefined) e.caps = caps;
     return e;
   },
   disconnect(conn: ConnId, reason?: string): Effect {

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

@@ -340,6 +340,13 @@ export type StoredCommand = 'PRIVMSG' | 'NOTICE' | 'TAGMSG';
  * is reconstructed by the reducer from the authoritative {@link ChannelState}
  * when building replay lines. `time` is epoch milliseconds from the injected
  * {@link Clock}; `msgid` is a fresh nonce from {@link IdFactory}.
+ *
+ * `clientTags` carries optional IRCv3 message-tags client-only entries
+ * (keys prefixed with `+`) that the recording reducer wants preserved on
+ * replay — e.g. `+draft/multiline` so a chathistory client can recognise
+ * that a stored PRIVMSG originated from a multi-line batch. Omitted (or
+ * empty) for normal PRIVMSG/NOTICE/TAGMSG. The chathistory replay weaves
+ * these into the `@time=…;msgid=…` tag section verbatim.
  */
 export interface StoredMessage {
   msgid: string;
@@ -350,6 +357,7 @@ export interface StoredMessage {
   user?: string;
   host?: string;
   text: string;
+  readonly clientTags?: readonly string[];
 }
 
 /** Subcommands of `CHATHISTORY` that select a slice of the backlog. */
@@ -570,6 +578,180 @@ function tail<T>(arr: readonly T[], n: number): T[] {
   return arr.slice(start);
 }
 
+// ============================================================================
+// Read-marker persistence (IRCv3 draft/read-marker)
+// ============================================================================
+
+/**
+ * One persisted last-read marker, keyed per `(account, channel)`.
+ *
+ * `channel` is the lowercased channel name (the storage key); `msgid` is the
+ * msgid of the most recent message the account has read in that channel.
+ * Returned by {@link ReadMarkerStore.forAccount} when seeding a fresh
+ * connection at identify time.
+ */
+export interface ReadMarkerEntry {
+  /** Canonical account name (as recorded by SASL). */
+  account: string;
+  /** Lowercased channel name (rfc1459-folded storage key). */
+  channel: string;
+  /** Msgid of the most recent read message in this channel. */
+  msgid: string;
+}
+
+/**
+ * Persistence port for IRCv3 `draft/read-marker`.
+ *
+ * The chathistory command keeps a per-`(connection, channel)`
+ * last-read marker in {@link ConnectionState.lastReadMarkers}; this port
+ * promotes that marker to a per-`(account, channel)` record so it survives
+ * reconnects and is shared across an account's connections.
+ *
+ * Mirrors the {@link MessageStore} / {@link AccountStore} pattern: the port
+ * is **synchronous** (reducers must stay pure and free of IO) and injected
+ * via {@link Ctx}. Adapters that need async storage (D1, DynamoDB) pre-load
+ * the relevant slice into a synchronously-readable store; the in-memory
+ * reference implementation ({@link InMemoryReadMarkerStore}) ships here.
+ *
+ * Account and channel keys are both case-folded (rfc1459) so lookups are
+ * case-insensitive, matching the rest of the server's comparison semantics.
+ */
+export interface ReadMarkerStore {
+  /**
+   * Returns the stored last-read msgid for `(account, channel)`, or
+   * `undefined` when no marker has been recorded.
+   */
+  get(account: string, channel: string): string | undefined;
+  /**
+   * Records (or replaces) the last-read msgid for `(account, channel)`.
+   * Callers MUST only move the marker forward (towards newer messages);
+   * the store itself does not order msgids, it stores the latest value set.
+   */
+  set(account: string, channel: string, msgid: string): void;
+  /**
+   * Enumerates every recorded marker for `account`. Used at identify time to
+   * seed a fresh connection's {@link ConnectionState.lastReadMarkers} so a
+   * reconnect restores the user's read position across all their channels.
+   */
+  forAccount(account: string): ReadonlyArray<ReadMarkerEntry>;
+}
+
+/**
+ * Reference in-memory {@link ReadMarkerStore} backed by a
+ * `foldedAccount → (foldedChannel → msgid)` nested map.
+ *
+ * Used by the local CLI, integration tests, and any deployment that has not
+ * bound a distributed backend. Cloud adapters replace this with a D1 /
+ * DynamoDB-backed implementation against the same surface.
+ *
+ * Both keys are folded via {@link caseFold} (`rfc1459`) so lookups are
+ * case-insensitive; the returned {@link ReadMarkerEntry.channel} carries the
+ * folded spelling and {@link ReadMarkerEntry.account} the canonical name
+ * passed to {@link ReadMarkerStore.forAccount}.
+ */
+export class InMemoryReadMarkerStore implements ReadMarkerStore {
+  private readonly byAccount = new Map<string, Map<string, string>>();
+
+  get(account: string, channel: string): string | undefined {
+    return this.byAccount.get(folded(account))?.get(folded(channel));
+  }
+
+  set(account: string, channel: string, msgid: string): void {
+    const acct = folded(account);
+    let chanMap = this.byAccount.get(acct);
+    if (chanMap === undefined) {
+      chanMap = new Map<string, string>();
+      this.byAccount.set(acct, chanMap);
+    }
+    chanMap.set(folded(channel), msgid);
+  }
+
+  forAccount(account: string): ReadonlyArray<ReadMarkerEntry> {
+    const chanMap = this.byAccount.get(folded(account));
+    if (chanMap === undefined) return [];
+    const out: ReadMarkerEntry[] = [];
+    for (const [channel, msgid] of chanMap) {
+      out.push({ account, channel, msgid });
+    }
+    return out;
+  }
+}
+
+/** rfc1459 case-fold used for both account and channel keys. */
+function folded(value: string): string {
+  return caseFold('rfc1459', value);
+}
+
+// ============================================================================
+// Away-status persistence (IRCv3 draft/pre-away)
+// ============================================================================
+
+/**
+ * Persistence port for IRCv3 `draft/pre-away`.
+ *
+ * The base `AWAY` reducer keeps the away reason in
+ * {@link ConnectionState.away} for the lifetime of a single connection; this
+ * port promotes that reason to a per-`account` record so it survives
+ * reconnects and is shared across an account's connections.
+ *
+ * Mirrors the {@link ReadMarkerStore} pattern: the port is
+ * **synchronous** (reducers must stay pure and free of IO) and injected
+ * via {@link Ctx}. Adapters that need async storage (D1, DynamoDB) pre-load
+ * the relevant slice into a synchronously-readable store; the in-memory
+ * reference implementation ({@link InMemoryAwayStore}) ships here.
+ *
+ * The account key is case-folded (rfc1459) so lookups are
+ * case-insensitive, matching the rest of the server's comparison
+ * semantics. The unified services `UserStore` should fold this store in
+ * when it lands.
+ */
+export interface AwayStore {
+  /**
+   * Returns the stored away reason for `account`, or `undefined` when no
+   * reason has been recorded.
+   */
+  get(account: string): string | undefined;
+  /**
+   * Records (or replaces) the away reason for `account`. An empty string
+   * is permitted at the store layer (callers avoid it via
+   * {@link clearAway}).
+   */
+  set(account: string, reason: string): void;
+  /**
+   * Removes the stored away reason for `account`. Used when the user
+   * unsets `AWAY` so the next reconnect does not auto-mark them away.
+   */
+  clear(account: string): void;
+}
+
+/**
+ * Reference in-memory {@link AwayStore} backed by a
+ * `foldedAccount → reason` map.
+ *
+ * Used by the local CLI, integration tests, and any deployment that has
+ * not bound a distributed backend. Cloud adapters replace this with a D1
+ * / DynamoDB-backed implementation against the same surface.
+ *
+ * The account key is folded via {@link caseFold} (`rfc1459`) so lookups
+ * are case-insensitive, matching the IRC nick-comparison semantics
+ * advertised via `005 RPL_ISUPPORT CASEMAPPING=rfc1459`.
+ */
+export class InMemoryAwayStore implements AwayStore {
+  private readonly byAccount = new Map<string, string>();
+
+  get(account: string): string | undefined {
+    return this.byAccount.get(folded(account));
+  }
+
+  set(account: string, reason: string): void {
+    this.byAccount.set(folded(account), reason);
+  }
+
+  clear(account: string): void {
+    this.byAccount.delete(folded(account));
+  }
+}
+
 // ============================================================================
 // Nick history (WHOWAS)
 // ============================================================================
@@ -672,6 +854,213 @@ export class InMemoryNickHistoryStore implements NickHistoryStore {
   }
 }
 
+// ============================================================================
+// MONITOR subscription registry (IRCv3 MONITOR)
+// ============================================================================
+
+/**
+ * One async push notification the {@link MonitorStore} requests from the
+ * actor layer. The actor turns each push into one or more `Send` effects
+ * addressed to the watcher's connection.
+ *
+ *   - `online` — the nick came online; the watcher should receive a
+ *     `730 RPL_MONONLINE` line naming `display`.
+ *   - `offline` — the nick went offline; the watcher should receive a
+ *     `731 RPL_MONOFFLINE` line naming `display`.
+ */
+export interface MonitorPush {
+  /** Watcher's connection id. */
+  connId: string;
+  /** Display spelling of the nick that changed state. */
+  display: string;
+  /** New state. */
+  status: 'online' | 'offline';
+}
+
+/**
+ * Subscription registry for the IRCv3 `MONITOR` command.
+ *
+ * The watchlist itself lives on {@link ConnectionState.monitorList} (so it
+ * persists across actor re-bindings); this port owns the **reverse index**
+ * (nick → set of watcher connIds) and the **online set** the actor consults
+ * when synchronously resolving `MONITOR +` / `MONITOR S`.
+ *
+ * Mirrors the {@link MessageStore} / {@link AccountStore} pattern: the port
+ * is **synchronous** (reducers must stay pure and free of IO). The actor
+ * layer drains pending pushes after each command via {@link drainPushes};
+ * adapters that need to fan notifications out across processes (CF
+ * ConnectionDO sharding, AWS WebSocket fanout) replace
+ * {@link InMemoryMonitorStore} with their own implementation against the
+ * same surface.
+ *
+ * Lifecycle:
+ *   - On `MONITOR +`, the actor calls {@link sync} with the before/after
+ *     watchlist snapshots; the store records each newly-added nick →
+ *     watcher mapping.
+ *   - On `MONITOR -` / `C`, {@link sync} drops the removed mappings.
+ *   - On `NICK` (reserve/change) the actor calls {@link onNickOnline} for
+ *     each newly-reserved nick; the store appends a {@link MonitorPush}
+ *     for every watcher of that nick.
+ *   - On `QUIT` (or any release) the actor calls {@link onNickOffline};
+ *     same flow with a `731` push.
+ *   - On connection teardown, the actor calls {@link unsubscribe} so the
+ *     reverse index does not leak.
+ */
+export interface MonitorStore {
+  /**
+   * Reconciles the reverse index for `connId` against a watchlist delta.
+   * `before` is the watchlist at the start of the command (folded nicks);
+   * `after` is the watchlist after the reducer ran. The store adds
+   * mappings for entries in `after` not in `before`, and removes mappings
+   * for entries in `before` not in `after`.
+   */
+  sync(connId: string, before: ReadonlySet<string>, after: ReadonlySet<string>): void;
+  /**
+   * Removes every subscription for `connId`. Safe to call when the
+   * connection had no subscriptions. Idempotent.
+   */
+  unsubscribe(connId: string): void;
+  /**
+   * Records `nick` as online and enqueues a `730 RPL_MONONLINE` push to
+   * every watcher currently subscribed to that nick. `display` is the
+   * registered spelling the wire line should carry.
+   *
+   * Idempotent: a no-op when `nick` was already online (the second call
+   * enqueues nothing — prevents double-pushes on a `ReserveNick` for an
+   * already-reserved nick the runtime allowed through as a same-conn
+   * re-reserve).
+   */
+  onNickOnline(display: string): void;
+  /**
+   * Records `nick` as offline and enqueues a `731 RPL_MONOFFLINE` push to
+   * every watcher currently subscribed to that nick. Idempotent in the
+   * same way {@link onNickOnline} is.
+   */
+  onNickOffline(display: string): void;
+  /**
+   * Returns every display spelling currently marked online, in insertion
+   * order. Used by the actor's synchronous `MONITOR +` / `MONITOR S`
+   * resolution so the reducer can emit `730`/`731` lines without an
+   * O(N) `lookupNick` per requested nick.
+   */
+  onlineNicks(): string[];
+  /**
+   * Drains the queue of pending {@link MonitorPush}es the store has
+   * enqueued since the last drain. The actor calls this once per
+   * dispatched batch (after `NICK`/`QUIT` reducers release/reserve
+   * nicks) and turns each push into a `Send` effect for the watcher.
+   */
+  drainPushes(): MonitorPush[];
+}
+
+/**
+ * Reference in-memory {@link MonitorStore} used by the local CLI, the
+ * integration tests, and any deployment that has not bound a distributed
+ * backend.
+ *
+ * Backed by three plain `Map`s:
+ *   - `watchers`     connId → set of folded watched nicks.
+ *   - `reverse`      folded nick → set of watcher connIds.
+ *   - `online`       folded nick → display spelling (insertion-ordered).
+ *
+ * Plus a `pending` array of {@link MonitorPush} entries drained by the
+ * actor after each dispatched batch.
+ */
+export class InMemoryMonitorStore implements MonitorStore {
+  private readonly watchers = new Map<string, Set<string>>();
+  private readonly reverse = new Map<string, Set<string>>();
+  private readonly online = new Map<string, string>();
+  private readonly pending: MonitorPush[] = [];
+
+  sync(connId: string, before: ReadonlySet<string>, after: ReadonlySet<string>): void {
+    // Compute the delta without mutating `before`/`after` (callers pass
+    // references to their own state).
+    const added: string[] = [];
+    const removed: string[] = [];
+    for (const n of after) if (!before.has(n)) added.push(n);
+    for (const n of before) if (!after.has(n)) removed.push(n);
+
+    if (added.length === 0 && removed.length === 0) return;
+
+    // Look up (or allocate) the watcher's per-connection set; cleared from
+    // `watchers` when it ends up empty so unsubscribed connections do not
+    // leak in the forward map.
+    let wSet = this.watchers.get(connId);
+    if (wSet === undefined) {
+      wSet = new Set<string>();
+      this.watchers.set(connId, wSet);
+    }
+
+    for (const folded of added) {
+      wSet.add(folded);
+      let watchers = this.reverse.get(folded);
+      if (watchers === undefined) {
+        watchers = new Set<string>();
+        this.reverse.set(folded, watchers);
+      }
+      watchers.add(connId);
+    }
+    for (const folded of removed) {
+      wSet.delete(folded);
+      // The forward (`watchers`) and reverse indexes are kept in lockstep
+      // by sync, so any folded nick present in `before` has a
+      // corresponding reverse entry. The non-null assertion encodes that
+      // invariant; the alternative `if (watchers === undefined) return`
+      // would introduce an unreachable branch that violates the project's
+      // 100% branch-coverage threshold.
+      // biome-ignore lint/style/noNonNullAssertion: invariant — see above.
+      const watchers = this.reverse.get(folded)!;
+      watchers.delete(connId);
+      if (watchers.size === 0) this.reverse.delete(folded);
+    }
+    if (wSet.size === 0) this.watchers.delete(connId);
+  }
+
+  unsubscribe(connId: string): void {
+    const wSet = this.watchers.get(connId);
+    if (wSet === undefined) return;
+    for (const folded of wSet) {
+      // Same invariant as in `sync`: the forward/reverse indexes are kept
+      // in lockstep, so every folded nick in `wSet` has a reverse entry.
+      // biome-ignore lint/style/noNonNullAssertion: invariant — see above.
+      const watchers = this.reverse.get(folded)!;
+      watchers.delete(connId);
+      if (watchers.size === 0) this.reverse.delete(folded);
+    }
+    this.watchers.delete(connId);
+  }
+
+  onNickOnline(display: string): void {
+    const folded = display.toLowerCase();
+    if (this.online.has(folded)) return;
+    this.online.set(folded, display);
+    const watchers = this.reverse.get(folded);
+    if (watchers === undefined) return;
+    for (const connId of watchers) {
+      this.pending.push({ connId, display, status: 'online' });
+    }
+  }
+
+  onNickOffline(display: string): void {
+    const folded = display.toLowerCase();
+    if (!this.online.has(folded)) return;
+    this.online.delete(folded);
+    const watchers = this.reverse.get(folded);
+    if (watchers === undefined) return;
+    for (const connId of watchers) {
+      this.pending.push({ connId, display, status: 'offline' });
+    }
+  }
+
+  onlineNicks(): string[] {
+    return Array.from(this.online.values());
+  }
+
+  drainPushes(): MonitorPush[] {
+    return this.pending.splice(0);
+  }
+}
+
 // ============================================================================
 // Network statistics (LUSERS / STATS)
 // ============================================================================

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

@@ -9,6 +9,14 @@ export {
   formatServerTime,
 } from './outbound.js';
 export { wrapBatch, type BatchFrame } from './batch.js';
+export {
+  LABELED_RESPONSE_CAP_NAME,
+  LABEL_TAG,
+  applyLabelToEffects,
+  type LabelApplyOptions,
+  extractLabel,
+  wrapLabeledResponse,
+} from './labeled-response.js';
 export { decodeBase64, encodeBase64 } from './base64.js';
 export {
   formatNumeric,
@@ -17,3 +25,9 @@ export {
   numericToName,
   Numerics,
 } from './numerics.js';
+export {
+  type ReplyKind,
+  type StandardReplyMapping,
+  numericToStandardReply,
+  toStandardReply,
+} from './standard-replies.js';