serverless-ircd 0.9.0 → 0.10.0

package/packages/aws-adapter/src/handlers/index.ts

@@ -14,7 +14,6 @@
 import { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanagementapi';
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import {
-  type AccountStore,
   EmptyMotdProvider,
   InMemoryNickHistoryStore,
   type MessageStore,
@@ -25,11 +24,11 @@ import {
   StaticMotdProvider,
   SystemClock,
 } from '@serverless-ircd/irc-core';
-import { resolveAccountStore } from '../account-store.js';
 import { type LambdaConfigEnv, loadServerConfigFromLambdaEnv } from '../config-loader.js';
 import { type DynamoServicesStore, loadDynamoServicesStore } from '../dynamo-services-store.js';
 import { createDynamoDocumentClient } from '../dynamo.js';
 import { bindMessageStore } from '../message-store.js';
+import { parseWebOrigins } from '../origin-allowlist.js';
 import { TABLE_KEYS, type TablesConfig } from '../tables.js';
 import { handleConnect } from './connect.js';
 import { handleDefault } from './default.js';
@@ -105,20 +104,15 @@ export interface HandlerDeps {
    * DynamoDB-backed variant is a documented follow-up.
    */
   messages: MessageStore;
-  /**
-   * SASL account verification source bound to every actor. Constructed
-   * once per cold start (memoised via {@link cachedDeps}) so it survives
-   * across warm Lambda invocations. `undefined` when no accounts are
-   * configured (the default) so `ctx.accounts` stays unset.
-   */
-  accounts?: AccountStore;
   /**
    * Persistent services store (NickServ / ChanServ / HostServ / MemoServ /
-   * OperServ + read-marker), hydrated once per cold start from the
-   * `Services` DynamoDB table into a write-behind cache. `undefined` when
-   * `SERVICES_TABLE` is unset (services unbound → no NickServ/ChanServ
-   * routing). The handler flushes pending writes after each `$default` /
-   * NLB frame so a Lambda freeze / evict does not lose services state.
+   * OperServ + read-marker + the unified SASL/PASS credential home),
+   * hydrated once per cold start from the `Services` DynamoDB table into a
+   * write-behind cache. `undefined` when `SERVICES_TABLE` is unset
+   * (services unbound → no NickServ/ChanServ routing, no SASL/PASS
+   * credential verify). The handler flushes pending writes after each
+   * `$default` / NLB frame so a Lambda freeze / evict does not lose
+   * services state.
    */
   services?: DynamoServicesStore;
   /**
@@ -136,6 +130,16 @@ export interface HandlerDeps {
    * path applies (error-suffixed `382`).
    */
   configLoader?: () => Promise<ServerConfig>;
+  /**
+   * Parsed `WEB_ORIGINS` allowlist for the `$connect` CSWSH defence.
+   * Empty set (the default) disables the check; non-empty causes
+   * {@link handleConnect} to reject browser-sent `Origin` headers that
+   * are not in the set with `403`. Built once per cold start from
+   * `process.env.WEB_ORIGINS` via {@link parseWebOrigins}; non-browser
+   * clients (curl, WeeChat, the `tcp-ws-forwarder`) never send `Origin`
+   * and always proceed regardless.
+   */
+  webOrigins?: Set<string> | undefined;
 }
 
 /**
@@ -196,7 +200,12 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
         tables: deps.tables,
         connectionId: connId,
         serverConfig: deps.serverConfig,
-        secWebSocketProtocol: event.headers?.['Sec-WebSocket-Protocol'] ?? null,
+        secWebSocketProtocol: readHeader(event.headers, 'Sec-WebSocket-Protocol'),
+        // APIGW normalises header keys to lowercase, but readHeader
+        // tolerates either casing so a future proxy / stage mutation
+        // cannot silently bypass the CSWSH defence.
+        originHeader: readHeader(event.headers, 'Origin'),
+        webOrigins: deps.webOrigins,
       });
       if (outcome.admitted) {
         if (outcome.subprotocol !== null) {
@@ -233,7 +242,6 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
           serverConfig: deps.serverConfig,
           motd: deps.motd,
           messages: deps.messages,
-          ...(deps.accounts !== undefined ? { accounts: deps.accounts } : {}),
           ...(deps.services !== undefined ? { services: deps.services } : {}),
           ...(deps.history !== undefined ? { history: deps.history } : {}),
           ...(deps.configLoader !== undefined ? { configLoader: deps.configLoader } : {}),
@@ -341,7 +349,6 @@ export async function nlbStreamHandler(event: NlbStreamEvent): Promise<NlbStream
     motd: deps.motd,
     messages: deps.messages,
     managementApi: deps.managementApi,
-    ...(deps.accounts !== undefined ? { accounts: deps.accounts } : {}),
     ...(deps.services !== undefined ? { services: deps.services } : {}),
     ...(deps.history !== undefined ? { history: deps.history } : {}),
   });
@@ -359,10 +366,16 @@ export {
  * Builds a {@link HandlerDeps} from the current `process.env`.
  *
  * Exposed so tests can construct production-shaped deps without re-running
- * the env parsing. Async because it scans the `Accounts` DynamoDB table
- * (via {@link resolveAccountStore}) to pre-load SASL credentials at cold
- * start — the {@link AccountStore} port is synchronous, so the scan must
- * complete before any reducer calls `verify`.
+ * the env parsing. Async because it scans the `Services` DynamoDB table
+ * (via {@link loadDynamoServicesStore}) to pre-load the services snapshot
+ * at cold start — the {@link ServicesStore} port is synchronous, so the
+ * scan must complete before any reducer calls `verifyNick` /
+ * `verifyCertFP`.
+ *
+ * After the services scan, the `SASL_ACCOUNTS` env-var seed is ingested
+ * into the services store via `registerNick` (idempotent — existing
+ * registrations, including NickServ-registered nicks, win over the env
+ * seed).
  */
 export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Promise<HandlerDeps> {
   const cfg = loadServerConfigFromLambdaEnv(env as LambdaConfigEnv);
@@ -378,13 +391,24 @@ export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Pr
   const motd = cfg.motdLines.length > 0 ? new StaticMotdProvider(cfg.motdLines) : EmptyMotdProvider;
   const messages = bindMessageStore(cfg);
   const history = new InMemoryNickHistoryStore(SystemClock);
-  const accounts = await resolveAccountStore(dynamo, tables.Accounts, cfg);
   const servicesTable = typeof env.SERVICES_TABLE === 'string' ? env.SERVICES_TABLE : undefined;
   const services = await loadDynamoServicesStore(dynamo, servicesTable, SystemClock);
+  if (services !== undefined) {
+    for (const acct of cfg.saslAccounts) {
+      services.registerNick(acct.username, acct.password, '');
+    }
+  }
   // REHASH reload source: re-read the live env so a rotated oper password
   // or MOTD takes effect on the next REHASH without a redeploy.
   const configLoader = async (): Promise<ServerConfig> =>
     loadServerConfigFromLambdaEnv(env as LambdaConfigEnv);
+  // CSWSH defence — parsed once per cold start so every `$connect`
+  // reuses the same set. Empty set (the default when `WEB_ORIGINS` is
+  // unset) disables the check; non-empty denies browser-sent origins
+  // that are not in the set. Non-browser clients never send `Origin`.
+  const webOrigins = parseWebOrigins(
+    typeof env.WEB_ORIGINS === 'string' ? env.WEB_ORIGINS : undefined,
+  );
   return {
     dynamo,
     tables,
@@ -394,7 +418,7 @@ export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Pr
     messages,
     history,
     configLoader,
-    ...(accounts !== undefined ? { accounts } : {}),
+    ...(webOrigins.size > 0 ? { webOrigins } : {}),
     ...(services !== undefined ? { services } : {}),
   };
 }
@@ -411,3 +435,23 @@ function tablesConfigFromEnv(env: NodeJS.ProcessEnv): TablesConfig {
   }
   return out;
 }
+
+/**
+ * Case-insensitive header lookup against an APIGW `event.headers` record.
+ *
+ * API Gateway WebSocket normalises header keys to lowercase, but HTTP
+ * proxies in front of it (ALB, CloudFront, custom domains) can preserve
+ * the original case. A case-sensitive lookup would silently miss the
+ * header under one of those routes — for the `Origin` CSWSH check that
+ * is a security hole, so this helper walks both casings. Returns `null`
+ * when absent so callers can pass it straight to handlers that
+ * distinguish "header absent" from "header empty".
+ */
+function readHeader(headers: Record<string, string> | undefined, name: string): string | null {
+  if (headers === undefined) return null;
+  const direct = headers[name];
+  if (typeof direct === 'string') return direct;
+  const lower = headers[name.toLowerCase()];
+  if (typeof lower === 'string') return lower;
+  return null;
+}

package/packages/aws-adapter/src/handlers/nlb-stream.ts

@@ -44,7 +44,6 @@ import type { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanageme
 import { GetCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
 import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import {
-  type AccountStore,
   type ChannelState,
   type Clock,
   type ConnectionState,
@@ -137,12 +136,11 @@ export interface NlbStreamParams {
   motd: MotdProvider;
   /** Chat-history persistence source (same as the wss `$default` path). */
   messages?: MessageStore;
-  /** SASL account verification source. */
-  accounts?: AccountStore;
   /**
    * Persistent services store (NickServ / ChanServ / HostServ / MemoServ /
-   * OperServ + read-marker). Flushed after each frame so a Lambda freeze
-   * does not lose services state.
+   * OperServ + read-marker + the unified SASL/PASS credential home).
+   * Flushed after each frame so a Lambda freeze does not lose services
+   * state.
    */
   services?: DynamoServicesStore;
   /** mTLS identity source for SASL EXTERNAL. */
@@ -264,7 +262,6 @@ export async function handleNlbStream(
     // WsTextFrameTransport splits on \r\n (no-op for already-split lines).
     transport: new WsTextFrameTransport(),
     ...(params.messages !== undefined ? { messages: params.messages } : {}),
-    ...(params.accounts !== undefined ? { accounts: params.accounts } : {}),
     ...(params.services !== undefined ? { services: params.services } : {}),
     ...(params.mtlsIdentity !== undefined ? { mtlsIdentity: params.mtlsIdentity } : {}),
     ...(params.history !== undefined ? { history: params.history } : {}),

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

@@ -16,17 +16,15 @@ export { cleanupConnection } from './aws-runtime.js';
 export { TABLE_KEYS, TABLE_NAMES, tablesConfigFromNames } from './tables.js';
 export type { TableName, TablesConfig } from './tables.js';
 export { createDynamoDocumentClient } from './dynamo.js';
-export {
-  DynamoAccountStore,
-  type HashedAccountCredential,
-  hashAccountCredential,
-  loadDynamoAccountStore,
-} from './dynamo-account-store.js';
-export { bindAccountStore, putAccountCredential, resolveAccountStore } from './account-store.js';
 export {
   DynamoServicesStore,
   loadDynamoServicesStore,
 } from './dynamo-services-store.js';
+export {
+  type HashedAccountCredential,
+  hashAccountCredential,
+  verifyHashedPassword,
+} from '@serverless-ircd/irc-core';
 export { AwsStats } from './stats.js';
 export type { AwsStatsOptions } from './stats.js';
 export {

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
@@ -116,6 +130,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,7 +66,6 @@ export function tablesConfigFromNames(names: {
   ChannelMeta: string;
   ChannelMembers: string;
   Nicks: string;
-  Accounts: string;
   Services?: string;
 }): TablesConfig {
   const out: TablesConfig = { ...names };

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 });
   }

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

@@ -155,6 +155,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', () => {

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

@@ -17,7 +17,6 @@ const TABLES: TablesConfig = {
   ChannelMeta: 'ChannelMeta',
   ChannelMembers: 'ChannelMembers',
   Nicks: 'Nicks',
-  Accounts: 'Accounts',
 };
 
 interface Stub {
@@ -298,3 +297,127 @@ describe('handleConnect — IRCv3 WebSocket subprotocol negotiation', () => {
     expect(stub.puts).toBe(0);
   });
 });
+
+describe('handleConnect — Origin allowlist (CSWSH defence)', () => {
+  // The same lowercase / trim / comma-split semantics as the CF Worker's
+  // policy (`apps/cf-worker/src/origin-allowlist.ts`); the parsed set is
+  // built once per cold start and injected via `ConnectParams.webOrigins`.
+  const allowlist = new Set(['https://app.example.com']);
+
+  it('denies a disallowed Origin with 403 before touching the counter', async () => {
+    // A denied upgrade must NOT consume an admission slot — the Origin
+    // check runs before the counter increment so a CSWSH flood from a
+    // hostile origin cannot exhaust the `maxClients` cap.
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-cswsh',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: 'https://attacker.example.com',
+      webOrigins: allowlist,
+    });
+    expect(outcome).toEqual({
+      admitted: false,
+      statusCode: 403,
+      reason: expect.stringMatching(/origin/iu),
+    });
+    expect(stub.puts).toBe(0);
+    expect(stub.increments).toBe(0);
+    expect(stub.decrements).toBe(0);
+  });
+
+  it('admits an allowed Origin (existing connect path)', async () => {
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-ok',
+      now: 42,
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: 'https://app.example.com',
+      webOrigins: allowlist,
+    });
+    expect(outcome).toEqual({ admitted: true, subprotocol: null });
+    expect(stub.puts).toBe(1);
+  });
+
+  it('case-insensitively matches a mixed-case allowed Origin', async () => {
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-case',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: 'https://APP.Example.COM',
+      webOrigins: allowlist,
+    });
+    expect(outcome.admitted).toBe(true);
+  });
+
+  it('admits a missing Origin (non-browser client: curl, WeeChat, tcp-ws-forwarder)', async () => {
+    // The defence only fires when `Origin` is present; non-browser
+    // tooling never sends it and must pass through unchanged.
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-cli',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: null,
+      webOrigins: allowlist,
+    });
+    expect(outcome.admitted).toBe(true);
+    expect(stub.puts).toBe(1);
+  });
+
+  it('admits a missing Origin when the header key is absent from the event', async () => {
+    // APIGW may omit the header entirely on some non-browser flows;
+    // `undefined` is treated the same as `null`.
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-noheader',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: undefined,
+      webOrigins: allowlist,
+    });
+    expect(outcome.admitted).toBe(true);
+  });
+
+  it('skips the check when WEB_ORIGINS is unset (defence is opt-in)', async () => {
+    // An empty allowlist means the deployment has not opted in; every
+    // Origin (including an obviously hostile one) must proceed so
+    // existing AWS deployments without a web frontend are unchanged
+    // on upgrade.
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-unset',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: 'https://attacker.example.com',
+      webOrigins: new Set(),
+    });
+    expect(outcome.admitted).toBe(true);
+    expect(stub.puts).toBe(1);
+  });
+
+  it('denies an Origin that matches a listed origin except for the scheme', async () => {
+    // Origins are case-sensitive on scheme+host+port; an `http://`
+    // form MUST NOT be admitted against an `https://`-only allowlist
+    // (defends against a stripped-TLS attacker on the same hostname).
+    const stub = makeStub(0);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-scheme',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      originHeader: 'http://app.example.com',
+      webOrigins: allowlist,
+    });
+    expect(outcome.admitted).toBe(false);
+    expect(outcome.admitted === false && outcome.statusCode).toBe(403);
+  });
+});