#677 docs: TLS setup guide for swamp serve (direct and reverse proxy)

Parent

Related to #662 (serve authentication & authorization) and #675 (static TLS).

Summary

Document the two TLS deployment variants for `swamp serve` so users can get up and running without guesswork.

What to document

Variant 1 — swamp terminates TLS directly

Using the `--cert-file` and `--key-file` flags added in #675. Cover:

• Generating a self-signed cert for local testing: ```bash openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 \ -keyout server.key -out server.crt -days 30 -nodes \ -subj '/CN=localhost' \ -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1' \ -addext 'basicConstraints=critical,CA:FALSE' ``` Note: `CA:FALSE` is required — Deno's TLS stack rejects CA certs used as end-entity certs.

• Starting the server with TLS: ```bash swamp serve --cert-file server.crt --key-file server.key ```

• Connecting from a client: ```bash swamp model method run --server wss://: ```

• Self-signed cert trust: compiled binary uses baked-in cert store, so self-signed certs must be added to the OS trust store. `DENO_CERT` works with `deno run` but not compiled binaries. For production, use a CA-signed cert.

• Environment variable alternatives: `SWAMP_SERVE_CERT_FILE` and `SWAMP_SERVE_KEY_FILE`.

Variant 2 — reverse proxy terminates TLS (e.g. Caddy)

• swamp serve runs plain on loopback: ```bash swamp serve ```

• Caddy (or nginx) sits in front and handles TLS: ```bash caddy reverse-proxy --from localhost:9443 --to localhost:9090 ```

• Client connects to the proxy: ```bash swamp model method run --server wss://localhost:9443 ```

• Note: Caddy auto-provisions locally-trusted certs — no cert generation or keychain manipulation needed for local testing.

• Tradeoff: extra process but zero cert management. For production, Caddy can auto-provision Let's Encrypt certs.

When to use which

• Direct TLS: single binary, no extra infra, you manage certs. Good for simple deployments or when you already have certs from corporate PKI.
• Reverse proxy: extra process, but automatic cert management and renewal. Good for production deployments where you already have a proxy layer, or for easy local testing with Caddy.

Scope

Documentation only — no code changes.