feat: add DPoP sender-constrained token support (RFC 9449)

[davidbemer]

Summary

• Implements DPoP (Demonstrated Proof of Possession, RFC 9449) proof validation for sender-constrained session tokens
• Adds DPoPUtils.validateDPoPProof() implementing the full RFC 9449 §7.1-7.2 algorithm (all JOSE asymmetric algorithms: RS*, ES*, PS*, EdDSA)
• Adds AuthenticationService.validateDPoP() — validates the DPoP proof after session token validation; no-op when the token has no cnf.jkt claim
• Mirrors the Go SDK implementation: feat: add DPoP Proof Validation (RFC 9449) go-sdk#737

Test plan

• Unit tests in DPoPUtilsTest: valid ES256 proof, valid RS256 proof, wrong method, wrong URL, wrong key, empty/malformed proof, max-length exceeded, default-port normalization (:443 == no port)
• Verify existing tests continue to pass (mvn test)

🤖 Generated with Claude Code

[shuni-bot-dev]

🐕 Review complete — View session on Shuni Portal 🐾

[shuni-bot-dev]

🐕 Shuni's Review

Adds RFC 9449 DPoP proof validation mirroring the Go SDK. Crypto logic looks solid for RS*/ES*/PS*; tests cover the main paths.

Sniffed out 2 issues:

• 1 🟠 HIGH: EdDSA OKP key decoding doesn't clear the x-sign bit before computing y — rejects ~50% of valid Ed25519/Ed448 proofs
• 1 🟡 MEDIUM: Unchecked (String)/(Number) casts on JWT claims leak ClassCastException instead of ClientFunctionalException for malformed proofs

See inline comments for details. Woof!

[shuni-bot-dev]

🟠 HIGH: The x-sign bit is not cleared before computing the y coordinate. Per RFC 8032 §5.1.2, the encoded Ed25519/Ed448 public key stores the x-sign in the high bit of the last (little-endian) byte; that bit must be masked off before the remaining bits are interpreted as y. As written, when the sign bit is set, BigInteger(1, reverseBytes(xBytes)) produces y_expected + 2^255 (Ed25519), which is outside the valid range and will cause KeyFactory.generatePublic to throw — so roughly half of otherwise-valid EdDSA proofs will be rejected as signature verification failed. EdDSA is advertised in ALLOWED_ALGS (line 35) but never exercised by tests, which is why this slipped through.

Suggested change

	new java.security.spec.EdECPoint(
	(xBytes[xBytes.length - 1] & 0x80) != 0,
	new BigInteger(1, reverseBytes(xBytes))
	));
	byte[] yBytes = xBytes.clone();
	yBytes[yBytes.length - 1] &= 0x7F; // clear x-sign bit before computing y
	java.security.spec.EdECPublicKeySpec edSpec =
	new java.security.spec.EdECPublicKeySpec(namedSpec,
	new java.security.spec.EdECPoint(
	(xBytes[xBytes.length - 1] & 0x80) != 0,
	new BigInteger(1, reverseBytes(yBytes))
	));

[davidbemer]

Fixed. Replaced the Java 15+ EdECPublicKeySpec/NamedParameterSpec/EdECPoint approach entirely with BouncyCastle (bcprov-jdk18on, already in pom.xml, scope changed from runtime to compile). The new importOKPKey builds a minimal DER SubjectPublicKeyInfo (OID + BIT STRING of the raw key bytes), then uses KeyFactory.getInstance("Ed25519", "BC") with an X509EncodedKeySpec. BouncyCastle's Ed25519 decoder handles the RFC 8032 §5.1.2 compressed encoding natively — the sign bit in the MSB of the last byte is consumed correctly without any manual masking needed.

[shuni-bot-dev]

🟡 MEDIUM: Several JWT claim casts are not wrapped in a try/catch and will leak ClassCastException (or NullPointerException for method) instead of ClientFunctionalException.invalidToken if a caller supplies a malformed proof:

• L127 (String) header.get("alg") — non-string alg
• L135 (Map<String, Object>) header.get("jwk") — non-object jwk
• L181 / L188 / L201 / L226 (String) payload.get(...) for jti/htm/htu/ath
• L195 method.equals(htm) — NPE if caller passes method == null
• L217 ((Number) iatObj).longValue() — non-numeric iat

A malicious or buggy client can change the exception type observed by callers (callers catching DescopeException/ClientFunctionalException will miss the error and may leak a stack trace). Wrap the post-parse extraction in a try/catch that maps unexpected types to ClientFunctionalException.invalidToken(...), or validate types explicitly (e.g. if (!(header.get("alg") instanceof String))).

[davidbemer]

Fixed. All unchecked casts in the payload and header parsing are now guarded by instanceof checks. Specifically: alg uses instanceof String, jwk uses instanceof Map (the separate null check was removed as instanceof handles null), jti/htm/htu/ath all use instanceof String, and iat uses instanceof Number. Any type mismatch now throws ClientFunctionalException.invalidToken instead of ClassCastException.

[Copilot]

Pull request overview

Adds DPoP (RFC 9449) proof validation to the Java SDK so session tokens with cnf.jkt can be sender-constrained, exposing a new AuthenticationService.validateDPoP(...) API plus documentation and unit tests.

Changes:

• Introduces DPoPUtils.validateDPoPProof(...) to validate DPoP proof JWS headers/claims, signature, ath, and JWK thumbprint (jkt).
• Exposes DPoP validation via AuthenticationService.validateDPoP(...) and wires it in AuthenticationServiceImpl.
• Adds README usage docs and a new DPoPUtilsTest covering several success/error paths.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/main/java/com/descope/utils/DPoPUtils.java	New DPoP validation utility implementing proof parsing, signature verification, URL/method checks, and JWK thumbprint binding.
src/test/java/com/descope/utils/DPoPUtilsTest.java	New unit tests for DPoP thumbprint extraction and core validation scenarios (ES256/RS256 + error cases).
src/main/java/com/descope/sdk/auth/AuthenticationService.java	Adds public API method to validate DPoP proofs for DPoP-bound session tokens.
src/main/java/com/descope/sdk/auth/impl/AuthenticationServiceImpl.java	Implements the new validateDPoP API and delegates to DPoPUtils.
README.md	Documents how to call validateDPoP after validating a session token.

Comments suppressed due to low confidence (1)

src/test/java/com/descope/utils/DPoPUtilsTest.java:110

• This file uses Java 11+ APIs (e.g., String.repeat) and will not compile with the project’s Java 8 target. Replace with a Java 8-compatible way to generate a long string (e.g., loop/StringBuilder) to keep tests compiling under <maven.compiler.source>1.8.</comment_content>

    String sessionToken = buildRawJwtWithJkt(jkt);

    String longProof = "a".repeat(8193);
    assertThrows(ClientFunctionalException.class, () ->
        DPoPUtils.validateDPoPProof(longProof, "GET", "https://api.example.com/resource", sessionToken));

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[davidbemer]

Fixed. Removed unused imports BigInteger, URI, AlgorithmParameters, and ECParameterSpec from DPoPUtilsTest.java. These were only referenced in a comment (BigInteger) or not at all.

[davidbemer]

Fixed. Replaced all Java 15+ APIs (NamedParameterSpec, EdECPublicKeySpec, EdECPoint) with a BouncyCastle-based approach that is Java 8 compatible. The new implementation builds a DER-encoded SubjectPublicKeyInfo for the Ed25519/Ed448 key and uses KeyFactory.getInstance(algorithm, "BC") with an X509EncodedKeySpec. BouncyCastle (bcprov-jdk18on 1.84) is already in pom.xml; its scope was changed from runtime to compile since we now reference it at compile time.

[davidbemer]

Fixed. All lines in DPoPUtils.java have been verified to be within the 120-character Checkstyle limit. The new OKP implementation uses intermediate variables and wrapped method calls to stay within the limit.

[davidbemer]

Fixed. Changed method.equals(htm) to htm.equals(method). Since htm is already validated as non-null/non-empty by the instanceof+isEmpty check immediately above, this is safe and also avoids NPE if the caller passes null for method (which is now also guarded upstream in AuthenticationServiceImpl.validateDPoP).

[davidbemer]

Fixed. Added instanceof Number check before casting iat: if the claim is absent, null, or not a Number, the code now throws ClientFunctionalException.invalidToken with message 'missing iat'.

[davidbemer]

Fixed. Changed validateDPoP from an abstract method to a default method in the AuthenticationService interface. The default implementation throws UnsupportedOperationException, which preserves backward compatibility: existing interface implementations that predate DPoP support will compile without change and fail loudly at runtime only if the new method is actually called.

[davidbemer]

Fixed. Added StringUtils.isBlank checks for both method and requestUrl in AuthenticationServiceImpl.validateDPoP, throwing ServerCommonException.invalidArgument for either missing value. This prevents NPE from propagating into DPoPUtils and returns a clear error to the caller.

[davidbemer]

Fixed. Rewrote the Javadoc to accurately describe the implementation: BouncyCastle is used directly (via SubjectPublicKeyInfo + X509EncodedKeySpec pattern) for Java 8 compatibility. Removed the incorrect mention of a 'fallback' — BouncyCastle is the primary and only implementation.

[davidbemer]

Replay protection (jti) — Deferred

jti replay tracking requires server-side storage (e.g. a distributed cache of seen jti values within the proof's validity window) which a stateless SDK cannot provide, matching the go-sdk reference implementation (descope/go-sdk#737). A note has been added to the validateDPoPProof Javadoc calling this out explicitly so callers are aware they need to handle replay protection in their own infrastructure if required.

[davidbemer]

Fixed: resolved checkstyle violations (OneStatementPerLine in switch cases, LocalVariableName for EC coordinates, JavadocParagraph) and replaced String.repeat() with Java 8 compatible alternative.