volcano-sdk 0.5.2

data/lib/volcano/auth.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+module Volcano
+  # Authenticates users and updates the client session.
+  class Auth
+    INCOMPLETE_SESSION = 'Expected a complete Volcano::Session'
+    private_constant :INCOMPLETE_SESSION
+
+    def initialize(client, transport, api_url:)
+      @client = client
+      @transport = transport
+      @api_url = api_url
+      @refresh_lock = Monitor.new
+    end
+
+    def current_session
+      @client.current_session
+    end
+
+    def current_session=(session)
+      @client.store_session(owned_complete_session(session), event: nil)
+    end
+
+    def on_auth_state_change(&callback)
+      raise ArgumentError, 'callback block required' unless callback
+
+      @client.subscribe_auth_state_change(&callback)
+    end
+
+    def sign_in(email:, password:)
+      generation, = @client.capture_session
+      sign_in_for_generation(email:, password:, generation:)
+    end
+
+    def sign_out
+      generation, current = @client.capture_session
+      return unless current
+
+      error = revocation_error(current.refresh_token)
+      raise Error::SessionChangedError, cause: error unless @client.clear_session_if_current?(generation)
+
+      raise error if error
+    end
+
+    private
+
+    def sign_in_for_generation(email:, password:, generation:)
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+
+      payload = Transport.body(sign_in_response(email:, password:), 200)
+      session = build_session(payload)
+      raise Error::SessionChangedError unless @client.store_session_if_current?(session, generation)
+
+      session
+    end
+
+    def sign_in_response(email:, password:)
+      Transport.invoke do
+        @transport.auth_signin(
+          authorization: @client.anon_token,
+          email: email,
+          password: password
+        )
+      end
+    end
+
+    def logout_response(refresh_token)
+      Transport.invoke do
+        @transport.auth_logout(
+          authorization: @client.anon_token,
+          refresh_token: refresh_token
+        )
+      end
+    end
+
+    def revocation_error(refresh_token)
+      Transport.body(logout_response(refresh_token), 204)
+      nil
+    rescue Error::VolcanoError => e
+      e
+    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')
+      )
+    end
+
+    def complete_session?(session)
+      return false unless session.is_a?(Session)
+
+      session.to_h.values.all? { |value| value.is_a?(String) && !value.strip.empty? }
+    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:)
+      Session.new(
+        access_token: access_token.dup.freeze,
+        refresh_token: refresh_token.dup.freeze,
+        user_id: user_id.dup.freeze
+      )
+    end
+  end
+end

data/lib/volcano/auth_anonymous.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Anonymous sign-in behavior for the authentication facade.
+  class Auth
+    def sign_in_anonymously(metadata: {})
+      generation, = @client.capture_session
+      payload = Transport.body(anonymous_signin_response(metadata), 201)
+      session = build_session(payload)
+      raise Error::SessionChangedError unless @client.store_session_if_current?(session, generation)
+
+      session
+    end
+
+    def convert_anonymous(email:, password:, metadata: {})
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      payload = Transport.body(
+        anonymous_conversion_response(current.access_token, email, password, metadata),
+        200
+      )
+      user = build_user(user_payload(payload))
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+
+      user
+    end
+
+    private
+
+    def anonymous_signin_response(metadata)
+      Transport.invoke do
+        @transport.auth_signup_anonymous(
+          authorization: @client.anon_token,
+          metadata: Hash(metadata)
+        )
+      end
+    end
+
+    def anonymous_conversion_response(access_token, email, password, metadata)
+      Transport.invoke do
+        @transport.auth_convert_anonymous(
+          authorization: access_token,
+          email: email,
+          password: password,
+          metadata: Hash(metadata)
+        )
+      end
+    end
+  end
+end

data/lib/volcano/auth_confirm_email.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Email-token confirmation behavior for the authentication facade.
+  class Auth
+    def confirm_email(token:)
+      Transport.body(confirm_email_response(token:), 200)
+      nil
+    end
+
+    private
+
+    def confirm_email_response(token:)
+      Transport.invoke do
+        @transport.auth_confirm_email(authorization: @client.anon_token, token:)
+      end
+    end
+  end
+end

data/lib/volcano/auth_email_change.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Email-change request behavior for the authentication facade.
+  class Auth
+    INVALID_EMAIL_CHANGE_RESULT = 'Expected a valid email-change acknowledgement'
+    private_constant :INVALID_EMAIL_CHANGE_RESULT
+
+    def request_email_change(new_email:)
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      payload = Transport.body(email_change_response(current.access_token, new_email), 200)
+      result = email_change_result(payload)
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+
+      result
+    end
+
+    def cancel_email_change
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      Transport.body(cancel_email_change_response(current.access_token), 200)
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+    end
+
+    def confirm_email_change(token:)
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      payload = Transport.body(confirm_email_change_response(current.access_token, token), 200)
+      user = build_user(user_payload(payload))
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+
+      user
+    end
+
+    private
+
+    def email_change_response(access_token, new_email)
+      Transport.invoke do
+        @transport.auth_request_email_change(authorization: access_token, new_email:)
+      end
+    end
+
+    def cancel_email_change_response(access_token)
+      Transport.invoke do
+        @transport.auth_cancel_email_change(authorization: access_token)
+      end
+    end
+
+    def confirm_email_change_response(access_token, token)
+      Transport.invoke do
+        @transport.auth_confirm_email_change(authorization: access_token, token:)
+      end
+    end
+
+    def email_change_result(payload)
+      raise TypeError, INVALID_EMAIL_CHANGE_RESULT unless payload.is_a?(Hash)
+
+      message = payload['message']
+      new_email = payload['new_email']
+      unless [message, new_email].all? { |value| value.nil? || value.is_a?(String) }
+        raise TypeError, INVALID_EMAIL_CHANGE_RESULT
+      end
+
+      EmailChangeResult.new(message: owned_string(message), new_email: owned_string(new_email))
+    end
+
+    def owned_string(value)
+      value&.dup&.freeze
+    end
+  end
+end

data/lib/volcano/auth_get_user.rb

@@ -0,0 +1,110 @@
+# 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
+
+    def user
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      payload = Transport.body(get_user_response(current.access_token), 200)
+      user = build_user(user_payload(payload))
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+
+      user
+    end
+
+    alias get_user user
+
+    private
+
+    def get_user_response(access_token)
+      Transport.invoke do
+        @transport.auth_get_user(authorization: access_token)
+      end
+    end
+
+    def build_user(payload)
+      raise Error::AuthenticationError, INVALID_USER unless valid_user?(payload)
+
+      User.new(**user_attributes(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_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'])
+    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
+    end
+
+    def parse_time(value)
+      Time.iso8601(value).freeze unless value.nil?
+    end
+
+    def complete_string?(value)
+      value.is_a?(String) && !value.strip.empty?
+    end
+  end
+end

data/lib/volcano/auth_hosted.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'uri'
+
+module Volcano
+  # Builds URLs for Volcano's managed hosted-auth pages.
+  class Auth
+    HOSTED_AUTH_ACTIONS = %w[login signup forgot-password].freeze
+    private_constant :HOSTED_AUTH_ACTIONS
+
+    def get_hosted_auth_url(project_id:, state:, action: 'login')
+      project = hosted_auth_parameter(project_id).strip
+      auth_state = hosted_auth_parameter(state)
+      raise ArgumentError, 'Unsupported hosted auth action' unless HOSTED_AUTH_ACTIONS.include?(action)
+
+      query = URI.encode_www_form(action:, anon_key: @client.anon_token, state: auth_state)
+      "#{@api_url}/projects/#{URI.encode_uri_component(project)}/auth/hosted?#{query}"
+    end
+
+    def adopt_hosted_auth_session(session, state:, expected_state:)
+      validate_hosted_auth_callback_state(state, expected_state)
+      adopted = owned_complete_session(session)
+      @client.store_session(adopted)
+      adopted
+    end
+
+    private
+
+    def validate_hosted_auth_callback_state(state, expected_state)
+      actual = hosted_auth_parameter(state)
+      expected = hosted_auth_parameter(expected_state)
+      valid = actual.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(actual, expected)
+      raise ArgumentError, 'Hosted auth state mismatch' unless valid
+    end
+
+    def hosted_auth_parameter(value)
+      return value if value.is_a?(String) && !value.strip.empty?
+
+      raise ArgumentError, 'Hosted auth parameters must be non-empty strings'
+    end
+  end
+end

data/lib/volcano/auth_oauth.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Linked OAuth-provider behavior for the authentication facade.
+  class Auth
+    OAUTH_PROVIDERS = %w[apple github google microsoft].freeze
+    private_constant :OAUTH_PROVIDERS
+
+    def list_linked_oauth_providers
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      body = Transport.body(list_oauth_providers_response(current.access_token), 200)
+      result = linked_oauth_providers(body)
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+
+      result
+    end
+
+    def link_oauth_provider(provider)
+      provider_name = oauth_provider_name(provider)
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      body = Transport.body(link_oauth_provider_response(current.access_token, provider_name), 200)
+      result = oauth_authorization_url(body)
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+
+      result
+    end
+
+    def unlink_oauth_provider(provider)
+      provider_name = oauth_provider_name(provider)
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      Transport.body(unlink_oauth_provider_response(current.access_token, provider_name), 204)
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+    end
+
+    private
+
+    def list_oauth_providers_response(access_token)
+      Transport.invoke do
+        @transport.auth_list_oauth_providers(authorization: access_token)
+      end
+    end
+
+    def link_oauth_provider_response(access_token, provider)
+      Transport.invoke do
+        @transport.auth_link_oauth_provider(authorization: access_token, provider: provider)
+      end
+    end
+
+    def unlink_oauth_provider_response(access_token, provider)
+      Transport.invoke do
+        @transport.auth_unlink_oauth_provider(authorization: access_token, provider: provider)
+      end
+    end
+
+    def oauth_provider_name(provider)
+      return provider if provider.is_a?(String) && OAUTH_PROVIDERS.include?(provider)
+
+      raise ArgumentError, 'Unsupported OAuth provider'
+    end
+
+    def oauth_authorization_url(body)
+      authorization_url = body.fetch('authorization_url') if body.is_a?(Hash)
+      return authorization_url if authorization_url.is_a?(String) && !authorization_url.strip.empty?
+
+      raise TypeError, 'Expected an OAuth authorization URL'
+    rescue KeyError
+      raise TypeError, 'Expected an OAuth authorization URL'
+    end
+
+    def linked_oauth_providers(body)
+      raise TypeError, 'Expected complete linked OAuth providers' unless body.is_a?(Hash)
+
+      providers = body.fetch('providers')
+      raise TypeError, 'Expected complete linked OAuth providers' unless providers.is_a?(Array)
+
+      providers.map { |attributes| linked_oauth_provider(attributes) }.freeze
+    rescue KeyError
+      raise TypeError, 'Expected complete linked OAuth providers'
+    end
+
+    def linked_oauth_provider(attributes)
+      raise TypeError, 'Expected complete linked OAuth providers' unless attributes.is_a?(Hash)
+
+      provider = attributes.fetch('provider')
+      linked_at = attributes.fetch('linked_at')
+      updated_at = attributes.fetch('updated_at')
+      valid = provider.is_a?(String) && !provider.strip.empty? &&
+              linked_at.is_a?(Time) && updated_at.is_a?(Time)
+      raise TypeError, 'Expected complete linked OAuth providers' unless valid
+
+      LinkedOAuthProvider.new(provider:, linked_at:, updated_at:)
+    rescue KeyError
+      raise TypeError, 'Expected complete linked OAuth providers'
+    end
+  end
+end

data/lib/volcano/auth_oauth_api.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Fixed-host OAuth-provider API proxy behavior for the auth facade.
+  class Auth
+    def call_oauth_api(provider, endpoint:, method: 'GET', body: nil)
+      provider_name = oauth_provider_name(provider)
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      response = oauth_api_response(
+        current.access_token, provider_name, endpoint: endpoint, method: method, body: body
+      )
+      result = oauth_api_data(Transport.body(response, 200))
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+
+      result
+    end
+
+    private
+
+    def oauth_api_response(access_token, provider, endpoint:, method:, body:)
+      Transport.invoke do
+        @transport.auth_call_oauth_api(
+          authorization: access_token, provider: provider, endpoint: endpoint,
+          method: method, body: body
+        )
+      end
+    end
+
+    def oauth_api_data(response_body)
+      data = response_body.fetch('data')
+      freeze_oauth_api_data(data)
+    rescue KeyError, NoMethodError
+      raise TypeError, 'Expected OAuth provider API response data'
+    end
+
+    def freeze_oauth_api_data(value)
+      case value
+      when Hash
+        value.to_h { |key, item| [freeze_oauth_api_data(key), freeze_oauth_api_data(item)] }.freeze
+      when Array
+        value.map { |item| freeze_oauth_api_data(item) }.freeze
+      when String
+        value.dup.freeze
+      else
+        value.frozen? ? value : value.dup.freeze
+      end
+    end
+  end
+end

data/lib/volcano/auth_oauth_sign_in.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Volcano
+  # OAuth sign-in initiation and callback exchange behavior.
+  class Auth
+    MAX_OAUTH_STATE_LENGTH = 255
+    private_constant :MAX_OAUTH_STATE_LENGTH
+
+    def sign_in_with_oauth(provider, redirect_to:, state:)
+      @transport.auth_oauth_authorization_url(
+        anon_key: @client.anon_token,
+        provider: oauth_provider_name(provider),
+        redirect_url: oauth_parameter(redirect_to),
+        client_state: oauth_state(state)
+      )
+    end
+
+    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))
+      raise Error::SessionChangedError unless @client.store_session_if_current?(session, generation)
+
+      session
+    end
+
+    private
+
+    def oauth_exchange_response(code, redirect_to)
+      Transport.invoke do
+        @transport.auth_oauth_exchange(
+          authorization: @client.anon_token,
+          code: oauth_parameter(code),
+          redirect_url: oauth_parameter(redirect_to)
+        )
+      end
+    end
+
+    def oauth_parameter(value)
+      return value if value.is_a?(String) && !value.strip.empty?
+
+      raise ArgumentError, 'OAuth parameters must be non-empty strings'
+    end
+
+    def oauth_state(value)
+      state = oauth_parameter(value)
+      raise ArgumentError, 'OAuth state must not exceed 255 characters' if state.length > MAX_OAUTH_STATE_LENGTH
+
+      state
+    end
+
+    def validate_oauth_callback_state(state, expected_state)
+      actual = oauth_state(state)
+      expected = oauth_state(expected_state)
+      valid = actual.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(actual, expected)
+      raise ArgumentError, 'OAuth state mismatch' unless valid
+    end
+  end
+end

data/lib/volcano/auth_oauth_token.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Server-held OAuth-provider token metadata behavior for the auth facade.
+  class Auth
+    def get_oauth_provider_token(provider)
+      provider_name = oauth_provider_name(provider)
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      body = Transport.body(oauth_provider_token_response(current.access_token, provider_name), 200)
+      result = oauth_provider_token_status(body)
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+
+      result
+    end
+
+    def refresh_oauth_provider_token(provider)
+      provider_name = oauth_provider_name(provider)
+      generation, current = @client.capture_session
+      raise Error::AuthenticationError, 'No active session' unless current
+
+      body = Transport.body(refresh_oauth_provider_token_response(current.access_token, provider_name), 200)
+      result = oauth_provider_token_status(body)
+      raise Error::SessionChangedError unless @client.capture_session.first == generation
+
+      result
+    end
+
+    private
+
+    def oauth_provider_token_response(access_token, provider)
+      Transport.invoke do
+        @transport.auth_get_oauth_provider_token(authorization: access_token, provider: provider)
+      end
+    end
+
+    def refresh_oauth_provider_token_response(access_token, provider)
+      Transport.invoke do
+        @transport.auth_refresh_oauth_provider_token(authorization: access_token, provider: provider)
+      end
+    end
+
+    def oauth_provider_token_status(body)
+      message, provider, expires_in = body.fetch_values('message', 'provider', 'expires_in')
+      OAuthProviderTokenStatus.new(message:, provider:, expires_in:)
+    rescue KeyError, NoMethodError
+      raise TypeError, 'Expected complete OAuth provider token status'
+    end
+  end
+end