serverless-ircd 0.1.0 → 0.3.0

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

@@ -0,0 +1,251 @@
+/**
+ * Pure reducer for the IRCv3 `AUTHENTICATE` command (SASL).
+ *
+ * PLAN §2.1 location-of-authority: SASL runs in the Connection entity.
+ * The reducer drives the multi-frame SASL exchange purely:
+ *
+ *   1. `AUTHENTICATE <MECH>` — selects a mechanism. `PLAIN` is supported and
+ *      answers with `AUTHENTICATE +` (requesting the payload). `EXTERNAL` is
+ *      recognized but stubbed to `904` until mTLS lands. Anything else gets
+ *      `908 ERR_SASLMECHS` listing what is available.
+ *   2. `AUTHENTICATE <b64>` / `AUTHENTICATE +` — delivers the payload (whole
+ *      or in `<=400`-byte chunks; `+` marks an empty/final chunk). The
+ *      decoded bytes are handed to the injected {@link AccountStore}; on
+ *      success the connection records the account name and the reducer emits
+ *      `900 RPL_LOGGEDIN` + `903 RPL_SASLSUCCESS`, on failure `904 ERR_SASLFAIL`.
+ *   3. `AUTHENTICATE *` — client abort → `906 ERR_SASLABORT`.
+ *
+ * The `AccountStore` port is **synchronous** (see {@link AccountStore} docs):
+ * adapters pre-load credentials so the reducer stays pure. Async backends
+ * resolve their lookups before the actor invokes this reducer.
+ *
+ * State: {@link ConnectionState.saslMech} tracks the mechanism in flight;
+ * {@link ConnectionState.saslBuffer} accumulates chunked payloads. Both are
+ * cleared on every terminal outcome.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { decodeBase64 } from '../protocol/base64.js';
+import { Numerics } from '../protocol/numerics.js';
+import { hostmaskOf } from '../state/connection.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer } from '../types.js';
+
+/** Per-ircdocs.horse: a single `AUTHENTICATE` payload chunk is at most 400 bytes. */
+const SASL_CHUNK_BYTES = 400;
+
+/** Total decoded-payload cap before `905 ERR_SASLTOOLONG`. */
+const SASL_MAX_BYTES = 8192;
+
+/** Mechanisms this server will accept today (advertised verbatim by the cap). */
+const SUPPORTED_MECHS = 'PLAIN,EXTERNAL';
+
+/**
+ * Reducer for `AUTHENTICATE [<param>]`. See module docs for the state
+ * machine. Authority: the invoking connection's {@link ConnectionState}.
+ */
+export const authenticateReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const param = msg.params[0];
+  if (param === undefined) {
+    return { state, effects: [Effect.send(ctx.connId, [needMoreParams(ctx)])] };
+  }
+
+  if (state.registration === 'registered' || !state.capNegotiating || state.account !== undefined) {
+    return { state, effects: [Effect.send(ctx.connId, [saslAlready(ctx)])] };
+  }
+
+  if (param === '*') {
+    return handleAbort(state, ctx);
+  }
+
+  if (state.saslMech === undefined) {
+    return handleMechanism(state, param, ctx);
+  }
+
+  return handlePayload(state, param, ctx);
+};
+
+/** `AUTHENTICATE *` — client-initiated abort. */
+function handleAbort(
+  state: ConnectionState,
+  ctx: Ctx,
+): { state: ConnectionState; effects: EffectType[] } {
+  if (state.saslMech === undefined) {
+    return { state, effects: [] };
+  }
+  clearSasl(state);
+  return { state, effects: [Effect.send(ctx.connId, [saslAbort(ctx)])] };
+}
+
+/** `AUTHENTICATE <MECH>` — first frame of an exchange. */
+function handleMechanism(
+  state: ConnectionState,
+  param: string,
+  ctx: Ctx,
+): { state: ConnectionState; effects: EffectType[] } {
+  const mech = param.toUpperCase();
+  if (mech === 'PLAIN') {
+    state.saslMech = 'PLAIN';
+    state.saslBuffer = '';
+    return { state, effects: [Effect.send(ctx.connId, [L('AUTHENTICATE +')])] };
+  }
+  if (mech === 'EXTERNAL') {
+    return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };
+  }
+  return { state, effects: [Effect.send(ctx.connId, [saslMechs(ctx)])] };
+}
+
+/** `AUTHENTICATE <chunk>` / `AUTHENTICATE +` — payload delivery. */
+function handlePayload(
+  state: ConnectionState,
+  param: string,
+  ctx: Ctx,
+): { state: ConnectionState; effects: EffectType[] } {
+  const mech = state.saslMech as string;
+  const buffer = state.saslBuffer as string;
+
+  if (param === '+') {
+    return finalize(state, buffer, mech, ctx);
+  }
+
+  const next = buffer + param;
+  if (next.length > SASL_MAX_BYTES) {
+    clearSasl(state);
+    return { state, effects: [Effect.send(ctx.connId, [saslTooLong(ctx)])] };
+  }
+
+  if (param.length === SASL_CHUNK_BYTES) {
+    state.saslBuffer = next;
+    return { state, effects: [] };
+  }
+
+  return finalize(state, next, mech, ctx);
+}
+
+/** Decodes the accumulated payload and runs it through the AccountStore. */
+function finalize(
+  state: ConnectionState,
+  payloadB64: string,
+  mech: string,
+  ctx: Ctx,
+): { state: ConnectionState; effects: EffectType[] } {
+  const parsed = parsePlain(payloadB64);
+
+  if (parsed === null) {
+    clearSasl(state);
+    return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };
+  }
+
+  const store = ctx.accounts;
+  if (store === undefined) {
+    clearSasl(state);
+    return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };
+  }
+
+  const result = store.verify(mech, {
+    kind: 'PLAIN',
+    username: parsed.username,
+    password: parsed.password,
+  });
+
+  clearSasl(state);
+
+  if (result.ok) {
+    state.account = result.account;
+    return {
+      state,
+      effects: [Effect.send(ctx.connId, [loggedIn(ctx, result.account), saslSuccess(ctx)])],
+    };
+  }
+  return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };
+}
+
+/**
+ * Decodes a base64 PLAIN payload (`authzid\0authcid\0passwd`) and returns the
+ * authcid/password pair. Returns `null` on any decode or shape failure.
+ */
+function parsePlain(payloadB64: string): { username: string; password: string } | null {
+  let decoded: string;
+  try {
+    decoded = decodeBase64(payloadB64);
+  } catch {
+    return null;
+  }
+  const parts = decoded.split('\0');
+  if (parts.length !== 3) return null;
+  const [, username, password] = parts as [string, string, string];
+  return { username, password };
+}
+
+/** Clears every SASL-related scratch field on the connection. */
+function clearSasl(state: ConnectionState): void {
+  // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+  delete state.saslMech;
+  // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+  delete state.saslBuffer;
+}
+
+function loggedIn(ctx: Ctx, account: string): RawLine {
+  const nick = nickOf(ctx);
+  const hostmask = hostmaskOf(ctx.connection) ?? nick;
+  return L(
+    `:${ctx.serverName} ${code(Numerics.RPL_LOGGEDIN)} ${nick} ${hostmask} ${account} :You are now logged in as ${account}`,
+  );
+}
+
+function saslSuccess(ctx: Ctx): RawLine {
+  return L(
+    `:${ctx.serverName} ${code(Numerics.RPL_SASLSUCCESS)} ${nickOf(ctx)} :SASL authentication successful`,
+  );
+}
+
+function saslFail(ctx: Ctx): RawLine {
+  return L(
+    `:${ctx.serverName} ${code(Numerics.ERR_SASLFAIL)} ${nickOf(ctx)} :SASL authentication failed`,
+  );
+}
+
+function saslTooLong(ctx: Ctx): RawLine {
+  return L(
+    `:${ctx.serverName} ${code(Numerics.ERR_SASLTOOLONG)} ${nickOf(ctx)} :SASL message too long`,
+  );
+}
+
+function saslAbort(ctx: Ctx): RawLine {
+  return L(
+    `:${ctx.serverName} ${code(Numerics.ERR_SASLABORT)} ${nickOf(ctx)} :SASL authentication aborted`,
+  );
+}
+
+function saslAlready(ctx: Ctx): RawLine {
+  return L(
+    `:${ctx.serverName} ${code(Numerics.ERR_SASLALREADY)} ${nickOf(ctx)} :You have already authenticated using SASL`,
+  );
+}
+
+function saslMechs(ctx: Ctx): RawLine {
+  return L(
+    `:${ctx.serverName} ${code(Numerics.ERR_SASLMECHS)} ${nickOf(ctx)} ${SUPPORTED_MECHS} :are the available SASL mechanisms`,
+  );
+}
+
+function needMoreParams(ctx: Ctx): RawLine {
+  return L(
+    `:${ctx.serverName} ${code(Numerics.ERR_NEEDMOREPARAMS)} ${nickOf(ctx)} AUTHENTICATE :Not enough parameters`,
+  );
+}
+
+function nickOf(ctx: Ctx): string {
+  return ctx.connection.nick ?? '*';
+}
+
+function code(n: number): string {
+  return n.toString().padStart(3, '0');
+}
+
+function L(text: string): RawLine {
+  return { text };
+}

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

@@ -0,0 +1,205 @@
+/**
+ * Pure reducer for the IRCv3 `message-tags` `TAGMSG` command.
+ *
+ * Spec: https://ircv3.net/specs/extensions/message-tags#the-tagmsg-command
+ *
+ * TAGMSG carries ONLY message tags — no text body. Wire format:
+ *   `@+client-tag=value;vendor/tag=value :nick!user@host TAGMSG #target`
+ *
+ * The command is gated behind the `message-tags` capability: clients that
+ * did not negotiate it see `421 ERR_UNKNOWNCOMMAND` (matching the spec's
+ * permitted "unknown command" fallback, same as `draft/chathistory`).
+ *
+ * After the cap gate passes, TAGMSG follows NOTICE semantics: **no numeric
+ * error replies are ever emitted.** All rejection paths (+n, +m, +b,
+ * missing target) silently return an empty effect list.
+ *
+ * Recording mirrors the PRIVMSG/NOTICE channel path so chathistory replay
+ * (which already handles `command === 'TAGMSG'` in `formatReplayLine`)
+ * picks up TAGMSG lines for free.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import { escapeTagValue } from '../protocol/serializer.js';
+import type { ChannelState } from '../state/channel.js';
+import { hostmaskOf } from '../state/connection.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer } from '../types.js';
+
+/** The cap name advertising message-tags support. */
+const MESSAGE_TAGS_CAP = 'message-tags';
+
+/**
+ * Returns true iff `hostmask` matches the IRC ban mask `mask`. Identical to
+ * the implementation in `privmsg.ts`; duplicated to keep the message path
+ * self-contained (ban-matching consolidation is planned).
+ */
+function matchesBanMask(mask: string, hostmask: string): boolean {
+  let pattern = '^';
+  for (const ch of mask) {
+    if (ch === '*') {
+      pattern += '.*';
+    } else if (ch === '?') {
+      pattern += '.';
+    } else if (/[A-Za-z0-9]/.test(ch)) {
+      pattern += ch;
+    } else {
+      pattern += `\\${ch}`;
+    }
+  }
+  pattern += '$';
+  return new RegExp(pattern, 'i').test(hostmask);
+}
+
+/** Formats a numeric error line addressed to the connection's nick (or `*`). */
+function numericErr(ctx: Ctx, code: number, trailing: string, middle: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: [`:${ctx.serverName}`, codeStr, nick, middle, `:${trailing}`].join(' ') };
+}
+
+/** Resolves the sender's hostmask, falling back to nick then `?`. */
+function senderHostmask(conn: ConnectionState): string {
+  return hostmaskOf(conn) ?? conn.nick ?? '?';
+}
+
+/**
+ * Returns true iff `entry` may speak on a moderated channel: ops and voiced
+ * members pass; everyone else is blocked.
+ */
+function maySpeakOnModerated(entry: { op: boolean; voice: boolean } | undefined): boolean {
+  if (entry === undefined) return false;
+  return entry.op || entry.voice;
+}
+
+/**
+ * Serializes `tags` into the `@key=val;… ` wire prefix used by TAGMSG.
+ * Returns an empty string when there are no tags (so the line has no `@…`
+ * prefix at all). A valueless tag (empty string) renders as just the key.
+ */
+function serializeTags(tags: Readonly<Record<string, string>>): string {
+  const entries = Object.entries(tags);
+  if (entries.length === 0) return '';
+  const section = entries
+    .map(([key, value]) => (value === '' ? key : `${key}=${escapeTagValue(value)}`))
+    .join(';');
+  return `@${section} `;
+}
+
+/** Reducer for `TAGMSG <channel>`. Authority: ChannelState. */
+export const tagmsgChannelReducer: Reducer<ChannelState> = (state, msg, ctx) => {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  // Cap gate: clients that did not negotiate message-tags see RFC 2812 only.
+  if (!ctx.connection.caps.has(MESSAGE_TAGS_CAP)) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericErr(ctx, Numerics.ERR_UNKNOWNCOMMAND, 'Unknown command', 'TAGMSG'),
+        ]),
+      ],
+    };
+  }
+
+  const effects: EffectType[] = [];
+
+  const target = msg.params[0];
+
+  // NOTICE-style silence: missing target → empty effects.
+  if (target === undefined) {
+    return { state, effects };
+  }
+
+  const senderEntry = state.members.get(ctx.connId);
+  const hostmask = senderHostmask(ctx.connection);
+
+  // +n (no external messages): sender must be a member. Silent.
+  if (state.modes.noExternal && senderEntry === undefined) {
+    return { state, effects };
+  }
+
+  // +m (moderated): sender must be op or voiced. Silent.
+  if (state.modes.moderated && !maySpeakOnModerated(senderEntry)) {
+    return { state, effects };
+  }
+
+  // +b (ban): sender's hostmask must not match any ban mask. Silent.
+  if (state.banMasks.size > 0) {
+    for (const mask of state.banMasks) {
+      if (matchesBanMask(mask, hostmask)) {
+        return { state, effects };
+      }
+    }
+  }
+
+  // Persist for chathistory playback when a MessageStore is bound.
+  if (ctx.messages !== undefined) {
+    ctx.messages.record({
+      msgid: ctx.ids.nonce(),
+      time: ctx.clock.now(),
+      chan: state.nameLower,
+      command: 'TAGMSG',
+      nick: ctx.connection.nick as string,
+      user: ctx.connection.user as string,
+      host: ctx.connection.host as string,
+      text: '',
+    });
+  }
+
+  // Broadcast the tag-bearing line to message-tags-enabled members only.
+  const tagPrefix = serializeTags(msg.tags);
+  const line: RawLine = { text: `${tagPrefix}:${hostmask} TAGMSG ${state.name}` };
+  effects.push(Effect.broadcast(state.name, [line], ctx.connId, MESSAGE_TAGS_CAP));
+
+  // IRCv3 echo-message: echo the same line back to the sender, after
+  // the broadcast effect so clients observe their own message last.
+  if (ctx.connection.caps.has('echo-message')) {
+    effects.push(Effect.send(ctx.connId, [line]));
+  }
+
+  return { state, effects };
+};
+
+/** Reducer for `TAGMSG <nick>`. Authority: sender's ConnectionState. */
+export const tagmsgUserReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  // Cap gate: clients that did not negotiate message-tags see RFC 2812 only.
+  if (!ctx.connection.caps.has(MESSAGE_TAGS_CAP)) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericErr(ctx, Numerics.ERR_UNKNOWNCOMMAND, 'Unknown command', 'TAGMSG'),
+        ]),
+      ],
+    };
+  }
+
+  const effects: EffectType[] = [];
+
+  const target = msg.params[0];
+
+  // NOTICE-style silence: missing target → empty effects.
+  if (target === undefined) {
+    return { state, effects };
+  }
+
+  const hostmask = senderHostmask(state);
+  const tagPrefix = serializeTags(msg.tags);
+  const line: RawLine = { text: `${tagPrefix}:${hostmask} TAGMSG ${target}` };
+
+  // No notFoundLines — TAGMSG is silent like NOTICE for offline recipients.
+  effects.push(Effect.sendToNick(target, ctx.connId, [line]));
+
+  // IRCv3 echo-message: echo the same line back to the sender, after
+  // the SendToNick effect so clients observe their own message last.
+  if (ctx.connection.caps.has('echo-message')) {
+    effects.push(Effect.send(ctx.connId, [line]));
+  }
+
+  return { state, effects };
+};