workos 5.31.1 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5e37c10b9ae34685d2545d670ca866dbda73c22df75fc1a2e8d79c159d3a2c7
-  data.tar.gz: a6f6e36847db549930e7a18ae58e9e95a9c249eb7a93e4466f14109e50e7fddd
+  metadata.gz: 6f0ac87a768fc79fa7ffbc77d0bf4a1ba30cbf6c1f5b96f8574c40bd2b61d296
+  data.tar.gz: eb05af387d9c1c40e5de4fb830e4ce83e7baf94a2d9bcb428d97032208688780
 SHA512:
-  metadata.gz: 37ce63e77ccf9dd05b0d85837c5e1334ae155cd9beb0500d9b3faa3dd985c9638f54f77ff5cd1f350e3d283db23ac16f7a08bd972f308852a6f5eb4c63ebfa79
-  data.tar.gz: 77b058f1b59efe3a390817173d8a4b45557d41f95385196af8c999e4130ddc83a7a306b68714a7c5c2f7cc695db2e21192599792bce156918bce435a0b2d9b7f
+  metadata.gz: 5f82d97362d7063dcc970313794671ca7f8c2c8892ae9728179e3c22a980b1d7e3d238959eb875d4a20629f13c00a56053347a70dfcb2214cf769979fc704151
+  data.tar.gz: 5954446fc2d3c6fbad2542c7d377bb7eb8361e514d1d099f01c052085aebc6952277fd15efe7e3cf9683fc2a9dbf4976240098d48e9305607ab3233978b23f21

data/.github/workflows/version-bump.yml

@@ -67,7 +67,7 @@ jobs:
           sed -i "s/VERSION = '.*'/VERSION = '${{ steps.bump-version.outputs.new_version }}'/" lib/workos/version.rb
 
       - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@v8
         with:
           token: ${{ steps.generate-token.outputs.token }}
           commit-message: "v${{ steps.bump-version.outputs.new_version }}"

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    workos (5.31.1)
+    workos (6.0.0)
       encryptor (~> 3.0)
-      jwt (~> 2.8)
+      jwt (~> 3.1)
 
 GEM
   remote: https://rubygems.org/
@@ -11,7 +11,7 @@ GEM
     addressable (2.8.6)
       public_suffix (>= 2.0.2, < 6.0)
     ast (2.4.2)
-    base64 (0.2.0)
+    base64 (0.3.0)
     bigdecimal (3.1.7)
     crack (1.0.0)
       bigdecimal
@@ -20,7 +20,7 @@ GEM
     encryptor (3.0.0)
     hashdiff (1.1.0)
     json (2.9.1)
-    jwt (2.10.2)
+    jwt (3.1.2)
       base64
     language_server-protocol (3.17.0.3)
     parallel (1.26.3)

data/lib/workos/authentication_response.rb

@@ -31,13 +31,17 @@ module WorkOS
       @oauth_tokens = json[:oauth_tokens] ? WorkOS::OAuthTokens.new(json[:oauth_tokens].to_json) : nil
       @sealed_session =
         if session && session[:seal_session]
-          WorkOS::Session.seal_data({
-                                      access_token: access_token,
-                                      refresh_token: refresh_token,
-                                      user: user.to_json,
-                                      organization_id: organization_id,
-                                      impersonator: impersonator.to_json,
-                                    }, session[:cookie_password],)
+          WorkOS::Session.seal_data(
+            {
+              access_token: access_token,
+              refresh_token: refresh_token,
+              user: user.to_json,
+              organization_id: organization_id,
+              impersonator: impersonator.to_json,
+            },
+            session[:cookie_password],
+            encryptor: session[:encryptor],
+          )
         end
     end
     # rubocop:enable Metrics/AbcSize

data/lib/workos/encryptors/aes_gcm.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'encryptor'
+require 'securerandom'
+require 'json'
+require 'base64'
+
+module WorkOS
+  module Encryptors
+    # Default encryptor using AES-256-GCM.
+    # Implements the encryptor interface: #seal(data, key) and #unseal(sealed_data, key)
+    class AesGcm
+      # Encrypts and seals data using AES-256-GCM
+      # @param data [Hash] The data to seal
+      # @param key [String] The encryption key
+      # @return [String] Base64-encoded sealed data
+      def seal(data, key)
+        iv = SecureRandom.random_bytes(12)
+
+        encrypted_data = Encryptor.encrypt(
+          value: JSON.generate(data),
+          key: key,
+          iv: iv,
+          algorithm: 'aes-256-gcm',
+        )
+        Base64.encode64(iv + encrypted_data)
+      end
+
+      # Decrypts and unseals data using AES-256-GCM
+      # @param sealed_data [String] The sealed data to unseal
+      # @param key [String] The decryption key
+      # @return [Hash] The unsealed data with symbolized keys
+      def unseal(sealed_data, key)
+        decoded_data = Base64.decode64(sealed_data)
+        iv = decoded_data[0..11]
+        encrypted_data = decoded_data[12..]
+
+        decrypted_data = Encryptor.decrypt(
+          value: encrypted_data,
+          key: key,
+          iv: iv,
+          algorithm: 'aes-256-gcm',
+        )
+
+        JSON.parse(decrypted_data, symbolize_names: true)
+      end
+    end
+  end
+end

data/lib/workos/encryptors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module WorkOS
+  # Encryptors module provides pluggable encryption implementations for session data.
+  # The default encryptor is AesGcm, which uses AES-256-GCM encryption.
+  module Encryptors
+    autoload :AesGcm, 'workos/encryptors/aes_gcm'
+  end
+end

data/lib/workos/refresh_authentication_response.rb

@@ -22,13 +22,17 @@ module WorkOS
         end
       @sealed_session =
         if session && session[:seal_session]
-          WorkOS::Session.seal_data({
-                                      access_token: access_token,
-                                      refresh_token: refresh_token,
-                                      user: user.to_json,
-                                      organization_id: organization_id,
-                                      impersonator: impersonator.to_json,
-                                    }, session[:cookie_password],)
+          WorkOS::Session.seal_data(
+            {
+              access_token: access_token,
+              refresh_token: refresh_token,
+              user: user.to_json,
+              organization_id: organization_id,
+              impersonator: impersonator.to_json,
+            },
+            session[:cookie_password],
+            encryptor: session[:encryptor],
+          )
         end
     end
     # rubocop:enable Metrics/AbcSize

data/lib/workos/session.rb

@@ -12,11 +12,14 @@ module WorkOS
   # The Session class provides helper methods for working with WorkOS sessions
   # This class is not meant to be instantiated in a user space, and is instantiated internally but exposed.
   class Session
-    attr_accessor :jwks, :jwks_algorithms, :user_management, :cookie_password, :session_data, :client_id
+    attr_accessor :jwks, :jwks_algorithms, :user_management, :cookie_password, :session_data, :client_id, :encryptor
 
-    def initialize(user_management:, client_id:, session_data:, cookie_password:)
+    def initialize(user_management:, client_id:, session_data:, cookie_password:, encryptor: nil)
       raise ArgumentError, 'cookiePassword is required' if cookie_password.nil? || cookie_password.empty?
 
+      @encryptor = encryptor || WorkOS::Encryptors::AesGcm.new
+      validate_encryptor!(@encryptor)
+
       @user_management = user_management
       @cookie_password = cookie_password
       @session_data = session_data
@@ -30,13 +33,14 @@ module WorkOS
 
     # Authenticates the user based on the session data
     # @param include_expired [Boolean] If true, returns decoded token data even when expired (default: false)
+    # @param block [Proc] Optional block to call to extract additional claims from the decoded JWT
     # @return [Hash] A hash containing the authentication response and a reason if the authentication failed
     # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity
-    def authenticate(include_expired: false)
+    def authenticate(include_expired: false, &claim_extractor)
       return { authenticated: false, reason: 'NO_SESSION_COOKIE_PROVIDED' } if @session_data.nil?
 
       begin
-        session = Session.unseal_data(@session_data, @cookie_password)
+        session = Session.unseal_data(@session_data, @cookie_password, encryptor: @encryptor)
       rescue StandardError
         return { authenticated: false, reason: 'INVALID_SESSION_COOKIE' }
       end
@@ -59,7 +63,7 @@ module WorkOS
         return { authenticated: false, reason: 'INVALID_JWT' } if expired && !include_expired
 
         # Return full data for valid tokens or when include_expired is true
-        {
+        result = {
           authenticated: !expired,
           session_id: decoded['sid'],
           organization_id: decoded['org_id'],
@@ -72,6 +76,8 @@ module WorkOS
           impersonator: session[:impersonator],
           reason: expired ? 'INVALID_JWT' : nil,
         }
+        result.merge!(claim_extractor.call(decoded)) if block_given?
+        result
       rescue JWT::DecodeError
         { authenticated: false, reason: 'INVALID_JWT' }
       rescue StandardError => e
@@ -89,7 +95,7 @@ module WorkOS
       cookie_password = options.nil? || options[:cookie_password].nil? ? @cookie_password : options[:cookie_password]
 
       begin
-        session = Session.unseal_data(@session_data, cookie_password)
+        session = Session.unseal_data(@session_data, cookie_password, encryptor: @encryptor)
       rescue StandardError
         return { authenticated: false, reason: 'INVALID_SESSION_COOKIE' }
       end
@@ -101,7 +107,7 @@ module WorkOS
           client_id: @client_id,
           refresh_token: session[:refresh_token],
           organization_id: options.nil? || options[:organization_id].nil? ? nil : options[:organization_id],
-          session: { seal_session: true, cookie_password: cookie_password },
+          session: { seal_session: true, cookie_password: cookie_password, encryptor: @encryptor },
         )
 
         @session_data = auth_response.sealed_session
@@ -134,43 +140,34 @@ module WorkOS
       @user_management.get_logout_url(session_id: auth_response[:session_id], return_to: return_to)
     end
 
-    # Encrypts and seals data using AES-256-GCM
+    # Encrypts and seals data using the provided encryptor (defaults to AES-256-GCM)
     # @param data [Hash] The data to seal
     # @param key [String] The key to use for encryption
+    # @param encryptor [Object] Optional encryptor that responds to #seal(data, key)
     # @return [String] The sealed data
-    def self.seal_data(data, key)
-      iv = SecureRandom.random_bytes(12)
-
-      encrypted_data = Encryptor.encrypt(
-        value: JSON.generate(data),
-        key: key,
-        iv: iv,
-        algorithm: 'aes-256-gcm',
-      )
-      Base64.encode64(iv + encrypted_data) # Combine IV with encrypted data and encode as base64
+    def self.seal_data(data, key, encryptor: nil)
+      enc = encryptor || WorkOS::Encryptors::AesGcm.new
+      enc.seal(data, key)
     end
 
-    # Decrypts and unseals data using AES-256-GCM
+    # Decrypts and unseals data using the provided encryptor (defaults to AES-256-GCM)
     # @param sealed_data [String] The sealed data to unseal
     # @param key [String] The key to use for decryption
+    # @param encryptor [Object] Optional encryptor that responds to #unseal(sealed_data, key)
     # @return [Hash] The unsealed data
-    def self.unseal_data(sealed_data, key)
-      decoded_data = Base64.decode64(sealed_data)
-      iv = decoded_data[0..11] # Extract the IV (first 12 bytes)
-      encrypted_data = decoded_data[12..-1] # Extract the encrypted data
-
-      decrypted_data = Encryptor.decrypt(
-        value: encrypted_data,
-        key: key,
-        iv: iv,
-        algorithm: 'aes-256-gcm',
-      )
-
-      JSON.parse(decrypted_data, symbolize_names: true) # Parse the decrypted JSON string back to original data
+    def self.unseal_data(sealed_data, key, encryptor: nil)
+      enc = encryptor || WorkOS::Encryptors::AesGcm.new
+      enc.unseal(sealed_data, key)
     end
 
     private
 
+    def validate_encryptor!(enc)
+      return if enc.respond_to?(:seal) && enc.respond_to?(:unseal)
+
+      raise ArgumentError, 'encryptor must respond to #seal(data, key) and #unseal(sealed_data, key)'
+    end
+
     # Creates a JWKS set from a remote JWKS URL
     # @param uri [URI] The URI of the JWKS
     # @return [JWT::JWK::Set] The JWKS set

data/lib/workos/user_management.rb

@@ -42,14 +42,16 @@ module WorkOS
       # @param [String] client_id The WorkOS client ID for the environment
       # @param [String] session_data The sealed session data
       # @param [String] cookie_password The password used to seal the session
+      # @param [Object] encryptor Optional custom encryptor that responds to #seal and #unseal
       #
       # @return WorkOS::Session
-      def load_sealed_session(client_id:, session_data:, cookie_password:)
+      def load_sealed_session(client_id:, session_data:, cookie_password:, encryptor: nil)
         WorkOS::Session.new(
           user_management: self,
           client_id: client_id,
           session_data: session_data,
           cookie_password: cookie_password,
+          encryptor: encryptor,
         )
       end
 

data/lib/workos/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WorkOS
-  VERSION = '5.31.1'
+  VERSION = '6.0.0'
 end

data/lib/workos.rb

@@ -56,6 +56,7 @@ module WorkOS
   autoload :DirectorySync, 'workos/directory_sync'
   autoload :DirectoryUser, 'workos/directory_user'
   autoload :EmailVerification, 'workos/email_verification'
+  autoload :Encryptors, 'workos/encryptors'
   autoload :Event, 'workos/event'
   autoload :Events, 'workos/events'
   autoload :Factor, 'workos/factor'

data/spec/lib/workos/encryptors/aes_gcm_spec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+RSpec.describe WorkOS::Encryptors::AesGcm do
+  subject(:encryptor) { described_class.new }
+
+  let(:key) { 'a' * 32 }
+  let(:data) { { access_token: 'tok_123', user: { id: 'user_01' } } }
+
+  describe '#seal' do
+    it 'returns a base64-encoded string' do
+      sealed = encryptor.seal(data, key)
+      expect(sealed).to be_a(String)
+      expect { Base64.decode64(sealed) }.not_to raise_error
+    end
+
+    it 'produces different output each time (random IV)' do
+      sealed1 = encryptor.seal(data, key)
+      sealed2 = encryptor.seal(data, key)
+      expect(sealed1).not_to eq(sealed2)
+    end
+  end
+
+  describe '#unseal' do
+    it 'round-trips data correctly' do
+      sealed = encryptor.seal(data, key)
+      unsealed = encryptor.unseal(sealed, key)
+      expect(unsealed).to eq(data)
+    end
+
+    it 'returns hash with symbolized keys' do
+      sealed = encryptor.seal({ 'string_key' => 'value' }, key)
+      unsealed = encryptor.unseal(sealed, key)
+      expect(unsealed.keys.first).to be_a(Symbol)
+    end
+
+    it 'raises error with wrong key' do
+      sealed = encryptor.seal(data, key)
+      expect { encryptor.unseal(sealed, 'b' * 32) }.to raise_error(OpenSSL::Cipher::CipherError)
+    end
+  end
+end

data/spec/lib/workos/session_spec.rb

@@ -5,8 +5,8 @@ describe WorkOS::Session do
   let(:cookie_password) { 'test_very_long_cookie_password__' }
   let(:session_data) { 'test_session_data' }
   let(:jwks_url) { 'https://api.workos.com/sso/jwks/client_123' }
-  let(:jwks_hash) { '{"keys":[{"alg":"RS256","kty":"RSA","use":"sig","n":"test_n","e":"AQAB","kid":"sso_oidc_key_pair_123","x5c":["test"],"x5t#S256":"test"}]}' } # rubocop:disable all
   let(:jwk) { JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), { kid: 'sso_oidc_key_pair_123', use: 'sig', alg: 'RS256' }) }
+  let(:jwks_hash) { { keys: [jwk.export] }.to_json }
 
   before do
     allow(Net::HTTP).to receive(:get).and_return(jwks_hash)
@@ -222,6 +222,29 @@ describe WorkOS::Session do
                            })
     end
 
+    it 'merges custom claims from claim_extractor block' do
+      custom_payload = payload.merge(custom_claim: 'custom_value', another_claim: 123)
+      custom_access_token = JWT.encode(custom_payload, jwk.signing_key, jwk[:alg], { kid: jwk[:kid] })
+      custom_session_data = WorkOS::Session.seal_data({
+                                                        access_token: custom_access_token,
+                                                        user: 'user',
+                                                        impersonator: 'impersonator',
+                                                      }, cookie_password,)
+      session = WorkOS::Session.new(
+        user_management: user_management,
+        client_id: client_id,
+        session_data: custom_session_data,
+        cookie_password: cookie_password,
+      )
+      allow_any_instance_of(JWT::Decode).to receive(:verify_signature).and_return(true)
+      result = session.authenticate do |jwt|
+        { my_custom_claim: jwt['custom_claim'], my_other_claim: jwt['another_claim'] }
+      end
+      expect(result[:authenticated]).to be true
+      expect(result[:my_custom_claim]).to eq('custom_value')
+      expect(result[:my_other_claim]).to eq(123)
+    end
+
     describe 'with entitlements' do
       let(:payload) do
         {
@@ -385,4 +408,68 @@ describe WorkOS::Session do
       end
     end
   end
+
+  describe 'custom encryptor' do
+    let(:user_management) { instance_double('UserManagement') }
+    let(:custom_encryptor) do
+      Class.new do
+        def seal(data, _key)
+          "CUSTOM:#{JSON.generate(data)}"
+        end
+
+        def unseal(sealed_data, _key)
+          json = sealed_data.sub('CUSTOM:', '')
+          JSON.parse(json, symbolize_names: true)
+        end
+      end.new
+    end
+
+    before do
+      allow(user_management).to receive(:get_jwks_url).with(client_id).and_return(jwks_url)
+    end
+
+    it 'uses custom encryptor for seal_data' do
+      sealed = WorkOS::Session.seal_data({ foo: 'bar' }, 'key', encryptor: custom_encryptor)
+      expect(sealed).to start_with('CUSTOM:')
+    end
+
+    it 'uses custom encryptor for unseal_data' do
+      sealed = 'CUSTOM:{"foo":"bar"}'
+      unsealed = WorkOS::Session.unseal_data(sealed, 'key', encryptor: custom_encryptor)
+      expect(unsealed).to eq({ foo: 'bar' })
+    end
+
+    it 'accepts custom encryptor in initialize' do
+      session = WorkOS::Session.new(
+        user_management: user_management,
+        client_id: client_id,
+        session_data: session_data,
+        cookie_password: cookie_password,
+        encryptor: custom_encryptor,
+      )
+      expect(session.encryptor).to eq(custom_encryptor)
+    end
+
+    it 'defaults to AesGcm encryptor when none provided' do
+      session = WorkOS::Session.new(
+        user_management: user_management,
+        client_id: client_id,
+        session_data: session_data,
+        cookie_password: cookie_password,
+      )
+      expect(session.encryptor).to be_a(WorkOS::Encryptors::AesGcm)
+    end
+
+    it 'raises ArgumentError for invalid encryptor' do
+      expect do
+        WorkOS::Session.new(
+          user_management: user_management,
+          client_id: client_id,
+          session_data: session_data,
+          cookie_password: cookie_password,
+          encryptor: Object.new,
+        )
+      end.to raise_error(ArgumentError, /must respond to/)
+    end
+  end
 end

data/workos.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'encryptor', '~> 3.0'
-  spec.add_dependency 'jwt', '~> 2.8'
+  spec.add_dependency 'jwt', '~> 3.1'
 
   spec.add_development_dependency 'bundler', '>= 2.0.1'
   spec.add_development_dependency 'rake'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workos
 version: !ruby/object:Gem::Version
-  version: 5.31.1
+  version: 6.0.0
 platform: ruby
 authors:
 - WorkOS
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-03 00:00:00.000000000 Z
+date: 2026-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: encryptor
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.8'
+        version: '3.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.8'
+        version: '3.1'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -166,6 +166,8 @@ files:
 - lib/workos/directory_sync.rb
 - lib/workos/directory_user.rb
 - lib/workos/email_verification.rb
+- lib/workos/encryptors.rb
+- lib/workos/encryptors/aes_gcm.rb
 - lib/workos/errors.rb
 - lib/workos/event.rb
 - lib/workos/events.rb
@@ -211,6 +213,7 @@ files:
 - spec/lib/workos/configuration_spec.rb
 - spec/lib/workos/directory_sync_spec.rb
 - spec/lib/workos/directory_user_spec.rb
+- spec/lib/workos/encryptors/aes_gcm_spec.rb
 - spec/lib/workos/event_spec.rb
 - spec/lib/workos/mfa_spec.rb
 - spec/lib/workos/organizations_spec.rb
@@ -451,6 +454,7 @@ test_files:
 - spec/lib/workos/configuration_spec.rb
 - spec/lib/workos/directory_sync_spec.rb
 - spec/lib/workos/directory_user_spec.rb
+- spec/lib/workos/encryptors/aes_gcm_spec.rb
 - spec/lib/workos/event_spec.rb
 - spec/lib/workos/mfa_spec.rb
 - spec/lib/workos/organizations_spec.rb