volcano-sdk 0.29.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e946d4476603cf2c234194f51e63aadd8ca1327719bcae02bf098de61049b65b
-  data.tar.gz: 38d3aa7dbbc508796620f75285b2a483b70a9e2d49a255aded0dba3fa023334b
+  metadata.gz: 36cf6c142c98f421f086d919b4d5e83034e95831d2b4246a892be57ebfaea9d5
+  data.tar.gz: 877909af108367683c4cbb434235baa27669af9d303dd0b52307919446f8c348
 SHA512:
-  metadata.gz: 014b16629b5d06e89d39f010b1c8cb550582f3f7f224b6c6911324c6b2b07196eed9729305c2edd623d6fbedb2ba12a9460d4d128bda61202c9c88874823fada
-  data.tar.gz: d98691e237fd5cdb277f701701e3549aa6e533179d36c0039e188a66143fe5992a1ac9565f210304704838d2e855a9512e9e2e60de7ec0b2abfa9a8a30ae4cb2
+  metadata.gz: 832893a1b1ba6caa88f144b81d8b8e155d2041be82fccffe4328eeb1f59f4fc8e3ce84adbb476f3b1a6b26ed719da7293f9dfb6a563270cdcb5222125661f378
+  data.tar.gz: acfb489b98c3e8dcca7918ee1136d4e04f62fec2a7287fcc16fcd952edd3bfae2d4973b6307ef53d577a08cb4104511666917e4435c3d7722bb3cde544d7ad3d

data/lib/volcano/auth.rb

@@ -3,8 +3,13 @@
 module Volcano
   # Authenticates users and updates the client session.
   class Auth
-    INCOMPLETE_SESSION = 'Expected a complete Volcano::Session'
-    private_constant :INCOMPLETE_SESSION
+    include AuthRefresh
+    include AuthSignOut
+    include AuthProfile
+    include AuthUpdateUser
+    include AuthEmailChange
+    include AuthSessions
+    include AuthSessionConstruction
 
     def initialize(client, transport, api_url:)
       @client = client
@@ -20,10 +25,10 @@ module Volcano
       @client.store_session(owned_complete_session(session), event: nil)
     end
 
-    def on_auth_state_change(&callback)
-      raise ArgumentError, 'callback block required' unless callback
+    def on_auth_state_change(&)
+      raise ArgumentError, 'callback block required' unless block_given?
 
-      @client.subscribe_auth_state_change(&callback)
+      @client.subscribe_auth_state_change(&)
     end
 
     def sign_in(email:, password:)
@@ -70,47 +75,5 @@ module Volcano
         )
       end
     end
-
-    def build_session(payload)
-      owned_session(
-        access_token: payload.fetch('access_token'),
-        refresh_token: payload.fetch('refresh_token'),
-        user_id: payload.fetch('user').fetch('id'),
-        user: payload.fetch('user')
-      )
-    end
-
-    def parse_refresh_session(payload)
-      owned_complete_session(build_session(payload))
-    rescue KeyError, TypeError, NoMethodError, ArgumentError => e
-      raise Error::TransportError, INCOMPLETE_SESSION, cause: e
-    end
-
-    def complete_session?(session)
-      return false unless session.is_a?(Session)
-
-      values = [session.access_token, session.refresh_token, session.user_id]
-      values.all? { |value| value.is_a?(String) && !value.strip.empty? } &&
-        matching_session_user?(session)
-    end
-
-    def matching_session_user?(session)
-      session.user.nil? || (session.user.is_a?(Hash) && session.user['id'] == session.user_id)
-    end
-
-    def owned_complete_session(session)
-      raise ArgumentError, INCOMPLETE_SESSION unless complete_session?(session)
-
-      owned_session(**session.to_h)
-    end
-
-    def owned_session(access_token:, refresh_token:, user_id:, user: nil)
-      Session.new(
-        access_token: access_token.dup.freeze,
-        refresh_token: refresh_token.dup.freeze,
-        user_id: user_id.dup.freeze,
-        user: user
-      )
-    end
   end
 end

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_session_construction.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Builds and validates owned credential snapshots for the auth facade.
+  module AuthSessionConstruction
+    INCOMPLETE_SESSION = 'Expected a complete Volcano::Session'
+    private_constant :INCOMPLETE_SESSION
+
+    private
+
+    def build_session(payload)
+      raise TypeError, INCOMPLETE_SESSION unless payload.is_a?(Hash)
+
+      user = payload.fetch('user')
+      raise TypeError, INCOMPLETE_SESSION unless user.is_a?(Hash)
+
+      owned_session(
+        access_token: required_session_string(payload.fetch('access_token')),
+        refresh_token: required_session_string(payload.fetch('refresh_token')),
+        user_id: required_session_string(user.fetch('id')),
+        user: user
+      )
+    end
+
+    def parse_refresh_session(payload)
+      owned_complete_session(build_session(payload))
+    rescue KeyError, TypeError, NoMethodError, ArgumentError => e
+      raise Error::TransportError, INCOMPLETE_SESSION, cause: e
+    end
+
+    def complete_session?(session)
+      values = [session.access_token, session.refresh_token, session.user_id]
+      values.all? { |value| value.is_a?(String) && !value.strip.empty? } &&
+        matching_session_user?(session)
+    end
+
+    def matching_session_user?(session)
+      session.user.nil? || (session.user.is_a?(Hash) && session.user['id'] == session.user_id)
+    end
+
+    def owned_complete_session(session)
+      raise ArgumentError, INCOMPLETE_SESSION unless session.is_a?(Session) && complete_session?(session)
+
+      owned_session(
+        access_token: required_session_string(session.access_token),
+        refresh_token: required_session_string(session.refresh_token),
+        user_id: required_session_string(session.user_id),
+        user: session.user
+      )
+    end
+
+    def required_session_string(value)
+      return value if value.is_a?(String) && !value.strip.empty?
+
+      raise ArgumentError, INCOMPLETE_SESSION
+    end
+
+    def owned_session(access_token:, refresh_token:, user_id:, user: nil)
+      Session.new(
+        access_token: access_token.dup.freeze,
+        refresh_token: refresh_token.dup.freeze,
+        user_id: user_id.dup.freeze,
+        user: user
+      )
+    end
+  end
+end