volcano-sdk 0.29.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e946d4476603cf2c234194f51e63aadd8ca1327719bcae02bf098de61049b65b
-  data.tar.gz: 38d3aa7dbbc508796620f75285b2a483b70a9e2d49a255aded0dba3fa023334b
+  metadata.gz: 296cdb524e3552873235adccfe2d5c98b39a3da451c06777020b59d45c6a4be0
+  data.tar.gz: 9ca783889458304d91b40601f673a4f5015f117ee4f30f90c23891e351cafe3a
 SHA512:
-  metadata.gz: 014b16629b5d06e89d39f010b1c8cb550582f3f7f224b6c6911324c6b2b07196eed9729305c2edd623d6fbedb2ba12a9460d4d128bda61202c9c88874823fada
-  data.tar.gz: d98691e237fd5cdb277f701701e3549aa6e533179d36c0039e188a66143fe5992a1ac9565f210304704838d2e855a9512e9e2e60de7ec0b2abfa9a8a30ae4cb2
+  metadata.gz: 81067b14e84482e5dfebf935d27051c109ff14b87d144814a36db6ef5a7de6003e0cde0fe4ed4c54c1e06dcd9db79d8f5088c1aa21fbd4bbc3419da9a585f44e
+  data.tar.gz: 4346575e985ab233b5afd723f36e1044b4e9e001b1eefa461a2514977f10a240a88a73978f30d88b2b74a3ec2a6bd4565d1e1ab92968e1988069492cbae9c739

data/lib/volcano/auth.rb

@@ -3,6 +3,13 @@
 module Volcano
   # Authenticates users and updates the client session.
   class Auth
+    include AuthRefresh
+    include AuthSignOut
+    include AuthProfile
+    include AuthUpdateUser
+    include AuthEmailChange
+    include AuthSessions
+
     INCOMPLETE_SESSION = 'Expected a complete Volcano::Session'
     private_constant :INCOMPLETE_SESSION
 

data/lib/volcano/auth_email_change.rb

@@ -2,7 +2,7 @@
 
 module Volcano
   # Email-change request behavior for the authentication facade.
-  class Auth
+  module AuthEmailChange
     INVALID_EMAIL_CHANGE_RESULT = 'Expected a valid email-change acknowledgement'
     private_constant :INVALID_EMAIL_CHANGE_RESULT
 

data/lib/volcano/auth_get_user.rb

@@ -1,21 +1,12 @@
 # frozen_string_literal: true
 
-require 'time'
-
 module Volcano
-  # Server-validated current-user behavior for the authentication facade.
-  class Auth
-    INVALID_USER = 'Expected a complete user profile'
-    RFC3339_OFFSET = /(?:[Zz]|[+-]\d{2}:\d{2})\z/
-    USER_OPTIONAL_VALUES = %w[project_id email_confirmed user_metadata app_metadata avatar_url].freeze
-    USER_OPTIONAL_STRINGS = %w[project_id avatar_url].freeze
-    USER_STATUSES = %w[active banned deleted].freeze
-    USER_TIMESTAMPS = %w[banned_until last_sign_in_at created_at updated_at].freeze
-    private_constant :INVALID_USER, :RFC3339_OFFSET, :USER_OPTIONAL_STRINGS,
-                     :USER_OPTIONAL_VALUES, :USER_STATUSES, :USER_TIMESTAMPS
+  # Current-user requests and session cache updates.
+  module AuthProfile
+    include AuthProfileFields
 
     def user
-      profile_request { method(:get_user_response) }
+      profile_request { ->(token) { get_user_response(token) } }
     end
 
     alias get_user user
@@ -32,7 +23,7 @@ module Volcano
     end
 
     def cache_current_user(payload, generation)
-      profile = user_payload(payload)
+      profile = profile_user_payload(payload)
       user = build_user(profile)
       raise Error::SessionChangedError unless @client.update_session_user_if_current?(profile, generation)
 
@@ -46,79 +37,47 @@ module Volcano
     end
 
     def build_user(payload)
-      raise Error::AuthenticationError, INVALID_USER unless valid_user?(payload)
-
-      User.new(**user_attributes(payload))
+      new_profile_user(user_identity(payload), user_optional_attributes(payload), user_timestamps(payload))
     rescue ArgumentError => e
       raise Error::AuthenticationError, INVALID_USER, cause: e
     end
 
-    def user_attributes(payload)
-      {
-        id: payload.fetch('id'),
-        email: payload.fetch('email'),
-        status: payload.fetch('status'),
-        **USER_OPTIONAL_VALUES.to_h { |name| [name.to_sym, payload[name]] },
-        **USER_TIMESTAMPS.to_h { |name| [name.to_sym, parse_time(payload[name])] }
-      }
-    end
-
-    def user_payload(payload)
-      raise Error::AuthenticationError, INVALID_USER unless payload.is_a?(Hash)
-
-      payload['user']
-    end
-
-    def valid_user?(payload)
-      return false unless payload.is_a?(Hash)
-
-      required_user_fields?(payload) && valid_optional_user_fields?(payload)
-    end
-
-    def valid_optional_user_fields?(payload)
-      valid_email_confirmation?(payload) && valid_metadata?(payload) &&
-        valid_optional_strings?(payload) && valid_timestamps?(payload)
-    end
-
-    def required_user_fields?(payload)
-      complete_string?(payload['id']) && payload['email'].is_a?(String) &&
-        USER_STATUSES.include?(payload['status'])
-    end
-
-    def valid_email_confirmation?(payload)
-      [true, false, nil].include?(payload['email_confirmed'])
+    def new_profile_user(identity, optional, timestamps)
+      User.new(
+        id: identity[:id], email: identity[:email], status: identity[:status],
+        project_id: optional[:project_id], email_confirmed: optional[:email_confirmed],
+        user_metadata: optional[:user_metadata], app_metadata: optional[:app_metadata],
+        avatar_url: optional[:avatar_url], banned_until: timestamps[:banned_until],
+        last_sign_in_at: timestamps[:last_sign_in_at], created_at: timestamps[:created_at],
+        updated_at: timestamps[:updated_at]
+      )
     end
 
-    def valid_metadata?(payload)
-      %w[user_metadata app_metadata].all? do |name|
-        payload[name].nil? || payload[name].is_a?(Hash)
-      end
-    end
-
-    def valid_optional_strings?(payload)
-      USER_OPTIONAL_STRINGS.all? do |name|
-        payload[name].nil? || payload[name].is_a?(String)
-      end
-    end
-
-    def valid_timestamps?(payload)
-      USER_TIMESTAMPS.all? { |name| valid_timestamp?(payload[name]) }
-    end
-
-    def valid_timestamp?(value)
-      return true if value.nil?
-
-      value.is_a?(String) && RFC3339_OFFSET.match?(value) && Time.iso8601(value)
-    rescue ArgumentError
-      false
+    def user_identity(payload)
+      {
+        id: profile_required_id(payload['id']),
+        email: profile_required_string(payload['email']),
+        status: profile_status(payload['status'])
+      }
     end
 
-    def parse_time(value)
-      Time.iso8601(value).freeze unless value.nil?
+    def user_optional_attributes(payload)
+      {
+        project_id: profile_optional_string(payload['project_id']),
+        email_confirmed: profile_optional_boolean(payload['email_confirmed']),
+        user_metadata: profile_optional_object(payload['user_metadata']),
+        app_metadata: profile_optional_object(payload['app_metadata']),
+        avatar_url: profile_optional_string(payload['avatar_url'])
+      }
     end
 
-    def complete_string?(value)
-      value.is_a?(String) && !value.strip.empty?
+    def user_timestamps(payload)
+      {
+        banned_until: profile_parse_time(payload['banned_until']),
+        last_sign_in_at: profile_parse_time(payload['last_sign_in_at']),
+        created_at: profile_parse_time(payload['created_at']),
+        updated_at: profile_parse_time(payload['updated_at'])
+      }
     end
   end
 end

data/lib/volcano/auth_notification_dispatch.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Runs queued auth-state callbacks outside session coordination locks.
+  module AuthNotificationDispatch
+    private
+
+    def run_auth_notifications(notifications)
+      notifications.each do |notification|
+        notification.call
+        nil
+      end
+    end
+  end
+  private_constant :AuthNotificationDispatch
+end

data/lib/volcano/auth_oauth.rb

@@ -88,5 +88,9 @@ module Volcano
     def valid_linked_oauth_provider?(provider, linked_at, updated_at)
       complete_string?(provider) && linked_at.is_a?(Time) && updated_at.is_a?(Time)
     end
+
+    def complete_string?(value)
+      value.is_a?(String) && !value.strip.empty?
+    end
   end
 end

data/lib/volcano/auth_oauth_api.rb

@@ -6,9 +6,12 @@ module Volcano
     def call_oauth_api(provider, endpoint:, method: 'GET', body: nil)
       session_payload(200, decode: :oauth_api_data) do
         provider_name = oauth_provider_name(provider)
-        request = { endpoint: endpoint.dup.freeze, method: method.dup.freeze,
-                    body: body.nil? ? nil : JSON.parse(JSON.generate(body), freeze: true) }
-        ->(token) { oauth_api_response(token, provider_name, **request) }
+        owned_endpoint = endpoint.dup.freeze
+        owned_method = method.dup.freeze
+        owned_body = body.nil? ? nil : JSON.parse(JSON.generate(body), freeze: true)
+        lambda do |token|
+          oauth_api_response(token, provider_name, endpoint: owned_endpoint, method: owned_method, body: owned_body)
+        end
       end
     end
 
@@ -24,6 +27,8 @@ module Volcano
     end
 
     def oauth_api_data(response_body)
+      raise TypeError, 'Expected OAuth provider API response data' unless response_body.is_a?(Hash)
+
       data = response_body.fetch('data')
       freeze_oauth_api_data(data)
     rescue KeyError, NoMethodError

data/lib/volcano/auth_oauth_sign_in.rb

@@ -20,7 +20,7 @@ module Volcano
     def exchange_oauth_code(code:, redirect_to:, state:, expected_state:)
       validate_oauth_callback_state(state, expected_state)
       generation, = @client.capture_session
-      session = build_session(Transport.body(oauth_exchange_response(code, redirect_to), 200))
+      session = owned_complete_session(build_session(Transport.body(oauth_exchange_response(code, redirect_to), 200)))
       raise Error::SessionChangedError unless @client.store_session_if_current?(session, generation)
 
       session

data/lib/volcano/auth_oauth_token.rb

@@ -32,6 +32,8 @@ module Volcano
     end
 
     def oauth_provider_token_status(body)
+      raise TypeError, 'Expected complete OAuth provider token status' unless body.is_a?(Hash)
+
       message, provider, expires_in = body.fetch_values('message', 'provider', 'expires_in')
       OAuthProviderTokenStatus.new(message:, provider:, expires_in:)
     rescue KeyError, NoMethodError

data/lib/volcano/auth_profile_fields.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Volcano
+  # Validates and maps the current-user JSON response.
+  module AuthProfileFields
+    INVALID_USER = 'Expected a complete user profile'
+    RFC3339_OFFSET = /(?:[Zz]|[+-]\d{2}:\d{2})\z/
+    USER_STATUSES = %w[active banned deleted].freeze
+    private_constant :INVALID_USER, :RFC3339_OFFSET, :USER_STATUSES
+
+    private
+
+    def profile_user_payload(payload)
+      raise Error::AuthenticationError, INVALID_USER unless payload.is_a?(Hash)
+
+      profile_json_object(payload['user'])
+    end
+
+    def profile_json_object(payload)
+      raise Error::AuthenticationError, INVALID_USER unless payload.is_a?(Hash)
+
+      payload.to_h do |key, value|
+        raise Error::AuthenticationError, INVALID_USER unless key.is_a?(String)
+
+        [key, profile_json_value(value)]
+      end
+    end
+
+    def profile_json_value(value)
+      case value
+      when Array then value.map { |item| profile_json_value(item) }
+      when Hash then profile_json_object(value)
+      else profile_json_scalar(value)
+      end
+    end
+
+    def profile_json_scalar(value)
+      case value
+      when nil, true, false, Integer, String then value
+      when Float then profile_finite_float(value)
+      else raise Error::AuthenticationError, INVALID_USER
+      end
+    end
+
+    def profile_finite_float(value)
+      raise Error::AuthenticationError, INVALID_USER unless value.finite?
+
+      value
+    end
+
+    def profile_required_string(value)
+      raise Error::AuthenticationError, INVALID_USER unless value.is_a?(String)
+
+      value
+    end
+
+    def profile_required_id(value)
+      raise Error::AuthenticationError, INVALID_USER unless value.is_a?(String) && !value.strip.empty?
+
+      value
+    end
+
+    def profile_status(value)
+      raise Error::AuthenticationError, INVALID_USER unless value.is_a?(String) && USER_STATUSES.include?(value)
+
+      value
+    end
+
+    def profile_optional_string(value)
+      return if value.nil?
+
+      profile_required_string(value)
+    end
+
+    def profile_optional_object(value)
+      profile_json_object(value) unless value.nil?
+    end
+
+    def profile_optional_boolean(value)
+      return if value.nil?
+      return true if value == true
+      return false if value == false
+
+      raise Error::AuthenticationError, INVALID_USER
+    end
+
+    def profile_parse_time(value)
+      return if value.nil?
+      raise Error::AuthenticationError, INVALID_USER unless value.is_a?(String) && RFC3339_OFFSET.match?(value)
+
+      Time.iso8601(value).freeze
+    rescue ArgumentError
+      raise Error::AuthenticationError, INVALID_USER
+    end
+  end
+end

data/lib/volcano/auth_refresh.rb

@@ -2,12 +2,16 @@
 
 module Volcano
   # Refreshes only the session captured by the initiating operation.
-  class Auth
+  module AuthRefresh
+    include AuthNotificationDispatch
+    include AuthSessionBinding
+
     def refresh_session
       binding = @client.capture_session_binding
-      raise Error::AuthenticationError, 'No active session' unless binding.last
+      session = binding.last
+      raise Error::AuthenticationError, 'No active session' unless session
 
-      refresh_captured_session(binding)
+      refresh_captured_session([binding.first, binding[1], session])
     end
 
     def session_request(binding: @client.capture_session_binding)
@@ -26,7 +30,7 @@ module Volcano
       response
     end
 
-    alias session_read session_request
+    def session_read(...) = session_request(...)
 
     private
 
@@ -51,6 +55,7 @@ module Volcano
     end
 
     def refresh_with_notifications(binding)
+      # @type var notifications: Array[Method]
       notifications = []
       active_generation, = owned_session_binding(binding)
       binding[1].refresh { perform_refresh(binding, notifications) } if active_generation == binding.first
@@ -60,31 +65,17 @@ module Volcano
       raise
     ensure
       # Only the dispatcher owner drains, after refresh coordination is released.
-      notifications.each(&:call)
-    end
-
-    def owned_session_binding(binding)
-      active = @client.capture_session_binding
-      raise Error::AuthenticationError, 'No active session' if rejected_refresh?(binding, active)
-
-      _, active_lineage, current = active
-      raise Error::SessionChangedError unless current && active_lineage == binding[1]
-
-      active
-    end
-
-    def rejected_refresh?(binding, active)
-      generation, lineage, = binding
-      @client.refresh_rejected?(generation, lineage) &&
-        active.first == generation + 1 && active.last.nil?
+      run_auth_notifications(notifications)
     end
 
     def perform_refresh(binding, notifications)
       active = owned_session_binding(binding)
       return active.last if active.first != binding.first
-      raise Error::AuthenticationError, 'No refresh token' unless binding.last.refresh_token
 
-      session = refreshed_session(binding, notifications)
+      refresh_token = binding.last.refresh_token
+      raise Error::AuthenticationError, 'No refresh token' unless refresh_token
+
+      session = refreshed_session(binding, refresh_token, notifications)
       unless binding[1].closing?
         @client.store_session_if_current?(
           session, binding.first, event: :token_refreshed, notifications: notifications
@@ -93,17 +84,23 @@ module Volcano
       session
     end
 
-    def refreshed_session(binding, notifications)
+    def refreshed_session(binding, refresh_token, notifications)
       _, owner, current = binding
       verified = owner.verified_pair?(current)
-      SessionCredentials.validate_refresh_source(current, verified: verified)
-      owner.verify_pair(nil)
-      session = parse_refresh_session(refresh_payload(binding, notifications))
+      begin
+        SessionCredentials.validate_refresh_source(current, verified: verified)
+        owner.verify_pair(nil)
+        parse_and_verify_refresh(owner, current, binding, refresh_token, notifications)
+      rescue Error::RateLimitedError
+        owner.verify_pair(current) if verified
+        raise
+      end
+    end
+
+    def parse_and_verify_refresh(owner, current, binding, refresh_token, notifications)
+      session = parse_refresh_session(refresh_payload(binding, refresh_token, notifications))
       verify_refreshed_session(owner, current, session)
       session
-    rescue Error::RateLimitedError
-      owner.verify_pair(current) if verified
-      raise
     end
 
     def verify_refreshed_session(owner, current, session)
@@ -111,8 +108,8 @@ module Volcano
       owner.verify_pair(session)
     end
 
-    def refresh_payload(binding, notifications)
-      Transport.body(refresh_response(binding.last.refresh_token), 200)
+    def refresh_payload(binding, refresh_token, notifications)
+      Transport.body(refresh_response(refresh_token), 200)
     rescue Error::AuthenticationError
       generation, owner, = binding
       @client.reject_refresh_if_current?(generation, notifications: notifications) unless owner.closing?

data/lib/volcano/auth_session_binding.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Rejects stale or replaced auth-session lineages.
+  module AuthSessionBinding
+    private
+
+    def owned_session_binding(binding)
+      active = @client.capture_session_binding
+      raise Error::AuthenticationError, 'No active session' if rejected_refresh?(binding, active)
+
+      _, active_lineage, current = active
+      raise Error::SessionChangedError unless current && active_lineage == binding[1]
+
+      [active.first, active_lineage, current]
+    end
+
+    def rejected_refresh?(binding, active)
+      generation, lineage, = binding
+      @client.refresh_rejected?(generation, lineage) &&
+        active.first == generation + 1 && active.last.nil?
+    end
+  end
+  private_constant :AuthSessionBinding
+end

data/lib/volcano/auth_sessions.rb

@@ -1,49 +1,10 @@
 # frozen_string_literal: true
 
-require 'json'
+require_relative 'session_page_mapping'
 
 module Volcano
-  # Maps the internal wire response to immutable public session values.
-  module SessionPageMapping
-    SESSION_FIELDS = %i[
-      id user_id provider expires_at is_active is_current user_agent ip_address last_ip_address
-      last_activity_at session_started_at created_at updated_at
-    ].freeze
-    REQUIRED_SESSION_FIELDS = SESSION_FIELDS.first(6).freeze
-
-    private
-
-    def session_page(body)
-      raise TypeError, 'Expected a complete session page' unless body.is_a?(Hash)
-
-      sessions = body.fetch('sessions')
-      raise TypeError, 'Expected a complete session page' unless sessions.is_a?(Array)
-
-      SessionPage.new(
-        sessions: sessions.map { |attributes| auth_session(attributes) },
-        total: body.fetch('total'), page: body.fetch('page'), limit: body.fetch('limit'),
-        total_pages: body.fetch('total_pages')
-      )
-    rescue KeyError
-      raise TypeError, 'Expected a complete session page'
-    end
-
-    def auth_session(attributes)
-      raise TypeError, 'Expected a complete authentication session' unless attributes.is_a?(Hash)
-
-      required = REQUIRED_SESSION_FIELDS.to_h { |name| [name, attributes.fetch(name.to_s)] }
-      optional = (SESSION_FIELDS - REQUIRED_SESSION_FIELDS).to_h do |name|
-        [name, attributes[name.to_s]]
-      end
-      AuthSession.new(**required, **optional)
-    rescue KeyError
-      raise TypeError, 'Expected a complete authentication session'
-    end
-  end
-  private_constant :SessionPageMapping
-
   # Multi-device session behavior for the authentication facade.
-  class Auth
+  module AuthSessions
     include SessionPageMapping
 
     def list_sessions(page: 1, limit: 20)
@@ -57,10 +18,11 @@ module Volcano
 
     def delete_session(session_id)
       binding = @client.capture_session_binding
-      raise Error::AuthenticationError, 'No active session' unless binding.last
+      session = binding.last
+      raise Error::AuthenticationError, 'No active session' unless session
 
       request_id = session_id.dup.freeze
-      deletes_current = same_session_id?(binding.last.access_token, request_id)
+      deletes_current = same_session_id?(session.access_token, request_id)
       error = delete_bound_session_error(binding, request_id)
       current_unchanged = session_unchanged_after_deletion?(deletes_current, error, binding)
       raise Error::SessionChangedError, cause: error unless current_unchanged
@@ -119,12 +81,14 @@ module Volcano
 
     def deletion_binding_current?(binding, error)
       active = @client.capture_session_binding
-      (active.last && active[1] == binding[1]) || (error && rejected_refresh?(binding, active))
+      return true if active.last && active[1] == binding[1]
+
+      !error.nil? && rejected_refresh?(binding, active)
     end
 
     def same_session_id?(access_token, session_id)
       current_session_id = access_token_session_id(access_token)
-      session_id.is_a?(String) && current_session_id&.casecmp?(session_id)
+      session_id.is_a?(String) && current_session_id&.casecmp?(session_id) == true
     end
 
     def access_token_session_id(access_token)

data/lib/volcano/auth_sign_out.rb

@@ -2,24 +2,28 @@
 
 module Volcano
   # Revokes the captured server session and clears its local lineage.
-  class Auth
+  module AuthSignOut
+    include AuthNotificationDispatch
+
     def sign_out
+      # @type var notifications: Array[Method]
+      notifications = []
       binding = @client.capture_session_binding
-      return binding[1].wait_for_sign_out unless binding.last
+      session = binding.last
+      return binding[1].wait_for_sign_out unless session
 
-      notifications = []
       binding[1].sign_out do |preceding, pending|
-        sign_out_captured(binding, preceding, pending, notifications)
+        sign_out_captured(binding, session, preceding, pending, notifications)
       end
     ensure
-      notifications&.each(&:call)
+      run_auth_notifications(notifications)
     end
 
     private
 
-    def sign_out_captured(binding, preceding, pending, notifications)
+    def sign_out_captured(binding, session, preceding, pending, notifications)
       generation, owner, = binding
-      current, refresh_error = revocation_credentials(binding, preceding)
+      current, refresh_error = revocation_credentials(owner, session, preceding)
       error = revocation_error(current, owner, pending ? refresh_error : nil, joined: pending)
       cleared = @client.clear_session_if_current?(generation, lineage: owner, notifications: notifications)
       raise Error::SessionChangedError, cause: error unless cleared
@@ -27,10 +31,13 @@ module Volcano
       raise error if error
     end
 
-    def revocation_credentials(binding, preceding)
-      [binding[1].result(preceding) || binding.last, nil]
+    def revocation_credentials(owner, session, preceding)
+      resolved = owner.result(preceding) || session
+      raise TypeError, 'Expected a session from refresh' unless resolved.is_a?(Session)
+
+      [resolved, nil]
     rescue Error::VolcanoError => e
-      [binding.last, e]
+      [session, e]
     end
 
     def logout_response(refresh_token)
@@ -67,16 +74,17 @@ module Volcano
 
     def revoke_access_session(session, session_id, refresh_error, joined:)
       error = delete_session_error(session.access_token, session_id)
-      return error unless refreshable_revocation?(error, session)
+      refresh_token = refreshable_revocation_token(error, session)
+      return error unless refresh_token
       return refresh_error || error if joined
 
-      refreshed = parse_refresh_session(Transport.body(refresh_response(session.refresh_token), 200))
+      refreshed = parse_refresh_session(Transport.body(refresh_response(refresh_token), 200))
       SessionCredentials.validate_refresh(session, refreshed)
       delete_session_error(refreshed.access_token, session_id)
     end
 
-    def refreshable_revocation?(error, session)
-      error&.status == 401 && session.refresh_token
+    def refreshable_revocation_token(error, session)
+      session.refresh_token if error&.status == 401
     end
   end
 end

data/lib/volcano/auth_state.rb

@@ -81,9 +81,10 @@ module Volcano
 
     def update_user_if_current?(user, generation)
       @mutex.synchronize do
-        return false unless generation == @generation && @session
+        current = @session
+        return false unless generation == @generation && current
 
-        @session = SessionCredentials.with_user(@session, user)
+        @session = SessionCredentials.with_user(current, user)
         true
       end
     end

data/lib/volcano/auth_state_notifications.rb

@@ -3,8 +3,8 @@
 module Volcano
   # Queues auth events under the state mutex and invokes subscribers outside it.
   module AuthStateNotifications
-    CALLBACK_FAILURES = [Exception].freeze
-    private_constant :CALLBACK_FAILURES
+    CALLBACK_FAILURE = Exception
+    private_constant :CALLBACK_FAILURE
 
     private
 
@@ -26,12 +26,14 @@ module Volcano
     end
 
     def drain_notifications
+      # @type var failure: Exception?
       failure = nil
       loop do
         notification = next_notification
         break unless notification
 
-        current_failure = notify(*notification)
+        callback_ids, event, session = notification
+        current_failure = notify(callback_ids, event, session)
         failure ||= current_failure
       end
       raise failure if failure
@@ -48,12 +50,13 @@ module Volcano
     end
 
     def notify(callback_ids, event, session)
+      # @type var failure: Exception?
       failure = nil
       callback_ids.each do |callback_id|
         @mutex.synchronize { @callbacks[callback_id] }&.call(event, session)
       rescue StandardError => e
         Warning.warn("Volcano auth-state callback failed (#{e.class})\n")
-      rescue *CALLBACK_FAILURES => e
+      rescue CALLBACK_FAILURE => e
         unsubscribe(callback_id)
         failure ||= e
       end

data/lib/volcano/auth_update_user.rb

@@ -2,7 +2,7 @@
 
 module Volcano
   # Current-user update behavior for the authentication facade.
-  class Auth
+  module AuthUpdateUser
     def update_user(password: nil, metadata: nil)
       profile_request do
         request_password = password&.dup&.freeze

data/lib/volcano/session.rb

@@ -9,79 +9,6 @@ module Volcano
   end
   private_constant :SESSION_USER_CODER
 
-  # Owns credential snapshots and preserves validated identity during refresh.
-  module SessionCredentials
-    def self.build(access_token, refresh_token)
-      raise ArgumentError, 'refresh_token requires access_token' if access_token.nil? && !refresh_token.nil?
-      return if access_token.nil?
-
-      Session.new(access_token: credential(access_token, :access_token),
-                  refresh_token: credential(refresh_token, :refresh_token))
-    end
-
-    def self.credential(value, name)
-      return if value.nil?
-
-      raise ArgumentError, "#{name} must be a non-empty string" unless value.is_a?(String) && !value.strip.empty?
-
-      value.dup.freeze
-    end
-    private_class_method :credential
-
-    def self.validate_refresh_source(current, verified: false)
-      return if verified || session_id(current.access_token)
-
-      raise Error::AuthenticationError, 'Cannot refresh supplied credentials without a session identifier'
-    end
-
-    def self.validate_refresh(current, refreshed)
-      return unless current
-
-      validate_refresh_session_id(current, refreshed)
-      return unless current.user_id && current.user_id != refreshed&.user_id
-
-      raise Error::AuthenticationError, 'Refreshed session belongs to a different user'
-    end
-
-    def self.validate_refresh_session_id(current, refreshed)
-      expected = session_id(current.access_token)
-      return unless expected && expected != session_id(refreshed&.access_token)
-
-      raise Error::AuthenticationError, 'Refreshed credentials belong to a different server session'
-    end
-    private_class_method :validate_refresh_session_id
-
-    # Untrusted continuity constraint, never authenticated user identity.
-    def self.session_id(access_token)
-      payload = token_payload(access_token)
-      return unless payload.is_a?(Hash)
-
-      value = payload['session_id']
-      value.downcase if value.is_a?(String) && value.match?(/\A[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/i)
-    end
-
-    def self.token_payload(access_token)
-      return unless access_token.is_a?(String)
-
-      parts = access_token.split('.')
-      return unless parts.length == 3
-
-      encoded = parts.fetch(1).tr('-_', '+/')
-      JSON.parse((encoded + ('=' * (-encoded.length % 4))).unpack1('m0'))
-    rescue ArgumentError, JSON::ParserError
-      nil
-    end
-    private_class_method :token_payload
-
-    def self.with_user(session, user)
-      user_id = (session.user_id || user.fetch('id')).dup.freeze
-      raise Error::AuthenticationError, 'Profile belongs to a different user' unless user['id'] == user_id
-
-      Session.new(**session.to_h, user_id: user_id, user: user)
-    end
-  end
-  private_constant :SessionCredentials
-
   # Local credentials; refresh credentials and user identity may be unknown.
   Session = Data.define(:access_token, :refresh_token, :user_id, :user) do
     def initialize(access_token:, refresh_token: nil, user_id: nil, user: nil)

data/lib/volcano/session_credentials.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require_relative 'session'
+
+module Volcano
+  # Owns credential snapshots and preserves validated identity during refresh.
+  module SessionCredentials
+    def self.build(access_token, refresh_token)
+      raise ArgumentError, 'refresh_token requires access_token' if access_token.nil? && !refresh_token.nil?
+      return if access_token.nil?
+
+      Session.new(access_token: credential(access_token, :access_token),
+                  refresh_token: refresh_token.nil? ? nil : credential(refresh_token, :refresh_token))
+    end
+
+    def self.credential(value, name)
+      raise ArgumentError, "#{name} must be a non-empty string" unless value.is_a?(String) && !value.strip.empty?
+
+      value.dup.freeze
+    end
+    private_class_method :credential
+
+    def self.validate_refresh_source(current, verified: false)
+      return if verified || session_id(current.access_token)
+
+      raise Error::AuthenticationError, 'Cannot refresh supplied credentials without a session identifier'
+    end
+
+    def self.validate_refresh(current, refreshed)
+      return unless current
+
+      validate_refresh_session_id(current, refreshed)
+      return unless current.user_id && current.user_id != refreshed&.user_id
+
+      raise Error::AuthenticationError, 'Refreshed session belongs to a different user'
+    end
+
+    def self.validate_refresh_session_id(current, refreshed)
+      expected = session_id(current.access_token)
+      return unless expected && expected != session_id(refreshed&.access_token)
+
+      raise Error::AuthenticationError, 'Refreshed credentials belong to a different server session'
+    end
+    private_class_method :validate_refresh_session_id
+
+    # Untrusted continuity constraint, never authenticated user identity.
+    def self.session_id(access_token)
+      payload = token_payload(access_token)
+      return unless payload.is_a?(Hash)
+
+      value = payload['session_id']
+      value.downcase if value.is_a?(String) && value.match?(/\A[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/i)
+    end
+
+    def self.token_payload(access_token)
+      return unless access_token.is_a?(String)
+
+      parts = access_token.split('.')
+      return unless parts.length == 3
+
+      encoded = parts.fetch(1).tr('-_', '+/')
+      JSON.parse(Base64.strict_decode64(encoded + ('=' * (-encoded.length % 4))))
+    rescue ArgumentError, JSON::ParserError
+      nil
+    end
+    private_class_method :token_payload
+
+    def self.with_user(session, user)
+      user_id = session.user_id || user.fetch('id')
+      raise Error::AuthenticationError, 'Profile has no valid user identifier' unless user_id.is_a?(String)
+
+      user_id = user_id.dup.freeze
+      raise Error::AuthenticationError, 'Profile belongs to a different user' unless user['id'] == user_id
+
+      Session.new(access_token: session.access_token, refresh_token: session.refresh_token,
+                  user_id: user_id, user: user)
+    end
+  end
+  private_constant :SessionCredentials
+end

data/lib/volcano/session_operations.rb

@@ -42,7 +42,9 @@ module Volcano
     def refresh(&)
       operation, owner = @mutex.synchronize do
         raise Error::SessionChangedError if @sign_out || @locally_cleared
-        next [@refresh, false] if @refresh && !@refresh.done
+
+        current = @refresh
+        next [current, false] if current && !current.done
 
         @refresh = Outcome.new(false)
         [@refresh, true]
@@ -51,11 +53,7 @@ module Volcano
     end
 
     def sign_out
-      operation, owner, preceding, pending = @mutex.synchronize do
-        first = @sign_out.nil?
-        @sign_out ||= Outcome.new(false)
-        [@sign_out, first, @refresh, @refresh && !@refresh.done]
-      end
+      operation, owner, preceding, pending = @mutex.synchronize { claim_sign_out }
       execute(operation, owner) do
         yield(preceding, pending)
       ensure
@@ -79,10 +77,19 @@ module Volcano
 
     private
 
+    def claim_sign_out
+      first = @sign_out.nil? == true
+      operation = @sign_out ||= Outcome.new(false)
+      current = @refresh
+      [operation, first, current, current && !current.done]
+    end
+
     def execute(operation, owner)
       return result(operation) unless owner
 
       completed = false
+      # @type var value: Object?
+      value = nil
       begin
         value = yield
         completed = true

data/lib/volcano/session_page_mapping.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Maps the internal wire response to immutable public session values.
+  module SessionPageMapping
+    private
+
+    def session_page(body)
+      raise TypeError, 'Expected a complete session page' unless body.is_a?(Hash)
+
+      sessions = body.fetch('sessions')
+      raise TypeError, 'Expected a complete session page' unless sessions.is_a?(Array)
+
+      SessionPage.new(
+        sessions: sessions.map { |attributes| auth_session(attributes) },
+        total: required_integer(body, 'total'), page: required_integer(body, 'page'),
+        limit: required_integer(body, 'limit'), total_pages: required_integer(body, 'total_pages')
+      )
+    rescue KeyError
+      raise TypeError, 'Expected a complete session page'
+    end
+
+    def auth_session(attributes)
+      raise TypeError, 'Expected a complete authentication session' unless attributes.is_a?(Hash)
+
+      build_auth_session(attributes)
+    rescue KeyError
+      raise TypeError, 'Expected a complete authentication session'
+    end
+
+    def build_auth_session(attributes)
+      AuthSession.new(
+        id: required_string(attributes, 'id'), user_id: required_string(attributes, 'user_id'),
+        provider: required_string(attributes, 'provider'), expires_at: required_time(attributes, 'expires_at'),
+        is_active: required_boolean(attributes, 'is_active'), is_current: required_boolean(attributes, 'is_current'),
+        user_agent: optional_string(attributes, 'user_agent'), ip_address: optional_string(attributes, 'ip_address'),
+        last_ip_address: optional_string(attributes, 'last_ip_address'),
+        last_activity_at: optional_time(attributes, 'last_activity_at'),
+        session_started_at: optional_time(attributes, 'session_started_at'),
+        created_at: optional_time(attributes, 'created_at'), updated_at: optional_time(attributes, 'updated_at')
+      )
+    end
+
+    def required_integer(body, name)
+      value = body.fetch(name)
+      raise TypeError, 'Expected a complete session page' unless value.is_a?(Integer)
+
+      value
+    end
+
+    def required_string(body, name)
+      value = body.fetch(name)
+      raise TypeError, 'Expected a complete authentication session' unless value.is_a?(String)
+
+      value
+    end
+
+    def required_time(body, name)
+      value = body.fetch(name)
+      raise TypeError, 'Expected a complete authentication session' unless value.is_a?(Time)
+
+      value
+    end
+
+    def required_boolean(body, name)
+      value = body.fetch(name)
+      unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        raise TypeError, 'Expected a complete authentication session'
+      end
+
+      value
+    end
+
+    def optional_string(body, name)
+      value = body[name]
+      raise TypeError, 'Expected a complete authentication session' unless value.nil? || value.is_a?(String)
+
+      value
+    end
+
+    def optional_time(body, name)
+      value = body[name]
+      raise TypeError, 'Expected a complete authentication session' unless value.nil? || value.is_a?(Time)
+
+      value
+    end
+  end
+  private_constant :SessionPageMapping
+end

data/lib/volcano/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Volcano
-  VERSION = '0.29.0'
+  VERSION = '0.30.0'
 end

data/lib/volcano.rb

@@ -5,6 +5,7 @@ require_relative 'volcano/connection_string'
 require_relative 'volcano/models'
 require_relative 'volcano/user'
 require_relative 'volcano/session'
+require_relative 'volcano/session_credentials'
 require_relative 'volcano/function_response'
 require_relative 'volcano/durable_models'
 require_relative 'volcano/log_responses'
@@ -16,16 +17,21 @@ require_relative 'volcano/errors'
 require_relative 'volcano/redaction'
 require_relative 'volcano/transport'
 require_relative 'volcano/generated_transport'
-require_relative 'volcano/auth'
+require_relative 'volcano/auth_notification_dispatch'
+require_relative 'volcano/auth_session_binding'
 require_relative 'volcano/auth_sign_out'
 require_relative 'volcano/auth_refresh'
+require_relative 'volcano/auth_profile_fields'
+require_relative 'volcano/auth_get_user'
+require_relative 'volcano/auth_update_user'
+require_relative 'volcano/auth_email_change'
+require_relative 'volcano/auth_sessions'
+require_relative 'volcano/auth'
 require_relative 'volcano/auth_sign_up'
 require_relative 'volcano/sign_up_result'
 require_relative 'volcano/auth_anonymous'
 require_relative 'volcano/auth_confirm_email'
 require_relative 'volcano/auth_resend_confirmation'
-require_relative 'volcano/auth_email_change'
-require_relative 'volcano/auth_sessions'
 require_relative 'volcano/auth_oauth'
 require_relative 'volcano/auth_oauth_sign_in'
 require_relative 'volcano/auth_hosted'
@@ -33,8 +39,6 @@ require_relative 'volcano/auth_oauth_token'
 require_relative 'volcano/auth_oauth_api'
 require_relative 'volcano/auth_reset_password_for_email'
 require_relative 'volcano/auth_reset_password'
-require_relative 'volcano/auth_get_user'
-require_relative 'volcano/auth_update_user'
 require_relative 'volcano/database'
 require_relative 'volcano/function_resolution'
 require_relative 'volcano/functions'
@@ -58,8 +62,10 @@ require_relative 'volcano/client'
 
 # Public namespace for the Volcano Ruby SDK.
 module Volcano
-  private_constant :GeneratedTransport, :LockAutoRenewal, :LockLeaseClock, :LockRenewer, :LockSession, :LockResponse,
-                   :Redaction, :SessionOperations
+  private_constant :AuthRefresh, :AuthSignOut, :AuthProfile, :AuthProfileFields, :AuthUpdateUser, :AuthEmailChange,
+                   :AuthSessions,
+                   :GeneratedTransport, :LockAutoRenewal, :LockLeaseClock, :LockRenewer,
+                   :LockSession, :LockResponse, :Redaction, :SessionOperations
 
   Realtime.private_constant :Protocol, :ProtocolDispatch, :ProtocolPublicationDispatch, :ProtocolRecovery,
                             :ProtocolRecoveryDispatch, :ProtocolRecoveryPosition

data/sig/auth_oauth.rbs

@@ -0,0 +1,16 @@
+module Volcano
+  type oauth_api_input = session_input
+
+  class Auth
+    def list_linked_oauth_providers: () -> Array[LinkedOAuthProvider]
+    def link_oauth_provider: (String provider) -> String
+    def unlink_oauth_provider: (String provider) -> nil
+    def get_oauth_provider_token: (String provider) -> OAuthProviderTokenStatus
+    def refresh_oauth_provider_token: (String provider) -> OAuthProviderTokenStatus
+    def call_oauth_api: (String provider, endpoint: String, ?method: String, ?body: oauth_api_input) -> Object?
+    def sign_in_with_oauth: (String provider, redirect_to: String, state: String) -> String
+    def exchange_oauth_code: (code: String, redirect_to: String, state: String, expected_state: String) -> Session
+    def get_hosted_auth_url: (project_id: String, state: String, ?action: String) -> String
+    def adopt_hosted_auth_session: (Session session, state: String, expected_state: String) -> Session
+  end
+end

data/sig/auth_profile.rbs

@@ -0,0 +1,10 @@
+module Volcano
+  class Auth
+    def user: () -> User
+    def get_user: () -> User
+    def update_user: (?password: String?, ?metadata: session_user_input?) -> User
+    def request_email_change: (new_email: String) -> EmailChangeResult
+    def cancel_email_change: () -> nil
+    def confirm_email_change: (token: String) -> User
+  end
+end

data/sig/auth_sessions.rbs

@@ -0,0 +1,7 @@
+module Volcano
+  class Auth
+    def list_sessions: (?page: Integer, ?limit: Integer) -> SessionPage
+    def delete_all_other_sessions: () -> nil
+    def delete_session: (String session_id) -> nil
+  end
+end

data/sig/auth_subscription.rbs

@@ -0,0 +1,6 @@
+module Volcano
+  class AuthSubscription
+    def initialize: () ?{ () -> void } -> void
+    def unsubscribe: () -> nil
+  end
+end

data/sig/session.rbs

@@ -1,7 +1,7 @@
 module Volcano
   type json_value = nil | bool | Integer | Float | String | Array[json_value] | Hash[String, json_value]
   type session_input = nil | bool | Integer | Float | String | Symbol | Time | Array[session_input] | Hash[String | Symbol, session_input]
-  type session_user_input = Hash[String, session_input] | Hash[Symbol, session_input] | Hash[String | Symbol, session_input]
+  type session_user_input = Hash[String, json_value] | Hash[String, session_input] | Hash[Symbol, session_input] | Hash[String | Symbol, session_input]
 
   class Session < Data
     attr_reader access_token: String

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: volcano-sdk
 version: !ruby/object:Gem::Version
-  version: 0.29.0
+  version: 0.30.0
 platform: ruby
 authors:
 - Kong
@@ -136,14 +136,17 @@ files:
 - lib/volcano/auth_email_change.rb
 - lib/volcano/auth_get_user.rb
 - lib/volcano/auth_hosted.rb
+- lib/volcano/auth_notification_dispatch.rb
 - lib/volcano/auth_oauth.rb
 - lib/volcano/auth_oauth_api.rb
 - lib/volcano/auth_oauth_sign_in.rb
 - lib/volcano/auth_oauth_token.rb
+- lib/volcano/auth_profile_fields.rb
 - lib/volcano/auth_refresh.rb
 - lib/volcano/auth_resend_confirmation.rb
 - lib/volcano/auth_reset_password.rb
 - lib/volcano/auth_reset_password_for_email.rb
+- lib/volcano/auth_session_binding.rb
 - lib/volcano/auth_sessions.rb
 - lib/volcano/auth_sign_out.rb
 - lib/volcano/auth_sign_up.rb
@@ -592,7 +595,9 @@ files:
 - lib/volcano/realtime/reconnect.rb
 - lib/volcano/redaction.rb
 - lib/volcano/session.rb
+- lib/volcano/session_credentials.rb
 - lib/volcano/session_operations.rb
+- lib/volcano/session_page_mapping.rb
 - lib/volcano/sign_up_result.rb
 - lib/volcano/storage.rb
 - lib/volcano/storage_models.rb
@@ -604,7 +609,11 @@ files:
 - lib/volcano/transport.rb
 - lib/volcano/user.rb
 - lib/volcano/version.rb
+- sig/auth_oauth.rbs
+- sig/auth_profile.rbs
 - sig/auth_session_records.rbs
+- sig/auth_sessions.rbs
+- sig/auth_subscription.rbs
 - sig/connection_string.rbs
 - sig/durable_records.rbs
 - sig/email_change_result.rbs