serverless-ircd 0.10.0 → 0.11.0

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

@@ -8,6 +8,7 @@
 
 import type { Effect } from './effects.js';
 import type { FloodControlConfig } from './flood-control.js';
+import type { OperFailureStats } from './oper-lockout.js';
 import type {
   AwayStore,
   Clock,
@@ -52,16 +53,67 @@ export interface StsConfig {
 }
 
 /**
- * A single IRC operator credential. The {@link operReducer} consults the
- * configured list to authenticate `OPER <name> <password>`. Both fields are
- * compared verbatim; adapters are responsible for any hashing at the auth
- * boundary if they layer one on top.
+ * Legacy plaintext IRC operator credential (DEPRECATED — retained for a
+ * single deprecation-cycle window).
+ *
+ * The {@link operReducer} still verifies this shape via timing-safe byte
+ * comparison, but emits a one-shot `warn` per boot when it is encountered.
+ * Migrate to {@link OperCredHashed} via `tools/hash-oper-cred.ts`; this
+ * form will be removed in a future release.
  */
-export interface OperCred {
+export interface OperCredPlaintext {
   readonly user: string;
   readonly password: string;
 }
 
+/**
+ * At-rest hashed IRC operator credential (the recommended shape).
+ *
+ * `salt` and `hash` are base64 strings produced by
+ * `tools/hash-oper-cred.ts` (which wraps {@link hashAccountCredential}'s
+ * scrypt derivation). The {@link operReducer} verifies via the shared
+ * {@link verifyHashedPassword} with `timingSafeEqual`, mirroring the
+ * NickServ / SASL PLAIN credential path.
+ */
+export interface OperCredHashed {
+  readonly user: string;
+  readonly salt: string;
+  readonly hash: string;
+}
+
+/**
+ * A single IRC operator credential. Either the at-rest hashed form
+ * ({@link OperCredHashed}, recommended) or the legacy plaintext form
+ * ({@link OperCredPlaintext}, deprecated — retained for a single
+ * deprecation-cycle window). The {@link operReducer} consults whichever
+ * shape is present; adapters are responsible for any hashing at the auth
+ * boundary if they layer one on top.
+ */
+export type OperCred = OperCredHashed | OperCredPlaintext;
+
+/**
+ * Per-IP failed-`OPER` lockout tunables as seen by reducers. Mirrors the
+ * `oper` sub-schema of {@link ServerConfigSchema}; the OPER reducer reads
+ * `maxFailures` / `failureWindowSeconds` (falling back to the documented
+ * defaults when unset).
+ *
+ * Optional fields are widened to `T | undefined` to mirror Zod's
+ * `.optional()` output under `exactOptionalPropertyTypes: true`.
+ */
+export interface OperThrottleConfig {
+  /**
+   * Consecutive failed `OPER` attempts (per host, per window) that trip
+   * the lockout. Omitted → the reducer falls back to
+   * {@link DEFAULT_OPER_MAX_FAILURES} (3).
+   */
+  readonly maxFailures?: number | undefined;
+  /**
+   * Sliding window length in seconds. Omitted → the reducer falls back to
+   * {@link DEFAULT_OPER_FAILURE_WINDOW_SECONDS} (300).
+   */
+  readonly failureWindowSeconds?: number | undefined;
+}
+
 /**
  * NickServ-specific tunables as seen by reducers. Mirrors the
  * `nickServ` sub-schema of {@link ServerConfigSchema}; the NickServ
@@ -78,6 +130,84 @@ export interface NickServConfig {
    * {@link DEFAULT_MIN_PASSWORD_LENGTH} (8).
    */
   readonly minPasswordLength?: number | undefined;
+  /**
+   * Failed-IDENTIFY threshold that freezes the account. Omitted → the
+   * NickServ IDENTIFY reducer falls back to
+   * {@link DEFAULT_MAX_IDENTIFY_FAILURES} (5).
+   */
+  readonly maxIdentifyFailures?: number | undefined;
+  /**
+   * Sliding window (seconds) the failed-IDENTIFY threshold counts
+   * within. Omitted → the reducer falls back to
+   * {@link DEFAULT_IDENTIFY_FREEZE_SECONDS} (300).
+   */
+  readonly identifyFreezeSeconds?: number | undefined;
+}
+
+/**
+ * SASL brute-force hardening tunables as seen by reducers. Mirrors the
+ * `sasl` sub-schema of {@link ServerConfigSchema}; the SASL reducer reads
+ * them to trip a per-connection lockout after too many failed
+ * `AUTHENTICATE` attempts (falling back to the documented defaults when
+ * unset).
+ *
+ * Optional fields are widened to `T | undefined` to mirror Zod's
+ * `.optional()` output under `exactOptionalPropertyTypes: true`.
+ */
+export interface SaslConfig {
+  /**
+   * Failed `AUTHENTICATE` attempts (per connection, within the sliding
+   * window) before the connection is disconnected. Omitted → the reducer
+   * falls back to {@link DEFAULT_SASL_MAX_FAILURES} (3).
+   */
+  readonly maxFailures?: number | undefined;
+  /**
+   * Sliding-window length (seconds) the failure tracker counts within.
+   * Failures older than the window no longer count. Omitted → the reducer
+   * falls back to {@link DEFAULT_SASL_FAILURE_WINDOW_SECONDS} (60).
+   */
+  readonly failureWindowSeconds?: number | undefined;
+  /**
+   * Operator opt-in for the certificate-backed SASL EXTERNAL mechanism.
+   * Omitted → EXTERNAL is neither advertised nor accepted (the reducers
+   * treat absence as `false`). Enabling additionally requires a bound
+   * mTLS identity source and a secure (TLS) connection — see the
+   * AUTHENTICATE reducer. The adapters surface this as the
+   * `EXTERNAL_ENABLED` env var.
+   */
+  readonly externalEnabled?: boolean | undefined;
+  /**
+   * Transport-level EXTERNAL non-support override. When set (by an
+   * adapter whose transport cannot surface a client-cert identity —
+   * e.g. the Spectrum PROXY-v1 TCP container origin), SASL EXTERNAL is
+   * hard-disabled for the deployment: the `sasl` cap and `908
+   * ERR_SASLMECHS` list `PLAIN` only, and `AUTHENTICATE EXTERNAL` is
+   * rejected up front with `904 ERR_SASLFAIL` carrying this exact
+   * message (a stable, transport-specific refusal) — even if
+   * {@link externalEnabled} and every three-way-gate input is bound.
+   * The rejection is a protocol-level refusal, not a credential
+   * attempt: it does not count toward the per-connection SASL failure
+   * lockout.
+   */
+  readonly externalUnsupportedMessage?: string | undefined;
+}
+
+/**
+ * `draft/chathistory` tunables as seen by reducers. Mirrors the
+ * `chathistory` sub-schema of {@link ServerConfigSchema}; the CHATHISTORY
+ * reducer caps every client-supplied query limit at `maxLimit` (falling
+ * back to {@link DEFAULT_MAX_CHATHISTORY_LIMIT} when unset).
+ *
+ * Optional fields are widened to `T | undefined` to mirror Zod's
+ * `.optional()` output under `exactOptionalPropertyTypes: true`.
+ */
+export interface ChathistoryConfig {
+  /**
+   * Maximum number of messages one `CHATHISTORY` query may return.
+   * Omitted → the reducer falls back to
+   * {@link DEFAULT_MAX_CHATHISTORY_LIMIT} (100).
+   */
+  readonly maxLimit?: number | undefined;
 }
 
 /**
@@ -131,6 +261,17 @@ export interface ServerConfig {
    * here.
    */
   readonly operCreds?: ReadonlyArray<OperCred> | undefined;
+  /**
+   * Per-IP failed-`OPER` lockout tunables consulted by the `OPER`
+   * reducer's brute-force gate. Omitted (or field-omitted) values fall
+   * back to the documented defaults (3 failures / 300s window); the
+   * parsed config always supplies both fields (schema defaults).
+   *
+   * Typed `OperThrottleConfig | undefined` to mirror Zod's `.optional()`
+   * output shape under `exactOptionalPropertyTypes: true` so inline
+   * `ServerConfig` literals in tests may omit it.
+   */
+  readonly oper?: OperThrottleConfig | undefined;
   maxChannelsPerUser: number;
   maxTargetsPerCommand: number;
   maxListEntries: number;
@@ -183,6 +324,18 @@ export interface ServerConfig {
    * literals in tests may omit it.
    */
   readonly multilineMaxBytes?: number | undefined;
+  /**
+   * Per-batch entry ceiling for IRCv3 `draft/multiline`. Enforced
+   * incrementally on each accumulated inner line — together with
+   * {@link ServerConfig.multilineMaxBytes} — so a client cannot hold an
+   * unbounded batch open. Defaults to
+   * {@link DEFAULT_MULTILINE_MAX_ENTRIES} (100) when omitted.
+   *
+   * Typed `number | undefined` to mirror Zod's optional output shape under
+   * `exactOptionalPropertyTypes: true` so inline `ServerConfig` literals in
+   * tests may omit it.
+   */
+  readonly multilineMaxEntries?: number | undefined;
   /**
    * Per-connection MONITOR watchlist ceiling, advertised as `MONITOR=<n>`
    * in `005 RPL_ISUPPORT`. Omitted → the reducer falls back to
@@ -240,18 +393,58 @@ export interface ServerConfig {
    */
   readonly nickServ?: NickServConfig | undefined;
   /**
-   * HostServ approval mode for `REQUEST <vhost>`. `true` (the parsed
-   * default) preserves the legacy auto-approve behaviour — the vhost is
-   * recorded against the account immediately, no oper review. `false`
-   * switches HostServ into oper-queue mode: `REQUEST` queues a pending
-   * request that an oper must `APPROVE` (or `REJECT`); `LIST` enumerates
-   * the pending queue. See `docs/Services.md` §6.
+   * SASL brute-force hardening tunables consulted by the SASL reducer:
+   * `maxFailures` failed `AUTHENTICATE` attempts within
+   * `failureWindowSeconds` disconnect the connection. Omitted entirely →
+   * the reducer falls back to the documented defaults (3 failures / 60 s).
+   *
+   * Typed `SaslConfig | undefined` to mirror Zod's `.optional()` output
+   * under `exactOptionalPropertyTypes: true` so inline `ServerConfig`
+   * literals in tests may omit it.
+   */
+  readonly sasl?: SaslConfig | undefined;
+  /**
+   * `draft/chathistory` tunables consulted by the CHATHISTORY reducer.
+   * Every client-supplied query limit is silently capped at
+   * `maxLimit`; omitted entirely → the documented default ceiling (100).
+   *
+   * Typed `ChathistoryConfig | undefined` to mirror Zod's `.optional()`
+   * output shape under `exactOptionalPropertyTypes: true` so inline
+   * `ServerConfig` literals in tests may omit it.
+   */
+  readonly chathistory?: ChathistoryConfig | undefined;
+  /**
+   * HostServ approval mode for `REQUEST <vhost>`. `false` (the parsed
+   * default) is oper-queue mode: `REQUEST` queues a pending request that an
+   * oper must `APPROVE` (or `REJECT`); `LIST` enumerates the pending
+   * queue — the recommended mode. `true` preserves the legacy
+   * auto-approve behaviour (the vhost is recorded immediately, no oper
+   * review), hard-constrained by {@link hostservAutoApproveAllowlist} and
+   * a built-in denylist (reserved labels + this server's own hostname).
+   *
+   * @deprecated Auto-approve is deprecated; queue mode (the default) is
+   *   the long-term path and a future release removes the auto-approve
+   *   arm. See `docs/Services.md`.
    *
    * Typed `boolean | undefined` so inline `ServerConfig` literals in tests
-   * may omit it (the reducer treats `undefined` as "auto-approve on",
-   * matching the parsed default).
+   * may omit it (the reducer treats `undefined` as queue mode, matching
+   * the parsed default).
    */
   readonly hostservAutoApproveVhosts?: boolean | undefined;
+  /**
+   * Explicit allowlist constraining auto-approved vhosts when
+   * {@link hostservAutoApproveVhosts} is `true`: an entry is an exact
+   * hostname (`users.example.com`) or a wildcard suffix
+   * (`*.users.example.com`, any depth beneath it). Case-insensitive.
+   * Ignored in queue mode (opers vet requests). The parsed config always
+   * supplies an array (default `[]`), and config parsing refuses to boot
+   * auto-approve mode with an empty allowlist; the reducer additionally
+   * fails closed when the field is omitted from an inline literal.
+   *
+   * Typed `ReadonlyArray<string> | undefined` to mirror Zod's `.optional()`
+   * output under `exactOptionalPropertyTypes: true`.
+   */
+  readonly hostservAutoApproveAllowlist?: ReadonlyArray<string> | undefined;
 }
 
 /** Per-invocation context handed to every reducer. */
@@ -317,6 +510,21 @@ export interface Ctx {
    * `904` / silent no-op.
    */
   readonly services?: ServicesStore;
+  /**
+   * Per-IP failed-`OPER` counter (absent when the deployment's runtime
+   * does not maintain one). When present, the OPER reducer counts
+   * credential failures per source host: once
+   * `serverConfig.oper.maxFailures` failures land within
+   * `serverConfig.oper.failureWindowSeconds`, further OPER attempts from
+   * that host are rejected with `491 ERR_NOOPERHOST` without consulting
+   * the credential store, and a `BroadcastOperNotice` effect notifies
+   * every oper. A successful OPER resets the host's counter. Omitted (→
+   * `ctx.operFailures` undefined) preserves the unlocked behaviour for
+   * runtimes that have not wired the shared tracker (e.g. per-connection
+   * Durable Object adapters): every attempt still reaches the credential
+   * store.
+   */
+  readonly operFailures?: OperFailureStats;
   /** The connection invoking the command. Reducers mutate this freely. */
   readonly connection: ConnectionState;
   /** Convenience: `connection.id`. */
@@ -358,6 +566,12 @@ export interface BuildCtxOptions {
   history?: NickHistoryStore;
   away?: AwayStore;
   services?: ServicesStore;
+  /**
+   * Per-IP failed-`OPER` counter shared across every connection (see
+   * {@link Ctx.operFailures}). Omitted → the OPER brute-force gate is
+   * disabled for this actor.
+   */
+  operFailures?: OperFailureStats;
   connection: ConnectionState;
   /**
    * IRCv3 `labeled-response` label extracted from the inbound `+label` tag.
@@ -383,6 +597,7 @@ export function buildCtx(opts: BuildCtxOptions): Ctx {
     ...(opts.history !== undefined ? { history: opts.history } : {}),
     ...(opts.away !== undefined ? { away: opts.away } : {}),
     ...(opts.services !== undefined ? { services: opts.services } : {}),
+    ...(opts.operFailures !== undefined ? { operFailures: opts.operFailures } : {}),
     ...(opts.label !== undefined ? { label: opts.label } : {}),
   };
   return ctx;

package/packages/irc-core/src/ws-framing.ts

@@ -25,6 +25,7 @@
  * every WebSocket runtime (Node `ws`, Cloudflare Durable Objects, Lambda).
  */
 
+import { byteLength } from './protocol/bytes.js';
 import type { WsSubprotocol } from './ws-subprotocol.js';
 
 /**
@@ -103,12 +104,12 @@ export function frameToLines(frame: string, mode: WsFrameMode): string[] {
 /**
  * Returns `true` when `frame` fits within the IRCv3 WebSocket 510-byte
  * message budget, `false` when it exceeds it and MUST be rejected by the
- * inbound path. Measured in UTF-16 code units, consistent with how
- * {@link enforceLineLimit} and the input parser cap line length across this
- * package (every supported runtime exposes `.length`).
+ * inbound path. Measured in UTF-8 bytes (the wire encoding), consistent
+ * with how {@link enforceLineLimit} and the input parser cap line length
+ * across this package, so multi-byte content cannot double the budget.
  */
 export function isWithinWsByteBudget(frame: string): boolean {
-  return frame.length <= MAX_WS_MESSAGE_BYTES;
+  return byteLength(frame) <= MAX_WS_MESSAGE_BYTES;
 }
 
 /**

package/packages/irc-core/tests/bytes.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import { byteLength, truncateToByteBudget } from '../src/protocol/bytes';
+
+// ============================================================================
+// byteLength — UTF-8 byte accounting for IRC wire budgets
+//
+// IRC line limits are byte budgets (RFC 1459 §2.3), but JavaScript strings
+// expose UTF-16 code units via `.length`. These tests pin the semantics the
+// line-budget seams rely on: one byte per ASCII char, 2–4 bytes per
+// non-ASCII code point.
+// ============================================================================
+
+describe('byteLength', () => {
+  it('returns 0 for the empty string', () => {
+    expect(byteLength('')).toBe(0);
+  });
+
+  it('counts one byte per ASCII character (matches .length)', () => {
+    expect(byteLength('NICK bob')).toBe('NICK bob'.length);
+  });
+
+  it('counts 2 bytes for a 2-byte BMP character (é)', () => {
+    expect('é'.length).toBe(1);
+    expect(byteLength('é')).toBe(2);
+  });
+
+  it('returns 1022 for 511 é characters — not the UTF-16 count of 511', () => {
+    const s = 'é'.repeat(511);
+    expect(s.length).toBe(511);
+    expect(byteLength(s)).toBe(1022);
+  });
+
+  it('counts 4 bytes for an astral code point (surrogate pair)', () => {
+    const emoji = '😀';
+    expect(emoji.length).toBe(2);
+    expect(byteLength(emoji)).toBe(4);
+  });
+
+  it('accounts for mixed ASCII and multi-byte content', () => {
+    expect(byteLength('aé😀')).toBe(1 + 2 + 4);
+  });
+});
+
+// ============================================================================
+// truncateToByteBudget — byte-bounded right-truncation
+//
+// Line-budget seams must not only DETECT over-budget multi-byte lines, they
+// must emit output that fits the byte budget. Code-unit slicing cannot do
+// that (510 'é' units = 1020 bytes) and can split surrogate pairs.
+// ============================================================================
+
+describe('truncateToByteBudget', () => {
+  it('returns the input unchanged when it already fits the budget', () => {
+    expect(truncateToByteBudget('NICK bob', 510)).toBe('NICK bob');
+  });
+
+  it('truncates ASCII input exactly like code-unit slicing', () => {
+    expect(truncateToByteBudget('x'.repeat(600), 510)).toBe('x'.repeat(510));
+  });
+
+  it('truncates multi-byte input so the result fits the byte budget', () => {
+    const out = truncateToByteBudget('é'.repeat(600), 510);
+    expect(byteLength(out)).toBeLessThanOrEqual(510);
+    // 510 bytes of 'é' = 255 chars; the budget is fully used.
+    expect(out).toBe('é'.repeat(255));
+  });
+
+  it('stops before the code point that would cross the budget', () => {
+    // Budget 511 with 'é' (2 bytes each): 255 chars = 510 bytes; the 256th
+    // 'é' would make 512, so it is dropped and one byte stays unused.
+    expect(truncateToByteBudget('é'.repeat(600), 511)).toBe('é'.repeat(255));
+  });
+
+  it('never splits a surrogate pair', () => {
+    const out = truncateToByteBudget('😀'.repeat(400), 510);
+    // 4-byte emoji: floor(510/4) = 127 complete pairs = 508 bytes.
+    expect(out).toBe('😀'.repeat(127));
+    expect(byteLength(out)).toBe(508);
+  });
+
+  it('accounts for mixed ASCII and multi-byte content', () => {
+    // 'ab' (2 bytes) + 3 'é' (6 bytes) = 8 bytes; budget 5 keeps 'abé'.
+    expect(truncateToByteBudget('abééé', 5)).toBe('abé');
+  });
+
+  it('returns the empty string for a zero budget', () => {
+    expect(truncateToByteBudget('abc', 0)).toBe('');
+  });
+});

package/packages/irc-core/tests/certfp.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CERT_FP_PREFIX,
+  canonicalizeCertSubject,
+  certFingerprintId,
+  certIdentityFromSubject,
+} from '../src/certfp';
+
+// ============================================================================
+// canonicalizeCertSubject — RFC 4514-style DN canonicalisation
+// ============================================================================
+
+describe('canonicalizeCertSubject', () => {
+  it('lowercases the attribute type but preserves the value case', () => {
+    expect(canonicalizeCertSubject('CN=Alice')).toBe('cn=Alice');
+  });
+
+  it('collapses repeated whitespace inside a value', () => {
+    expect(canonicalizeCertSubject('CN=alice   smith')).toBe('cn=alice smith');
+  });
+
+  it('trims whitespace around the type and value', () => {
+    expect(canonicalizeCertSubject('  CN  =  alice  ')).toBe('cn=alice');
+  });
+
+  it('sorts RDNs into a stable order regardless of input ordering', () => {
+    expect(canonicalizeCertSubject('O=Example Inc,CN=alice')).toBe('cn=alice,o=Example Inc');
+    expect(canonicalizeCertSubject('CN=alice,O=Example Inc')).toBe('cn=alice,o=Example Inc');
+  });
+
+  it('sorts AVAs inside a multi-valued RDN regardless of input ordering', () => {
+    expect(canonicalizeCertSubject('O=Example+CN=alice')).toBe('cn=alice+o=Example');
+    expect(canonicalizeCertSubject('CN=alice+O=Example')).toBe('cn=alice+o=Example');
+  });
+
+  it('collapses two semantically-equal DNs (spacing + ordering differ) to one form', () => {
+    const a = canonicalizeCertSubject('CN=alice ,  O = Example   Inc , C=US');
+    const b = canonicalizeCertSubject('C=US,O=Example Inc,CN=alice');
+    expect(a).toBe(b);
+  });
+
+  it('does not split on an escaped separator', () => {
+    expect(canonicalizeCertSubject('CN=a\\,b,O=x')).toBe('cn=a\\,b,o=x');
+  });
+
+  it('skips escaped characters when locating the type/value split', () => {
+    expect(canonicalizeCertSubject('CN\\=tag=y')).toBe('cn\\=tag=y');
+  });
+
+  it('does not trim an escaped trailing space from a value', () => {
+    expect(canonicalizeCertSubject('CN=alice\\ ')).toBe('cn=alice\\ ');
+  });
+
+  it('keeps an escape pair intact when a pending space precedes it', () => {
+    expect(canonicalizeCertSubject('CN=a  \\, b')).toBe('cn=a \\, b');
+  });
+
+  it('keeps a trailing dangling backslash verbatim', () => {
+    expect(canonicalizeCertSubject('CN=a\\')).toBe('cn=a\\');
+  });
+
+  it('keeps a malformed AVA without an equals sign as trimmed collapsed text', () => {
+    expect(canonicalizeCertSubject('  alice  smith ')).toBe('alice smith');
+  });
+
+  it('canonicalises an empty DN to the empty string', () => {
+    expect(canonicalizeCertSubject('')).toBe('');
+  });
+});
+
+// ============================================================================
+// certFingerprintId — normalised DER SHA-256 fingerprint binding id
+// ============================================================================
+
+describe('certFingerprintId', () => {
+  it('prefixes the fingerprint with the binding prefix', () => {
+    expect(certFingerprintId('af363dc8')).toBe(`${CERT_FP_PREFIX}af363dc8`);
+  });
+
+  it('lowercases an uppercase hex fingerprint', () => {
+    expect(certFingerprintId('AF363DC8')).toBe('fp:af363dc8');
+  });
+
+  it('strips openssl-style colon separators', () => {
+    expect(certFingerprintId('AF:36:3D:C8')).toBe('fp:af363dc8');
+  });
+
+  it('trims surrounding whitespace', () => {
+    expect(certFingerprintId('  af363dc8  ')).toBe('fp:af363dc8');
+  });
+});
+
+// ============================================================================
+// certIdentityFromSubject — CertIdentity construction
+// ============================================================================
+
+describe('certIdentityFromSubject', () => {
+  it('builds an identity with the canonical DN and no fingerprint key', () => {
+    expect(certIdentityFromSubject('CN=alice')).toEqual({
+      subject: 'CN=alice',
+      canonicalDn: 'cn=alice',
+    });
+  });
+
+  it('includes the fingerprint when the platform supplied one', () => {
+    expect(certIdentityFromSubject('CN=alice', 'af363dc8')).toEqual({
+      subject: 'CN=alice',
+      canonicalDn: 'cn=alice',
+      fingerprint: 'af363dc8',
+    });
+  });
+
+  it('carries the canonical DN of a multi-RDN subject', () => {
+    const id = certIdentityFromSubject('O=Example,CN=alice');
+    expect(id.canonicalDn).toBe('cn=alice,o=Example');
+  });
+});

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

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { getLsString } from '../../src/caps/capabilities';
+import { certIdentityFromSubject } from '../../src/certfp';
 import { capReducer } from '../../src/commands/cap';
 import { userReducer } from '../../src/commands/registration';
 import { Effect } from '../../src/effects';
@@ -131,8 +132,12 @@ describe('capReducer — LS', () => {
 
   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);
+    state.secure = true;
+    const provider: MtlsIdentityProvider = {
+      getIdentity: () => certIdentityFromSubject('CN=alice'),
+    };
+    const cfg: ServerConfig = { ...serverConfig, sasl: { externalEnabled: true } };
+    const ctx = makeCtx(state, cfg, provider);
     const out = capReducer(state, { command: 'CAP', params: ['LS'], tags: {} }, ctx);
     const send = out.effects[0];
     expect(send).toBeDefined();
@@ -142,6 +147,75 @@ describe('capReducer — LS', () => {
     }
   });
 
+  it('advertises sasl=PLAIN when EXTERNAL is not opted in, even with mTLS on a secure connection', () => {
+    // The operator opt-in gate: without sasl.externalEnabled the mechanism
+    // is not advertised, so clients never attempt an exchange the server
+    // would refuse with 908.
+    const state = makeState();
+    state.secure = true;
+    const provider: MtlsIdentityProvider = {
+      getIdentity: () => certIdentityFromSubject('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');
+      expect(body).not.toContain('sasl=PLAIN,EXTERNAL');
+    }
+  });
+
+  it('advertises sasl=PLAIN on an insecure connection even when EXTERNAL is opted in', () => {
+    // SASL EXTERNAL is certificate-backed authentication: the client-cert
+    // identity only carries meaning over a transport the server trusts
+    // (TLS). A plaintext connection never sees the mechanism.
+    const state = makeState();
+    state.secure = false;
+    const provider: MtlsIdentityProvider = {
+      getIdentity: () => certIdentityFromSubject('CN=alice'),
+    };
+    const cfg: ServerConfig = { ...serverConfig, sasl: { externalEnabled: true } };
+    const ctx = makeCtx(state, cfg, 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');
+      expect(body).not.toContain('sasl=PLAIN,EXTERNAL');
+    }
+  });
+
+  it('advertises sasl=PLAIN when the transport-level EXTERNAL override is set, even with mTLS + opt-in on a secure connection', () => {
+    // A transport that cannot surface a client-cert identity (the
+    // Spectrum TCP container origin) pins the mechanism off via
+    // sasl.externalUnsupportedMessage: the cap must never advertise a
+    // mechanism AUTHENTICATE would refuse with a transport-specific 904.
+    const state = makeState();
+    state.secure = true;
+    const provider: MtlsIdentityProvider = {
+      getIdentity: () => certIdentityFromSubject('CN=alice'),
+    };
+    const cfg: ServerConfig = {
+      ...serverConfig,
+      sasl: {
+        externalEnabled: true,
+        externalUnsupportedMessage: 'SASL EXTERNAL not supported on this transport',
+      },
+    };
+    const ctx = makeCtx(state, cfg, 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');
+      expect(body).not.toContain('sasl=PLAIN,EXTERNAL');
+    }
+  });
+
   it('advertises draft/multiline=4096 with the default byte budget', () => {
     const state = makeState();
     const ctx = makeCtx(state);