serverless-ircd 0.7.0 → 0.8.0

package/packages/irc-core/src/commands/account-auth.ts

@@ -0,0 +1,172 @@
+/**
+ * Shared account-login helpers used by every account-setting entry point.
+ *
+ * PLAN §6.5 (services ↔ daemon hooks): a successful SASL PLAIN/EXTERNAL
+ * login, a PASS-based account login at registration, and (later) a
+ * NickServ `IDENTIFY` all reduce to the same thing — "this connection is
+ * now account X". {@link applyAccountSuccess} is that shared reduction:
+ * it stamps the account, sets the read-only `+r` user mode, restores
+ * per-account state (read markers, persisted away, queued memos), and
+ * emits the `900 RPL_LOGGEDIN` + `903 RPL_SASLSUCCESS` numerics plus the
+ * `account-notify` broadcast. Keeping the chain in one place guarantees
+ * the entry points never diverge.
+ *
+ * {@link passBasedAccountAuth} is the legacy IRC convention of carrying
+ * NickServ credentials in `PASS <nick>:<password>` at registration; it
+ * resolves at registration completion via the injected
+ * {@link AccountStore} and, on success, delegates to
+ * {@link applyAccountSuccess}.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import { hostmaskOf } from '../state/connection.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx } from '../types.js';
+import { emitAccountNotify } from './account-notify.js';
+import { deliverUnreadMemos } from './memoserv.js';
+import { nowAwayLine, replayPersistedAway } from './pre-away.js';
+import { seedReadMarkers } from './read-marker.js';
+
+/**
+ * Applies the account-login success effects shared by SASL, PASS-auth, and
+ * NickServ IDENTIFY.
+ *
+ * Mutates `state`: sets `state.account`, stamps read-only user mode `r`
+ * (`userModes.registered = true`), seeds `lastReadMarkers` from the bound
+ * services store, replays the persisted away reason, and returns the
+ * effects the caller must emit:
+ *   - `Send` carrying `900 RPL_LOGGEDIN` + `903 RPL_SASLSUCCESS`;
+ *   - an optional `306 RPL_NOWAWAY` when an away reason was replayed;
+ *   - any queued MemoServ `NOTICE`s delivered from the services store;
+ *   - the `account-notify` `ACCOUNT` broadcasts to cap-enabled peers in
+ *     shared channels (empty at identify time — no channels joined yet).
+ *
+ * Does NOT clear SASL scratch state; the SASL reducer owns that.
+ */
+export function applyAccountSuccess(
+  state: ConnectionState,
+  ctx: Ctx,
+  account: string,
+): EffectType[] {
+  state.account = account;
+  // A successful account login is equivalent to NickServ IDENTIFY: stamp
+  // read-only user mode `r` so `221`/WHOIS reflect the identified state.
+  state.userModes.registered = true;
+  // IRCv3 draft/read-marker: restore the user's per-channel last-read
+  // markers from the persisted store so a reconnect resumes at their last
+  // read position. No-op when no services store is bound.
+  if (ctx.services !== undefined) {
+    seedReadMarkers(state, ctx.services, account);
+  }
+  // IRCv3 draft/pre-away: replay the user's persisted away reason onto the
+  // fresh connection and emit 306 so the user sees they are still away.
+  const replayedAway =
+    ctx.away !== undefined ? replayPersistedAway(state, ctx.away, account) : undefined;
+  const awayEffects: EffectType[] =
+    replayedAway !== undefined
+      ? [Effect.send(ctx.connId, [nowAwayLine(state, ctx.serverName)])]
+      : [];
+  // MemoServ: deliver queued unread memos recorded while the account was
+  // offline. No-op when no services store is bound or there are none.
+  const memoEffects: EffectType[] = [];
+  if (ctx.services !== undefined) {
+    deliverUnreadMemos(state, ctx.services, account, memoEffects);
+  }
+  return [
+    Effect.send(ctx.connId, [loggedInLine(ctx, account), saslSuccessLine(ctx)]),
+    ...awayEffects,
+    ...memoEffects,
+    ...emitAccountNotify({ conn: state, account }),
+  ];
+}
+
+/**
+ * Parses a `PASS` payload of the form `<nick>:<password>` (the literal
+ * shape used by the `SASL_ACCOUNTS` env var and the seed tooling). Returns
+ * `null` when `attempt` is absent, has no colon, or the nick (left of the
+ * first colon) is empty. Only the first colon splits; the password may
+ * itself contain colons.
+ */
+export function parsePassAccountAttempt(
+  attempt: string | undefined,
+): { nick: string; password: string } | null {
+  if (attempt === undefined) return null;
+  const colon = attempt.indexOf(':');
+  if (colon <= 0) return null;
+  return { nick: attempt.slice(0, colon), password: attempt.slice(colon + 1) };
+}
+
+/**
+ * Attempts PASS-based account authentication at registration completion.
+ *
+ * Recognises the `<nick>:<password>` form in `state.passAttempt`, verifies
+ * it against the bound {@link AccountStore} (PLAIN), and on success runs
+ * the shared {@link applyAccountSuccess} chain. Returns the success
+ * effects, or `[]` for every other outcome:
+ *   - already identified (`state.account` set, e.g. via SASL) → no-op;
+ *   - no `<nick>:<password>` form (bare value) → left to the server-password
+ *     gate;
+ *   - payload nick does not match `state.nick` (when set) → not a coherent
+ *     account attempt, treated as failed auth;
+ *   - no {@link AccountStore} bound → the `<nick>:<password>` form is
+ *     ignored (collapses to the server-password gate);
+ *   - verify failure (unknown nick or wrong password) → no account effects.
+ *
+ * A failed verify is followed by a verify against a fixed dummy entry so
+ * the failure path performs the same AccountStore work whether the payload
+ * nick was unknown or the password was wrong — the observable outcome
+ * (no numerics, no disconnect, no state change) is identical for both
+ * cases, giving no information to a remote attacker.
+ */
+export function passBasedAccountAuth(state: ConnectionState, ctx: Ctx): EffectType[] {
+  if (state.account !== undefined) return [];
+  const parsed = parsePassAccountAttempt(state.passAttempt);
+  if (parsed === null) return [];
+  if (state.nick !== undefined && state.nick !== parsed.nick) return [];
+  const store = ctx.accounts;
+  if (store === undefined) return [];
+  const result = store.verify('PLAIN', {
+    kind: 'PLAIN',
+    username: parsed.nick,
+    password: parsed.password,
+  });
+  if (result.ok) {
+    return applyAccountSuccess(state, ctx, result.account);
+  }
+  // Equalise timing: perform a verify against a fixed dummy entry so a
+  // failed PASS-auth always costs one extra AccountStore call regardless
+  // of whether the payload nick was unknown or the password was wrong.
+  store.verify('PLAIN', {
+    kind: 'PLAIN',
+    username: PASS_AUTH_DUMMY_NICK,
+    password: PASS_AUTH_DUMMY_PASSWORD,
+  });
+  return [];
+}
+
+/** Fixed dummy credential used to equalise failed-PASS-auth timing. */
+const PASS_AUTH_DUMMY_NICK = '\u0000pass-auth-timing-dummy';
+const PASS_AUTH_DUMMY_PASSWORD = '\u0000pass-auth-timing-dummy';
+
+/** Builds the `900 RPL_LOGGEDIN` line for an account login. */
+function loggedInLine(ctx: Ctx, account: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const hostmask = hostmaskOf(ctx.connection) ?? nick;
+  return {
+    text: `:${ctx.serverName} ${numeric(Numerics.RPL_LOGGEDIN)} ${nick} ${hostmask} ${account} :You are now logged in as ${account}`,
+  };
+}
+
+/** Builds the `903 RPL_SASLSUCCESS` line for an account login. */
+function saslSuccessLine(ctx: Ctx): RawLine {
+  return {
+    text: `:${ctx.serverName} ${numeric(Numerics.RPL_SASLSUCCESS)} ${ctx.connection.nick ?? '*'} :SASL authentication successful`,
+  };
+}
+
+/** Zero-pads a numeric code to its three-digit wire form. */
+function numeric(n: number): string {
+  return n.toString().padStart(3, '0');
+}