workos 8.0.0 → 8.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 974591cf2aee743c7ea0f4c00e9d851bcd83275e7425f6b57913f1d3ee3674d8
-  data.tar.gz: f7170a52d3dbf70cfc7a2abb05d8017812e8c96c759d7d414034cb3e3b8f0b19
+  metadata.gz: 24ec60a2134602d268907b2a885e04872b8ad5bb7ccff1095abb1a1d7bbb30d7
+  data.tar.gz: 1ef26bc5f186054f6949156b127d64ad3b1533c38468e0c919105b2ce7e0dd4c
 SHA512:
-  metadata.gz: 9ecabceabdc1847645a1a07fa7d747bfde8bdf8fe1cb86c487d44b5b2d0a87c49e41bb32d49c8511009970bd3de64ac13b6674616a3b8026ae10bccfd337a81b
-  data.tar.gz: 41d43875ebc5c9de7f87b8ce3e810795846c6077ae79c8f752fdd8894c6b5de574bd5e594d3a2a6a77ef7853b94ee04fe2d811b52cf69576bebcd6812fab9c70
+  metadata.gz: 81b868876a7b9541e043f8ed407b8a0ef1879df9d96ce1163ea737ea037132c80a036a03636165f53e0c96e9a0a52bdc6a8775fc84e953df1be9aa8646e78e34
+  data.tar.gz: 9118c02daa8efe8812fb999fd1ac745bc1760f7e6a0613fe34f4272489eff27ebe552e653b2b7dab36de54b8ef06919a81936873af8741e2c7f57e9b4f71898c

data/.github/workflows/docs.yml

@@ -1,7 +1,7 @@
 name: Publish API Docs
 on:
   push:
-    tags: ['v*']
+    branches: [main]
   workflow_dispatch:
 permissions:
   contents: read
@@ -37,6 +37,9 @@ jobs:
           if-no-files-found: error
   deploy:
     needs: build
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

data/.github/workflows/release-please.yml

@@ -3,7 +3,7 @@ name: Release Please
 on:
   push:
     branches:
-      - main
+      - v8.0.x
 
 permissions:
   contents: write
@@ -24,6 +24,7 @@ jobs:
         id: release
         with:
           token: ${{ steps.generate-token.outputs.token }}
+          target-branch: v8.0.x
 
       - name: Update Gemfile.lock on release PR
         if: steps.release.outputs.pr
@@ -45,8 +46,8 @@ jobs:
           if git diff --quiet Gemfile.lock; then
             echo "Gemfile.lock is up to date"
           else
-            git config user.name "github-actions[bot]"
-            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git config user.name "workos-sdk-automation[bot]"
+            git config user.email "255426317+workos-sdk-automation[bot]@users.noreply.github.com"
             git add Gemfile.lock
             git commit -m "chore: update Gemfile.lock"
             git push

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "8.0.0"
+  ".": "8.0.2"
 }

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [8.0.2](https://github.com/workos/workos-ruby/compare/v8.0.1...v8.0.2) (2026-08-20)
+
+
+### Bug Fixes
+
+* explicitly evict connections if request does not complete as success ([d79b839](https://github.com/workos/workos-ruby/commit/d79b8390690ce595896d1b6057cf68e5058b98da))
+
+## [8.0.1](https://github.com/workos/workos-ruby/compare/v8.0.0...v8.0.1) (2026-05-12)
+
+
+### Bug Fixes
+
+* harden session sealing, log redaction, and webhook tolerance checks ([#482](https://github.com/workos/workos-ruby/issues/482)) ([347fe1e](https://github.com/workos/workos-ruby/commit/347fe1edf296778d7ea331e666a7957870074b9f))
+
 ## [8.0.0](https://github.com/workos/workos-ruby/compare/v7.1.2...v8.0.0) (2026-05-06)
 
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    workos (8.0.0)
+    workos (8.0.2)
       jwt (~> 3.1)
       logger (~> 1.7)
       zeitwerk (~> 2.6)
@@ -153,7 +153,7 @@ CHECKSUMS
   unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
   webmock (3.26.2) sha256=774556f2ea6371846cca68c01769b2eac0d134492d21f6d0ab5dd643965a4c90
   webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
-  workos (8.0.0)
+  workos (8.0.2)
   yard (0.9.43) sha256=cf8733a8f0485df2a162927e9b5f182215a61f6d22de096b8f402c726a1c5821
   yard-markdown (0.7.1) sha256=06c378632dfe7ba053be9ba469eb4701aa0470e36bcf7e5546f353eb90c1bfd1
   zeitwerk (2.7.5) sha256=d8da92128c09ea6ec62c949011b00ed4a20242b255293dd66bf41545398f73dd

data/README.md

@@ -139,6 +139,25 @@ user = WorkOS.client.user_management.create_user(
 puts user.id
 ```
 
+### Sealed sessions (cookie_password requirements)
+
+When you use `client.session_manager` to seal session cookies, the
+`cookie_password` you supply must be **at least 32 bytes** of high-entropy
+secret material (typically 32 random bytes encoded as base64 or a 64-char
+hex string). The SDK derives the AES-256-GCM key from this password via
+SHA-256, and a passphrase shorter than 32 bytes makes the resulting key
+materially easier to brute-force offline.
+
+Generate a suitable secret once and store it as an environment variable:
+
+```sh
+ruby -rsecurerandom -e 'puts SecureRandom.base64(32)'
+```
+
+Anything shorter than 32 bytes (including `nil` or `""`) raises
+`ArgumentError` at SDK init time — sealing or unsealing will not silently
+proceed with a weakened key.
+
 ### Verify a webhook
 
 ```ruby

data/docs/V7_MIGRATION_GUIDE.md

@@ -501,6 +501,27 @@ Session management was one of the largest refactors in v7. The old `WorkOS::Sess
 
 If your application seals session cookies, refreshes access tokens, or decodes the access-token JWT, every one of these call sites needs to be updated.
 
+#### `cookie_password` minimum length (32 bytes)
+
+v7 enforces a **minimum 32-byte length** on every `cookie_password` you supply
+to the session manager (`load`, `seal_data`, `unseal_data`,
+`seal_session_from_auth_response`, and the underlying `Encryptors::AesGcm`).
+
+Anything shorter — including `nil` or `""` — now raises `ArgumentError` at the
+moment the SDK is asked to seal or unseal. Older deployments that used a
+short passphrase (e.g. a 16-character secret) will start erroring at app
+boot or the next sealed-session request.
+
+Pick a 32+ byte secret once and store it as an environment variable:
+
+```sh
+ruby -rsecurerandom -e 'puts SecureRandom.base64(32)'
+```
+
+The KDF itself (single-pass SHA-256) is unchanged in this release, so
+existing sealed cookies continue to round-trip as long as the same
+(now-length-validated) password is in use.
+
 #### Sealing a cookie from an authentication response
 
 In v6, you asked `authenticate_with_*` to seal the cookie for you:

data/lib/workos/actions.rb

@@ -35,7 +35,7 @@ module WorkOS
     def verify_header(payload:, sig_header:, secret:, tolerance: DEFAULT_TOLERANCE_SECONDS)
       timestamp_ms, signature_hash = parse_signature_header(sig_header)
       issued_at = timestamp_ms.to_i / 1000.0
-      if (Time.now.to_f - issued_at) > tolerance
+      if (Time.now.to_f - issued_at).abs > tolerance
         raise WorkOS::SignatureVerificationError.new(
           message: "Timestamp outside the tolerance zone",
           http_status: nil

data/lib/workos/base_client.rb

@@ -134,19 +134,33 @@ module WorkOS
       attempt = 0
 
       loop do
-        log(:debug, "request start", method: request.method, path: request.path, attempt: attempt + 1)
+        loggable_path = redact_path(request.path)
+        log(:debug, "request start", method: request.method, path: loggable_path, attempt: attempt + 1)
         http = connection_for(base, timeout)
-        response = http.request(request)
+        request_completed = false
+        begin
+          response = http.request(request)
+          request_completed = true
+        ensure
+          # Any exit from #request other than a returned response can leave
+          # the socket mid-stream: a connection error the rescue below knows
+          # about, one it doesn't (OpenSSL::SSL::SSLError,
+          # Net::HTTPBadResponse), or a non-local exit such as an
+          # application-level Timeout.timeout or Thread#kill. A half-read
+          # socket handed back to the pool desyncs the *next* request on this
+          # thread, so drop it here rather than in the rescue.
+          evict_connection(base) unless request_completed
+        end
         return response if response.is_a?(Net::HTTPSuccess)
 
         if attempt < retries && retryable?(response)
           attempt += 1
           inject_retry_idempotency_key(request)
-          log(:info, "request retry", method: request.method, path: request.path, attempt: attempt + 1, status: response.code.to_i)
+          log(:info, "request retry", method: request.method, path: loggable_path, attempt: attempt + 1, status: response.code.to_i)
           sleep(retry_delay(response, attempt))
           next
         end
-        log(:warn, "request error", method: request.method, path: request.path, status: response.code.to_i, request_id: response["x-request-id"] || response["X-Request-Id"])
+        log(:warn, "request error", method: request.method, path: loggable_path, status: response.code.to_i, request_id: response["x-request-id"] || response["X-Request-Id"])
         handle_error_response(response)
       rescue Net::OpenTimeout, Net::ReadTimeout,
         Errno::ECONNRESET, Errno::ECONNREFUSED,
@@ -155,11 +169,11 @@ module WorkOS
         if attempt < retries
           attempt += 1
           inject_retry_idempotency_key(request)
-          log(:info, "request retry", method: request.method, path: request.path, attempt: attempt + 1, error: e.class.name)
+          log(:info, "request retry", method: request.method, path: loggable_path, attempt: attempt + 1, error: e.class.name)
           sleep(retry_delay(nil, attempt))
           next
         end
-        log(:warn, "connection error", method: request.method, path: request.path, error: e.class.name, message: e.message)
+        log(:warn, "connection error", method: request.method, path: loggable_path, error: e.class.name, message: e.message)
         raise WorkOS::APIConnectionError.new(message: e.message)
       end
     end
@@ -179,6 +193,71 @@ module WorkOS
 
     private
 
+    # Redact path segments that carry bearer-equivalent tokens (e.g.
+    # `/user_management/invitations/by_token/<token>`,
+    # `/user_management/magic_auth/<token>`, password-reset / email-
+    # verification token paths) before the path is written to a logger.
+    # The WorkOS API exposes a small number of "by_token" endpoints whose
+    # path segments are themselves authentication material; redacting them
+    # here means the SDK never emits the token in its own log/retry/error
+    # messages even when the host application configures verbose logging.
+    REDACTED_TOKEN_PREFIXES = %w[
+      /user_management/invitations/by_token
+      /user_management/magic_auth
+      /user_management/password_reset
+      /user_management/email_verification
+    ].freeze
+    private_constant :REDACTED_TOKEN_PREFIXES
+
+    # Query-string keys whose values are bearer-equivalent or otherwise
+    # sensitive and should never appear in SDK log lines. Defense-in-depth
+    # for any path that flows through execute_request with a sensitive
+    # query parameter (most WorkOS-issued tokens are path segments or POST
+    # bodies, but a few flows — e.g. authorize/logout redirects — surface
+    # them in the query string).
+    REDACTED_QUERY_KEYS = %w[
+      token
+      code
+      code_challenge
+      code_verifier
+      session_id
+      refresh_token
+      access_token
+    ].freeze
+    private_constant :REDACTED_QUERY_KEYS
+
+    def redact_path(path)
+      return path if path.nil? || path.empty?
+
+      # Strip query string for the prefix match; reattach (scrubbed) after.
+      path_only, query = path.split("?", 2)
+      REDACTED_TOKEN_PREFIXES.each do |prefix|
+        next unless path_only.start_with?("#{prefix}/")
+
+        # Replace every segment after the matched prefix with "[REDACTED]".
+        remainder = path_only[(prefix.length + 1)..]
+        next if remainder.nil? || remainder.empty?
+
+        redacted = remainder.split("/").map { "[REDACTED]" }.join("/")
+        path_only = "#{prefix}/#{redacted}"
+        break
+      end
+      query ? "#{path_only}?#{redact_query(query)}" : path_only
+    end
+
+    def redact_query(query)
+      return query if query.nil? || query.empty?
+
+      query.split("&").map { |pair|
+        key, value = pair.split("=", 2)
+        if value && !value.empty? && REDACTED_QUERY_KEYS.include?(key)
+          "#{key}=[REDACTED]"
+        else
+          pair
+        end
+      }.join("&")
+    end
+
     def append_query(path, params)
       return path unless params.is_a?(Hash) && !params.empty?
 

data/lib/workos/encryptors/aes_gcm.rb

@@ -14,8 +14,14 @@ module WorkOS
   module Encryptors
     class AesGcm
       SEAL_VERSION = 0x01
+      # Minimum cookie_password byte length. AES-256-GCM derives a 32-byte
+      # key from the password via SHA-256; a passphrase shorter than the
+      # output it derives to provides less than the full keyspace and makes
+      # offline brute-force feasible. See README + V7_MIGRATION_GUIDE.md.
+      MIN_KEY_BYTES = 32
 
       def seal(data, key)
+        validate_key!(key)
         json = data.is_a?(String) ? data : JSON.generate(data)
         cipher = OpenSSL::Cipher.new("aes-256-gcm").encrypt
         cipher.key = derive_key(key)
@@ -26,13 +32,16 @@ module WorkOS
       end
 
       def unseal(sealed, key)
+        validate_key!(key)
         raw = Base64.decode64(sealed.to_s)
-        decode_v7(raw, key)
-      rescue ArgumentError, OpenSSL::Cipher::CipherError => original_error
         begin
-          decode_old(raw, key)
-        rescue ArgumentError, OpenSSL::Cipher::CipherError
-          raise original_error
+          decode_v7(raw, key)
+        rescue ArgumentError, OpenSSL::Cipher::CipherError => original_error
+          begin
+            decode_old(raw, key)
+          rescue ArgumentError, OpenSSL::Cipher::CipherError
+            raise original_error
+          end
         end
       end
 
@@ -83,6 +92,11 @@ module WorkOS
       def derive_key(passphrase)
         Digest::SHA256.digest(passphrase.to_s)
       end
+
+      def validate_key!(key)
+        raise ArgumentError, "cookie_password is required" if key.nil? || key.to_s.empty?
+        raise ArgumentError, "cookie_password must be at least #{MIN_KEY_BYTES} bytes" if key.to_s.bytesize < MIN_KEY_BYTES
+      end
     end
   end
 end

data/lib/workos/session.rb

@@ -21,8 +21,16 @@ module WorkOS
   # @example Build a logout URL
   #   url = session.get_logout_url(return_to: "https://app.example.com")
   class Session
+    # Minimum cookie_password byte length. AES-256-GCM derives a 32-byte
+    # key from the password via SHA-256; a passphrase shorter than the
+    # output it derives to provides less than the full keyspace and makes
+    # offline brute-force feasible. Require callers to supply at least 32
+    # bytes of high-entropy secret. See README + V7_MIGRATION_GUIDE.md.
+    MIN_COOKIE_PASSWORD_BYTES = 32
+
     def initialize(manager, seal_data:, cookie_password:)
       raise ArgumentError, "cookie_password is required" if cookie_password.nil? || cookie_password.empty?
+      raise ArgumentError, "cookie_password must be at least #{MIN_COOKIE_PASSWORD_BYTES} bytes" if cookie_password.bytesize < MIN_COOKIE_PASSWORD_BYTES
       @manager = manager
       @client = manager.client
       @seal_data = seal_data
@@ -57,7 +65,7 @@ module WorkOS
         return SessionManager::AuthError.new(authenticated: false, reason: SessionManager::INVALID_JWT)
       end
 
-      is_expired = decoded["exp"] && decoded["exp"] < Time.now.to_i
+      is_expired = decoded["exp"].nil? || decoded["exp"] < Time.now.to_i
 
       SessionManager::AuthSuccess.new(
         authenticated: !is_expired,
@@ -77,6 +85,11 @@ module WorkOS
 
     def refresh(organization_id: nil, cookie_password: nil)
       effective_password = cookie_password || @cookie_password
+      # Validate up front so a caller-supplied short password raises ArgumentError
+      # (matching Session#initialize) instead of being swallowed by the
+      # unseal_data rescue and surfacing as INVALID_SESSION_COOKIE.
+      raise ArgumentError, "cookie_password is required" if effective_password.nil? || effective_password.empty?
+      raise ArgumentError, "cookie_password must be at least #{MIN_COOKIE_PASSWORD_BYTES} bytes" if effective_password.bytesize < MIN_COOKIE_PASSWORD_BYTES
 
       session = begin
         @manager.unseal_data(@seal_data, effective_password)
@@ -105,17 +118,20 @@ module WorkOS
         impersonator: auth_response["impersonator"]
       )
 
-      # Decode before mutating session state so a malformed access_token
-      # doesn't leave the Session half-updated.
-      decoded = @manager.decode_jwt(auth_response["access_token"])
-
+      # Persist the new seal/password BEFORE decoding the JWT, so a transient
+      # JWKS fetch error (or any decode failure on the freshly-minted token)
+      # leaves the Session with a usable sealed cookie that the caller can
+      # re-#authenticate against, rather than half-updated state.
       @seal_data = sealed
       @cookie_password = effective_password
+
+      decoded = @manager.decode_jwt(auth_response["access_token"])
+
       SessionManager::RefreshSuccess.new(
         authenticated: true,
         sealed_session: sealed,
         session_id: decoded["sid"],
-        organization_id: decoded["org_id"],
+        organization_id: auth_response["organization_id"] || decoded["org_id"],
         role: decoded["role"],
         roles: decoded["roles"],
         permissions: decoded["permissions"],
@@ -127,7 +143,12 @@ module WorkOS
     rescue WorkOS::AuthenticationError, WorkOS::InvalidRequestError => e
       SessionManager::RefreshError.new(authenticated: false, reason: e.message)
     rescue JWT::DecodeError => e
-      SessionManager::RefreshError.new(authenticated: false, reason: e.message)
+      # The refresh token was already rotated server-side before decode failed,
+      # so @seal_data holds the freshly-minted cookie. Surface it on the error
+      # struct so the caller can write the rotated cookie back to the browser
+      # and recover on a subsequent #authenticate, rather than re-sending the
+      # now-revoked refresh token.
+      SessionManager::RefreshError.new(authenticated: false, reason: e.message, sealed_session: @seal_data)
     end
 
     # Build the WorkOS session-logout URL for the currently authenticated session.

data/lib/workos/session_manager.rb

@@ -107,7 +107,7 @@ module WorkOS
       :roles, :permissions, :entitlements, :user, :impersonator, :feature_flags,
       keyword_init: true
     )
-    RefreshError = Struct.new(:authenticated, :reason, keyword_init: true)
+    RefreshError = Struct.new(:authenticated, :reason, :sealed_session, keyword_init: true)
 
     # Failure reason constants
     NO_SESSION_COOKIE_PROVIDED = "no_session_cookie_provided"
@@ -150,12 +150,14 @@ module WorkOS
     # H06 — Raw seal: encrypt arbitrary data with a key string.
     # Delegates to the configured encryptor (default: AES-256-GCM).
     def seal_data(data, key)
+      validate_cookie_password!(key)
       @encryptor.seal(data, key)
     end
 
     # H06 — Raw unseal: returns parsed JSON (Hash) or raw string if not JSON.
     # Delegates to the configured encryptor (default: AES-256-GCM).
     def unseal_data(sealed, key)
+      validate_cookie_password!(key)
       @encryptor.unseal(sealed, key)
     end
 
@@ -164,11 +166,20 @@ module WorkOS
       payload = {"access_token" => access_token, "refresh_token" => refresh_token}
       payload["user"] = user if user
       payload["impersonator"] = impersonator if impersonator
+      # Delegates to seal_data, which calls validate_cookie_password!; no need
+      # to validate here too.
       seal_data(payload, cookie_password)
     end
 
     # Verify an access-token JWT against the WorkOS JWKS for this client.
     # Used by Session#authenticate; exposed publicly for advanced cases.
+    #
+    # NOTE on iss/aud/required_claims: this method intentionally does not
+    # enforce iss, aud, or required_claims. workos-node's `jose` call and
+    # workos-php's `isset($exp) && $exp < time()` accept exp-less tokens, and
+    # cross-SDK parity is required for the planned coordinated hardening of
+    # these claims. See commit 9ce069f for the rationale behind dropping the
+    # required_claims: ['exp'] tightening that was considered here.
     def decode_jwt(access_token, verify_expiration: true)
       jwks = fetch_jwks
       JWT.decode(
@@ -182,6 +193,18 @@ module WorkOS
       ).first
     end
 
+    private
+
+    # Validate a cookie_password is non-empty and at least the minimum
+    # byte length required by Session::MIN_COOKIE_PASSWORD_BYTES (32).
+    # Defense-in-depth — Session#initialize enforces the same invariant
+    # on the load path; this guards the inline #seal_data / #unseal_data
+    # entry points.
+    def validate_cookie_password!(key)
+      raise ArgumentError, "cookie_password is required" if key.nil? || key.empty?
+      raise ArgumentError, "cookie_password must be at least #{Session::MIN_COOKIE_PASSWORD_BYTES} bytes" if key.bytesize < Session::MIN_COOKIE_PASSWORD_BYTES
+    end
+
     # Cached JWKS fetch (5-minute TTL, thread-safe).
     def fetch_jwks(now: Time.now)
       @jwks_mutex.synchronize do

data/lib/workos/user_management.rb

@@ -1641,6 +1641,13 @@ module WorkOS
     def get_authorization_url_with_pkce(redirect_uri:, client_id: nil, **opts)
       pair = WorkOS::PKCE.generate_pair
       state = opts.delete(:state) || WorkOS::PKCE.generate_code_verifier
+      # Strip caller-supplied PKCE params: this helper exists specifically
+      # to generate them, so a caller-provided value would either silently
+      # override our freshly-generated challenge (defeating the helper) or
+      # collide with the keyword args below and raise. Mirror the existing
+      # opts.delete(:state) pattern.
+      opts.delete(:code_challenge)
+      opts.delete(:code_challenge_method)
       url = get_authorization_url(
         redirect_uri: redirect_uri,
         client_id: client_id,

data/lib/workos/version.rb

@@ -2,5 +2,5 @@
 
 # @oagen-ignore-file
 module WorkOS
-  VERSION = "8.0.0"
+  VERSION = "8.0.2"
 end

data/lib/workos/webhooks.rb

@@ -193,7 +193,7 @@ module WorkOS
       timestamp_ms, signature_hash = parse_signature_header(sig_header)
       max_age = tolerance.to_i
       issued_at = timestamp_ms.to_i / 1000.0
-      if (Time.now.to_f - issued_at) > max_age
+      if (Time.now.to_f - issued_at).abs > max_age
         raise WorkOS::SignatureVerificationError.new(
           message: "Timestamp outside the tolerance zone",
           http_status: nil

data/test/workos/test_actions.rb

@@ -49,6 +49,15 @@ class ActionsTest < Minitest::Test
     end
   end
 
+  def test_verify_header_raises_on_future_timestamp
+    payload = '{"x":1}'
+    future_ts = now_ms + 60_000 # 60s ahead, beyond default 30s tolerance
+    sig = OpenSSL::HMAC.hexdigest("SHA256", SECRET, "#{future_ts}.#{payload}")
+    assert_raises(WorkOS::SignatureVerificationError) do
+      @actions.verify_header(payload: payload, sig_header: "t=#{future_ts}, v1=#{sig}", secret: SECRET)
+    end
+  end
+
   def test_sign_response_authentication_allow
     resp = @actions.sign_response(action_type: "authentication", verdict: "Allow", secret: SECRET)
     assert_equal "authentication_action_response", resp["object"]

data/test/workos/test_base_client.rb

@@ -82,10 +82,36 @@ class BaseClientTest < Minitest::Test
     end
   end
 
+  # A pooled connection that either returns a canned response or raises when
+  # driven, so execute_request can be exercised without real TCP+TLS.
+  class StubConnection < FakeConnection
+    attr_accessor :read_timeout, :open_timeout
+
+    def initialize(response: nil, error: nil, **kwargs)
+      super(**kwargs)
+      @response = response
+      @error = error
+    end
+
+    def request(_request)
+      raise @error if @error
+
+      @response
+    end
+  end
+
   def setup
     @client = WorkOS::BaseClient.new(api_key: "sk_test_123", max_retries: 1)
   end
 
+  def teardown
+    super
+    # Close any open connections and clear the fiber-local cache to avoid
+    # leaking pooled connections between tests.
+    @client.shutdown
+    Fiber[:workos_connections] = nil
+  end
+
   def test_request_dispatches_known_methods
     client = RecordingClient.new(api_key: "sk_test_123")
 
@@ -170,4 +196,185 @@ class BaseClientTest < Minitest::Test
     assert evict.finished
     refute keep.finished
   end
+
+  def test_redact_path_strips_invitation_token_segment
+    redacted = @client.send(:redact_path, "/user_management/invitations/by_token/invtoken_secret123")
+    assert_equal "/user_management/invitations/by_token/[REDACTED]", redacted
+  end
+
+  def test_redact_path_strips_magic_auth_token_segment
+    redacted = @client.send(:redact_path, "/user_management/magic_auth/magic_secret/extra")
+    assert_equal "/user_management/magic_auth/[REDACTED]/[REDACTED]", redacted
+  end
+
+  def test_redact_path_preserves_non_token_paths
+    assert_equal "/organizations/org_123", @client.send(:redact_path, "/organizations/org_123")
+  end
+
+  def test_redact_path_preserves_query_string
+    redacted = @client.send(:redact_path, "/user_management/invitations/by_token/secret?foo=bar")
+    assert_equal "/user_management/invitations/by_token/[REDACTED]?foo=bar", redacted
+  end
+
+  def test_redact_path_handles_nil_and_empty
+    assert_nil @client.send(:redact_path, nil)
+    assert_equal "", @client.send(:redact_path, "")
+  end
+
+  def test_redact_path_scrubs_sensitive_query_params
+    redacted = @client.send(:redact_path, "/user_management/sessions/logout?session_id=ses_abc123&return_to=https://app.example.com")
+    assert_equal "/user_management/sessions/logout?session_id=[REDACTED]&return_to=https://app.example.com", redacted
+  end
+
+  def test_redact_path_scrubs_authorize_code_query_param
+    redacted = @client.send(:redact_path, "/user_management/authorize?client_id=client_1&code=auth_code_secret&state=xyz")
+    assert_equal "/user_management/authorize?client_id=client_1&code=[REDACTED]&state=xyz", redacted
+  end
+
+  def test_redact_path_leaves_non_sensitive_query_params_untouched
+    redacted = @client.send(:redact_path, "/user_management/users?limit=10&order=desc")
+    assert_equal "/user_management/users?limit=10&order=desc", redacted
+  end
+
+  def test_redact_path_scrubs_query_alongside_path_segment_redaction
+    redacted = @client.send(:redact_path, "/user_management/magic_auth/magic_secret?token=qs_token")
+    assert_equal "/user_management/magic_auth/[REDACTED]?token=[REDACTED]", redacted
+  end
+
+  # An exception execute_request's rescue clause doesn't list still leaves the
+  # socket mid-stream, so the connection must not survive in the pool for the
+  # next request on this thread to pick up.
+  def test_unlisted_request_error_evicts_the_pooled_connection
+    conn = StubConnection.new(error: Net::HTTPBadResponse.new("wrong version"))
+    cache = @client.send(:thread_connections)
+    cache["https:api.workos.com:443:30"] = conn
+
+    assert_raises(Net::HTTPBadResponse) do
+      @client.execute_request(request: Net::HTTP::Get.new("/things"))
+    end
+
+    refute cache.key?("https:api.workos.com:443:30"),
+      "a connection whose request did not complete must not stay pooled"
+    assert conn.finished
+  end
+
+  def test_completed_request_keeps_the_connection_pooled
+    conn = StubConnection.new(response: Net::HTTPOK.new("1.1", "200", "OK"))
+    cache = @client.send(:thread_connections)
+    cache["https:api.workos.com:443:30"] = conn
+
+    @client.execute_request(request: Net::HTTP::Get.new("/things"))
+
+    assert cache.key?("https:api.workos.com:443:30")
+    refute conn.finished
+  end
+
+  # Raised asynchronously into the worker thread to stand in for a caller-side
+  # abort: Timeout.timeout, Thread#kill, a signal handler unwinding the stack.
+  # It descends from Exception rather than StandardError so that nothing in
+  # execute_request can catch it — the `ensure` is the only cleanup that runs.
+  class AbortSignal < Exception; end # standard:disable Lint/InheritException
+
+  # End-to-end regression test over a real keep-alive socket, for the failure
+  # the eviction actually prevents: request one is abandoned mid-flight, the
+  # server then writes response one onto that socket, and request two on the
+  # same thread reads those stale bytes as if they were its own response.
+  #
+  # Before the fix, request two sees marker "one" (or a mangled response) off
+  # the pooled socket. After it, the abandoned socket is closed and the server
+  # accepts a fresh connection for request two.
+  def test_aborted_request_does_not_leak_its_response_to_the_next_request
+    WebMock.disable!
+    server = TCPServer.new("127.0.0.1", 0)
+    port = server.addr[1]
+    client = WorkOS::BaseClient.new(
+      api_key: "sk_test_123",
+      base_url: "http://127.0.0.1:#{port}",
+      timeout: 5,
+      max_retries: 0
+    )
+
+    request_one_read = Queue.new
+    release_response_one = Queue.new
+    response_one_written = Queue.new
+    aborted = Queue.new
+    connections = Queue.new
+
+    server_thread = Thread.new do
+      # Connection one: read the request, then hold the response back until
+      # the client has been aborted and has unwound.
+      first = server.accept
+      connections << first
+      read_http_request(first)
+      request_one_read << true
+      release_response_one.pop
+      begin
+        write_http_response(first, {marker: "one"})
+      rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+        # Expected once the fix closes the abandoned socket.
+      end
+      response_one_written << true
+
+      # Connection two: a fresh accept, which only completes because the
+      # client did not reuse the socket above.
+      second = server.accept
+      connections << second
+      read_http_request(second)
+      write_http_response(second, {marker: "two"})
+    end
+
+    worker = Thread.new do
+      begin
+        client.execute_request(request: Net::HTTP::Get.new("/one"))
+      rescue AbortSignal
+        # The caller unwinds but the thread survives and goes on to serve more
+        # work, the way a Puma or Solid Queue worker does. execute_request's
+        # `ensure` has already run by the time this body executes.
+        aborted << true
+        response_one_written.pop
+      end
+      response = client.execute_request(request: Net::HTTP::Get.new("/two"))
+      JSON.parse(response.body)["marker"]
+    end
+
+    marker = Timeout.timeout(15) do
+      request_one_read.pop
+      worker.raise(AbortSignal)
+      aborted.pop
+      release_response_one << true
+      worker.value
+    end
+
+    assert_equal "two", marker,
+      "request two read the abandoned socket's response instead of its own"
+  ensure
+    server_thread&.kill
+    worker&.kill
+    until connections.nil? || connections.empty?
+      socket = connections.pop
+      socket.close unless socket.closed?
+    end
+    server&.close
+    WebMock.enable!
+  end
+
+  def read_http_request(socket)
+    socket.gets # request line
+    loop do
+      line = socket.gets
+      break if line.nil? || line == "\r\n"
+    end
+  end
+
+  def write_http_response(socket, body)
+    payload = JSON.generate(body)
+    socket.write(
+      "HTTP/1.1 200 OK\r\n" \
+      "Content-Type: application/json\r\n" \
+      "Content-Length: #{payload.bytesize}\r\n" \
+      "Connection: keep-alive\r\n" \
+      "\r\n#{payload}"
+    )
+    socket.flush
+  end
 end

data/test/workos/test_encryptors_aes_gcm.rb

@@ -28,11 +28,26 @@ class EncryptorsAesGcmTest < Minitest::Test
 
   def test_unseal_with_wrong_key_raises
     sealed = @enc.seal({"x" => 1}, PASSWORD)
+    # Wrong key is the same length (>= 32 bytes) so the length guard doesn't
+    # short-circuit; we want to assert the underlying cipher rejection.
     assert_raises(OpenSSL::Cipher::CipherError) do
-      @enc.unseal(sealed, "wrong-password")
+      @enc.unseal(sealed, "wrong-cookie-password-32-bytes--")
     end
   end
 
+  def test_unseal_rejects_short_key
+    sealed = @enc.seal({"x" => 1}, PASSWORD)
+    assert_raises(ArgumentError) do
+      @enc.unseal(sealed, "too-short")
+    end
+  end
+
+  def test_seal_rejects_short_key
+    assert_raises(ArgumentError) { @enc.seal({"x" => 1}, "too-short") }
+    assert_raises(ArgumentError) { @enc.seal({"x" => 1}, nil) }
+    assert_raises(ArgumentError) { @enc.seal({"x" => 1}, "") }
+  end
+
   def test_unseal_rejects_short_payload
     assert_raises(ArgumentError) do
       @enc.unseal(Base64.strict_encode64("short"), PASSWORD)

data/test/workos/test_session.rb

@@ -26,11 +26,27 @@ class SessionTest < Minitest::Test
 
   def test_unseal_with_wrong_key_raises
     sealed = @sm.seal_data({"x" => 1}, PASSWORD)
+    # Wrong key is the same length (>= 32 bytes) so the length guard doesn't
+    # short-circuit; we want to assert the underlying cipher rejection.
     assert_raises(OpenSSL::Cipher::CipherError) do
-      @sm.unseal_data(sealed, "wrong-password")
+      @sm.unseal_data(sealed, "wrong-cookie-password-32-bytes--")
     end
   end
 
+  def test_unseal_with_short_key_raises_argument_error
+    sealed = @sm.seal_data({"x" => 1}, PASSWORD)
+    assert_raises(ArgumentError) { @sm.unseal_data(sealed, "too-short") }
+  end
+
+  def test_seal_with_short_key_raises_argument_error
+    assert_raises(ArgumentError) { @sm.seal_data({"x" => 1}, "too-short") }
+  end
+
+  def test_session_load_requires_min_length_cookie_password
+    short = "x" * 31
+    assert_raises(ArgumentError) { @sm.load(seal_data: "x", cookie_password: short) }
+  end
+
   def test_unseal_rejects_short_payload
     assert_raises(ArgumentError) do
       @sm.unseal_data(Base64.strict_encode64("short"), PASSWORD)
@@ -334,6 +350,19 @@ class SessionTest < Minitest::Test
     assert_equal WorkOS::SessionManager::INVALID_SESSION_COOKIE, result.reason
   end
 
+  def test_refresh_raises_argument_error_for_short_cookie_password_override
+    sealed = @sm.seal_data({"access_token" => "at", "refresh_token" => "rt"}, PASSWORD)
+    session = @sm.load(seal_data: sealed, cookie_password: PASSWORD)
+    err = assert_raises(ArgumentError) { session.refresh(cookie_password: "x" * 31) }
+    assert_match(/at least 32 bytes/, err.message)
+  end
+
+  def test_refresh_raises_argument_error_for_empty_cookie_password_override
+    sealed = @sm.seal_data({"access_token" => "at", "refresh_token" => "rt"}, PASSWORD)
+    session = @sm.load(seal_data: sealed, cookie_password: PASSWORD)
+    assert_raises(ArgumentError) { session.refresh(cookie_password: "") }
+  end
+
   def test_refresh_returns_error_when_no_refresh_token
     sealed = @sm.seal_data({"access_token" => "at_only"}, PASSWORD)
     result = @sm.refresh(seal_data: sealed, cookie_password: PASSWORD)
@@ -361,7 +390,7 @@ class SessionTest < Minitest::Test
     assert_requested(stub)
   end
 
-  def test_refresh_returns_error_on_malformed_access_token_without_mutating_state
+  def test_refresh_persists_seal_data_even_when_access_token_decode_fails
     rsa, pub = signing_key_pair
     old_access = make_jwt({"sid" => "session_old", "exp" => Time.now.to_i - 60}, rsa)
     sealed = @sm.seal_data({"access_token" => old_access, "refresh_token" => "rt_old", "user" => {"id" => "u_1"}}, PASSWORD)
@@ -383,8 +412,18 @@ class SessionTest < Minitest::Test
     assert_kind_of WorkOS::SessionManager::RefreshError, result
     refute result.authenticated
 
-    # Session state should not have been mutated
-    assert_equal sealed, session.seal_data
+    # Session state IS updated to the freshly-sealed cookie before decode runs,
+    # so a transient JWT/JWKS failure leaves a usable seal the caller can
+    # re-#authenticate against rather than half-updated state pinned to the
+    # stale (already-rotated) refresh token.
+    refute_equal sealed, session.seal_data
+    refute_nil session.seal_data
+
+    # The rotated cookie is also reachable through the RefreshError result, so a
+    # caller that doesn't retain the Session object across requests (typical in
+    # a Rails request cycle) can still write the new cookie back to the browser
+    # rather than re-sending the now-revoked refresh token on the next request.
+    assert_equal session.seal_data, result.sealed_session
   end
 
   # --- Session constructor validation ---------------------------------------

data/test/workos/test_webhook_verify.rb

@@ -60,6 +60,17 @@ class WebhookVerifyTest < Minitest::Test
     assert_match(/Timestamp outside the tolerance zone/, err.message)
   end
 
+  def test_verify_header_raises_on_future_timestamp
+    payload = '{"x":1}'
+    future_ts = now_ms + (10 * 60 * 1000) # 10 minutes ahead
+    sig = OpenSSL::HMAC.hexdigest("SHA256", SECRET, "#{future_ts}.#{payload}")
+    header = "t=#{future_ts}, v1=#{sig}"
+    err = assert_raises(WorkOS::SignatureVerificationError) do
+      @webhooks.verify_header(payload: payload, sig_header: header, secret: SECRET, tolerance: 60)
+    end
+    assert_match(/Timestamp outside the tolerance zone/, err.message)
+  end
+
   def test_verify_header_raises_on_malformed_header
     assert_raises(WorkOS::SignatureVerificationError) do
       @webhooks.verify_header(payload: "{}", sig_header: "garbage", secret: SECRET)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workos
 version: !ruby/object:Gem::Version
-  version: 8.0.0
+  version: 8.0.2
 platform: ruby
 authors:
 - WorkOS
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-06 00:00:00.000000000 Z
+date: 2026-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt