fix: harden JWT signature verification and URL path encoding

[gjtorikian]

Summary

• Verify access-token JWS signatures against the JWKS in SessionManager::decodeAccessToken, with an RS256 allow-list that rejects alg: none, missing/unknown kid, tampered signatures, and tokens lacking a matching JWK. Expiration is now checked only after signature verification.
• Issuer/audience enforcement is intentionally deferred (TODO) until the documented WorkOS values are confirmed; mirrors current Ruby/Python SDK behavior.
• Centralize RFC 3986 path-segment encoding in HttpClient::resolveUrl so an untrusted ID interpolated into a path template (e.g. om_xyz?/foo) cannot escape its segment into a new path or query. Pre-encoded triplets from existing rawurlencode callers are preserved (no double-encoding).
• Stabilize the tampered-signature test by flipping a middle byte of the JWS signature instead of the last base64url char, which could canonicalise back to the original bytes.

Test plan

• composer test passes (HttpClient + SessionManager suites)
• Confirm existing services that already rawurlencode IDs are not double-encoded
• Manually verify a tampered access token is rejected end-to-end
• Confirm tokens with alg: none or unknown kid are rejected

[greptile-apps]

Greptile Summary

This PR adds proper JWS signature verification to SessionManager::decodeAccessToken (RS256 allow-list, JWKS-based key lookup with in-memory caching, key-rotation refresh), and centralizes RFC 3986 path-segment encoding in HttpClient::encodePathSegments so that non-slash special characters like ? and # in interpolated IDs are encoded before they can open a new query or fragment.

• lib/SessionManager.php: Rewrites decodeAccessToken to validate the JWS header alg against an RS256 allow-list, fetch/cache JWKS by clientId, match JWK by kid, build an RSA public key from the DER-encoded JWK, verify the signature with openssl_verify, and check expiration only after successful verification. Adds a manual RSA JWK → PEM converter to avoid a new dependency. Adds a 5-minute in-memory JWKS cache with forced-refresh on kid miss.
• lib/HttpClient.php: Adds encodePathSegments/encodePathSegment to percent-encode unsafe non-slash characters in each URL path segment while preserving already-encoded %XX triplets, preventing a raw ? or # in an ID from opening a spurious query/fragment.
• tests/: New tests cover valid signatures, tampered signatures, alg: none, unknown kid, JWKS caching, and key-rotation refresh; HttpClientTest pins both the double-encoding-free and raw-slash caveat behaviors.

Confidence Score: 5/5

Safe to merge; the JWS verification path is sound, the JWKS cache is correctly implemented, and the path-encoding change is well-tested with documented caveats.

The core security additions — RS256-only algorithm enforcement, per-kid JWKS lookup with forced-refresh on miss, manual DER/PEM construction, and openssl_verify integration — are all implemented correctly. The DER OID encoding is byte-accurate. All current throw sites inside decodeAccessToken extend Exception, so the catch block is complete for today's code paths. The only open items are defensive hardening suggestions that do not represent present defects.

No files require special attention; the three suggestions on lib/SessionManager.php are defensive hardening, not corrections to current broken behaviour.

Important Files Changed

Filename	Overview
lib/SessionManager.php	Rewrites decodeAccessToken with RS256-only JWS verification, JWKS caching, and manual RSA JWK-to-PEM DER construction; all suggestion comments are defensive hardening rather than corrections to broken behaviour.
lib/HttpClient.php	Adds encodePathSegments/encodePathSegment to resolve non-slash special characters in path IDs before URL assembly; raw / inside an unencoded ID still acts as a separator (documented caveat), no double-encoding issues.
tests/SessionManagerTest.php	Adds tests for valid RS256 token, tampered signature, alg:none rejection, unknown kid (with two queued responses to reach the intended guard), JWKS caching, and key-rotation refresh; all test scenarios are well-constructed.
tests/HttpClientTest.php	Adds tests for no-double-encoding of pre-encoded IDs, ? encoding in raw segments, and the documented raw-slash caveat; behavioral contract is clearly pinned.

_{Reviews (5): Last reviewed commit: "chore(session,http): address Greptile re..." | Re-trigger Greptile}

[greptile-apps]

iss and aud claims are not validated

Team policy (rule e0f82177) requires that JWTs always have their iss and aud claims validated. The TODO defers this indefinitely, leaving the door open for tokens issued by a different issuer or intended for a different audience to be accepted. An attacker with a valid WorkOS-signed token for a different client application (different aud) or a different issuer would still pass signature verification and be treated as authenticated. The Ruby/Python SDK comparison in the comment is not sufficient justification when the org's own policy mandates validation.

Rule Used: JWTs should always be validated before use and the... (source)

[gjtorikian]

Acknowledged on the rule, but I want to flag why this PR keeps the TODO rather than fixing it inline:

I checked the canonical workos-node SDK — its isValidJwt (in src/user-management/session.ts) calls jwtVerify(accessToken, jwks) with no issuer or audience options, so jose verifies signature + alg + exp only. There are zero iss/aud string literals anywhere in workos-node's source or tests. Combined with the Ruby/Python SDKs already skipping aud, none of the WorkOS SDKs currently validate these claims, and the canonical values aren't documented in any SDK repo.

If I hard-code defensible guesses (e.g. iss = baseUrl, aud = clientId) and the real tokens use something else (e.g. iss = https://api.workos.com/user_management/{clientId}), every production caller's session check breaks on upgrade. That's a worse outcome than the cross-tenant risk this rule targets — which already requires a WorkOS-signed token and a way to plant it in the victim's sealed cookie.

Plan: I'll get the canonical iss/aud values from the auth team and add validation in a follow-up PR. The TODO and rationale will be expanded to reference this conversation so the deferral is explicit.