Implement RFC domain-scoped mTLS routing with /v3/access_rules API

Replace POC route-options-based mTLS implementation with RFC-compliant architecture:

Domain model changes:
- Add enforce_access_rules (boolean) and access_rules_scope (any/org/space) to domains
- Fields are immutable after domain creation
- Update DomainCreateMessage, DomainPresenter, and DomainCreate action

Access Rules resource:
- New /v3/access_rules API with full CRUD operations
- RouteAccessRule model with guid, name, selector, route_id
- Selector format: cf:app:<uuid>, cf:space:<uuid>, cf:org:<uuid>, or cf:any
- Enforce cf:any exclusivity and per-route name/selector uniqueness
- Space Developer can manage rules for routes in their space

Diego sync path:
- Inject access_scope and access_rules into route options for GoRouter
- Filter internal mTLS keys (access_scope, access_rules) from public /v3/routes API
- Add access_rules to eager load to avoid N+1 queries

Tests:
- Unit tests for AccessRuleCreateMessage (selector validation, cf:any rules)
- Request specs for /v3/access_rules CRUD (create, show, list, delete, metadata update)
- Updated domain_create_message_spec for enforce_access_rules validation
- Updated routing_info_spec to verify mTLS options injection
- Updated route_presenter_spec to verify internal keys are filtered

Remove POC artifacts:
- Remove app_to_app_mtls_routing feature flag
- Remove mtls_allowed_* keys from route_options_message

Author: rkoster

app/access/access_rule_access.rb

@@ -0,0 +1,66 @@
+module VCAP::CloudController
+  class AccessRuleAccess < BaseAccess
+    # Space Developer of the route's space can manage access rules.
+    # No bilateral requirement — destination-controlled auth only.
+
+    def create?(access_rule, _params=nil)
+      return true if admin_user?
+
+      route = access_rule.route
+      return false unless route
+
+      space = route.space
+      context.user_email && context.user.is_a?(User) &&
+        space.developers.include?(context.user)
+    end
+
+    def read?(access_rule)
+      return true if admin_user? || admin_read_only_user? || global_auditor?
+
+      route = access_rule.route
+      return false unless route
+
+      object_is_visible_to_user?(access_rule, context.user)
+    end
+
+    def update?(access_rule, _params=nil)
+      create?(access_rule)
+    end
+
+    def delete?(access_rule)
+      create?(access_rule)
+    end
+
+    def index?(_object_class, _params=nil)
+      admin_user? || admin_read_only_user? || has_read_scope? || global_auditor?
+    end
+
+    def read_with_token?(_)
+      admin_user? || admin_read_only_user? || has_read_scope? || global_auditor?
+    end
+
+    def create_with_token?(_)
+      admin_user? || has_write_scope?
+    end
+
+    def read_for_update_with_token?(_)
+      admin_user? || has_write_scope?
+    end
+
+    def can_remove_related_object_with_token?(*args)
+      read_for_update_with_token?(*args)
+    end
+
+    def read_related_object_for_update_with_token?(*args)
+      read_for_update_with_token?(*args)
+    end
+
+    def update_with_token?(_)
+      admin_user? || has_write_scope?
+    end
+
+    def delete_with_token?(_)
+      admin_user? || has_write_scope?
+    end
+  end
+end

app/actions/domain_create.rb

@@ -21,6 +21,8 @@ def create(message:, shared_organizations: [])
                end
 
       domain.router_group_guid = message.router_group_guid
+      domain.enforce_access_rules = message.enforce_access_rules || false
+      domain.access_rules_scope = message.access_rules_scope
 
       Domain.db.transaction do
         domain.save

app/controllers/v3/access_rules_controller.rb

@@ -0,0 +1,129 @@
+require 'messages/access_rule_create_message'
+require 'messages/access_rule_update_message'
+require 'messages/access_rules_list_message'
+require 'presenters/v3/access_rule_presenter'
+
+class AccessRulesController < ApplicationController
+  def index
+    message = AccessRulesListMessage.from_params(query_params)
+    invalid_param!(message.errors.full_messages) unless message.valid?
+
+    dataset = build_dataset(message)
+
+    render status: :ok, json: Presenters::V3::PaginatedListPresenter.new(
+      presenter: Presenters::V3::AccessRulePresenter,
+      paginated_result: SequelPaginator.new.get_page(dataset, message.try(:pagination_options)),
+      path: '/v3/access_rules',
+      message: message
+    )
+  end
+
+  def show
+    access_rule = VCAP::CloudController::RouteAccessRule.find(guid: hashed_params[:guid])
+    resource_not_found!(:access_rule) unless access_rule
+
+    route = access_rule.route
+    resource_not_found!(:access_rule) unless route && permission_queryer.can_read_from_space?(route.space.id, route.space.organization_id)
+
+    render status: :ok, json: Presenters::V3::AccessRulePresenter.new(access_rule)
+  end
+
+  def create
+    message = AccessRuleCreateMessage.new(hashed_params[:body])
+    unprocessable!(message.errors.full_messages) unless message.valid?
+
+    route = VCAP::CloudController::Route.find(guid: message.route_guid)
+    resource_not_found!(:route) unless route && permission_queryer.can_read_from_space?(route.space.id, route.space.organization_id)
+    unauthorized! unless permission_queryer.can_write_to_active_space?(route.space.id)
+    suspended! unless permission_queryer.is_space_active?(route.space.id)
+
+    unless route.domain.enforce_access_rules
+      unprocessable!("Cannot create access rules for route '#{route.guid}': the route's domain does not have enforce_access_rules enabled.")
+    end
+
+    # Enforce cf:any exclusivity: if route already has a cf:any rule, reject new rules;
+    # if new rule is cf:any, reject if route already has any rules.
+    existing_selectors = route.access_rules.map(&:selector)
+    if message.selector == 'cf:any' && existing_selectors.any?
+      unprocessable!("Cannot add 'cf:any' selector when other access rules already exist for this route.")
+    end
+    if existing_selectors.include?('cf:any') && message.selector != 'cf:any'
+      unprocessable!("Cannot add selector '#{message.selector}': route already has a 'cf:any' rule.")
+    end
+
+    # Uniqueness: name and selector must be unique per route
+    if route.access_rules.any? { |r| r.name == message.name }
+      unprocessable!("An access rule with name '#{message.name}' already exists for this route.")
+    end
+    if existing_selectors.include?(message.selector)
+      unprocessable!("An access rule with selector '#{message.selector}' already exists for this route.")
+    end
+
+    access_rule = VCAP::CloudController::RouteAccessRule.new(
+      guid: SecureRandom.uuid,
+      name: message.name,
+      selector: message.selector,
+      route_id: route.id,
+      created_at: Time.now.utc,
+      updated_at: Time.now.utc
+    )
+    access_rule.save
+
+    render status: :created, json: Presenters::V3::AccessRulePresenter.new(access_rule)
+  end
+
+  def update
+    access_rule = VCAP::CloudController::RouteAccessRule.find(guid: hashed_params[:guid])
+    resource_not_found!(:access_rule) unless access_rule
+
+    route = access_rule.route
+    resource_not_found!(:access_rule) unless route && permission_queryer.can_read_from_space?(route.space.id, route.space.organization_id)
+    unauthorized! unless permission_queryer.can_write_to_active_space?(route.space.id)
+    suspended! unless permission_queryer.is_space_active?(route.space.id)
+
+    message = AccessRuleUpdateMessage.new(hashed_params[:body])
+    unprocessable!(message.errors.full_messages) unless message.valid?
+
+    VCAP::CloudController::MetadataUpdate.update(access_rule, message)
+
+    render status: :ok, json: Presenters::V3::AccessRulePresenter.new(access_rule.reload)
+  end
+
+  def destroy
+    access_rule = VCAP::CloudController::RouteAccessRule.find(guid: hashed_params[:guid])
+    resource_not_found!(:access_rule) unless access_rule
+
+    route = access_rule.route
+    resource_not_found!(:access_rule) unless route && permission_queryer.can_read_from_space?(route.space.id, route.space.organization_id)
+    unauthorized! unless permission_queryer.can_write_to_active_space?(route.space.id)
+    suspended! unless permission_queryer.is_space_active?(route.space.id)
+
+    access_rule.destroy
+    head :no_content
+  end
+
+  private
+
+  def build_dataset(message)
+    dataset = VCAP::CloudController::RouteAccessRule.dataset
+
+    readable_route_ids = VCAP::CloudController::Route.
+      join(:spaces, id: :space_id).
+      where(Sequel.lit(permission_queryer.readable_space_scoped_space_guids_query)).
+      select(:routes__id)
+
+    dataset = dataset.where(route_id: readable_route_ids)
+
+    if message.requested?(:route_guids)
+      dataset = dataset.
+        join(:routes, id: :route_id).
+        where(routes__guid: message.route_guids).
+        select_all(:route_access_rules)
+    end
+
+    dataset = dataset.where(name: message.names) if message.requested?(:names)
+    dataset = dataset.where(selector: message.selectors) if message.requested?(:selectors)
+
+    dataset
+  end
+end

app/decorators/include_access_rule_selector_resource_decorator.rb

@@ -0,0 +1,40 @@
+module VCAP::CloudController
+  class IncludeAccessRuleSelectorResourceDecorator
+    # Handles `?include=selector_resource` for GET /v3/access_rules
+    # Stale/missing resources (selector GUIDs that no longer exist) are silently absent.
+
+    SELECTOR_REGEX = /\Acf:(app|space|org):([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\z/
+
+    def self.match?(include_params)
+      include_params&.include?('selector_resource')
+    end
+
+    def self.decorate(hash, access_rules)
+      included = []
+
+      access_rules.each do |rule|
+        match = SELECTOR_REGEX.match(rule.selector)
+        next unless match
+
+        resource_type = match[1]
+        resource_guid = match[2]
+
+        resource = case resource_type
+                   when 'app'
+                     VCAP::CloudController::AppModel.find(guid: resource_guid)
+                   when 'space'
+                     VCAP::CloudController::Space.find(guid: resource_guid)
+                   when 'org'
+                     VCAP::CloudController::Organization.find(guid: resource_guid)
+                   end
+
+        next if resource.nil?
+
+        included << { type: resource_type, guid: resource.guid }
+      end
+
+      hash[:included] = { selector_resources: included }
+      hash
+    end
+  end
+end

app/messages/access_rule_create_message.rb

@@ -0,0 +1,52 @@
+require 'messages/metadata_base_message'
+
+module VCAP::CloudController
+  class AccessRuleCreateMessage < MetadataBaseMessage
+    SELECTOR_REGEX = /\A(cf:(app|space|org):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|cf:any)\z/
+
+    register_allowed_keys %i[
+      name
+      selector
+      relationships
+    ]
+
+    validates_with NoAdditionalKeysValidator
+    validates_with RelationshipValidator
+
+    validates :name, presence: true, string: true
+    validates :selector, presence: true, string: true
+
+    validate :selector_format_valid
+    validate :selector_not_cf_any_with_others
+
+    delegate :route_guid, to: :relationships_message
+
+    def relationships_message
+      @relationships_message ||= Relationships.new(relationships&.deep_symbolize_keys)
+    end
+
+    private
+
+    def selector_format_valid
+      return unless selector.is_a?(String)
+      return if SELECTOR_REGEX.match?(selector)
+
+      errors.add(:selector, "must be in format 'cf:app:<uuid>', 'cf:space:<uuid>', 'cf:org:<uuid>', or 'cf:any'")
+    end
+
+    def selector_not_cf_any_with_others
+      # enforced at the controller level when checking existing rules on the route
+    end
+
+    class Relationships < BaseMessage
+      register_allowed_keys [:route]
+
+      validates_with NoAdditionalKeysValidator
+      validates :route, presence: true, to_one_relationship: true
+
+      def route_guid
+        HashUtils.dig(route, :data, :guid)
+      end
+    end
+  end
+end

app/messages/access_rule_update_message.rb

@@ -0,0 +1,9 @@
+require 'messages/metadata_base_message'
+
+module VCAP::CloudController
+  class AccessRuleUpdateMessage < MetadataBaseMessage
+    register_allowed_keys []
+
+    validates_with NoAdditionalKeysValidator
+  end
+end

app/messages/access_rules_list_message.rb

@@ -0,0 +1,17 @@
+require 'messages/list_message'
+
+module VCAP::CloudController
+  class AccessRulesListMessage < ListMessage
+    register_allowed_keys %i[
+      route_guids
+      names
+      selectors
+    ]
+
+    validates_with NoAdditionalParamsValidator
+
+    def self.from_params(params)
+      super(params, %w[route_guids names selectors])
+    end
+  end
+end

app/messages/domain_create_message.rb

@@ -16,6 +16,8 @@ class DomainCreateMessage < MetadataBaseMessage
       internal
       relationships
       router_group
+      enforce_access_rules
+      access_rules_scope
     ]
 
     def self.relationships_requested?
@@ -59,6 +61,12 @@ def self.relationships_requested?
               allow_nil: true,
               boolean: true
 
+    validates :enforce_access_rules,
+              allow_nil: true,
+              boolean: true
+
+    validate :access_rules_scope_validation
+
     delegate :organization_guid, to: :relationships_message
     delegate :shared_organizations_guids, to: :relationships_message
 
@@ -97,6 +105,20 @@ def router_group_validation
       errors.add(:router_group, 'guid must be a string') unless router_group_guid.is_a?(String)
     end
 
+    def access_rules_scope_validation
+      if requested?(:access_rules_scope)
+        unless access_rules_scope.nil? || %w[any org space].include?(access_rules_scope)
+          errors.add(:access_rules_scope, "must be one of 'any', 'org', 'space'")
+        end
+      end
+
+      if requested?(:enforce_access_rules) && enforce_access_rules == true
+        if !requested?(:access_rules_scope) || access_rules_scope.nil?
+          errors.add(:access_rules_scope, 'is required when enforce_access_rules is true')
+        end
+      end
+    end
+
     class Relationships < BaseMessage
       def self.shared_organizations_requested?
         @shared_organizations_requested ||= proc { |a| a.requested?(:shared_organizations) }