Add mTLS app-to-app routing support (RFC draft)

[rkoster]

Summary

Implements Part 2 (CF Identity & Authorization) of the RFC for Identity-Aware Routing for GoRouter. This adds a new Access Rules API that allows developers to control which Cloud Foundry apps can access routes on identity-aware domains.

Note: This PR is a draft because the RFC has not been approved yet.

What This Enables

Developers can now secure routes on identity-aware domains with platform-enforced access control:

# Create a route on an identity-aware domain
cf map-route my-backend apps.identity --hostname backend

# Allow specific apps to access it
cf add-access-rule apps.identity --source-app frontend-app --hostname backend
cf add-access-rule apps.identity --source-app monitoring-app --hostname backend

# List access rules
cf access-rules apps.identity --hostname backend

GoRouter enforces these rules automatically - no code changes needed in the backend app.

Implementation Summary

1. Access Rules API (RFC-Compliant)

New /v3/access_rules endpoints for managing route-level access control:

Method	Path	Description
GET	/v3/access_rules	List access rules with filtering
GET	/v3/access_rules/:guid	Get a single access rule
POST	/v3/access_rules	Create an access rule
PATCH	/v3/access_rules/:guid	Update metadata (labels/annotations only)
DELETE	/v3/access_rules/:guid	Delete an access rule

Query Parameters:

• guids, route_guids, space_guids - Filter by resource GUIDs
• selectors - Filter by exact selector strings
• selector_resource_guids - Text-match against GUIDs in selectors (for stale rule detection)
• include - Sideload related resources: route, app, space, organization, selector_resource

Example Request:

POST /v3/access_rules
{
  "selector": "cf:app:d76446a1-f429-4444-8797-be2f78b75b08",
  "metadata": {
    "labels": { "team": "payments" },
    "annotations": { "description": "Allow frontend to call payments API" }
  },
  "relationships": {
    "route": { "data": { "guid": "route-guid" } }
  }
}

Response includes:

• Selector string (e.g., cf:app:<guid>, cf:space:<guid>, cf:org:<guid>, cf:any)
• Read-only relationships extracted from selector (app, space, organization)
• Metadata (labels and annotations)
• Created/updated timestamps

2. Domain-Level Enforcement Configuration

Domains can now be configured with enforcement settings at creation time (immutable):

cf create-shared-domain apps.identity --enforce-access-rules --scope org

New Domain Fields:

• enforce_access_rules (boolean) - When true, GoRouter enforces access rules for routes on this domain
• access_rules_scope (string: any, org, space) - Operator-level boundary for allowed callers

These fields are set via POST /v3/domains and are not present on PATCH /v3/domains (immutable by design).

3. Validation Rules

Access rule creation enforces all RFC-specified validations:

• ✅ Route's domain must have enforce_access_rules: true
• ✅ Route's domain cannot be internal (internal routes bypass GoRouter)
• ✅ cf:any cannot be combined with other selectors on the same route
• ✅ Duplicate selectors per route are rejected
• ✅ Selector GUIDs are not validated at creation time (intentional - allows cross-org sharing)

4. Metadata Support

Access rules support labels and annotations for auditability:

{
  "metadata": {
    "labels": { "team": "frontend", "env": "prod" },
    "annotations": { 
      "contact": "frontend-team@example.com",
      "slack": "#frontend-support"
    }
  }
}

Implemented via:

• RouteAccessRuleLabelModel and RouteAccessRuleAnnotationModel
• Database tables: route_access_rule_labels, route_access_rule_annotations
• Migrations applied

5. Read-Only Relationships

Access rules expose read-only relationships extracted from the selector:

Selector	Populated Relationship	Others
cf:app:<guid>	app: { data: { guid } }	space, organization → null
cf:space:<guid>	space: { data: { guid } }	app, organization → null
cf:org:<guid>	organization: { data: { guid } }	app, space → null
cf:any	All null	—

When the referenced resource no longer exists, the relationship data is null but the selector string is preserved (for metadata like contact info).

6. Diego Sync Integration

Access rules are automatically translated into GoRouter-compatible route options during Diego sync:

# Cloud Controller converts access rules to:
route.options = {
  "access_scope": "org",  # From domain.access_rules_scope
  "access_rules": "cf:app:guid1,cf:space:guid2"  # Comma-joined selectors
}

Process timestamps are updated on access rule create/delete to trigger ProcessesSync.

Database Migrations

Three new migrations:

1. 20260415000001_remove_name_from_route_access_rules.rb - Remove name field per RFC update
2. 20260415000002_create_route_access_rule_labels.rb - Labels table for metadata
3. 20260415000003_create_route_access_rule_annotations.rb - Annotations table for metadata

Previous migrations (already applied):

• 20260407100000_add_enforce_access_rules_to_domains.rb - Domain enforcement fields
• 20260407100001_create_route_access_rules.rb - Access rules table

Files Changed

Controllers:

• app/controllers/v3/access_rules_controller.rb - Access Rules API implementation

Models:

• app/models/runtime/route_access_rule.rb - Core model with Diego sync callbacks
• app/models/runtime/route_access_rule_label_model.rb - Labels metadata
• app/models/runtime/route_access_rule_annotation_model.rb - Annotations metadata
• app/models/runtime/domain.rb - Add enforcement fields
• app/models/runtime/route.rb - Add access_rules relationship
• app/models.rb - Explicit requires for new models (Rails autoloading disabled)

Messages:

• app/messages/access_rule_create_message.rb - Create validation
• app/messages/access_rule_update_message.rb - Update validation (metadata only)
• app/messages/access_rules_list_message.rb - List filtering
• app/messages/domain_create_message.rb - Add enforcement fields

Presenters:

• app/presenters/v3/access_rule_presenter.rb - API response format
• app/presenters/v3/domain_presenter.rb - Add enforcement fields

Decorators:

• app/decorators/include_access_rule_selector_resource_decorator.rb - Sideload selector resources
• app/decorators/include_access_rule_route_decorator.rb - Sideload routes

Actions:

• app/actions/domain_create.rb - Set enforcement fields (immutable after creation)

Diego Integration:

• lib/cloud_controller/diego/protocol/routing_info.rb - Generate route options

Tests:

• spec/request/access_rules_spec.rb - Full API integration tests
• spec/unit/models/runtime/route_access_rule_spec.rb - Model unit tests
• spec/unit/messages/access_rule*_spec.rb - Message validation tests

Related PRs

• RFC: RFC: Domain-Scoped mTLS for GoRouter community#1438
• routing-release (GoRouter): Add mTLS app-to-app routing support (RFC draft) routing-release#535
• CLI (cf add-access-rule, cf access-rules, etc.): TBD

Testing

All RFC requirements have test coverage:

• ✅ Access Rules CRUD operations
• ✅ Query parameter filtering (guids, route_guids, space_guids, selectors, selector_resource_guids)
• ✅ Include parameter (route, app, space, organization, selector_resource)
• ✅ Metadata (labels/annotations)
• ✅ Read-only relationships
• ✅ Validation rules (enforce_access_rules, internal domains, cf:any exclusivity, duplicates)
• ✅ Permissions (Space Developer required)
• ✅ Diego sync on create/delete

Run tests:

bundle exec rspec spec/request/access_rules_spec.rb
bundle exec rspec spec/unit/models/runtime/route_access_rule_spec.rb

Deployment Notes

1. Run migrations: rake db:migrate
2. Ensure routing-release is deployed with mTLS support
3. No feature flags required - gated by domain configuration (enforce_access_rules)

Breaking Changes

None - this is additive functionality. Existing routes are unaffected.