serverless-ircd 0.3.0 → 0.4.0

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

@@ -14,8 +14,12 @@
  *   - nick registry: {@link ReserveNickEffect}, {@link ChangeNickEffect},
  *     {@link ReleaseNickEffect}
  *   - channel ownership: {@link ApplyChannelDeltaEffect}
- *   - lookups: {@link LookupNickEffect}, {@link GetConnectionInfoEffect},
- *     {@link GetChannelSnapshotEffect}
+ *
+ *   Lookup-shaped runtime methods (`lookupNick`, `getConnectionInfo`,
+ *   `getChannelSnapshot`) are consumed directly inside `dispatch`'s
+ *   broadcast helper and the actor — they are request/response and cannot
+ *   be modelled as pure fire-and-forget effects, so no Effect variants
+ *   wrap them.
  */
 
 import type { ChanName, ChannelDelta } from './state/channel.js';
@@ -71,21 +75,6 @@ export interface ApplyChannelDeltaEffect {
   delta: ChannelDelta;
 }
 
-export interface LookupNickEffect {
-  tag: 'LookupNick';
-  nick: Nick;
-}
-
-export interface GetConnectionInfoEffect {
-  tag: 'GetConnectionInfo';
-  conn: ConnId;
-}
-
-export interface GetChannelSnapshotEffect {
-  tag: 'GetChannelSnapshot';
-  chan: ChanName;
-}
-
 /**
  * Routes `lines` to whichever connection currently owns `nick`. If the nick
  * is offline, `notFoundLines` (when supplied) is sent back to `sender` —
@@ -109,9 +98,6 @@ export type Effect =
   | ChangeNickEffect
   | ReleaseNickEffect
   | ApplyChannelDeltaEffect
-  | LookupNickEffect
-  | GetConnectionInfoEffect
-  | GetChannelSnapshotEffect
   | SendToNickEffect;
 
 /** Literal string tag of every {@link Effect} variant. */
@@ -167,15 +153,6 @@ export const Effect = {
   applyChannelDelta(chan: ChanName, delta: ChannelDelta): Effect {
     return { tag: 'ApplyChannelDelta', chan, delta };
   },
-  lookupNick(nick: Nick): Effect {
-    return { tag: 'LookupNick', nick };
-  },
-  getConnectionInfo(conn: ConnId): Effect {
-    return { tag: 'GetConnectionInfo', conn };
-  },
-  getChannelSnapshot(chan: ChanName): Effect {
-    return { tag: 'GetChannelSnapshot', chan };
-  },
   sendToNick(nick: Nick, sender: ConnId, lines: RawLine[], notFoundLines?: RawLine[]): Effect {
     const e: SendToNickEffect = { tag: 'SendToNick', nick, sender, lines };
     if (notFoundLines !== undefined) e.notFoundLines = notFoundLines;

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

@@ -10,6 +10,7 @@ export * from './caps/index.js';
 export * from './commands/index.js';
 export * from './effects.js';
 export * from './ports.js';
+export * from './credential-hashing.js';
 export * from './flood-control.js';
 export * from './cloak.js';
 export * from './case-fold.js';

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

@@ -57,7 +57,7 @@ export interface IdFactory {
 
 /**
  * Production id factory. Generates UUIDv4-shaped strings without relying
- * on `crypto` so the same code runs on Node 20, Cloudflare Workers, and
+ * on `crypto` so the same code runs on Node 24, Cloudflare Workers, and
  * Lambda without per-platform type wrangling. Uniqueness is statistical;
  * for cryptographic IDs, adapters can supply their own {@link IdFactory}.
  */
@@ -171,7 +171,8 @@ export const EmptyMotdProvider: MotdProvider = new StaticMotdProvider([]);
  */
 export type SaslPayload =
   | { kind: 'PLAIN'; username: string; password: string }
-  | { kind: 'RAW'; data: string };
+  | { kind: 'RAW'; data: string }
+  | { kind: 'EXTERNAL'; identity: string };
 
 /**
  * Outcome of an {@link AccountStore.verify} call: either the canonical
@@ -202,6 +203,12 @@ export interface AccountStore {
 export interface SaslAccountCredential {
   username: string;
   password: string;
+  /**
+   * Optional mTLS client-certificate subject (e.g. `CN=alice` or a
+   * fingerprint hash). When set, SASL `EXTERNAL` authentications that
+   * present this subject are mapped to {@link username} as the account.
+   */
+  certSubject?: string;
 }
 
 /**
@@ -221,23 +228,37 @@ export interface SaslAccountCredential {
  */
 export class InMemoryAccountStore implements AccountStore {
   private readonly creds: ReadonlyMap<string, string>;
+  private readonly certMap: ReadonlyMap<string, string>;
 
   constructor(credentials: ReadonlyArray<SaslAccountCredential>) {
     this.creds = new Map(credentials.map((c) => [c.username, c.password]));
+    this.certMap = new Map(
+      credentials
+        .filter((c) => c.certSubject !== undefined)
+        .map((c) => [c.certSubject as string, c.username]),
+    );
   }
 
   verify(mech: string, payload: SaslPayload): SaslResult {
-    if (mech.toUpperCase() !== 'PLAIN' || payload.kind !== 'PLAIN') {
-      return { ok: false, reason: `unsupported mechanism: ${mech}` };
-    }
-    const expected = this.creds.get(payload.username);
-    if (expected === undefined) {
-      return { ok: false, reason: 'invalid credentials' };
+    const m = mech.toUpperCase();
+    if (m === 'PLAIN' && payload.kind === 'PLAIN') {
+      const expected = this.creds.get(payload.username);
+      if (expected === undefined) {
+        return { ok: false, reason: 'invalid credentials' };
+      }
+      if (!constantTimeEquals(payload.password, expected)) {
+        return { ok: false, reason: 'invalid credentials' };
+      }
+      return { ok: true, account: payload.username };
     }
-    if (!constantTimeEquals(payload.password, expected)) {
-      return { ok: false, reason: 'invalid credentials' };
+    if (m === 'EXTERNAL' && payload.kind === 'EXTERNAL') {
+      const account = this.certMap.get(payload.identity);
+      if (account === undefined) {
+        return { ok: false, reason: 'untrusted certificate' };
+      }
+      return { ok: true, account };
     }
-    return { ok: true, account: payload.username };
+    return { ok: false, reason: `unsupported mechanism: ${mech}` };
   }
 }
 
@@ -256,6 +277,52 @@ function constantTimeEquals(a: string, b: string): boolean {
   return diff === 0;
 }
 
+// ============================================================================
+// mTLS identity (SASL EXTERNAL)
+// ============================================================================
+
+/**
+ * Port that resolves the verified client-certificate identity for a
+ * connection.
+ *
+ * At the edge (CF API Shield mTLS, AWS API Gateway custom-domain mTLS) the
+ * platform terminates TLS, validates the client certificate against the
+ * configured trust store, and surfaces the certificate subject to the
+ * Worker/Lambda. The adapter captures this at connection-admission time
+ * and stores it keyed by connection ID.
+ *
+ * The method is **synchronous** — adapters pre-populate the identity at
+ * admission time (before the first reducer runs), so the SASL EXTERNAL
+ * reducer can look it up without awaiting. When no client certificate was
+ * presented (or mTLS is not configured), `getIdentity` returns `undefined`
+ * and EXTERNAL authentication fails with `904`.
+ */
+export interface MtlsIdentityProvider {
+  /**
+   * @returns the verified client-cert subject for `connId`, or `undefined`
+   *   when no trusted certificate was presented.
+   */
+  getIdentity(connId: string): string | undefined;
+}
+
+/**
+ * Reference in-memory {@link MtlsIdentityProvider} backed by a static map
+ * of connection IDs to certificate subjects. Useful for tests and the
+ * local-cli adapter; cloud adapters replace this with a lookup keyed by
+ * the platform's connection identifier.
+ */
+export class InMemoryMtlsIdentityProvider implements MtlsIdentityProvider {
+  private readonly identities: ReadonlyMap<string, string>;
+
+  constructor(entries: ReadonlyArray<{ connId: string; identity: string }>) {
+    this.identities = new Map(entries.map((e) => [e.connId, e.identity]));
+  }
+
+  getIdentity(connId: string): string | undefined {
+    return this.identities.get(connId);
+  }
+}
+
 // ============================================================================
 // Chat-history persistence (IRCv3 draft/chathistory)
 // ============================================================================
@@ -501,6 +568,108 @@ function tail<T>(arr: readonly T[], n: number): T[] {
   return arr.slice(start);
 }
 
+// ============================================================================
+// Nick history (WHOWAS)
+// ============================================================================
+
+/**
+ * One persisted sign-off record for a nick, written by the QUIT and
+ * post-registration NICK-change reducers and replayed by `WHOWAS`.
+ *
+ * `nick` preserves the original case the client used; `connId` is the
+ * connection that owned the nick at sign-off. `username` / `hostname` /
+ * `realname` mirror the {@link ConnectionState} fields at sign-off time
+ * (optional because a never-fully-registered connection may still quit with
+ * a nick). `signoffTime` is epoch milliseconds from the injected
+ * {@link Clock}.
+ */
+export interface NickHistoryEntry {
+  nick: string;
+  connId: string;
+  username?: string;
+  hostname?: string;
+  realname?: string;
+  signoffTime: number;
+}
+
+/**
+ * Persistence port for the IRC `WHOWAS` command.
+ *
+ * Mirrors the {@link MessageStore} 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; Phase 8 ships the in-memory
+ * reference implementation only.
+ *
+ * `query` always returns matches most-recent-first (the order `WHOWAS`
+ * emits `314 RPL_WHOWASUSER` lines in), capped at `count`.
+ */
+export interface NickHistoryStore {
+  /** Records a sign-off entry for a nick (TTL eviction is impl-defined). */
+  record(entry: NickHistoryEntry): void;
+  /** Returns up to `count` most-recent entries for `nick` (case-insensitive). */
+  query(nick: string, count: number): NickHistoryEntry[];
+}
+
+/** Default retention window for nick-history entries: 24 hours. */
+const DEFAULT_NICK_HISTORY_MAX_AGE = 24 * 60 * 60 * 1000;
+
+/**
+ * Reference in-memory {@link NickHistoryStore} backed by a per-nick
+ * chronological array with a configurable TTL.
+ *
+ * Used by the local CLI and by tests. Each nick keeps its sign-off records
+ * in arrival order; entries older than `maxAge` (measured against the
+ * injected {@link Clock}) are dropped lazily on `record` and `query` so the
+ * per-nick buffers do not grow unbounded.
+ *
+ * Nicks are keyed via {@link caseFold} (`rfc1459`) so lookups are
+ * case-insensitive, matching the IRC nick-comparison semantics advertised
+ * via `005 RPL_ISUPPORT CASEMAPPING=rfc1459`.
+ */
+export class InMemoryNickHistoryStore implements NickHistoryStore {
+  private readonly byNick = new Map<string, NickHistoryEntry[]>();
+  private readonly clock: Clock;
+  private readonly maxAge: number;
+
+  constructor(clock: Clock, opts?: { maxAge?: number }) {
+    this.clock = clock;
+    this.maxAge = opts?.maxAge ?? DEFAULT_NICK_HISTORY_MAX_AGE;
+  }
+
+  record(entry: NickHistoryEntry): void {
+    const key = caseFold('rfc1459', entry.nick);
+    let arr = this.byNick.get(key);
+    if (arr === undefined) {
+      arr = [];
+      this.byNick.set(key, arr);
+    }
+    this.purgeExpired(arr);
+    arr.push(entry);
+  }
+
+  query(nick: string, count: number): NickHistoryEntry[] {
+    if (count <= 0) return [];
+    const arr = this.byNick.get(caseFold('rfc1459', nick));
+    if (arr === undefined) return [];
+    this.purgeExpired(arr);
+    if (arr.length === 0) return [];
+    return arr.slice(Math.max(0, arr.length - count)).reverse();
+  }
+
+  /**
+   * Drops entries whose `signoffTime` is older than `now - maxAge`, in place.
+   * Entries arrive in chronological order (append-only), so the first alive
+   * entry marks the boundary; everything before it is expired.
+   */
+  private purgeExpired(arr: NickHistoryEntry[]): void {
+    const cutoff = this.clock.now() - this.maxAge;
+    let firstAlive = arr.findIndex((e) => e.signoffTime >= cutoff);
+    if (firstAlive === -1) firstAlive = arr.length;
+    arr.splice(0, firstAlive);
+  }
+}
+
 // ============================================================================
 // Observability — structured logger
 // ============================================================================
@@ -854,7 +1023,7 @@ export class ConsoleLogger implements Logger {
 
 /** Returns the global `console` as a {@link ConsoleLoggerSinks}. */
 function globalThisConsoleSinks(): ConsoleLoggerSinks {
-  // `globalThis.console` is universal across Node 20, Workers, and Lambda.
+  // `globalThis.console` is universal across Node 24, Workers, and Lambda.
   // Reference it lazily so tests that stub the logger do not need to
   // replace the global.
   const c = (globalThis as { console?: GlobalConsole }).console;

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

@@ -13,7 +13,7 @@ export const Numerics = {
   RPL_ISUPPORT: 5,
   RPL_BOUNCE: 10,
 
-  // Capability / stats admin
+  // Capability / stats admin / version
   RPL_ADMINME: 256,
 
   // Away / userhost / ison
@@ -23,7 +23,10 @@ export const Numerics = {
   RPL_UNAWAY: 305,
   RPL_NOWAWAY: 306,
 
-  // WHOIS
+  // Version
+  RPL_VERSION: 351,
+
+  // WHOIS / WHOWAS
   RPL_WHOISUSER: 311,
   RPL_WHOISSERVER: 312,
   RPL_WHOISOPERATOR: 313,
@@ -31,6 +34,7 @@ export const Numerics = {
   RPL_ENDOFWHOIS: 318,
   RPL_WHOISCHANNELS: 319,
   RPL_WHOISACCOUNT: 330,
+  RPL_WHOWASUSER: 314,
 
   // LIST
   RPL_LISTSTART: 321,
@@ -57,7 +61,8 @@ export const Numerics = {
   RPL_NAMREPLY: 353,
   RPL_ENDOFNAMES: 366,
 
-  // Links / ban / whowas
+  // Links / ban / whowas. RPL_LINKS/RPL_ENDOFLINKS retained for the deferred
+  // LINKS verb (S2S server list — PLAN non-goal; see actor default-route triage).
   RPL_LINKS: 364,
   RPL_ENDOFLINKS: 365,
   RPL_BANLIST: 367,
@@ -71,7 +76,8 @@ export const Numerics = {
   RPL_MOTDSTART: 375,
   RPL_ENDOFMOTD: 376,
 
-  // Oper
+  // Oper. RPL_REHASHING retained for the deferred REHASH verb (no runtime
+  // config-reload path in serverless; see actor default-route triage).
   RPL_YOUREOPER: 381,
   RPL_REHASHING: 382,
   RPL_YOURESERVICE: 383,
@@ -96,7 +102,7 @@ export const Numerics = {
   ERR_TOOMANYCHANNELS: 405,
   ERR_WASNOSUCHNICK: 406,
   ERR_TOOMANYTARGETS: 407,
-  ERR_NOSUCHSERVICE: 408,
+  ERR_NOSUCHSERVICE: 408, // retained: deferred SERVICE verb (RFC 2812 obsolete)
   ERR_INVALIDCAPCMD: 410,
   ERR_NORECIPIENT: 411,
   ERR_NOTEXTTOSEND: 412,
@@ -115,8 +121,8 @@ export const Numerics = {
   ERR_NOTONCHANNEL: 442,
   ERR_USERONCHANNEL: 443,
   ERR_NOLOGIN: 444,
-  ERR_SUMMONDISABLED: 445,
-  ERR_USERSDISABLED: 446,
+  ERR_SUMMONDISABLED: 445, // retained: deferred SUMMON verb (RFC 2812 obsolete)
+  ERR_USERSDISABLED: 446, // retained: deferred USERS verb (RFC 2812 obsolete)
   ERR_NOTREGISTERED: 451,
   ERR_NEEDMOREPARAMS: 461,
   ERR_ALREADYREGISTRED: 462,
@@ -134,7 +140,7 @@ export const Numerics = {
   ERR_BANLISTFULL: 478,
   ERR_NOPRIVILEGES: 481,
   ERR_CHANOPRIVSNEEDED: 482,
-  ERR_CANTKILLSERVER: 483,
+  ERR_CANTKILLSERVER: 483, // retained: deferred SQUIT verb (S2S, PLAN non-goal)
   ERR_NOOPERHOST: 491,
   ERR_UMODEUNKNOWNFLAG: 501,
   ERR_USERSDONTMATCH: 502,

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

@@ -8,7 +8,15 @@
 
 import type { Effect } from './effects.js';
 import type { FloodControlConfig } from './flood-control.js';
-import type { AccountStore, Clock, IdFactory, MessageStore, MotdProvider } from './ports.js';
+import type {
+  AccountStore,
+  Clock,
+  IdFactory,
+  MessageStore,
+  MotdProvider,
+  MtlsIdentityProvider,
+  NickHistoryStore,
+} from './ports.js';
 import type { IrcMessage } from './protocol/messages.js';
 import type { ConnectionState } from './state/connection.js';
 
@@ -46,6 +54,18 @@ export interface OperCred {
 export interface ServerConfig {
   serverName: string;
   networkName: string;
+  /**
+   * Server version surfaced in `002`/`004`/`351`/`371`. When undefined the
+   * reducer falls back to {@link DEFAULT_SERVER_VERSION} (the irc-core
+   * package version); adapters inject the deploy-time version via config.
+   */
+  readonly serverVersion?: string | undefined;
+  /**
+   * "Created" text for `003 RPL_CREATED`. A string is used verbatim; a
+   * number is treated as epoch-ms and formatted as a UTC timestamp. When
+   * undefined the reducer falls back to {@link DEFAULT_CREATED_TEXT}.
+   */
+  readonly createdAt?: string | number | undefined;
   /**
    * Server password gate. Empty string or undefined disables enforcement.
    * When set, registration refuses to complete until the connection
@@ -115,6 +135,12 @@ export interface Ctx {
   readonly motd: MotdProvider;
   /** SASL account verification source (absent when no accounts are configured). */
   readonly accounts?: AccountStore;
+  /**
+   * mTLS client-cert identity source for SASL EXTERNAL (absent when mTLS
+   * is not configured). When present, `AUTHENTICATE EXTERNAL` resolves the
+   * connection's verified certificate subject through this port.
+   */
+  readonly mtlsIdentity?: MtlsIdentityProvider;
   /**
    * Chat-history persistence source (absent when chathistory playback is
    * disabled for this deployment). When present, the PRIVMSG/NOTICE channel
@@ -122,6 +148,13 @@ export interface Ctx {
    * cap-enabled joiners.
    */
   readonly messages?: MessageStore;
+  /**
+   * Nick-history source for the `WHOWAS` command (absent when WHOWAS
+   * history retention is disabled for this deployment). When present, the
+   * QUIT and post-registration NICK-change reducers record sign-off
+   * entries and the WHOWAS reducer replays them.
+   */
+  readonly history?: NickHistoryStore;
   /** The connection invoking the command. Reducers mutate this freely. */
   readonly connection: ConnectionState;
   /** Convenience: `connection.id`. */
@@ -147,7 +180,9 @@ export interface BuildCtxOptions {
   ids: IdFactory;
   motd: MotdProvider;
   accounts?: AccountStore;
+  mtlsIdentity?: MtlsIdentityProvider;
   messages?: MessageStore;
+  history?: NickHistoryStore;
   connection: ConnectionState;
 }
 
@@ -163,7 +198,9 @@ export function buildCtx(opts: BuildCtxOptions): Ctx {
     connection: opts.connection,
     connId: opts.connection.id,
     ...(opts.accounts !== undefined ? { accounts: opts.accounts } : {}),
+    ...(opts.mtlsIdentity !== undefined ? { mtlsIdentity: opts.mtlsIdentity } : {}),
     ...(opts.messages !== undefined ? { messages: opts.messages } : {}),
+    ...(opts.history !== undefined ? { history: opts.history } : {}),
   };
   return ctx;
 }

package/packages/irc-core/tests/account-store.test.ts

@@ -65,9 +65,9 @@ describe('InMemoryAccountStore — PLAIN', () => {
 });
 
 describe('InMemoryAccountStore — mechanism handling', () => {
-  it('rejects any non-PLAIN mechanism with a failure result', () => {
+  it('rejects an unsupported mechanism with a failure result', () => {
     const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
-    const out = store.verify('EXTERNAL', { kind: 'RAW', data: 'cert-subject' });
+    const out = store.verify('CRAM-MD5', { kind: 'RAW', data: 'whatever' });
     expect(out.ok).toBe(false);
   });
 
@@ -78,6 +78,49 @@ describe('InMemoryAccountStore — mechanism handling', () => {
   });
 });
 
+describe('InMemoryAccountStore — EXTERNAL (mTLS)', () => {
+  it('maps a known cert subject to its account', () => {
+    const store = new InMemoryAccountStore([
+      { username: 'alice', password: 'secret', certSubject: 'CN=alice' },
+    ]);
+    const out = store.verify('EXTERNAL', { kind: 'EXTERNAL', identity: 'CN=alice' });
+    expect(out).toEqual<SaslResult>({ ok: true, account: 'alice' });
+  });
+
+  it('rejects an unknown cert subject', () => {
+    const store = new InMemoryAccountStore([
+      { username: 'alice', password: 'secret', certSubject: 'CN=alice' },
+    ]);
+    const out = store.verify('EXTERNAL', { kind: 'EXTERNAL', identity: 'CN=evil' });
+    expect(out.ok).toBe(false);
+  });
+
+  it('rejects EXTERNAL when no cert subjects are configured', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('EXTERNAL', { kind: 'EXTERNAL', identity: 'CN=alice' });
+    expect(out.ok).toBe(false);
+  });
+
+  it('treats the mechanism name case-insensitively for EXTERNAL', () => {
+    const store = new InMemoryAccountStore([
+      { username: 'alice', password: 'secret', certSubject: 'CN=alice' },
+    ]);
+    const out = store.verify('external', { kind: 'EXTERNAL', identity: 'CN=alice' });
+    expect(out).toEqual<SaslResult>({ ok: true, account: 'alice' });
+  });
+
+  it('maps multiple accounts with distinct cert subjects', () => {
+    const store = new InMemoryAccountStore([
+      { username: 'alice', password: 'a', certSubject: 'CN=alice' },
+      { username: 'bob', password: 'b', certSubject: 'CN=bob' },
+    ]);
+    expect(store.verify('EXTERNAL', { kind: 'EXTERNAL', identity: 'CN=bob' })).toEqual<SaslResult>({
+      ok: true,
+      account: 'bob',
+    });
+  });
+});
+
 describe('InMemoryAccountStore — failure reason', () => {
   it('returns a human-readable reason on failure', () => {
     const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);

package/packages/irc-core/tests/caps/capabilities.test.ts

@@ -31,10 +31,10 @@ describe('SUPPORTED_CAPABILITIES', () => {
     );
   });
 
-  it('declares the sasl value as the advertised mechanism list', () => {
+  it('declares the sasl value as the base mechanism list (PLAIN only by default)', () => {
     const sasl = SUPPORTED_CAPABILITIES.find((c) => c.name === 'sasl');
     expect(sasl).toBeDefined();
-    expect(sasl?.value).toBe('PLAIN,EXTERNAL');
+    expect(sasl?.value).toBe('PLAIN');
   });
 
   it('does not attach a value to caps that have no parameter', () => {
@@ -107,7 +107,8 @@ describe('getLsString', () => {
   });
 
   it('contains the sasl token with its value', () => {
-    expect(getLsString()).toContain('sasl=PLAIN,EXTERNAL');
+    expect(getLsString()).toContain('sasl=PLAIN');
+    expect(getLsString()).not.toContain('sasl=PLAIN,EXTERNAL');
   });
 
   it('contains server-time as a bare name', () => {

package/packages/irc-core/tests/commands/cap.test.ts

@@ -4,6 +4,7 @@ import { capReducer } from '../../src/commands/cap';
 import { userReducer } from '../../src/commands/registration';
 import { Effect } from '../../src/effects';
 import type { Effect as EffectType, RawLine } from '../../src/effects';
+import type { MtlsIdentityProvider } from '../../src/ports';
 import { EmptyMotdProvider, FakeClock, SequentialIdFactory } from '../../src/ports';
 import { type ConnectionState, createConnection } from '../../src/state/connection';
 import { type Ctx, type ServerConfig, buildCtx } from '../../src/types';
@@ -20,13 +21,18 @@ const serverConfig: ServerConfig = {
   quitMessage: 'Client Quit',
 };
 
-function makeCtx(state: ConnectionState, cfg: ServerConfig = serverConfig): Ctx {
+function makeCtx(
+  state: ConnectionState,
+  cfg: ServerConfig = serverConfig,
+  mtlsIdentity?: MtlsIdentityProvider,
+): Ctx {
   return buildCtx({
     serverConfig: cfg,
     clock: new FakeClock(1_000),
     ids: new SequentialIdFactory(),
     motd: EmptyMotdProvider,
     connection: state,
+    ...(mtlsIdentity !== undefined ? { mtlsIdentity } : {}),
   });
 }
 
@@ -110,6 +116,32 @@ describe('capReducer — LS', () => {
     }
   });
 
+  it('advertises sasl=PLAIN when no mTLS provider is configured', () => {
+    const state = makeState();
+    const ctx = makeCtx(state);
+    const out = capReducer(state, { command: 'CAP', params: ['LS'], tags: {} }, ctx);
+    const send = out.effects[0];
+    expect(send).toBeDefined();
+    if (send?.tag === 'Send') {
+      const body = send.lines[0]?.text ?? '';
+      expect(body).toContain('sasl=PLAIN');
+      expect(body).not.toContain('sasl=PLAIN,EXTERNAL');
+    }
+  });
+
+  it('advertises sasl=PLAIN,EXTERNAL when an mTLS provider is configured', () => {
+    const state = makeState();
+    const provider: MtlsIdentityProvider = { getIdentity: () => 'CN=alice' };
+    const ctx = makeCtx(state, serverConfig, provider);
+    const out = capReducer(state, { command: 'CAP', params: ['LS'], tags: {} }, ctx);
+    const send = out.effects[0];
+    expect(send).toBeDefined();
+    if (send?.tag === 'Send') {
+      const body = send.lines[0]?.text ?? '';
+      expect(body).toContain('sasl=PLAIN,EXTERNAL');
+    }
+  });
+
   it('marks the connection as in CAP negotiation so the welcome is deferred', () => {
     const state = makeState();
     const ctx = makeCtx(state);