serverless-ircd 0.9.0 → 0.11.0

package/packages/aws-adapter/src/origin-allowlist.ts

@@ -0,0 +1,94 @@
+/**
+ * WebSocket `Origin` policy for the AWS adapter's `$connect` Lambda —
+ * Cross-Site WebSocket Hijacking (CSWSH) defence.
+ *
+ * Browsers send an `Origin` header on every cross-origin WebSocket
+ * upgrade (RFC 6454); WebSocket upgrades do not otherwise enforce
+ * same-origin. Without a check, a malicious page can open a WebSocket
+ * to the IRC server from the victim's browser and drive the session
+ * with the victim's credentials. API Gateway WebSocket has no
+ * built-in `Origin` validation — the `$connect` Lambda receives
+ * `event.headers.Origin` and must enforce the allowlist itself.
+ *
+ * This module mirrors the canonical Cloudflare Worker policy
+ * (`apps/cf-worker/src/origin-allowlist.ts`) for the parsing
+ * semantics (comma-separated, trimmed, lowercased) and the
+ * "missing `Origin` = non-browser → allow" branch.
+ *
+ * **Deliberate divergence from the CF policy:** the AWS adapter
+ * supports ONLY the explicit-allowlist mode. The CF Worker's Mode 2
+ * (auto-derive the expected origin from the request's own `Host`
+ * header — same-origin enforcement) does not apply on AWS, because
+ * the SPA is served from a different CloudFront origin than the API
+ * Gateway WebSocket endpoint (`wss://{api-id}.execute-api.…`), so
+ * the request's own host is never the SPA's origin. The CSWSH
+ * defence is therefore opt-in: it only fires when `WEB_ORIGINS` is
+ * set. Unset → no Origin policy (existing AWS deployments without a
+ * web frontend are unchanged on upgrade).
+ */
+
+/**
+ * Outcome of evaluating a `$connect` upgrade's `Origin` header.
+ *
+ *   • `'allow'` — proceed: the origin is allowlisted, or the
+ *                  allowlist is empty (defence disabled), or the
+ *                  header is absent (non-browser client).
+ *   • `'deny'`  — reject (`403`): a browser sent an `Origin` that
+ *                  is not in the configured allowlist.
+ */
+export type ConnectOriginDecision = 'allow' | 'deny';
+
+/**
+ * Parse the comma-separated `WEB_ORIGINS` env var into a normalised
+ * set of lowercased origins. Whitespace-only and empty entries are
+ * dropped so trailing commas / stray spaces do not pollute the set.
+ * An empty/undefined var yields an empty set, which
+ * {@link decideConnectOrigin} treats as "defence disabled" (NOT
+ * deny-all).
+ *
+ * Origins are lowercased wholesale for case-insensitive matching;
+ * the scheme and host are case-insensitive per RFC 3986, and
+ * lowercasing the whole string is the simplest normalisation that
+ * handles the real-world browser-emitted form
+ * (`https://Example.com` → `https://example.com`). Port numbers —
+ * the only case-sensitive trailing component per the URI spec — are
+ * always digits in practice, so lowercasing is a no-op on them.
+ */
+export function parseWebOrigins(raw: string | undefined): Set<string> {
+  return new Set(
+    (raw ?? '')
+      .split(',')
+      .map((entry) => entry.trim().toLowerCase())
+      .filter((entry) => entry.length > 0),
+  );
+}
+
+/**
+ * Decide whether a `$connect` upgrade's `Origin` header is permitted.
+ *
+ * @param originHeader the raw `Origin` header value from
+ *                     `event.headers.Origin` (`null` / `undefined` /
+ *                     `''` when absent — non-browser clients).
+ * @param allowlist    the parsed {@link parseWebOrigins} set. When
+ *                     empty, the defence is disabled and every
+ *                     upgrade is allowed regardless of its `Origin`.
+ * @returns `'allow'` to proceed with the upgrade, or `'deny'` to
+ *          return `403` so API Gateway closes the connection.
+ */
+export function decideConnectOrigin(
+  originHeader: string | null | undefined,
+  allowlist: Set<string>,
+): ConnectOriginDecision {
+  // Missing Origin = non-browser client (curl, WeeChat, tcp-ws-forwarder).
+  if (originHeader === null || originHeader === undefined || originHeader === '') {
+    return 'allow';
+  }
+
+  // Defence disabled — WEB_ORIGINS unset/empty. Every Origin proceeds.
+  if (allowlist.size === 0) {
+    return 'allow';
+  }
+
+  const origin = originHeader.trim().toLowerCase();
+  return allowlist.has(origin) ? 'allow' : 'deny';
+}

package/packages/aws-adapter/src/serialize.ts

@@ -84,6 +84,20 @@ export interface MarshalledConnection {
   away?: string;
   saslMech?: string;
   saslBuffer?: string;
+  /**
+   * Optimistic-concurrency revision counter. Incremented on every
+   * `$default`/NLB state write (conditional `UpdateItem` with
+   * `ConditionExpression: revision = :expected`) so two concurrent
+   * Lambda invocations for the same connection cannot silently
+   * clobber each other's state (the registration deadlock where
+   * `CAP END`'s `capNegotiating=false` got overwritten by a later
+   * frame's stale read). Absent on rows written before this field
+   * shipped; the persist path treats a missing attribute as revision
+   * `0` via an `attribute_not_exists(#rev) OR #rev = :expected`
+   * condition, so the migration is seamless. Seeded to `0` by
+   * {@link marshalConnection} at `$connect`.
+   */
+  revision?: number;
   /**
    * Negotiated IRCv3 WebSocket frame mode persisted at `$connect` time.
    * Absent (`undefined`) on legacy connections (no subprotocol agreed) so
@@ -93,6 +107,14 @@ export interface MarshalledConnection {
    * subsequent frame.
    */
   wsMode?: WsFrameMode;
+  /**
+   * Source IP of the connecting client, persisted at `$connect` (and on
+   * NLB flow creation) so the `sourceIp` GSI (`sourceIp-connectedSince`)
+   * carries the row for the per-IP admission walks. Absent on rows
+   * written before this field shipped — those are invisible to the
+   * index (a GSI item requires both key attributes).
+   */
+  sourceIp?: string;
 }
 
 /**
@@ -116,6 +138,7 @@ export function marshalConnection(state: ConnectionState, idleSince: number): Ma
     connectedSince: state.connectedSince,
     idleSince,
     version: CONNECTION_VERSION,
+    revision: 0,
   };
   if (state.joinedChannels.size > 0) {
     // Copy so later mutations to `state` don't alias the stored value.

package/packages/aws-adapter/src/tables.ts

@@ -14,13 +14,7 @@
  */
 
 /** Logical table names — also used as CDK construct ids. */
-export type TableName =
-  | 'Connections'
-  | 'ChannelMeta'
-  | 'ChannelMembers'
-  | 'Nicks'
-  | 'Accounts'
-  | 'Services';
+export type TableName = 'Connections' | 'ChannelMeta' | 'ChannelMembers' | 'Nicks' | 'Services';
 
 /** Logical table names in stable order. */
 export const TABLE_NAMES: readonly TableName[] = [
@@ -28,7 +22,6 @@ export const TABLE_NAMES: readonly TableName[] = [
   'ChannelMeta',
   'ChannelMembers',
   'Nicks',
-  'Accounts',
   'Services',
 ];
 
@@ -47,7 +40,6 @@ export const TABLE_KEYS = {
   ChannelMeta: { pk: 'channelName' },
   ChannelMembers: { pk: 'channelName', sk: 'connectionId' },
   Nicks: { pk: 'nickLower' },
-  Accounts: { pk: 'account' },
 } as const;
 
 /**
@@ -58,14 +50,13 @@ export const TABLE_KEYS = {
  * `Services` is optional: the services-persistence table is provisioned by
  * {@link TABLE_DEFS} but the runtime reads `SERVICES_TABLE` directly and
  * tolerates an unset var (services unbound). A `TablesConfig` built from
- * the required-five env vars still type-checks.
+ * the required-four env vars still type-checks.
  */
 export type TablesConfig = {
   Connections: string;
   ChannelMeta: string;
   ChannelMembers: string;
   Nicks: string;
-  Accounts: string;
   Services?: string;
 };
 
@@ -75,9 +66,17 @@ export function tablesConfigFromNames(names: {
   ChannelMeta: string;
   ChannelMembers: string;
   Nicks: string;
-  Accounts: string;
   Services?: string;
 }): TablesConfig {
   const out: TablesConfig = { ...names };
   return out;
 }
+
+/**
+ * Name of the per-IP admission GSI on the `Connections` table
+ * (partition key `sourceIp`, sort key `connectedSince`). Consulted by the
+ * `$connect` and NLB handlers' per-IP admission gates; declared on the
+ * deployed table by `TABLE_DEFS` in `cdk-table-defs.ts`. Shared here so
+ * the runtime (this module) and the CDK definition reference one name.
+ */
+export const SOURCE_IP_INDEX_NAME = 'sourceIp-connectedSince';

package/packages/aws-adapter/tests/admission.test.ts

@@ -1,8 +1,8 @@
 /**
  * Pure unit tests for the AWS `$connect` admission policy
  * (`src/admission.ts`). No DynamoDB — these exercise every branch of
- * {@link decideConnectAdmission} directly so the per-IP branch is covered
- * even though the AWS handler does not yet feed it a `perIp` count.
+ * {@link decideConnectAdmission} directly so the per-IP branches are
+ * covered without standing up DynamoDB Local.
  */
 
 import { describe, expect, it } from 'vitest';
@@ -67,4 +67,62 @@ describe('decideConnectAdmission', () => {
       reason: 'server full',
     });
   });
+
+  it('admits when a rate budget is set but no recent count is supplied', () => {
+    expect(
+      decideConnectAdmission(
+        { total: 0 },
+        { maxClients: 10, perIpRate: { max: 5, windowMs: 60_000 } },
+      ),
+    ).toEqual({ admitted: true });
+  });
+
+  it('admits when the recent per-IP count is below the rate budget', () => {
+    expect(
+      decideConnectAdmission(
+        { total: 0, recentPerIp: 4 },
+        { maxClients: 10, perIpRate: { max: 5, windowMs: 60_000 } },
+      ),
+    ).toEqual({ admitted: true });
+  });
+
+  it('rejects with 429 once the recent per-IP count reaches the rate budget', () => {
+    expect(
+      decideConnectAdmission(
+        { total: 0, recentPerIp: 5 },
+        { maxClients: 10, perIpRate: { max: 5, windowMs: 60_000 } },
+      ),
+    ).toEqual({
+      admitted: false,
+      statusCode: 429,
+      reason: 'connection rate exceeded for this IP',
+    });
+  });
+
+  it('checks the per-IP simultaneous cap before the rate budget', () => {
+    // A caller supplying both over-budget counts gets the simultaneous-
+    // cap reason: the more specific signal for an already-connected IP.
+    expect(
+      decideConnectAdmission(
+        { total: 0, perIp: 3, recentPerIp: 5 },
+        { maxClients: 10, maxConnectionsPerIp: 3, perIpRate: { max: 5, windowMs: 60_000 } },
+      ),
+    ).toEqual({
+      admitted: false,
+      statusCode: 429,
+      reason: 'too many connections from this IP',
+    });
+  });
+
+  it('ignores a stale recent count (window decayed) and admits', () => {
+    // Window-reset behaviour at the policy seam: a recent count of 0
+    // (every prior admission aged out of the window) never trips the
+    // rate branch even at a budget of 1.
+    expect(
+      decideConnectAdmission(
+        { total: 0, recentPerIp: 0 },
+        { maxClients: 10, perIpRate: { max: 1, windowMs: 60_000 } },
+      ),
+    ).toEqual({ admitted: true });
+  });
 });

package/packages/aws-adapter/tests/aws-harness.ts

@@ -97,7 +97,6 @@ export class AwsHarness implements IrcHarness {
       ChannelMeta: `${this.prefix}ChannelMeta`,
       ChannelMembers: `${this.prefix}ChannelMembers`,
       Nicks: `${this.prefix}Nicks`,
-      Accounts: `${this.prefix}Accounts`,
     };
     this.client = createDynamoDocumentClient({ endpoint });
   }
@@ -212,7 +211,7 @@ export class AwsHarness implements IrcHarness {
       const pkName = props.partitionKey?.name;
       const skName = props.sortKey?.name;
       if (pkName === undefined) throw new Error(`table ${logical} missing partitionKey`);
-      const attributeDefinitions: Array<{ AttributeName: string; AttributeType: 'S' }> = [
+      const attributeDefinitions: Array<{ AttributeName: string; AttributeType: 'S' | 'N' }> = [
         { AttributeName: pkName, AttributeType: 'S' },
       ];
       const keySchema: Array<{ AttributeName: string; KeyType: 'HASH' | 'RANGE' }> = [
@@ -222,11 +221,33 @@ export class AwsHarness implements IrcHarness {
         attributeDefinitions.push({ AttributeName: skName, AttributeType: 'S' });
         keySchema.push({ AttributeName: skName, KeyType: 'RANGE' });
       }
+      // Mirror the CDK-declared secondary indexes (the Connections
+      // per-IP admission GSI) so the fixture matches the deployed schema.
+      const globalSecondaryIndexes = (props.globalSecondaryIndexes ?? []).map((g) => {
+        const gpk = g.partitionKey;
+        if (gpk === undefined) throw new Error(`index ${g.indexName} missing partitionKey`);
+        const gsiKeySchema: Array<{ AttributeName: string; KeyType: 'HASH' | 'RANGE' }> = [
+          { AttributeName: gpk.name, KeyType: 'HASH' },
+        ];
+        attributeDefinitions.push({ AttributeName: gpk.name, AttributeType: 'S' });
+        if (g.sortKey !== undefined) {
+          gsiKeySchema.push({ AttributeName: g.sortKey.name, KeyType: 'RANGE' });
+          attributeDefinitions.push({ AttributeName: g.sortKey.name, AttributeType: 'N' });
+        }
+        return {
+          IndexName: g.indexName,
+          KeySchema: gsiKeySchema,
+          Projection: { ProjectionType: 'ALL' as const },
+        };
+      });
       await this.client.send(
         new CreateTableCommand({
           TableName: `${this.prefix}${logical}`,
           AttributeDefinitions: attributeDefinitions,
           KeySchema: keySchema,
+          ...(globalSecondaryIndexes.length > 0
+            ? { GlobalSecondaryIndexes: globalSecondaryIndexes }
+            : {}),
           BillingMode: 'PAY_PER_REQUEST',
         }),
       );

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

@@ -471,6 +471,70 @@ describe.skipIf(!available)('AwsRuntime', () => {
     });
   });
 
+  // -------------------------------------------------------------------------
+  // broadcastOperNotice — Scan-based fan-out to every +o connection (the
+  // OPER lockout gate's oper notice)
+  // -------------------------------------------------------------------------
+
+  describe('broadcastOperNotice', () => {
+    it('delivers to every +o connection and skips the except id', async () => {
+      const receivedA: string[] = [];
+      const receivedB: string[] = [];
+      const stateA = createConnection({ id: 'o-a', connectedSince: 0 });
+      stateA.userModes.oper = true;
+      const stateB = createConnection({ id: 'o-b', connectedSince: 0 });
+      stateB.userModes.oper = true;
+
+      const mgmt = new LocalPostToConnection();
+      mgmt.register('o-a', (data) => {
+        for (const line of data.split('\r\n')) {
+          if (line.length > 0) receivedA.push(line);
+        }
+      });
+      mgmt.register('o-b', (data) => {
+        for (const line of data.split('\r\n')) {
+          if (line.length > 0) receivedB.push(line);
+        }
+      });
+
+      const rtA = makeRuntime('o-a', handlersSink(receivedA, stateA), undefined, mgmt);
+      const rtB = makeRuntime('o-b', handlersSink(receivedB, stateB), undefined, mgmt);
+
+      await rtA.persistConnectionState(stateA);
+      await rtB.persistConnectionState(stateB);
+
+      // Caller 'o-a' is excepted; only 'o-b' should receive the notice.
+      await rtA.broadcastOperNotice(
+        [{ text: ':srv NOTICE * :OPER lockout triggered for h' }],
+        'o-a',
+      );
+      expect(receivedA).toEqual([]);
+      expect(receivedB).toEqual([':srv NOTICE * :OPER lockout triggered for h']);
+    });
+
+    it('does not deliver to a +w-only connection (the gate is +o)', async () => {
+      const received: string[] = [];
+      const state = createConnection({ id: 'o-wonly', connectedSince: 0 });
+      state.userModes.wallops = true;
+      const rt = makeRuntime('o-caller', handlersSink(received, state), undefined, null);
+      await rt.persistConnectionState(state);
+      await rt.broadcastOperNotice([{ text: ':srv NOTICE * :hi' }]);
+      expect(received).toEqual([]);
+    });
+
+    it('delivers to the bound connection via in-process handlers when not excepted', async () => {
+      // The bound connection's own +o delivery goes through handlers.send,
+      // not APIGW. With no `except`, the bound oper conn is a recipient.
+      const received: string[] = [];
+      const state = createConnection({ id: 'self', connectedSince: 0 });
+      state.userModes.oper = true;
+      const rt = makeRuntime('self', handlersSink(received, state), undefined, null);
+      await rt.persistConnectionState(state);
+      await rt.broadcastOperNotice([{ text: ':srv NOTICE * :hi' }]);
+      expect(received).toEqual([':srv NOTICE * :hi']);
+    });
+  });
+
   // -------------------------------------------------------------------------
   // Nick registry — error propagation
   // -------------------------------------------------------------------------

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

@@ -51,6 +51,35 @@ describe('buildLambdaConfigInput', () => {
     expect(out.operCreds).toEqual([{ user: '', password: 'pw' }]);
   });
 
+  it('builds a hashed operCred when OPER_USER + OPER_SALT + OPER_HASH are set', () => {
+    const out = buildLambdaConfigInput({
+      OPER_USER: 'admin',
+      OPER_SALT: 'c2FsdA==',
+      OPER_HASH: 'aGFzaA==',
+    });
+    expect(out.operCreds).toEqual([{ user: 'admin', salt: 'c2FsdA==', hash: 'aGFzaA==' }]);
+  });
+
+  it('prefers the hashed form over plaintext when both are set', () => {
+    const out = buildLambdaConfigInput({
+      OPER_USER: 'admin',
+      OPER_PASSWORD: 'legacy',
+      OPER_SALT: 'c2FsdA==',
+      OPER_HASH: 'aGFzaA==',
+    });
+    expect(out.operCreds).toEqual([{ user: 'admin', salt: 'c2FsdA==', hash: 'aGFzaA==' }]);
+  });
+
+  it('does NOT build operCreds when only OPER_SALT + OPER_HASH are set (no OPER_USER)', () => {
+    // Without OPER_USER the loader has no `user` field to thread; the
+    // hashed form requires a user name. The schema's superRefine would
+    // catch a missing user too, but the loader opts to omit operCreds
+    // entirely so the no-op (vs. `491 ERR_NOOPERHOST`) behaviour stays
+    // consistent with the legacy "no OPER_USER" path.
+    const out = buildLambdaConfigInput({ OPER_SALT: 'c2FsdA==', OPER_HASH: 'aGFzaA==' });
+    expect('operCreds' in out).toBe(false);
+  });
+
   it('threads SERVER_PASSWORD through to serverPassword', () => {
     expect(buildLambdaConfigInput({ SERVER_PASSWORD: 'hunter2' }).serverPassword).toBe('hunter2');
   });
@@ -155,6 +184,72 @@ describe('buildLambdaConfigInput', () => {
     const out = buildLambdaConfigInput({ SASL_ACCOUNTS: '  alice:secret  ' });
     expect(out.saslAccounts).toEqual([{ username: 'alice', password: 'secret' }]);
   });
+
+  it('does NOT thread WEB_ORIGINS into the ServerConfig input', () => {
+    // WEB_ORIGINS is an adapter-level operational concern (consumed by
+    // `$connect`'s CSWSH defence), NOT a server-config knob. Routing
+    // it through the shared Zod schema would either be silently
+    // stripped (the schema is non-strict) or pollute the canonical
+    // `ServerConfig` type with an AWS-only field. The buildLambdaConfigInput
+    // function therefore accepts the typed env field but never emits
+    // it — `buildDepsFromEnv` parses it directly via `parseWebOrigins`.
+    const out = buildLambdaConfigInput({ WEB_ORIGINS: 'https://app.example.com' });
+    expect('webOrigins' in out).toBe(false);
+    expect('WEB_ORIGINS' in out).toBe(false);
+  });
+
+  it('types WEB_ORIGINS as an optional string field on LambdaConfigEnv', () => {
+    // Compile-time assertion: the env interface accepts the field.
+    const env: LambdaConfigEnv = { WEB_ORIGINS: 'https://a.example.com,https://b.example.com' };
+    expect(env.WEB_ORIGINS).toBe('https://a.example.com,https://b.example.com');
+  });
+});
+
+describe('buildDepsFromEnv — WEB_ORIGINS wiring', () => {
+  // Build a minimal env shape that satisfies `tablesConfigFromEnv` and the
+  // shared config schema, pointing DynamoDB at an unreachable endpoint so
+  // `resolveAccountStore` / `loadDynamoServicesStore` fall through to
+  // defaults rather than scanning a live table. We are only asserting the
+  // env→deps wiring for `WEB_ORIGINS`.
+  function makeBaseEnv(): NodeJS.ProcessEnv {
+    return {
+      SERVER_NAME: 'irc.test',
+      NETWORK_NAME: 'TestNet',
+      CONNECTIONS_TABLE: 'Connections',
+      CHANNELMETA_TABLE: 'ChannelMeta',
+      CHANNELMEMBERS_TABLE: 'ChannelMembers',
+      NICKS_TABLE: 'Nicks',
+      ACCOUNTS_TABLE: 'Accounts',
+      DYNAMO_ENDPOINT: 'http://127.0.0.1:1',
+    };
+  }
+
+  it('parses WEB_ORIGINS into a Set on the returned deps', async () => {
+    // The env→deps wiring is the production path: `WEB_ORIGINS` is read
+    // once at cold start, parsed via `parseWebOrigins`, and stored on
+    // `HandlerDeps.webOrigins` so every `$connect` invocation reuses the
+    // same set.
+    const { buildDepsFromEnv } = await import('../src/handlers/index.js');
+    const deps = await buildDepsFromEnv({
+      ...makeBaseEnv(),
+      WEB_ORIGINS: 'https://app.example.com, https://staging.app.example.com',
+    });
+    expect(deps.webOrigins).toEqual(
+      new Set(['https://app.example.com', 'https://staging.app.example.com']),
+    );
+  });
+
+  it('omits webOrigins from deps when WEB_ORIGINS is unset', async () => {
+    const { buildDepsFromEnv } = await import('../src/handlers/index.js');
+    const deps = await buildDepsFromEnv(makeBaseEnv());
+    expect(deps.webOrigins).toBeUndefined();
+  });
+
+  it('omits webOrigins from deps when WEB_ORIGINS is an empty string', async () => {
+    const { buildDepsFromEnv } = await import('../src/handlers/index.js');
+    const deps = await buildDepsFromEnv({ ...makeBaseEnv(), WEB_ORIGINS: '' });
+    expect(deps.webOrigins).toBeUndefined();
+  });
 });
 
 describe('loadServerConfigFromLambdaEnv', () => {
@@ -248,3 +343,125 @@ describe('loadServerConfigFromLambdaEnv', () => {
     ]);
   });
 });
+
+describe('loadServerConfigFromLambdaEnv — EXTERNAL_ENABLED (SASL EXTERNAL opt-in)', () => {
+  it('leaves SASL EXTERNAL off when EXTERNAL_ENABLED is unset', () => {
+    const cfg = loadServerConfigFromLambdaEnv({ SERVER_NAME: 's', NETWORK_NAME: 'n' });
+    expect(cfg.sasl?.externalEnabled ?? false).toBe(false);
+  });
+
+  it('maps EXTERNAL_ENABLED=true to sasl.externalEnabled', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      EXTERNAL_ENABLED: 'true',
+    });
+    expect(cfg.sasl?.externalEnabled).toBe(true);
+  });
+
+  it('maps EXTERNAL_ENABLED=1 to sasl.externalEnabled', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      EXTERNAL_ENABLED: '1',
+    });
+    expect(cfg.sasl?.externalEnabled).toBe(true);
+  });
+
+  it('maps EXTERNAL_ENABLED=false (and any other value) to false', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      EXTERNAL_ENABLED: 'false',
+    });
+    expect(cfg.sasl?.externalEnabled).toBe(false);
+    const junk = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      EXTERNAL_ENABLED: 'yes please',
+    });
+    expect(junk.sasl?.externalEnabled ?? false).toBe(false);
+  });
+});
+
+describe('loadServerConfigFromLambdaEnv — adapter frame-rate limit', () => {
+  it('defaults the adapter frame window when the vars are unset', () => {
+    const cfg = loadServerConfigFromLambdaEnv({ SERVER_NAME: 's', NETWORK_NAME: 'n' });
+    expect(cfg.adapter).toEqual({ maxFramesPerWindow: 50, frameWindowSeconds: 5 });
+  });
+
+  it('maps MAX_FRAMES_PER_WINDOW + FRAME_WINDOW_SECONDS to the adapter section', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      MAX_FRAMES_PER_WINDOW: '20',
+      FRAME_WINDOW_SECONDS: '10',
+    });
+    expect(cfg.adapter).toEqual({ maxFramesPerWindow: 20, frameWindowSeconds: 10 });
+  });
+
+  it('fills the unset knob with its schema default when only one var is set', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      FRAME_WINDOW_SECONDS: '30',
+    });
+    expect(cfg.adapter).toEqual({ maxFramesPerWindow: 50, frameWindowSeconds: 30 });
+  });
+
+  it('throws when MAX_FRAMES_PER_WINDOW is non-numeric', () => {
+    expect(() =>
+      loadServerConfigFromLambdaEnv({
+        SERVER_NAME: 's',
+        NETWORK_NAME: 'n',
+        MAX_FRAMES_PER_WINDOW: 'many',
+      }),
+    ).toThrowError(/maxFramesPerWindow/u);
+  });
+
+  it('throws when FRAME_WINDOW_SECONDS is non-positive', () => {
+    expect(() =>
+      loadServerConfigFromLambdaEnv({
+        SERVER_NAME: 's',
+        NETWORK_NAME: 'n',
+        FRAME_WINDOW_SECONDS: '-1',
+      }),
+    ).toThrowError(/frameWindowSeconds/u);
+  });
+});
+
+describe('loadServerConfigFromLambdaEnv — per-IP admission knobs', () => {
+  it('defaults maxConnectionsPerIp / perIpConnectionRate from the schema', () => {
+    const cfg = loadServerConfigFromLambdaEnv({ SERVER_NAME: 's', NETWORK_NAME: 'n' });
+    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 = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      MAX_CONNECTIONS_PER_IP: '4',
+    });
+    expect(cfg.maxConnectionsPerIp).toBe(4);
+  });
+
+  it('parses PER_IP_CONNECTION_RATE_MAX / _WINDOW_MS into the rate knob', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      PER_IP_CONNECTION_RATE_MAX: '10',
+      PER_IP_CONNECTION_RATE_WINDOW_MS: '30000',
+    });
+    expect(cfg.perIpConnectionRate).toEqual({ max: 10, windowMs: 30_000 });
+  });
+
+  it('fills the unset half of the rate knob with the schema default', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      PER_IP_CONNECTION_RATE_WINDOW_MS: '10000',
+    });
+    expect(cfg.perIpConnectionRate).toEqual({ max: 5, windowMs: 10_000 });
+  });
+});