serverless-ircd 0.9.0 → 0.11.0

package/docs/AWS-Deployment.md

@@ -26,6 +26,8 @@ Key in-repo paths cited below:
 | `packages/aws-adapter/src/cdk-table-defs.ts`      | Five DynamoDB table shapes.                   |
 | `packages/aws-adapter/src/config-loader.ts`       | Lambda env → `ServerConfig` mapping.          |
 | `packages/aws-adapter/src/handlers/index.ts`      | Lambda entry (`handler`, `sweeperHandler`, `pingCheckerHandler`). |
+| `apps/aws-stack/src/static-site.ts`               | CDK construct for the optional web client (S3 + CloudFront + OAC). See §16. |
+| `scripts/deploy-web-aws.mjs`                      | Two-phase web client deploy (describe → bake → s3 sync → invalidate). See §16. |
 | `.github/workflows/deploy-aws.yml`                | Staging deploy + smoke e2e CI.                |
 
 **Acceptance criterion:** a new contributor can deploy their own
@@ -36,8 +38,11 @@ staging instance following only this doc.
 ## 1. What gets deployed
 
 A single CDK v2 stack (`IrcAwsStack`) provisions the entire AWS
-substrate. There are no static assets — CloudFront and S3 are not part
-of this deployment. Every resource is regional.
+substrate. Every resource is regional. The IRC runtime itself is
+stateful compute (Lambda + DynamoDB + API Gateway WebSocket); the
+optional **web client** (S3 + CloudFront + OAC) is provisioned only
+when the `webSite`/`webSiteCustomDomain` CDK context is supplied. See
+§16 for the web-serving path.
 
 ```
    ┌──────────────────────────────────────────────────────────────────┐
@@ -191,19 +196,30 @@ If you skip this, the first `cdk deploy` fails with a bucket-not-found
 error (see §13.1). Bootstrap is idempotent — re-running on an
 already-bootstrapped account is a no-op.
 
-### 3.4 Optional: set up OIDC for CI
+### 3.4 Set up OIDC for CI (required)
 
-If you intend to use the GitHub Actions deploy workflow (§12) without
-long-lived access keys, configure GitHub OIDC:
+> **Mandatory.** Long-lived access keys (`AWS_ACCESS_KEY_ID` /
+> `AWS_SECRET_ACCESS_KEY`) are NOT accepted by the deploy workflow.
+> The workflow assumes a role via GitHub OIDC web identity and asserts
+> the assumed role matches `AWS_DEPLOY_ROLE_ARN` before any `cdk
+> deploy`. The full trust-policy snippet, condition keys, and
+> verification steps are in **§17**.
 
-1. Create an IAM identity provider for `token.actions.githubusercontent.com`.
+To deploy via the GitHub Actions workflow (§12) you MUST configure
+GitHub OIDC — there is no static-key fallback. Summary of the one-time
+setup (full snippet and verification in §17):
+
+1. Create an IAM identity provider for
+   `token.actions.githubusercontent.com` (one per AWS account).
 2. Create a role with a trust policy granting
-   `sts:AssumeRoleWithWebIdentity` to your repo's `ref:refs/heads/main`.
+   `sts:AssumeRoleWithWebIdentity` to your repo's
+   `ref:refs/heads/main` claim (the workflow is
+   `workflow_dispatch`-only on `main`).
 3. Attach a permission policy broad enough to manage the stack (IAM,
-   API Gateway v2, Lambda, DynamoDB, EventBridge, CloudFormation).
+   API Gateway v2, Lambda, DynamoDB, EventBridge, CloudFormation) —
+   ideally the same surface `cdk deploy` needs.
 4. Note the role ARN — it becomes the `AWS_DEPLOY_ROLE_ARN` secret in
-   CI. Static keys (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`) are
-   the fallback; the workflow supports both.
+   CI.
 
 ---
 
@@ -283,18 +299,18 @@ shared protocol layer.
 
 ---
 
-## 5. Deploy staging
+## 5. Deploy
 
-Staging is the environment CI deploys on every push to `main`; you can
-also deploy it manually from a clean checkout.
+The deploy is `workflow_dispatch`-only (a maintainer runs it by hand);
+you can also deploy manually from a clean checkout.
 
 ### 5.1 Deploy from your machine
 
 ```bash
 # From the repo root:
-pnpm deploy:aws:staging
+pnpm deploy:aws
 # Equivalent to:
-#   pnpm --filter @serverless-ircd/aws-stack deploy:staging
+#   pnpm --filter @serverless-ircd/aws-stack run deploy
 #   → cdk deploy --all --require-approval never
 ```
 
@@ -349,38 +365,39 @@ TCP IRC client to a WebSocket endpoint.
 
 ---
 
-## 6. Deploy production
-
-The repo-level shortcut is:
-
-```bash
-pnpm deploy:aws:prod
-# Equivalent to:
-#   pnpm --filter @serverless-ircd/aws-stack deploy:prod
-#   → cdk deploy --all --require-approval never
-```
+## 6. Production hardening
 
-**There is no separate production stack.** `deploy:prod` and
-`deploy:staging` run the identical CDK command — both deploy a stack
-named `IrcAwsStack` (hardcoded in `apps/aws-stack/bin/aws.ts`). The
-staging/production distinction is **which AWS account and region the
-stack is deployed into**, controlled by the credentials and
-`AWS_REGION` in the environment.
+There is a single deploy target per platform (`pnpm deploy:aws`). The
+staging/prod split was collapsed — there is no `-staging` / `-prod`
+stack-name suffix, no `environmentName` CDK context, and no per-env
+table-name prefixing. The stack is always named `IrcAwsStack` (hardcoded
+in `apps/aws-stack/bin/aws.ts`), and table names are the bare logical
+ids (`Connections`, `Nicks`, …). The staging/production distinction is
+**which AWS account and region the stack is deployed into**, controlled
+by the credentials and `AWS_REGION` in the environment.
 
-For a real production deployment, before your first `pnpm deploy:aws:prod`:
+For a real production deployment, before your first `pnpm deploy:aws`:
 
 1. **Use a dedicated AWS account** (or at least a dedicated region) for
    production. Do not point production credentials at the same stack
    CI is deploying to on every push.
-2. **Change `RemovalPolicy.DESTROY` to `RemovalPolicy.RETAIN`** on the
-   five DynamoDB tables (see §9.4). The committed stack deletes all
-   data on `cdk destroy` — intentional for staging, dangerous for
-   production.
+2. **Keep the default table protection on.** State-bearing tables
+   (`Nicks`, `Services`, `ChannelMeta`, `ChannelMembers`) default to
+   `RemovalPolicy.RETAIN` + `deletionProtection: true` + PITR-on, so a
+   mistaken `cdk destroy` or a stray `aws dynamodb delete-table` cannot
+   wipe them (see §9.4). Only set `-c allowTableDeletion=true` for a
+   deliberate teardown.
 3. **Set the server identity** (`SERVER_NAME`, `NETWORK_NAME`,
    `MOTD`) — see §7.1. `SERVER_NAME` is required at boot; the stack
    falls back to `irc.localhost` when the prop is omitted, which is
    intentionally not production-ready.
 4. **Pick a region close to your users** (see §10).
+5. **Do NOT re-enable API Gateway `DataTraceEnabled`.** It is OFF by default
+   (safe). Turning it on logs the full body of every IRC frame (`PASS`,
+   `AUTHENTICATE <SASL-PLAIN>`, channel keys, all `PRIVMSG`/`NOTICE`) to
+   CloudWatch, leaking credentials to anyone with `logs:GetLogEvents`. The
+   two-step sandbox-only escape hatch is documented in §7.6; never use it
+   against a production account.
 
 There is **no CI auto-deploy to production**. The deploy workflow
 (`deploy-aws.yml`) only triggers on push to `main` and targets
@@ -418,8 +435,7 @@ These three values are injected into the `IrcHandler` and
 pass the construct props when creating the stack:
 
 ```ts
-new IrcAwsStack(app, 'IrcAwsStack-production', {
-  environmentName: 'production',
+new IrcAwsStack(app, 'IrcAwsStack', {
   serverName: 'irc.my.net',
   networkName: 'MyNet',
   motdLines: ['Welcome to my network.', 'Be excellent to each other.'],
@@ -484,6 +500,13 @@ any of them** — to enable one, add an `addEnvironment(...)` line in
 | `MAX_LIST_ENTRIES`        | int     | `maxListEntries`      |
 | `QUIT_MESSAGE`            | string  | `quitMessage`         |
 | `SASL_ACCOUNTS`           | string  | `saslAccounts`        |
+| `MAX_CONNECTIONS_PER_IP`  | int     | `maxConnectionsPerIp` |
+| `PER_IP_CONNECTION_RATE_MAX` | int  | `perIpConnectionRate.max` |
+| `PER_IP_CONNECTION_RATE_WINDOW_MS` | int | `perIpConnectionRate.windowMs` |
+
+The last three are the per-IP admission knobs (§7.8): setting only one
+half of the rate pair falls back to the schema default (5 per 60 000 ms)
+for the other half.
 
 `SASL_ACCOUNTS` is the legacy/config fallback (newline-delimited
 `username:password` pairs); it is used only when the `Accounts` table is
@@ -493,18 +516,25 @@ Invalid values cause a readable boot-time error — the Lambda will
 throw on the first invocation (cold start). Test changes locally with
 `pnpm --filter @serverless-ircd/aws-adapter test`.
 
+> **Note:** `WEB_ORIGINS` is intentionally NOT in this table. It is an
+> adapter-level operational concern (the `$connect` CSWSH defence), not
+> a `ServerConfig` knob — the env var is parsed directly by
+> `buildDepsFromEnv` via `parseWebOrigins` rather than threaded through
+> the shared Zod schema. See §8.2.
+
 ### 7.4 No per-environment stack parameter
 
-There is no `stageName` or `environmentType` parameter on the CDK
-stack. The stack name (`IrcAwsStack`), table names
-(`Connections`, `ChannelMeta`, `ChannelMembers`, `Nicks`, `Accounts`),
-API Gateway stage name (`prod`), and Lambda construct ids are all
-hardcoded. To run staging and production in **the same AWS account**,
-you would need to fork the stack to parameterize these names; the
-recommended path is to use separate accounts (or separate regions) for
-staging vs production. This is the same architectural choice the
-Cloudflare adapter makes (staging and production are separate Worker
-namespaces).
+There is no `stageName`, `environmentType`, or `environmentName`
+parameter on the CDK stack (the former staging/prod split was
+collapsed into a single target). The stack name (`IrcAwsStack`), table
+names (`Connections`, `ChannelMeta`, `ChannelMembers`, `Nicks`,
+`Accounts`, `Services`), API Gateway stage name (`prod`), and Lambda
+construct ids are all hardcoded. To run staging and production in
+**the same AWS account**, you would need to fork the stack to
+parameterize these names; the recommended path is to use separate
+accounts (or separate regions) for staging vs production. This is the
+same architectural choice the Cloudflare adapter makes (one Worker
+namespace; staging vs production isolation is by account).
 
 ### 7.5 Lambda runtime and bundling
 
@@ -525,6 +555,91 @@ namespaces).
 | Auto-deploy       | `true` (changes propagate without a manual deployment).   |
 | Auth on `$connect`| None today (no authorizer). See §13.5.                    |
 | Route responses   | Default (`$connect` returns 200 → upgrade; `$default` and `$disconnect` are fire-and-forget). |
+| Logging level     | `INFO` by default; override at deploy time via `--parameters ApiGatewayLoggingLevel=OFF\|INFO\|ERROR`. Emits request/response metadata (route, status, source IP, …) **without** frame bodies. |
+| Full-frame body tracing (`DataTraceEnabled`) | **OFF by default and hard-locked.** See the warning below. |
+
+#### ⚠️ Re-enabling `DataTraceEnabled` leaks IRC credentials
+
+API Gateway execution-log body tracing (`DataTraceEnabled = true`) writes
+the FULL payload of every WebSocket frame to the APIGW CloudWatch log group
+(`AWS/ApiGateway…`, separate from the stack's access-log group). For an IRC
+endpoint that includes, verbatim:
+
+- `PASS <server password>`
+- `AUTHENTICATE <base64-SASL-PLAIN>` (decodes to `account\0account\0password`)
+- `JOIN #channel <channel-key>`
+- every `PRIVMSG` / `NOTICE` (private messages)
+
+Anyone with `logs:GetLogEvents` — operators, SREs, a Logpush destination, or
+compromised CI credentials — recovers server passwords, SASL accounts,
+channel keys, and private messages. Retention is account-default (unbounded).
+
+For this reason `DataTraceEnabled` defaults to `false` and is the single
+highest-impact logging control on the stack. INFO-level execution logging
+alone is enough to diagnose whether API Gateway received and routed a frame
+or dropped it pre-Lambda.
+
+Because the staging/prod split was collapsed (every synth is effectively a
+prod synth), there is no quiet "non-prod" path to re-enable it. The only way
+back on is an explicit, **two-step opt-in** that exists solely for live
+debugging in a throwaway sandbox:
+
+```sh
+pnpm --filter @serverless-ircd/aws-stack run cdk:synth -- \
+  -c allowDataTrace=true \
+  -c iUnderstandThisLeaksCredentials=true
+```
+
+Setting only `-c allowDataTrace=true` **refuses synthesis** with a loud error
+that names the credentials it would leak. The awkward second flag is
+intentional — it cannot be set by accident. Tear the sandbox stack down
+immediately after debugging; never deploy this combination to a shared
+account.
+
+### 7.7 DynamoDB table-protection context flags
+
+Two CDK context flags control the state-bearing tables' data-loss
+protection (`Nicks`, `Services`, `ChannelMeta`, `ChannelMembers`).
+`Connections` is always `DESTROY` with no PITR and is unaffected by
+either flag. See §9.4 for the full table and the rationale (and the
+"no snapshot-on-delete" note).
+
+| Context flag           | Default | Effect when flipped                                                                 |
+|------------------------|---------|-------------------------------------------------------------------------------------|
+| `allowTableDeletion`   | `false` | `true` → state tables become `RemovalPolicy.DESTROY` + `deletionProtection: false`, so a deliberate `cdk destroy` teardown can delete them. Data is irreversibly lost. |
+| `enablePitr`           | `true`  | `false` → point-in-time recovery is disabled on every state table. Independent of `allowTableDeletion` (a teardown keeps PITR on). PITR costs ~$0.20/GB-month per table (§11.1). |
+
+Both arrive as strings on the CLI and are normalised with the shared
+`parseContextBool` helper (same path as `allowDataTrace`), so
+`-c allowTableDeletion=false` stays false-y. They map onto the
+`IrcStackProps.allowTableDeletion` / `IrcStackProps.enablePitr` construct
+props (`apps/aws-stack/bin/aws.ts`).
+
+### 7.8 Connect throttling (per-IP admission, stage limits, WAF)
+
+Connection setup is where credential brute-force spends its budget
+(`PASS` / `AUTHENTICATE` per connection), so the stack throttles it in
+three layers, outermost first:
+
+| Layer | Where | Knob | Default |
+|-------|-------|------|---------|
+| **1. WAF edge rate limit** | WAFv2 rate-based rule, associated with the stage. WAF only inspects the initial HTTP upgrade on a WebSocket API, so the rule is effectively scoped to `$connect` and never re-fires on established frames. | `-c wafConnectRateLimit=<req/5min/IP>` (CDK context; blocks at the edge before a Lambda invocation is billed) | off (no WAF resources) |
+| **2. APIGW stage throttling** | `defaultRouteSettings` on the stage — global backstop across ALL routes and IPs. | `--parameters ApiThrottlingRateLimit=…` / `--parameters ApiThrottlingBurstLimit=…` (CloudFormation parameters) | 100 rps / burst 200 |
+| **3. Per-IP admission gates** | Inside the `$connect` Lambda: a paginated Query against the `Connections` table's `sourceIp-connectedSince` GSI counts the caller IP's live connections (`maxConnectionsPerIp`) and in-window establishments (`perIpConnectionRate`); over-budget connects return `429` and no row is written. The same rate budget gates NLB new flows (§AWS-TCP-Deployment). | `MAX_CONNECTIONS_PER_IP`, `PER_IP_CONNECTION_RATE_MAX`, `PER_IP_CONNECTION_RATE_WINDOW_MS` env vars (§7.3) | 10 / 5 per 60 s |
+
+Notes:
+
+- Layer 1 is opt-in because WAFv2 web ACLs cost ~$5/mo + $1/rule + $0.60/M
+  requests; for a small deployment, layers 2+3 are usually enough. Enable
+  with `pnpm --filter @serverless-ircd/aws-stack run cdk:synth -- -c wafConnectRateLimit=2000`
+  (2000 upgrade requests per 5-minute window per client IP before the IP
+  is blocked at the edge).
+- Layer 3's per-IP counts are eventually consistent (GSI reads), so a
+  coordinated burst from one IP can slightly overshoot the cap — the same
+  best-effort TOCTOU contract as the global `maxClients` counter.
+- The 429 response carries `ERROR :Closing link` semantics at the HTTP
+  layer where possible; clients should treat it as back-pressure (retry
+  after the window decays), not a permanent ban.
 
 ---
 
@@ -599,7 +714,7 @@ root):
 node --input-type=module -e '
   import { createDynamoDocumentClient, putAccountCredential } from "@serverless-ircd/aws-adapter";
   const dynamo = createDynamoDocumentClient({ region: "us-east-1" });
-  await putAccountCredential(dynamo, "StagingAccounts", "alice", "change-me");
+  await putAccountCredential(dynamo, "Accounts", "alice", "change-me");
   console.log("seeded alice");
 '
 ```
@@ -610,13 +725,13 @@ calls for batch provisioning:
 ```bash
 # Seed against DynamoDB Local:
 npx tsx tools/seed-aws-accounts.ts \
-  --table StagingAccounts \
+  --table Accounts \
   --endpoint http://localhost:8000 \
   --accounts alice:s3cret bob:password2
 
 # Or from a file (newline-delimited username:password):
 npx tsx tools/seed-aws-accounts.ts \
-  --table StagingAccounts \
+  --table Accounts \
   --region us-east-1 \
   --file accounts.txt
 ```
@@ -627,7 +742,7 @@ row directly:
 ```bash
 # Hash with the adapter, then write the row yourself:
 aws dynamodb put-item \
-  --table-name StagingAccounts \
+  --table-name Accounts \
   --item '{"account":{"S":"alice"},"algorithm":{"S":"scrypt"},"salt":{"S":"<base64-salt>"},"hash":{"S":"<base64-hash>"}}'
 ```
 
@@ -641,14 +756,80 @@ aws dynamodb put-item \
 vars are visible in the console and in CloudFormation describe output;
 they are not secret.
 
+### 8.2 `$connect` Origin allowlist (`WEB_ORIGINS`, CSWSH defence)
+
+WebSocket upgrades do not follow the same-origin policy, so a malicious
+web page can open a WebSocket to the IRC server from the victim's
+browser and drive the session with the victim's credentials (Cross-Site
+WebSocket Hijacking, CSWSH). API Gateway WebSocket has **no built-in
+`Origin` validation** — the `$connect` Lambda receives
+`event.headers.Origin` and must enforce the allowlist itself.
+
+**Knob:** `WEB_ORIGINS` — a comma-separated list of allowed web origins
+(e.g. `https://app.example.com, https://staging.app.example.com`).
+Mirror of the CF Worker's `WEB_ORIGINS` (TICKET-137).
+
+**Behaviour** (`packages/aws-adapter/src/origin-allowlist.ts` and
+`packages/aws-adapter/src/handlers/connect.ts`):
+
+| `WEB_ORIGINS` | `Origin` header on the upgrade | Outcome                                |
+|---------------|--------------------------------|----------------------------------------|
+| unset / empty | (any)                          | **Allow** — defence disabled (default) |
+| set           | absent (non-browser client)    | **Allow** — curl / WeeChat / `tcp-ws-forwarder` / NLB TCP+TLS pass through |
+| set           | present, in allowlist          | **Allow**                              |
+| set           | present, NOT in allowlist      | **Deny** — `$connect` returns `403`; API Gateway closes the upgrade |
+
+**The defence is opt-in.** Unset `WEB_ORIGINS` skips the check entirely
+— existing AWS deployments without a web frontend are unchanged on
+upgrade. The check only matters once you ship a web client (TICKET-164)
+and want to admit the SPA's origin while rejecting hostile ones.
+
+**Matching semantics** (mirror the CF Worker):
+ - entries are trimmed of surrounding whitespace and lowercased
+   (`https://APP.Example.COM` → `https://app.example.com`);
+ - the incoming `Origin` header is normalised the same way before the
+   membership test, so the match is case-insensitive on scheme+host
+   (per RFC 3986);
+ - origins are otherwise case-sensitive — `http://app.example.com` is
+   a different origin from `https://app.example.com` and is denied if
+   only the `https://` form is listed (defends against a stripped-TLS
+   attacker on the same hostname).
+
+**Deliberate divergence from the CF policy:** the CF Worker has a
+same-origin auto-derive mode (when `WEB_ORIGINS` is unset, it compares
+`Origin` against the request's own `Host`). On AWS the SPA is served
+from a different CloudFront origin than the API Gateway WebSocket
+endpoint (`wss://{api-id}.execute-api.…`), so the request's own host is
+never the SPA's origin — auto-derive does not apply. The AWS defence is
+therefore explicit-allowlist only.
+
+**Wiring.** Inject `WEB_ORIGINS` on the `$connect` Lambda via the CDK
+stack prop:
+
+```typescript
+new IrcAwsStack(app, 'IrcAwsStack', {
+  webOrigins: 'https://app.example.com, https://staging.app.example.com',
+  // ...other props
+});
+```
+
+…or at deploy time via CDK context (`-c webOrigins=…`). The stack
+injects the env var only on the wss `$connect` handler (the sweeper,
+ping-checker, and NLB handler never run `$connect`). The handler parses
+the value once per cold start via `parseWebOrigins` and stores the
+resulting `Set<string>` on `HandlerDeps.webOrigins`.
+
+`WEB_ORIGINS` is **not** a secret — it is a public allowlist of origin
+strings. Do not put it in Secrets Manager / SSM; set it as a plain
+Lambda env var (the CDK stack does this directly via
+`addEnvironment`).
+
 The CI deploy uses **GitHub Actions secrets** plus an optional repo
 variable (see §12):
 
 | Secret                  | Used by           | Purpose                                                       |
 |-------------------------|-------------------|---------------------------------------------------------------|
-| `AWS_ACCESS_KEY_ID`     | `deploy-aws.yml`  | Static access key for CDK deploy. Required unless OIDC is used. |
-| `AWS_SECRET_ACCESS_KEY` | `deploy-aws.yml`  | Companion secret key. Required unless OIDC is used.           |
-| `AWS_DEPLOY_ROLE_ARN`   | `deploy-aws.yml`  | Optional. When set, the job assumes this role via OIDC web identity instead of using static keys. |
+| `AWS_DEPLOY_ROLE_ARN`   | `deploy-aws.yml`  | **Required.** ARN of the IAM role the workflow assumes via GitHub OIDC web identity. No static-key fallback. |
 | `AWS_REGION`            | `deploy-aws.yml`  | Region to deploy into (e.g. `us-east-1`).                     |
 
 | Variable        | Purpose                                                              |
@@ -728,28 +909,62 @@ postToConnection, per-channel send-list cache, a dedicated fanout
 Lambda) are deferred to post-v1; the load-test ticket will surface
 the ceiling.
 
-### 9.4 Removal policy (IMPORTANT)
+### 9.4 Removal policy, deletion protection, and PITR (IMPORTANT)
+
+Every table is protected from accidental data loss by default. The
+state-bearing tables (`Nicks`, `Services`, `ChannelMeta`, `ChannelMembers`)
+get **three independent safeguards**, each toggleable so a deliberate
+teardown can still proceed; the one ephemeral table (`Connections`) is
+always DESTROY:
+
+| Table                                         | RemovalPolicy | `deletionProtection` | PITR |
+|-----------------------------------------------|---------------|----------------------|------|
+| `Nicks`, `Services`, `ChannelMeta`, `ChannelMembers` | `RETAIN` (default) | `true` (default) | `true` (default) |
+| `Connections`                                 | `DESTROY`     | (unset → off)        | (unset → off) |
+
+- **`RemovalPolicy.RETAIN`** — when the stack is deleted, CloudFormation
+  *orphans* the table instead of deleting it; the data survives.
+- **`deletionProtection: true`** — DynamoDB refuses a `DeleteTable` API
+  call while this is on, blocking a stray `aws dynamodb delete-table` even
+  from an admin or compromised credential.
+- **`pointInTimeRecovery` (PITR)** — continuous, per-table restore (within
+  the last ~35 days) against accidental writes/deletes that RETAIN +
+  deletion protection cannot stop (e.g. a buggy `UpdateItem` that
+  overwrites rows).
+
+> **No snapshot-on-delete.** DynamoDB tables do NOT snapshot when a stack
+> is deleted (`RemovalPolicy.SNAPSHOT` is a no-op here). `RETAIN` (orphan +
+> keep) + PITR (continuous, in-place restore) is the correct combination;
+> do not rely on a snapshot that does not exist.
+
+Two CDK context flags control these (threaded through `bin/aws.ts`, see
+§7.7):
+
+- **`allowTableDeletion`** (default `false`). Set `-c allowTableDeletion=true`
+  for a deliberate `cdk destroy` teardown: every state table flips to
+  `RemovalPolicy.DESTROY` with `deletionProtection: false` so CloudFormation
+  can delete them. The data is **irreversibly lost** — flip this off only
+  when you genuinely want the tables gone. `Connections` is always DESTROY
+  regardless.
+- **`enablePitr`** (default `true`). Set `-c enablePitr=false` to disable
+  PITR on every state table. Independent of `allowTableDeletion` — a
+  teardown keeps PITR on (harmless, and the data is still recoverable up
+  until the table is actually deleted). `Connections` never carries PITR.
 
-The stack sets `RemovalPolicy.DESTROY` on every table:
+```bash
+# Default deploy: state tables RETAIN + deletion-protected + PITR-on.
+pnpm --filter @serverless-ircd/aws-stack run cdk:synth
 
-```ts
-// apps/aws-stack/src/aws-stack.ts:48
-const tables = Object.entries(TABLE_DEFS).map(
-  ([logicalId, tableProps]) =>
-    new Table(this, logicalId, { ...tableProps, removalPolicy: RemovalPolicy.DESTROY }),
-);
-```
+# Deliberate teardown (state tables become DELETABLE):
+pnpm --filter @serverless-ircd/aws-stack run cdk:synth -- -c allowTableDeletion=true
 
-**This means `cdk destroy` deletes every table and all of its data.**
-This is intentional for staging (you want a clean teardown between
-experiments) and **dangerous for production**.
+# Disable PITR (e.g. cost-sensitive dev deploy):
+pnpm --filter @serverless-ircd/aws-stack run cdk:synth -- -c enablePitr=false
+```
 
-For production, fork the stack to use `RemovalPolicy.RETAIN` (or
-`RETAIN_ON_UPDATE`): tables become orphans on stack deletion and keep
-their data. There is no built-in knob for this today — it requires
-editing `aws-stack.ts`. Recommendation: ship a `production: boolean`
-stack prop in a future change that flips the removal policy. Flagged
-in §15.
+The protection knobs are asserted per parameter combination in
+`apps/aws-stack/tests/stack.test.ts` (the "DynamoDB table protection"
+suite).
 
 ### 9.5 TTL on `Connections.idleSince`
 
@@ -819,9 +1034,10 @@ see ~10 ms. **Pick the region closest to your user base.**
 
 ### 10.2 Recommendation: single-region for v1
 
-For v1, deploy in one region. There are no static assets (CloudFront
-and S3 are not part of this stack), so a CDN adds no value here.
-Single-region keeps the data model simple: the cross-table
+For v1, deploy in one region. The IRC runtime is regional stateful
+compute (Lambda + DynamoDB + APIGW); CloudFront only enters the picture
+for the optional web client (§16) and is global-edge, not a region
+picker. Single-region keeps the data model simple: the cross-table
 `TransactWriteItems` flows (§9.2) only work within one region.
 
 ### 10.3 Multi-region is out of scope for v1
@@ -877,12 +1093,25 @@ verify against the current AWS pricing page** before budgeting:
 | Lambda                   | GB-second                                      | $0.0000166667 (≈ $0.0167 / GB-hour) |
 | DynamoDB on-demand       | write request unit (WRU)                       | $1.25 / million               |
 | DynamoDB on-demand       | read request unit (RRU)                        | $0.25 / million               |
+| DynamoDB PITR (continuous)| GB-month of table data + indexes, per table   | ~$0.20 / GB-month             |
 | EventBridge Scheduler    | event published                                | $1.00 / million               |
 | CloudWatch Logs          | GB ingested                                    | $0.50                         |
 
 The Lambda free tier (1M requests + 400k GB-seconds per month) covers
 a meaningful slice of a small staging deployment.
 
+> **Table-protection cost.** `RemovalPolicy.RETAIN` and
+> `deletionProtection` are **free** — they are CloudFormation/DynamoDB
+> flags, not billable features. Point-in-time recovery (PITR) **is**
+> billed: continuously at ~$0.20/GB-month **per table**, charged on the
+> full table size including indexes, for as long as PITR is on. With the
+> default (`enablePitr=true`) this applies to the four state tables
+> (`Nicks`, `Services`, `ChannelMeta`, `ChannelMembers`); `Connections`
+> never carries PITR. For a small deployment these tables are tiny
+> (kilobytes to low megabytes), so the PITR line item is fractions of a
+> cent; it only becomes material if a table grows to many GB. Disable
+> with `-c enablePitr=false` on a cost-sensitive dev deploy (see §9.4).
+
 ### 11.2 Back-of-envelope: 100 concurrent users
 
 Assume a small staging deployment with 100 concurrent users, average
@@ -922,10 +1151,10 @@ single 1k-member announcement channel can multiply the fanout cost by
 
 ## 12. CI/CD
 
-The GitHub Actions workflow at `.github/workflows/deploy-aws.yml`
-deploys staging on every push to `main` and replays the smoke e2e. It
-is the canonical deploy path — manual `pnpm deploy:aws:staging` is for
-iteration only.
+The GitHub Actions workflow at `.github/workflows/deploy-aws.yml` is
+`workflow_dispatch`-only (a maintainer triggers it by hand); there is
+no automatic push-to-main deploy. It deploys the single AWS target and
+replays the smoke e2e.
 
 ### 12.1 What the workflow does
 
@@ -936,60 +1165,91 @@ Steps performed (in order):
 3. `pnpm install --frozen-lockfile`.
 4. `pnpm build` — builds all workspace packages.
 5. `pnpm typecheck` and `pnpm test` — gate the deploy.
-6. Configure AWS credentials (OIDC if `AWS_DEPLOY_ROLE_ARN` is set,
-   otherwise static keys).
-7. `pnpm deploy:aws:staging` → `cdk deploy --all --require-approval never`.
-8. Resolve the smoke URL: repo variable `AWS_SMOKE_URL` first, else
-   the stack's `ConnectUrl` CloudFormation output via
-   `aws cloudformation describe-stacks --stack-name IrcAwsStack`, else
-   skip the smoke step with a warning.
-9. `pnpm smoke:aws:staging -- --url "$SMOKE_URL"` — failure fails the
-   build.
-
-Concurrency is serialized via `concurrency.group: aws-staging`,
-`cancel-in-progress: false`, so two pushes cannot race the same
+6. **Assert `AWS_DEPLOY_ROLE_ARN` is non-empty** (fail-fast before any
+   AWS call).
+7. Configure AWS credentials via OIDC (`aws-actions/configure-aws-credentials@v4`
+   with `role-to-assume` only — no static keys).
+8. **Assert `aws sts get-caller-identity` returns the configured role**
+   (defence-in-depth against silent fallbacks).
+9. `pnpm deploy:aws` → `cdk deploy --all --require-approval never`.
+10. Resolve the smoke URL: repo variable `AWS_SMOKE_URL` first, else
+    the stack's `ConnectUrl` CloudFormation output via
+    `aws cloudformation describe-stacks --stack-name IrcAwsStack`, else
+    skip the smoke step with a warning.
+11. `pnpm smoke:aws -- --url "$SMOKE_URL"` — failure fails the
+    build.
+
+Concurrency is serialized via `concurrency.group: aws-deploy`,
+`cancel-in-progress: false`, so two runs cannot race the same
 CloudFormation stack.
 
 ### 12.2 Required repo configuration
 
 Under **Settings → Secrets and variables → Actions**:
 
-- **Secret `AWS_ACCESS_KEY_ID`** — required unless OIDC.
-- **Secret `AWS_SECRET_ACCESS_KEY`** — required unless OIDC.
-- **Secret `AWS_DEPLOY_ROLE_ARN`** — optional; enables OIDC.
+- **Secret `AWS_DEPLOY_ROLE_ARN`** — **required**. ARN of the IAM
+  role the workflow assumes via GitHub OIDC. There is no static-key
+  fallback. Set this up once per AWS account (see §17 for the trust
+  policy).
 - **Secret `AWS_REGION`** — required (e.g. `us-east-1`).
 - **Variable `AWS_SMOKE_URL`** — optional but recommended; the
   workflow can fall back to the CFN output, but setting this variable
   explicitly avoids the `describe-stacks` round-trip and the
   possibility of a stale cached value after a redeploy.
 
-### 12.3 OIDC vs static keys
+> **Removed:** `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are no
+> longer read by the workflow. Long-lived access keys powerful enough
+> to deploy CloudFormation + IAM + Lambda + DynamoDB are effectively
+> account-admin; a single exfil vector yields full AWS account
+> takeover. The H1 security-hardening ticket dropped them. If you have
+> stale `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` secrets in the
+> repo, delete them and invalidate the underlying IAM access key in
+> IAM → Users → Security credentials.
 
-The workflow supports both auth modes:
+### 12.3 OIDC is mandatory
+
+The workflow accepts **only** GitHub OIDC web-identity credentials:
 
 ```yaml
+permissions:
+  id-token: write
+  contents: read
+
+# …
+
+- name: Assert OIDC deploy role ARN is set
+  if: env.AWS_DEPLOY_ROLE_ARN == ''
+  env:
+    AWS_DEPLOY_ROLE_ARN: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+  run: |
+    echo "::error::AWS_DEPLOY_ROLE_ARN secret is empty …"
+    exit 1
+
 - name: Configure AWS credentials
   uses: aws-actions/configure-aws-credentials@v4
   with:
     aws-region: ${{ secrets.AWS_REGION }}
     role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
-    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
-    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+
+- name: Assert assumed role matches AWS_DEPLOY_ROLE_ARN
+  # aws sts get-caller-identity + ARN-shape check; aborts before cdk deploy.
+  run: …
 ```
 
-When `AWS_DEPLOY_ROLE_ARN` is set, the action assumes the role via
-OIDC web identity (requires `permissions.id-token: write`, which the
-workflow declares) and ignores the static keys. When unset, it falls
-back to the static access-key pair. OIDC is the recommended path for
-any deployment tied to a real AWS account — no long-lived credentials
-to rotate.
+The `id-token: write` permission lets Actions mint the OIDC JWT that
+`sts:AssumeRoleWithWebIdentity` consumes. After the assume-role step
+the workflow calls `aws sts get-caller-identity` and asserts the
+returned ARN's role-name + account-id match `AWS_DEPLOY_ROLE_ARN`, so
+a silent fallback to ambient static credentials cannot ship a deploy.
+See §17 for the matching IAM trust policy and verification.
 
-### 12.4 No CI auto-deploy to production
+### 12.4 Manual-only deploy trigger
 
-Production deploys are intentionally manual (`pnpm deploy:aws:prod`
-from a clean checkout on `main`, against separate credentials). The
-workflow's `on:` block only triggers on `push` to `main` and
-`workflow_dispatch`, both of which target staging.
+The workflow's `on:` block is `workflow_dispatch`-only — there is no
+automatic push-to-main trigger, and no separate staging/prod target.
+A maintainer runs the deploy by hand against whichever AWS account
+and region the secrets point at; staging vs production isolation is
+driven by account/region, not by a workflow-per-env split.
 
 ---
 
@@ -1005,7 +1265,7 @@ The CDK bootstrap stack hasn't been created in this account/region.
 ```bash
 cd apps/aws-stack
 pnpm cdk bootstrap
-pnpm deploy:aws:staging
+pnpm deploy:aws
 ```
 
 Bootstrap is idempotent and per-region — re-run it if you change
@@ -1024,7 +1284,7 @@ injects these — if one is missing in the console, somebody hand-edited
 the Lambda config. Fix by re-deploying:
 
 ```bash
-pnpm deploy:aws:staging
+pnpm deploy:aws
 ```
 
 If the error mentions `MANAGEMENT_URL` being absent: that env var is
@@ -1073,7 +1333,7 @@ to resolve the smoke URL. If this returns nothing, either:
   name, the workflow's `--stack-name IrcAwsStack` won't find it.
   Update the workflow or rename back.
 - **The deploy failed silently.** Check the prior `pnpm
-  deploy:aws:staging` step's exit code. `cdk deploy` with
+  deploy:aws` step's exit code. `cdk deploy` with
   `--require-approval never` can still fail on IAM or
   CloudFormation errors.
 - **Wrong region.** The `describe-stacks` call uses `AWS_REGION` from
@@ -1234,14 +1494,18 @@ npm install -g aws-cdk-local
 export AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1
 LOCALSTACK=1 pnpm --filter @serverless-ircd/aws-stack test
 
-# Staging
-pnpm deploy:aws:staging
+# Deploy (single target — staging vs prod is which account/region you point at)
+pnpm deploy:aws
 node apps/aws-stack/scripts/smoke.mjs \
   --url wss://<id>.execute-api.<region>.amazonaws.com/prod
 aws logs tail /aws/lambda/IrcHandler --follow     # live logs
 
-# Production (manual, separate credentials)
-pnpm deploy:aws:prod
+# Web client (opt-in; provision via webSite/webSiteCustomDomain context)
+pnpm deploy:aws -- -c webSiteCustomDomain=app.example.com \
+                  -c webSiteCertificateArn=arn:aws:acm:us-east-1:... \
+                  -c webSiteHostedZoneName=example.com. -c webSiteHostedZoneId=... \
+                  -c webOrigins=https://app.example.com   # CSWSH (§8.2, §16.4)
+node scripts/deploy-web-aws.mjs                    # bake + s3 sync + invalidate (§16.3)
 
 # Tests / lint
 pnpm test                                         # full workspace
@@ -1263,9 +1527,420 @@ Key files:
 | `packages/aws-adapter/src/tables.ts`              | Runtime table-name + key-column constants.          |
 | `packages/aws-adapter/src/config-loader.ts`       | Lambda env → `ServerConfig` schema mapping.         |
 | `packages/aws-adapter/src/handlers/index.ts`      | Lambda entry points (`handler`, `sweeperHandler`, `pingCheckerHandler`). |
+| `apps/aws-stack/src/static-site.ts`               | CDK construct for the optional web client (S3 + CloudFront + OAC). See §16. |
+| `scripts/deploy-web-aws.mjs`                      | Two-phase web client deploy helper. See §16.        |
 | `.github/workflows/deploy-aws.yml`                | Staging deploy + smoke e2e CI.                      |
 
-### Known gaps flagged for follow-up
+---
+
+## 16. Web client (S3 + CloudFront + OAC)
+
+The CF Worker serves the SPA from the same origin as the WebSocket
+(one Worker, one domain). AWS **cannot** do this — API Gateway
+WebSocket and a static SPA host are different AWS services on
+different endpoints — so the AWS web client splits in two: the wss
+IRC endpoint stays on API Gateway, and the SPA is served from an S3
+bucket fronted by CloudFront. This § documents the architecture, the
+build, the deploy pipeline, the CSWSH defence (mandatory once the
+SPA ships), and the optional custom-domain setup.
+
+> **Cross-reference:** `docs/WebClientGuide.md` covers the
+> Cloudflare path (one origin for HTTP + WebSocket). The CF-vs-AWS
+> architectural difference is called out in §16.5 below.
+
+### 16.1 What gets provisioned
+
+The `StaticSite` construct (`apps/aws-stack/src/static-site.ts`,
+provisioned only when `IrcStackProps.webSite` is supplied) creates:
+
+- a **private S3 bucket** holding the `apps/web/dist` build artifact
+  (`index.html` for the landing page, `webclient/index.html` for the
+  Kiwi SPA, `webclient/static/*` for hashed JS/CSS) — the same layout
+  the CF Worker's `[assets]` binding serves, so one artifact ships on
+  both platforms unchanged;
+- a **CloudFront distribution** with an S3 origin pointing at the
+  bucket via **Origin Access Control (OAC)** — the modern replacement
+  for the legacy OAI. Direct S3 access (`https://<bucket>.s3.…/…`)
+  is denied by the bucket policy; only CloudFront URLs resolve;
+- `defaultRootObject = index.html` so requests to `/` serve the
+  project landing page (the static HTML front door with links to the
+  SPA, the rendered docs, and the source repo);
+- a **custom error response** mapping S3's `403`/`404` → `200` with
+  response page `/webclient/index.html`, so client-side routes under
+  `/webclient/*` resolve to the SPA shell (Kiwi is hash/history-routed);
+- three CFN outputs at the parent-stack level (stable logical IDs):
+  `WebsiteURL` (the `*.cloudfront.net` default OR the custom domain),
+  `WebsiteBucketName`, `WebsiteDistributionId`. The deploy pipeline
+  (§16.3) consumes the latter two.
+
+**Why not Amplify / why not S3-only:** Amplify Hosting adds a managed
+build step the project doesn't need (the SPA build is already
+`pnpm --filter web build:prod-aws`); S3-only (no CloudFront) forces
+either a public bucket (anti-pattern) or a signed-URL-per-asset
+scheme (heavy). CloudFront + OAC is the AWS-recommended static-site
+shape and gives HTTPS on `*.cloudfront.net` for free.
+
+### 16.2 Opt-in: provision the web client
+
+The web client is **opt-in**. To provision it, pass `webSite` props
+on the stack. From CDK context (the easiest path), set
+`webSiteCustomDomain`:
+
+```bash
+pnpm deploy:aws -- \
+  -c webSiteCustomDomain=app.example.com \
+  -c webSiteCertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abc-def-... \
+  -c webSiteHostedZoneName=example.com. \
+  -c webSiteHostedZoneId=Z2KVMGOMGMOU2
+```
+
+The ACM certificate **must** be in `us-east-1` (CloudFront requirement).
+Hosted-zone name + ID are both required because CDK's
+`fromHostedZoneAttributes` needs both; retrieve them once via
+`aws route53 list-hosted-zones-by-name --dns-name <zone>`.
+
+> **Default-`*.cloudfront.net` only (no custom domain) gap:**
+> `bin/aws.ts` currently keys the `webSite` prop's existence on
+> `webSiteCustomDomain` being set, so provisioning the construct
+> without a custom domain requires editing `bin/aws.ts` to pass
+> `webSite: {}` directly. Tracked as a follow-up. For v1 deploys,
+> supply a custom domain (prod-style) or patch `bin/aws.ts`.
+
+### 16.3 Two-phase deploy (stack → bake → s3 sync → invalidate)
+
+Unlike the CF Worker (where `wrangler deploy` ships the SPA in the
+same command as the runtime), the AWS SPA deploy is **two-phase** and
+**stack-output-driven**: the CloudFormation stack must exist before
+the SPA can be baked, because the baked `config.json` carries the
+API Gateway WebSocket URL as a literal. The deploy pipeline
+(`scripts/deploy-web-aws.mjs`) runs:
+
+1. `aws cloudformation describe-stacks --stack-name IrcAwsStack`
+   reads the `ConnectUrl`, `WebsiteBucketName`, and
+   `WebsiteDistributionId` outputs. If any are missing the script
+   exits non-zero ("stack not deployed" or "web client construct not
+   provisioned").
+2. `pnpm --filter @serverless-ircd/web run build:prod-aws -- --api-url <ConnectUrl>`
+   bakes the SPA with the real API Gateway URL. The `--api-url` flag is
+   overridden **in memory** after Zod parse — the source
+   `apps/web/static/config.prod-aws.json` is never mutated, so the
+   templated `{{API_ID}}.execute-api.{{REGION}}.amazonaws.com` host and
+   `/{{STAGE}}` path placeholders stay in the repo and no concrete URL
+   is committed. The build rejects any leftover `{{...}}` placeholders.
+
+   The flag value (`wss://<id>.execute-api.<region>.amazonaws.com/<stage>`)
+   is **split** by `parseApiUrlForKiwi` into Kiwi's two URL fields:
+   `server` ← `<id>.execute-api.<region>.amazonaws.com` (hostname only,
+   no scheme) and `direct_path` ← `/<stage>`. irc-framework builds the
+   WS URL itself as `wss://<server>:<port><direct_path>` — it prepends
+   `wss://` whenever `tls: true`, so passing the full URL through to
+   `server` would double the scheme (`wss://wss//<host>...`) and Firefox
+   would reject the connection. The split keeps `server` host-only and
+   routes the API Gateway stage name through `direct_path`.
+3. `aws s3 sync apps/web/dist s3://<WebsiteBucketName> --delete`
+   uploads the build. The CLI skips unchanged objects via etag
+   comparison, so a re-deploy with no SPA changes uploads nothing.
+   (This is why the deploy uses the AWS CLI rather than the SDK —
+   `s3 sync`'s etag-based unchanged-skip is non-trivial to reproduce
+   on `@aws-sdk/client-s3`.)
+4. `aws cloudfront create-invalidation --distribution-id <WebsiteDistributionId> --paths /*`
+   busts the edge cache so the next visitor gets the new build.
+
+**CI wiring:** the `deploy-web` job in `.github/workflows/deploy-aws.yml`
+runs `node scripts/deploy-web-aws.mjs` with `needs: deploy` (after the
+CDK stack applies). Both jobs are `workflow_dispatch`-only — a
+maintainer runs the workflow by hand (T170 collapsed the staging/prod
+split; there is no push trigger and no `staging` branch).
+
+**Why a script instead of CDK `BucketDeployment`:** `BucketDeployment`
+re-synths on every deploy, is slower, and — critically — cannot bake
+a post-deploy stack output (the API Gateway URL) into the SPA config,
+because at synth time the URL does not exist yet. The two-phase
+script reads the output, then bakes.
+
+### 16.4 CSWSH defence (`WEB_ORIGINS`) — mandatory once the SPA ships
+
+**Once you deploy the web client, set `WEB_ORIGINS`.** WebSocket
+upgrades do not follow the same-origin policy, so a malicious web
+page can otherwise open a wss to the IRC endpoint from a victim's
+browser and drive the session with the victim's credentials
+(Cross-Site WebSocket Hijacking, CSWSH). API Gateway WebSocket has
+no built-in Origin validation — the `$connect` Lambda enforces it.
+
+Pass the SPA's origin alongside the `webSite` props:
+
+```bash
+pnpm deploy:aws -- \
+  -c webSiteCustomDomain=app.example.com \
+  -c webSiteCertificateArn=... \
+  -c webSiteHostedZoneName=example.com. \
+  -c webSiteHostedZoneId=... \
+  -c webOrigins=https://app.example.com
+```
+
+The full behaviour matrix, matching semantics, and the deliberate
+divergence from the CF Worker policy (no same-origin auto-derive on
+AWS — the SPA and the wss endpoint are on different origins) are in
+**§8.2**. Unset `WEB_ORIGINS` disables the check; this is why the
+defence is documented as "mandatory-once-the-SPA-ships" rather than
+"mandatory always" — bare-IRC deployments without a web frontend
+(`curl`, WeeChat, `tcp-ws-forwarder`) never send `Origin` and are
+correctly served without the knob.
+
+### 16.5 CF-vs-AWS: one origin vs two origins
+
+The architectural difference is the reason this § exists:
+
+| Platform | HTTP (SPA) origin               | WebSocket origin                  | Same-origin? |
+|----------|---------------------------------|-----------------------------------|--------------|
+| CF       | the Worker (`*.workers.dev` / custom domain) | the same Worker        | **Yes** — one domain serves both |
+| AWS      | CloudFront (`*.cloudfront.net` / custom domain) | API Gateway (`*.execute-api.*.amazonaws.com`) | **No** — two different endpoints |
+
+Two practical consequences:
+
+1. **The baked SPA config (`config.prod-aws.json`) carries a templated
+   host + stage path** because the browser cannot infer either from
+   `window.location`. The CF config (`config.prod.json`) uses Kiwi's
+   `{{hostname}}` template resolved at load time and no `direct_path`
+   (the Worker's WS upgrade is at root). The AWS config templates
+   `server` = `{{API_ID}}.execute-api.{{REGION}}.amazonaws.com` (host
+   only — irc-framework prepends `wss://` from `tls: true`) and
+   `direct_path` = `/{{STAGE}}` (the API Gateway stage segment). The
+   AWS deploy pipeline splits the stack-output URL into these two
+   fields at bake time (§16.3 step 2).
+2. **The CF Worker's CSWSH defence has a same-origin auto-derive
+   mode** (when `WEB_ORIGINS` is unset, compare `Origin` against the
+   request's own `Host`). AWS cannot use auto-derive — the request's
+   own host is the API Gateway domain, never the SPA's — so the AWS
+   defence is explicit-allowlist only (§8.2).
+
+### 16.6 Custom domain (ACM + CloudFront alias + Route53)
+
+`StaticSite` accepts four optional props for the custom domain (see
+`apps/aws-stack/src/static-site.ts`):
+
+| Prop              | Purpose                                                              |
+|-------------------|----------------------------------------------------------------------|
+| `customDomain`    | The hostname to serve the SPA on (e.g. `app.example.com`).           |
+| `certificateArn`  | ARN of an ACM certificate covering `customDomain`. Must be in `us-east-1`. |
+| `hostedZoneName`  | Public Route53 hosted zone name (e.g. `example.com.`).               |
+| `hostedZoneId`    | Public Route53 hosted zone ID for the above.                         |
+
+When all four are supplied (the CDK context wiring in `bin/aws.ts`
+handles the optional spread), the construct adds the alias to the
+CloudFront distribution and creates a Route53 `ARecord` aliasing the
+distribution. When `customDomain` is omitted, the distribution serves
+on its default `*.cloudfront.net` URL — but see the gap note in
+§16.2 (the current `bin/aws.ts` wiring only provisions the construct
+at all when `webSiteCustomDomain` is set).
+
+ACM certificate validation: the certificate must be DNS-validated
+and in `ISSUED` status before `cdk deploy` runs — CloudFront will
+not deploy an alias to a pending certificate. Create it ahead of time
+in `us-east-1` via the console or:
+
+```bash
+aws acm request-certificate \
+  --domain-name app.example.com \
+  --validation-method DNS \
+  --region us-east-1
+# add the returned CNAME to Route53, wait for ISSUED
+```
+
+### 16.7 Verification (manual smoke check)
+
+After a `deploy-web` job completes:
+
+```bash
+# Stack outputs
+aws cloudformation describe-stacks --stack-name IrcAwsStack \
+  --query 'Stacks[0].Outputs[?OutputKey==`WebsiteURL`].OutputValue' --output text
+
+# Landing page
+curl -sI https://<distribution-or-custom-domain>/ | head -1
+# Landing page (the project front door — links to SPA + docs + source repo)
+curl -sI https://<distribution-or-custom-domain>/ | head -1
+# SPA shell (200, served via the 404→/webclient/index.html error mapping for /webclient/* routes)
+curl -sI https://<distribution-or-custom-domain>/webclient/ | head -1
+# Baked config — server MUST be the real wss URL, not a {{...}} template
+curl -s https://<distribution-or-custom-domain>/webclient/static/config.json | jq .startupOptions.server
+```
+
+Open `https://<distribution-or-custom-domain>/webclient/` in a browser,
+register, join `#welcome`, send a `PRIVMSG`, see the echo. (Visiting the
+root `https://<distribution-or-custom-domain>/` serves the landing page,
+which links to the SPA at `/webclient/`.) If the SPA loads but never
+connects, check (1) the baked `config.json` `server` matches the stack's
+`ConnectUrl` output, (2) `WEB_ORIGINS` (§16.4) includes the CloudFront
+origin you're loading the SPA from, and (3) the `$connect` route is
+reachable.
+
+---
+
+## 17. OIDC deploy role (CI)
+
+The GitHub Actions deploy workflow (§12) accepts **only** GitHub OIDC
+web-identity credentials. Long-lived access keys
+(`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`) are NOT supported — a
+single exfiltration vector against them (rogue PR `printenv`,
+compromised third-party Action, poisoned runner) yields full AWS
+account takeover because the deploy role can manage CloudFormation,
+IAM, Lambda, and DynamoDB. This section documents the operator-side
+setup that the `AWS_DEPLOY_ROLE_ARN` repo secret points at.
+
+### 17.1 One-time AWS account setup
+
+1. **Create the GitHub OIDC identity provider** (one per AWS account,
+   idempotent):
+
+   ```bash
+   aws iam create-open-id-connect-provider \
+     --url https://token.actions.githubusercontent.com \
+     --client-id-list sts.amazonaws.com \
+     --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1 \
+     --tags Key=managed-by,Value=github-actions
+   ```
+
+   > The `--thumbprint-list` above is the well-known root CA
+   > thumbprint GitHub's OIDC tokens chain to. AWS now also accepts
+   > the trust-root automatically, but specifying it keeps the
+   > provider deterministic across accounts.
+
+2. **Create the deploy role** with the trust policy below (save as
+   `trust-policy.json` then `create-role`). The single condition key
+   binds the role to this repository's `main` branch — the only ref
+   the `workflow_dispatch` deploy workflow can run from:
+
+   ```json
+   {
+     "Version": "2012-10-17",
+     "Statement": [
+       {
+         "Effect": "Allow",
+         "Principal": {
+           "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
+         },
+         "Action": "sts:AssumeRoleWithWebIdentity",
+         "Condition": {
+           "StringEquals": {
+             "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
+             "token.actions.githubusercontent.com:sub": "repo:<owner>/<repo>:ref:refs/heads/main"
+           }
+         }
+       }
+     ]
+   }
+   ```
+
+   Replace `<ACCOUNT_ID>` with the AWS account id and `<owner>/<repo>`
+   with the GitHub owner/repo (e.g. `ServerlessIRCd/ServerlessIRCd`).
+   The `sub` condition is the security boundary: only workflows
+   running on a ref matching `refs/heads/main` in this exact repo can
+   assume the role. Do NOT widen it to `StringLike` with a wildcard —
+   that lets forked PRs mint credentials.
+
+   ```bash
+   aws iam create-role \
+     --role-name IrcDeployRole \
+     --assume-role-policy-document file://trust-policy.json \
+     --description "GitHub Actions OIDC role for IrcAwsStack deploys"
+
+   # Note the returned ARN — this becomes AWS_DEPLOY_ROLE_ARN.
+   aws iam get-role --role-name IrcDeployRole --query 'Role.Arn' --output text
+   ```
+
+3. **Attach a permission policy.** The role needs the same surface
+   `cdk deploy` uses: IAM (pass-role + role creation), API Gateway v2,
+   Lambda, DynamoDB, EventBridge, CloudFormation, S3 (the CDK
+   bootstrap bucket), and logs. The CDK bootstrap already creates a
+   `cdk-hnb659fds-deploy-role-<account>-<region>` role with the right
+   shape — for a v1 deployment, the simplest pattern is to let the
+   GitHub-OIDC role `sts:AssumeRole` the CDK deploy role:
+
+   ```json
+   {
+     "Version": "2012-10-17",
+     "Statement": [
+       {
+         "Effect": "Allow",
+         "Action": "sts:AssumeRole",
+         "Resource": "arn:aws:iam::<ACCOUNT_ID>:role/cdk-hnb659fds-deploy-role-<ACCOUNT_ID>-<REGION>"
+       }
+     ]
+   }
+   ```
+
+   Attach this as an inline policy on `IrcDeployRole`. (If you would
+   rather grant the deploy permissions directly on `IrcDeployRole`,
+   mirror the statement list from the CDK deploy role's
+   `DefaultDeploymentRole`.)
+
+4. **Store the role ARN as the `AWS_DEPLOY_ROLE_ARN` repo secret**
+   (Settings → Secrets and variables → Actions → New repository
+   secret). This is the **only** AWS-shaped secret the workflow reads.
+
+### 17.2 Condition key reference
+
+| JWT claim (`token.actions.githubusercontent.com:<key>`) | Value to bind                                              | Meaning                                                              |
+|---------------------------------------------------------|------------------------------------------------------------|----------------------------------------------------------------------|
+| `aud`                                                   | `sts.amazonaws.com`                                        | Required. AWS is the intended audience of the OIDC token.            |
+| `sub`                                                   | `repo:<owner>/<repo>:ref:refs/heads/main`                  | Required. Pinning to `main` matches the `workflow_dispatch` trigger. |
+
+The workflow's `on:` block is `workflow_dispatch` only, and a
+maintainer runs it from the `main` branch in the GitHub UI, so the
+`sub` claim always carries `:ref:refs/heads/main`. If you later add a
+push trigger on another branch, add a second condition entry rather
+than loosening this one.
+
+### 17.3 CI verification (operator-run, out-of-band)
+
+Once the role and secret are configured, verify end-to-end by running
+the workflow from the Actions UI against a sandbox account. The
+workflow's `Assert assumed role matches AWS_DEPLOY_ROLE_ARN` step
+prints the assumed role-name + account on success:
+
+```
+OIDC role assertion passed: IrcDeployRole in account 111122223333
+```
+
+If that step fails, the trust policy condition keys do not match the
+workflow's `sub` claim — re-check `repo:<owner>/<repo>` and the branch
+ref. The workflow aborts BEFORE `cdk deploy`, so a misconfigured trust
+policy cannot mutate the stack.
+
+Authoritative reference: GitHub's "Configuring OpenID Connect in
+Amazon Web Services" guide
+(<https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services>)
+and the AWS "Creating OpenID Connect (OIDC) identity providers" guide
+walk through the IAM-side setup in more detail.
+
+### 17.4 What the workflow enforces in-repo
+
+The CI-hardening test suite (`tools/ci-hardening/tests/deploy-aws-oidc.test.ts`)
+asserts the workflow shape so the security property cannot regress
+silently:
+
+- No `aws-access-key-id` / `aws-secret-access-key` inputs to
+  `configure-aws-credentials@v4` anywhere in the file.
+- Top-level `permissions:` block grants exactly
+  `{ id-token: write, contents: read }` (least-privilege).
+- Every `configure-aws-credentials` step has a `role-to-assume` input.
+- The `deploy` and `deploy-web` jobs both have an
+  `if: env.AWS_DEPLOY_ROLE_ARN == ''` guard that runs `exit 1` before
+  any AWS call.
+- The `deploy` job runs `aws sts get-caller-identity` and references
+  `AWS_DEPLOY_ROLE_ARN` before any `cdk deploy` (defence-in-depth
+  against silent OIDC fallback).
+
+The `deploy-web` job (TICKET-167, §16) inherits the same OIDC model:
+it has its own empty-ARN guard before `configure-aws-credentials` and
+assumes the same role via web identity — no static keys, no ambient
+credential inheritance from the parent `deploy` job. The two jobs are
+independent `workflow_dispatch` runs against the same role ARN.
+
+---
+
+## 18. Open questions / future work
 
 These are facts the **code does not yet have an answer for**; the
 recommendations above are deployer guidance, not built-in knobs: