Implement RFC domain-scoped mTLS app-to-app routing in GoRouter

Replace MtlsAllowedSources model with AccessScope/AccessRules selectors,
add per-connection TLS state tracking via ConnContext, implement two-layer
RFC authorization handler (SNI/Host 421 check + scope/rules enforcement),
emit mTLS fields in RTR access logs, and rename router.mtls_domains to
router.domains in BOSH config.

Author: rkoster

jobs/gorouter/spec

@@ -200,25 +200,25 @@ properties:
   router.only_trust_client_ca_certs:
     description: "When router.only_trust_client_ca_certs is true, router.client_ca_certs are the only trusted CA certs for client requests. When router.only_trust_client_ca_certs is false, router.client_ca_certs are trusted in addition to router.ca_certs and the CA certificates installed on the filesystem. This will have no affect if the `router.client_cert_validation` property is set to none."
     default: false
-  router.mtls_domains:
+  router.domains:
     description: |
       Array of domains requiring mutual TLS authentication. Each domain can have its own CA certificate pool, forwarded_client_cert mode, and xfcc_format.
       For non-wildcard domains, the domain must match the request host exactly.
-      For wildcard domains (e.g., *.apps.mtls.internal), the wildcard must be the leftmost label and matches any single label.
+      For wildcard domains (e.g., *.apps.identity), the wildcard must be the leftmost label and matches any single label.
 
       xfcc_format controls the format of the X-Forwarded-Client-Cert header:
       - "raw" (default): Full base64-encoded certificate (~1.5KB)
       - "envoy": Compact Hash=<sha256>;Subject="<DN>" format (~300 bytes)
     default: []
     example:
-    - domain: "*.apps.mtls.internal"
+    - name: "*.apps.identity"
       ca_certs: |
         -----BEGIN CERTIFICATE-----
-        <CA certificate for apps.mtls.internal domain>
+        <CA certificate for apps.identity domain>
         -----END CERTIFICATE-----
       forwarded_client_cert: sanitize_set
       xfcc_format: envoy
-    - domain: "secure.example.com"
+    - name: "secure.example.com"
       ca_certs: |
         -----BEGIN CERTIFICATE-----
         <CA certificate for secure.example.com>

jobs/gorouter/templates/gorouter.yml.erb

@@ -503,35 +503,35 @@ if p('router.client_ca_certs')
   params['client_ca_certs'] = client_ca_certs
 end
 
-if_p('router.mtls_domains') do |mtls_domains|
-  if !mtls_domains.is_a?(Array)
-    raise 'router.mtls_domains must be provided as an array'
+if_p('router.domains') do |domains|
+  if !domains.is_a?(Array)
+    raise 'router.domains must be provided as an array'
   end
 
   processed_domains = []
-  mtls_domains.each do |domain_config|
+  domains.each do |domain_config|
     if !domain_config.is_a?(Hash)
-      raise 'Each entry in router.mtls_domains must be a hash'
+      raise 'Each entry in router.domains must be a hash'
     end
 
-    if !domain_config.key?('domain') || domain_config['domain'].nil? || domain_config['domain'].strip.empty?
-      raise 'Each entry in router.mtls_domains must have a "domain" key'
+    if !domain_config.key?('name') || domain_config['name'].nil? || domain_config['name'].strip.empty?
+      raise 'Each entry in router.domains must have a "name" key'
     end
 
     if !domain_config.key?('ca_certs') || domain_config['ca_certs'].nil? || domain_config['ca_certs'].strip.empty?
-      raise 'Each entry in router.mtls_domains must have a "ca_certs" key with certificate content'
+      raise 'Each entry in router.domains must have a "ca_certs" key with certificate content'
     end
 
     processed_entry = {
-      'domain' => domain_config['domain'],
+      'domain' => domain_config['name'],
       'ca_certs' => domain_config['ca_certs']
     }
 
     if domain_config.key?('forwarded_client_cert') && !domain_config['forwarded_client_cert'].nil?
       valid_modes = ['always_forward', 'forward', 'sanitize_set']
       mode = domain_config['forwarded_client_cert']
       unless valid_modes.include?(mode)
-        raise "Invalid forwarded_client_cert mode '#{mode}' for domain '#{domain_config['domain']}'. Must be one of: #{valid_modes.join(', ')}"
+        raise "Invalid forwarded_client_cert mode '#{mode}' for domain '#{domain_config['name']}'. Must be one of: #{valid_modes.join(', ')}"
       end
       processed_entry['forwarded_client_cert'] = mode
     end
@@ -540,15 +540,15 @@ if_p('router.mtls_domains') do |mtls_domains|
       valid_formats = ['raw', 'envoy']
       format = domain_config['xfcc_format']
       unless valid_formats.include?(format)
-        raise "Invalid xfcc_format '#{format}' for domain '#{domain_config['domain']}'. Must be one of: #{valid_formats.join(', ')}"
+        raise "Invalid xfcc_format '#{format}' for domain '#{domain_config['name']}'. Must be one of: #{valid_formats.join(', ')}"
       end
       processed_entry['xfcc_format'] = format
     end
 
     processed_domains << processed_entry
   end
 
-  params['mtls_domains'] = processed_domains
+  params['domains'] = processed_domains
 end
 
 if_p('router.http_rewrite') do |r|

src/code.cloudfoundry.org/gorouter/accesslog/schema/access_log_record.go

@@ -127,6 +127,20 @@ type AccessLogRecord struct {
 	GorouterTime                float64
 
 	LocalAddress string
+
+	// mTLS authorization fields (populated for mTLS domains only).
+	// MtlsAuth is "allowed" or "denied"; empty for non-mTLS requests.
+	MtlsAuth string
+	// MtlsRule identifies the rule that matched or caused denial.
+	MtlsRule string
+	// MtlsDeniedReason is a human-readable denial explanation (empty on allow).
+	MtlsDeniedReason string
+	// CallerApp/Space/Org are the CF identity fields from the client certificate.
+	CallerApp   string
+	CallerSpace string
+	CallerOrg   string
+	// TlsSNI is the SNI used during TLS (logged on 421 rejections).
+	TlsSNI string
 }
 
 func (r *AccessLogRecord) formatStartedAt() string {
@@ -316,6 +330,43 @@ func (r *AccessLogRecord) makeRecord(performTruncate bool) []byte {
 	b.WriteString(`x_cf_routererror:`)
 	b.WriteDashOrStringValue(r.RouterError)
 
+	// mTLS identity and authorization fields (only emitted when present)
+	if r.TlsSNI != "" {
+		// #nosec G104
+		b.WriteString(` tls_sni:`)
+		b.WriteDashOrStringValue(r.TlsSNI)
+	}
+	if r.CallerApp != "" {
+		// #nosec G104
+		b.WriteString(` caller_app:`)
+		b.WriteDashOrStringValue(r.CallerApp)
+	}
+	if r.CallerSpace != "" {
+		// #nosec G104
+		b.WriteString(` caller_space:`)
+		b.WriteDashOrStringValue(r.CallerSpace)
+	}
+	if r.CallerOrg != "" {
+		// #nosec G104
+		b.WriteString(` caller_org:`)
+		b.WriteDashOrStringValue(r.CallerOrg)
+	}
+	if r.MtlsAuth != "" {
+		// #nosec G104
+		b.WriteString(` mtls_auth:`)
+		b.WriteDashOrStringValue(r.MtlsAuth)
+	}
+	if r.MtlsRule != "" {
+		// #nosec G104
+		b.WriteString(` mtls_rule:`)
+		b.WriteDashOrStringValue(r.MtlsRule)
+	}
+	if r.MtlsDeniedReason != "" {
+		// #nosec G104
+		b.WriteString(` mtls_denied_reason:`)
+		b.WriteDashOrStringValue(r.MtlsDeniedReason)
+	}
+
 	r.addExtraHeaders(b, performTruncate)
 
 	return b.Bytes()

src/code.cloudfoundry.org/gorouter/config/config.go

@@ -409,9 +409,10 @@ type Config struct {
 	ClientCACerts                  string            `yaml:"client_ca_certs,omitempty"`
 	ClientCAPool                   *x509.CertPool    `yaml:"-"`
 
-	// MtlsDomains configures domains that require client certificates (mTLS)
-	// Routes on these domains will require valid instance identity certificates
-	MtlsDomains []MtlsDomainConfig `yaml:"mtls_domains,omitempty"`
+	// Domains configures domains that require client certificates (mTLS).
+	// Corresponds to router.domains in the BOSH manifest (RFC: router.domains).
+	// Routes on these domains will require valid instance identity certificates.
+	Domains []MtlsDomainConfig `yaml:"domains,omitempty"`
 	// Computed: map of domain -> config for fast lookup
 	mtlsDomainMap map[string]*MtlsDomainConfig `yaml:"-"`
 
@@ -930,16 +931,16 @@ func (c *Config) processMtlsDomains() error {
 	// Initialize mTLS domain map
 	c.mtlsDomainMap = make(map[string]*MtlsDomainConfig)
 
-	for i := range c.MtlsDomains {
-		domain := &c.MtlsDomains[i]
+	for i := range c.Domains {
+		domain := &c.Domains[i]
 		domain.RequireClientCert = true
 
 		// Validate forwarded_client_cert mode
 		if domain.ForwardedClientCert == "" {
 			domain.ForwardedClientCert = SANITIZE_SET // Default to most secure
 		}
 		if !slices.Contains(AllowedForwardedClientCertModes, domain.ForwardedClientCert) {
-			return fmt.Errorf("mtls_domains[%d].forwarded_client_cert must be one of %v",
+			return fmt.Errorf("domains[%d].forwarded_client_cert must be one of %v",
 				i, AllowedForwardedClientCertModes)
 		}
 
@@ -948,24 +949,24 @@ func (c *Config) processMtlsDomains() error {
 			domain.XFCCFormat = XFCC_FORMAT_RAW // Default to raw for backwards compatibility
 		}
 		if !slices.Contains(AllowedXFCCFormats, domain.XFCCFormat) {
-			return fmt.Errorf("mtls_domains[%d].xfcc_format must be one of %v",
+			return fmt.Errorf("domains[%d].xfcc_format must be one of %v",
 				i, AllowedXFCCFormats)
 		}
 
 		// Build CA pool for this domain
 		if domain.CACerts != "" {
 			pool := x509.NewCertPool()
 			if !pool.AppendCertsFromPEM([]byte(domain.CACerts)) {
-				return fmt.Errorf("mtls_domains[%d].ca_certs contains invalid certificates", i)
+				return fmt.Errorf("domains[%d].ca_certs contains invalid certificates", i)
 			}
 			domain.CAPool = pool
 		} else {
-			return fmt.Errorf("mtls_domains[%d].ca_certs is required", i)
+			return fmt.Errorf("domains[%d].ca_certs is required", i)
 		}
 
 		// Validate domain is not empty
 		if domain.Domain == "" {
-			return fmt.Errorf("mtls_domains[%d].domain is required", i)
+			return fmt.Errorf("domains[%d].domain is required", i)
 		}
 
 		c.mtlsDomainMap[domain.Domain] = domain

src/code.cloudfoundry.org/gorouter/handlers/access_log.go

@@ -83,6 +83,15 @@ func (a *accessLog) ServeHTTP(rw http.ResponseWriter, r *http.Request, next http
 
 	alr.LocalAddress = reqInfo.LocalAddress
 
+	// mTLS authorization fields
+	alr.MtlsAuth = reqInfo.MtlsAuth
+	alr.MtlsRule = reqInfo.MtlsRule
+	alr.MtlsDeniedReason = reqInfo.MtlsDeniedReason
+	alr.CallerApp = reqInfo.CallerApp
+	alr.CallerSpace = reqInfo.CallerSpace
+	alr.CallerOrg = reqInfo.CallerOrg
+	alr.TlsSNI = reqInfo.TlsSNI
+
 	a.accessLogger.Log(*alr)
 }
 

src/code.cloudfoundry.org/gorouter/handlers/clientcert_test.go

@@ -236,7 +236,7 @@ var _ = Describe("Clientcert mTLS Domain XFCC Format", func() {
 			cfg, err := config.DefaultConfig()
 			Expect(err).NotTo(HaveOccurred())
 
-			cfg.MtlsDomains = []config.MtlsDomainConfig{{
+			cfg.Domains = []config.MtlsDomainConfig{{
 				Domain:              "*.apps.mtls.internal",
 				CACerts:             string(certChain.CACertPEM),
 				ForwardedClientCert: config.SANITIZE_SET,
@@ -319,7 +319,7 @@ var _ = Describe("Clientcert mTLS Domain XFCC Format", func() {
 			cfg, err := config.DefaultConfig()
 			Expect(err).NotTo(HaveOccurred())
 
-			cfg.MtlsDomains = []config.MtlsDomainConfig{{
+			cfg.Domains = []config.MtlsDomainConfig{{
 				Domain:              "*.apps.mtls.internal",
 				CACerts:             string(certChain.CACertPEM),
 				ForwardedClientCert: config.SANITIZE_SET,
@@ -395,7 +395,7 @@ var _ = Describe("Clientcert mTLS Domain XFCC Format", func() {
 			cfg, err := config.DefaultConfig()
 			Expect(err).NotTo(HaveOccurred())
 
-			cfg.MtlsDomains = []config.MtlsDomainConfig{{
+			cfg.Domains = []config.MtlsDomainConfig{{
 				Domain:              "*.apps.mtls.internal",
 				CACerts:             string(certChain.CACertPEM),
 				ForwardedClientCert: config.SANITIZE_SET,
@@ -405,7 +405,7 @@ var _ = Describe("Clientcert mTLS Domain XFCC Format", func() {
 			Expect(err).NotTo(HaveOccurred())
 
 			// After Process(), XFCCFormat should be set to "raw"
-			Expect(cfg.MtlsDomains[0].XFCCFormat).To(Equal(config.XFCC_FORMAT_RAW))
+			Expect(cfg.Domains[0].XFCCFormat).To(Equal(config.XFCC_FORMAT_RAW))
 		})
 	})
 })