serverless-ircd 0.8.0 → 0.10.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,25 +365,18 @@ 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
@@ -381,6 +390,12 @@ For a real production deployment, before your first `pnpm deploy:aws:prod`:
    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 +433,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.'],
@@ -493,18 +507,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 +546,46 @@ 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.
 
 ---
 
@@ -599,7 +660,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 +671,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 +688,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 +702,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                                                              |
@@ -819,9 +946,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
@@ -922,10 +1050,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 +1064,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.
+
+### 12.3 OIDC is mandatory
 
-The workflow supports both auth modes:
+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 +1164,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 +1183,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 +1232,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 +1393,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 +1426,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: