serverless-ircd 0.9.0 → 0.11.0

package/packages/cf-adapter/tests/cf-runtime.test.ts

@@ -29,9 +29,10 @@ import {
   type RawLine,
   createConnection,
 } from '@serverless-ircd/irc-core';
-import { afterAll, afterEach, describe, expect, it } from 'vitest';
+import { afterAll, afterEach, describe, expect, it, vi } from 'vitest';
 import { type CfConnectionHandlers, CfRuntime } from '../src/cf-runtime';
 import type { Env, RegistryRpc } from '../src/env';
+import { serialize } from '../src/serialize';
 import { registryKeyForNick } from '../src/sharding';
 
 declare global {
@@ -45,6 +46,8 @@ declare global {
       CHANNEL_DO_REAL: DurableObjectNamespace;
       CHANNEL_DO_STUB: DurableObjectNamespace;
       CHANNEL_REGISTRY_DO: DurableObjectNamespace;
+      COUNTER_DO: DurableObjectNamespace;
+      RATE_LIMIT_DO: DurableObjectNamespace;
     }
   }
 }
@@ -64,6 +67,8 @@ function envWithRealDOs(): Env {
     REGISTRY_DO: env.REGISTRY_DO_REAL,
     CHANNEL_DO: env.CHANNEL_DO_REAL,
     CHANNEL_REGISTRY_DO: env.CHANNEL_REGISTRY_DO,
+    COUNTER_DO: env.COUNTER_DO,
+    RATE_LIMIT_DO: env.RATE_LIMIT_DO,
     SERVER_NAME: 'irc.example.com',
     NETWORK_NAME: 'ExampleNet',
     MOTD_LINES: '',
@@ -81,6 +86,8 @@ function envWithChannelStub(): Env {
     REGISTRY_DO: env.REGISTRY_DO_REAL,
     CHANNEL_DO: env.CHANNEL_DO_STUB,
     CHANNEL_REGISTRY_DO: env.CHANNEL_REGISTRY_DO,
+    COUNTER_DO: env.COUNTER_DO,
+    RATE_LIMIT_DO: env.RATE_LIMIT_DO,
     SERVER_NAME: 'irc.example.com',
     NETWORK_NAME: 'ExampleNet',
     MOTD_LINES: '',
@@ -659,41 +666,54 @@ describe('CfRuntime — reloadConfig (REHASH)', () => {
 
 /**
  * Opens a ConnectionDO, registers it with the given nick, and optionally
- * flips user mode `w` on via a direct state mutation (avoids driving the
- * full MODE handshake through the actor). Returns the live WebSocket and
- * the connection's canonical hex id.
+ * flips user mode `w`/`o` on via a direct state mutation (avoids driving
+ * the full MODE/OPER handshake through the actor). Returns the live
+ * WebSocket and the connection's canonical hex id.
  */
 async function openWallopsCapableConn(
   name: string,
-  opts: { wallops: boolean },
+  opts: { wallops?: boolean; oper?: boolean },
 ): Promise<{ ws: WebSocket; hexId: string; received: string[] }> {
   const ws = await openConnection(name);
   await new Promise<void>((r) => setTimeout(r, 20));
   ws.send(`NICK ${name}\r\n`);
-  ws.send(`USER ${name} 0 * :${name}\r\n`);
+  // Fixed short username: the server caps USER at 16 bytes, and several
+  // connection names in these suites are longer — interpolating the name
+  // here made the server reject USER and close the link before the
+  // wallops/oper fan-out ever ran.
+  ws.send('USER chat 0 * :chat\r\n');
   // Drain the registration numerics so they don't interfere with the
-  // assertions on wallops delivery below.
+  // assertions on wallops/oper-notice delivery below.
   await new Promise<void>((r) => setTimeout(r, 100));
 
   const hexId = await getConnectionHexId(name);
   const received = drainSocket(ws);
 
-  if (opts.wallops) {
-    // Flip the +w mode directly on the live cached state. The DO is the
-    // authority for this state; broadcastWallops reads it back via
-    // getConnState() so what we mutate here is exactly what the fan-out
-    // will see.
+  if (opts.wallops === true || opts.oper === true) {
+    // Flip the mode(s) directly on the live cached state. The DO is the
+    // authority for this state; broadcastWallops/broadcastOperNotice read
+    // it back via getConnState() so what we mutate here is exactly what
+    // the fan-out will see.
     const stub = env.CONNECTION_DO.get(env.CONNECTION_DO.idFromString(hexId));
     await runInDurableObject(stub, async (instance: unknown) => {
       const doi = instance as {
         __peekState?: () => Promise<
           import('@serverless-ircd/irc-core').ConnectionState | undefined
         >;
-        __pokeState?: (s: import('@serverless-ircd/irc-core').ConnectionState) => void;
       };
       const state = await doi.__peekState?.();
-      if (state !== undefined) state.userModes.wallops = true;
+      if (state !== undefined) {
+        if (opts.wallops === true) state.userModes.wallops = true;
+        if (opts.oper === true) state.userModes.oper = true;
+      }
     });
+    // Persist the mutated mode: the DO persists state only after a frame
+    // dispatches, and a DO eviction between here and the fan-out would
+    // otherwise reload the unmutated persisted copy (the cause of a
+    // pre-existing intermittent failure in the excepted-originator
+    // tests). One client PING forces the persist.
+    ws.send('PING :pin\r\n');
+    await new Promise<void>((r) => setTimeout(r, 150));
   }
 
   // Reserve the nick in the REAL registry under its hex id so
@@ -751,7 +771,7 @@ describe('CfRuntime — broadcastWallops', () => {
     await rt.broadcastWallops([{ text: ':oper!u@h WALLOPS :except me' }], sender.hexId);
 
     await new Promise<void>((resolve) => {
-      const deadline = Date.now() + 1000;
+      const deadline = Date.now() + 4000;
       const tick = (): void => {
         if (other.received.some((l) => l.includes('except me'))) {
           resolve();
@@ -801,7 +821,7 @@ describe('CfRuntime — broadcastWallops', () => {
     ).resolves.toBeUndefined();
 
     await new Promise<void>((resolve) => {
-      const deadline = Date.now() + 1000;
+      const deadline = Date.now() + 4000;
       const tick = (): void => {
         if (other.received.some((l) => l.includes('ghost friendly'))) {
           resolve();
@@ -821,6 +841,76 @@ describe('CfRuntime — broadcastWallops', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Tests — broadcastOperNotice (global +o fan-out for oper-only notices)
+// ---------------------------------------------------------------------------
+
+describe('CfRuntime — broadcastOperNotice', () => {
+  it('delivers to every +o connection and skips non-opers', async () => {
+    const realEnv = envWithRealDOs();
+
+    const oper = await openWallopsCapableConn('opernote-oper', { oper: true });
+    // +w without +o must NOT receive an oper notice.
+    const wallopsOnly = await openWallopsCapableConn('opernote-wallops', { wallops: true });
+
+    const rt = new CfRuntime(realEnv, 'conn-opernote-sender', recordingHandlers());
+    await rt.broadcastOperNotice([{ text: ':server NOTICE * :*** oper lockout tripped' }]);
+
+    await new Promise<void>((resolve) => {
+      const deadline = Date.now() + 1500;
+      const tick = (): void => {
+        if (oper.received.some((l) => l.includes('oper lockout tripped'))) {
+          resolve();
+          return;
+        }
+        if (Date.now() > deadline) {
+          resolve();
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+
+    expect(oper.received.some((l) => l.includes('oper lockout tripped'))).toBe(true);
+    expect(wallopsOnly.received.some((l) => l.includes('oper lockout tripped'))).toBe(false);
+
+    oper.ws.close();
+    wallopsOnly.ws.close();
+  });
+
+  it('skips the excepted originator', async () => {
+    const realEnv = envWithRealDOs();
+    const sender = await openWallopsCapableConn('opernote-except-sender', { oper: true });
+    const other = await openWallopsCapableConn('opernote-except-other', { oper: true });
+
+    const rt = new CfRuntime(realEnv, sender.hexId, recordingHandlers());
+    await rt.broadcastOperNotice([{ text: ':server NOTICE * :*** except me' }], sender.hexId);
+
+    await new Promise<void>((resolve) => {
+      const deadline = Date.now() + 4000;
+      const tick = (): void => {
+        if (other.received.some((l) => l.includes('except me'))) {
+          resolve();
+          return;
+        }
+        if (Date.now() > deadline) {
+          resolve();
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+
+    expect(other.received.some((l) => l.includes('except me'))).toBe(true);
+    expect(sender.received.some((l) => l.includes('except me'))).toBe(false);
+
+    sender.ws.close();
+    other.ws.close();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Tests — changeNick shard routing + failure paths
 // ---------------------------------------------------------------------------
@@ -921,3 +1011,102 @@ describe('CfRuntime — getConnection and getChannelConnections branches', () =>
     member.ws.close();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Tests — pure helper seams for defensive null-DTO branches
+// ---------------------------------------------------------------------------
+
+describe('CfRuntime — defensive DTO helper seams', () => {
+  it('deserializeConnState returns null when the DTO is null', () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-dsz-null', recordingHandlers());
+    expect(rt.deserializeConnState(null)).toBeNull();
+  });
+
+  it('deserializeConnState rehydrates a populated DTO', () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-dsz-real', recordingHandlers());
+    const live = createConnection({ id: 'conn-dsz-real', connectedSince: 0 });
+    live.nick = 'dz';
+    // Round-trip through serialize so the DTO matches what a real
+    // ConnectionDO.getConnState would return.
+    const dto = serialize(live);
+    const out = rt.deserializeConnState(dto);
+    expect(out?.nick).toBe('dz');
+    expect(out?.id).toBe('conn-dsz-real');
+  });
+
+  it('collectChannelMember skips a null DTO without mutating the map', () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-ccm-null', recordingHandlers());
+    const out = new Map();
+    rt.collectChannelMember(out, 'ghost', null);
+    expect(out.size).toBe(0);
+  });
+
+  it('collectChannelMember rehydrates and inserts a populated DTO', () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-ccm-real', recordingHandlers());
+    const live = createConnection({ id: 'conn-ccm-real', connectedSince: 0 });
+    live.nick = 'ccm';
+    const out = new Map();
+    rt.collectChannelMember(out, 'conn-ccm-real', serialize(live));
+    expect(out.size).toBe(1);
+    expect(out.get('conn-ccm-real')?.nick).toBe('ccm');
+  });
+
+  it('deliverWallopsToCandidate is a no-op when the DTO is null', async () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-dwc-null', recordingHandlers());
+    const deliver = vi.fn();
+    await rt.deliverWallopsToCandidate({ deliver }, null, [{ text: 'x' }]);
+    expect(deliver).not.toHaveBeenCalled();
+  });
+
+  it('deliverWallopsToCandidate skips a candidate whose +w mode is off', async () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-dwc-now', recordingHandlers());
+    const live = createConnection({ id: 'conn-dwc-now', connectedSince: 0 });
+    live.userModes.wallops = false;
+    const deliver = vi.fn();
+    await rt.deliverWallopsToCandidate({ deliver }, serialize(live), [{ text: 'x' }]);
+    expect(deliver).not.toHaveBeenCalled();
+  });
+
+  it('deliverWallopsToCandidate delivers to a +w candidate', async () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-dwc-yes', recordingHandlers());
+    const live = createConnection({ id: 'conn-dwc-yes', connectedSince: 0 });
+    live.userModes.wallops = true;
+    const calls: RawLine[][] = [];
+    const deliver = (lines: RawLine[]): Promise<void> => {
+      calls.push(lines);
+      return Promise.resolve();
+    };
+    await rt.deliverWallopsToCandidate({ deliver }, serialize(live), [
+      { text: ':oper!u@h WALLOPS :hi' },
+    ]);
+    expect(calls).toEqual([[{ text: ':oper!u@h WALLOPS :hi' }]]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests — getChannelSnapshot topic branch (the { topic } arm of the spread)
+// ---------------------------------------------------------------------------
+
+describe('CfRuntime — getChannelSnapshot topic branch', () => {
+  it('rehydrates the topic onto ChanSnapshot when the ChannelDO reports one', async () => {
+    // Existing coverage exercises the `: {}` arm of the topic spread; this
+    // case drives the `{ topic: dto.topic }` arm by applying a topic
+    // through the real ChannelDO and reading it back via CfRuntime.
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-topic-caller', recordingHandlers());
+    const topic = { text: 'news', setter: 'alice', setAt: 1 };
+    await rt.applyChannelDelta('#topic-branch', {
+      memberships: [{ type: 'add' as const, conn: 'conn-topic-caller', nick: 'alice' }],
+      topic,
+    });
+    const snap = await rt.getChannelSnapshot('#topic-branch');
+    expect(snap?.topic).toEqual(topic);
+  });
+});

package/packages/cf-adapter/tests/channel-do.test.ts

@@ -18,7 +18,7 @@
 import { env, runInDurableObject } from 'cloudflare:test';
 import type { ChannelDelta, ChannelTopic, ConnId, RosterEntry } from '@serverless-ircd/irc-core';
 import { describe, expect, it } from 'vitest';
-import type { ChannelSnapshotDto } from '../src/channel-do';
+import { type ChannelSnapshotDto, deserializeChannel, toDto } from '../src/channel-do';
 
 declare global {
   namespace Cloudflare {
@@ -595,3 +595,120 @@ describe('ChannelDO — broadcast + cache edge cases', () => {
     await alice.client.close();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Tests — ChannelDO instantiated without a name (idFromString)
+// ---------------------------------------------------------------------------
+
+describe('ChannelDO — id.name fallback', () => {
+  it('falls back to ctx.id.toString() when the DO was created via idFromString', async () => {
+    // ChannelDOs in production are always keyed by lowercased name
+    // (idFromName), but the DO storage-creation path still needs to
+    // handle the no-name case. `newUniqueId()` returns a valid hex DO id
+    // whose `id.name` is null, forcing the `??` fallback to `toString()`.
+    const hexId = env.CHANNEL_DO_REAL.newUniqueId().toString();
+    const stub = env.CHANNEL_DO_REAL.get(env.CHANNEL_DO_REAL.idFromString(hexId));
+    const rpc = stub as unknown as ChannelRpc;
+    await rpc.applyChannelDelta({
+      memberships: [{ type: 'add', conn: 'c-id-fallback', nick: 'alice' }],
+    });
+    const snap = await rpc.getChannelSnapshot();
+    // The DO used the hex id as the storage key, so nameLower resolves
+    // to the hex string (not a lowercased channel name).
+    expect(snap?.nameLower).toBe(hexId);
+    expect(snap?.name).toBe(hexId);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests — pure deserializeChannel / toDto helpers (legacy-shape arms)
+// ---------------------------------------------------------------------------
+
+describe('deserializeChannel — legacy record defensive arms', () => {
+  it('coalesces missing op/voice to false for legacy persisted members', () => {
+    // Pre-feature records may have been written without `op`/`voice`
+    // fields (or with them explicitly undefined). The loader's `?? false`
+    // arms must catch both so the rehydrated RosterEntry always carries
+    // a boolean. The PersistedChannelState interface types op/voice as
+    // optional, but legacy on-disk rows predate the field — cast through
+    // unknown to simulate the storage layer's untyped payload.
+    const record = {
+      name: '#legacy',
+      nameLower: '#legacy',
+      modes: {
+        inviteOnly: false,
+        topicLock: false,
+        noExternal: false,
+        moderated: false,
+        secret: false,
+        private: false,
+        registered: false,
+        blockUnidentified: false,
+        moderatedIdent: false,
+      },
+      banMasks: [],
+      members: [{ conn: 'c-1', nick: 'alice' }],
+      pendingInvites: [],
+      createdAt: 0,
+    } as unknown as Parameters<typeof deserializeChannel>[0];
+    const chan = deserializeChannel(record);
+    const entry = chan.members.get('c-1');
+    expect(entry?.op).toBe(false);
+    expect(entry?.voice).toBe(false);
+  });
+
+  it('leaves topic undefined when the record carries none', () => {
+    // The `if (record.topic !== undefined)` else arm: a record written
+    // before any TOPIC was set has no topic field, and deserializeChannel
+    // must leave chan.topic undefined.
+    const record = {
+      name: '#notopic',
+      nameLower: '#notopic',
+      modes: {
+        inviteOnly: false,
+        topicLock: false,
+        noExternal: false,
+        moderated: false,
+        secret: false,
+        private: false,
+        registered: false,
+        blockUnidentified: false,
+        moderatedIdent: false,
+      },
+      banMasks: [],
+      members: [],
+      pendingInvites: [],
+      createdAt: 0,
+    } as unknown as Parameters<typeof deserializeChannel>[0];
+    expect(deserializeChannel(record).topic).toBeUndefined();
+  });
+});
+
+describe('toDto — defensive Set/Map arms', () => {
+  it('returns empty arrays when ChannelState fields are missing', () => {
+    // Channels constructed without going through createChannel (e.g. a
+    // hand-built test fixture or a future storage migration) may lack
+    // the `Set`/`Map` fields. The `?:` arms in toDto must degrade to
+    // empty arrays so the DTO never carries undefined to callers.
+    const partial = {
+      name: '#partial',
+      nameLower: '#partial',
+      modes: {
+        inviteOnly: false,
+        topicLock: false,
+        noExternal: false,
+        moderated: false,
+        secret: false,
+        private: false,
+        registered: false,
+        blockUnidentified: false,
+        moderatedIdent: false,
+      },
+      createdAt: 0,
+    } as unknown as Parameters<typeof toDto>[0];
+    const dto = toDto(partial);
+    expect(dto.banMasks).toEqual([]);
+    expect(dto.members).toEqual([]);
+    expect(dto.pendingInvites).toEqual([]);
+  });
+});

package/packages/cf-adapter/tests/config-loader.test.ts

@@ -17,6 +17,18 @@ interface CfEnvLike {
   CHANNEL_PREFIXES?: string;
   OPER_USER?: string;
   OPER_PASSWORD?: string;
+  /**
+   * Scrypt salt (base64) for the hashed oper credential form. When set
+   * alongside `OPER_USER` + `OPER_HASH`, the loader builds a hashed
+   * `{user, salt, hash}` cred instead of the legacy plaintext
+   * `{user, password}` shape.
+   */
+  OPER_SALT?: string;
+  /**
+   * Scrypt hash (base64) for the hashed oper credential form. See
+   * `OPER_SALT` for the full set of vars.
+   */
+  OPER_HASH?: string;
   /**
    * Server-password gate. Treat as a wrangler secret in production
    * (never a plaintext `[vars]` entry); the loader threads it through
@@ -30,6 +42,8 @@ interface CfEnvLike {
   TOPIC_LEN?: string;
   MAX_LIST_ENTRIES?: string;
   QUIT_MESSAGE?: string;
+  /** SASL EXTERNAL operator opt-in ('true'/'1' enable; default off). */
+  EXTERNAL_ENABLED?: string;
 }
 
 function baseEnv(): CfEnvLike {
@@ -82,6 +96,49 @@ describe('loadServerConfigFromCfEnv — valid env', () => {
     expect(cfg.operCreds).toEqual([{ user: 'admin', password: 'hunter2' }]);
   });
 
+  it('builds a hashed operCred from OPER_USER + OPER_SALT + OPER_HASH', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      OPER_USER: 'admin',
+      OPER_SALT: 'c2FsdA==',
+      OPER_HASH: 'aGFzaA==',
+    });
+    expect(cfg.operCreds).toEqual([{ user: 'admin', salt: 'c2FsdA==', hash: 'aGFzaA==' }]);
+  });
+
+  it('prefers the hashed form when both OPER_PASSWORD and OPER_HASH/OPER_SALT are set', () => {
+    // Hashed form takes precedence so operators can rotate to it without
+    // removing the legacy OPER_PASSWORD var in the same deploy.
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      OPER_USER: 'admin',
+      OPER_PASSWORD: 'legacy',
+      OPER_SALT: 'c2FsdA==',
+      OPER_HASH: 'aGFzaA==',
+    });
+    expect(cfg.operCreds).toEqual([{ user: 'admin', salt: 'c2FsdA==', hash: 'aGFzaA==' }]);
+  });
+
+  it('throws when OPER_USER + OPER_SALT are set but OPER_HASH is missing', () => {
+    expect(() =>
+      loadServerConfigFromCfEnv({
+        ...baseEnv(),
+        OPER_USER: 'admin',
+        OPER_SALT: 'c2FsdA==',
+      }),
+    ).toThrowError(/hash/u);
+  });
+
+  it('throws when OPER_USER + OPER_HASH are set but OPER_SALT is missing', () => {
+    expect(() =>
+      loadServerConfigFromCfEnv({
+        ...baseEnv(),
+        OPER_USER: 'admin',
+        OPER_HASH: 'aGFzaA==',
+      }),
+    ).toThrowError(/salt/u);
+  });
+
   it('threads SERVER_PASSWORD through to serverPassword', () => {
     const cfg = loadServerConfigFromCfEnv({
       ...baseEnv(),
@@ -237,3 +294,105 @@ describe('loadServerConfigFromCfEnv — SASL_ACCOUNTS parsing', () => {
     expect(cfg.createdAt).toBe(huge);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Adapter frame-rate limit (per-connection inbound frame window).
+// ---------------------------------------------------------------------------
+
+describe('loadServerConfigFromCfEnv — adapter frame-rate limit', () => {
+  it('defaults the adapter frame window when the vars are unset', () => {
+    const cfg = loadServerConfigFromCfEnv(baseEnv());
+    expect(cfg.adapter).toEqual({ maxFramesPerWindow: 50, frameWindowSeconds: 5 });
+  });
+
+  it('maps MAX_FRAMES_PER_WINDOW + FRAME_WINDOW_SECONDS to the adapter section', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      MAX_FRAMES_PER_WINDOW: '10',
+      FRAME_WINDOW_SECONDS: '2',
+    });
+    expect(cfg.adapter).toEqual({ maxFramesPerWindow: 10, frameWindowSeconds: 2 });
+  });
+
+  it('fills the unset knob with its schema default when only one var is set', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), MAX_FRAMES_PER_WINDOW: '25' });
+    expect(cfg.adapter).toEqual({ maxFramesPerWindow: 25, frameWindowSeconds: 5 });
+  });
+
+  it('throws when MAX_FRAMES_PER_WINDOW is non-numeric', () => {
+    expect(() =>
+      loadServerConfigFromCfEnv({ ...baseEnv(), MAX_FRAMES_PER_WINDOW: 'lots' }),
+    ).toThrowError(/maxFramesPerWindow/u);
+  });
+
+  it('throws when FRAME_WINDOW_SECONDS is non-positive', () => {
+    expect(() =>
+      loadServerConfigFromCfEnv({ ...baseEnv(), FRAME_WINDOW_SECONDS: '0' }),
+    ).toThrowError(/frameWindowSeconds/u);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// EXTERNAL_ENABLED — SASL EXTERNAL operator opt-in (default off).
+// ---------------------------------------------------------------------------
+
+describe('loadServerConfigFromCfEnv — EXTERNAL_ENABLED (SASL EXTERNAL opt-in)', () => {
+  it('leaves SASL EXTERNAL off when EXTERNAL_ENABLED is unset', () => {
+    const cfg = loadServerConfigFromCfEnv(baseEnv());
+    expect(cfg.sasl?.externalEnabled ?? false).toBe(false);
+  });
+
+  it('maps EXTERNAL_ENABLED=true to sasl.externalEnabled', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), EXTERNAL_ENABLED: 'true' });
+    expect(cfg.sasl?.externalEnabled).toBe(true);
+  });
+
+  it('maps EXTERNAL_ENABLED=1 to sasl.externalEnabled', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), EXTERNAL_ENABLED: '1' });
+    expect(cfg.sasl?.externalEnabled).toBe(true);
+  });
+
+  it('maps EXTERNAL_ENABLED=false (and any other value) to false', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), EXTERNAL_ENABLED: 'false' });
+    expect(cfg.sasl?.externalEnabled).toBe(false);
+    const junk = loadServerConfigFromCfEnv({ ...baseEnv(), EXTERNAL_ENABLED: 'yes please' });
+    expect(junk.sasl?.externalEnabled ?? false).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Per-IP admission knobs — edge throttling is operator-tunable via env vars.
+// ---------------------------------------------------------------------------
+
+describe('loadServerConfigFromCfEnv — per-IP admission knobs', () => {
+  it('defaults maxConnectionsPerIp / perIpConnectionRate from the schema', () => {
+    const cfg = loadServerConfigFromCfEnv(baseEnv());
+    expect(cfg.maxConnectionsPerIp).toBe(10);
+    expect(cfg.perIpConnectionRate).toEqual({ max: 5, windowMs: 60_000 });
+  });
+
+  it('parses MAX_CONNECTIONS_PER_IP as an integer', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), MAX_CONNECTIONS_PER_IP: '3' });
+    expect(cfg.maxConnectionsPerIp).toBe(3);
+  });
+
+  it('parses PER_IP_CONNECTION_RATE_MAX / _WINDOW_MS into the rate knob', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      PER_IP_CONNECTION_RATE_MAX: '10',
+      PER_IP_CONNECTION_RATE_WINDOW_MS: '30000',
+    });
+    expect(cfg.perIpConnectionRate).toEqual({ max: 10, windowMs: 30000 });
+  });
+
+  it('fills the unset half of the rate knob with the schema default', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), PER_IP_CONNECTION_RATE_MAX: '9' });
+    expect(cfg.perIpConnectionRate).toEqual({ max: 9, windowMs: 60_000 });
+  });
+
+  it('rejects a non-positive rate budget', () => {
+    expect(() =>
+      loadServerConfigFromCfEnv({ ...baseEnv(), PER_IP_CONNECTION_RATE_MAX: '0' }),
+    ).toThrowError(/perIpConnectionRate/u);
+  });
+});