serverless-ircd 0.9.0 → 0.11.0

package/apps/aws-stack/tests/stack.test.ts

@@ -3,7 +3,7 @@
  *
  * These are the primary red→green tests for the infrastructure stack:
  * they assert the exact CloudFormation shape that `cdk synth` must
- * produce — six DynamoDB tables with the PLAN §4 schema, a single
+ * produce — five DynamoDB tables with the PLAN §4 schema, a single
  * Node 24 Lambda wired to all three WebSocket routes, the API Gateway
  * v2 WebSocket API, the two stack outputs, and a least-privilege guard
  * that no IAM policy grants `Resource: '*'` or `Action: '*'`.
@@ -18,28 +18,31 @@ import { App, type Stack } from 'aws-cdk-lib';
 import { Template } from 'aws-cdk-lib/assertions';
 import { describe, expect, it } from 'vitest';
 import { IrcAwsStack } from '../src/aws-stack.js';
+import type { StaticSiteProps } from '../src/static-site.js';
 
 /** All five table names that must exist in the stack (PLAN §4). */
-const TABLE_NAMES = ['Accounts', 'ChannelMembers', 'ChannelMeta', 'Connections', 'Nicks'] as const;
-
-/** Default environment name assumed when the prop is omitted. */
-const DEFAULT_ENV = 'staging';
+const TABLE_NAMES = ['ChannelMembers', 'ChannelMeta', 'Connections', 'Nicks', 'Services'] as const;
 
 /**
- * Capitalises the first character of an environment name so it composes
- * cleanly with the PascalCase logical table ids (`staging` → `Staging`).
+ * Raw synthesised CloudFormation node for a DynamoDB table. `DeletionPolicy`
+ * and `UpdateReplacePolicy` live at the resource root (siblings of
+ * `Properties`), so they are NOT visible via `Template.hasResourceProperties`
+ * — tests that assert the removal policy inspect the full node.
  */
-function prefixedTableName(environmentName: string, logicalId: string): string {
-  return `${environmentName.charAt(0).toUpperCase()}${environmentName.slice(1)}${logicalId}`;
-}
+type DynamoTableResource = {
+  Type: string;
+  DeletionPolicy?: string;
+  UpdateReplacePolicy?: string;
+  Properties?: {
+    TableName?: string;
+    PointInTimeRecoverySpecification?: { PointInTimeRecoveryEnabled?: boolean };
+    DeletionProtectionEnabled?: boolean;
+  };
+};
 
-function makeTemplate(environmentName?: string): { app: App; stack: Stack; template: Template } {
+function makeTemplate(): { app: App; stack: Stack; template: Template } {
   const app = new App();
-  const stack = new IrcAwsStack(
-    app,
-    'TestStack',
-    environmentName !== undefined ? { environmentName } : undefined,
-  );
+  const stack = new IrcAwsStack(app, 'TestStack');
   const template = Template.fromStack(stack);
   return { app, stack, template };
 }
@@ -79,15 +82,15 @@ function findRuleTargetingLambda(
 }
 
 describe('IrcAwsStack — DynamoDB tables', () => {
-  it('creates exactly six DynamoDB tables', () => {
+  it('creates exactly five DynamoDB tables', () => {
     const { template } = makeTemplate();
-    template.resourceCountIs('AWS::DynamoDB::Table', 6);
+    template.resourceCountIs('AWS::DynamoDB::Table', 5);
   });
 
   it.each(TABLE_NAMES)('creates the %s table', (tableName) => {
     const { template } = makeTemplate();
     template.hasResourceProperties('AWS::DynamoDB::Table', {
-      TableName: prefixedTableName(DEFAULT_ENV, tableName),
+      TableName: tableName,
     });
   });
 
@@ -101,7 +104,7 @@ describe('IrcAwsStack — DynamoDB tables', () => {
   it('enables TTL on the Connections table via the idleSince attribute', () => {
     const { template } = makeTemplate();
     template.hasResourceProperties('AWS::DynamoDB::Table', {
-      TableName: prefixedTableName(DEFAULT_ENV, 'Connections'),
+      TableName: 'Connections',
       TimeToLiveSpecification: {
         AttributeName: 'idleSince',
         Enabled: true,
@@ -112,8 +115,13 @@ describe('IrcAwsStack — DynamoDB tables', () => {
   it('keys the Connections table by connectionId (String)', () => {
     const { template } = makeTemplate();
     template.hasResourceProperties('AWS::DynamoDB::Table', {
-      TableName: prefixedTableName(DEFAULT_ENV, 'Connections'),
-      AttributeDefinitions: [{ AttributeName: 'connectionId', AttributeType: 'S' }],
+      TableName: 'Connections',
+      // connectionId (base key) plus the per-IP admission GSI keys.
+      AttributeDefinitions: [
+        { AttributeName: 'connectionId', AttributeType: 'S' },
+        { AttributeName: 'sourceIp', AttributeType: 'S' },
+        { AttributeName: 'connectedSince', AttributeType: 'N' },
+      ],
       KeySchema: [{ AttributeName: 'connectionId', KeyType: 'HASH' }],
     });
   });
@@ -121,7 +129,7 @@ describe('IrcAwsStack — DynamoDB tables', () => {
   it('keys the ChannelMembers table by channelName (PK) + connectionId (SK)', () => {
     const { template } = makeTemplate();
     template.hasResourceProperties('AWS::DynamoDB::Table', {
-      TableName: prefixedTableName(DEFAULT_ENV, 'ChannelMembers'),
+      TableName: 'ChannelMembers',
       AttributeDefinitions: [
         { AttributeName: 'channelName', AttributeType: 'S' },
         { AttributeName: 'connectionId', AttributeType: 'S' },
@@ -136,7 +144,7 @@ describe('IrcAwsStack — DynamoDB tables', () => {
   it('keys the ChannelMeta table by channelName (String)', () => {
     const { template } = makeTemplate();
     template.hasResourceProperties('AWS::DynamoDB::Table', {
-      TableName: prefixedTableName(DEFAULT_ENV, 'ChannelMeta'),
+      TableName: 'ChannelMeta',
       AttributeDefinitions: [{ AttributeName: 'channelName', AttributeType: 'S' }],
       KeySchema: [{ AttributeName: 'channelName', KeyType: 'HASH' }],
     });
@@ -145,25 +153,16 @@ describe('IrcAwsStack — DynamoDB tables', () => {
   it('keys the Nicks table by nickLower (String)', () => {
     const { template } = makeTemplate();
     template.hasResourceProperties('AWS::DynamoDB::Table', {
-      TableName: prefixedTableName(DEFAULT_ENV, 'Nicks'),
+      TableName: 'Nicks',
       AttributeDefinitions: [{ AttributeName: 'nickLower', AttributeType: 'S' }],
       KeySchema: [{ AttributeName: 'nickLower', KeyType: 'HASH' }],
     });
   });
 
-  it('keys the Accounts table by account (String)', () => {
-    const { template } = makeTemplate();
-    template.hasResourceProperties('AWS::DynamoDB::Table', {
-      TableName: prefixedTableName(DEFAULT_ENV, 'Accounts'),
-      AttributeDefinitions: [{ AttributeName: 'account', AttributeType: 'S' }],
-      KeySchema: [{ AttributeName: 'account', KeyType: 'HASH' }],
-    });
-  });
-
   it('keys the Services table by composite pk/sk (String/String)', () => {
     const { template } = makeTemplate();
     template.hasResourceProperties('AWS::DynamoDB::Table', {
-      TableName: prefixedTableName(DEFAULT_ENV, 'Services'),
+      TableName: 'Services',
       AttributeDefinitions: [
         { AttributeName: 'pk', AttributeType: 'S' },
         { AttributeName: 'sk', AttributeType: 'S' },
@@ -176,6 +175,173 @@ describe('IrcAwsStack — DynamoDB tables', () => {
   });
 });
 
+describe('IrcAwsStack — DynamoDB table protection (RETAIN + PITR + deletion protection)', () => {
+  /**
+   * State-bearing tables hold user data (nicks, services credentials,
+   * channel state, membership) and MUST survive a mistaken `cdk destroy`,
+   * a stack-name collision, or a stray `aws dynamodb delete-table` from a
+   * compromised credential. `Connections` is the one exception: its rows
+   * are ephemeral per-connection records (TTL-reaped, sweeper-cleaned), so
+   * it stays DESTROY with no PITR and no deletion protection.
+   */
+  const STATE_TABLES = ['ChannelMembers', 'ChannelMeta', 'Nicks', 'Services'] as const;
+  const EPHEMERAL_TABLE = 'Connections';
+
+  /**
+   * Returns the synthesised `AWS::DynamoDB::Table` resources keyed by their
+   * physical `TableName`. Each value is the raw CloudFormation resource
+   * node, so `DeletionPolicy`, `UpdateReplacePolicy`, and the protection
+   * properties under `Properties` are all inspectable. `DeletionPolicy` lives
+   * at the resource root (sibling of `Properties`), so it is NOT visible to
+   * `hasResourceProperties` — the raw node is required.
+   */
+  function dynamoTablesByName(template: Template): Record<
+    string,
+    {
+      Type: string;
+      DeletionPolicy?: string;
+      UpdateReplacePolicy?: string;
+      Properties?: {
+        TableName?: string;
+        PointInTimeRecoverySpecification?: { PointInTimeRecoveryEnabled?: boolean };
+        DeletionProtectionEnabled?: boolean;
+      };
+    }
+  > {
+    const tmpl = template.toJSON() as { Resources?: Record<string, unknown> };
+    const out: Record<string, DynamoTableResource> = {};
+    for (const raw of Object.values(tmpl.Resources ?? {})) {
+      const res = raw as { Type?: string; Properties?: { TableName?: string } };
+      if (res.Type !== 'AWS::DynamoDB::Table') {
+        continue;
+      }
+      const name = res.Properties?.TableName;
+      if (typeof name === 'string') {
+        out[name] = raw as DynamoTableResource;
+      }
+    }
+    return out;
+  }
+
+  describe('default synth (no flags)', () => {
+    it.each(STATE_TABLES)('RETAINs the %s table (DeletionPolicy=Retain)', (name) => {
+      const { template } = makeTemplate();
+      expect(dynamoTablesByName(template)[name]?.DeletionPolicy).toBe('Retain');
+    });
+
+    it.each(STATE_TABLES)('sets UpdateReplacePolicy=Retain on the %s table', (name) => {
+      const { template } = makeTemplate();
+      expect(dynamoTablesByName(template)[name]?.UpdateReplacePolicy).toBe('Retain');
+    });
+
+    it('keeps the Connections table DESTROY (DeletionPolicy=Delete)', () => {
+      const { template } = makeTemplate();
+      expect(dynamoTablesByName(template)[EPHEMERAL_TABLE]?.DeletionPolicy).toBe('Delete');
+    });
+
+    it.each(STATE_TABLES)('enables point-in-time recovery on the %s table', (name) => {
+      const { template } = makeTemplate();
+      expect(
+        dynamoTablesByName(template)[name]?.Properties?.PointInTimeRecoverySpecification
+          ?.PointInTimeRecoveryEnabled,
+      ).toBe(true);
+    });
+
+    it('does NOT enable point-in-time recovery on the Connections table', () => {
+      const { template } = makeTemplate();
+      expect(
+        dynamoTablesByName(template)[EPHEMERAL_TABLE]?.Properties?.PointInTimeRecoverySpecification,
+      ).toBeUndefined();
+    });
+
+    it.each(STATE_TABLES)('enables deletion protection on the %s table', (name) => {
+      const { template } = makeTemplate();
+      expect(dynamoTablesByName(template)[name]?.Properties?.DeletionProtectionEnabled).toBe(true);
+    });
+
+    it('does NOT enable deletion protection on the Connections table', () => {
+      const { template } = makeTemplate();
+      expect(
+        dynamoTablesByName(template)[EPHEMERAL_TABLE]?.Properties?.DeletionProtectionEnabled,
+      ).toBeUndefined();
+    });
+  });
+
+  describe('allowTableDeletion=true synth (teardown mode)', () => {
+    function makeTeardownTemplate(): Template {
+      const app = new App();
+      const stack = new IrcAwsStack(app, 'TestStack', { allowTableDeletion: true });
+      return Template.fromStack(stack);
+    }
+
+    it.each(STATE_TABLES)('flips the %s table to DESTROY (DeletionPolicy=Delete)', (name) => {
+      const template = makeTeardownTemplate();
+      expect(dynamoTablesByName(template)[name]?.DeletionPolicy).toBe('Delete');
+    });
+
+    it.each(STATE_TABLES)('disables deletion protection on the %s table', (name) => {
+      const template = makeTeardownTemplate();
+      expect(dynamoTablesByName(template)[name]?.Properties?.DeletionProtectionEnabled).toBe(false);
+    });
+
+    it('keeps the Connections table DESTROY', () => {
+      const template = makeTeardownTemplate();
+      expect(dynamoTablesByName(template)[EPHEMERAL_TABLE]?.DeletionPolicy).toBe('Delete');
+    });
+
+    it('still keeps point-in-time recovery enabled on state tables in teardown mode', () => {
+      // allowTableDeletion and enablePitr are independent flags: a legitimate
+      // teardown still keeps PITR on (it is harmless and the data is still
+      // recoverable up until the table is actually deleted). Disabling PITR
+      // is a separate, deliberate opt-in via enablePitr=false.
+      const template = makeTeardownTemplate();
+      for (const name of STATE_TABLES) {
+        expect(
+          dynamoTablesByName(template)[name]?.Properties?.PointInTimeRecoverySpecification
+            ?.PointInTimeRecoveryEnabled,
+        ).toBe(true);
+      }
+    });
+  });
+
+  describe('enablePitr=false synth (PITR disabled)', () => {
+    function makeNoPitrTemplate(): Template {
+      const app = new App();
+      const stack = new IrcAwsStack(app, 'TestStack', { enablePitr: false });
+      return Template.fromStack(stack);
+    }
+
+    it.each(STATE_TABLES)('disables point-in-time recovery on the %s table', (name) => {
+      const template = makeNoPitrTemplate();
+      expect(
+        dynamoTablesByName(template)[name]?.Properties?.PointInTimeRecoverySpecification
+          ?.PointInTimeRecoveryEnabled,
+      ).toBe(false);
+    });
+
+    it('still does NOT enable point-in-time recovery on the Connections table', () => {
+      const template = makeNoPitrTemplate();
+      expect(
+        dynamoTablesByName(template)[EPHEMERAL_TABLE]?.Properties?.PointInTimeRecoverySpecification,
+      ).toBeUndefined();
+    });
+
+    it('keeps state tables RETAIN with deletion protection when PITR is disabled', () => {
+      // enablePitr=false narrows ONLY the PITR knob; the RETAIN +
+      // deletion-protection guarantees are independent of PITR and must
+      // remain on so a disabled-PITR deploy is still protected from
+      // accidental stack deletion.
+      const template = makeNoPitrTemplate();
+      for (const name of STATE_TABLES) {
+        expect(dynamoTablesByName(template)[name]?.DeletionPolicy).toBe('Retain');
+        expect(dynamoTablesByName(template)[name]?.Properties?.DeletionProtectionEnabled).toBe(
+          true,
+        );
+      }
+    });
+  });
+});
+
 describe('IrcAwsStack — API Gateway v2 WebSocket API', () => {
   it('creates a WebSocket protocol API Gateway v2 API', () => {
     const { template } = makeTemplate();
@@ -287,12 +453,20 @@ describe('IrcAwsStack — API Gateway logging', () => {
     ]);
   });
 
-  it('wires the stage execution logging level to the parameter (Ref) with data tracing on', () => {
+  it('wires the stage execution logging level to the parameter (Ref) with full-frame body tracing OFF by default', () => {
+    // Regression guard: `dataTraceEnabled` MUST default to `false`. For a
+    // WebSocket IRC endpoint, APIGW execution-log body tracing writes the
+    // full payload of every frame — including `PASS <password>`,
+    // `AUTHENTICATE <base64-SASL-PLAIN>`, `JOIN #chan <channel-key>`, and
+    // every `PRIVMSG`/`NOTICE` — to the APIGW CloudWatch log group. Anyone
+    // with `logs:GetLogEvents` recovers IRC credentials verbatim. The
+    // default is therefore safe-by-default; re-enabling requires an
+    // explicit, double-opt-in escape hatch (see the guard tests below).
     const { template } = makeTemplate();
     template.hasResourceProperties('AWS::ApiGatewayV2::Stage', {
       DefaultRouteSettings: {
         LoggingLevel: { Ref: 'ApiGatewayLoggingLevel' },
-        DataTraceEnabled: true,
+        DataTraceEnabled: false,
       },
     });
   });
@@ -361,15 +535,12 @@ describe('IrcAwsStack — API Gateway logging', () => {
     ).toBe(true);
   });
 
-  it('grants the logging role CloudWatch Logs write access across ALL log groups', () => {
-    // APIGW writes execution logs to its OWN AWS/ApiGateway... log groups
-    // (separate from this stack's access-log group), so the role must be
-    // able to write broadly — a single-log-group ARN scope is rejected by
-    // APIGW account-role validation. Defined inline (the
-    // AmazonAPIGatewayPushToCloudWatchLogs managed policy is not available
-    // in every partition); CDK renders the statement as a separate
-    // AWS::IAM::Policy attached to the role.
-    const { template } = makeTemplate();
+  /**
+   * Flattens the IAM actions granted by the inline policy CDK attaches to
+   * the `ApiGatewayLoggingRole` (`addToPolicy` renders as a separate
+   * `AWS::IAM::Policy` resource referencing the role).
+   */
+  function loggingRoleActions(template: Template): string[] {
     const roles = template.findResources('AWS::IAM::Role') as Record<string, unknown>;
     const loggingRoleEntry = Object.entries(roles).find(([id]) =>
       id.startsWith('ApiGatewayLoggingRole'),
@@ -394,12 +565,102 @@ describe('IrcAwsStack — API Gateway logging', () => {
     const stmts = attached?.Properties?.PolicyDocument?.Statement ?? [];
     const flat = (a: string | string[] | undefined): string[] =>
       Array.isArray(a) ? a : a !== undefined ? [a] : [];
-    const actions = JSON.stringify(stmts.flatMap((s) => flat(s.Action)));
-    const resources = JSON.stringify(stmts.flatMap((s) => flat(s.Resource as string[])));
-    expect(actions).toContain('logs:PutLogEvents');
-    expect(actions).toContain('logs:CreateLogGroup');
-    // Broad scope — NOT narrowed to a single log-group ARN.
-    expect(resources).toContain('*');
+    return stmts.flatMap((s) => flat(s.Action));
+  }
+
+  it('grants the logging role exactly the three CloudWatch Logs WRITE actions across ALL log groups', () => {
+    // APIGW writes execution logs to its OWN AWS/ApiGateway... log groups
+    // (separate from this stack's access-log group), so the role must be
+    // able to write broadly — a single-log-group ARN scope is rejected by
+    // APIGW account-role validation. The grant set is EXACTLY the three
+    // write actions APIGW needs; the legacy inline policy additionally
+    // carried Describe* actions, which let a compromised role enumerate
+    // (and, via the managed policy AWS offers for this purpose, read)
+    // arbitrary log groups in the account. Exact-set assertion so any
+    // future widening fails this test.
+    const { template } = makeTemplate();
+    expect([...loggingRoleActions(template)].sort()).toEqual([
+      'logs:CreateLogGroup',
+      'logs:CreateLogStream',
+      'logs:PutLogEvents',
+    ]);
+  });
+
+  it('does not grant the logging role any log-enumeration or log-read actions', () => {
+    const { template } = makeTemplate();
+    const actions = loggingRoleActions(template);
+    expect(
+      actions.filter((a) => /^logs:(Describe|Get|Filter)/.test(a)),
+      'logging role must not enumerate or read log groups',
+    ).toEqual([]);
+  });
+
+  it('attaches no AWS-managed policies to the logging role (documented inline decision)', () => {
+    // Decision record: the AmazonAPIGatewayPushToCloudWatchLogs managed
+    // policy was considered and REJECTED. Its fixed grant set is broader
+    // than the tightened inline policy — it still grants DescribeLogGroups
+    // and DescribeLogStreams (the actions this stack deliberately drops)
+    // plus GetLogEvents and FilterLogEvents, all on Resource '*' — and AWS
+    // can widen its contents without this stack being re-reviewed. The
+    // inline policy keeps the grant set exact and auditable at synth time.
+    const { template } = makeTemplate();
+    const roles = template.findResources('AWS::IAM::Role') as Record<
+      string,
+      { Properties?: { ManagedPolicyArns?: unknown } }
+    >;
+    const loggingRole = Object.entries(roles).find(([id]) =>
+      id.startsWith('ApiGatewayLoggingRole'),
+    );
+    expect(loggingRole, 'expected an ApiGatewayLoggingRole').toBeDefined();
+    expect(loggingRole?.[1]?.Properties?.ManagedPolicyArns).toBeUndefined();
+  });
+});
+
+describe('IrcAwsStack — `dataTraceEnabled` credential-leak guard', () => {
+  /**
+   * Since the staging/prod split was collapsed (every synth is effectively a
+   * prod synth), `dataTraceEnabled` defaults to `false` and the ONLY way to
+   * re-enable it is the explicit `allowDataTrace` + `iUnderstandThisLeaksCredentials`
+   * double opt-in. Enabling without the confirmation REFUSES synthesis with a
+   * loud error naming the IRC credentials it would leak.
+   */
+  it('refuses synth when allowDataTrace=true is set WITHOUT the leak acknowledgement', () => {
+    const app = new App();
+    expect(() => new IrcAwsStack(app, 'TestStack', { allowDataTrace: true })).toThrow(
+      /DataTraceEnabled|dataTraceEnabled|leak|credential/i,
+    );
+  });
+
+  it('still refuses synth when allowDataTrace=true is set but the acknowledgement is explicitly false', () => {
+    // Belt-and-braces: an explicit `false` confirmation is identical to
+    // omitting it — the guard must not be bypassable by passing the prop.
+    const app = new App();
+    expect(
+      () =>
+        new IrcAwsStack(app, 'TestStack', {
+          allowDataTrace: true,
+          iUnderstandThisLeaksCredentials: false,
+        }),
+    ).toThrow(/DataTraceEnabled|dataTraceEnabled|leak|credential/i);
+  });
+
+  it('permits dataTraceEnabled ONLY when allowDataTrace AND the leak acknowledgement are BOTH true', () => {
+    // The documented dev escape hatch: a sandbox operator who has read the
+    // warning can force-enable full-frame tracing by supplying the
+    // two-step opt-in. This is the ONLY path that produces
+    // DataTraceEnabled=true, and it is deliberately awkward to set.
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', {
+      allowDataTrace: true,
+      iUnderstandThisLeaksCredentials: true,
+    });
+    const template = Template.fromStack(stack);
+    template.hasResourceProperties('AWS::ApiGatewayV2::Stage', {
+      DefaultRouteSettings: {
+        LoggingLevel: { Ref: 'ApiGatewayLoggingLevel' },
+        DataTraceEnabled: true,
+      },
+    });
   });
 });
 
@@ -438,7 +699,7 @@ describe('IrcAwsStack — gone-connection sweeper', () => {
     // Both Lambda roles must scope their DynamoDB actions to the concrete
     // table ARNs — the least-privilege suite below also asserts no '*'.
     const tables = template.findResources('AWS::DynamoDB::Table');
-    expect(Object.keys(tables)).toHaveLength(6);
+    expect(Object.keys(tables)).toHaveLength(5);
   });
 });
 
@@ -637,73 +898,44 @@ describe('IrcAwsStack — least-privilege IAM', () => {
   });
 });
 
-describe('IrcAwsStack — environmentName prop (env isolation)', () => {
-  it('prefixes the Connections table name with the production environment', () => {
-    const { template } = makeTemplate('production');
-    template.hasResourceProperties('AWS::DynamoDB::Table', {
-      TableName: 'ProductionConnections',
-    });
-  });
-
-  it('prefixes the Connections table name with the staging environment', () => {
-    const { template } = makeTemplate('staging');
+describe('IrcAwsStack — single deploy target (no env prefixing)', () => {
+  it('uses the bare logical id as the Connections table name (no env prefix)', () => {
+    const { template } = makeTemplate();
     template.hasResourceProperties('AWS::DynamoDB::Table', {
-      TableName: 'StagingConnections',
+      TableName: 'Connections',
     });
   });
 
-  it('defaults to the staging prefix when the prop is omitted', () => {
+  it('uses the bare logical id as the Services table name (no env prefix)', () => {
     const { template } = makeTemplate();
     template.hasResourceProperties('AWS::DynamoDB::Table', {
-      TableName: prefixedTableName(DEFAULT_ENV, 'Connections'),
+      TableName: 'Services',
     });
   });
 
-  it('injects the prefixed physical table name into every Lambda env var', () => {
-    const { template } = makeTemplate('production');
+  it('injects the bare logical table name into every Lambda env var', () => {
+    const { template } = makeTemplate();
     const fns = template.findResources('AWS::Lambda::Function') as Record<
       string,
       { Properties?: { Environment?: { Variables?: Record<string, string> } } }
     >;
-    // Every Lambda must carry CONNECTIONS_TABLE pointing at the production-prefixed name.
-    const withPrefixed = Object.values(fns).filter(
-      (fn) => fn.Properties?.Environment?.Variables?.CONNECTIONS_TABLE === 'ProductionConnections',
-    );
-    expect(withPrefixed).toHaveLength(3);
-  });
-
-  it('produces non-colliding table names for staging vs production', () => {
-    const stagingTables = Object.keys(
-      makeTemplate('staging').template.findResources('AWS::DynamoDB::Table'),
+    // Every Lambda must carry CONNECTIONS_TABLE pointing at the bare name.
+    const withBare = Object.values(fns).filter(
+      (fn) => fn.Properties?.Environment?.Variables?.CONNECTIONS_TABLE === 'Connections',
     );
-    const prodTables = Object.keys(
-      makeTemplate('production').template.findResources('AWS::DynamoDB::Table'),
-    );
-    const stagingNames = new Set(
-      Object.values(
-        makeTemplate('staging').template.findResources('AWS::DynamoDB::Table') as Record<
-          string,
-          { Properties: { TableName: string } }
-        >,
-      ).map((t) => t.Properties.TableName),
-    );
-    const prodNames = Object.values(
-      makeTemplate('production').template.findResources('AWS::DynamoDB::Table') as Record<
-        string,
-        { Properties: { TableName: string } }
-      >,
-    ).map((t) => t.Properties.TableName);
-    expect(stagingTables).toHaveLength(6);
-    expect(prodTables).toHaveLength(6);
-    expect(prodNames.every((n) => !stagingNames.has(n))).toBe(true);
+    expect(withBare).toHaveLength(3);
   });
 
-  it('includes the environment suffix in the CloudFormation stack name', () => {
-    const app = new App();
-    const stack = new IrcAwsStack(app, 'IrcAwsStack-production', {
-      environmentName: 'production',
-    });
-    expect(stack.stackName).toBe('IrcAwsStack-production');
+  it('produces a fixed set of bare table names (no Staging* / Production* prefixes)', () => {
+    const { template } = makeTemplate();
+    const tables = template.findResources('AWS::DynamoDB::Table') as Record<
+      string,
+      { Properties: { TableName: string } }
+    >;
+    const names = Object.values(tables).map((t) => t.Properties.TableName);
+    expect(names).toHaveLength(5);
+    // No name may carry a capitalized environment prefix.
+    expect(names.every((n) => !/^(Staging|Production)/.test(n))).toBe(true);
   });
 });
 
@@ -853,6 +1085,82 @@ describe('IrcAwsStack — server identity CloudFormation parameters', () => {
   });
 });
 
+describe('IrcAwsStack — `$connect` Origin allowlist (CSWSH defence)', () => {
+  /** Finds a Lambda function resource by its logical-id prefix (e.g. `IrcHandler`). */
+  function findFunction(
+    template: Template,
+    idPrefix: string,
+  ): {
+    Properties?: { Environment?: { Variables?: Record<string, unknown> } };
+  } {
+    const fns = template.findResources('AWS::Lambda::Function') as Record<
+      string,
+      { Properties?: { Environment?: { Variables?: Record<string, unknown> } } }
+    >;
+    const found = Object.entries(fns).find(([id]) => id.startsWith(idPrefix));
+    if (!found) {
+      throw new Error(`No Lambda with logical id starting with "${idPrefix}"`);
+    }
+    return found[1];
+  }
+
+  it('does NOT inject WEB_ORIGINS on the handler when the prop is omitted (defence opt-in)', () => {
+    // The CSWSH defence is opt-in: existing AWS deployments without a
+    // web frontend must be unchanged on upgrade, so the env var is
+    // omitted entirely (not set to '') when the prop is absent. The
+    // handler's parser then returns an empty set and the `$connect`
+    // Origin check is skipped.
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack');
+    const template = Template.fromStack(stack);
+    expect(
+      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.WEB_ORIGINS,
+    ).toBeUndefined();
+  });
+
+  it('does NOT inject WEB_ORIGINS when the prop is an empty string', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', { webOrigins: '' });
+    const template = Template.fromStack(stack);
+    expect(
+      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.WEB_ORIGINS,
+    ).toBeUndefined();
+  });
+
+  it('injects WEB_ORIGINS on the wss handler when the prop is set', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', {
+      webOrigins: 'https://app.example.com, https://staging.app.example.com',
+    });
+    const template = Template.fromStack(stack);
+    expect(
+      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.WEB_ORIGINS,
+    ).toBe('https://app.example.com, https://staging.app.example.com');
+  });
+
+  it('does NOT inject WEB_ORIGINS on the sweeper (never runs `$connect`)', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', {
+      webOrigins: 'https://app.example.com',
+    });
+    const template = Template.fromStack(stack);
+    expect(
+      findFunction(template, 'IrcSweeper').Properties?.Environment?.Variables?.WEB_ORIGINS,
+    ).toBeUndefined();
+  });
+
+  it('does NOT inject WEB_ORIGINS on the ping checker (never runs `$connect`)', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', {
+      webOrigins: 'https://app.example.com',
+    });
+    const template = Template.fromStack(stack);
+    expect(
+      findFunction(template, 'IrcPingChecker').Properties?.Environment?.Variables?.WEB_ORIGINS,
+    ).toBeUndefined();
+  });
+});
+
 describe('IrcAwsStack — TCP+TLS NLB adapter', () => {
   /** Makes a template WITH the tcpTlsDomainName prop (enables the NLB path). */
   function makeTcpTemplate(domainName = 'irc.example.com'): {
@@ -862,7 +1170,6 @@ describe('IrcAwsStack — TCP+TLS NLB adapter', () => {
   } {
     const app = new App();
     const stack = new IrcAwsStack(app, 'TestStack', {
-      environmentName: 'staging',
       tcpTlsDomainName: domainName,
     });
     const template = Template.fromStack(stack);
@@ -933,6 +1240,101 @@ describe('IrcAwsStack — TCP+TLS NLB adapter', () => {
       });
     });
 
+    /**
+     * Collects every IAM policy statement attached to the NLB handler
+     * Lambda's execution role — the role's inline `Policies` plus every
+     * separate `AWS::IAM::Policy` resource referencing it (CDK renders
+     * `grant*` calls as the role's `DefaultPolicy` resource).
+     */
+    function nlbRoleStatements(template: Template): Array<Record<string, unknown>> {
+      const fns = template.findResources('AWS::Lambda::Function') as Record<
+        string,
+        { Properties?: { Role?: { 'Fn::GetAtt'?: string[] } | { Ref?: string } } }
+      >;
+      const nlbFn = Object.entries(fns).find(([id]) => id.startsWith('IrcNlbHandler'));
+      if (nlbFn === undefined) {
+        throw new Error('No Lambda with logical id starting with "IrcNlbHandler"');
+      }
+      const role = nlbFn[1]?.Properties?.Role as
+        | { 'Fn::GetAtt'?: string[]; Ref?: string }
+        | undefined;
+      const getAtt = role?.['Fn::GetAtt'];
+      const roleLogicalId = Array.isArray(getAtt) ? getAtt[0] : role?.Ref;
+      if (typeof roleLogicalId !== 'string') {
+        throw new Error('IrcNlbHandler Lambda has no resolvable execution role');
+      }
+      const statements: Array<Record<string, unknown>> = [];
+      const roles = template.findResources('AWS::IAM::Role') as Record<
+        string,
+        { Properties?: { Policies?: Array<{ PolicyDocument?: { Statement?: unknown[] } }> } }
+      >;
+      for (const inline of roles[roleLogicalId]?.Properties?.Policies ?? []) {
+        statements.push(
+          ...((inline.PolicyDocument?.Statement ?? []) as Array<Record<string, unknown>>),
+        );
+      }
+      const policies = template.findResources('AWS::IAM::Policy') as Record<
+        string,
+        {
+          Properties?: {
+            Roles?: Array<{ Ref?: string }>;
+            PolicyDocument?: { Statement?: unknown[] };
+          };
+        }
+      >;
+      for (const policy of Object.values(policies)) {
+        const attached = (policy.Properties?.Roles ?? []).some((r) => r.Ref === roleLogicalId);
+        if (attached) {
+          statements.push(
+            ...((policy.Properties?.PolicyDocument?.Statement ?? []) as Array<
+              Record<string, unknown>
+            >),
+          );
+        }
+      }
+      return statements;
+    }
+
+    /** True when a statement's Action includes `execute-api:ManageConnections`. */
+    function managesConnections(stmt: Record<string, unknown>): boolean {
+      const action = stmt.Action;
+      return (
+        action === 'execute-api:ManageConnections' ||
+        (Array.isArray(action) && action.includes('execute-api:ManageConnections'))
+      );
+    }
+
+    it('grants the NLB handler Lambda execute-api:ManageConnections on the stage', () => {
+      // The NLB stream handler passes MANAGEMENT_URL into AwsRuntime and
+      // fans channel messages out to *other* connections via
+      // ApiGatewayManagementApi.postToConnection — including wss clients
+      // on the API Gateway transport. Without the stage grant on the NLB
+      // handler's own execution role, every such cross-transport delivery
+      // fails with 403.
+      const { template } = makeTcpTemplate();
+      const manages = nlbRoleStatements(template).filter(managesConnections);
+      expect(
+        manages.length,
+        'NLB handler role must be granted execute-api:ManageConnections',
+      ).toBeGreaterThan(0);
+    });
+
+    it('scopes the NLB handler ManageConnections grant to this stack API stage connections', () => {
+      // Least privilege: the grant must target THIS stack's WebSocket API
+      // stage connections resource (…/apis/<api>/prod/*/@connections/*),
+      // never a wildcard API or account-wide resource.
+      const { template } = makeTcpTemplate();
+      const apiIds = Object.keys(template.findResources('AWS::ApiGatewayV2::Api')).filter((id) =>
+        id.startsWith('IrcWsApi'),
+      );
+      expect(apiIds).toHaveLength(1);
+      const manages = nlbRoleStatements(template).filter(managesConnections);
+      const resourceJson = JSON.stringify(manages.map((s) => s.Resource));
+      expect(resourceJson).toContain('@connections');
+      expect(resourceJson).toContain('/prod/');
+      expect(resourceJson).toContain(apiIds[0] ?? '');
+    });
+
     it('still creates the wss WebSocket API (both transports coexist)', () => {
       const { template } = makeTcpTemplate();
       template.hasResourceProperties('AWS::ApiGatewayV2::Api', {
@@ -947,3 +1349,210 @@ describe('IrcAwsStack — TCP+TLS NLB adapter', () => {
     });
   });
 });
+
+describe('IrcAwsStack — web client hosting (StaticSite)', () => {
+  /** Makes a template WITH the webSite prop (enables the StaticSite path). */
+  function makeWebTemplate(webSite: StaticSiteProps = {}): {
+    app: App;
+    stack: Stack;
+    template: Template;
+  } {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', { webSite });
+    const template = Template.fromStack(stack);
+    return { app, stack, template };
+  }
+
+  describe('when webSite is omitted (default)', () => {
+    it('creates no S3 origin bucket for the web client', () => {
+      const { template } = makeTemplate();
+      template.resourceCountIs('AWS::S3::Bucket', 0);
+    });
+
+    it('creates no CloudFront distribution', () => {
+      const { template } = makeTemplate();
+      template.resourceCountIs('AWS::CloudFront::Distribution', 0);
+    });
+
+    it('creates no Origin Access Control', () => {
+      const { template } = makeTemplate();
+      template.resourceCountIs('AWS::CloudFront::OriginAccessControl', 0);
+    });
+  });
+
+  describe('when webSite is provided', () => {
+    it('creates an S3 origin bucket', () => {
+      const { template } = makeWebTemplate();
+      template.resourceCountIs('AWS::S3::Bucket', 1);
+    });
+
+    it('creates a CloudFront distribution with an S3 origin + OAC', () => {
+      const { template } = makeWebTemplate();
+      template.resourceCountIs('AWS::CloudFront::Distribution', 1);
+      template.resourceCountIs('AWS::CloudFront::OriginAccessControl', 1);
+    });
+
+    it('still creates the wss WebSocket API (both paths coexist)', () => {
+      const { template } = makeWebTemplate();
+      template.hasResourceProperties('AWS::ApiGatewayV2::Api', {
+        ProtocolType: 'WEBSOCKET',
+      });
+    });
+
+    it('emits a WebsiteURL output with a stable logical id naming the distribution domain', () => {
+      const { template } = makeWebTemplate();
+      const outputs = (template.toJSON().Outputs ?? {}) as Record<string, { Value?: unknown }>;
+      expect(outputs.WebsiteURL, 'expected a WebsiteURL output with a stable key').toBeDefined();
+      const distIds = Object.keys(template.findResources('AWS::CloudFront::Distribution'));
+      expect(distIds).toHaveLength(1);
+      const getAtt = (outputs.WebsiteURL?.Value as { 'Fn::GetAtt'?: unknown[] })?.['Fn::GetAtt'];
+      expect(getAtt, 'expected WebsiteURL.Value to Fn::GetAtt the distribution DomainName').toEqual(
+        [distIds[0], 'DomainName'],
+      );
+    });
+
+    // The AWS web deploy pipeline (`scripts/deploy-web-aws.mjs`) reads these
+    // outputs to drive `s3 sync <bucket>` and `cloudfront create-invalidation
+    // --distribution-id <id>`. They MUST be exposed at the parent-stack level
+    // with stable logical IDs (no CDK hashing, since the CfnOutput constructs
+    // live at the stack root alongside `ConnectUrl` / `ManagementUrl`) — the
+    // script queries them by exact key via `describe-stacks --query`.
+    it('emits a WebsiteBucketName output Ref-ing the S3 origin bucket', () => {
+      const { template } = makeWebTemplate();
+      const outputs = (template.toJSON().Outputs ?? {}) as Record<string, { Value?: unknown }>;
+      const bucketIds = Object.keys(template.findResources('AWS::S3::Bucket'));
+      expect(bucketIds).toHaveLength(1);
+      expect(outputs.WebsiteBucketName, 'expected a WebsiteBucketName output').toBeDefined();
+      const ref = (outputs.WebsiteBucketName?.Value as { Ref?: unknown })?.Ref;
+      expect(ref, 'expected WebsiteBucketName.Value to be a { Ref: <bucket-logical-id> }').toBe(
+        bucketIds[0],
+      );
+    });
+
+    it('emits a WebsiteDistributionId output Ref-ing the CloudFront distribution', () => {
+      const { template } = makeWebTemplate();
+      const outputs = (template.toJSON().Outputs ?? {}) as Record<string, { Value?: unknown }>;
+      const distIds = Object.keys(template.findResources('AWS::CloudFront::Distribution'));
+      expect(distIds).toHaveLength(1);
+      expect(
+        outputs.WebsiteDistributionId,
+        'expected a WebsiteDistributionId output',
+      ).toBeDefined();
+      const ref = (outputs.WebsiteDistributionId?.Value as { Ref?: unknown })?.Ref;
+      expect(ref, 'expected WebsiteDistributionId.Value to be a { Ref: <dist-logical-id> }').toBe(
+        distIds[0],
+      );
+    });
+  });
+});
+
+describe('IrcAwsStack — API Gateway stage throttling', () => {
+  it('exposes ApiThrottlingRateLimit as a configurable Number parameter (default 100)', () => {
+    const { template } = makeTemplate();
+    const p = parameters(template).ApiThrottlingRateLimit;
+    expect(p).toBeDefined();
+    expect(p?.Type).toBe('Number');
+    // CfnParameter renders a numeric default as a JSON number.
+    expect(Number(p?.Default)).toBe(100);
+    expect(typeof p?.Description).toBe('string');
+    expect(p?.Description?.length).toBeGreaterThan(0);
+  });
+
+  it('exposes ApiThrottlingBurstLimit as a configurable Number parameter (default 200)', () => {
+    const { template } = makeTemplate();
+    const p = parameters(template).ApiThrottlingBurstLimit;
+    expect(p).toBeDefined();
+    expect(p?.Type).toBe('Number');
+    expect(Number(p?.Default)).toBe(200);
+    expect(typeof p?.Description).toBe('string');
+  });
+
+  it('wires the stage default-route throttling to the parameters (Ref)', () => {
+    // Stage-level throttling is the global backstop behind the per-IP
+    // admission gates: it bounds aggregate request rate into the API
+    // (connect floods included) before a Lambda invocation is billed.
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::Stage', {
+      DefaultRouteSettings: {
+        ThrottlingRateLimit: { Ref: 'ApiThrottlingRateLimit' },
+        ThrottlingBurstLimit: { Ref: 'ApiThrottlingBurstLimit' },
+      },
+    });
+  });
+});
+
+describe('IrcAwsStack — Connections sourceIp GSI', () => {
+  it('adds a sourceIp+connectedSince GSI to the Connections table', () => {
+    // The per-IP admission gates ($connect simultaneous cap + rate
+    // window, NLB new-flow rate) consult this index; without it the
+    // handler would need a full-table Scan per connect.
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: 'Connections',
+      GlobalSecondaryIndexes: [
+        {
+          IndexName: 'sourceIp-connectedSince',
+          KeySchema: [
+            { AttributeName: 'sourceIp', KeyType: 'HASH' },
+            { AttributeName: 'connectedSince', KeyType: 'RANGE' },
+          ],
+        },
+      ],
+    });
+  });
+});
+
+describe('IrcAwsStack — WAF rate-based rule on $connect', () => {
+  /** Synths a stack with the optional edge rate limit configured. */
+  function makeWafTemplate(limit: number): Template {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', { wafConnectRateLimit: limit });
+    return Template.fromStack(stack);
+  }
+
+  it('emits no WebACL by default (the knob is opt-in)', () => {
+    const { template } = makeTemplate();
+    template.resourceCountIs('AWS::WAFv2::WebACL', 0);
+    template.resourceCountIs('AWS::WAFv2::WebACLAssociation', 0);
+  });
+
+  it('emits a REGIONAL WebACL with a per-IP rate-based rule when the knob is set', () => {
+    // WAF on a WebSocket API only inspects the initial HTTP upgrade —
+    // the `$connect` route — so a plain rate-based statement is
+    // effectively scoped to connection establishment.
+    const template = makeWafTemplate(2000);
+    template.resourceCountIs('AWS::WAFv2::WebACL', 1);
+    template.hasResourceProperties('AWS::WAFv2::WebACL', {
+      Scope: 'REGIONAL',
+      DefaultAction: { Allow: {} },
+      Rules: [
+        {
+          Name: 'ConnectRateLimit',
+          Priority: 0,
+          Action: { Block: {} },
+          Statement: {
+            RateBasedStatement: { Limit: 2000, AggregateKeyType: 'IP' },
+          },
+        },
+      ],
+    });
+  });
+
+  it('associates the WebACL with the WebSocket stage', () => {
+    const template = makeWafTemplate(2000);
+    template.resourceCountIs('AWS::WAFv2::WebACLAssociation', 1);
+    const assoc = template.findResources('AWS::WAFv2::WebACLAssociation') as Record<
+      string,
+      { Properties?: { ResourceArn?: unknown; WebACLArn?: unknown } }
+    >;
+    const entry = Object.values(assoc)[0];
+    expect(entry?.Properties?.WebACLArn).toBeDefined();
+    // ResourceArn must be the API Gateway stage ARN (Fn::Join over the
+    // partition/region refs + the WebSocket Api Ref + the stage name),
+    // not a dangling literal.
+    const arn = JSON.stringify(entry?.Properties?.ResourceArn);
+    expect(arn).toContain('apigateway');
+    expect(arn).toContain('/stages/prod');
+    expect(arn).toContain('IrcWsApi');
+  });
+});