serverless-ircd 0.9.0 → 0.11.0

package/apps/aws-stack/cdk.json

@@ -1,8 +1,5 @@
 {
   "app": "tsx bin/aws.ts",
-  "context": {
-    "environmentName": "staging"
-  },
   "watch": {
     "include": ["src/**", "bin/**"],
     "exclude": ["tests/**", "dist/**", "node_modules/**"]

package/apps/aws-stack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-stack",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "private": true,
   "description": "AWS CDK v2 stack: API Gateway v2 WebSocket API, Lambda, DynamoDB tables, least-privilege IAM",
   "license": "BSD-3-Clause",
@@ -14,9 +14,8 @@
     "clean": "rimraf dist coverage .tsbuildinfo .turbo cdk.out",
     "cdk": "cdk",
     "cdk:synth": "cdk synth",
-    "deploy:staging": "cdk deploy --all --require-approval never",
-    "deploy:prod": "cdk deploy --all --require-approval never",
-    "smoke:staging": "node scripts/smoke.mjs"
+    "deploy": "cdk deploy --all --require-approval never",
+    "smoke": "node scripts/smoke.mjs"
   },
   "devDependencies": {
     "aws-cdk": "^2.262.0",

package/apps/aws-stack/src/aws-stack.ts

@@ -2,7 +2,7 @@
  * `apps/aws-stack` CDK stack — the AWS substrate for ServerlessIRCd (PLAN §6.2).
  *
  *   • 5 DynamoDB tables sourced from `@serverless-ircd/aws-adapter/cdk-table-defs`
- *     (Connections, ChannelMeta, ChannelMembers, Nicks, Accounts).
+ *     (Connections, ChannelMeta, ChannelMembers, Nicks, Services).
  *   • ONE Node 24 `NodejsFunction` bundling the AWS Lambda handler
  *     (`$connect` / `$disconnect` / `$default` dispatched on
  *     `event.requestContext.routeKey`).
@@ -34,7 +34,7 @@ import {
 } from 'aws-cdk-lib/aws-apigatewayv2';
 import { WebSocketLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
 import { Certificate } from 'aws-cdk-lib/aws-certificatemanager';
-import { Table } from 'aws-cdk-lib/aws-dynamodb';
+import { Table, type TableProps } from 'aws-cdk-lib/aws-dynamodb';
 import { Vpc } from 'aws-cdk-lib/aws-ec2';
 import {
   NetworkListener,
@@ -50,7 +50,9 @@ import { PolicyStatement, Role, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
 import { Code, Function as Lambda, Runtime } from 'aws-cdk-lib/aws-lambda';
 import { NodejsFunction, type NodejsFunctionProps } from 'aws-cdk-lib/aws-lambda-nodejs';
 import { LogGroup, RetentionDays } from 'aws-cdk-lib/aws-logs';
+import { CfnWebACL, CfnWebACLAssociation } from 'aws-cdk-lib/aws-wafv2';
 import type { Construct } from 'constructs';
+import { StaticSite, type StaticSiteProps } from './static-site.js';
 
 /** Stage name served by the auto-deploying WebSocket stage. */
 const STAGE_NAME = 'prod';
@@ -60,7 +62,14 @@ const IRC_TLS_PORT = 6697;
 
 /** Fixed rate for the gone-connection sweeper (matches the architecture doc). */
 const SWEEPER_SCHEDULE_RATE = Duration.minutes(5);
-
+/**
+ * Logical id of the one ephemeral DynamoDB table. `Connections` holds
+ * per-connection rows (TTL-reaped, sweeper-cleaned) and is the ONLY table
+ * kept on `RemovalPolicy.DESTROY` with no PITR and no deletion protection;
+ * every other table is state-bearing and protected (see the table-creation
+ * block below).
+ */
+const EPHEMERAL_TABLE_LOGICAL_ID = 'Connections';
 /**
  * Fixed rate for the idle / PING checker. One minute is the finest
  * granularity EventBridge `rate(...)` expressions support, which
@@ -68,13 +77,6 @@ const SWEEPER_SCHEDULE_RATE = Duration.minutes(5);
  */
 const PING_CHECKER_SCHEDULE_RATE = Duration.minutes(1);
 
-/**
- * Environment assumed when {@link IrcStackProps.environmentName} is
- * omitted. Keeps the existing deploy pipeline green without requiring
- * callers to pass the flag.
- */
-const DEFAULT_ENVIRONMENT_NAME = 'staging';
-
 /**
  * Fallback server identity, used when the corresponding prop is omitted.
  * Deliberately not `irc.example.com` (the retired placeholder) so a
@@ -109,21 +111,10 @@ const TEST_NO_BUNDLE_FLAG = 'IRC_AWS_STACK_TEST_NO_BUNDLE';
 
 /**
  * Construct props for {@link IrcAwsStack}. Acts as the single
- * configuration bag extended by deploy-time knobs (environment name,
- * server identity, …) so the prop surface grows in one place.
+ * configuration bag extended by deploy-time knobs (server identity, …)
+ * so the prop surface grows in one place.
  */
 export interface IrcStackProps extends StackProps {
-  /**
-   * Logical deployment environment (e.g. `staging`, `production`).
-   *
-   * Prefixes every physical DynamoDB table name
-   * (`<Env><LogicalId>` — first letter capitalised, e.g.
-   * `StagingConnections`) and is intended to be folded into the
-   * CloudFormation stack id by the caller
-   * (`IrcAwsStack-<environmentName>`). Defaults to `staging`.
-   */
-  readonly environmentName?: string;
-
   /**
    * Server name advertised to clients (`SERVER_NAME` / the `001`
    * welcome source). Falls back to `irc.localhost` when omitted; production
@@ -158,13 +149,148 @@ export interface IrcStackProps extends StackProps {
    * (WebSocket) transport is deployed.
    */
   readonly tcpTlsDomainName?: string;
+
+  /**
+   * Web client hosting substrate (S3 + CloudFront + OAC).
+   *
+   * When provided, the stack provisions a {@link StaticSite} that serves
+   * the shared `apps/web/dist` build artifact over CloudFront. The S3
+   * origin bucket is private and grants the distribution via Origin
+   * Access Control (never public-read); SPA client-side routing under
+   * `/app/*` is handled by a CloudFront custom error response mapping
+   * 403/404 → `200 /app/index.html`. Pure infrastructure — the per-env
+   * config bake and the s3-sync deploy pipeline are separate. Pass the
+   * custom-domain fields for prod; omit them for the default
+   * `*.cloudfront.net` URL (staging). When omitted entirely, no web
+   * hosting resources are provisioned.
+   */
+  readonly webSite?: StaticSiteProps;
+
+  /**
+   * Comma-separated allowlist of web origins permitted to open
+   * WebSocket upgrades (CSWSH defence — API Gateway WebSocket has no
+   * built-in Origin check). Mirrors the CF Worker's `WEB_ORIGINS` env.
+   *
+   * When provided (non-empty), the value is injected as the
+   * `WEB_ORIGINS` Lambda env var on the wss `$connect` handler. The
+   * `$connect` Lambda then denies any browser-sent `Origin` not in
+   * the list with `403`, so API Gateway closes the upgrade. Unset /
+   * empty (the default) disables the check — existing deployments
+   * without a web frontend are unchanged on upgrade. Non-browser
+   * clients (curl, WeeChat, the `tcp-ws-forwarder`, NLB TCP+TLS)
+   * never send `Origin` and pass through regardless.
+   *
+   * Example: `'https://app.example.com, https://staging.app.example.com'`
+   */
+  readonly webOrigins?: string;
+
+  /**
+   * Escape hatch that re-enables API Gateway full-frame body tracing
+   * (`DataTraceEnabled = true`) on the WebSocket stage. Defaults to
+   * `false` (safe: no frame bodies are logged).
+   *
+   * ⚠️ Setting this to `true` alone REFUSES synthesis — it must be
+   * accompanied by {@link iUnderstandThisLeaksCredentials} = `true`.
+   * This double opt-in is deliberate: since the staging/prod split was
+   * collapsed (every synth is effectively a prod synth; there is no
+   * `environmentName` context), there is no longer a "non-prod" branch
+   * to quietly enable tracing on. The only safe default is OFF, and the
+   * only way back on is an explicit, two-step acknowledgement.
+   *
+   * For a WebSocket IRC endpoint, body tracing writes the FULL payload
+   * of every frame — `PASS <password>`, `AUTHENTICATE <base64-SASL-PLAIN>`,
+   * `JOIN #chan <channel-key>`, and every `PRIVMSG`/`NOTICE` — to the
+   * APIGW execution-log CloudWatch group. Anyone with `logs:GetLogEvents`
+   * (operators, SREs, Logpush destinations, compromised CI creds)
+   * recovers IRC credentials verbatim. Use ONLY in a throwaway sandbox
+   * account for live debugging, and tear it down immediately after.
+   *
+   * Set via CDK context: `-c allowDataTrace=true`.
+   */
+  readonly allowDataTrace?: boolean;
+
+  /**
+   * Mandatory confirmation that accompanies {@link allowDataTrace} = `true`.
+   * Has NO effect on its own; it only unlocks the `allowDataTrace` escape
+   * hatch. Defaults to `false`. The awkward name is intentional: it cannot
+   * be set by accident, and a synth error names this prop when it is
+   * missing so the operator is forced to read the credential-leak warning.
+   *
+   * Set via CDK context: `-c iUnderstandThisLeaksCredentials=true`.
+   */
+  readonly iUnderstandThisLeaksCredentials?: boolean;
+
+  /**
+   * Escape hatch that allows `cdk destroy` to tear down the state-bearing
+   * DynamoDB tables (Nicks, Services, ChannelMeta, ChannelMembers).
+   *
+   * Defaults to `false` (safe): state tables are `RemovalPolicy.RETAIN`'d
+   * and carry `deletionProtection: true`, so a mistaken `cdk destroy`, a
+   * stack-name collision, or a stray `aws dynamodb delete-table` from a
+   * compromised credential CANNOT wipe user accounts. The Connections
+   * table is always DESTROY regardless (its rows are ephemeral per-
+   * connection records, TTL-reaped and sweeper-cleaned).
+   *
+   * Set to `true` ONLY for a deliberate teardown (`-c allowTableDeletion=true`):
+   * every state table flips to `RemovalPolicy.DESTROY` with
+   * `deletionProtection: false` so CloudFormation can delete them. The data
+   * is irreversibly lost — there is no DynamoDB snapshot-on-delete (tables
+   * do not snapshot); `RETAIN` + PITR is the only protection, so flipping
+   * this off is a one-way operation. {@link enablePitr} is independent and
+   * stays on by default even in teardown mode.
+   */
+  readonly allowTableDeletion?: boolean;
+
+  /**
+   * Toggles point-in-time recovery (PITR) on the state-bearing DynamoDB
+   * tables (Nicks, Services, ChannelMeta, ChannelMembers). Defaults to
+   * `true` — PITR enables continuous, per-table point-in-time restore
+   * (within the last ~35 days) against accidental writes or deletes that
+   * RETAIN + deletion protection do not cover (e.g. a buggy deploy that
+   * overwrites rows, or an `UpdateItem` with the wrong key).
+   *
+   * The Connections table NEVER carries PITR regardless of this flag: its
+   * rows are ephemeral and the restore cost is unjustified.
+   *
+   * Set `-c enablePitr=false` to disable on all tables. PITR is billed
+   * continuously at ~$0.20/GB-month per table (see docs/AWS-Deployment.md);
+   * RETAIN and deletionProtection are free.
+   */
+  readonly enablePitr?: boolean;
+
+  /**
+   * Optional WAFv2 per-IP edge rate limit for the WebSocket API's
+   * `$connect` route (requests per 5-minute window per client IP).
+   *
+   * When set, the stack emits a `AWS::WAFv2::WebACL` (REGIONAL scope,
+   * default action Allow) whose single rate-based rule BLOCKS an IP once
+   * it exceeds the limit, associated with the WebSocket stage. WAF on a
+   * WebSocket API only inspects the initial HTTP upgrade — i.e. the
+   * `$connect` route; established-connection frames ride the upgrade and
+   * are never re-inspected — so the rule is effectively scoped to
+   * connection establishment without any route matching.
+   *
+   * This is the EDGE tier of the three-layer connect throttling (WAF at
+   * the edge → APIGW stage throttling → the per-IP admission gates in
+   * the `$connect` handler); it blocks a flood before a Lambda is
+   * invoked at all. Unset (the default) provisions no WAF resources.
+   *
+   * Set via CDK context: `-c wafConnectRateLimit=2000`.
+   */
+  readonly wafConnectRateLimit?: number;
 }
 
 export class IrcAwsStack extends Stack {
   constructor(scope: Construct, id: string, props: IrcStackProps = {}) {
     super(scope, id, props);
 
-    const environmentName = props.environmentName ?? DEFAULT_ENVIRONMENT_NAME;
+    // Fail-fast on the credential-leak escape hatch BEFORE any resource is
+    // constructed: if `allowDataTrace` was requested without the explicit
+    // `iUnderstandThisLeaksCredentials` confirmation, refuse synthesis here so
+    // the operator sees the credential-leak error immediately (and so the
+    // throw is not masked by downstream asset bundling). The resolved value
+    // is threaded into `defaultRouteSettings.dataTraceEnabled` below.
+    const dataTraceEnabled = resolveDataTraceEnabled(props);
 
     // Server identity is exposed as CloudFormation Parameters so it can be
     // overridden at deploy time (`cdk deploy --parameters ServerName=...`,
@@ -209,6 +335,34 @@ export class IrcAwsStack extends Stack {
       default: 'INFO',
       allowedValues: ['OFF', 'INFO', 'ERROR'],
     });
+
+    // Stage-level throttling: the global backstop BEHIND the per-IP
+    // admission gates (the `sourceIp` GSI counts in the `$connect`
+    // handler and the per-IP rate knobs). Caps the aggregate
+    // requests/second (and burst) APIGW forwards to ANY route — a
+    // connect flood from many IPs hits this even when each single IP
+    // stays under its per-IP budget. Defaults (100 rps / burst 200) are
+    // generous for an IRC deployment sized by `maxClients`; tune at
+    // deploy time via `--parameters ApiThrottlingRateLimit=...`. For
+    // per-IP rate limiting at the EDGE, deploy a WAFv2 rate-based rule
+    // scoped to the `$connect` route (operator-side; see
+    // docs/AWS-Deployment.md § throttling).
+    const apiThrottlingRateParam = new CfnParameter(this, 'ApiThrottlingRateLimit', {
+      type: 'Number',
+      description:
+        'API Gateway stage throttling: max requests per second across all routes ' +
+        '(global backstop behind the per-IP admission gates). ' +
+        'Override at deploy time via `--parameters ApiThrottlingRateLimit=...`.',
+      default: 100,
+    });
+    const apiThrottlingBurstParam = new CfnParameter(this, 'ApiThrottlingBurstLimit', {
+      type: 'Number',
+      description:
+        'API Gateway stage throttling: burst capacity (concurrent requests allowed momentarily) ' +
+        'paired with ApiThrottlingRateLimit. ' +
+        'Override at deploy time via `--parameters ApiThrottlingBurstLimit=...`.',
+      default: 200,
+    });
     const motd = (props.motdLines ?? DEFAULT_MOTD_LINES).join('\n');
 
     // EventBridge schedule expressions are surfaced as CloudFormation
@@ -238,17 +392,66 @@ export class IrcAwsStack extends Stack {
       default: Schedule.rate(PING_CHECKER_SCHEDULE_RATE).expressionString,
     });
 
-    // Prefix every physical table name with the environment so parallel
-    // envs (staging + production) cannot collide in one account+region.
-    // The first letter is capitalised to compose cleanly with the
-    // PascalCase logical ids (`staging` → `StagingConnections`).
+    // DynamoDB table names are the bare logical ids (`Connections`,
+    // `Nicks`, …). There is a single deploy target per platform (the
+    // staging/prod split was collapsed); staging vs production isolation
+    // is driven by which AWS account + region the deploy credentials
+    // target, not by table-name prefixing.
+    //
+    // State-bearing tables (every table EXCEPT `Connections`) are protected
+    // from accidental data loss by THREE independent mechanisms, each
+    // toggleable so a deliberate teardown can still proceed:
+    //   • `RemovalPolicy.RETAIN` — orphans the table (keeps its data) when
+    //     the stack is deleted, instead of CloudFormation deleting it.
+    //   • `deletionProtection: true` — DynamoDB refuses a `DeleteTable`
+    //     API call while this is on, blocking a stray
+    //     `aws dynamodb delete-table` even from an admin credential.
+    //   • `pointInTimeRecovery` — continuous, per-table restore (within
+    //     ~35 days) against accidental writes/deletes that RETAIN +
+    //     deletion protection cannot stop (e.g. a buggy `UpdateItem`).
+    //
+    // NOTE: SNAPSHOT semantics are deliberately NOT used. DynamoDB tables
+    // do NOT snapshot on stack delete (`RemovalPolicy.SNAPSHOT` is a no-op
+    // here and would lull an operator into a false sense of backup). The
+    // correct combination is RETAIN (orphan + keep) + PITR (continuous,
+    // in-place restore). `Connections` is the sole exception: its rows are
+    // ephemeral per-connection records (TTL-reaped, sweeper-cleaned), so it
+    // stays DESTROY with no PITR and no deletion protection at all times.
+    //
+    // Cost: RETAIN and deletionProtection are free; PITR is billed
+    // continuously at ~$0.20/GB-month per table (see docs/AWS-Deployment.md).
+    const allowTableDeletion = props.allowTableDeletion === true;
+    const enablePitr = props.enablePitr !== false;
     const tables = Object.fromEntries(
-      Object.entries(TABLE_DEFS).map(([logicalId, tableProps]) => {
+      Object.entries(TABLE_DEFS).map(([logicalId, tableDef]) => {
+        const isStateTable = logicalId !== EPHEMERAL_TABLE_LOGICAL_ID;
+        // `exactOptionalPropertyTypes` forbids passing `undefined` for
+        // optional props, so the protection knobs are spread in
+        // conditionally: Connections omits all three (always DESTROY,
+        // no PITR, no deletion protection); state tables set all three
+        // based on the flags.
+        const protectionProps: Partial<
+          Pick<TableProps, 'deletionProtection' | 'pointInTimeRecovery'>
+        > = isStateTable
+          ? {
+              deletionProtection: !allowTableDeletion,
+              pointInTimeRecovery: enablePitr,
+            }
+          : {};
+        // The GSI side-channel rides alongside the construct props in
+        // TABLE_DEFS; pop it before constructing (current CDK declares
+        // indexes via addGlobalSecondaryIndex, not TableProps).
+        const { globalSecondaryIndexes, ...tableProps } = tableDef;
         const table = new Table(this, logicalId, {
           ...tableProps,
-          tableName: prefixedTableName(environmentName, logicalId),
-          removalPolicy: RemovalPolicy.DESTROY,
+          tableName: logicalId,
+          removalPolicy:
+            isStateTable && !allowTableDeletion ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,
+          ...protectionProps,
         });
+        for (const gsi of globalSecondaryIndexes ?? []) {
+          table.addGlobalSecondaryIndex(gsi);
+        }
         return [logicalId, table];
       }),
     );
@@ -352,19 +555,25 @@ export class IrcAwsStack extends Stack {
     // APIGW validates this role when it is set as the account CloudWatch
     // role, and rejects one scoped to a single log-group ARN: execution
     // logs land in APIGW's OWN log groups (AWS/ApiGateway...), separate
-    // from this stack's access-log group. Grant the logs write actions
-    // across all log groups. Defined inline (not via the
-    // AmazonAPIGatewayPushToCloudWatchLogs managed policy) because that
-    // managed policy is not available in every partition.
+    // from this stack's access-log group. Grant ONLY the three write
+    // actions APIGW needs, across all log groups (the wildcard is an
+    // inherent APIGW constraint — those group ARNs are not predictable at
+    // synth time). The legacy policy also carried Describe* actions; they
+    // were dropped so a compromised role cannot enumerate (or, given the
+    // read actions AWS's own managed policy for this purpose includes,
+    // exfiltrate) arbitrary log groups in the account.
+    //
+    // Managed-policy decision: the AWS-managed
+    // AmazonAPIGatewayPushToCloudWatchLogs policy was considered and
+    // REJECTED. Its fixed grant set is broader than needed — it grants
+    // DescribeLogGroups/DescribeLogStreams (deliberately dropped here)
+    // plus GetLogEvents/FilterLogEvents, all on '*' — and AWS can widen
+    // its contents without this stack being re-reviewed. It is also not
+    // available in every partition. The inline policy keeps the grant set
+    // exact and auditable at synth time.
     apiLoggingRole.addToPolicy(
       new PolicyStatement({
-        actions: [
-          'logs:CreateLogGroup',
-          'logs:CreateLogStream',
-          'logs:DescribeLogGroups',
-          'logs:DescribeLogStreams',
-          'logs:PutLogEvents',
-        ],
+        actions: ['logs:CreateLogGroup', 'logs:CreateLogStream', 'logs:PutLogEvents'],
         resources: ['*'],
       }),
     );
@@ -414,13 +623,23 @@ export class IrcAwsStack extends Stack {
         sourceIp: '$context.sourceIp',
       }),
     };
-    // Execution logging: the parameter drives LoggingLevel (OFF/INFO/ERROR);
-    // DataTraceEnabled logs full request/response bodies when a level is
-    // active. This is the layer that shows whether APIGW received and routed
-    // a client frame or dropped it pre-Lambda.
+    // Execution logging: the parameter drives LoggingLevel (OFF/INFO/ERROR).
+    // `DataTraceEnabled` is hard-locked to `false` here. For a WebSocket IRC
+    // endpoint, body tracing writes the FULL payload of every frame —
+    // `PASS <password>`, `AUTHENTICATE <base64-SASL-PLAIN>`,
+    // `JOIN #chan <channel-key>`, and every `PRIVMSG`/`NOTICE` — to the
+    // APIGW execution-log CloudWatch group (AWS/ApiGateway…). Anyone with
+    // `logs:GetLogEvents` recovers IRC credentials verbatim. The logging
+    // LEVEL (INFO request/response metadata without bodies) is enough to
+    // diagnose frame-routing drops; the only way to re-enable full-body
+    // tracing is the explicit, double-opt-in escape hatch asserted below.
     cfnStage.defaultRouteSettings = {
       loggingLevel: apiLoggingLevelParam.valueAsString,
-      dataTraceEnabled: true,
+      dataTraceEnabled,
+      // Stage throttling (see the parameter definitions above): global
+      // rate + burst backstop behind the per-IP admission gates.
+      throttlingRateLimit: apiThrottlingRateParam.valueAsNumber,
+      throttlingBurstLimit: apiThrottlingBurstParam.valueAsNumber,
     };
 
     stage.grantManagementApiAccess(handler);
@@ -428,18 +647,64 @@ export class IrcAwsStack extends Stack {
     handler.addEnvironment('MANAGEMENT_URL', stage.callbackUrl);
     pingChecker.addEnvironment('MANAGEMENT_URL', stage.callbackUrl);
 
+    // Optional WAFv2 rate-based rule on the WebSocket API's `$connect`
+    // (see the `wafConnectRateLimit` prop doc): WAF only inspects the
+    // initial HTTP upgrade on a WebSocket API, so the rate statement
+    // applies exactly where credential brute-force has to spend its
+    // budget — connection establishment — and never to established
+    // frames. Blocks happen at the edge, before a Lambda invocation is
+    // billed. Unset → no WAF resources at all (the default).
+    if (props.wafConnectRateLimit !== undefined) {
+      const webAcl = new CfnWebACL(this, 'ConnectRateWebAcl', {
+        scope: 'REGIONAL',
+        defaultAction: { allow: {} },
+        // CFN requires a VisibilityConfig on both the ACL and the rule;
+        // sampled requests + the CloudWatch metric keep operator
+        // visibility without full request logging.
+        visibilityConfig: {
+          cloudWatchMetricsEnabled: true,
+          metricName: 'IrcConnectWebAcl',
+          sampledRequestsEnabled: true,
+        },
+        rules: [
+          {
+            name: 'ConnectRateLimit',
+            priority: 0,
+            action: { block: {} },
+            visibilityConfig: {
+              cloudWatchMetricsEnabled: true,
+              metricName: 'IrcConnectRateLimit',
+              sampledRequestsEnabled: true,
+            },
+            statement: {
+              rateBasedStatement: {
+                limit: props.wafConnectRateLimit,
+                aggregateKeyType: 'IP',
+              },
+            },
+          },
+        ],
+      });
+      new CfnWebACLAssociation(this, 'ConnectRateWebAclAssociation', {
+        webAclArn: webAcl.attrArn,
+        // WAF associates with API Gateway stages via the v1-style stage
+        // ARN namespace (`/restapis/…`) — WebSocket APIs use the same
+        // format (there is no `WebSocketStage.stageArn` L2 helper).
+        resourceArn: `arn:${this.partition}:apigateway:${this.region}::/restapis/${webSocketApi.apiId}/stages/${stage.stageName}`,
+      });
+    }
+
     // Inject each table's physical name as an env var so every Lambda can
     // construct a `TablesConfig` at cold start via `buildDepsFromEnv`. The
-    // env-var value is the environment-prefixed physical name (computed
-    // through the same helper as the Table construct so they match
-    // exactly), NOT a CloudFormation Ref — the runtime needs the literal
-    // per-env table name to target the correct table.
+    // env-var value is the literal physical table name (the bare logical
+    // id, computed through the same mapping as the Table construct so they
+    // match exactly), NOT a CloudFormation Ref — the runtime needs the
+    // literal name to target the correct table.
     for (const logicalId of Object.keys(TABLE_DEFS)) {
       const envName = `${logicalId.toUpperCase()}_TABLE`;
-      const physicalName = prefixedTableName(environmentName, logicalId);
-      handler.addEnvironment(envName, physicalName);
-      sweeper.addEnvironment(envName, physicalName);
-      pingChecker.addEnvironment(envName, physicalName);
+      handler.addEnvironment(envName, logicalId);
+      sweeper.addEnvironment(envName, logicalId);
+      pingChecker.addEnvironment(envName, logicalId);
     }
 
     // Server identity is injected into the handler, ping checker, AND the
@@ -461,6 +726,16 @@ export class IrcAwsStack extends Stack {
     sweeper.addEnvironment('NETWORK_NAME', networkName);
     sweeper.addEnvironment('MOTD', motd);
 
+    // CSWSH defence — opt-in `WEB_ORIGINS` allowlist on the `$connect`
+    // handler. Only the wss handler runs `$connect`, so only it needs
+    // the env var (the sweeper, ping-checker, and NLB handler never see
+    // an `event.headers.Origin`). When the prop is unset/empty the env
+    // var is omitted entirely and the handler's defence is disabled —
+    // existing deployments without a web frontend are unchanged.
+    if (props.webOrigins !== undefined && props.webOrigins.length > 0) {
+      handler.addEnvironment('WEB_ORIGINS', props.webOrigins);
+    }
+
     // EventBridge schedule → sweeper Lambda. The schedule expression comes
     // from a CloudFormation Parameter (see above), so it can be overridden
     // at deploy time; the sweeper is self-throttling
@@ -526,12 +801,18 @@ export class IrcAwsStack extends Stack {
       // Inject the same table names, server identity, and management URL.
       for (const logicalId of Object.keys(TABLE_DEFS)) {
         const envName = `${logicalId.toUpperCase()}_TABLE`;
-        nlbHandler.addEnvironment(envName, prefixedTableName(environmentName, logicalId));
+        nlbHandler.addEnvironment(envName, logicalId);
       }
       nlbHandler.addEnvironment('SERVER_NAME', serverName);
       nlbHandler.addEnvironment('NETWORK_NAME', networkName);
       nlbHandler.addEnvironment('MOTD', motd);
       nlbHandler.addEnvironment('MANAGEMENT_URL', stage.callbackUrl);
+      // The NLB handler fans channel messages out to OTHER connections via
+      // the management API — including wss clients on the API Gateway
+      // transport — so it needs the same `execute-api:ManageConnections`
+      // grant as the wss handler and ping checker. Without it every
+      // cross-transport `postToConnection` fails with 403.
+      stage.grantManagementApiAccess(nlbHandler);
 
       const nlb = new NetworkLoadBalancer(this, 'IrcNlb', {
         vpc,
@@ -571,6 +852,39 @@ export class IrcAwsStack extends Stack {
       description: 'HTTPS management endpoint for ApiGatewayManagementApi.postToConnection.',
       value: stage.callbackUrl,
     });
+
+    // -------------------------------------------------------------------------
+    // Web client hosting substrate (S3 + CloudFront + OAC).
+    //
+    // Serves the shared `apps/web/dist` artifact (Kiwi SPA + landing page)
+    // exclusively over CloudFront. The S3 origin bucket is private; CloudFront
+    // reads it via Origin Access Control (the modern replacement for OAI).
+    // Only provisioned when `webSite` is supplied — staging defaults to the
+    // `*.cloudfront.net` URL, prod passes the custom-domain fields. Pure
+    // infrastructure; the per-env config bake and the s3-sync deploy pipeline
+    // are separate.
+    // -------------------------------------------------------------------------
+    if (props.webSite !== undefined) {
+      const site = new StaticSite(this, 'StaticSite', props.webSite);
+      // Expose the deploy-pipeline-relevant resource IDs at the PARENT-stack
+      // level (stable logical IDs — no CDK hashing, which only kicks in for
+      // outputs nested under child constructs). `scripts/deploy-web-aws.mjs`
+      // reads these via `aws cloudformation describe-stacks --query` to drive
+      // `s3 sync apps/web/dist s3://<bucket> --delete` and
+      // `cloudfront create-invalidation --distribution-id <id> --paths /*`.
+      // `ConnectUrl` (above) supplies the wss URL that the same script bakes
+      // into the SPA's config.json via `build.mjs --api-url`.
+      new CfnOutput(this, 'WebsiteBucketName', {
+        description:
+          'S3 origin bucket holding the web client build artifact (apps/web/dist). The deploy pipeline runs `aws s3 sync apps/web/dist s3://<this-bucket> --delete`.',
+        value: site.bucket.bucketName,
+      });
+      new CfnOutput(this, 'WebsiteDistributionId', {
+        description:
+          'CloudFront distribution ID serving the web client. The deploy pipeline runs `aws cloudfront create-invalidation --distribution-id <this-id> --paths /*` after each s3 sync.',
+        value: site.distribution.distributionId,
+      });
+    }
   }
 }
 
@@ -582,6 +896,34 @@ function handlerEntry(): string {
   return resolve(HERE, '..', '..', '..', 'packages', 'aws-adapter', 'src', 'handlers', 'index.ts');
 }
 
+/**
+ * Resolves the API Gateway `DataTraceEnabled` flag for the stage from the
+ * construct props. Safe-by-default: returns `false` unless the explicit,
+ * documented escape hatch is invoked. See {@link IrcStackProps.allowDataTrace}.
+ *
+ * Post-T170 (staging/prod collapse) every synth is effectively a prod synth,
+ * so there is no "non-prod" branch to quietly enable tracing on. The guard
+ * therefore refuses synthesis the moment `allowDataTrace` is requested
+ * without the explicit `iUnderstandThisLeaksCredentials` acknowledgement —
+ * forcing the operator to read the credential-leak warning.
+ */
+function resolveDataTraceEnabled(props: IrcStackProps): boolean {
+  if (props.allowDataTrace === true) {
+    if (props.iUnderstandThisLeaksCredentials === true) {
+      return true;
+    }
+    throw new Error(
+      'Refusing to enable API Gateway DataTraceEnabled: for a WebSocket IRC ' +
+        'endpoint this logs the FULL body of every frame (PASS <password>, ' +
+        'AUTHENTICATE <base64-SASL-PLAIN>, JOIN #chan <channel-key>, every ' +
+        'PRIVMSG/NOTICE) to the APIGW CloudWatch log group, leaking IRC ' +
+        'credentials to anyone with logs:GetLogEvents. To override in a ' +
+        'throwaway sandbox ONLY, also pass iUnderstandThisLeaksCredentials=true.',
+    );
+  }
+  return false;
+}
+
 /**
  * Internal Lambda-construct props: `NodejsFunctionProps` narrowed so the
  * runtime and handler are required. Every call site in the stack already
@@ -623,14 +965,3 @@ function makeLambda(scope: Construct, id: string, props: StrictLambdaProps): Lam
   }
   return new NodejsFunction(scope, id, props);
 }
-
-/**
- * Builds the physical DynamoDB table name for a logical id under the
- * given environment. Capitalises the environment's first letter so it
- * composes cleanly with PascalCase logical ids
- * (`staging` + `Connections` → `StagingConnections`).
- */
-function prefixedTableName(environmentName: string, logicalId: string): string {
-  const cap = environmentName.charAt(0).toUpperCase() + environmentName.slice(1);
-  return `${cap}${logicalId}`;
-}