serverless-ircd 0.7.0 → 0.9.0

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

@@ -0,0 +1,522 @@
+/**
+ * Pure reducer for the HostServ services pseudo-client.
+ *
+ * HostServ is invoked via `PRIVMSG HostServ :<command>`. The actor routes
+ * any `PRIVMSG` whose target matches {@link HOSTSERV_NICK}
+ * (case-insensitive) to {@link hostservReducer} instead of the normal
+ * user-target reducer.
+ *
+ * Supported subcommands:
+ *   - `ON` — applies the per-account vhost (set via REQUEST or oper SET)
+ *     to the connection's visible host, persists the prior host so OFF can
+ *     restore it, and emits `CHGHOST` (IRCv3 `chghost`) to every peer the
+ *     user shares a channel with. Requires the connection to be identified.
+ *   - `OFF` — restores the real (pre-vhost) host and emits `CHGHOST` so
+ *     peers see the revert. Requires identification.
+ *   - `REQUEST <vhost>` — proposes a vhost for the account. Behaviour
+ *     depends on {@link ServerConfig.hostservAutoApproveVhosts}: when the
+ *     knob is on (the default) the vhost is recorded against the account
+ *     immediately (legacy auto-approve); when the knob is off the request
+ *     is queued for oper review via {@link ServicesStore.requestVhost}
+ *     and the requester is told it is pending. Requires identification.
+ *   - `SET <account> <vhost>` — oper-only. Records (or, with the literal
+ *     `*` argument, clears) the vhost for `account` directly without
+ *     going through REQUEST. The target account must be a registered nick.
+ *   - `APPROVE <account>` (alias `ACTIVATE`) — oper-only. Activates the
+ *     pending vhost request recorded via queue-mode REQUEST, replying to
+ *     the oper and best-effort NOTICE-ing the requester when online.
+ *   - `REJECT <account>` — oper-only. Drops the pending vhost request,
+ *     replying to the oper and best-effort NOTICE-ing the requester when
+ *     online.
+ *   - `LIST` — oper-only. Enumerates every pending vhost request.
+ *
+ * The reducer is a pure `Reducer<ConnectionState>`: all side effects are
+ * emitted as {@link Effect}s. The CHGHOST fanout reuses the
+ * {@link emitChghost} broadcast helper so the wire shape stays consistent
+ * with SETNAME and any other user/host mutation.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { ServicesStore } from '../ports.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer } from '../types.js';
+import { emitChghost } from './chghost.js';
+
+/** Canonical HostServ pseudo-client nick. */
+export const HOSTSERV_NICK = 'HostServ';
+
+/** Services hostmask fragment used by every services pseudo-client. */
+const SERVICES_HOST = 'services';
+
+/** Sentinel value used by `SET <account> *` to clear a recorded vhost. */
+const CLEAR_VHOST_SENTINEL = '*';
+
+/**
+ * Grammar for a HostServ vhost. Permits the dotted-label form used by
+ * mainstream IRC services (each label bounded by alphanumerics, hyphens
+ * permitted in the interior). Rejects whitespace, IRC protocol metachars,
+ * and empty labels. Capped at 63 characters per label (DNS label limit)
+ * and a total of 253 characters (DNS hostname limit).
+ */
+const VHOST_RE =
+  /^(?=.{1,253}$)[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/u;
+
+/** Returns true iff `vhost` is a syntactically valid HostServ vhost. */
+function isValidVhost(vhost: string): boolean {
+  return VHOST_RE.test(vhost);
+}
+
+/**
+ * Reducer for `PRIVMSG HostServ :<subcommand> <args…>`.
+ * Authority: the invoking connection's {@link ConnectionState}.
+ */
+export const hostservReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  if (ctx.services === undefined) {
+    effects.push(notice(state, 'Services are not available on this server.'));
+    return { state, effects };
+  }
+
+  const body = msg.params[1] ?? '';
+  const tokens = body.split(/\s+/u).filter((t) => t.length > 0);
+  if (tokens.length === 0) {
+    effects.push(helpNotice(state));
+    return { state, effects };
+  }
+
+  const sub = tokens[0]?.toUpperCase();
+  const args = tokens.slice(1);
+
+  switch (sub) {
+    case 'ON':
+      return handleOn(state, ctx, effects);
+    case 'OFF':
+      return handleOff(state, ctx, effects);
+    case 'REQUEST':
+      return handleRequest(state, args, ctx, effects);
+    case 'SET':
+      return handleSet(state, args, ctx, effects);
+    case 'APPROVE':
+    case 'ACTIVATE':
+      return handleApprove(state, args, ctx, effects);
+    case 'REJECT':
+      return handleReject(state, args, ctx, effects);
+    case 'LIST':
+      return handleList(state, ctx, effects);
+    default:
+      effects.push(unknownNotice(state));
+      return { state, effects };
+  }
+};
+
+// ============================================================================
+// ON
+// ============================================================================
+
+/**
+ * Handles `ON`. Applies the connection's per-account vhost (looked up from
+ * the bound {@link ServicesStore}) to {@link ConnectionState.host}, records
+ * the prior host on {@link ConnectionState.preVhostHost} so OFF can restore
+ * it, and broadcasts `CHGHOST` to every shared-channel peer.
+ */
+function handleOn(
+  state: ConnectionState,
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  if (state.account === undefined) {
+    effects.push(notice(state, 'You must identify before enabling a vhost.'));
+    return { state, effects };
+  }
+
+  if (state.vhostActive === true) {
+    effects.push(notice(state, 'Your vhost is already active.'));
+    return { state, effects };
+  }
+
+  const services = ctx.services as ServicesStore;
+  const vhost = services.getVhost(state.account);
+  if (vhost === undefined) {
+    effects.push(notice(state, 'No vhost is assigned to your account.'));
+    return { state, effects };
+  }
+
+  applyVhost(state, vhost, effects);
+  effects.push(notice(state, 'Your vhost is now active.'));
+  return { state, effects };
+}
+
+// ============================================================================
+// OFF
+// ============================================================================
+
+/**
+ * Handles `OFF`. Restores the real (pre-vhost) host from
+ * {@link ConnectionState.preVhostHost} and broadcasts `CHGHOST`.
+ */
+function handleOff(
+  state: ConnectionState,
+  _ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  if (state.account === undefined) {
+    effects.push(notice(state, 'You must identify before changing your vhost.'));
+    return { state, effects };
+  }
+
+  if (state.vhostActive !== true) {
+    effects.push(notice(state, 'No vhost is currently active.'));
+    return { state, effects };
+  }
+
+  restoreRealHost(state, effects);
+  effects.push(notice(state, 'Your vhost has been disabled.'));
+  return { state, effects };
+}
+
+// ============================================================================
+// REQUEST
+// ============================================================================
+
+/**
+ * Handles `REQUEST <vhost>`. Behaviour is selected by
+ * {@link ServerConfig.hostservAutoApproveVhosts}:
+ *   - `true` (auto-approve) — the vhost is recorded against the account
+ *     immediately (the path that shipped before the oper queue landed). The
+ *     user is notified that the vhost has been requested and approved.
+ *   - `false` or omitted (the default — queue mode) — the request is
+ *     queued for oper review via {@link ServicesStore.requestVhost}; the
+ *     vhost is NOT activated and no `CHGHOST` is emitted. The user is
+ *     notified that the request is pending oper approval.
+ *
+ * Identified-only — otherwise a guest could plant a vhost (or a pending
+ * request) against a registered account they do not own.
+ */
+function handleRequest(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  if (state.account === undefined) {
+    effects.push(notice(state, 'You must identify before requesting a vhost.'));
+    return { state, effects };
+  }
+
+  const vhost = args[0];
+  if (vhost === undefined) {
+    effects.push(notice(state, 'Syntax: REQUEST <vhost>'));
+    return { state, effects };
+  }
+
+  if (!isValidVhost(vhost)) {
+    effects.push(notice(state, `Invalid vhost: ${vhost}`));
+    return { state, effects };
+  }
+
+  const services = ctx.services as ServicesStore;
+  if (ctx.serverConfig.hostservAutoApproveVhosts !== true) {
+    services.requestVhost(state.account, vhost);
+    effects.push(notice(state, `Vhost ${vhost} is pending oper approval.`));
+    return { state, effects };
+  }
+
+  services.setVhost(state.account, vhost);
+  effects.push(notice(state, `Vhost ${vhost} has been requested and approved.`));
+  return { state, effects };
+}
+
+// ============================================================================
+// SET (oper-only)
+// ============================================================================
+
+/**
+ * Handles `SET <account> <vhost>` (oper-only). Records the vhost against
+ * the named account directly, bypassing REQUEST. The literal `*` clears
+ * the recorded vhost. The target account must already be a registered
+ * nick; SET does not auto-register.
+ */
+function handleSet(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  if (!state.userModes.oper) {
+    effects.push(notice(state, 'You must be an oper to use SET.'));
+    return { state, effects };
+  }
+
+  const account = args[0];
+  const vhost = args[1];
+  if (account === undefined || vhost === undefined) {
+    effects.push(notice(state, 'Syntax: SET <account> <vhost>'));
+    return { state, effects };
+  }
+
+  const services = ctx.services as ServicesStore;
+  if (!services.isRegisteredNick(account)) {
+    effects.push(notice(state, `Nick ${account} is not registered.`));
+    return { state, effects };
+  }
+
+  if (vhost === CLEAR_VHOST_SENTINEL) {
+    services.setVhost(account, '');
+    effects.push(notice(state, `Vhost for ${account} has been cleared.`));
+    return { state, effects };
+  }
+
+  if (!isValidVhost(vhost)) {
+    effects.push(notice(state, `Invalid vhost: ${vhost}`));
+    return { state, effects };
+  }
+
+  services.setVhost(account, vhost);
+  effects.push(notice(state, `Vhost for ${account} is now set to ${vhost}.`));
+  return { state, effects };
+}
+
+// ============================================================================
+// APPROVE / ACTIVATE (oper-only)
+// ============================================================================
+
+/**
+ * Handles `APPROVE <account>` (alias `ACTIVATE`). Activates the pending
+ * vhost request recorded via queue-mode REQUEST: removes the pending
+ * entry, calls {@link ServicesStore.setVhost} to activate the vhost, and
+ * replies to the oper. A best-effort `SendToNick` NOTICE is emitted to
+ * the requester when they are online — delivery is owned by the actor
+ * layer (the reducer cannot mutate another connection's host directly).
+ * The requester is told to run `HostServ ON` to apply the vhost to their
+ * active connection.
+ */
+function handleApprove(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  if (!state.userModes.oper) {
+    effects.push(notice(state, 'You must be an oper to use APPROVE.'));
+    return { state, effects };
+  }
+
+  const account = args[0];
+  if (account === undefined) {
+    effects.push(notice(state, 'Syntax: APPROVE <account>'));
+    return { state, effects };
+  }
+
+  const services = ctx.services as ServicesStore;
+  const vhost = services.approveVhost(account);
+  if (vhost === undefined) {
+    effects.push(notice(state, `No pending vhost request for ${account}.`));
+    return { state, effects };
+  }
+
+  effects.push(notice(state, `Vhost ${vhost} for ${account} has been approved and activated.`));
+  effects.push(
+    Effect.sendToNick(account, state.id, [
+      servicesRawNotice(
+        HOSTSERV_NICK,
+        account,
+        `Your vhost ${vhost} has been approved and activated. /msg HostServ ON to apply it.`,
+      ),
+    ]),
+  );
+  return { state, effects };
+}
+
+// ============================================================================
+// REJECT (oper-only)
+// ============================================================================
+
+/**
+ * Handles `REJECT <account>`. Drops the pending vhost request without
+ * activating it, replies to the oper, and best-effort NOTICEs the
+ * requester via `SendToNick` (delivered when they are online, silently
+ * dropped otherwise).
+ */
+function handleReject(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  if (!state.userModes.oper) {
+    effects.push(notice(state, 'You must be an oper to use REJECT.'));
+    return { state, effects };
+  }
+
+  const account = args[0];
+  if (account === undefined) {
+    effects.push(notice(state, 'Syntax: REJECT <account>'));
+    return { state, effects };
+  }
+
+  const services = ctx.services as ServicesStore;
+  const vhost = services.rejectVhost(account);
+  if (vhost === undefined) {
+    effects.push(notice(state, `No pending vhost request for ${account}.`));
+    return { state, effects };
+  }
+
+  effects.push(notice(state, `Vhost request for ${account} has been rejected.`));
+  effects.push(
+    Effect.sendToNick(account, state.id, [
+      servicesRawNotice(
+        HOSTSERV_NICK,
+        account,
+        `Your vhost request for ${vhost} has been rejected.`,
+      ),
+    ]),
+  );
+  return { state, effects };
+}
+
+// ============================================================================
+// LIST (oper-only)
+// ============================================================================
+
+/**
+ * Handles `LIST`. Enumerates every pending vhost request as a
+ * `<account>: <vhost>` NOTICE line, or a `No pending vhost requests.`
+ * NOTICE when the queue is empty.
+ */
+function handleList(
+  state: ConnectionState,
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  if (!state.userModes.oper) {
+    effects.push(notice(state, 'You must be an oper to use LIST.'));
+    return { state, effects };
+  }
+
+  const services = ctx.services as ServicesStore;
+  const pending = services.listPendingVhosts();
+  if (pending.length === 0) {
+    effects.push(notice(state, 'No pending vhost requests.'));
+    return { state, effects };
+  }
+  for (const entry of pending) {
+    effects.push(notice(state, `${entry.account}: ${entry.vhost}`));
+  }
+  return { state, effects };
+}
+
+// ============================================================================
+// vhost application helpers
+// ============================================================================
+
+/**
+ * Consults the bound {@link ServicesStore} for an assigned vhost for `account`
+ * and, when one is present, applies it to {@link ConnectionState} via
+ * {@link applyVhost}. This is the shared login-time hook invoked by every
+ * account-success path (SASL PLAIN, PASS-auth via {@link applyAccountSuccess},
+ * and NickServ `IDENTIFY` via {@link applyIdentify}) so a reconnecting user
+ * with an assigned vhost does not have to re-run `HostServ ON` every session.
+ *
+ * No-op (no effects emitted, no state change) when no vhost is recorded. The
+ * CHGHOST fanout appended to `effects` is empty at SASL / PASS-auth time
+ * (registration has not completed and/or no channels are joined yet) but fires
+ * for a post-registration NickServ `IDENTIFY` when the user is already in
+ * channels — reusing {@link applyVhost} so the wire shape matches `HostServ ON`.
+ */
+export function applyAssignedVhost(
+  state: ConnectionState,
+  services: ServicesStore,
+  account: string,
+  effects: EffectType[],
+): void {
+  const vhost = services.getVhost(account);
+  if (vhost === undefined) return;
+  applyVhost(state, vhost, effects);
+}
+
+/**
+ * Applies `vhost` to {@link ConnectionState.host}, records the prior host
+ * on {@link ConnectionState.preVhostHost}, flips
+ * {@link ConnectionState.vhostActive}, and appends the CHGHOST fanout for
+ * every channel the user is joined to. The CHGHOST emission reuses the
+ * {@link emitChghost} helper so the wire shape matches every other
+ * user/host mutation.
+ */
+export function applyVhost(state: ConnectionState, vhost: string, effects: EffectType[]): void {
+  const oldUser = state.user ?? '';
+  const oldHost = state.host ?? '';
+  state.preVhostHost = oldHost;
+  state.host = vhost;
+  state.vhostActive = true;
+  effects.push(...emitChghost({ conn: state, oldUser, oldHost, newUser: oldUser, newHost: vhost }));
+}
+
+/**
+ * Restores {@link ConnectionState.host} from
+ * {@link ConnectionState.preVhostHost}, clears the saved host, flips
+ * {@link ConnectionState.vhostActive} off, and appends the CHGHOST fanout.
+ */
+function restoreRealHost(state: ConnectionState, effects: EffectType[]): void {
+  const oldUser = state.user ?? '';
+  const oldHost = state.host ?? '';
+  const realHost = state.preVhostHost ?? oldHost;
+  state.host = realHost;
+  state.vhostActive = false;
+  // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+  delete state.preVhostHost;
+  effects.push(
+    ...emitChghost({ conn: state, oldUser, oldHost, newUser: oldUser, newHost: realHost }),
+  );
+}
+
+// ============================================================================
+// Notice helpers
+// ============================================================================
+
+/** Builds a `:HostServ!HostServ@services NOTICE <nick> :<text>` line. */
+function notice(state: ConnectionState, text: string): EffectType {
+  return Effect.send(state.id, [servicesNotice(HOSTSERV_NICK, state, text)]);
+}
+
+/** User-visible HostServ subcommands (shown to every caller). */
+const USER_COMMANDS = 'ON, OFF, REQUEST';
+
+/** Oper-only HostServ subcommands, appended to {@link USER_COMMANDS} for opers. */
+const OPER_COMMANDS = 'SET, APPROVE, REJECT, LIST';
+
+/** Builds a help `:HostServ!HostServ@services NOTICE <nick> :…` line. */
+function helpNotice(state: ConnectionState): EffectType {
+  const commands =
+    state.userModes.oper === true ? `${USER_COMMANDS}, ${OPER_COMMANDS}` : USER_COMMANDS;
+  return notice(state, `Available commands: ${commands}`);
+}
+
+function unknownNotice(state: ConnectionState): EffectType {
+  const commands =
+    state.userModes.oper === true ? `${USER_COMMANDS}, ${OPER_COMMANDS}` : USER_COMMANDS;
+  return notice(state, `Unknown command. Available: ${commands}`);
+}
+
+/**
+ * Formats a services NOTICE line. The source hostmask is
+ * `<svc>!<svc>@services` regardless of the deployment's serverName so the
+ * pseudo-clients are stable across deployments and easy to identify in
+ * client UIs.
+ */
+function servicesNotice(svc: string, state: ConnectionState, text: string): RawLine {
+  const nick = state.nick ?? '*';
+  return { text: `:${svc}!${svc}@${SERVICES_HOST} NOTICE ${nick} :${text}` };
+}
+
+/**
+ * Formats a services NOTICE line addressed to `recipient` (rather than to
+ * the calling connection's nick). Used by APPROVE / REJECT to best-effort
+ * NOTICE the requester via `SendToNick` when they are online.
+ */
+function servicesRawNotice(svc: string, recipient: string, text: string): RawLine {
+  return { text: `:${svc}!${svc}@${SERVICES_HOST} NOTICE ${recipient} :${text}` };
+}

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

@@ -58,6 +58,7 @@ export {
   CHATHISTORY_CAP,
 } from './chathistory.js';
 export { tagmsgChannelReducer, tagmsgUserReducer } from './tagmsg.js';
+export { markreadChannelReducer } from './markread.js';
 export {
   DEFAULT_MULTILINE_MAX_BYTES,
   MULTILINE_CAP,
@@ -98,3 +99,15 @@ export {
   persistAway,
   replayPersistedAway,
 } from './pre-away.js';
+export { NICKSERV_NICK, nickservReducer } from './nickserv.js';
+export { MEMOSERV_NICK, memoservReducer } from './memoserv.js';
+export {
+  CHANSERV_NICK,
+  chanservReducer,
+  clearServicesModesDelta,
+  positiveMlockLetters,
+  setRegisteredDelta,
+} from './chanserv.js';
+export { HOSTSERV_NICK, hostservReducer } from './hostserv.js';
+export { OPERSERV_NICK, operservReducer } from './operserv.js';
+export { SERVICE_NICKS, SHORTCUT_TO_SERVICE } from './service-aliases.js';