fix: harden session sealing, log redaction, and webhook tolerance checks

[gjtorikian]

Summary

• Session cookie_password hardening: require cookie_password.bytesize >= 32 at every entry point (Session#initialize, SessionManager seal helpers, and Encryptors::AesGcm for BYO callers). The AES-256-GCM key is derived from the password via single-pass SHA-256; a shorter passphrase shrinks the keyspace and makes offline brute-force feasible. Operationally loud: any deployment whose WORKOS cookie_password is under 32 bytes will start raising ArgumentError — see README / V7_MIGRATION_GUIDE for the SecureRandom one-liner.
• Session refresh durability: persist @seal_data / @cookie_password before decoding the freshly-minted access token, and surface the rotated cookie on the result struct from both code paths — RefreshSuccess#sealed_session on the happy path and RefreshError#sealed_session on the JWT::DecodeError rescue. The AuthenticationError / InvalidRequestError rescue intentionally does not populate sealed_session: those fire before WorkOS rotates the refresh token, so no new cookie exists. End result: a transient JWKS failure no longer strands a typical Rails-style caller on the pre-rotation (revoked) refresh token — they can write result.sealed_session to the browser unconditionally when present. Source user / impersonator / organization_id from the auth response directly.
• Exp-less JWT handled as expired: treat decoded["exp"].nil? as expired in Session#authenticate so include_expired: true cannot return authenticated: true for a token without an expiry. required_claims: ['exp'] on JWT.decode was considered and rejected for cross-SDK parity — workos-node's jose call and workos-php's isset($exp) && $exp < time() both accept exp-less tokens, and WorkOS-issued tokens always carry exp, so tightening Ruby unilaterally only shifts the reason code (INVALID_JWT vs EXPIRED_JWT) without meaningful defense-in-depth. See 9ce069f for the full rationale; coordinated iss/aud/exp hardening will land as a cross-SDK change.
• Base client log redaction: redact bearer-token path segments (invitation by_token, magic_auth, password reset, email verification, sessions authorize/logout) before they hit :debug / :info / :warn log lines. Wire request is unchanged.
• Symmetric tolerance in Webhooks#verify_header and Actions#verify_header: use .abs so a future-dated timestamp (clock skew or attacker-supplied) is rejected like a stale one.
• PKCE helper hygiene: UserManagement#get_authorization_url_with_pkce now strips caller-supplied code_challenge / code_challenge_method from **opts, mirroring the existing :state pattern, so callers can't override the freshly-generated challenge or trigger an ArgumentError collision.

Compatibility note on RefreshError

RefreshError gains an optional :sealed_session field. This is non-breaking under keyword_init: true: existing RefreshError.new(authenticated: ..., reason: ...) constructions still work, == between old and new instances holds (the new field defaults to nil), and callers who previously got NoMethodError on .sealed_session now get nil. Already in 8.0.0-line territory regardless.

Test plan

• bundle exec rake test passes
• Existing session/cookie_password tests still pass; new tests cover the < 32-byte rejection paths
• Webhook + Actions verify_header reject future-dated timestamps
• Spot-check: log output for an invitation by_token request shows redaction
• Manual: a session refresh whose JWKS fetch fails leaves the previously-good session unchanged AND surfaces the rotated cookie via result.sealed_session for the caller to write back

[greptile-apps]

Greptile Summary

This PR hardens several security-sensitive paths: it enforces a 32-byte minimum on cookie_password at every entry point, reorders state mutation so @seal_data is persisted before JWT decode (making JWKS failures recoverable), propagates the rotated cookie through RefreshError, treats exp-less tokens as expired, adds symmetric .abs tolerance checks to webhook/action timestamp verification, and adds log-redaction for bearer-token path segments and sensitive query params.

• Session durability fix: @seal_data is now mutated before decode_jwt, and RefreshError gains a sealed_session field so callers can always write the latest cookie back to the browser even when JWKS decode fails.
• Cookie password hardening: A 32-byte minimum is checked in Session#initialize, Session#refresh, SessionManager#validate_cookie_password!, and Encryptors::AesGcm#validate_key!, providing layered enforcement.
• Log redaction: redact_path strips token path segments for invitation/magic-auth/password-reset/email-verification routes and scrubs a fixed list of sensitive query-string keys before any log line is written.

Confidence Score: 5/5

Safe to merge — all changes tighten existing invariants without introducing regressions on the happy path.

The session durability fix, cookie-password enforcement, log redaction, and symmetric tolerance checks are all narrow, well-tested changes. The @seal_data mutation-before-decode reordering is the most structurally significant change; it is correct and its behavior is verified by the updated test. The iss/aud JWT validation gap is pre-existing and deliberately deferred (documented in code and PR description). No new blocking issues were found.

No files require special attention. lib/workos/session.rb and lib/workos/session_manager.rb carry the most logic change but are covered by the updated test suite.

Important Files Changed

Filename	Overview
lib/workos/session.rb	Adds 32-byte password guard in initialize and refresh, flips exp-nil handling to treat absent exp as expired, persists seal state before JWT decode, and surfaces rotated cookie on RefreshError.
lib/workos/session_manager.rb	Adds private validate_cookie_password! called from seal_data/unseal_data; adds :sealed_session field to RefreshError; decode_jwt intentionally omits iss/aud validation (documented as cross-SDK parity deferral).
lib/workos/base_client.rb	Adds redact_path/redact_query helpers; sessions/logout and sessions/authorize paths are handled correctly via query-param redaction (session_id key in REDACTED_QUERY_KEYS) even though they can't match the path-prefix list.
lib/workos/encryptors/aes_gcm.rb	Adds validate_key! enforcing 32-byte minimum; refactors unseal fallback from method-level rescue to explicit begin/rescue blocks — logically equivalent, cleaner scoping.
lib/workos/webhooks.rb	Adds .abs to tolerance check — symmetric future-timestamp rejection, correct fix.
lib/workos/actions.rb	Mirrors webhook .abs tolerance fix for Actions#verify_header.
lib/workos/user_management.rb	Strips caller-supplied code_challenge/code_challenge_method from opts in get_authorization_url_with_pkce to prevent collisions or challenge override.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant Session
    participant SessionManager
    participant WorkOSAPI
    participant JWTDecoder

    Caller->>Session: refresh(cookie_password?)
    Session->>Session: "validate effective_password length >= 32"
    Session->>SessionManager: unseal_data(seal_data, password)
    SessionManager-->>Session: unsealed session payload
    Session->>WorkOSAPI: "POST authenticate (grant_type=refresh_token)"
    WorkOSAPI-->>Session: auth_response with new tokens
    Session->>SessionManager: seal_session_from_auth_response(...)
    SessionManager-->>Session: sealed cookie string
    Note over Session: MUTATE state before decode
    Note over Session: @seal_data = sealed
    Session->>JWTDecoder: decode_jwt(new token)
    alt decode succeeds
        JWTDecoder-->>Session: decoded claims
        Session-->>Caller: RefreshSuccess(sealed_session: sealed)
    else JWT::DecodeError
        JWTDecoder-->>Session: raise DecodeError
        Session-->>Caller: "RefreshError(sealed_session: @seal_data)"
        Note over Caller: write rotated cookie to browser
    else AuthError before rotation
        WorkOSAPI-->>Session: raise AuthenticationError
        Session-->>Caller: RefreshError(sealed_session: nil)
    end

Loading

_{Reviews (7): Last reviewed commit: "fix(base_client): redact sensitive query..." | Re-trigger Greptile}