AuthZen PDP client

[stevenvegt]

Parent PRD

#4144

Summary

New HTTP client for the AuthZen Access Evaluations batch API (POST /access/v1/evaluations). Provides the types and the transport layer for dynamic scope policy evaluation. The server-side token flow in #4179 uses this client to evaluate requested scopes against an external PDP.

What changed

New package policy/authzen:

• types.go — AuthZen request/response types matching the AuthZen spec batch format
• client.go — Thin HTTP client with a single Evaluate method returning map[string]bool (scope → decision)
• client_test.go — Unit tests using httptest.NewServer

Batch format: top-level subject / action / context are shared defaults, and an evaluations array contains per-scope resource overrides. This avoids repeating shared fields for every scope.

Error handling:

• HTTP non-2xx → error with status code, PDP error body truncated to 200 chars (prevents log injection)
• Network errors / cancelled context → wrapped error
• Malformed JSON / evaluation count mismatch → error
• Duplicate resource IDs in request → early error before HTTP call (client-side invariant check)

How to review

Start with types.go — verify the AuthZen request/response shape against the spec (the batch format uses top-level defaults + per-evaluation overrides).

Then client.go — single Evaluate method:

• Sends JSON with Content-Type + Accept headers
• Reads the response through the caller-provided HTTPRequestDoer (StrictHTTPClient is used in wiring for response body limits / timeout)
• Validates evaluation count matches request
• Returns map[string]bool keyed by Resource.ID

Tests (client_test.go) — 8 scenarios covering the full surface: success, partial denial, HTTP 500, unreachable endpoint, cancelled context, count mismatch, malformed response, duplicate resource IDs.

Deviations from spec

• Request type changed from the original spec. The original spec had Resource []Resource, implying a flat batch with multiple resources. During planning we verified this didn't match the AuthZen batch API. Corrected to Evaluations []Evaluation with per-evaluation overrides, matching the spec's top-level-defaults-plus-overrides pattern.
• Claim extraction removed from this PR. Originally the spec included an ExtractSubjectProperties helper. Moved to Server-side multi-scope flow & scope policy evaluation #4179 where the credential map's shape is concrete. This client is transport-only — it takes a pre-built EvaluationsRequest from the caller.
• NewClient signature simplified — no timeout parameter. Timeout is the responsibility of the injected HTTPRequestDoer (wired with StrictHTTPClient in Server-side multi-scope flow & scope policy evaluation #4179).
• Added at self-review: duplicate resource ID precondition check, error body truncation, Accept: application/json header.
• subject.type in the PRD example was updated from "token_request" to "organization" (see PRD comment). The AuthZen client itself is agnostic — the caller sets the type.

Dependencies

Depends on: #4176 (foundation PR, provides the base branch).

Review order: Review #4176 first for the foundation; this PR can then be reviewed independently as it's a self-contained new package with no cross-cutting changes.

Design context

• PRD: Support mixed OAuth2 scopes with configurable scope policy #4144
• AuthZen spec: https://openid.net/specs/authorization-api-1_0.html
• Request format discussion: determined during implementation planning — switched from "multi-resource single evaluation" to "evaluations array" per the spec
• Future enhancement: Consider circuit breaker for AuthZen PDP client #4175 (circuit breaker for PDP calls)

Acceptance Criteria

• AuthZen client sends correctly formatted batch evaluation requests (per AuthZen spec)
• Response parsed into scope → decision map
• Timeout and error handling works correctly
• Evaluation count mismatch detected and reported
• Duplicate resource IDs in request detected (added during self-review)
• Error response body truncated to prevent log injection (added during self-review)
• Unit tests with HTTP mock cover success, partial denial, errors

Original implementation spec (used during AI-assisted development)

Parent PRD

#4144

Implementation Spec

Overview

New HTTP client for the AuthZen batch Access Evaluations API (POST /access/v1/evaluations). This client is used by the server-side token flow (PR #4179) when scope_policy: "dynamic" to evaluate requested scopes against an external PDP.

Key files to create/modify

• policy/authzen/client.go — New HTTP client
• policy/authzen/types.go — Request/response types
• policy/authzen/client_test.go — Unit tests

Design decisions

• Batch format follows the AuthZen spec: top-level subject/action/context are shared defaults, the evaluations array contains per-scope resource overrides. This avoids repeating the same subject/action/context for every scope.
• Claim extraction deferred to PR Server-side multi-scope flow & scope policy evaluation #4179: The ExtractSubjectProperties helper depends on how the credential map from PEX evaluation maps to the organization bucket. This becomes clear in the server-side flow where the actual credential data is available. The AuthZen client takes a pre-built EvaluationsRequest — it doesn't need to know about credentials.
• map[string]bool return type: Denial reasons from the AuthZen response are logged for debugging but not exposed in the return value. Rego-produced reasons are typically terse and few. A richer return type can be added later if operators need it.

AuthZen request/response examples

Request (POST /access/v1/evaluations):

{
  "subject": {
    "type": "token_request",
    "id": "did:web:hospital.example.com",
    "properties": {
      "organization": {
        "id": "did:web:hospital.example.com",
        "name": "Hospital B.V.",
        "ura": "12345678"
      }
    }
  },
  "action": { "name": "request_scope" },
  "context": { "policy": "urn:nuts:medication-overview" },
  "evaluations": [
    { "resource": { "type": "scope", "id": "urn:nuts:medication-overview" } },
    { "resource": { "type": "scope", "id": "patient/Observation.read" } },
    { "resource": { "type": "scope", "id": "launch/patient" } }
  ]
}

Response:

{
  "evaluations": [
    { "decision": true },
    { "decision": true },
    { "decision": false, "context": { "reason": "scope not permitted by policy" } }
  ]
}

Go types

type EvaluationsRequest struct {
    Subject     Subject           `json:"subject"`
    Action      Action            `json:"action"`
    Context     EvaluationContext `json:"context"`
    Evaluations []Evaluation      `json:"evaluations"`
}

type Evaluation struct {
    Resource Resource `json:"resource"`
}

type Subject struct {
    Type       string            `json:"type"`
    ID         string            `json:"id"`
    Properties SubjectProperties `json:"properties"`
}

type SubjectProperties struct {
    Client       map[string]any `json:"client,omitempty"`
    Organization map[string]any `json:"organization,omitempty"`
    User         map[string]any `json:"user,omitempty"`
}

type Action struct {
    Name string `json:"name"`
}

type Resource struct {
    Type string `json:"type"`
    ID   string `json:"id"`
}

type EvaluationContext struct {
    Policy string `json:"policy"`
}

type EvaluationsResponse struct {
    Evaluations []EvaluationResult `json:"evaluations"`
}

type EvaluationResult struct {
    Decision bool                    `json:"decision"`
    Context  *EvaluationResultContext `json:"context,omitempty"`
}

type EvaluationResultContext struct {
    Reason string `json:"reason,omitempty"`
}

Client implementation

type Client struct {
    endpoint   string
    httpClient core.HTTPRequestDoer
}

func NewClient(endpoint string, httpClient core.HTTPRequestDoer) *Client

// Evaluate sends a batch evaluation request for the given scopes.
// Returns a map of scope → decision (true = granted, false = denied).
func (c *Client) Evaluate(ctx context.Context, req EvaluationsRequest) (map[string]bool, error)

The Evaluate method:

1. Serializes the request to JSON.
2. POSTs to {endpoint}/access/v1/evaluations.
3. Parses the response.
4. Maps each evaluation result back to the corresponding scope (by index).
5. Returns a map[string]bool for easy lookup.

Error handling

• HTTP errors (non-2xx) → return error with status code
• Network errors / timeouts → return error (caller maps to 503)
• Malformed response → return error
• Evaluation count mismatch (response has fewer evaluations than scopes) → return error

Testing

• Successful evaluation: batch request → scope→decision map
• Partial denial: some scopes approved, some denied
• HTTP error: PDP returns 500 → error
• Timeout: PDP unreachable → error
• Evaluation count mismatch: response has fewer evaluations than request → error
• Malformed response: invalid JSON → error
• Use httptest.NewServer for HTTP mocking

Acceptance Criteria

• AuthZen client sends correctly formatted batch evaluation requests (per AuthZen spec)
• Response parsed into scope → decision map
• Timeout and error handling works correctly
• Evaluation count mismatch detected and reported
• Duplicate resource IDs in request detected (added during self-review)
• Error response body truncated to prevent log injection (added during self-review)
• Unit tests with HTTP mock cover success, partial denial, errors

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on feature/4144-mixed-scopes by 0.01%.

Modified Files with Diff Coverage (1)

Rating	File	% Diff	Uncovered Line #s
	policy/authzen/client.go	91.3%	52-53, 56-57
	Total	91.3%

🤖 Increase coverage with AI coding...

In the `4144-2-authzen-client` branch, add test coverage for this new code:

- `policy/authzen/client.go` -- Lines 52-53 and 56-57

🚦 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.

[qltysh]

All good ✅