feat: allow custom scope claim name

[alepane21]

Some systems don't use JWT claim "scope" as the claim where they put scopes. In alternative we saw is "scp". This additional config will keep scope as the default value, but will allow users to choose for a different claim if needed.

Summary by CodeRabbit

• New Features

  • Configurable JWT claim name for authorization scopes via a new scope_claim option (default: "scope"); access control respects this setting.

• Tests

  • Added integration and unit tests verifying custom scope-claim parsing and scope enforcement with non-default claim names.

• Documentation

  • Updated docs and examples to document scope_claim and when to set a custom claim (e.g., "scp").

Checklist

• I have discussed my proposed changes in an issue and have received approval to proceed.
• I have followed the coding standards of the project.
• Tests or benchmarks have been added or updated.
• Documentation has been updated on https://github.com/wundergraph/docs-website.
• I have read the Contributors Guide.

Open Source AI Manifesto

This project follows the principles of the Open Source AI Manifesto. Please ensure your contribution aligns with its principles.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds configurable JWT scope-claim support across config, schema, docs, authentication API, AccessController wiring, and tests; ensures runtime authentications use the configured claim name for scopes.

Changes

Cohort / File(s)	Summary
Configuration & Schema router/pkg/config/config.go, router/pkg/config/config.schema.json, router/pkg/config/fixtures/full.yaml, router/pkg/config/testdata/config_defaults.json, router/pkg/config/testdata/config_full.json	Add ScopeClaim to JWT authentication config, YAML/env annotations and JSON schema/default; update fixtures and testdata for custom/default values.
Authentication Implementation & API router/pkg/authentication/authentication.go	Introduce DefaultScopeClaim, add scopeClaim field and SetScopesClaim(scopeClaim string) to the Authentication API; read/write scopes use the configured claim key.
Access Control Wiring router/core/access_controller.go, router/core/supervisor_instance.go	Add ScopeClaim to AccessControllerOptions/AccessController; wire Authentication.JWT.ScopeClaim into AccessController and call auth.SetScopesClaim(...) when authenticators return auth.
Tests & Test Helpers router/pkg/config/config_test.go, router/core/ratelimiter_test.go, router-tests/security/authentication_test.go	Add config tests for explicit/default scope_claim; add SetScopesClaim no-op to FakeAuthenticator; add integration test asserting custom scope claim (scp) is honored at runtime.
Documentation docs-website/router/authentication-and-authorization.mdx, docs-website/router/configuration.mdx	Document new scope_claim JWT option (default scope) and update examples and reference table to show custom scope-claim usage.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat(router): add introspection authentication bypass feature #2192: Modifies AccessController/AccessControllerOptions and related wiring; strongly related to the access-controller field additions in this change.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: allow custom scope claim name' clearly and specifically summarizes the main change—adding support for custom JWT scope claim names—which is consistently reflected across all modified files and test additions.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Router image scan passed

✅ No security vulnerabilities found in image:

ghcr.io/wundergraph/cosmo/router:sha-78e2572aead7a63d0114ae9e474a9b572d436ba3

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@router/pkg/config/config.schema.json`:
- Around line 2105-2109: The schema currently allows an empty string for the
"scope_claim" property, which can lead to empty lookup keys and confusing auth
behavior; update the "scope_claim" definition in config.schema.json (the
property named "scope_claim") to disallow empty values by adding a non-empty
constraint (e.g., add "minLength": 1 or a non-empty "pattern") so the schema
validation rejects "" values. Ensure you only modify the "scope_claim"
property's schema object to include that constraint without changing its type or
description.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d4b272c5-22cd-4860-a1b8-baa8b51e9760

📥 Commits

Reviewing files that changed from the base of the PR and between 43e52a8 and cb2c67b.

📒 Files selected for processing (11)

• router-tests/security/authentication_test.go
• router/core/access_controller.go
• router/core/ratelimiter_test.go
• router/core/supervisor_instance.go
• router/pkg/authentication/authentication.go
• router/pkg/config/config.go
• router/pkg/config/config.schema.json
• router/pkg/config/config_test.go
• router/pkg/config/fixtures/full.yaml
• router/pkg/config/testdata/config_defaults.json
• router/pkg/config/testdata/config_full.json

[codecov]

Codecov Report

❌ Patch coverage is 76.92308% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 63.46%. Comparing base (2ca7b28) to head (9e7f199).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
router/pkg/authentication/authentication.go	77.77%	1 Missing and 1 partial ⚠️
router/core/supervisor_instance.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2724      +/-   ##
==========================================
- Coverage   63.46%   63.46%   -0.01%     
==========================================
  Files         251      251              
  Lines       26767    26777      +10     
==========================================
+ Hits        16989    16994       +5     
- Misses       8415     8419       +4     
- Partials     1363     1364       +1     

Files with missing lines	Coverage Δ
router/core/access_controller.go	81.25% <100.00%> (+1.93%)	⬆️
router/pkg/config/config.go	80.51% <ø> (ø)
router/core/supervisor_instance.go	0.00% <0.00%> (ø)
router/pkg/authentication/authentication.go	80.48% <77.77%> (-2.37%)	⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

router/pkg/authentication/authentication.go (1)

29-37: ⚠️ Potential issue | 🟠 Major

Authentication interface now requires SetScopesClaim method—verify no external implementations exist.

Adding a required method to an exported Go interface is a breaking change. All implementations within the codebase have been updated (authentication struct and FakeAuthenticator test mock), suggesting this is a coordinated change as part of feature eng-9325. However, if this package is consumed by external implementations outside this monorepo, they will break and must be updated to implement SetScopesClaim. Confirm that no external consumers depend on the Authentication interface.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@router/pkg/authentication/authentication.go` around lines 29 - 37, You added
SetScopesClaim to the exported Authentication interface which is a breaking
change; search for any external consumers or implementations of Authentication
(look for references to the Authentication interface symbol and types claiming
to implement it), and update them to implement SetScopesClaim (or provide a
no-op shim) — ensure internal types like authentication and FakeAuthenticator
are updated already, add a short package-level comment documenting the breaking
change, and if this package is consumed externally consider bumping the module
major version or communicate the required change to downstream consumers so
their implementations add SetScopesClaim.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@router/pkg/authentication/authentication.go`:
- Around line 63-68: SetScopesClaim currently allows empty or whitespace-only
scope names which can misroute scope reads/writes; update
authentication.SetScopesClaim to first check a != nil, then trim the input using
strings.TrimSpace and if the trimmed value is empty return without changing
a.scopeClaim, otherwise assign the trimmed value. Add the strings import if
missing and update any callers/tests that assume blank values are accepted.

---

Outside diff comments:
In `@router/pkg/authentication/authentication.go`:
- Around line 29-37: You added SetScopesClaim to the exported Authentication
interface which is a breaking change; search for any external consumers or
implementations of Authentication (look for references to the Authentication
interface symbol and types claiming to implement it), and update them to
implement SetScopesClaim (or provide a no-op shim) — ensure internal types like
authentication and FakeAuthenticator are updated already, add a short
package-level comment documenting the breaking change, and if this package is
consumed externally consider bumping the module major version or communicate the
required change to downstream consumers so their implementations add
SetScopesClaim.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5ce16f2f-d3dd-4348-ad2a-b360bd0c4211

📥 Commits

Reviewing files that changed from the base of the PR and between 0143c03 and e93fd0b.

📒 Files selected for processing (1)

• router/pkg/authentication/authentication.go