fix: Harden webhook, vault, session, and base client paths

[gjtorikian]

Summary

• Webhook/action signature verification: reject future-skewed timestamps in webhooks/_resource, webhooks/_verification, and actions._verify_signature by comparing abs(seconds_since_issued); honor an explicit tolerance=0 (was silently coerced to the 180s default).
• Vault crypto: preserve empty associated_data/aad (was dropped, causing encrypt/decrypt AAD divergence) and bound _decode_u32_leb128 to 32 bits so a malformed payload can't yield a >32-bit key_len. Empty-AAD ciphertexts written by older SDKs need migration — noted for release notes.
• Public client isolation: create_public_client now forces api_key=None and sets is_public=True, so a PKCE/public client cannot pick up WORKOS_API_KEY from the process env.
• Session refresh: map auth-flow/network exceptions to structured AuthenticateWithSessionCookieFailureReason members (MFA_CHALLENGE_REQUIRED, SSO_REQUIRED, EMAIL_VERIFICATION_REQUIRED, ORGANIZATION_SELECTION_REQUIRED, REFRESH_DENIED, REFRESH_NETWORK_ERROR) instead of stringifying. Additive — string consumers keep working.
• Base client URL safety: percent-encode every path segment via a single _encode_path helper so user-supplied identifiers can't escape their segment with /, ?, #, or %. Covers all ~115 generated call sites.

Test plan

• uv run ruff format --check .
• uv run ruff check .
• uv run pyright
• uv run pytest (in particular tests/test_actions.py, tests/test_webhook_verification.py, vault, session, and base-client suites)
• Manually verify a public client built via create_public_client does not include client_secret even when WORKOS_API_KEY is set in the environment
• Confirm release notes call out the empty-AAD wire-format change for locally-persisted vault ciphertexts

[greptile-apps]

Greptile Summary

This PR hardens several security-critical code paths: webhook/action signature verification now rejects future-skewed timestamps with abs() and honours an explicit tolerance=0; create_public_client forces the server credential to None so the process-env value cannot leak into PKCE flows; the LEB128 decoder in vault is bounded to 32 bits; and session-refresh exceptions are mapped to structured enum members instead of raw strings.

• Path encoding (_base_client.py): all ~115 call-sites converted from bare f-string paths to tuple segments; _encode_path percent-encodes each segment with quote(seg, safe=\"\") and rejects bare strings with a TypeError, preventing ?, #, and % injection into path segments.
• Vault LEB128 (vault.py): _decode_u32_leb128 now caps the byte-count at 5 and validates the final value against 0xFFFFFFFF, preventing a crafted payload from yielding a key-blob length larger than 32 bits.
• Session refresh (session.py): _map_refresh_exception_to_reason maps all auth-flow and network exceptions to AuthenticateWithSessionCookieFailureReason enum members; unknown exceptions fall back to str(exc) for backward compatibility.

Confidence Score: 5/5

Safe to merge; all security-relevant changes are internally consistent and the new tests confirm the intended behavior.

The changes are well-scoped and correctly implemented: timestamp skew is now rejected symmetrically with abs(), explicit zero tolerance is honoured, the public-client factory reliably clears the server credential regardless of environment, LEB128 decoding is bounded to 32 bits with two independent guards, and session-refresh exceptions are exhaustively mapped to structured enum members. No new logic errors were found.

No files require special attention beyond what was flagged in prior review rounds.

Important Files Changed

Filename	Overview
src/workos/_base_client.py	Adds _encode_path static method that percent-encodes tuple segments; all request/build_url methods now require Sequence[str] paths. is_public flag correctly suppresses env-var credential lookup.
src/workos/vault.py	_decode_u32_leb128 now raises on 5-byte LEB128 with continuation bit set and checks final value against 0xFFFFFFFF. All KV paths converted to segment tuples.
src/workos/session.py	Adds _map_refresh_exception_to_reason mapping all auth-flow and network exceptions to AuthenticateWithSessionCookieFailureReason enum members; unknown exceptions fall back to str(exc).
src/workos/webhooks/_verification.py	abs() wraps seconds_since_issued to reject future-skewed timestamps. tolerance is now checked via is not None so an explicit tolerance=0 is honoured instead of falling back to 180s default.
src/workos/actions.py	abs() added around seconds_since_issued in _verify_signature; future-dated action timestamps are now correctly rejected.
src/workos/public_client.py	create_public_client now passes is_public=True so the client credential is forced to None regardless of what the process environment contains, preventing credential leakage in PKCE flows.
src/workos/webhooks/_resource.py	Both sync and async Webhooks.verify_header now use abs() for timestamp comparison and tolerance is not None guard, matching the standalone _verification.py fixes.
tests/test_actions.py	New tests cover future-timestamp rejection confirming the abs() fix is exercised.
tests/test_session.py	Tests cover _map_refresh_exception_to_reason for all mapped exception types and the generic fallback.

_{Reviews (5): Last reviewed commit: "fix(client): pass path as sequence of se..." | Re-trigger Greptile}