serverless-ircd 0.10.0 → 0.11.0

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

@@ -1,7 +1,9 @@
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { getLsString } from '../../src/caps/capabilities';
+import { type CertIdentity, certIdentityFromSubject } from '../../src/certfp';
 import { capReducer } from '../../src/commands/cap';
 import { authenticateReducer } from '../../src/commands/sasl';
+import type { HashedAccountCredential } from '../../src/credential-hashing';
 import { Effect } from '../../src/effects';
 import type { Effect as EffectType, RawLine } from '../../src/effects';
 import type { AwayStore, MtlsIdentityProvider, ServicesStore } from '../../src/ports';
@@ -11,12 +13,16 @@ import {
   InMemoryAwayStore,
   InMemoryServicesStore,
   SequentialIdFactory,
+  resetVerifyNickTimingSpy,
+  setVerifyNickHashedPassword,
 } from '../../src/ports';
 import { encodeBase64 } from '../../src/protocol/base64';
 import type { IrcMessage } from '../../src/protocol/messages';
 import { type ConnectionState, createConnection } from '../../src/state/connection';
 import { type Ctx, type ServerConfig, buildCtx } from '../../src/types';
 
+type VerifyHashedPasswordFn = (password: string, entry: HashedAccountCredential) => boolean;
+
 const serverConfig: ServerConfig = {
   serverName: 'irc.example.com',
   networkName: 'ExampleNet',
@@ -29,6 +35,17 @@ const serverConfig: ServerConfig = {
   quitMessage: 'Client Quit',
 };
 
+/**
+ * Config with SASL EXTERNAL opted in — mirrors an operator setting the
+ * adapters' `EXTERNAL_ENABLED` env var. The mTLS-backed EXTERNAL tests
+ * bind this so they exercise the enabled path; the opt-in/secure-connection
+ * gate tests build their own configs explicitly.
+ */
+const externalServerConfig: ServerConfig = {
+  ...serverConfig,
+  sasl: { externalEnabled: true },
+};
+
 const L = (text: string): RawLine => ({ text });
 
 const SV = 'irc.example.com';
@@ -43,6 +60,10 @@ function saslReadyState(): ConnectionState {
   s.registration = 'registering';
   s.capNegotiating = true;
   s.caps.add('sasl');
+  // SASL EXTERNAL requires a secure (TLS) transport; the standard helper
+  // models the common secure client so the EXTERNAL describe inherits it.
+  // The insecure-connection gate has its own explicit test.
+  s.secure = true;
   return s;
 }
 
@@ -67,7 +88,11 @@ function makeCtx(
   away?: AwayStore,
 ): Ctx {
   return buildCtx({
-    serverConfig,
+    // A test that binds an mTLS provider intends to exercise the EXTERNAL
+    // path, so it gets the EXTERNAL-enabled config (mirrors an operator
+    // setting EXTERNAL_ENABLED). The gate matrix tests below build their
+    // own ctxs to control the flag explicitly.
+    serverConfig: mtlsIdentity !== undefined ? externalServerConfig : serverConfig,
     clock: new FakeClock(1_000),
     ids: new SequentialIdFactory(),
     motd: EmptyMotdProvider,
@@ -83,11 +108,14 @@ class FakeMtlsIdentityProvider implements MtlsIdentityProvider {
   readonly calls: string[] = [];
   constructor(
     private readonly connId: string,
-    private readonly identity: string | undefined,
+    private readonly subject: string | undefined,
+    private readonly fingerprint?: string,
   ) {}
-  getIdentity(connId: string): string | undefined {
+  getIdentity(connId: string): CertIdentity | undefined {
     this.calls.push(connId);
-    return connId === this.connId ? this.identity : undefined;
+    return connId === this.connId && this.subject !== undefined
+      ? certIdentityFromSubject(this.subject, this.fingerprint)
+      : undefined;
   }
 }
 
@@ -465,6 +493,57 @@ describe('authenticateReducer — PLAIN failure', () => {
   });
 });
 
+// ============================================================================
+// AUTHENTICATE PLAIN — timing equalisation (username-enumeration defence).
+// The unknown-username and wrong-password paths must perform the SAME
+// number of scrypt verifies (one each) and emit the identical 904 line, so
+// a remote attacker cannot distinguish "user exists, wrong password" from
+// "user unknown" by measuring latency between AUTHENTICATE and 904.
+// ============================================================================
+
+describe('authenticateReducer — PLAIN timing equalisation (username enumeration)', () => {
+  afterEach(() => {
+    resetVerifyNickTimingSpy();
+  });
+
+  function runPlainFailure(
+    authcid: string,
+    password: string,
+  ): { verifyCalls: number; line: string } {
+    const spy = vi.fn<VerifyHashedPasswordFn>(() => false);
+    setVerifyNickHashedPassword(spy);
+    let out: { verifyCalls: number; line: string };
+    try {
+      const state = saslReadyState();
+      const ctx = makeCtx(state, registeredServices('alice', 'secret'));
+      authenticateReducer(state, authenticate('PLAIN'), ctx);
+      const result = authenticateReducer(state, authenticate(plainPayload(authcid, password)), ctx);
+      out = { verifyCalls: spy.mock.calls.length, line: firstLineText(result.effects[0]) };
+    } finally {
+      setVerifyNickHashedPassword(null);
+    }
+    return out;
+  }
+
+  it('runs exactly one scrypt verify on the unknown-username path (no O(1) miss)', () => {
+    const { verifyCalls } = runPlainFailure('definitely-not-a-user', 'secret');
+    expect(verifyCalls).toBe(1);
+  });
+
+  it('runs exactly one scrypt verify on the wrong-password path', () => {
+    const { verifyCalls } = runPlainFailure('alice', 'wrong');
+    expect(verifyCalls).toBe(1);
+  });
+
+  it('emits the identical 904 ERR_SASLFAIL on both paths with equal verify cost', () => {
+    const unknownUser = runPlainFailure('definitely-not-a-user', 'secret');
+    const wrongPassword = runPlainFailure('alice', 'wrong');
+    expect(unknownUser.verifyCalls).toBe(wrongPassword.verifyCalls);
+    expect(unknownUser.line).toBe(`:${SV} 904 alice :SASL authentication failed`);
+    expect(wrongPassword.line).toBe(unknownUser.line);
+  });
+});
+
 // ============================================================================
 // AUTHENTICATE PLAIN — no ServicesStore wired
 // ============================================================================
@@ -526,7 +605,7 @@ describe('authenticateReducer — EXTERNAL with mTLS', () => {
     ]);
   });
 
-  it('forwards the resolved mTLS subject to services.verifyCertFP', () => {
+  it('forwards the resolved mTLS identity to services.verifyCertFP', () => {
     const state = saslReadyState();
     const services = registeredServices('alice', 'secret');
     services.addCertFP('alice', 'CN=alice');
@@ -537,7 +616,41 @@ describe('authenticateReducer — EXTERNAL with mTLS', () => {
     authenticateReducer(state, authenticate('EXTERNAL'), ctx);
     authenticateReducer(state, authenticate('+'), ctx);
 
-    expect(verifyCertFP).toHaveBeenCalledWith('CN=alice');
+    expect(verifyCertFP).toHaveBeenCalledWith(certIdentityFromSubject('CN=alice'));
+  });
+
+  it('forwards the platform fingerprint on the identity to verifyCertFP', () => {
+    const state = saslReadyState();
+    const services = registeredServices('alice', 'secret');
+    services.addCertFingerprint('alice', 'aa112233');
+    const verifyCertFP = vi.spyOn(services, 'verifyCertFP');
+    const provider = new FakeMtlsIdentityProvider('c1', 'CN=alice', 'aa112233');
+    const ctx = makeCtx(state, services, provider);
+
+    authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+    authenticateReducer(state, authenticate('+'), ctx);
+
+    expect(verifyCertFP).toHaveBeenCalledWith(
+      expect.objectContaining({ subject: 'CN=alice', fingerprint: 'aa112233' }),
+    );
+    expect(state.account).toBe('alice');
+  });
+
+  it('succeeds via an equivalent DN spelling (canonical compare)', () => {
+    const state = saslReadyState();
+    const services = registeredServices('alice', 'secret');
+    services.addCertFP('alice', 'CN=alice ,  O = Example Inc');
+    const provider = new FakeMtlsIdentityProvider('c1', 'O=Example Inc,CN=alice');
+    const ctx = makeCtx(state, services, provider);
+
+    authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+    const out = authenticateReducer(state, authenticate('+'), ctx);
+
+    expect(state.account).toBe('alice');
+    expect(sendLinesOf(out.effects[0])).toEqual<RawLine[]>([
+      L(`:${SV} 900 alice alice!alice@example.com alice :You are now logged in as alice`),
+      L(`:${SV} 903 alice :SASL authentication successful`),
+    ]);
   });
 
   it('clears saslMech/saslBuffer after a successful EXTERNAL', () => {
@@ -635,6 +748,223 @@ describe('authenticateReducer — EXTERNAL with mTLS', () => {
   });
 });
 
+// ============================================================================
+// AUTHENTICATE EXTERNAL — operator opt-in + secure-connection gate
+// ============================================================================
+
+describe('authenticateReducer — EXTERNAL opt-in / secure-connection gate', () => {
+  /** Builds a ctx with full control over the sasl config + transport. */
+  function gateCtx(
+    state: ConnectionState,
+    opts: { externalEnabled: boolean; provider?: MtlsIdentityProvider },
+  ): Ctx {
+    return buildCtx({
+      serverConfig: { ...serverConfig, sasl: { externalEnabled: opts.externalEnabled } },
+      clock: new FakeClock(1_000),
+      ids: new SequentialIdFactory(),
+      motd: EmptyMotdProvider,
+      connection: state,
+      ...(opts.provider !== undefined ? { mtlsIdentity: opts.provider } : {}),
+    });
+  }
+
+  it('refuses EXTERNAL with 908 when the flag is unset, even with mTLS on a secure connection', () => {
+    const state = saslReadyState();
+    const provider = new FakeMtlsIdentityProvider('c1', 'CN=alice');
+    const ctx = gateCtx(state, { externalEnabled: false, provider });
+    const out = authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+
+    expect(sendLinesOf(out.effects[0])).toEqual<RawLine[]>([
+      L(`:${SV} 908 alice PLAIN :are the available SASL mechanisms`),
+    ]);
+    expect(state.saslMech).toBeUndefined();
+  });
+
+  it('refuses EXTERNAL with 908 when the sasl block omits the flag entirely', () => {
+    // A deployment may set other sasl knobs (lockout tuning) without the
+    // EXTERNAL opt-in; the flag defaults off — absence is not consent.
+    const state = saslReadyState();
+    const provider = new FakeMtlsIdentityProvider('c1', 'CN=alice');
+    const ctx = buildCtx({
+      serverConfig: { ...serverConfig, sasl: { maxFailures: 3 } },
+      clock: new FakeClock(1_000),
+      ids: new SequentialIdFactory(),
+      motd: EmptyMotdProvider,
+      connection: state,
+      mtlsIdentity: provider,
+    });
+    const out = authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+
+    expect(sendLinesOf(out.effects[0])).toEqual<RawLine[]>([
+      L(`:${SV} 908 alice PLAIN :are the available SASL mechanisms`),
+    ]);
+    expect(state.saslMech).toBeUndefined();
+  });
+
+  it('refuses EXTERNAL with 908 on an insecure connection even when the flag is enabled', () => {
+    const state = saslReadyState();
+    state.secure = false;
+    const provider = new FakeMtlsIdentityProvider('c1', 'CN=alice');
+    const ctx = gateCtx(state, { externalEnabled: true, provider });
+    const out = authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+
+    expect(sendLinesOf(out.effects[0])).toEqual<RawLine[]>([
+      L(`:${SV} 908 alice PLAIN :are the available SASL mechanisms`),
+    ]);
+    expect(state.saslMech).toBeUndefined();
+  });
+
+  it('does not count the 908 opt-in / secure-connection refusal toward the lockout', () => {
+    // A protocol-level mechanism rejection is not a credential attempt;
+    // an attacker probing EXTERNAL on an insecure transport must not be
+    // able to burn the failure budget (nor succeed by accident).
+    const state = saslReadyState();
+    state.secure = false;
+    const provider = new FakeMtlsIdentityProvider('c1', 'CN=alice');
+    const ctx = gateCtx(state, { externalEnabled: true, provider });
+
+    for (let i = 0; i < 3; i++) {
+      const out = authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+      expect(firstLineText(out.effects[0])).toContain(' 908 ');
+    }
+    expect(state.saslFailures).toBeUndefined();
+  });
+
+  it('enters the payload phase when the flag is enabled on a secure connection with mTLS', () => {
+    const state = saslReadyState();
+    const provider = new FakeMtlsIdentityProvider('c1', 'CN=alice');
+    const ctx = gateCtx(state, { externalEnabled: true, provider });
+    const out = authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+
+    expect(state.saslMech).toBe('EXTERNAL');
+    expect(sendLinesOf(out.effects[0])).toEqual<RawLine[]>([L('AUTHENTICATE +')]);
+  });
+
+  it('succeeds (900/903) with a bound cert on a secure, EXTERNAL-enabled connection', () => {
+    const state = saslReadyState();
+    const services = registeredServices('alice', 'secret');
+    services.addCertFingerprint('alice', 'aa112233445566778899aabbccddeeff');
+    const provider = new FakeMtlsIdentityProvider(
+      'c1',
+      'CN=alice',
+      'AA:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF',
+    );
+    const ctx = buildCtx({
+      serverConfig: externalServerConfig,
+      clock: new FakeClock(1_000),
+      ids: new SequentialIdFactory(),
+      motd: EmptyMotdProvider,
+      connection: state,
+      services,
+      mtlsIdentity: provider,
+    });
+
+    authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+    const out = authenticateReducer(state, authenticate('+'), ctx);
+
+    expect(state.account).toBe('alice');
+    expect(sendLinesOf(out.effects[0])).toEqual<RawLine[]>([
+      L(`:${SV} 900 alice alice!alice@example.com alice :You are now logged in as alice`),
+      L(`:${SV} 903 alice :SASL authentication successful`),
+    ]);
+  });
+
+  it('fails with 904 on a secure, EXTERNAL-enabled connection when no binding matches the cert', () => {
+    const state = saslReadyState();
+    const services = registeredServices('alice', 'secret');
+    // alice has no cert binding; the presented cert is unknown to the store.
+    const provider = new FakeMtlsIdentityProvider('c1', 'CN=intruder');
+    const ctx = buildCtx({
+      serverConfig: externalServerConfig,
+      clock: new FakeClock(1_000),
+      ids: new SequentialIdFactory(),
+      motd: EmptyMotdProvider,
+      connection: state,
+      services,
+      mtlsIdentity: provider,
+    });
+
+    authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+    const out = authenticateReducer(state, authenticate('+'), ctx);
+
+    expect(sendLinesOf(out.effects[0])).toEqual<RawLine[]>([
+      L(`:${SV} 904 alice :SASL authentication failed`),
+    ]);
+    expect(state.account).toBeUndefined();
+    expect(state.saslFailures).toEqual([1_000]);
+  });
+});
+
+// ============================================================================
+// AUTHENTICATE EXTERNAL — transport-level non-support override
+// ============================================================================
+
+describe('authenticateReducer — EXTERNAL transport-level non-support override', () => {
+  /**
+   * Builds a ctx carrying the transport-level EXTERNAL non-support
+   * override — the seam a transport with no mTLS identity source (the
+   * Spectrum TCP container origin) uses to reject
+   * `AUTHENTICATE EXTERNAL` with an explicit, stable `904` instead of
+   * the generic three-way-gate `908`.
+   */
+  function unsupportedCtx(state: ConnectionState): Ctx {
+    return buildCtx({
+      serverConfig: {
+        ...serverConfig,
+        sasl: {
+          externalEnabled: true,
+          externalUnsupportedMessage: 'SASL EXTERNAL not supported on this transport',
+        },
+      },
+      clock: new FakeClock(1_000),
+      ids: new SequentialIdFactory(),
+      motd: EmptyMotdProvider,
+      connection: state,
+      mtlsIdentity: new FakeMtlsIdentityProvider('c1', 'CN=alice'),
+    });
+  }
+
+  it('rejects EXTERNAL with the configured 904 message even when the three-way gate holds', () => {
+    // The override is authoritative: a transport that cannot surface a
+    // client-cert identity must reject up front with the transport-
+    // specific message, never fall through to the generic refusal —
+    // even if every gate input (mTLS source, opt-in, secure) is bound.
+    const state = saslReadyState();
+    const ctx = unsupportedCtx(state);
+    const out = authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+
+    expect(sendLinesOf(out.effects[0])).toEqual<RawLine[]>([
+      L(`:${SV} 904 alice :SASL EXTERNAL not supported on this transport`),
+    ]);
+    expect(state.saslMech).toBeUndefined();
+  });
+
+  it('does not count the transport-level 904 toward the failure lockout', () => {
+    // A transport-capability rejection is not a credential attempt; a
+    // client probing EXTERNAL must not burn the SASL failure budget.
+    const state = saslReadyState();
+    const ctx = unsupportedCtx(state);
+
+    for (let i = 0; i < 3; i++) {
+      const out = authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+      expect(firstLineText(out.effects[0])).toContain(
+        ' 904 alice :SASL EXTERNAL not supported on this transport',
+      );
+    }
+    expect(state.saslFailures).toBeUndefined();
+  });
+
+  it('lists PLAIN only in 908 when the transport override is set', () => {
+    const state = saslReadyState();
+    const ctx = unsupportedCtx(state);
+    const out = authenticateReducer(state, authenticate('CRAM-MD5'), ctx);
+
+    expect(sendLinesOf(out.effects[0])).toEqual<RawLine[]>([
+      L(`:${SV} 908 alice PLAIN :are the available SASL mechanisms`),
+    ]);
+  });
+});
+
 // ============================================================================
 // AUTHENTICATE <unknown mechanism>
 // ============================================================================
@@ -954,3 +1284,262 @@ describe('authenticateReducer — NickServ-registered nick via ServicesStore', (
     expect(firstLineText(out.effects[0])).toBe(`:${SV} 904 alice :SASL authentication failed`);
   });
 });
+
+// ============================================================================
+// Per-connection SASL failure lockout (brute-force hardening)
+// ============================================================================
+
+/** Disconnect reason the reducer stamps once the failure lockout trips. */
+const SASL_LOCKOUT_REASON = 'too many failed SASL attempts';
+
+describe('authenticateReducer — per-connection SASL failure lockout', () => {
+  /**
+   * Ctx builder with injectable clock + config so window/threshold tests can
+   * advance time and override `sasl.maxFailures` / `sasl.failureWindowSeconds`.
+   */
+  function lockoutCtx(
+    state: ConnectionState,
+    clock: FakeClock,
+    config: ServerConfig = serverConfig,
+  ): Ctx {
+    return buildCtx({
+      serverConfig: config,
+      clock,
+      ids: new SequentialIdFactory(),
+      motd: EmptyMotdProvider,
+      connection: state,
+      services: registeredServices('alice', 'secret'),
+    });
+  }
+
+  /** Drives one full failed PLAIN exchange; returns the payload-frame effects. */
+  function failedAttempt(state: ConnectionState, ctx: Ctx): EffectType[] {
+    authenticateReducer(state, authenticate('PLAIN'), ctx);
+    const out = authenticateReducer(state, authenticate(plainPayload('alice', 'wrong')), ctx);
+    return out.effects;
+  }
+
+  it('emits 904 without a disconnect for the first two failed attempts', () => {
+    const state = saslReadyState();
+    const ctx = lockoutCtx(state, new FakeClock(1_000));
+
+    const first = failedAttempt(state, ctx);
+    expect(first).toEqual<EffectType[]>([
+      Effect.send('c1', [L(`:${SV} 904 alice :SASL authentication failed`)]),
+    ]);
+
+    const second = failedAttempt(state, ctx);
+    expect(second).toEqual<EffectType[]>([
+      Effect.send('c1', [L(`:${SV} 904 alice :SASL authentication failed`)]),
+    ]);
+  });
+
+  it('records failed-attempt timestamps on the connection state', () => {
+    const state = saslReadyState();
+    const ctx = lockoutCtx(state, new FakeClock(1_000));
+
+    failedAttempt(state, ctx);
+    failedAttempt(state, ctx);
+
+    expect(state.saslFailures).toEqual([1_000, 1_000]);
+  });
+
+  it('disconnects after the third failed attempt, 904 delivered first', () => {
+    const state = saslReadyState();
+    const ctx = lockoutCtx(state, new FakeClock(1_000));
+
+    failedAttempt(state, ctx);
+    failedAttempt(state, ctx);
+    const third = failedAttempt(state, ctx);
+
+    expect(third).toEqual<EffectType[]>([
+      Effect.send('c1', [L(`:${SV} 904 alice :SASL authentication failed`)]),
+      Effect.disconnect('c1', SASL_LOCKOUT_REASON),
+    ]);
+  });
+
+  it('honours a configured sasl.maxFailures override', () => {
+    const config: ServerConfig = { ...serverConfig, sasl: { maxFailures: 2 } };
+    const state = saslReadyState();
+    const ctx = lockoutCtx(state, new FakeClock(1_000), config);
+
+    failedAttempt(state, ctx);
+    const second = failedAttempt(state, ctx);
+
+    expect(second).toEqual<EffectType[]>([
+      Effect.send('c1', [L(`:${SV} 904 alice :SASL authentication failed`)]),
+      Effect.disconnect('c1', SASL_LOCKOUT_REASON),
+    ]);
+  });
+
+  it('does not trip when prior failures fall outside the window (sliding window)', () => {
+    const state = saslReadyState();
+    const clock = new FakeClock(1_000);
+    const ctx = lockoutCtx(state, clock);
+
+    failedAttempt(state, ctx); // t = 1_000
+    clock.advance(30_000);
+    failedAttempt(state, ctx); // t = 31_000
+    clock.advance(31_000);
+    const third = failedAttempt(state, ctx); // t = 62_000; t = 1_000 is 61s old → pruned
+
+    expect(third).toEqual<EffectType[]>([
+      Effect.send('c1', [L(`:${SV} 904 alice :SASL authentication failed`)]),
+    ]);
+    expect(state.saslFailures).toEqual([31_000, 62_000]);
+  });
+
+  it('trips once three failures land inside the window again after pruning', () => {
+    const state = saslReadyState();
+    const clock = new FakeClock(1_000);
+    const ctx = lockoutCtx(state, clock);
+
+    failedAttempt(state, ctx); // t = 1_000
+    clock.advance(30_000);
+    failedAttempt(state, ctx); // t = 31_000
+    clock.advance(31_000);
+    failedAttempt(state, ctx); // t = 62_000 (count: 2)
+    clock.advance(1_000);
+    const tripping = failedAttempt(state, ctx); // t = 63_000 (31_000/62_000/63_000 in window)
+
+    expect(tripping).toEqual<EffectType[]>([
+      Effect.send('c1', [L(`:${SV} 904 alice :SASL authentication failed`)]),
+      Effect.disconnect('c1', SASL_LOCKOUT_REASON),
+    ]);
+  });
+
+  it('honours a configured sasl.failureWindowSeconds override', () => {
+    const config: ServerConfig = { ...serverConfig, sasl: { failureWindowSeconds: 1 } };
+    const state = saslReadyState();
+    const clock = new FakeClock(1_000);
+    const ctx = lockoutCtx(state, clock, config);
+
+    failedAttempt(state, ctx); // t = 1_000
+    clock.advance(1_100);
+    failedAttempt(state, ctx); // t = 2_100 (t = 1_000 pruned)
+    clock.advance(1_100);
+    const third = failedAttempt(state, ctx); // t = 3_200 (t = 2_100 pruned)
+
+    expect(third).toEqual<EffectType[]>([
+      Effect.send('c1', [L(`:${SV} 904 alice :SASL authentication failed`)]),
+    ]);
+    expect(state.saslFailures).toEqual([3_200]);
+  });
+
+  it('resets the failure counter after a successful authentication', () => {
+    const state = saslReadyState();
+    const ctx = lockoutCtx(state, new FakeClock(1_000));
+
+    failedAttempt(state, ctx);
+    failedAttempt(state, ctx);
+    expect(state.saslFailures).toEqual([1_000, 1_000]);
+
+    authenticateReducer(state, authenticate('PLAIN'), ctx);
+    authenticateReducer(state, authenticate(plainPayload('alice', 'secret')), ctx);
+
+    expect(state.account).toBe('alice');
+    expect(state.saslFailures).toBeUndefined();
+  });
+
+  it('does not count AUTHENTICATE * (abort) as a failure or reset the counter', () => {
+    const state = saslReadyState();
+    const ctx = lockoutCtx(state, new FakeClock(1_000));
+
+    failedAttempt(state, ctx); // count: 1
+
+    // Abort mid-exchange: clears the exchange scratch state but must neither
+    // count as a failure nor let the attacker launder the counter away.
+    authenticateReducer(state, authenticate('PLAIN'), ctx);
+    const abortOut = authenticateReducer(state, authenticate('*'), ctx);
+    expect(firstLineText(abortOut.effects[0])).toContain(' 906 ');
+
+    failedAttempt(state, ctx); // count: 2 — no disconnect yet
+    const third = failedAttempt(state, ctx); // count: 3 → trips
+
+    expect(third).toEqual<EffectType[]>([
+      Effect.send('c1', [L(`:${SV} 904 alice :SASL authentication failed`)]),
+      Effect.disconnect('c1', SASL_LOCKOUT_REASON),
+    ]);
+  });
+
+  it('does not count 908 unknown-mechanism rejections toward the lockout', () => {
+    const state = saslReadyState();
+    const ctx = lockoutCtx(state, new FakeClock(1_000));
+
+    for (let i = 0; i < 3; i++) {
+      authenticateReducer(state, authenticate('CRAM-MD5'), ctx);
+    }
+
+    const attempt = failedAttempt(state, ctx);
+    expect(attempt).toEqual<EffectType[]>([
+      Effect.send('c1', [L(`:${SV} 904 alice :SASL authentication failed`)]),
+    ]);
+    expect(state.saslFailures).toEqual([1_000]);
+  });
+
+  it('does not count 905 ERR_SASLTOOLONG rejections toward the lockout', () => {
+    const state = saslReadyState();
+    const ctx = lockoutCtx(state, new FakeClock(1_000));
+
+    for (let i = 0; i < 3; i++) {
+      authenticateReducer(state, authenticate('PLAIN'), ctx);
+      const out = authenticateReducer(state, authenticate(`${'A'.repeat(8193)}`), ctx);
+      expect(firstLineText(out.effects[0])).toContain(' 905 ');
+    }
+
+    const attempt = failedAttempt(state, ctx);
+    expect(attempt).toEqual<EffectType[]>([
+      Effect.send('c1', [L(`:${SV} 904 alice :SASL authentication failed`)]),
+    ]);
+    expect(state.saslFailures).toEqual([1_000]);
+  });
+
+  it('counts malformed-base64 904 failures toward the lockout', () => {
+    const state = saslReadyState();
+    const ctx = lockoutCtx(state, new FakeClock(1_000));
+
+    for (let i = 0; i < 2; i++) {
+      authenticateReducer(state, authenticate('PLAIN'), ctx);
+      const out = authenticateReducer(state, authenticate('!!!notbase64!!!'), ctx);
+      expect(firstLineText(out.effects[0])).toContain(' 904 ');
+    }
+
+    const third = failedAttempt(state, ctx);
+    expect(third).toEqual<EffectType[]>([
+      Effect.send('c1', [L(`:${SV} 904 alice :SASL authentication failed`)]),
+      Effect.disconnect('c1', SASL_LOCKOUT_REASON),
+    ]);
+  });
+
+  it('counts EXTERNAL verification failures toward the lockout', () => {
+    const state = saslReadyState();
+    const services = registeredServices('alice', 'secret');
+    const provider = new FakeMtlsIdentityProvider('c1', undefined);
+    const clock = new FakeClock(1_000);
+    const ctx = buildCtx({
+      // EXTERNAL must be opted in for the exchange to reach the verify
+      // step whose failure the lockout counts.
+      serverConfig: externalServerConfig,
+      clock,
+      ids: new SequentialIdFactory(),
+      motd: EmptyMotdProvider,
+      connection: state,
+      services,
+      mtlsIdentity: provider,
+    });
+
+    for (let i = 0; i < 2; i++) {
+      authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+      const out = authenticateReducer(state, authenticate('+'), ctx);
+      expect(firstLineText(out.effects[0])).toContain(' 904 ');
+    }
+
+    authenticateReducer(state, authenticate('EXTERNAL'), ctx);
+    const third = authenticateReducer(state, authenticate('+'), ctx);
+
+    expect(third.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(`:${SV} 904 alice :SASL authentication failed`)]),
+      Effect.disconnect('c1', SASL_LOCKOUT_REASON),
+    ]);
+  });
+});