feat(core): ALPN configuration and TLS visibility on Request/WebSocketSession

- TlsConfig.applicationProtocols(String...) sets the listener's negotiable
  ALPN protocol list via SSLParameters, inherited by every accepted socket
  like clientAuth — works on both keystore() and ofContext(), untouched
  unless called. Enables TLS-ALPN-01 (RFC 8737) style on-demand cert
  issuance: a custom KeyManager can read the already-resolved protocol via
  engine/socket getHandshakeApplicationProtocol() inside
  chooseEngineServerAlias/chooseServerAlias, since ALPN is resolved during
  ClientHello/ServerHello, always before Certificate production.
- Request gains isSecure()/sslSession(), threaded through RequestParser from
  the accepted SSLSocket exactly like remoteAddress() — reference-only,
  zero per-request allocation. sslSession() defers to SSLSocket#getSession()
  lazily, so it's a cached-field read (handshake already completed by the
  time a handler can call it), never a forced handshake.
- WebSocketSession.isSecure()/sslSession() delegate to the upgrading
  Request rather than tracking the socket a second time.
- Documents TLS end-to-end in README.md (listeners, TlsConfig, SNI, ALPN,
  mTLS, Request/WebSocketSession accessors).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -163,8 +163,96 @@ app.onException((ex, req, res) -> {
 |---|---|---|
 | `port` | — | TCP port to bind |
 | `host` | `"0.0.0.0"` | Bind address |
+| `tls` | `null` | TLS for the default listener — see [TLS](#tls) |
+| `listeners` | `[]` | Multiple bind targets (port + host + optional TLS) on one app — see [TLS](#tls) |
 | `maxHeaderBufferSize` | `65536` | Max size of the header buffer (bytes) |
 
+## TLS
+
+HTTPS and WSS are a transport-layer concern only: once a listener is bound, the accepted
+`Socket` is either plain or an `SSLSocket` indistinguishably from `HttpServer`'s point of view
+onward — the request parser, router, and WebSocket upgrade never branch on it. WSS is therefore
+not a separate feature; it's a WebSocket upgrade running over whatever transport it was handed.
+
+### Quick start
+
+```java
+FlashApp.create(FlashConfiguration.builder()
+        .port(443)
+        .tls(TlsConfig.keystore(Path.of("cert.p12"), "changeit"))
+        .build())
+    .get("/ping", (req, res) -> "pong")   // HTTPS
+    .ws("/live", handler)                 // WSS, same route API
+    .start();
+```
+
+### Multiple listeners
+
+One app can bind any number of ports, each independently plain or TLS:
+
+```java
+FlashApp.create(FlashConfiguration.builder()
+        .listener(new FlashConfiguration.Listener(80))                                   // plain
+        .listener(new FlashConfiguration.Listener(443, TlsConfig.keystore(cert, pass)))  // TLS
+        .build());
+```
+
+A non-empty `listeners` list takes precedence over the top-level `port`/`host`/`tls` fields.
+Each listener gets its own accept threads; the router, WS router, and virtual-thread executor
+are shared by all of them — one app, N ports.
+
+### `TlsConfig`
+
+| Factory | Use |
+|---|---|
+| `TlsConfig.keystore(Path, String)` | Builds the `SSLContext` from a PKCS12/JKS keystore (type guessed from the extension). Pins `TLSv1.2`/`TLSv1.3` as enabled protocols; cipher suites are left at the JDK's own curated default. |
+| `TlsConfig.ofContext(SSLContext)` | Escape hatch — the given `SSLContext` is used exactly as built. Flash never calls `setSSLParameters` on this path beyond what you explicitly request via `clientAuth`/`applicationProtocols`, so anything else you configured (custom `KeyManager`, ALPN, cipher suites) is authoritative. |
+
+Chainable on either factory:
+
+```java
+TlsConfig.keystore(cert, pass)
+    .clientAuth(ClientAuth.REQUIRE)                    // mTLS: NONE (default) | OPTIONAL | REQUIRE
+    .applicationProtocols("acme-tls/1", "http/1.1")    // ALPN, in preference order
+```
+
+**SNI** falls out of `keystore()` for free: a keystore holding more than one certificate entry
+is matched against the requested hostname by each certificate's SAN (falling back to CN) — no
+per-hostname config. The first entry in the keystore is the default when SNI is absent or
+matches nothing (same convention as nginx/HAProxy's `default_server`).
+
+**ALPN and custom certificate selection** (e.g. TLS-ALPN-01 / RFC 8737 for on-demand ACME
+issuance): ALPN is resolved while consuming `ClientHello`/producing `ServerHello`, which always
+precedes `Certificate` production. A custom `X509ExtendedKeyManager` passed via `ofContext`
+can therefore read `engine.getHandshakeApplicationProtocol()` (or
+`((SSLSocket) socket).getHandshakeApplicationProtocol()`) inside
+`chooseEngineServerAlias`/`chooseServerAlias` — the negotiated protocol is already resolved by
+then, so the certificate decision can key off it.
+
+**mTLS with a private CA**: `clientAuth(...)` only requests/requires a client certificate;
+`keystore()` deliberately doesn't expose a way to configure which CAs are trusted for that
+certificate (it uses the JDK default trust store). For a private CA, build the `SSLContext`
+yourself with a `TrustManagerFactory` and use `ofContext(...)`.
+
+### Reading TLS info from a request
+
+```java
+app.get("/whoami", (req, res) -> {
+    if (!req.isSecure()) return "plain";
+    SSLSession session = req.sslSession();          // null iff !isSecure()
+    X509Certificate peer = (X509Certificate) session.getPeerCertificates()[0]; // mTLS only
+    return session.getCipherSuite() + " / " + session.getProtocol();
+});
+```
+
+`Request.isSecure()` / `Request.sslSession()` cost nothing extra per request: the `SSLSocket`
+reference is threaded through once per connection (same mechanism as `remoteAddress()`), and
+`sslSession()` only calls `SSLSocket#getSession()` — a cached-field read once the handshake
+that got the request this far has already completed, never a forced handshake.
+
+`WebSocketSession` mirrors this exactly (`isSecure()`, `sslSession()`) by delegating to the
+upgrading `Request` — no separate TLS state is tracked for WS.
+
 ## Architecture
 
 ```
@@ -181,6 +269,7 @@ ServerSocket.accept()
 - **Zero-allocation router** — `FastPathRouterImpl` uses `fpr-core`, a byte-level FSM that matches on `METHOD + path` bytes with no per-request allocation.
 - **Keep-alive** — `RequestParser` reuses its header buffer across requests on the same connection.
 - **Chunked transfer** — both chunked request bodies (decoded via `ChunkedInputStream`) and chunked response bodies are supported.
+- **TLS is transport-only** — see [TLS](#tls). Listeners bind either a plain `ServerSocket` or an `SSLServerSocket`; nothing downstream of `accept()` branches on which.
 
 ## Build & test