feat(router): add TLS/mTLS support to gRPC subgraphs

docs-website/router/configuration.mdx

@@ -416,34 +416,78 @@ tls:
       cert_file: ../your/cert.pem
 ```
 
-### Outbound Client TLS (mTLS to Subgraphs)
+### Outbound TLS to Subgraphs
 
-Configure TLS client certificates for outbound connections from the router to subgraphs. See [Outbound mTLS to Subgraphs](/router/security/tls#router-mtls) for details.
+Configure TLS for outbound connections from router to subgraphs.
+See [TLS](/router/security/tls) for details.
 
-| Environment Variable                      | YAML                                          | Required               | Description                                                                                                                   | Default Value |
-| ----------------------------------------- | --------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------- |
-| TLS_CLIENT_CERT_FILE                      | tls.client.all.cert_file                      | <Icon icon="square" /> | Path to the client certificate chain file for authenticating the router to subgraphs.                                         |               |
-| TLS_CLIENT_KEY_FILE                       | tls.client.all.key_file                       | <Icon icon="square" /> | Path to the client private key file.                                                                                          |               |
-| TLS_CLIENT_CA_FILE                        | tls.client.all.ca_file                        | <Icon icon="square" /> | Path to a custom CA certificate file for verifying subgraph server certificates.                                              |               |
-| TLS_CLIENT_INSECURE_SKIP_CA_VERIFICATION  | tls.client.all.insecure_skip_ca_verification  | <Icon icon="square" /> | Skip verification of the subgraph server certificate. Only use for development or testing.                                    | false         |
+#### HTTP Subgraphs
 
-### Example YAML config:
+Configuring a subgraph URL with a `https://` scheme activates TLS to subgraphs.
+Specifying `ca_file` additionally verifies a subgraphs certificate against that CA certificate.  
+Additionally specifying `cert_file` and `key_file` enables mTLS on subgraph connections.
+
+The following settings configure TLS for HTTP based subgraphs.
+
+| Environment Variable                          | YAML                                          | Required               | Description                                                                                         | Default Value |
+| --------------------------------------------- | --------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------- | ------------- |
+| TLS_CLIENT_ALL_CA_FILE                        | tls.client.all.ca_file                        | <Icon icon="square" /> | Path to a custom CA certificate file for verifying subgraph server certificates.                    |               |
+| TLS_CLIENT_ALL_CERT_FILE                      | tls.client.all.cert_file                      | <Icon icon="square" /> | Path to the client certificate chain file for authenticating the router to subgraphs. Enables mTLS. |               |
+| TLS_CLIENT_ALL_KEY_FILE                       | tls.client.all.key_file                       | <Icon icon="square" /> | Path to the client private key file. Enables mTLS.                                                  |               |
+| TLS_CLIENT_ALL_INSECURE_SKIP_CA_VERIFICATION  | tls.client.all.insecure_skip_ca_verification  | <Icon icon="square" /> | Skip verification of the subgraph server certificate. Only use for development or testing.          | false         |
+
+##### Example YAML config:
 
 ```yaml config.yaml
 version: "1"
 
 tls:
   client:
-    all:
+    all: # global tls configuration affecting all HTTP subgraphs
       cert_file: /path/to/client.crt
       key_file: /path/to/client.key
       ca_file: /path/to/ca.crt
-    subgraphs:
+    subgraphs: # additional overwrites for specific HTTP subgraphs
       products:
         cert_file: /path/to/products-client.crt
         key_file: /path/to/products-client.key
 ```
 
+#### gRPC Subgraphs
+
+The configuration settings above are not applied to gRPC subgraphs.
+For gRPC subgraphs, TLS must be explicitly enabled with `enabled: true`.
+
+| Environment Variable                               | YAML                                               | Required                | Description                                                                                              | Default Value |
+| -------------------------------------------------- | -------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- | ------------- |
+| TLS_CLIENT_GRPC_ALL_ENABLED                        | tls.client_grpc.all.enabled                        | <Icon icon="check-square" /> | Enable TLS for all gRPC subgraph connections.                                                       |               |
+| TLS_CLIENT_GRPC_ALL_CA_FILE                        | tls.client_grpc.all.ca_file                        | <Icon icon="square" /> | Path to a custom CA certificate file for verifying gRPC subgraph server certificates.                    |               |
+| TLS_CLIENT_GRPC_ALL_CERT_FILE                      | tls.client_grpc.all.cert_file                      | <Icon icon="square" /> | Path to the client certificate chain file for authenticating the router to gRPC subgraphs. Enables mTLS. |               |
+| TLS_CLIENT_GRPC_ALL_KEY_FILE                       | tls.client_grpc.all.key_file                       | <Icon icon="square" /> | Path to the client private key file. Enables mTLS.                                                       |               |
+| TLS_CLIENT_GRPC_ALL_INSECURE_SKIP_CA_VERIFICATION  | tls.client_grpc.all.insecure_skip_ca_verification  | <Icon icon="square" /> | Skip verification of the gRPC subgraph server certificate. Only use for development or testing.          | false         |
+
+##### Example YAML config:
+
+```yaml config.yaml
+version: "1"
+
+tls:
+  client_grpc:
+    all: # global TLS configuration for all gRPC subgraphs
+      enabled: true
+      cert_file: /path/to/client.crt
+      key_file: /path/to/client.key
+      ca_file: /path/to/ca.crt
+    subgraphs: # per-subgraph overrides
+      products:
+        enabled: true
+        cert_file: /path/to/products-client.crt
+        key_file: /path/to/products-client.key
+      projects:
+        enabled: false # specifically disable TLS for this subgraph
+```
+
+
 ## Compliance
 
 The configuration for the compliance. Includes for example the configuration for the anonymization of the IP addresses.

docs-website/router/gRPC/grpc-services.mdx

@@ -96,7 +96,7 @@ gRPC services integrate into GraphQL Federation through this architecture:
 
 ### Security
 - Implement proper authentication between router and services
-- Consider network security and encryption (when TLS support is available)
+- Consider network security and [TLS on connections](/router/security/tls#tls-with-grpc-subgraphs) to your service
 - Follow microservices security best practices
 
 ### Monitoring and Observability

docs-website/router/intro.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Cosmo Router"
-description: "Cosmo Router is an Apache 2.0 licensed Router compatible with GraphQL Federation v1 & v2. The Router is implemented in Golang with a focus on performance, maintainability."
+description: "Cosmo Router is an Apache 2.0 licensed Router compatible with GraphQL Federation v1 & v2. The Router is implemented in Golang with a focus on performance and maintainability."
 icon: "door-open"
 ---
 

docs-website/router/security/tls.mdx

@@ -7,7 +7,7 @@ icon: "shield-halved"
 <Info>
   Available since version [0.71.0](https://github.com/wundergraph/cosmo/releases/tag/router%400.71.0)
 </Info>
-The Cosmo Router supports TLS to secure and authenticate communications for both client and subgraph connections. For subgraph connections, encryption and authentication are automatically enabled when the subgraph URL uses the `https://` protocol. For client connections, you can configure TLS as follow:
+The Cosmo Router supports TLS to secure and authenticate communications for both client and subgraph connections. For client connections, you can configure TLS as follow:
 
 
 ```yaml config.yaml
@@ -119,6 +119,25 @@ That's it! The router should now be able to receive TLS connections **only** fro
 
 ## TLS with Subgraphs
 
+For subgraph connections, encryption and authentication are automatically enabled when the subgraph URL uses the `https://` protocol.
+
+<Note>
+These settings do not apply to [Cosmo Connect](/connect/overview) subgraphs.
+See [TLS with gRPC Subgraphs](#tls-with-grpc-subgraphs) on how to configure them.
+</Note>
+
+### Custom CA Certificates
+
+By default, the router uses your operating system's root CA store to verify subgraph server certificates. If your subgraphs use TLS certificates signed by an internal or private CA that is not in the system's root CA store, you can provide a custom CA certificate file using `ca_file`. The router will use this CA to verify the subgraph's server certificate during the TLS handshake.
+
+```yaml config.yaml
+tls:
+  client:
+    all:
+      ca_file: /path/to/internal-ca.crt
+      insecure_skip_ca_verification: false
+```
+
 ### Router mTLS
 
 In addition to accepting mTLS connections from clients (inbound), the router can also present client certificates when connecting to subgraphs (outbound). This is useful when your subgraphs require mTLS authentication to accept requests from the router.
@@ -160,18 +179,122 @@ tls:
   Per-subgraph entries live under `tls.client.subgraphs` and use the same field structure as `tls.client.all` (e.g., `cert_file`, `key_file`). A per-subgraph entry fully overrides the global `all` config for that subgraph.
 </Note>
 
+<Warning>
+  `insecure_skip_ca_verification` disables subgraph certificate validation. Only use this for development or testing environments.
+</Warning>
+
+## TLS with gRPC Subgraphs
+
+gRPC subgraph connections use a separate configuration section from HTTP subgraphs: `tls.client_grpc`.
+Unlike HTTP subgraphs, where a `https://` URL automatically enables TLS, gRPC subgraph TLS must be explicitly activated with `enabled: true`.
+
+### Enabling TLS
+
+Set `enabled: true` under `tls.client_grpc.all` to enable TLS for all gRPC subgraph connections. By default, the router uses the operating system's root CA store to verify server certificates.
+
+```yaml config.yaml
+tls:
+  client_grpc:
+    all:
+      enabled: true
+```
+
+To enable TLS for a specific subgraph only, omit the global `all` config and configure it under `subgraphs`:
+
+```yaml config.yaml
+tls:
+  client_grpc:
+    subgraphs:
+      products:
+        enabled: true
+```
+
+To disable TLS for a specific subgraph while keeping it enabled globally, set `enabled: false` in the per-subgraph entry. Per-subgraph config fully replaces the global `all` config for that subgraph.
+
+```yaml config.yaml
+tls:
+  client_grpc:
+    all:
+      enabled: true
+    subgraphs:
+      products:
+        enabled: false
+```
+
 ### Custom CA Certificates
 
-By default, the router uses your operating system's root CA store to verify subgraph server certificates. If your subgraphs use TLS certificates signed by an internal or private CA that is not in the system's root CA store, you can provide a custom CA certificate file using `ca_file`. The router will use this CA to verify the subgraph's server certificate during the TLS handshake.
+If your gRPC subgraphs use certificates signed by an internal or private CA, provide the CA certificate via `ca_file`:
 
 ```yaml config.yaml
 tls:
-  client:
+  client_grpc:
     all:
+      enabled: true
       ca_file: /path/to/internal-ca.crt
-      insecure_skip_ca_verification: false
+```
+
+`ca_file` can also be set per-subgraph to use a different CA for a specific subgraph:
+
+```yaml config.yaml
+tls:
+  client_grpc:
+    all:
+      enabled: true
+      ca_file: /path/to/internal-ca.crt
+    subgraphs:
+      products:
+        enabled: true
+        ca_file: /path/to/products-ca.crt
+```
+
+### mTLS
+
+To present a client certificate to gRPC subgraphs (mutual TLS), provide both `cert_file` and `key_file`. Both fields are required together.
+
+#### Global Configuration
+
+Apply a client certificate to all gRPC subgraph connections:
+
+```yaml config.yaml
+tls:
+  client_grpc:
+    all:
+      enabled: true
+      cert_file: /path/to/client.crt
+      key_file: /path/to/client.key
+      ca_file: /path/to/ca.crt
+```
+
+#### Per-Subgraph Configuration
+
+Override the global config for specific gRPC subgraphs. A per-subgraph entry fully replaces the global `all` config for that subgraph. It does not merge with it.
+
+```yaml config.yaml
+tls:
+  client_grpc:
+    all:
+      enabled: true
+      cert_file: /path/to/default-client.crt
+      key_file: /path/to/default-client.key
+    subgraphs:
+      products:
+        enabled: true
+        cert_file: /path/to/products-client.crt
+        key_file: /path/to/products-client.key
+      inventory:
+        enabled: true
+        cert_file: /path/to/inventory-client.crt
+        key_file: /path/to/inventory-client.key
 ```
 
 <Warning>
-  `insecure_skip_ca_verification` disables subgraph certificate validation. Only use this for development or testing environments.
+  `insecure_skip_ca_verification` disables gRPC subgraph certificate validation. Only use this for development or testing environments.
 </Warning>
+
+```yaml config.yaml
+tls:
+  client_grpc:
+    all:
+      enabled: true
+      insecure_skip_ca_verification: true
+```