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 five distinct security and correctness surface areas across the WorkOS Python SDK: webhook/action timestamp validation, vault LEB128 payload parsing, public-client credential isolation, session refresh exception mapping, and URL path encoding.

• Timestamp validation: All three signature-verification paths now use abs(seconds_since_issued) to reject both old and future-skewed timestamps; _verification.py also fixes the tolerance or DEFAULT pattern so an explicit tolerance=0 is honoured rather than silently overridden.
• Vault LEB128 hardening: _decode_u32_leb128 now raises on the 5th byte when a continuation bit is set (i >= 4 and b & 0x80 != 0) and adds a res > 0xFFFFFFFF guard, closing a window where a malformed payload could yield a key-length larger than 32 bits.
• Public client isolation + path encoding: create_public_client forces is_public=True to prevent server credentials from leaking into PKCE flows; a new _encode_path helper percent-encodes every user-supplied path segment across all request call sites to block path-traversal via reserved characters.

Confidence Score: 5/5

Safe to merge — all five hardening areas are narrowly scoped, well-tested, and additive; the only behavioural break is the empty-AAD vault wire format, which the PR description already flags for release notes.

Each change is a tightly contained correctness fix (abs-wrap, None-guard, LEB128 bit-boundary check, public-client credential null-out, path segment encoding). The MfaEnrollmentError gap flagged in a prior review thread is now mapped. Tests cover future-timestamp rejection, tolerance=0, all eleven exception-to-reason mappings, and the unknown-exception fallback. No regressions introduced on the reviewed paths.

No files require special attention. The vault _aes_gcm_encrypt/_aes_gcm_decrypt if-aad guards are unchanged (the empty-AAD wire-format note in the PR description is documentation/release-notes scope, not a code defect in this diff).

Important Files Changed

Filename	Overview
src/workos/_base_client.py	Adds _encode_path static helper to percent-encode path segments, wiring it into both sync and async request methods; adds is_public constructor flag that forces the auth credential to None so public PKCE clients cannot inherit server credentials from the process environment.
src/workos/actions.py	Single-line fix: wraps seconds_since_issued in abs() to reject future-skewed timestamps. Tolerance is a mandatory int default, so no tolerance=0 hole exists here.
src/workos/public_client.py	Sets is_public=True on the underlying client constructor and nulls out the auth credential at construction time, ensuring public PKCE clients never carry server-side credentials.
src/workos/session.py	Adds _map_refresh_exception_to_reason helper mapping all AuthenticationFlowError/AuthenticationError/network errors to structured enum members (including the previously-missing MfaEnrollmentError); replaces bare str(e) in refresh paths.
src/workos/vault.py	Tightens _decode_u32_leb128: raises on a 5th continuation byte (i >= 4 and b & 0x80 != 0) and adds an explicit res > 0xFFFFFFFF guard so a valid 5-byte encoding that encodes a >32-bit value is still rejected.
src/workos/webhooks/_verification.py	Fixes two bugs: (1) replaces tolerance or DEFAULT_TOLERANCE with tolerance if tolerance is not None else DEFAULT_TOLERANCE to honour an explicit tolerance=0; (2) wraps seconds_since_issued in abs() to catch future-dated timestamps.
src/workos/webhooks/_resource.py	Applies the same abs(seconds_since_issued) fix in both the sync Webhooks and async AsyncWebhooks class implementations.
tests/test_session.py	Adds TestMapRefreshExceptionToReason parametrized suite covering all 11 exception-to-reason mappings plus the unknown-exception fallback string.
tests/test_webhook_verification.py	Adds future-timestamp rejection tests for both the class-based and standalone webhook verifier, and adds a tolerance=0 test confirming the explicit-zero fix in _verification.py.
tests/test_actions.py	Adds test_verify_header_future_timestamp to verify the abs() fix rejects a timestamp 60 seconds in the future within a 30-second tolerance window.

_{Reviews (3): Last reviewed commit: "Revert "fix: preserve empty AAD in vault..." | Re-trigger Greptile}