Replace (string) casts on JSON payload values with is_string guards

[turegjorup]

Summary

Pre-existing follow-up flagged during PR #41's review. Two (string) casts in OpenIdConfigurationProvider coerced JSON-decoded mixed values into strings:

• $kid = (string) $key['kid']; — JWK key identifier (RFC 7517 §4.5 specifies it as a JSON string).
• $value = (string) $configuration[$key]; — OIDC discovery document value (OIDC Discovery specifies these as strings).

Both spec-compliant payloads work today. The cast silently masks the malformed-payload case: an int / bool / array gets coerced to a useless string ("42", "", "Array") that flows downstream and produces a confusing assertion failure rather than diagnosing "the IdP returned a malformed payload at this key".

What changes

Each cast is replaced with an is_string guard that throws an appropriate typed exception:

• JWK with non-string kid → KeyException('JWK entry missing string "kid" (RFC 7517 §4.5)').
• Discovery doc with non-string value at a required key → CacheException(sprintf('OIDC discovery document value for "%s" is not a string (got %s)', $key, get_debug_type(...))).

Both KeyException and CacheException already implement OpenIdConnectExceptionInterface (per the 5.0 contract), so consumers catching the marker pick up the new throw paths without code changes.

Backward compatibility

Spec-compliant IdPs (every IdP we test against) are unaffected. The new throw paths only fire when the upstream payload violates the spec — and in that case the new behaviour is strictly better than silent coercion.

The two new throws share the same OpenIdConnectExceptionInterface marker as their pre-existing siblings; existing catch (OpenIdConnectExceptionInterface) blocks pick them up automatically. Documented under the 5.0 BREAKING section of the CHANGELOG.

Test plan

• task test:coverage — 89 tests; 100% coverage on OpenIdConfigurationProvider (24/24 methods, 151/151 lines including the two new throw lines).
• task analyze:php — PHPStan level 8, no errors.
• task lint:php — clean.
• task lint:markdown — clean.
• CI matrix on PR (PHP 8.3/8.4/8.5 × stable/lowest).

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (1774bc0) to head (39ac2f8).

Additional details and impacted files

@@             Coverage Diff             @@
##             develop       #42   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
- Complexity        62        64    +2     
===========================================
  Files              1         1           
  Lines            172       175    +3     
===========================================
+ Hits             172       175    +3     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jekuaitk]

I know the existing code throws a CacheException here, but surely theres a more fitting exception?

[turegjorup]

Added new MetadataException

<?php

namespace ItkDev\OpenIdConnect\Exception;

/**
 * Thrown when the IdP-returned OIDC discovery metadata does not conform to the
 * OIDC Discovery spec — for example, a required key is missing or has the
 * wrong type. Distinct from `JsonException` (the document didn't even parse)
 * and `CacheException` (the cache layer failed): the JSON parsed fine, the
 * cache is fine, but the document's contents are structurally invalid.
 *
 * Consumers typically can't recover by retrying — the IdP needs to fix the
 * payload — so a `catch (MetadataException $e)` block normally logs + alerts.
 */
class MetadataException extends \RuntimeException implements OpenIdConnectExceptionInterface
{
}