docs: RAINBOW_TRUSTLESS_GATEWAY_DOMAINS

docs/environment-variables.md

@@ -20,31 +20,56 @@
 
 ### `RAINBOW_GATEWAY_DOMAINS`
 
-Comma-separated list of path gateway hostnames. For example, passing `ipfs.io` will enable handler for standard [path gateway](https://specs.ipfs.tech/http-gateways/path-gateway/) requests with the `Host` header set to `ipfs.io`.
+Comma-separated list of [path gateway](https://specs.ipfs.tech/http-gateways/path-gateway/)
+hostnames that will serve both trustless and deserialized response types.
+
+Example:  passing `ipfs.io` will enable deserialized handler for flat
+[path gateway](https://specs.ipfs.tech/http-gateways/path-gateway/)
+requests with the `Host` header set to `ipfs.io`.
 
 Default: `127.0.0.1`
 
 ### `RAINBOW_SUBDOMAIN_GATEWAY_DOMAINS`
 
-Comma-separated list of [subdomain gateway](https://specs.ipfs.tech/http-gateways/subdomain-gateway/) domains. For example, passing `dweb.link` will enable handler for standard [subdomain gateway](https://specs.ipfs.tech/http-gateways/subdomain-gateway/) requests with the `Host` header set to `*.ipfs.dweb.link` and  `*.ipns.dweb.link`.
+Comma-separated list of [subdomain gateway](https://specs.ipfs.tech/http-gateways/subdomain-gateway/)
+domains for website hosting with Origin-isolation per content root.
+
+Example: passing `dweb.link` will enable handler for Origin-isolated
+[subdomain gateway](https://specs.ipfs.tech/http-gateways/subdomain-gateway/)
+requests with the `Host` header with subdomain values matching
+`*.ipfs.dweb.link` or  `*.ipns.dweb.link`.
 
 Default: `localhost`
 
 ### `RAINBOW_TRUSTLESS_GATEWAY_DOMAINS`
 
-Comma-separated list of [trustless gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/) domains. These gateways can also be included in [`RAINBOW_SUBDOMAIN_GATEWAY_DOMAINS`](#rainbow_subdomain_gateway_domains), which means they will be trustless subdomain gateways.
+Specifies trustless-only hostnames.
 
-Default: none
+Comma-separated list of [trustless gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/)
+domains, where unverified website asset hosting and deserialized responses is
+disabled, and **response types requested via `?format=` and `Accept` HTTP header are limited to
+[verifiable content types](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval)**:
+- [`application/vnd.ipld.raw`](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw)
+- [`application/vnd.ipld.car`](https://www.iana.org/assignments/media-types/application/vnd.ipld.car)
+- [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record)
 
-### `KUBO_RPC_URL`
+**NOTE:** This setting is applied on top of everything else, to ensure
+trustless domain can't be used for phishing or direct hotlinking and hosting of third-party content.
 
-Default: `127.0.0.1:5001` (see `DefaultKuboRPC`)
+Example:  passing `trustless-gateway.link` will ensure only verifiable content types are supported
+when request comes with the `Host` header set to `trustless-gateway.link`.
+
+Default: none (`Host` is ignored and gateway at `127.0.0.1` supports both deserialized and verifiable response types)
+
+### `KUBO_RPC_URL`
 
 Single URL or a comma separated list of RPC endpoints that provide legacy `/api/v0` from Kubo.
 
 We use this to redirect some legacy `/api/v0` commands that need to be handled on `ipfs.io`.
 
-This is deprecated and will be removed in the future.
+**NOTE:** This is deprecated and will be removed in the future.
+
+Default: `127.0.0.1:5001` (see `DefaultKuboRPC`)
 
 ## Logging
 

main.go

@@ -96,19 +96,19 @@ Generate an identity seed and launch a gateway:
 			Name:    "gateway-domains",
 			Value:   "",
 			EnvVars: []string{"RAINBOW_GATEWAY_DOMAINS"},
-			Usage:   "Legacy path-gateway domains. Comma-separated list.",
+			Usage:   "Domains with flat path gateway, no Origin isolation. Comma-separated list.",
 		},
 		&cli.StringFlag{
 			Name:    "subdomain-gateway-domains",
 			Value:   "",
 			EnvVars: []string{"RAINBOW_SUBDOMAIN_GATEWAY_DOMAINS"},
-			Usage:   "Subdomain gateway domains. Comma-separated list.",
+			Usage:   "Domains with subdomain-based Origin isolation. Comma-separated list.",
 		},
 		&cli.StringFlag{
 			Name:    "trustless-gateway-domains",
 			Value:   "",
 			EnvVars: []string{"RAINBOW_TRUSTLESS_GATEWAY_DOMAINS"},
-			Usage:   "Trustless gateway domains. Comma-separated list.",
+			Usage:   "Domains limited to trustless, verifiable response types. Comma-separated list.",
 		},
 		&cli.StringFlag{
 			Name:    "gateway-listen-address",