Token introspection verification & integration tests

[stevenvegt]

Parent PRD

#4144

Summary

Final PR in the mixed OAuth2 scopes feature. Adds focused end-to-end integration tests for the dynamic scope policy path — real authzen.Client calls, httptest.NewServer standing in for the PDP — validating the HTTP roundtrip that mock-based unit tests skip.

No production code changes.

What changed

auth/api/iam/integration_test.go (new, +176) — one TestIntegration_DynamicScopePolicy_AuthZenEndToEnd with three subtests, each wiring a real authzen.Client pointed at an httptest.NewServer:

1. PDP approves all scopes — token contains all scopes and the captured AuthZen request shape is asserted on the wire (subject.type=organization, action.name=request_scope, context.policy, evaluations in request order).
2. PDP partial denial — denied extra scope excluded from token.Scope.
3. PDP denies credential profile scope — rejected with access_denied, no token issued.

How to review

Read the test doc comment first — it states explicitly what's not covered to avoid duplicating policy/authzen/client_test.go (HTTP errors, timeouts) and s2s_vptoken_test.go (VP validation, profile-only rejection).

Then the three subtests. The startPDP helper both responds with canned decisions and captures the decoded request for post-call assertions. Subtest 1 is the only place where AuthZen request serialization is validated over the wire — evaluation order, context.policy, and subject.type all originate in code paths that unit tests mock past.

Deviations from spec

• Dropped 6 of the originally-planned test cases during self-review:
  • HTTP 500 / network errors / timeouts — covered by policy/authzen/client_test.go
  • Profile-only / passthrough integration — covered by s2s_vptoken_test.go
  • Multi-scope introspection — introspection is pointer pass-through of token.Scope; no multi-scope-specific logic
  • Backwards-compatibility — no version-specific code path
• Added access_denied integration (not in spec) — identified as security-critical during self-review.
• Final suite: 3 focused tests instead of the spec's 6.

Dependencies

Depends on: #4179 (server-side multi-scope flow) — provides handleS2SAccessTokenRequest and PDPBackend.AuthZenEvaluator() that these tests exercise. Transitively depends on #4176, #4177, #4178.

Review order: #4176 → #4177 → #4178 → #4179 → #4180. No new production API here, so the review value is confirming the scenarios are the right ones and the assertions catch what matters.

Design context

• PRD: Support mixed OAuth2 scopes with configurable scope policy #4144
• AuthZen request format: PRD section "AuthZen integration" + comment 4241925733 (subject.type = organization)
• Deny semantics: PRD comment 4235524867 (partial denial excludes scopes; credential-profile-scope denial errors) — maps to subtests 2 and 3

Acceptance Criteria

• Integration tests cover the dynamic scope policy end-to-end (real HTTP)
• Security-critical paths (access_denied) validated over real HTTP
• Request serialization verified on the wire
• No production code changes needed (introspection passes token.Scope through unchanged)
• Scope justified in the test doc comment (what's covered vs. intentionally not)
• Multi-scope introspection tests — dropped: no multi-scope-specific code exists
• Profile-only/passthrough integration tests — dropped: covered by existing unit tests
• HTTP error / timeout integration tests — dropped: covered by policy/authzen/client_test.go

Original implementation spec (used during AI-assisted development)

Parent PRD

#4144

Implementation Spec

Overview

Final PR in the mixed OAuth2 scopes feature. Adds end-to-end integration tests that exercise the dynamic scope policy path with a real AuthZen HTTP client (via httptest.NewServer), validating the full HTTP roundtrip that mock-based unit tests skip over.

No production code changes.

Key files

• auth/api/iam/integration_test.go (new) — E2E integration tests for dynamic scope policy

Design decisions

Scope narrowed during self-review. The spec suggested a broad set of integration tests covering all scope policies and introspection behavior. On review, many would duplicate existing unit tests or test trivial pointer pass-through. The final test suite is focused on what actually requires integration:

• Real HTTP roundtrip for dynamic scope policy — exercises request serialization, response parsing, and end-to-end wiring that mock-based unit tests don't reach.
• Security-critical path — PDP denying the credential profile scope over real HTTP.

Tests explicitly not included (and why):

• HTTP 500 / network errors — already covered by policy/authzen/client_test.go
• Profile-only / passthrough integration — already covered by s2s_vptoken_test.go unit tests
• Multi-scope introspection — introspection is Scope: &token.Scope (pointer pass-through); no multi-scope logic exists
• Backwards compatibility — no version-specific code path to test

Tests added

TestIntegration_DynamicScopePolicy_AuthZenEndToEnd — uses real authzen.Client pointing at httptest.NewServer:

1. PDP approves all scopes — asserts the token contains all scopes AND that the HTTP request body had the correct shape over the wire (subject.type=organization, action.name=request_scope, context.policy, ordered evaluations)
2. PDP partial denial — denied scopes excluded from the token
3. PDP denies credential profile scope — request rejected with access_denied, no token issued

Deviations from original spec

• Dropped 6 proposed test cases as duplicative or trivial (see design decisions)
• Added access_denied integration test (originally not in spec but identified as security-critical during review)
• Consolidated to 3 focused tests instead of 6

Acceptance Criteria

• Integration tests cover the dynamic scope policy end-to-end (real HTTP)
• Security-critical paths (access_denied) validated over real HTTP
• Request serialization verified on the wire
• No production code changes needed (confirmed: introspection passes token.Scope through unchanged)
• Multi-scope introspection tests — dropped: no multi-scope-specific code exists to test
• Profile-only/passthrough integration tests — dropped: covered by existing unit tests

[qltysh]

Coverage Impact

⬇️ Merging this pull request will decrease total coverage on feature/4144-mixed-scopes by 0.02%.

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.