serverless-ircd 0.10.0 → 0.11.0

package/README.md

@@ -54,7 +54,28 @@ One TypeScript codebase. Two serverless substrates.
 > (`DataTraceEnabled`) is **off by default and hard-locked**, so IRC
 > frames (`PASS`, `AUTHENTICATE <SASL-PLAIN>`, channel keys,
 > `PRIVMSG`/`NOTICE`) are never written to CloudWatch; the only way
-> back on is an explicit two-flag sandbox escape hatch.
+> back on is an explicit two-flag sandbox escape hatch. The CF deploy
+> workflow refuses placeholder hostnames (`irc.example.com` /
+> `irc.your-domain.invalid`), and a CI **env-var drift guard** keeps
+> the `consumed-env-vars` block of `apps/cf-worker/wrangler.toml`
+> exactly in sync with the config loader.
+>
+> **Abuse controls & hardening.** Layered admission control on both
+> platforms: a global `MAX_CLIENTS` cap (Cloudflare reserves a
+> `CounterDO` slot per upgrade; AWS keeps an atomic connection counter
+> — over-cap connects get `429`), per-IP simultaneous-connection caps
+> and sliding-window connect-rate limits (a `RateLimitDO` at the CF
+> edge; a source-IP GSI count + APIGW stage throttling + an opt-in
+> WAFv2 per-IP rate rule on AWS), and a per-connection inbound
+> frame-rate window at every adapter boundary. Credential handling is
+> hardened end-to-end: scrypt-hashed oper credentials, constant-time
+> server-password comparison, timing-equalized nick verification (no
+> account enumeration), SASL/OPER/IDENTIFY brute-force lockouts, and
+> credential redaction from parse-error logs. SASL `EXTERNAL` is
+> **operator opt-in** (`EXTERNAL_ENABLED`, default off), gated on a
+> bound mTLS identity source **and** a TLS transport, and binds
+> accounts to the client cert's **DER SHA-256 fingerprint**
+> (`fp:<hex>`, with a canonical-DN fallback).
 >
 > **Integrated IRC services.** NickServ, ChanServ, HostServ,
 > OperServ, and MemoServ run inside the daemon (no separate services
@@ -121,12 +142,18 @@ Hexagonal / ports-and-adapters. The core implements the IRC protocol; adapters h
 **Two transports, one core.** Both adapters accept WebSocket text frames
 (the serverless default) **and** a raw `irc+tls :6697` (TLS-over-TCP)
 surface for stock IRC clients. The TCP+TLS edge is platform-specific —
-Cloudflare **Spectrum** terminates TLS and forwards plaintext TCP to a
-stateful **Container** origin (`apps/cf-tcp-container`); AWS terminates
-TLS at a **Network Load Balancer** and invokes a **Lambda streaming**
-function. Both feed the same `ConnectionActor` through a `Transport`
-seam (`WsTextFrameTransport` vs. `TcpByteStreamTransport`); the
-parser/reducer/dispatch pipeline is identical.
+Cloudflare **Spectrum** fronts a stateful **Container** origin
+(`apps/cf-tcp-container`) with `proxy_protocol = "v1"` and
+`tls_mode = "full"`: the container itself terminates TLS (pinned to
+1.2/1.3), requires and parses a PROXY v1 header on every flow to recover
+the real client IP, and runs as a non-root user. AWS terminates TLS at a
+**Network Load Balancer** — the streaming handler asserts the flow is
+TLS-secured (surfacing user mode `S`), rejects missing or malformed flow
+headers, and enforces the same per-IP connect-rate budget — and invokes a
+**Lambda streaming** function. Both feed the same `ConnectionActor`
+through a `Transport` seam (`WsTextFrameTransport` vs.
+`TcpByteStreamTransport`); the parser/reducer/dispatch pipeline is
+identical.
 
 ### Design: pure reducers + location-of-authority
 
@@ -177,9 +204,11 @@ ServerlessIRCd/
 ├── tools/
 │   ├── tcp-ws-forwarder/  local TCP↔ws/wss bridge for stock IRC clients
 │   ├── load-test/         synthetic WebSocket IRC client pool (10k conns, p50/p95/p99, drop rate)
-│   ├── ci-hardening/      coverage-gate + mutation-config validators
+│   ├── ci-hardening/      coverage-gate + mutation-config + env-var-drift validators
+│   ├── hash-oper-cred.ts  scrypt oper-credential generator (OPER_SALT + OPER_HASH)
 │   ├── seed-aws-accounts.ts  scrypt-hash SASL PLAIN accounts into DynamoDB
-│   └── seed-cf-accounts.ts   scrypt-hash SASL PLAIN accounts into Cloudflare D1
+│   ├── seed-cf-accounts.ts   scrypt-hash SASL PLAIN accounts into Cloudflare D1
+│   └── migrate-accounts-to-services.ts  one-shot AccountStore→ServicesStore credential backfill
 ├── scripts/
 │   └── deploy-web-aws.mjs stack-output-driven AWS web client deploy (describe → bake → s3 sync → invalidate)
 ├── pnpm-workspace.yaml    turbo.json   tsconfig.base.json
@@ -241,8 +270,8 @@ pnpm --filter web build   # builds the Kiwi SPA into apps/web/dist/webclient/ (/
 Coverage reports are written to `packages/*/coverage/`. CI (`.github/workflows/ci.yml`)
 runs lint, typecheck, the coverage gate, the parametrized contract suite, and a
 Stryker mutation spot-check on every push and pull request. Coverage thresholds
-enforce 100% on `irc-core` / `irc-server` / `in-memory-runtime` and ≥90% on every
-other package.
+enforce 100% on `irc-core` / `irc-server` / `in-memory-runtime` / `ci-hardening`
+and ≥90% on every other package.
 
 ---
 
@@ -522,6 +551,27 @@ Deploy the Worker (Worker + assets in one command):
 pnpm deploy:cf   # wrangler deploy
 ```
 
+#### Configuration vars & secrets (Cloudflare)
+
+Every env var the Worker consumes is enumerated — and
+**drift-guarded in CI** — in the `consumed-env-vars` block of
+`apps/cf-worker/wrangler.toml`, classified as a plaintext `[vars]`
+knob or a `[secret]`. Credential material must be set as Workers
+secrets, never `[vars]`:
+
+| Secret | Purpose |
+|--------|---------|
+| `SERVER_PASSWORD` | server-wide PASS gate (see [above](#server-password-server_password---server-password)) |
+| `OPER_PASSWORD` | legacy plaintext oper credential |
+| `OPER_SALT` + `OPER_HASH` | hashed oper credential — generate with `node --import tsx tools/hash-oper-cred.ts --user admin --stdin` |
+| `SASL_ACCOUNTS` | newline-delimited `user:password` SASL seed list (see `tools/seed-cf-accounts.ts`) |
+
+Set each with `wrangler secret put <NAME>`. Everything else
+(`SERVER_NAME`, `MAX_CLIENTS`, `MAX_CONNECTIONS_PER_IP`,
+`PER_IP_CONNECTION_RATE_*`, `MAX_FRAMES_PER_WINDOW`,
+`FRAME_WINDOW_SECONDS`, `EXTERNAL_ENABLED`, …) is a non-sensitive
+`[vars]` knob.
+
 ### Deploying on AWS
 
 The web client is **opt-in**: provision the `StaticSite` construct by
@@ -630,6 +680,73 @@ deployed stack exercises the spec path end-to-end.
 
 ---
 
+## Abuse controls & credential hardening
+
+Every transport edge enforces layered admission and rate limits, and
+every credential path verifies through hardened, timing-equalized
+comparisons. The knobs below are `[vars]` on the Cloudflare Worker and
+mirrored as Lambda env vars on AWS.
+
+### Connection admission & rate limiting
+
+| Layer                  | Knobs                                             | Enforcement |
+|------------------------|---------------------------------------------------|-------------|
+| Global cap             | `MAX_CLIENTS`                                     | CF reserves a `CounterDO` slot before each upgrade and answers `429` (`ERROR :Closing link: server full`) at the cap (slots released on close, TTL-reaped if a DO dies); AWS keeps an atomic connection counter in DynamoDB. |
+| Per-IP simultaneous    | `MAX_CONNECTIONS_PER_IP`                          | Admission gates on both platforms reject over-budget source IPs with `429`. |
+| Per-IP connect rate    | `PER_IP_CONNECTION_RATE_MAX` / `PER_IP_CONNECTION_RATE_WINDOW_MS` | CF: a `RateLimitDO` sliding window keyed on `CF-Connecting-IP`, checked at the worker edge (rejections never consume budget, so a blocked IP recovers after window decay). AWS: `$connect` counts in-window establishments via a `sourceIp+connectedSince` GSI, the NLB path applies the same budget to new flows, APIGW stage throttling backstops globally, and an opt-in WAFv2 per-IP rate rule (`-c wafConnectRateLimit=<n>`) sits at the edge. |
+| Per-connection frames  | `MAX_FRAMES_PER_WINDOW` / `FRAME_WINDOW_SECONDS`  | Inbound frame budget enforced at the adapter boundary before the actor / storage write. |
+| Line-buffer memory     | (fixed)                                           | TCP input buffers capped at 8 KiB at every transport edge (local CLI, container origin, NLB handler, forwarder). |
+
+### Protocol budgets
+
+All length limits are enforced in **UTF-8 bytes**, not UTF-16 code
+units: the 510-byte WS frame / 512-byte TCP line budgets, `TOPICLEN`
+enforced on character boundaries, `draft/multiline` batch byte budgets
+enforced incrementally as lines arrive, at most 15 tags and an
+8192-byte tag section per message, long NAMES rosters split across
+multiple `353` replies within the 510-byte budget, `CHATHISTORY`
+limits capped at a configurable ceiling (default 100), and
+`MAX_TARGETS_PER_COMMAND` capping comma-split targets. The parser
+rejects bare-`CR` smuggling and NUL/control characters in channel
+names, builds tag maps with a null prototype (blocking prototype
+pollution), and `OPER` requires a registered connection (`451
+ERR_NOTREGISTERED`).
+
+### Credentials & anti-abuse
+
+Oper credentials verify against scrypt hashes (`OPER_USER` +
+`OPER_SALT`/`OPER_HASH`, generated with `tools/hash-oper-cred.ts`);
+the server password compares in constant time; `verifyNick` runs a
+dummy scrypt verify on unknown nicks so response timings cannot
+enumerate accounts. Brute force is throttled at every auth surface: a
+per-connection SASL failure lockout, a per-IP `OPER` failure lockout,
+and a per-account NickServ `IDENTIFY` freeze. HostServ auto-approve
+honours a vhost denylist/allowlist, and ChanServ `DEOP`/`KICK` protect
+founders and enforce caller rank. Parse-error logs carry only
+token/length/reason — `PASS` / `AUTHENTICATE` payloads are redacted —
+and the Worker's log sampling defaults to 10%.
+
+### SASL EXTERNAL (mTLS)
+
+`EXTERNAL` is advertised and accepted only when **all** of the
+following hold: an mTLS identity source is bound for the connection
+(CF API Shield / AWS API Gateway client certs), the operator opt-in
+`EXTERNAL_ENABLED` is set (default **off**), and the transport is
+TLS-secured. Otherwise the `sasl` cap and `908 ERR_SASLMECHS` list
+`PLAIN` only — refusals do not count toward the SASL lockout.
+Accounts bind to the client cert's **DER SHA-256 fingerprint**
+(`fp:<hex>` entries — what Cloudflare surfaces from
+`request.cf.tlsClientAuth`; the preferred binding) or a **canonical
+subject DN** (the only identifier API Gateway exposes; DNs are
+canonicalised — types lower-cased, whitespace collapsed, RDN/AVA order
+sorted — so re-issued or differently-ordered certificates still match).
+Transports without any client-cert surface — the Spectrum container
+origin, and the NLB stream handler unless an mTLS provider is injected
+— pin the mechanism off and reject `AUTHENTICATE EXTERNAL` with a
+transport-specific `904`.
+
+---
+
 ## Testing strategy
 
 This project follows strict TDD (Red → Green → Refactor) — every reducer is
@@ -666,12 +783,17 @@ Active follow-ups:
   surfaces.
 - **Web client e2e** — Playwright headless-browser e2e exercising the
   vendored Kiwi IRC SPA against a deployed stack.
-- **Coverage hardening** — `aws-adapter` and `aws-stack` clear the 90%
-  gate; the CF packages run under istanbul. The remaining packages
-  (`cf-adapter`, `local-cli`, `load-test`, `cf-tcp-container`,
-  `tcp-ws-forwarder`, `irc-test-support`, `web`) sit above the gate
-  but below 100%; follow-ups drive each to full coverage. `irc-core`,
-  `irc-server`, and `in-memory-runtime` are at 100%.
+- **Coverage hardening** — `irc-core`, `irc-server`,
+  `in-memory-runtime`, `local-cli`, `cf-worker`, `aws-stack`,
+  `load-test`, `cf-tcp-container`, `tcp-ws-forwarder`,
+  `irc-test-support`, and `ci-hardening` sit at 100% line coverage;
+  `cf-adapter` (~99.7%) and `aws-adapter` (~98%) clear the 90% gate
+  with follow-ups driving each to full coverage.
+- **Protocol follow-ups** — `WHOX` (`WHO <mask> %<fields>` /
+  `354 RPL_WHOSPCRPL`), `LIST` search masks + `ELIST=MNTU` filters,
+  `cap-notify` capability-change push, services data lifecycle
+  (last-used tracking + expiry sweep), and a persisted oper audit
+  trail.
 - **Persistent ChanServ ban list** — ban masks currently live on
   `ChannelState.banMasks` and do not survive an empty-recreate of a
   channel. Extending `ServicesStore` with a persistent ban list is the
@@ -747,17 +869,28 @@ The `ServicesStore` is the **single credential home**: SASL PLAIN, SASL
 EXTERNAL (CertFP), NickServ `IDENTIFY`, and `PASS <nick>:<password>` all
 verify through the same scrypt-hashed `verifyNick` / `verifyCertFP`
 surface, so a registered nick is also a SASL login and vice versa.
+The credential env vars that seed and unlock these paths
+(`SASL_ACCOUNTS`, `OPER_*`, `SERVER_PASSWORD`) are Workers secrets on
+Cloudflare — the full consumed-var list lives in the drift-guarded
+`consumed-env-vars` block of `apps/cf-worker/wrangler.toml` (see
+[Configuration vars & secrets](#configuration-vars-secrets-cloudflare)).
 Backends: D1 on Cloudflare, DynamoDB on AWS, in-memory for the
 local CLI / tests (all write-behind; registrations survive redeploys).
 When no store is bound, services commands reply `501` and the rest of
 the daemon is unaffected. See `docs/Services.md` for the full
 reference.
-
 **IRCv3 extensions (negotiated via `CAP`):** `message-tags` (incl. the
 `TAGMSG` command), `server-time`, `account-tag`, `account-notify`
 (pushes `ACCOUNT` on SASL login/logout), `echo-message`, `batch`,
-`sasl` (`PLAIN` always; `EXTERNAL` via mTLS when a client-cert trust store
-is bound), `multi-prefix`, `away-notify`, `chghost`, `invite-notify`,
+`sasl` (`PLAIN` always; `EXTERNAL` only under the triple gate of
+operator opt-in (`EXTERNAL_ENABLED`, default off) + a bound edge-mTLS
+identity source + a TLS connection — accounts bind to the client
+cert's DER SHA-256 fingerprint or a canonical subject DN, refusals
+answer `908 ERR_SASLMECHS` listing `PLAIN` only, and the
+`cf-tcp-container` Spectrum origin rejects `AUTHENTICATE EXTERNAL`
+with a transport-specific `904`; see
+[Abuse controls & credential hardening](#abuse-controls--credential-hardening)),
+`multi-prefix`, `away-notify`, `chghost`, `invite-notify`,
 `extended-join`, `msgid` (`@+msgid=<id>` on every PRIVMSG/NOTICE/TAGMSG,
 shared between live and `draft/chathistory` replay), `standard-replies`
 (`FAIL`/`WARN`/`NOTE` replacements for a curated numeric subset),

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

@@ -69,6 +69,26 @@ const iUnderstandThisLeaksCredentials = app.node.tryGetContext('iUnderstandThisL
 const allowDataTraceBool = parseContextBool(allowDataTrace);
 const acknowledgeLeakBool = parseContextBool(iUnderstandThisLeaksCredentials);
 
+// DynamoDB table-deletion escape hatch (state-table protection). Safe-by-
+// default: omitted → the stack keeps state tables RETAIN + deletion-protected
+// + PITR-on. `-c allowTableDeletion=true` flips state tables to DESTROY +
+// deletion-protection OFF so a deliberate `cdk destroy` teardown can delete
+// them (the data is irreversibly lost — DynamoDB tables do not snapshot on
+// delete). `Connections` is always DESTROY regardless. See §9.4 / §11.
+const allowTableDeletion = app.node.tryGetContext('allowTableDeletion') as
+  | boolean
+  | string
+  | undefined;
+const allowTableDeletionBool = parseContextBool(allowTableDeletion);
+
+// DynamoDB point-in-time recovery toggle. Defaults to ON (the stack's own
+// default when omitted); `-c enablePitr=false` disables PITR on every state
+// table (PITR is billed continuously at ~$0.20/GB-month per table; RETAIN
+// and deletionProtection are free). `Connections` never carries PITR. The
+// flag is independent of `allowTableDeletion` — a teardown keeps PITR on.
+const enablePitr = app.node.tryGetContext('enablePitr') as boolean | string | undefined;
+const enablePitrBool = parseContextBool(enablePitr);
+
 // Web client hosting (S3 + CloudFront + OAC) is opt-in. Supplying
 // `webSiteCustomDomain` provisions the static-site construct; prod passes
 // the custom domain + cert + hosted zone, staging leaves them unset to use
@@ -87,6 +107,19 @@ const webSite =
       }
     : undefined;
 
+// Optional WAFv2 per-IP edge rate limit on the WebSocket API's `$connect`
+// (requests per 5-minute window per client IP). Omitted → no WAF
+// resources; `-c wafConnectRateLimit=2000` provisions the WebACL with a
+// rate-based rule + the stage association. CDK context values arrive as
+// strings, so parse to an integer and drop non-numeric values.
+const rawWafConnectRateLimit = app.node.tryGetContext('wafConnectRateLimit');
+const wafConnectRateLimit =
+  typeof rawWafConnectRateLimit === 'number'
+    ? rawWafConnectRateLimit
+    : typeof rawWafConnectRateLimit === 'string' && /^\d+$/u.test(rawWafConnectRateLimit.trim())
+      ? Number.parseInt(rawWafConnectRateLimit.trim(), 10)
+      : undefined;
+
 const stackProps: IrcStackProps = {
   ...(serverName !== undefined ? { serverName } : {}),
   ...(networkName !== undefined ? { networkName } : {}),
@@ -98,6 +131,9 @@ const stackProps: IrcStackProps = {
   ...(acknowledgeLeakBool !== undefined
     ? { iUnderstandThisLeaksCredentials: acknowledgeLeakBool }
     : {}),
+  ...(allowTableDeletionBool !== undefined ? { allowTableDeletion: allowTableDeletionBool } : {}),
+  ...(enablePitrBool !== undefined ? { enablePitr: enablePitrBool } : {}),
+  ...(wafConnectRateLimit !== undefined ? { wafConnectRateLimit } : {}),
   ...(account && region ? { env: { account, region } } : {}),
 };
 

package/apps/aws-stack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-stack",
-  "version": "0.10.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",

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

@@ -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,6 +50,7 @@ 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';
 
@@ -61,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
@@ -211,6 +219,65 @@ export interface IrcStackProps extends StackProps {
    * 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 {
@@ -268,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
@@ -302,13 +397,61 @@ export class IrcAwsStack extends Stack {
     // 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: logicalId,
-          removalPolicy: RemovalPolicy.DESTROY,
+          removalPolicy:
+            isStateTable && !allowTableDeletion ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,
+          ...protectionProps,
         });
+        for (const gsi of globalSecondaryIndexes ?? []) {
+          table.addGlobalSecondaryIndex(gsi);
+        }
         return [logicalId, table];
       }),
     );
@@ -412,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: ['*'],
       }),
     );
@@ -487,6 +636,10 @@ export class IrcAwsStack extends Stack {
     cfnStage.defaultRouteSettings = {
       loggingLevel: apiLoggingLevelParam.valueAsString,
       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);
@@ -494,6 +647,53 @@ 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 literal physical table name (the bare logical
@@ -607,6 +807,12 @@ export class IrcAwsStack extends Stack {
       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,