Add JsonWebToken header-replacement constructor to avoid re-parsing payload

[shankar-shubh]

Add JsonWebToken header-replacement constructor to avoid re-parsing payload

• You've read the Contributor Guide and Code of Conduct.
• You've included unit or integration tests for your change, where applicable.
• You've included inline docs for your change, where applicable.
• If any gains or losses in performance are possible, you've included benchmarks for your changes. More info
• There's an open issue for the PR that you are making. If you'd like to propose a new feature or change, please open an issue to discuss the change or find an existing issue.

Summary of the changes (Less than 80 chars)

Add a JsonWebToken constructor that reuses a parsed payload on header replacement

Description

Adds a public constructor JsonWebToken(JsonWebToken jsonWebToken, string encodedHeader) that builds a token by replacing the header of an existing JWS while reusing its already-parsed payload and signature. The token is formed as encodedHeader.EncodedPayload.EncodedSignature; only the replacement header is decoded and parsed, so the payload claim set is reused instead of being parsed a second time.

This supports header-only transforms (for example PFT nonce hashing) where callers previously had to reassemble the token string and fully re-read it via ReadJsonWebToken, incurring a redundant payload parse and allocation.

Encrypted (JWE) source tokens are rejected with a new IDX14117 message because their plaintext payload is not available for reuse.

Changes

• New public constructor on JsonWebToken (additive; existing parse paths unchanged).
• New IDX14117 log message for the JWE-source rejection.
• PublicAPI.Unshipped.txt updated for the new public API.
• Unit tests: header replacement, payload/signature reuse, equivalence with a reparsed token, signature validation, null/empty guards, and the JWE rejection path.
• JsonWebTokenHeaderReplacementBenchmarks isolating the new constructor against reassemble-and-reparse.

Benchmarks

Isolated microbenchmark (Microsoft.IdentityModel.Benchmarks, net8.0, MediumRun, MemoryDiagnoser) — reassemble-and-reparse vs. the new constructor:

Token size	Re-parse	Reuse-payload ctor	Time	Allocation
Minimal ~0.7 KB	2,549 ns / 2.63 KB	601 ns / 2.26 KB	-76% (4.2x)	-14%
Small ~1.9 KB	16,758 ns / 11.25 KB	818 ns / 4.81 KB	-95% (20x)	-57%
Typical ~4 KB	47,911 ns / 24.30 KB	1,079 ns / 8.85 KB	-98% (44x)	-64%

The eliminated payload parse scales with payload size, so the win grows with the token.

Fixes #3529

[shankar-shubh]

@microsoft-github-policy-service agree company="Microsoft"

[iNinja]

Nice perf win. One thought on the public surface: the new ctor reuses the original signature with a swapped header. That's exactly right for the PFT nonce-hashing case the description mentions (the new header reconstructs the originally-signed bytes), but as a general public ctor it lets any caller swap a header and silently keep an invalid signature.

Could we expose this through JsonWebTokenHandler instead, e.g.:

public virtual JsonWebToken ReplaceTokenHeader(JsonWebToken jsonWebToken, string encodedHeader)

Same payload-reuse perf, but it sits next to ReadJsonWebToken, reads as an intentional transform rather than a general-purpose ctor, and is mockable. The XML doc should note the signature is preserved as-is and only validates when the header reconstructs the originally-signed form (as in PFT). Suggest dropping the ctor from the public API and adding the handler method.

[shankar-shubh]

@iNinja Have updated the PR as per the comment.

[MZOLN]

Left some comments

[bgavrilMS]

nit: it's not clear why JWEs aren't supported