serverless-ircd 0.5.0 → 0.7.0

package/docs/WebClientGuide.md

@@ -0,0 +1,535 @@
+# Web Client Guide
+
+End-to-end contributor/operator doc for the ServerlessIRCd web client: a
+vendored **Kiwi IRC** SPA served at `/app/` and a static project landing
+page served at `/` by the Cloudflare Worker. The browser opens a native
+`wss://` WebSocket straight to the Worker's existing IRC-over-WebSocket
+endpoint — no proxy, gateway, or transport adaptation in the hot path.
+
+Cross-reference: `PLAN.md` §6.1 (CF mapping), `docs/PlanWebClient.md`
+(design), `docs/Cloudflare-Deployment-Guide.md` (Worker deploy),
+`apps/cf-worker/wrangler.toml`, `apps/web/`.
+
+**Acceptance criterion (TICKET-139):** a new contributor can
+`git submodule update --init`, `pnpm install`,
+`pnpm --filter web build:staging`, and `wrangler deploy --env staging`
+following only this doc.
+
+---
+
+## 1. How the pieces fit
+
+```
+   ┌──────────────────────────────────────────────────────────────┐
+   │  Browser                                                     │
+   │    GET /            → landing page (project front door)      │
+   │    GET /app/        → Kiwi IRC SPA (index.html + JS bundle)  │
+   │    wss://.../       → one IRC message per WS text frame      │
+   └──────────────────────────────────────────────────────────────┘
+           │                                │
+           │ HTTPS (static assets)          │ wss (IRC-over-WebSocket)
+           ▼                                ▼
+   ┌──────────────────────────────────────────────────────────────┐
+   │  apps/cf-worker  (Cloudflare Worker)                         │
+   │    fetch(request, env):                                      │
+   │      Upgrade: websocket → Origin check → ConnectionDO       │
+   │      GET /health         → plaintext liveness string         │
+   │      else                → env.ASSETS (apps/web/dist)        │
+   └──────────────────────────────────────────────────────────────┘
+```
+
+The Worker is the single origin for the landing page, the SPA, **and**
+the WebSocket. Same-origin by default — which is what makes the CSWSH
+defense in §5 almost zero-config. A Cloudflare Pages deployment of the
+same `dist/` is a documented alternative for prod (see §7).
+
+Path layout on the Worker:
+
+| Path       | Served by                | Content                          |
+|------------|--------------------------|----------------------------------|
+| `/`        | `[assets]` binding       | `dist/index.html` (landing page) |
+| `/app/`    | `[assets]` binding       | `dist/app/index.html` (Kiwi SPA) |
+| `/app/static/...` | `[assets]` binding | Kiwi JS/CSS/themes + baked config |
+| `/health`  | `worker.ts` handler      | Plaintext liveness string        |
+| `/` (WS upgrade) | `worker.ts` → `ConnectionDO` | IRC session               |
+
+The WS endpoint and the landing page share path `/`. The Worker runs
+first for every request (`run_worker_first = true` in `wrangler.toml`)
+so the `Upgrade: websocket` check fires before the asset platform
+serves `/` — otherwise an upgrade would get a `200 OK` landing page
+instead of a `101` switch.
+
+---
+
+## 2. Prerequisites
+
+| Requirement | Version / detail |
+|---|---|
+| Node.js | ≥ 24 (matches CI; `engines.node` in root `package.json`) |
+| pnpm | 11.x (`packageManager` pin in root `package.json`) |
+| yarn | Required **only** to build the SPA. Kiwi ships a `yarn.lock`; `corepack enable` provides yarn on any Node. |
+| `wrangler` CLI | Comes from `apps/cf-worker/devDependencies`; no global install needed. |
+| Cloudflare account | For deploy only (see `docs/Cloudflare-Deployment-Guide.md`). Local dev needs nothing. |
+
+Confirm the local environment:
+
+```bash
+node --version          # v24.x or newer
+corepack enable         # lets the pinned pnpm + yarn run
+pnpm --version          # 11.x
+```
+
+---
+
+## 3. Quickstart (clean checkout → deployed staging SPA)
+
+```bash
+# 1. Pull submodules (docs wiki + Kiwi IRC upstream sources).
+git submodule update --init
+
+# 2. Install workspace deps.
+pnpm install
+
+# 3. Build the SPA + landing page (default config = staging target).
+pnpm --filter web build:staging
+#    Equivalent: pnpm --filter @serverless-ircd/web build:staging
+#    → apps/web/dist/index.html        (landing page)
+#    → apps/web/dist/app/index.html    (Kiwi SPA)
+#    → apps/web/dist/app/static/config.json  (baked, env-specific)
+
+# 4. Build the rest of the workspace (Worker imports compiled dist/).
+pnpm build
+
+# 5. Serve everything locally (Worker + SPA + landing page).
+pnpm --filter @serverless-ircd/cf-worker dev
+#    → http://localhost:8787/      landing page
+#    → http://localhost:8787/app/  Kiwi SPA
+#    → ws://localhost:8787/        IRC-over-WebSocket (same endpoint)
+
+# 6. Deploy staging (Worker + assets in one command).
+pnpm deploy:cf:staging
+#    → wrangler deploy --env staging
+```
+
+Open `http://localhost:8787/app/` in a browser — Kiwi boots, reads
+`/app/static/config.json`, and opens a `wss://` (or `ws://` in local
+dev) connection to the same origin.
+
+> **Forgot the submodule?** `apps/web/scripts/build.mjs` fails fast:
+> `Kiwi upstream missing at .../upstream. Run
+> 'git submodule update --init apps/web/upstream' first.`
+
+---
+
+## 4. The build pipeline (`apps/web/scripts/build.mjs`)
+
+The build is an orchestrated layering over the upstream Kiwi build —
+**we own no IRC logic**, only config + asset placement.
+
+### 4.1 Per-environment config matrix
+
+| `pnpm ...` command | Reads | Bakes into `dist/app/static/config.json` |
+|---|---|---|
+| `--filter web build` | `static/config.json` | default (staging-shaped) config |
+| `--filter web build:staging` | `static/config.staging.json` | staging config |
+| `--filter web build:prod` | `static/config.prod.json` | prod config |
+
+`--env` is parsed by `src/build-env.ts`; an unknown value aborts the
+build with a readable error. The selected file is validated against the
+Zod schema (`src/config-schema.ts`) **before** it is baked, so a
+malformed config fails the build rather than shipping a broken SPA.
+
+### 4.2 What the build does, in order
+
+1. **Verify the submodule** exists (`upstream/`), or fail with the
+   hint quoted above.
+2. **`yarn install --frozen-lockfile`** inside `upstream/` (only if
+   `upstream/node_modules` is missing). `COREPACK_ROOT` is set so yarn
+   classic doesn't refuse on the pnpm-managed workspace root. On
+   Node ≥ 17 the OpenSSL legacy provider is enabled for webpack 5's md4
+   hashing.
+3. **Patch `upstream/vue.config.js`** `publicPath: ''` →
+   `publicPath: '/app/'`, run `yarn build`, then **restore** the file
+   in `finally` so the submodule stays clean. This is why every hashed
+   asset URL comes out `/app/static/js/app.<hash>.js` instead of
+   `static/js/...`, which would 404 at root.
+4. **Copy `upstream/dist/` → `apps/web/dist/app/`.**
+5. **Rewrite bare `static/...` refs** in the baked `index.html` (e.g.
+   the favicon, which webpack doesn't run through `publicPath`) to
+   `/app/static/...`.
+6. **Validate + bake the per-env config**: read
+   `static/config.<env>.json`, run `parseKiwiConfig`, re-serialise
+   (stable key order), write to `dist/app/static/config.json`.
+7. **Copy the landing page** `landing/index.html` → `dist/index.html`.
+
+Output is reproducible: same checkout + same `--env` → byte-identical
+`dist/` (modulo upstream webpack hash stability).
+
+### 4.3 The config schema (`src/config-schema.ts`)
+
+The schema models only the fields ServerlessIRCd cares about; the rest
+of Kiwi's surface is passed through untouched (`.passthrough()`).
+
+```jsonc
+// static/config.staging.json
+{
+  "windowTitle": "ServerlessIRCd (staging)",
+  "startupOptions": {
+    "server": "{{hostname}}",   // resolved to window.location.hostname at boot
+    "direct": true,             // MUST be true — direct WS, no kiwiServer gateway
+    "tls": true,                // MUST be true — wss:// (page is HTTPS)
+    "port": 443,
+    "channel": "#welcome",
+    "nick": "Guest"
+  }
+}
+```
+
+Field notes (see the schema docstrings for the full rationale):
+
+- **`startupOptions.server`** — `{{hostname}}` (or `{{host}}` to keep
+  a non-default port) is a Kiwi template resolved by the browser to
+  `window.location.hostname` at load time. This is what lets one build
+  artifact target staging, prod, preview, and PR deploys without a
+  per-env hostname. A literal hostname is also accepted.
+- **`startupOptions.direct`** — MUST be `true`. ServerlessIRCd is a
+  direct IRC-over-WebSocket server; the Kiwi default (`false`) routes
+  through a `kiwiServer` WebIRC gateway that nothing serves here.
+- **`startupOptions.tls`** — MUST be `true` in any HTTPS deployment
+  (browsers refuse `ws://` on an HTTPS page).
+- **`startupOptions.direct_path`** — the WS path. Kiwi reads
+  `direct_path` (NOT `path`); the Worker exposes its WS upgrade at
+  root, so this MUST be `/` if supplied. Optional — when omitted,
+  irc-framework builds `wss://host:port` (no path), which the browser
+  normalises to `wss://host:port/`.
+- **`startupOptions.channel`** — must begin with `#` (matches
+  `CHANTYPES=#`); comma-separated lists are accepted.
+
+A malformed config aborts the build with an aggregated error, e.g.:
+
+```
+config.staging.json: Invalid Kiwi web config:
+  - startupOptions.port: port must be a valid TCP port (1-65535)
+  - startupOptions.channel: must begin with '#'
+```
+
+### 4.4 Tests
+
+```bash
+pnpm --filter web test         # schema + build-env + workspace tests
+pnpm --filter web typecheck
+```
+
+The schema and build-env tests are pure (no Kiwi build needed). The
+build-smoke tests (`tests/build-smoke.test.ts`) assert the **landing
+page** source unconditionally and the `dist/` output only when a build
+is present (`describe.skipIf(!built)`) — the Kiwi build is too heavy
+for the unit suite, so run `pnpm --filter web build` first to exercise
+those assertions.
+
+---
+
+## 5. CSWSH defense and the `WEB_ORIGINS` var
+
+WebSocket upgrades do **not** follow the same-origin policy. A
+malicious page can `new WebSocket('wss://irc.example.com/')` from the
+victim's browser and drive an IRC session with the victim's
+credentials (Cross-Site WebSocket Hijacking, CSWSH). The Worker
+rejects upgrades whose `Origin` is not allowed — see
+`apps/cf-worker/src/origin-allowlist.ts`.
+
+### 5.1 Two enforcement modes (evaluated in order)
+
+1. **Explicit allowlist** — when `WEB_ORIGINS` is set, only listed
+   origins proceed. Use this for cross-origin deployments (SPA on a
+   different domain than the Worker).
+2. **Auto-derive (same-origin)** — when `WEB_ORIGINS` is unset/empty
+   (the default), the Worker compares the browser's `Origin` against
+   the request's own origin (`${protocol}//${host}`). If they match,
+   the page opening the WS is the same origin as the server → safe.
+
+Non-browser clients (curl, WeeChat, the `tcp-ws-forwarder`, scripted
+test harnesses) never send `Origin`; their upgrades pass through
+unchanged in **both** modes, so existing tooling keeps working.
+
+### 5.2 `WEB_ORIGINS` is optional
+
+Because mode 2 (same-origin auto-derive) is the default and requires
+zero per-env configuration, **`WEB_ORIGINS` is optional**. Most
+deployments never need to set it: the SPA and the Worker are on the
+same origin, so the auto-derive check passes for every browser and
+rejects every cross-origin attempt. It works for `*.workers.dev`,
+custom domains, and preview URLs alike.
+
+Set `WEB_ORIGINS` only when the SPA is served from a **different**
+origin than the Worker (e.g. a Cloudflare Pages deployment — see §7 —
+or a separate static host). It is a comma-separated list of origins,
+lowercased and whitespace-trimmed:
+
+```toml
+# apps/cf-worker/wrangler.toml — cross-origin example
+[vars]
+WEB_ORIGINS = "https://irc.example.com,https://web.example.com"
+```
+
+```bash
+# or per-deploy via the secret store / dashboard env vars:
+wrangler secret put WEB_ORIGINS --env staging
+```
+
+### 5.3 Responses
+
+| Scenario | Response |
+|---|---|
+| `Origin` allowed (allowlist or same-origin) | `101 Switching Protocols` → `ConnectionDO` |
+| `Origin` header absent (non-browser client) | `101` (unchanged) |
+| `Origin` present but not allowed | `403 Forbidden` (`WebSocket upgrade refused: the request Origin is not allowed.`) |
+| No allowlist AND `Host` undeterminable | `403 Forbidden` (defensive fail-closed; does not fire on Cloudflare, which always sets `Host`) |
+
+The 403 path is unit-tested in `apps/cf-worker/tests/ws-origin.test.ts`
+and the pure policy in `origin-allowlist.test.ts`. There is no
+fail-open path.
+
+---
+
+## 6. Local development
+
+### 6.1 Serve the SPA from the Worker (`wrangler dev`)
+
+This is the canonical local loop — same-origin, real `workerd`, real
+Durable Objects:
+
+```bash
+pnpm --filter web build          # build the SPA + landing page
+pnpm build                       # build the rest of the workspace
+pnpm --filter @serverless-ircd/cf-worker dev
+```
+
+Then:
+
+- `http://localhost:8787/` — landing page.
+- `http://localhost:8787/app/` — Kiwi SPA (reads
+  `/app/static/config.json`, opens `ws://localhost:8787/`).
+- `http://localhost:8787/health` — plaintext liveness.
+
+Smoke the WS path directly (no browser needed):
+
+```bash
+node apps/cf-worker/scripts/smoke.mjs
+# → replays CONNECT/NICK/USER/JOIN/PRIVMSG/QUIT, asserts 001/376/353/366
+```
+
+### 6.2 Iterate on the SPA config without rebuilding Kiwi
+
+The Kiwi upstream build is the slow step. For a config-only change,
+edit `static/config.staging.json`, then re-run
+`pnpm --filter web build:staging` — step 2 of the build reuses
+`upstream/node_modules` and skips straight to re-baking the config
+(steps 4–6 are fast).
+
+### 6.3 Iterate on the landing page
+
+`landing/index.html` is pure static HTML + inline CSS, no JavaScript,
+no build step. Edit it and re-run the build (it is copied verbatim to
+`dist/index.html`); or just preview it directly in a browser — it has
+no runtime dependencies.
+
+---
+
+## 7. Optional: Cloudflare Pages instead of Worker assets
+
+The build output (`apps/web/dist/`) is identical for both hosting
+options; the choice is a deploy-time knob, not a build-time one. Use
+Pages when you want to decouple static deploys from Worker deploys
+(e.g. the frontend changes more often than the IRCd), or when prod
+favors a dedicated static edge.
+
+### 7.1 Set up Pages
+
+1. Push the repo (or just `apps/web/dist/`) to a Pages-connected
+   branch, or use `wrangler pages deploy apps/web/dist`.
+2. Set the Pages project's output directory to `apps/web/dist` and the
+   build command to `pnpm --filter web build:prod` (plus `pnpm build`
+   if the Worker is deployed from the same repo).
+3. The Pages project is reachable at
+   `https://<project>.pages.dev` (or a custom domain).
+
+### 7.2 Allow the Pages origin on the Worker
+
+Because the SPA is now on a **different** origin than the Worker, the
+same-origin auto-derive (§5.1 mode 2) will reject the browser's WS
+upgrade. Set `WEB_ORIGINS` on the Worker to the Pages origin:
+
+```toml
+# apps/cf-worker/wrangler.toml
+[vars]
+WEB_ORIGINS = "https://<project>.pages.dev"
+```
+
+The SPA config's `startupOptions.server` still resolves to the
+**Worker's** hostname (where the WS endpoint lives), not the Pages
+hostname — so set it to a literal if you've pinned it, or keep
+`{{hostname}}` only if Pages and the Worker share a domain.
+
+---
+
+## 8. Optional: `webircgateway` SockJS fallback
+
+ServerlessIRCd already speaks the wire format browser Kiwi expects:
+native WebSocket text frames, one IRC message per frame, with
+`\r\n`-joined-frame tolerance. The Worker's WS endpoint at `/` is all
+Kiwi needs. **You do not need `webircgateway` for normal operation.**
+
+When is it useful? Corporate proxies and some mobile carriers block
+raw `wss://` (or upgrade it in ways that break long-lived frames).
+`webircgateway` provides a SockJS + Kiwi multi-server transport that
+falls back to HTTP polling when raw WS is unavailable. If your users
+report "can't connect from the office Wi-Fi", that's the trigger.
+
+The gateway is vendored separately (see the `webircgateway/` submodule
+if present in your checkout). Running it as a sidecar is a deployment
+concern outside this doc's scope; the key point is that it is
+**strictly opt-in**. The default SPA build does not reference it, and
+no `kiwiServer` / gateway URL is baked into the config.
+
+To wire it up when needed, point Kiwi's `startupOptions.kiwiServer`
+at the gateway and set `startupOptions.direct: false` — the opposite
+of the ServerlessIRCd default. Document this only for the affected
+deployment; don't change the default config.
+
+---
+
+## 9. Customising the landing page
+
+The landing page (`apps/web/landing/index.html`) is the project's front
+door: a visitor hitting `/` learns what ServerlessIRCd is and clicks
+through to `/app/` to launch the client. It is intentionally
+framework-free (pure HTML + inline CSS, no JS) so it renders without
+JavaScript and costs nothing to serve.
+
+To customise:
+
+- **Copy/branding** — edit the `<header>`, `<main>`, and `<footer>`
+  blocks directly. The CSS variables at the top of the `<style>` block
+  (`--bg`, `--surface`, `--accent`, …) theme the whole page in one
+  place.
+- **Links** — the page links to `/app/` (the SPA), `docs/`, and the
+  source repo. Update the repo URLs and the docs path to match your
+  deployment.
+- **Accessibility** — keep the declared viewport meta tag and the
+  no-`<script>` invariant; both are asserted by
+  `tests/build-smoke.test.ts`. The build copies the file verbatim to
+  `dist/index.html`, so what you author is exactly what is served.
+
+Re-run `pnpm --filter web build` (any `--env`) after edits; the build
+test suite will fail loudly if you accidentally remove the `/app/`
+link, the docs link, or the viewport tag.
+
+---
+
+## 10. Troubleshooting
+
+### 10.1 `Kiwi upstream missing at .../upstream`
+
+The submodule wasn't initialised. Run:
+
+```bash
+git submodule update --init apps/web/upstream
+```
+
+The build fails fast with this hint rather than a confusing webpack
+error.
+
+### 10.2 SPA loads but never connects ("connection refused" / spinning)
+
+Almost always a config issue. Open the browser devtools Network tab
+and check the WS upgrade:
+
+- **`ws://` on an HTTPS page** — `startupOptions.tls` must be `true`
+  (browsers refuse insecure WS from secure pages). The default configs
+  set it; a hand-edited config may not.
+- **`direct: false`** — Kiwi is probing a `kiwiServer` gateway that
+  nothing serves. `startupOptions.direct` MUST be `true`.
+- **Wrong server** — if you pinned a literal `server`, it must be the
+  Worker's hostname. `{{hostname}}` resolves to
+  `window.location.hostname` and is the safest default.
+- **403 on upgrade** — the `Origin` was rejected (§5). Check
+  `WEB_ORIGINS` if you're cross-origin, or confirm the SPA and Worker
+  are same-origin.
+
+### 10.3 Asset 404s at `/static/...` (instead of `/app/static/...`)
+
+The `publicPath` patch in step 3 of the build didn't take. Confirm
+`upstream/vue.config.js` still contains a `publicPath: ''` literal to
+patch against (the build restores it after building). If upstream
+changed the phrasing, the patch regex in `scripts/build.mjs` needs an
+update.
+
+### 10.4 `200 OK` instead of `101 Switching Protocols` on WS upgrade
+
+The asset platform served the landing page for the upgrade request.
+This means `run_worker_first = true` is missing or false in the
+`[assets]` block of `wrangler.toml`. The WS endpoint and the landing
+page share path `/`, so the Worker MUST run first for everything and
+fall through to assets only for non-WS requests.
+
+### 10.5 `Cannot find module '@serverless-ircd/cf-adapter'`
+
+The workspace packages weren't built. Run `pnpm build` from the repo
+root before `pnpm --filter web build` or `wrangler dev` — the build
+script and the Worker entry import compiled `dist/` from the workspace
+packages.
+
+### 10.6 Build-smoke tests fail in CI but pass locally
+
+The `dist/`-dependent assertions in `tests/build-smoke.test.ts` are
+gated on `existsSync(dist/app/index.html)` and are skipped when the
+SPA hasn't been built. CI runs `pnpm --filter web build` (or
+`pnpm build`) before `pnpm --filter web test`, so the assertions fire
+there. If you run `pnpm --filter web test` locally without building,
+only the landing-page source assertions run — that's expected, not a
+regression.
+
+---
+
+## 11. Quick reference
+
+```bash
+# One-time / per-clone
+corepack enable
+git submodule update --init          # docs + apps/web/upstream (Kiwi)
+pnpm install
+
+# Build the SPA + landing page (pick the env)
+pnpm --filter web build              # default config (staging-shaped)
+pnpm --filter web build:staging      # static/config.staging.json
+pnpm --filter web build:prod         # static/config.prod.json
+
+# Local dev (Worker serves SPA + landing page + WS on one origin)
+pnpm build                           # build the rest of the workspace
+pnpm --filter @serverless-ircd/cf-worker dev   # http://localhost:8787
+node apps/cf-worker/scripts/smoke.mjs          # WS smoke
+
+# Deploy staging (Worker + assets in one command)
+pnpm deploy:cf:staging               # wrangler deploy --env staging
+
+# Tests / lint
+pnpm --filter web test
+pnpm --filter web typecheck
+pnpm lint
+```
+
+Key files:
+
+| Path | What |
+|---|---|
+| `apps/web/scripts/build.mjs` | Orchestrates the upstream Kiwi build + layers our config. |
+| `apps/web/src/config-schema.ts` | Zod schema for `static/config.*.json` (the only TS we own). |
+| `apps/web/src/build-env.ts` | `--env` → config-file resolution (unit-tested). |
+| `apps/web/static/config.{,staging,prod}.json` | Per-env Kiwi configs (validated at build time). |
+| `apps/web/landing/index.html` | Static landing page (project front door), copied to `dist/index.html`. |
+| `apps/web/tests/build-smoke.test.ts` | Landing-page + build-output assertions. |
+| `apps/cf-worker/src/worker.ts` | Edge handler: WS → `ConnectionDO`, `/health`, else `env.ASSETS`. |
+| `apps/cf-worker/src/origin-allowlist.ts` | CSWSH `Origin` policy (pure, unit-tested). |
+| `apps/cf-worker/wrangler.toml` | `[assets]` binding + per-env blocks + `WEB_ORIGINS` var. |
+| `apps/web/upstream/` | Kiwi IRC source (git submodule, tag-pinned). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-ircd",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": false,
   "description": "Serverless IRC daemon with a platform-agnostic core and Cloudflare Workers + AWS adapters",
   "license": "BSD-3-Clause",
@@ -17,7 +17,7 @@
     "typescript": "^5.9.3",
     "vite": "^7.3.6",
     "vitest": "^4.1.10",
-    "@serverless-ircd/aws-adapter": "0.5.0"
+    "@serverless-ircd/aws-adapter": "0.7.0"
   },
   "scripts": {
     "build": "turbo run build",

package/packages/aws-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-adapter",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": true,
   "description": "AWS Lambda + DynamoDB adapter: AwsRuntime implementing IrcRuntime + $connect/$disconnect/$default handlers",
   "license": "BSD-3-Clause",

package/packages/aws-adapter/src/handlers/default.ts

@@ -194,6 +194,9 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
     ...(params.accounts !== undefined ? { accounts: params.accounts } : {}),
     ...(params.mtlsIdentity !== undefined ? { mtlsIdentity: params.mtlsIdentity } : {}),
     ...(params.history !== undefined ? { history: params.history } : {}),
+    // API Gateway terminates TLS before the Lambda is invoked, so every
+    // WebSocket connection is secure → user mode `S`.
+    secure: true,
   });
 
   try {

package/packages/aws-adapter/src/handlers/nlb-stream.ts

@@ -158,6 +158,13 @@ export interface NlbStreamParams {
    * graceful error-suffixed `382`.
    */
   configLoader?: () => Promise<ServerConfig>;
+  /**
+   * Whether the NLB listener terminates TLS for this flow. Set to `true`
+   * when the target group fronts a TLS listener (the `irc+tls://` port) so
+   * the connection surfaces user mode `S`; omit / set `false` for a plain
+   * TCP listener. The stack code sets this from the listener protocol.
+   */
+  secure?: boolean;
 }
 
 /**
@@ -253,6 +260,8 @@ export async function handleNlbStream(
     ...(params.accounts !== undefined ? { accounts: params.accounts } : {}),
     ...(params.mtlsIdentity !== undefined ? { mtlsIdentity: params.mtlsIdentity } : {}),
     ...(params.history !== undefined ? { history: params.history } : {}),
+    // Surface TLS fact when the NLB listener terminates TLS (irc+tls port).
+    ...(params.secure === true ? { secure: true } : {}),
   });
 
   if (lines.length > 0) {

package/packages/aws-adapter/src/serialize.ts

@@ -56,6 +56,13 @@ export interface MarshalledConnection {
   connectionId: ConnId;
   registration: RegistrationState;
   capNegotiating: boolean;
+  /**
+   * Transport TLS fact (user mode `S`). Optional on the persisted shape so
+   * rows written before the field shipped deserialize with a `false`
+   * default via the coalescing in {@link unmarshalConnection}. Always
+   * written by {@link marshalConnection}.
+   */
+  secure?: boolean;
   caps: string[];
   /**
    * Present (as a JS `Set`, auto-marshalled to `SS`) only when the
@@ -102,6 +109,7 @@ export function marshalConnection(state: ConnectionState, idleSince: number): Ma
     connectionId: state.id,
     registration: state.registration,
     capNegotiating: state.capNegotiating,
+    secure: state.secure,
     caps: [...state.caps],
     userModes: { ...state.userModes },
     lastSeen: state.lastSeen,
@@ -140,13 +148,20 @@ export function unmarshalConnection(row: MarshalledConnection): ConnectionState
     id: row.connectionId,
     registration: row.registration,
     capNegotiating: row.capNegotiating,
+    // `secure` is absent on rows persisted before user mode `S` shipped;
+    // default to false (plain transport) so the state shape stays satisfied.
+    secure: row.secure ?? false,
     caps: new Set<string>(row.caps),
     // `joinedChannels` is absent on rows that never joined a channel
     // (DynamoDB rejects empty sets); default to an empty Set. The SDK
     // unmarshalls `SS` back to a native Set, which the Set constructor
     // copies; arrays (older rows) also iterate fine.
     joinedChannels: new Set<ChanName>(row.joinedChannels ?? []),
-    userModes: { ...row.userModes },
+    // `userModes.tls` is absent on rows persisted before user mode `S`
+    // shipped; default to false so the field is a real boolean rather than
+    // `undefined`. Cast to Partial so TypeScript accepts the explicit
+    // default without flagging the spread overwrite (TS2783).
+    userModes: normalizeUserModes(row.userModes),
     lastSeen: row.lastSeen,
     connectedSince: row.connectedSince,
   };
@@ -162,6 +177,19 @@ export function unmarshalConnection(row: MarshalledConnection): ConnectionState
   return state;
 }
 
+/**
+ * Defaults `tls` to false on a deserialized `UserModes`. Rows persisted
+ * before user mode `S` shipped lack the field; the DynamoDB SDK round-trip
+ * yields `undefined`, which would leak into runtime code expecting a real
+ * boolean. Casting to `Partial` lets the explicit default apply without
+ * TypeScript flagging the spread overwrite (TS2783).
+ */
+function normalizeUserModes(um: UserModes): UserModes {
+  const out: Partial<UserModes> = { ...um };
+  if (out.tls === undefined) out.tls = false;
+  return out as UserModes;
+}
+
 // ---------------------------------------------------------------------------
 // Nicks
 // ---------------------------------------------------------------------------