TLS and mTLS for GraphQL | Cosmo by WunderGraph - WunderGraph

Encrypt every connection to and from the router

TLS for encrypted client connections. mTLS for bidirectional certificate verification. HTTP/2 automatic when TLS is on. A few lines of YAML, no code changes.

Available since Router 0.71.0. PEM certificates. TLS 1.0–1.3.

The problem

Unencrypted internal traffic is a gap most teams accept

Traffic inside an infrastructure perimeter often travels in plaintext. mTLS is skipped because the setup is complex. HTTP/2 goes unused because enabling it requires TLS first.

Plaintext traffic is interceptable inside the perimeter

Traffic between a load balancer and the router often travels unencrypted within the infrastructure. Any compromised node on that path can read or modify the data in transit.

Mutual authentication requires complex custom setup

mTLS — where both client and server present certificates — requires coordinating certificate authorities, key files, and Go TLS config. Most teams skip it and accept the risk.

HTTP/2 is blocked without TLS

HTTP/2 multiplexing and header compression improve performance at scale, but TLS is mandatory for HTTP/2 operation. No TLS means no HTTP/2.

Our solution

TLS in YAML, HTTP/2 for free

Enable TLS with a cert and key file path. HTTP/2 follows automatically. Add a client_auth block for mTLS. No code changes, no middleware.

From plaintext to encrypted in six steps

Add the tls.server block to router YAML with cert_file and key_file paths pointing to PEM-format files.
The router starts an HTTPS listener. All client connections are encrypted.
HTTP/2 is automatically available when TLS is enabled. Clients supporting HTTP/2 are upgraded automatically.
For subgraph connections, use HTTPS URLs in the subgraph configuration. The router connects over TLS automatically.
For mTLS, add client_auth.cert_file with the CA certificate for validating client certificates.
Set client_auth.required: true to enforce that every client must present a valid certificate. Connections without valid certificates are refused.

Available since Router 0.71.0.

Before & After

Before Cosmo	With Cosmo
Plaintext traffic between load balancer and router	TLS encryption for all client connections
Manual TLS configuration with custom code	cert_file and key_file in YAML, no code changes
HTTP/2 requires separate configuration	HTTP/2 automatic when TLS is enabled
mTLS requires complex setup and coordination	client_auth block with required: true in YAML

How TLS works in Cosmo Router

Configure

Add tls.server.enabled: true with key_file and cert_file paths to the router YAML. Both PEM files are required. Available since Router 0.71.0.

Connect

The router listens for HTTPS connections. Client connections are encrypted using Go's standard TLS library. Supports TLS 1.0 through TLS 1.3. Go defaults apply for cipher suites (ECDHE-ECDSA, ECDHE-RSA, ChaCha20-Poly1305, AES-GCM).

Upgrade

HTTP/2 becomes available automatically when TLS is enabled. Clients that support HTTP/2 are upgraded. Multiplexing and header compression apply to all upgraded connections.

Authenticate

For mTLS, add client_auth.cert_file with the CA certificate. By default, clients without certificates are still accepted. Set client_auth.required: true to enforce client certificate validation and refuse connections that fail.

Encrypt your router connections

Add tls.server to router YAML. HTTP/2 follows. Add client_auth for zero-trust mTLS.