serverless-ircd 0.5.0 → 0.7.0

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

@@ -0,0 +1,327 @@
+/**
+ * Pure reducer for the IRCv3 `MONITOR` command.
+ *
+ * IRCv3 MONITOR spec <https://ircv3.net/specs/extensions/monitor-3.2.html>:
+ *
+ *   - `MONITOR + <nick>{,<nick>}` — add targets to the watchlist.
+ *   - `MONITOR - <nick>{,<nick>}` — remove targets from the watchlist.
+ *   - `MONITOR C`                 — clear the watchlist.
+ *   - `MONITOR L`                 — list the watchlist (`732` per line +
+ *                                   `733` terminator).
+ *   - `MONITOR S`                 — status: `730 RPL_MONONLINE` for the
+ *                                   online subset, `731 RPL_MONOFFLINE`
+ *                                   for the rest.
+ *
+ * Numerics:
+ *   - `730 RPL_MONONLINE`    `:<server> 730 <nick> :<online>{,<online>}`
+ *   - `731 RPL_MONOFFLINE`   `:<server> 731 <nick> :<offline>{,<offline>}`
+ *   - `732 RPL_MONLIST`      `:<server> 732 <nick> :<entry>`
+ *   - `733 RPL_ENDOFMONLIST` `:<server> 733 <nick> :End of MONITOR list`
+ *   - `734 ERR_MONLISTFULL`  `:<server> 734 <nick> <limit> :<rejected>{,<rejected>}`
+ *
+ * The watchlist lives on {@link ConnectionState.monitorList} (folded nicks,
+ * case-insensitive membership). The reducer resolves each requested nick
+ * against the supplied `online` map (folded-keyed → display spelling); the
+ * actor builds that map from the nick registry before invoking the reducer,
+ * mirroring the {@link isonReducer} pattern.
+ *
+ * Asynchronous `730`/`731` pushes on online/offline transitions are emitted
+ * by the actor layer (it watches `ReserveNick` / `ReleaseNick` effects
+ * against the watchlists); the pure reducer only handles the request/reply
+ * subcommands above.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, ReducerResult } from '../types.js';
+
+/** Wire name of the IRCv3 MONITOR capability. */
+export const MONITOR_CAP = 'monitor';
+
+/** Default monitor cap (max watchlist size) advertised via `MONITOR=<n>`. */
+export const DEFAULT_MONITOR_LIMIT = 30;
+
+/**
+ * Handles the IRCv3 `MONITOR` subcommands.
+ *
+ * Signature is bespoke (not {@link Reducer}) because the actor must resolve
+ * the requested nicks asynchronously before formatting — mirrors
+ * {@link isonReducer} / {@link whoisReducer}.
+ *
+ * @param online       Folded-keyed → display-spelling map of currently
+ *                     online nicks (built by the actor from the nick
+ *                     registry).
+ * @param maxMonitor   Server-wide cap on the per-connection watchlist size
+ *                     (advertised via `MONITOR=<n>` in `005`).
+ * @param msg          Parsed `MONITOR <sub> [<args>]` message.
+ * @param ctx          Per-invocation context.
+ */
+export function monitorReducer(
+  online: ReadonlyMap<string, string>,
+  maxMonitor: number,
+  msg: { params: readonly string[] },
+  ctx: Ctx,
+): ReducerResult<ConnectionState> {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const state = ctx.connection;
+  const nick = state.nick ?? '*';
+  const serverName = ctx.serverName;
+
+  const sub = (msg.params[0] ?? '').toUpperCase();
+
+  // No subcommand at all → 461 NEEDMOREPARAMS (the parser hands us an
+  // empty string when the sender wrote bare `MONITOR`). A non-empty but
+  // unknown subcommand (e.g. `MONITOR Z`) is also 461 with a different
+  // trailing string per the IRCv3 MONITOR dispatch table.
+  if (sub.length === 0) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(
+            serverName,
+            Numerics.ERR_NEEDMOREPARAMS,
+            nick,
+            'MONITOR',
+            'Not enough parameters',
+          ),
+        ]),
+      ],
+    };
+  }
+
+  switch (sub) {
+    case '+':
+      return handleAdd(state, online, maxMonitor, msg.params[1] ?? '', nick, serverName);
+    case '-':
+      return handleRemove(state, msg.params[1] ?? '');
+    case 'C':
+      return handleClear(state);
+    case 'L':
+      return handleList(state, nick, serverName);
+    case 'S':
+      return handleStatus(state, online, nick, serverName);
+    default:
+      return {
+        state,
+        effects: [
+          Effect.send(ctx.connId, [
+            numericLine(
+              serverName,
+              Numerics.ERR_NEEDMOREPARAMS,
+              nick,
+              'MONITOR',
+              'Unknown command',
+            ),
+          ]),
+        ],
+      };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand handlers
+// ---------------------------------------------------------------------------
+
+function handleAdd(
+  state: ConnectionState,
+  online: ReadonlyMap<string, string>,
+  maxMonitor: number,
+  targetList: string,
+  nick: string,
+  serverName: string,
+): ReducerResult<ConnectionState> {
+  if (targetList.length === 0) {
+    return {
+      state,
+      effects: [
+        Effect.send(state.id, [
+          numericLine(
+            serverName,
+            Numerics.ERR_NEEDMOREPARAMS,
+            nick,
+            'MONITOR',
+            'Not enough parameters',
+          ),
+        ]),
+      ],
+    };
+  }
+
+  const watchlist = ensureWatchlist(state);
+
+  const added: { folded: string; display: string }[] = [];
+  const rejected: string[] = [];
+  for (const requested of splitNicks(targetList)) {
+    const folded = requested.toLowerCase();
+    if (watchlist.has(folded)) continue; // already monitored; no output
+    if (watchlist.size >= maxMonitor) {
+      rejected.push(requested);
+      continue;
+    }
+    watchlist.add(folded);
+    // For the display spelling prefer the online map (canonical) and fall
+    // back to the requester spelling when the nick is offline.
+    const display = online.get(folded) ?? requested;
+    added.push({ folded, display });
+  }
+
+  const effects: EffectType[] = [];
+
+  const onlineDisplays = added.filter((a) => online.has(a.folded)).map((a) => a.display);
+  const offlineDisplays = added.filter((a) => !online.has(a.folded)).map((a) => a.display);
+
+  if (onlineDisplays.length > 0) {
+    effects.push(
+      Effect.send(state.id, [
+        monLine(Numerics.RPL_MONONLINE, serverName, nick, onlineDisplays.join(',')),
+      ]),
+    );
+  }
+  if (offlineDisplays.length > 0) {
+    effects.push(
+      Effect.send(state.id, [
+        monLine(Numerics.RPL_MONOFFLINE, serverName, nick, offlineDisplays.join(',')),
+      ]),
+    );
+  }
+  if (rejected.length > 0) {
+    effects.push(
+      Effect.send(state.id, [monListFullLine(serverName, nick, maxMonitor, rejected.join(','))]),
+    );
+  }
+
+  return { state, effects };
+}
+
+function handleRemove(state: ConnectionState, targetList: string): ReducerResult<ConnectionState> {
+  if (state.monitorList === undefined) return { state, effects: [] };
+  if (targetList.length === 0) return { state, effects: [] };
+  for (const requested of splitNicks(targetList)) {
+    state.monitorList.delete(requested.toLowerCase());
+  }
+  return { state, effects: [] };
+}
+
+function handleClear(state: ConnectionState): ReducerResult<ConnectionState> {
+  // Allocate the set on first clear so callers observe a stable post-state
+  // (size 0) regardless of whether the watchlist previously existed.
+  if (state.monitorList === undefined) {
+    state.monitorList = new Set<string>();
+  } else {
+    state.monitorList.clear();
+  }
+  return { state, effects: [] };
+}
+
+function handleList(
+  state: ConnectionState,
+  nick: string,
+  serverName: string,
+): ReducerResult<ConnectionState> {
+  const effects: EffectType[] = [];
+  if (state.monitorList !== undefined) {
+    for (const entry of state.monitorList) {
+      effects.push(Effect.send(state.id, [monLine(Numerics.RPL_MONLIST, serverName, nick, entry)]));
+    }
+  }
+  effects.push(
+    Effect.send(state.id, [
+      monLine(Numerics.RPL_ENDOFMONLIST, serverName, nick, 'End of MONITOR list'),
+    ]),
+  );
+  return { state, effects };
+}
+
+function handleStatus(
+  state: ConnectionState,
+  online: ReadonlyMap<string, string>,
+  nick: string,
+  serverName: string,
+): ReducerResult<ConnectionState> {
+  if (state.monitorList === undefined || state.monitorList.size === 0) {
+    return { state, effects: [] };
+  }
+  const onlineDisplays: string[] = [];
+  const offlineDisplays: string[] = [];
+  for (const folded of state.monitorList) {
+    const display = online.get(folded);
+    if (display !== undefined) {
+      onlineDisplays.push(display);
+    } else {
+      offlineDisplays.push(folded);
+    }
+  }
+  const effects: EffectType[] = [];
+  if (onlineDisplays.length > 0) {
+    effects.push(
+      Effect.send(state.id, [
+        monLine(Numerics.RPL_MONONLINE, serverName, nick, onlineDisplays.join(',')),
+      ]),
+    );
+  }
+  if (offlineDisplays.length > 0) {
+    effects.push(
+      Effect.send(state.id, [
+        monLine(Numerics.RPL_MONOFFLINE, serverName, nick, offlineDisplays.join(',')),
+      ]),
+    );
+  }
+  return { state, effects };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the connection's watchlist, lazily allocating it on first use.
+ * Existing persisted state migrates without a schema bump (the field stays
+ * optional; reducers that pre-date MONITOR never touch it).
+ */
+function ensureWatchlist(state: ConnectionState): Set<string> {
+  if (state.monitorList === undefined) {
+    state.monitorList = new Set<string>();
+  }
+  return state.monitorList;
+}
+
+/** Splits a comma-separated nick list, dropping empty entries. */
+function splitNicks(csv: string): string[] {
+  return csv
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/** `:<server> <code> <nick> :<trailing>` — used by 730/731/732/733. */
+function monLine(code: number, serverName: string, nick: string, trailing: string): RawLine {
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: `:${serverName} ${codeStr} ${nick} :${trailing}` };
+}
+
+/** `:<server> 734 <nick> <limit> :<rejected>` (ERR_MONLISTFULL). */
+function monListFullLine(
+  serverName: string,
+  nick: string,
+  limit: number,
+  rejected: string,
+): RawLine {
+  const codeStr = Numerics.ERR_MONLISTFULL.toString().padStart(3, '0');
+  return { text: `:${serverName} ${codeStr} ${nick} ${limit} :${rejected}` };
+}
+
+/** `:<server> <code> <nick> <cmd> :<trailing>` — used by 461-style errors. */
+function numericLine(
+  serverName: string,
+  code: number,
+  nick: string,
+  cmd: string,
+  trailing: string,
+): RawLine {
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: `:${serverName} ${codeStr} ${nick} ${cmd} :${trailing}` };
+}

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

@@ -0,0 +1,256 @@
+/**
+ * Pure reducer for IRCv3 `draft/multiline` (multi-line `BATCH`).
+ *
+ * Spec: https://ircv3.net/specs/extensions/multiline
+ *
+ * A cap-enabled client opens a multi-line batch with
+ *   `BATCH +id draft/multiline :<target>`
+ * followed by N `PRIVMSG`/`NOTICE` lines addressed to the same target, then
+ * closes it with `BATCH -id`. The server concatenates the per-line trailing
+ * parameters with `\n`, enforces the advertised byte budget, and fans the
+ * result out:
+ *
+ *   - to peers that also negotiated `draft/multiline`: a replayed
+ *     `BATCH +newid draft/multiline :<target>` containing the original
+ *     per-line `PRIVMSG`/`NOTICE` messages;
+ *   - to everyone else: a single joined `PRIVMSG`/`NOTICE` carrying the
+ *     `+draft/multiline` client tag so message-tags-aware (but not
+ *     multiline-aware) clients can recognise the joined form.
+ *
+ * This module owns the pure finalization step (concatenation, byte-budget
+ * enforcement, fanout construction). The stateful accumulation of the inner
+ * lines — buffering `PRIVMSG`/`NOTICE` between the `BATCH +` and `BATCH -`
+ * markers — lives in the actor layer, which calls
+ * {@link finalizeMultilineBatch} once the batch closes.
+ */
+
+import {
+  DEFAULT_MULTILINE_MAX_BYTES,
+  MULTILINE_CAP_NAME,
+  multilineCapValue,
+} from '../caps/capabilities.js';
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { hostmaskOf } from '../state/connection.js';
+import type { Ctx } from '../types.js';
+
+/**
+ * Wire name of the IRCv3 `draft/multiline` capability. Aliased from
+ * {@link MULTILINE_CAP_NAME} (the canonical home in the cap data table) for
+ * ergonomic use inside the reducer.
+ */
+export const MULTILINE_CAP = MULTILINE_CAP_NAME;
+
+export { DEFAULT_MULTILINE_MAX_BYTES, multilineCapValue };
+
+/**
+ * One accumulated inner line of a multi-line batch. The actor collects these
+ * as the client streams `PRIVMSG`/`NOTICE` lines between the batch markers,
+ * then hands the list to {@link finalizeMultilineBatch}. Only the trailing
+ * parameter (message text) is stored per line: the spec requires every inner
+ * line of a batch to share both the command and the target, so those live on
+ * the batch as a whole and are passed to the reducer separately.
+ */
+export interface MultilineEntry {
+  /** The trailing parameter (message text) of the inner line. */
+  readonly text: string;
+}
+
+/** Result of {@link finalizeMultilineBatch}: either accepted or rejected. */
+export type FinalizeMultilineResult =
+  | { readonly ok: true; readonly effects: EffectType[] }
+  | { readonly ok: false; readonly effects: EffectType[] };
+
+/**
+ * Concatenates the per-line texts of a multi-line batch with `\n`, per the
+ * IRCv3 spec. The joined value is what legacy (non-multiline) peers receive
+ * as the trailing parameter of the single relayed PRIVMSG/NOTICE.
+ */
+export function joinMultiline(entries: readonly MultilineEntry[]): string {
+  return entries.map((e) => e.text).join('\n');
+}
+
+/**
+ * Returns the byte length of the joined multi-line content as the byte budget
+ * sees it: the sum of every entry's UTF-8 byte length plus one byte per `\n`
+ * separator. This is the quantity compared against `draft/multiline=<max>`.
+ */
+export function multilineByteLength(entries: readonly MultilineEntry[]): number {
+  if (entries.length === 0) return 0;
+  let total = 0;
+  for (const entry of entries) {
+    total += utf8ByteLength(entry.text);
+  }
+  // `(n - 1)` separators join `n` entries.
+  total += entries.length - 1;
+  return total;
+}
+
+/** Shared `TextEncoder` for UTF-8 byte-length accounting (Web standard). */
+const TEXT_ENCODER = new TextEncoder();
+
+/** Returns the UTF-8 byte length of `s` (the wire encoding for IRC content). */
+function utf8ByteLength(s: string): number {
+  return TEXT_ENCODER.encode(s).length;
+}
+
+/** Resolves the sender's hostmask, falling back to nick then `?`. */
+function senderHostmask(conn: Ctx['connection']): string {
+  return hostmaskOf(conn) ?? conn.nick ?? '?';
+}
+
+/**
+ * Pre-built wire lines for a finalized multi-line batch, independent of the
+ * delivery mechanism (channel `Broadcast` vs. nick-target `Send`). The caller
+ * picks the appropriate variant per recipient based on the recipient's caps:
+ *
+ *   - `draft/multiline` + `batch` → `batchedReplay` (replayed BATCH frame).
+ *   - `message-tags` only        → `taggedJoined` (joined PRIVMSG with
+ *                                   `+draft/multiline` client tag).
+ *   - neither                     → `bareJoined` (joined PRIVMSG, no tag).
+ */
+export interface MultilineFanout {
+  /** Replayed `BATCH +id draft/multiline <target>` … `BATCH -id`. */
+  readonly batchedReplay: RawLine[];
+  /** Joined PRIVMSG/NOTICE carrying the `+draft/multiline` client tag. */
+  readonly taggedJoined: RawLine;
+  /** Joined PRIVMSG/NOTICE with no tag prefix (for legacy peers). */
+  readonly bareJoined: RawLine;
+  /** The `\n`-joined trailing parameter (for chathistory recording). */
+  readonly joined: string;
+}
+
+/**
+ * Builds the wire-line variants for a finalized multi-line batch. Pure: no
+ * context, no effects — just string construction. Shared by the channel
+ * broadcast path ({@link finalizeMultilineBatch}) and the actor-side nick
+ * target path so both emit identical wire forms.
+ *
+ * @param target   The batch target (channel name or nick).
+ * @param command  The inner-line command (`PRIVMSG` or `NOTICE`).
+ * @param entries  The accumulated inner lines in arrival order.
+ * @param hostmask The sender's `nick!user@host` (or fallback).
+ * @param batchId  A fresh batch reference id for the replayed BATCH frame.
+ */
+export function buildMultilineFanout(
+  target: string,
+  command: 'PRIVMSG' | 'NOTICE',
+  entries: readonly MultilineEntry[],
+  hostmask: string,
+  batchId: string,
+): MultilineFanout {
+  const joined = joinMultiline(entries);
+
+  const taggedJoined: RawLine = {
+    text: `@+draft/multiline :${hostmask} ${command} ${target} :${joined}`,
+  };
+  const bareJoined: RawLine = {
+    text: `:${hostmask} ${command} ${target} :${joined}`,
+  };
+
+  const inner: RawLine[] = entries.map(
+    (e) => ({ text: `:${hostmask} ${command} ${target} :${e.text}` }) as RawLine,
+  );
+  const batchedReplay: RawLine[] = [
+    { text: `BATCH +${batchId} draft/multiline ${target}` },
+    ...inner,
+    { text: `BATCH -${batchId}` },
+  ];
+
+  return { batchedReplay, taggedJoined, bareJoined, joined };
+}
+
+/**
+ * Finalizes a closed multi-line batch: enforces the byte budget and builds
+ * the fanout effects for both multiline-capable and legacy peers.
+ *
+ * On success the joined body is also recorded into the bound
+ * {@link MessageStore} (if any) as a single entry carrying the
+ * `+draft/multiline` client tag, so `CHATHISTORY` playback returns exactly
+ * one entry per batch.
+ *
+ * @param target    The batch's relay target (channel name). The actor
+ *                  validates that every inner line addressed this same target
+ *                  before calling.
+ * @param command   The inner-line command (`PRIVMSG` or `NOTICE`); the actor
+ *                  guarantees every inner line used the same one.
+ * @param entries   The accumulated inner lines in arrival order.
+ * @param maxBytes  The advertised byte budget (`draft/multiline=<n>`).
+ * @param ctx       Per-invocation context.
+ * @returns         `{ ok: true, effects }` on success; `{ ok: false, effects }`
+ *                  when the joined content exceeds `maxBytes` (the effects
+ *                  carry the `FAIL` rejection back to the sender).
+ */
+export function finalizeMultilineBatch(
+  target: string,
+  command: 'PRIVMSG' | 'NOTICE',
+  entries: readonly MultilineEntry[],
+  maxBytes: number,
+  ctx: Ctx,
+): FinalizeMultilineResult {
+  if (entries.length === 0) {
+    return { ok: true, effects: [] };
+  }
+
+  const bytes = multilineByteLength(entries);
+  if (bytes > maxBytes) {
+    return {
+      ok: false,
+      effects: [
+        Effect.send(ctx.connId, [
+          {
+            text: `:${ctx.serverName} FAIL BATCH MULTILINE_MAX_BYTES ${target} :Multi-line batch exceeds the ${maxBytes} byte limit`,
+          },
+        ]),
+      ],
+    };
+  }
+
+  const hostmask = senderHostmask(ctx.connection);
+  const batchId = ctx.ids.batchId();
+  const fanout = buildMultilineFanout(target, command, entries, hostmask, batchId);
+  const msgid = ctx.ids.nonce();
+  recordMultilineMessage(ctx, target, command, fanout.joined, msgid);
+
+  const effects: EffectType[] = [
+    Effect.broadcast(
+      target,
+      [fanout.taggedJoined],
+      ctx.connId,
+      MULTILINE_CAP,
+      fanout.batchedReplay,
+    ),
+  ];
+
+  return { ok: true, effects };
+}
+
+/**
+ * Records one finalized multi-line batch into the bound {@link MessageStore}
+ * (when present) as a single chathistory entry. The joined body is stored
+ * verbatim, the assigned `msgid` is the chathistory pivot, and the
+ * `+draft/multiline` client tag is attached so the chathistory replay can
+ * mark the line as originating from a multi-line batch. Shared by the
+ * channel broadcast path ({@link finalizeMultilineBatch}) and the actor-side
+ * nick-target path.
+ */
+export function recordMultilineMessage(
+  ctx: Ctx,
+  target: string,
+  command: 'PRIVMSG' | 'NOTICE',
+  joined: string,
+  msgid: string,
+): void {
+  if (ctx.messages === undefined) return;
+  ctx.messages.record({
+    msgid,
+    time: ctx.clock.now(),
+    chan: target.toLowerCase(),
+    command,
+    nick: (ctx.connection.nick as string) ?? '?',
+    user: ctx.connection.user as string,
+    host: ctx.connection.host as string,
+    text: joined,
+    clientTags: ['+draft/multiline'],
+  });
+}

package/packages/irc-core/src/commands/pre-away.ts

@@ -0,0 +1,112 @@
+/**
+ * Pure helpers for IRCv3 `draft/pre-away` (persistent away status).
+ *
+ * Spec (work-in-progress): https://github.com/ircv3/ircv3-specifications/pull/415
+ *
+ * Flow:
+ *   - The {@link awayReducer} sets/clears {@link ConnectionState.away} as
+ *     usual. When an {@link AwayStore} is bound AND the connection is
+ *     identified (has an `account`), the change is mirrored into the
+ *     per-`account` record via {@link persistAway} (on set) or
+ *     {@link clearPersistedAway} (on unset).
+ *   - On SASL identify, the actor calls {@link replayPersistedAway} so a
+ *     fresh connection's `away` is restored from the persisted reason and
+ *     `306 RPL_NOWAWAY` is emitted as if the client had sent
+ *     `AWAY :reason` themselves.
+ *
+ * Mirrors the {@link ReadMarkerStore} plumbing from the read-marker cap.
+ */
+
+import { PRE_AWAY_CAP_NAME } from '../caps/capabilities.js';
+import type { AwayStore } from '../ports.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx } from '../types.js';
+
+/**
+ * Wire name of the IRCv3 `draft/pre-away` capability. Aliased from
+ * {@link PRE_AWAY_CAP_NAME} (the canonical home in the cap data table)
+ * for ergonomic use inside the reducer.
+ */
+export const PRE_AWAY_CAP = PRE_AWAY_CAP_NAME;
+
+/**
+ * Records the away reason for the connection's account and stamps the
+ * in-memory {@link ConnectionState.away} so the current session tracks
+ * the new reason.
+ *
+ * Mirrors {@link persistReadMarker}: the store write is gated on both an
+ * {@link AwayStore} being bound AND the connection being identified.
+ * Unidentified connections still get the in-memory write so the session's
+ * own view (numerics, WHO/WHOIS) stays consistent.
+ */
+export function persistAway(ctx: Ctx, reason: string): void {
+  ctx.connection.away = reason;
+  const store = ctx.away;
+  const account = ctx.connection.account;
+  if (store !== undefined && account !== undefined) {
+    store.set(account, reason);
+  }
+}
+
+/**
+ * Clears the persisted away reason for the connection's account and the
+ * in-memory {@link ConnectionState.away}.
+ *
+ * Mirrors {@link persistAway}'s gating: a store write (delete) is gated
+ * on both a store being bound AND the connection being identified. The
+ * in-memory clear is unconditional so the session's own view stays
+ * consistent regardless of identification.
+ */
+export function clearPersistedAway(ctx: Ctx): void {
+  // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+  delete ctx.connection.away;
+  const store = ctx.away;
+  const account = ctx.connection.account;
+  if (store !== undefined && account !== undefined) {
+    store.clear(account);
+  }
+}
+
+/**
+ * Restores a fresh connection's {@link ConnectionState.away} from the
+ * persisted reason for `account`. Called at SASL identify so a reconnect
+ * resumes the user's away state.
+ *
+ * Existing in-memory `away` is preserved: a session may have already set
+ * a different reason, and the session's own value wins. Returns the
+ * persisted reason (or `undefined`) so the caller can emit the
+ * `306 RPL_NOWAWAY` numeric only when the replay actually applied a value.
+ */
+export function replayPersistedAway(
+  conn: ConnectionState,
+  store: AwayStore,
+  account: string,
+): string | undefined {
+  if (conn.away !== undefined) return undefined;
+  const reason = store.get(account);
+  if (reason === undefined) return undefined;
+  conn.away = reason;
+  return reason;
+}
+
+/**
+ * Builds the `306 RPL_NOWAWAY` line emitted after a successful away
+ * replay at identify time. Mirrors the line the {@link awayReducer}
+ * emits when a client sets `AWAY :reason` themselves, so the
+ * `draft/pre-away` replay is wire-identical to a direct AWAY set as far
+ * as the identified user is concerned.
+ *
+ * The companion `away-notify` broadcast (`:<hostmask> AWAY :<reason>` to
+ * cap-enabled peers in shared channels) is intentionally NOT emitted
+ * here: at SASL identify time the connection has not yet joined any
+ * channels, so the broadcast would have no audience. Peers learn the
+ * away state through the normal `AWAY` / `WHO` / `WHOIS` queries once
+ * the user joins.
+ */
+export function nowAwayLine(conn: ConnectionState, serverName: string): { text: string } {
+  const nick = conn.nick ?? '*';
+  return {
+    text: `:${serverName} ${Numerics.RPL_NOWAWAY.toString().padStart(3, '0')} ${nick} :You have been marked as being away`,
+  };
+}