volcano-sdk 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b992adf24aad6b7edea16323e1f9b21c8db08cefe1380cffaf12c99ed436baf4
-  data.tar.gz: 3770340779a1a5cf0b985b6290a185223632f85863e56ab33c4f8f443ce02f0e
+  metadata.gz: 255837a17bdecec1c4973e91d21885299b563a70adced0adf20fbbeb5bd8020d
+  data.tar.gz: edc269875f2132e437787412be884aeb0149acb81fb48397b750271b970afaa6
 SHA512:
-  metadata.gz: 8bd2583130b36e6ede81cdb096cfe97cff10aa9aebe8fb086cff5dd1d13c8883f6bc196b9d528c4e437fb7533df568aab7fce759d0a79f134983b825b730f9d7
-  data.tar.gz: d5118276bfe5a10d157e637643827a07586cba53d632b5f966501f3ffa9bf5562c1d1a682d8286026f0109f77b19cf701cd3a536d0fc419badf7e34e8d9f3a89
+  metadata.gz: b5e51ede8b8946bb3aca753f0e0661d5e93c9ca6c3dccae7bd5dc78a34b64cf645138a2edd09f6c0c402a920505087410b12d14ce5485ae6ae46630295be21cf
+  data.tar.gz: 38ca82b2e5e0ca112e2be5d7de5ac4719686622524e162d3db6526d0dcd4462d640ca1df17012265aa87243122176ee5f06083f3b7a8ea4e1090e04569b13711

data/README.md

@@ -378,6 +378,17 @@ Success returns `nil`. The reset revokes the recovered account's existing
 sessions and does not sign it in. The client keeps any unrelated local session
 unchanged; sign in with the new password when the reset flow completes.
 
+### Start with a supplied access token
+
+Pass `access_token` to `Volcano::Client.new` to start without a refresh token or
+known user identity. Construction makes no request and leaves `refresh_token`,
+`user_id`, and `user` as `nil`. `auth.user` validates and caches the profile
+without changing credentials. Without a refresh token, `refresh_session` raises
+`Volcano::Error::AuthenticationError`. `sign_out` revokes the server session using
+the access token and clears local state. Supply `refresh_token` alongside
+`access_token` to enable refresh.
+See the [token bootstrap example](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/README.md#use-a-supplied-access-token).
+
 ### Adopt an existing session
 
 ```ruby
@@ -429,10 +440,11 @@ client.auth.sign_out
 raise "still signed in" if client.auth.current_session
 ```
 
-`sign_out` revokes the current refresh token and clears the captured in-memory
+`sign_out` uses the access-token session when available, even if a refresh token was supplied.
+It revokes the captured session and clears the captured in-memory
 session. It succeeds without a request when no session exists. If revocation
-fails, the SDK still clears that session and raises the typed error. A session
-established while sign-out is pending remains current.
+fails, the SDK still clears that session and raises the typed error. A concurrent
+refresh of the same session is cleared; a separate sign-in or adoption remains current.
 
 ### Invoke a function
 

data/lib/volcano/auth.rb

@@ -34,16 +34,6 @@ module Volcano
       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:)
@@ -66,22 +56,6 @@ module Volcano
       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'),

data/lib/volcano/auth_refresh.rb

@@ -78,6 +78,9 @@ module Volcano
     end
 
     def perform_refresh(binding, notifications)
+      raise Error::AuthenticationError, 'No refresh token' unless binding.last.refresh_token
+
+      SessionCredentials.validate_refresh_source(binding.last)
       session = refreshed_session(binding, notifications)
       stored = @client.store_session_if_current?(
         session, binding.first, event: :token_refreshed, notifications: notifications
@@ -86,7 +89,11 @@ module Volcano
     end
 
     def refreshed_session(binding, notifications)
-      owned_complete_session(build_session(refresh_payload(binding, notifications)))
+      parse_refresh_session(refresh_payload(binding, notifications))
+    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

data/lib/volcano/auth_sessions.rb

@@ -124,16 +124,7 @@ module Volcano
     end
 
     def access_token_session_id(access_token)
-      parts = access_token.split('.')
-      return unless parts.length == 3
-
-      encoded = parts.fetch(1).tr('-_', '+/')
-      padding = '=' * (-encoded.length % 4)
-      payload = JSON.parse((encoded + padding).unpack1('m0'))
-      session_id = payload['session_id']
-      session_id if session_id.is_a?(String) && !session_id.empty?
-    rescue ArgumentError, JSON::ParserError
-      nil
+      SessionCredentials.session_id(access_token)
     end
   end
 end

data/lib/volcano/auth_sign_out.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Revokes the captured server session and clears its local lineage.
+  class Auth
+    def sign_out
+      binding = @client.capture_session_binding
+      return unless binding.last
+
+      notifications = []
+      @refresh_lock.synchronize { sign_out_captured(binding, notifications) }
+    ensure
+      notifications&.each(&:call)
+    end
+
+    private
+
+    def sign_out_captured(binding, notifications)
+      generation, lineage, current = revocation_binding(binding)
+      error = revocation_error(current)
+      lineage = nil unless access_token_session_id(current.access_token)
+      cleared = @client.clear_session_if_current?(generation, lineage: lineage, notifications: notifications)
+      raise Error::SessionChangedError, cause: error unless cleared
+
+      raise error if error
+    end
+
+    def revocation_binding(binding)
+      active = @client.capture_session_binding
+      active.last && active[1] == binding[1] ? active : binding
+    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(session)
+      session_id = access_token_session_id(session.access_token)
+      return revoke_access_session(session, session_id) if session_id
+      return unless session.refresh_token
+
+      Transport.body(logout_response(session.refresh_token), 204)
+      nil
+    rescue Error::VolcanoError => e
+      e
+    end
+
+    def revoke_access_session(session, session_id)
+      error = delete_session_error(session.access_token, session_id)
+      return error unless error&.status == 401 && session.refresh_token
+
+      refreshed = parse_refresh_session(Transport.body(refresh_response(session.refresh_token), 200))
+      SessionCredentials.validate_refresh(session, refreshed)
+      delete_session_error(refreshed.access_token, session_id)
+    end
+  end
+end

data/lib/volcano/auth_state.rb

@@ -24,11 +24,11 @@ module Volcano
     CALLBACK_FAILURES = [Exception].freeze
     private_constant :CALLBACK_FAILURES
 
-    def initialize
+    def initialize(session: nil)
       @mutex = Mutex.new
       @generation = 0
       @lineage = 0
-      @session = nil
+      @session = session
       @callbacks = {}
       @next_callback_id = 0
       @notifications = []
@@ -48,9 +48,9 @@ module Volcano
       drain_notifications if dispatch
     end
 
-    def store_if_current?(session, generation, event: :signed_in, notifications: nil)
+    def store_if_current?(session, generation, event: :signed_in, notifications: nil, lineage: nil)
       dispatch = @mutex.synchronize do
-        return false unless generation == @generation
+        return false unless lineage.nil? ? generation == @generation : lineage == @lineage
 
         enqueue_notification(replace(session, event), event, session)
       end
@@ -63,9 +63,8 @@ module Volcano
     def update_user_if_current?(user, generation)
       @mutex.synchronize do
         return false unless generation == @generation && @session
-        raise Error::AuthenticationError, 'Profile belongs to a different user' unless user['id'] == @session.user_id
 
-        @session = Session.new(**@session.to_h, user: user)
+        @session = SessionCredentials.with_user(@session, user)
         true
       end
     end
@@ -82,6 +81,7 @@ module Volcano
     private
 
     def replace(session, event)
+      SessionCredentials.validate_refresh(@session, session) if event == :token_refreshed
       @session = session
       @generation += 1
       @lineage += 1 unless event == :token_refreshed

data/lib/volcano/client.rb

@@ -19,13 +19,14 @@ module Volcano
       api_url: 'https://api.volcano.dev',
       service_key: nil,
       timeout: 60,
-      **adapters
+      **options
     )
-      transport, socket_factory, reconnect_delay = extract_adapters(adapters)
+      session = SessionCredentials.build(options.delete(:access_token), options.delete(:refresh_token))
+      transport, socket_factory, reconnect_delay = extract_adapters(options)
       @api_url = api_url.delete_suffix('/')
       @anon_key = anon_key
       @service_key = service_key
-      @auth_state = AuthState.new
+      @auth_state = AuthState.new(session: session)
       @transport = transport || GeneratedTransport.new(api_url: @api_url, timeout: timeout)
       initialize_facades(socket_factory, reconnect_delay)
     end
@@ -81,8 +82,8 @@ module Volcano
       @auth_state.store_if_current?(session, generation, event: event, notifications: notifications)
     end
 
-    def clear_session_if_current?(generation, event: :signed_out, notifications: nil)
-      @auth_state.store_if_current?(nil, generation, event: event, notifications: notifications)
+    def clear_session_if_current?(generation, event: :signed_out, notifications: nil, lineage: nil)
+      @auth_state.store_if_current?(nil, generation, event: event, notifications: notifications, lineage: lineage)
     end
 
     def subscribe_auth_state_change(...)

data/lib/volcano/realtime/connection.rb

@@ -13,17 +13,18 @@ module Volcano
         session = session_for_lineage(session_lineage)
         protocol = build_protocol(socket)
         result = protocol.connect(token: session.access_token)
-        session = session_for_lineage(session_lineage)
-        activate_protocol(protocol, session, result)
+        session_for_lineage(session_lineage)
+        activate_protocol(protocol, session_lineage, result)
       rescue StandardError => e
         handle_connection_failure(socket, e)
       end
 
       def active_session_lineage
         _, lineage, session = @client.capture_session_binding
-        return lineage if session
+        raise Error::AuthenticationError, 'No active session' unless session
 
-        raise Error::AuthenticationError, 'No active session'
+        session_for_lineage(lineage)
+        lineage
       end
 
       def session_for_lineage(expected_lineage)
@@ -33,9 +34,9 @@ module Volcano
         raise Error::SessionChangedError
       end
 
-      def activate_protocol(protocol, session, result)
+      def activate_protocol(protocol, session_lineage, result)
         @protocol = protocol
-        @protocol_user_id = session.user_id
+        @protocol_session_lineage = session_lineage
         protocol_connected(result)
         protocol
       end
@@ -55,7 +56,7 @@ module Volcano
       ensure
         @manual_disconnect = false
         @channels.each_value(&:mark_closed)
-        @protocol_user_id = nil
+        @protocol_session_lineage = nil
       end
 
       def handle_connection_failure(socket, error)

data/lib/volcano/realtime/connection_callbacks.rb

@@ -117,7 +117,7 @@ module Volcano
       def reset_after_protocol_loss
         protocol = @protocol
         @protocol = nil
-        @protocol_user_id = nil
+        @protocol_session_lineage = nil
         @channels.each_value { |channel| channel.protocol_lost(protocol) } if protocol
       end
     end

data/lib/volcano/realtime/postgres_database.rb

@@ -30,15 +30,14 @@ module Volcano
 
       def capture_protocol_session
         generation, lineage, session = capture_session_binding
-        return [generation, lineage, session] if session && session.user_id == @protocol_user_id
+        return [generation, lineage, session] if session && lineage == @protocol_session_lineage
 
         raise Error::SessionChangedError
       end
 
       def access_token_for_protocol_lineage(expected_lineage)
         _, lineage, session = capture_session_binding
-        return session.access_token if session && lineage == expected_lineage &&
-                                       session.user_id == @protocol_user_id
+        return session.access_token if session && lineage == expected_lineage && lineage == @protocol_session_lineage
 
         raise Error::SessionChangedError
       end

data/lib/volcano/realtime.rb

@@ -73,7 +73,7 @@ module Volcano
       @channels = {}
       @connection_callbacks = { connect: {}, disconnect: {}, error: {} }
       @next_connection_callback_id = 0
-      @protocol_user_id = nil
+      @protocol_session_lineage = nil
       @reconnect_task = nil
       @closed = false
     end

data/lib/volcano/session.rb

@@ -9,9 +9,78 @@ module Volcano
   end
   private_constant :SESSION_USER_CODER
 
-  # In-memory credentials with an optional, unverified local user snapshot.
+  # 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)
+      return if current.user_id || session_id(current.access_token)
+
+      raise Error::AuthenticationError, 'Cannot refresh unknown identity without a session identifier'
+    end
+
+    def self.validate_refresh(current, refreshed)
+      return unless current
+
+      validate_refresh_source(current)
+      expected = session_id(current.access_token)
+      if expected && expected != session_id(refreshed&.access_token)
+        raise Error::AuthenticationError, 'Refreshed credentials belong to a different server session'
+      end
+      return unless current.user_id && current.user_id != refreshed&.user_id
+
+      raise Error::AuthenticationError, 'Refreshed session belongs to a different user'
+    end
+
+    # 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:, user_id:, user: nil)
+    def initialize(access_token:, refresh_token: nil, user_id: nil, user: nil)
       super(access_token:, refresh_token:, user_id:, user: immutable_user(user))
     end
 

data/lib/volcano/version.rb

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

data/lib/volcano.rb

@@ -13,6 +13,7 @@ require_relative 'volcano/redaction'
 require_relative 'volcano/transport'
 require_relative 'volcano/generated_transport'
 require_relative 'volcano/auth'
+require_relative 'volcano/auth_sign_out'
 require_relative 'volcano/auth_refresh'
 require_relative 'volcano/auth_sign_up'
 require_relative 'volcano/sign_up_result'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: volcano-sdk
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Kong
@@ -145,6 +145,7 @@ files:
 - lib/volcano/auth_reset_password.rb
 - lib/volcano/auth_reset_password_for_email.rb
 - lib/volcano/auth_sessions.rb
+- lib/volcano/auth_sign_out.rb
 - lib/volcano/auth_sign_up.rb
 - lib/volcano/auth_state.rb
 - lib/volcano/auth_update_user.rb