clowk 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3298d33abdf85d08387832031c8bbdb6efa36785b73c59ece84a3dec4deb064
-  data.tar.gz: b533eb6930465ea11188d0f2f8e23758575f113972d9aea81d5bdcb87a21af32
+  metadata.gz: 23e593a98742fb2d99e89bcec77d30c250300f1ce40789ebadd82277548419d8
+  data.tar.gz: 0acb397f16bca42b0599cf2ab1e8c223010ea2ae1bb7f7031700e2cdb568f293
 SHA512:
-  metadata.gz: 486ff44e3a9e781cad6c87584d40079ca43724c113432a76513078525b8df9a8d64a82c593a4be9bb7db87dc9c3bce7a6ec611c14fbefe2d7074904d8901b758
-  data.tar.gz: e06afce3a59cbb24d8c388837b51582c30d2597dec2e9e08337343040ca9cbe1041b2442c573436faa2c958adf3bd6b15ac3170d82447189ae235386a16a5fd6
+  metadata.gz: 4b9cccf22eb2a0760dc0b949ac2021d6f509456424be2d93286af8fe47727a5853eee1dc06a8d5b934725288bc682ff34b74fe85e15c547877f9a78705d520f5
+  data.tar.gz: 515c0d900a8afada712f6aa2252fba6415afe3975db242c053131ae2749a127575adba4c801ca9d44ff27161cc4de660ec15fab89eba350cb61844efe55d54fa

data/README.md

@@ -86,7 +86,7 @@ Clowk.configure do |config|
   config.after_sign_in_path = '/'
   config.after_sign_out_path = '/'
 
-  config.api_base_url = 'https://api.clowk.dev/client/v1'
+  config.api_base_url = 'https://api.clowk.dev/api/v1'
   config.callback_path = '/clowk/oauth/callback'
   config.mount_path = '/clowk'
 
@@ -362,4 +362,4 @@ Its job is to make the Rails side of Clowk integration predictable:
 
 ## License
 
-MIT. See `LICENSE`.
+AGPL-3.0. See `LICENSE`.

data/clowk.gemspec

@@ -1,31 +1,32 @@
 # frozen_string_literal: true
 
-require_relative 'lib/clowk/version'
+require_relative "lib/clowk/version"
 
 Gem::Specification.new do |spec|
-  spec.name = 'clowk'
+  spec.name = "clowk"
   spec.version = Clowk::VERSION
-  spec.authors = ['Clowk']
-  spec.email = ['support@clowk.in']
+  spec.authors = ["Clowk"]
+  spec.email = ["support@clowk.in"]
 
-  spec.summary = 'Rails SDK for Clowk authentication'
-  spec.description = 'Clowk Authentication, JWT verification, and future API access'
-  spec.homepage = 'https://clowk.in'
-  spec.license = 'AGPL-3.0'
-  spec.required_ruby_version = '>= 3.3'
+  spec.summary = "Rails SDK for Clowk authentication"
+  spec.description = "Clowk Authentication, JWT verification, and future API access"
+  spec.homepage = "https://clowk.in"
+  spec.license = "AGPL-3.0-only"
+  spec.required_ruby_version = ">= 3.3"
   spec.metadata = {
-    'rubygems_mfa_required' => 'true'
+    "rubygems_mfa_required" => "true"
   }
 
   spec.files = Dir.chdir(__dir__) do
-    Dir['README.md', 'clowk.gemspec', 'config/routes.rb', 'lib/**/*.rb']
+    Dir["README.md", "clowk.gemspec", "config/routes.rb", "lib/**/*.rb"]
   end
 
-  spec.require_paths = ['lib']
+  spec.require_paths = ["lib"]
 
-  spec.add_dependency 'activesupport', '>= 7.0'
-  spec.add_dependency 'jwt', '>= 2.7', '< 3.0'
-  spec.add_dependency 'railties', '>= 7.0'
+  spec.add_dependency "activesupport", ">= 7.0"
+  spec.add_dependency "jwt", ">= 2.7", "< 3.0"
+  spec.add_dependency "railties", ">= 7.0"
 
-  spec.add_development_dependency 'rspec', '>= 3.13', '< 4.0'
+  spec.add_development_dependency "rspec", ">= 3.13", "< 4.0"
+  spec.add_development_dependency "standard", ">= 1.0"
 end

data/config/routes.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 Clowk::Engine.routes.draw do
-  get '/sign_in', to: 'sessions#new', as: :sign_in
-  get '/sign_up', to: 'sessions#sign_up', as: :sign_up
-  match '/sign_out', to: 'sessions#destroy', via: %i(get delete), as: :sign_out
-  get '/oauth/callback', to: 'callbacks#show', as: :auth_callback
+  get "/sign_in", to: "sessions#new", as: :sign_in
+  get "/sign_up", to: "sessions#sign_up", as: :sign_up
+  match "/sign_out", to: "sessions#destroy", via: %i[get delete], as: :sign_out
+  get "/oauth/callback", to: "callbacks#show", as: :auth_callback
 end

data/lib/clowk/authenticable.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'active_support/concern'
+require "active_support/concern"
 
 module Clowk
   module Authenticable
@@ -13,22 +13,37 @@ module Clowk
       signed_in_method = :"#{scope}_signed_in?"
 
       enforce_session_method = :"#{scope}_enforce_session!"
+      sign_out_method = :"#{scope}_sign_out!"
 
       base.class_eval do
-        define_method(current_method) do
-          clowk_current_resource
+        unless current_method == :clowk_current_resource
+          define_method(current_method) do
+            clowk_current_resource
+          end
         end
 
-        define_method(authenticate_method) do
-          clowk_authenticate!
+        unless authenticate_method == :clowk_authenticate!
+          define_method(authenticate_method) do
+            clowk_authenticate!
+          end
         end
 
-        define_method(signed_in_method) do
-          clowk_current_resource.present?
+        unless signed_in_method == :clowk_signed_in?
+          define_method(signed_in_method) do
+            clowk_signed_in?
+          end
         end
 
-        define_method(enforce_session_method) do
-          clowk_enforce_session!
+        unless enforce_session_method == :clowk_enforce_session!
+          define_method(enforce_session_method) do
+            clowk_enforce_session!
+          end
+        end
+
+        unless sign_out_method == :clowk_sign_out!
+          define_method(sign_out_method) do
+            clowk_sign_out!
+          end
         end
 
         helper_method current_method, authenticate_method, signed_in_method, :current_token if respond_to?(:helper_method)
@@ -47,7 +62,7 @@ module Clowk
     end
 
     def current_token
-      stored_session&.dig('token') || extracted_token
+      stored_session&.dig("token") || extracted_token
     end
 
     def clowk_signed_in?
@@ -59,7 +74,7 @@ module Clowk
     end
 
     def clowk_session_active?
-      clowk_session_status&.dig(:status) == 'active'
+      clowk_session_status&.dig(:status) == "active"
     end
 
     def clowk_enforce_session!
@@ -74,21 +89,21 @@ module Clowk
         return
       end
 
-      if request.format.json?
-        render json: { error: 'Session expired or inactive' }, status: :unauthorized
-      else
-        redirect_to clowk_sign_in_path(return_to: request.fullpath)
-      end
+      clowk_handle_expired_session(session_info)
     end
 
     def clowk_authenticate!
-      return clowk_current_resource if clowk_signed_in?
-
-      if request.format.json?
-        render json: { error: 'Unauthorized' }, status: :unauthorized
-      else
-        redirect_to clowk_sign_in_path(return_to: request.fullpath)
+      return clowk_handle_unauthenticated unless clowk_signed_in?
+
+      # A valid token proves who signed in, not that the session still stands —
+      # revocation lives server-side. Opt in with config.enforce_active_session
+      # to pay a lookup (cached for session_status_ttl) on every authentication.
+      if Clowk.config.enforce_active_session
+        clowk_enforce_session!
+        return if respond_to?(:performed?) && performed?
       end
+
+      clowk_current_resource
     end
 
     def clowk_sign_out!
@@ -100,6 +115,22 @@ module Clowk
 
     private
 
+    def clowk_handle_unauthenticated
+      if request.format.json?
+        render json: {error: "Unauthorized"}, status: :unauthorized
+      else
+        redirect_to clowk_sign_in_path(return_to: request.fullpath)
+      end
+    end
+
+    def clowk_handle_expired_session(_session_info)
+      if request.format.json?
+        render json: {error: "Session expired or inactive"}, status: :unauthorized
+      else
+        redirect_to clowk_sign_in_path(return_to: request.fullpath)
+      end
+    end
+
     def verified_request_payload
       return unless extracted_token
 
@@ -111,8 +142,13 @@ module Clowk
       nil
     end
 
+    # Bearer header or cookie only — never the query string. A valid token in a
+    # URL would otherwise sign the visitor in on ANY path, bypassing the state
+    # check that makes the OAuth callback safe, and would stay replayable for the
+    # token's full lifetime anywhere the URL was logged. CallbacksController
+    # reads params directly, after validating state.
     def extracted_token
-      @extracted_token ||= Clowk::Middleware::TokenExtractor.new(request).call
+      @extracted_token ||= Clowk::Middleware::TokenExtractor.new(request, token_param: nil).call
     end
 
     def stored_session
@@ -123,7 +159,7 @@ module Clowk
     end
 
     def stored_user_payload
-      payload = stored_session&.dig('user') || stored_session&.dig(:user)
+      payload = stored_session&.dig("user") || stored_session&.dig(:user)
       payload&.deep_symbolize_keys
     end
 
@@ -143,9 +179,9 @@ module Clowk
     end
 
     def resolve_session_status
-      cached = stored_session&.dig('session_status') || stored_session&.dig(:session_status)
+      cached = stored_session&.dig("session_status") || stored_session&.dig(:session_status)
 
-      return cached&.deep_symbolize_keys if cached
+      return cached&.deep_symbolize_keys if cached && clowk_session_status_fresh?
 
       resource = clowk_current_resource
 
@@ -156,9 +192,29 @@ module Clowk
       result = client.tokens.verify_with_session(token: current_token)
       status = result&.dig(:session)
 
-      session[Clowk.config.session_key] = stored_session.merge('session_status' => status) if status && stored_session
+      if status && stored_session
+        session[Clowk.config.session_key] = stored_session.merge(
+          "session_status" => status,
+          "session_status_checked_at" => Time.now.to_i
+        )
+      end
 
       status
+    rescue Clowk::InvalidTokenError
+      nil
+    end
+
+    # Whether the cached status may still be trusted. Timestamped alongside the
+    # payload rather than inside it, so what we hand back stays exactly what the
+    # API returned.
+    def clowk_session_status_fresh?
+      ttl = Clowk.config.session_status_ttl.to_i
+      return false unless ttl.positive?
+
+      checked_at = (stored_session&.dig("session_status_checked_at") ||
+                    stored_session&.dig(:session_status_checked_at)).to_i
+
+      checked_at.positive? && (Time.now.to_i - checked_at) < ttl
     end
   end
 end

data/lib/clowk/configuration.rb

@@ -2,9 +2,8 @@
 
 module Clowk
   class Configuration
+    attr_accessor :api_base_url
     attr_accessor :app_base_url
-    attr_accessor :after_sign_in_path
-    attr_accessor :after_sign_out_path
     attr_accessor :callback_path
     attr_accessor :cookie_key
     attr_accessor :http_logger
@@ -23,26 +22,65 @@ module Clowk
     attr_accessor :token_param
     attr_accessor :enforce_active_session
     attr_accessor :on_session_expired
+    attr_accessor :session_status_ttl
 
     def initialize
-      @app_base_url = 'https://app.clowk.in'
-      @after_sign_in_path = '/'
-      @after_sign_out_path = '/'
-      @mount_path = '/clowk'
-      @callback_path = '/clowk/oauth/callback'
-      @cookie_key = 'clowk_token'
+      @api_base_url = "https://api.clowk.dev/api/v1"
+      @app_base_url = "https://app.clowk.in"
+      @after_sign_in_path = "/"
+      @after_sign_out_path = "/"
+      @mount_path = "/clowk"
+      @callback_path = "/clowk/oauth/callback"
+      @cookie_key = "clowk_token"
       @http_logger = nil
       @http_open_timeout = 5
       @http_read_timeout = 10
       @http_retry_attempts = 2
       @http_retry_interval = 0.05
       @http_write_timeout = 10
-      @issuer = 'clowk'
+      @issuer = "clowk"
       @session_key = :clowk
       @prefix_by = :clowk
       @token_param = :token
       @enforce_active_session = false
       @on_session_expired = nil
+      # How long a fetched session status stays trusted, in seconds. Without a
+      # TTL the first lookup would be cached for the life of the Rails session,
+      # which silently turns every later enforcement call into a no-op. Set 0 to
+      # check on every call.
+      @session_status_ttl = 300
+    end
+
+    def after_sign_in_path
+      resolve_path(@after_sign_in_path)
+    end
+
+    def after_sign_out_path
+      resolve_path(@after_sign_out_path)
+    end
+
+    attr_writer :after_sign_in_path
+
+    attr_writer :after_sign_out_path
+
+    def validate!
+      errors = []
+      errors << "secret_key must be a String" unless @secret_key.is_a?(String) || @secret_key.nil?
+      errors << "http_open_timeout must be Numeric" unless @http_open_timeout.is_a?(Numeric)
+      errors << "http_read_timeout must be Numeric" unless @http_read_timeout.is_a?(Numeric)
+      errors << "http_write_timeout must be Numeric" unless @http_write_timeout.is_a?(Numeric)
+      errors << "http_retry_attempts must be a non-negative Integer" unless @http_retry_attempts.is_a?(Integer) && @http_retry_attempts >= 0
+      errors << "session_status_ttl must be a non-negative Integer" unless @session_status_ttl.is_a?(Integer) && @session_status_ttl >= 0
+
+      raise ConfigurationError, errors.join(", ") if errors.any?
+
+      true
+    end
+
+    private
+
+    def resolve_path(path_or_callable)
+      path_or_callable.respond_to?(:call) ? path_or_callable.call : path_or_callable
     end
   end
 end

data/lib/clowk/controllers/base_controller.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'securerandom'
-require 'uri'
+require "securerandom"
+require "uri"
 
 module Clowk
   class BaseController < ActionController::Base
@@ -13,18 +13,18 @@ module Clowk
     private
 
     def redirect_back_or(default, return_to: params[:return_to])
-      redirect_target = safe_redirect_path(return_to) || safe_redirect_path(default) || '/'
+      redirect_target = safe_redirect_path(return_to) || safe_redirect_path(default) || "/"
 
       redirect_to redirect_target
     end
 
     def start_clowk_auth_flow!(return_to: nil)
-      sanitized_return_to = safe_redirect_path(return_to) || safe_redirect_path(Clowk.config.after_sign_in_path) || '/'
+      sanitized_return_to = safe_redirect_path(return_to) || safe_redirect_path(Clowk.config.after_sign_in_path) || "/"
       state = SecureRandom.hex(32)
 
       session[:clowk_auth_flow] = {
-        'state' => state,
-        'return_to' => sanitized_return_to
+        "state" => state,
+        "return_to" => sanitized_return_to
       }
 
       state
@@ -38,9 +38,9 @@ module Clowk
     end
 
     def validate_clowk_state!(expected_state, actual_state)
-      raise Clowk::InvalidStateError, 'missing state' if actual_state.blank?
-      raise Clowk::InvalidStateError, 'missing state' if expected_state.blank?
-      raise Clowk::InvalidStateError, 'invalid state' unless state_matches?(expected_state, actual_state)
+      raise Clowk::InvalidStateError, "missing state" if actual_state.blank?
+      raise Clowk::InvalidStateError, "missing state" if expected_state.blank?
+      raise Clowk::InvalidStateError, "invalid state" unless state_matches?(expected_state, actual_state)
     end
 
     def state_matches?(expected_state, actual_state)
@@ -53,7 +53,7 @@ module Clowk
       value = candidate.to_s
       return if value.empty?
 
-      return value if value.start_with?('/') && !value.start_with?('//')
+      return value if value.start_with?("/") && !value.start_with?("//")
 
       uri = URI.parse(value)
       return unless uri.host == request.host && uri.scheme == request.scheme

data/lib/clowk/controllers/callbacks_controller.rb

@@ -4,20 +4,21 @@ module Clowk
   class CallbacksController < BaseController
     def show
       flow = consume_clowk_auth_flow!
-      validate_clowk_state!(flow['state'], params[:state])
+      validate_clowk_state!(flow["state"], params[:state])
 
       token = params[Clowk.config.token_param]
-      raise Clowk::InvalidTokenError, 'missing token' if token.blank?
+      raise Clowk::InvalidTokenError, "missing token" if token.blank?
 
       payload = Clowk::JwtVerifier.new.verify(token)
-      return_to = flow['return_to']
+      return_to = flow["return_to"]
 
       reset_clowk_session!
       persist_clowk_session(token, payload)
 
       redirect_back_or(Clowk.config.after_sign_in_path, return_to:)
     rescue Clowk::InvalidTokenError, Clowk::InvalidStateError => e
-      flash[:alert] = "Clowk authentication failed: #{e.message}"
+      Rails.logger.error("[Clowk] Authentication failed: #{e.class} - #{e.message}")
+      flash[:alert] = "Authentication failed. Please try again."
 
       redirect_back_or(Clowk.config.after_sign_out_path, return_to: nil)
     end

data/lib/clowk/current.rb

@@ -47,5 +47,19 @@ module Clowk
     def to_h
       attributes.merge(id: id)
     end
+
+    def ==(other)
+      return false unless other.is_a?(Current)
+
+      to_h == other.to_h
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def hash
+      to_h.hash
+    end
   end
-end
+end

data/lib/clowk/engine.rb

@@ -4,7 +4,7 @@ module Clowk
   class Engine < ::Rails::Engine
     isolate_namespace Clowk
 
-    initializer 'clowk.helpers' do
+    initializer "clowk.helpers" do
       ActiveSupport.on_load(:action_controller_base) do
         include Clowk::Helpers::UrlHelpers
       end

data/lib/clowk/helpers/url_helpers.rb

@@ -1,20 +1,18 @@
 # frozen_string_literal: true
 
-require 'cgi'
-
 module Clowk
   module Helpers
     module UrlHelpers
       def clowk_sign_in_path(return_to: nil)
-        append_query(clowk_local_path('/sign_in'), return_to:)
+        append_query(clowk_local_path("/sign_in"), return_to:)
       end
 
       def clowk_sign_up_path(return_to: nil)
-        append_query(clowk_local_path('/sign_up'), return_to:)
+        append_query(clowk_local_path("/sign_up"), return_to:)
       end
 
       def clowk_sign_out_path(return_to: nil)
-        append_query(clowk_local_path('/sign_out'), return_to:)
+        append_query(clowk_local_path("/sign_out"), return_to:)
       end
 
       def clowk_callback_url(return_to: nil, state: nil)
@@ -22,18 +20,18 @@ module Clowk
       end
 
       def clowk_sign_in_url(redirect_to: nil, return_to: nil, state: nil)
-        clowk_remote_auth_url('sign-in', redirect_to:, return_to:, state:)
+        clowk_remote_auth_url("sign-in", redirect_to:, return_to:, state:)
       end
 
       def clowk_sign_up_url(redirect_to: nil, return_to: nil, state: nil)
-        clowk_remote_auth_url('sign-up', redirect_to:, return_to:, state:)
+        clowk_remote_auth_url("sign-up", redirect_to:, return_to:, state:)
       end
 
       private
 
       def clowk_remote_auth_url(action, redirect_to:, return_to:, state:)
         callback_url = clowk_callback_url(return_to: redirect_to || return_to, state:)
-        query = { redirect_uri: callback_url }
+        query = {redirect_uri: callback_url}
 
         append_query("#{clowk_instance_base_url}/#{action}", query)
       end
@@ -50,7 +48,7 @@ module Clowk
         filtered = params.compact.reject { |_key, value| value.respond_to?(:empty?) && value.empty? }
         return url if filtered.empty?
 
-        separator = url.include?('?') ? '&' : '?'
+        separator = url.include?("?") ? "&" : "?"
         "#{url}#{separator}#{Rack::Utils.build_query(filtered)}"
       end
     end

data/lib/clowk/http/client.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'json'
-require 'net/http'
-require 'uri'
+require "json"
+require "net/http"
+require "uri"
 
 module Clowk
   class Http
@@ -121,7 +121,7 @@ module Clowk
 
       request.body = JSON.generate(env[:body]) unless env[:body].nil?
 
-      raw_response = Net::HTTP.start(env[:uri].host, env[:uri].port, use_ssl: env[:uri].scheme == 'https') do |http|
+      raw_response = Net::HTTP.start(env[:uri].host, env[:uri].port, use_ssl: env[:uri].scheme == "https") do |http|
         apply_timeouts(http, env[:timeouts])
         http.request(request)
       end
@@ -144,12 +144,12 @@ module Clowk
     end
 
     def normalize_path(path)
-      path.to_s.start_with?('/') ? path : "/#{path}"
+      path.to_s.start_with?("/") ? path : "/#{path}"
     end
 
     def join_paths(base_path, extra_path)
-      segments = [base_path.to_s, extra_path.to_s].map { |segment| segment.gsub(%r{^/+|/+$}, '') }.reject(&:empty?)
-      "/#{segments.join('/')}"
+      segments = [base_path.to_s, extra_path.to_s].map { |segment| segment.gsub(%r{^/+|/+$}, "") }.reject(&:empty?)
+      "/#{segments.join("/")}"
     end
 
     def apply_headers(request, request_headers)
@@ -167,8 +167,8 @@ module Clowk
 
     def default_headers
       {
-        'Accept' => 'application/json',
-        'Content-Type' => 'application/json'
+        "Accept" => "application/json",
+        "Content-Type" => "application/json"
       }
     end
 

data/lib/clowk/http/logger_middleware.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'logger'
+require "logger"
 
 module Clowk
   class Http
@@ -22,7 +22,8 @@ module Clowk
       attr_reader :app, :logger
 
       class NullLogger
-        def info(*); end
+        def info(*)
+        end
       end
     end
   end

data/lib/clowk/http/response.rb

@@ -27,17 +27,17 @@ module Clowk
           body: body,
           body_parsed: body_parsed,
           headers: headers,
-          success?: success?
+          success: success?
         }
       end
 
       def ==(other)
-        if other.respond_to?(:to_h)
-          to_h == other.to_h
+        to_h == if other.respond_to?(:to_h)
+          other.to_h
         else
-          to_h == other
+          other
         end
       end
     end
   end
-end
+end

data/lib/clowk/http/retry_middleware.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'net/http'
+require "net/http"
 
 module Clowk
   class Http
@@ -44,4 +44,4 @@ module Clowk
       attr_reader :app, :logger
     end
   end
-end
+end

data/lib/clowk/http/timeout_middleware.rb

@@ -27,4 +27,4 @@ module Clowk
       attr_reader :app, :logger, :open_timeout, :read_timeout, :write_timeout
     end
   end
-end
+end

data/lib/clowk/jwt_verifier.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require 'jwt'
+require "jwt"
 
 module Clowk
   class JwtVerifier
-    ALGORITHM = 'HS256'
+    ALGORITHM = "HS256"
 
     def initialize(secret_key: Clowk.config.secret_key, issuer: Clowk.config.issuer)
       @secret_key = secret_key
@@ -12,9 +12,9 @@ module Clowk
     end
 
     def verify(token)
-      raise ConfigurationError, 'missing Clowk secret_key' if @secret_key.to_s.empty?
+      raise ConfigurationError, "missing Clowk secret_key" if @secret_key.to_s.empty?
 
-      options = { algorithm: ALGORITHM }
+      options = {algorithm: ALGORITHM}
       options[:iss] = @issuer if @issuer
       options[:verify_iss] = @issuer.present?
 

data/lib/clowk/middleware/token_extractor.rb

@@ -17,8 +17,14 @@ module Clowk
 
       attr_reader :request, :token_param, :cookie_key
 
+      # Opt-in only. Reading a token from the query string on every request lets
+      # a link like /anything?token=<jwt> establish a session without ever
+      # passing the callback's `state` check, so callers that establish sessions
+      # pass token_param: nil. The callback reads params itself, after state.
       def token_from_params
-        params = request.respond_to?(:params) && request.params ? request.params : {}
+        return if token_param.nil?
+
+        params = (request.respond_to?(:params) && request.params) ? request.params : {}
         params[token_param.to_s].presence
       end
 
@@ -26,8 +32,8 @@ module Clowk
         header = request.authorization.to_s
         return if header.empty?
 
-        scheme, token = header.split(' ', 2)
-        return unless scheme.to_s.casecmp('Bearer').zero?
+        scheme, token = header.split(" ", 2)
+        return unless scheme.to_s.casecmp("Bearer").zero?
 
         token.presence
       end

data/lib/clowk/sdk/client.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require 'active_support/inflector'
+require "active_support/inflector"
 
 module Clowk
   module SDK
     class Client
       def initialize(options = {})
-        @api_base_url = options.fetch(:api_base_url, nil).presence || derive_api_base_url
+        @api_base_url = options.fetch(:api_base_url, nil).presence || Clowk.config.api_base_url
         @secret_key = options.fetch(:secret_key, Clowk.config.secret_key)
         @publishable_key = options.fetch(:publishable_key, Clowk.config.publishable_key)
       end
@@ -18,7 +18,7 @@ module Clowk
 
         return super unless Clowk::SDK.const_defined?(resource_class_name)
 
-        resource_ivar = "@#{method_name}"
+        resource_ivar = :"@#{resource_class_name}"
         return instance_variable_get(resource_ivar) if instance_variable_defined?(resource_ivar)
 
         resource_class = Clowk::SDK.const_get(resource_class_name)
@@ -65,13 +65,6 @@ module Clowk
 
       attr_reader :api_base_url, :publishable_key, :secret_key
 
-      def derive_api_base_url
-        base = Clowk.config.subdomain_url.to_s.strip
-        return if base.empty?
-
-        "#{base.sub(%r{/$}, '')}/api/v1"
-      end
-
       def http
         @http ||= Clowk::Http.new(
           base_url: api_base_url,
@@ -87,8 +80,8 @@ module Clowk
 
       def default_headers
         {}.tap do |headers|
-          headers['X-Clowk-Secret-Key'] = secret_key if secret_key.present?
-          headers['X-Clowk-Publishable-Key'] = publishable_key if publishable_key.present?
+          headers["X-Clowk-Secret-Key"] = secret_key if secret_key.present?
+          headers["X-Clowk-Publishable-Key"] = publishable_key if publishable_key.present?
         end
       end
     end

data/lib/clowk/sdk/resource.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require 'erb'
+require "erb"
 
 module Clowk
   module SDK
     class Resource
       def self.resource_path
-        raise NotImplementedError, 'resource_path must be implemented'
+        raise NotImplementedError, "resource_path must be implemented"
       end
 
       def initialize(client)
@@ -31,10 +31,10 @@ module Clowk
       # @return [Clowk::Http::Response]
       def search(raw_query = nil, **filters)
         query = if raw_query.is_a?(String)
-                  raw_query
-                else
-                  filters.map { |k, v| "#{k}:#{v}" }.join(' ')
-                end
+          raw_query
+        else
+          filters.map { |k, v| "#{k}:#{v}" }.join(" ")
+        end
 
         client.get("#{self.class.resource_path}/search?query=#{ERB::Util.url_encode(query)}")
       end

data/lib/clowk/sdk/session.rb

@@ -4,12 +4,16 @@ module Clowk
   module SDK
     class Session < Resource
       def self.resource_path
-        'sessions'
+        "sessions"
       end
 
-      # @param email [String] Email to search for (ILIKE match)
+      # @param raw_query [String, nil] Raw query string (forwarded to the base search)
+      # @param email [String, nil] Email to search for via the legacy ILIKE endpoint
+      # @param filters [Hash] Keyword filters (forwarded to the base search)
       # @return [Clowk::Http::Response]
-      def search(email:)
+      def search(raw_query = nil, email: nil, **filters)
+        return super(raw_query, **filters) unless email
+
         client.get("#{self.class.resource_path}/search?email=#{ERB::Util.url_encode(email)}")
       end
 

data/lib/clowk/sdk/session_config.rb

@@ -4,7 +4,7 @@ module Clowk
   module SDK
     class SessionConfig < Resource
       def self.resource_path
-        'session_config'
+        "session_config"
       end
 
       def fetch

data/lib/clowk/sdk/subdomain.rb

@@ -4,7 +4,7 @@ module Clowk
   module SDK
     class Subdomain < Resource
       def self.resource_path
-        'instances'
+        "instances"
       end
 
       def find_by_pk(key = nil)

data/lib/clowk/sdk/token.rb

@@ -4,16 +4,21 @@ module Clowk
   module SDK
     class Token < Resource
       def self.resource_path
-        'tokens'
+        "tokens"
       end
 
       def verify(token:)
-        client.post("#{self.class.resource_path}/verify", { token: token })
+        client.post("#{self.class.resource_path}/verify", {token: token})
       end
 
       def verify_with_session(token:)
         response = verify(token:)
-        data = response.body_parsed&.dig('data') || response.body_parsed
+
+        unless response.success?
+          raise Clowk::InvalidTokenError, response.body_parsed&.dig("error") || "token verification failed"
+        end
+
+        data = response.body_parsed&.dig("data") || response.body_parsed
 
         data&.deep_symbolize_keys
       end

data/lib/clowk/sdk/user.rb

@@ -4,7 +4,7 @@ module Clowk
   module SDK
     class User < Resource
       def self.resource_path
-        'users'
+        "users"
       end
     end
   end

data/lib/clowk/subdomain.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-require 'uri'
+require "uri"
 
 module Clowk
   class Subdomain
-    API_BASE_URL = 'https://api.clowk.dev/api/v1'
     CACHE_TTL = 60
-    DEFAULT_SUBDOMAIN_BASE = 'clowk.dev'
+    DEFAULT_SUBDOMAIN_BASE = "clowk.dev"
+
+    @cache_mutex = Mutex.new
 
     class << self
       def resolve_url!(...)
@@ -14,24 +15,28 @@ module Clowk
       end
 
       def clear_cache!
-        @cache = {}
+        @cache_mutex.synchronize { @cache = {} }
       end
 
       def read_cache(key)
-        entry = cache[key]
+        @cache_mutex.synchronize do
+          entry = cache[key]
 
-        return unless entry
-        return entry[:value] if entry[:expires_at] > Time.now
+          return unless entry
+          return entry[:value] if entry[:expires_at] > Time.now
 
-        cache.delete(key)
-        nil
+          cache.delete(key)
+          nil
+        end
       end
 
       def write_cache(key, value, ttl:)
-        cache[key] = {
-          value: value,
-          expires_at: Time.now + ttl
-        }
+        @cache_mutex.synchronize do
+          cache[key] = {
+            value: value,
+            expires_at: Time.now + ttl
+          }
+        end
       end
 
       private
@@ -50,7 +55,7 @@ module Clowk
       return resolve_from_key if publishable_key.present?
       return normalize_url(subdomain_url) if subdomain_url.present?
 
-      raise ConfigurationError, 'set publishable_key or subdomain_url to build Clowk URLs'
+      raise ConfigurationError, "set publishable_key or subdomain_url to build Clowk URLs"
     end
 
     private
@@ -64,7 +69,7 @@ module Clowk
       response = client.subdomains.find_by_pk(publishable_key)
       resolved = extract_url_from_instance(response.body_parsed)
 
-      raise ConfigurationError, 'could not resolve subdomain_url from publishable_key' if resolved.blank?
+      raise ConfigurationError, "could not resolve subdomain_url from publishable_key" if resolved.blank?
 
       self.class.write_cache(cache_key, resolved, ttl: CACHE_TTL)
       resolved
@@ -78,27 +83,27 @@ module Clowk
       return if payload.blank?
 
       root = payload.is_a?(Hash) ? payload : {}
-      instance_data = if root['instance'].is_a?(Hash)
-                        root['instance']
-                      elsif root['data'].is_a?(Hash)
-                        root['data']
-                      else
-                        root
-                      end
-
-      explicit_url = instance_data['url'] || instance_data['subdomain_url'] || instance_data['instance_url']
+      instance_data = if root["instance"].is_a?(Hash)
+        root["instance"]
+      elsif root["data"].is_a?(Hash)
+        root["data"]
+      else
+        root
+      end
+
+      explicit_url = instance_data["url"] || instance_data["subdomain_url"] || instance_data["instance_url"]
       return normalize_url(explicit_url) if explicit_url.present?
 
-      host = instance_data['host'] || instance_data['domain'] || instance_data['hostname']
+      host = instance_data["host"] || instance_data["domain"] || instance_data["hostname"]
       return normalize_url(host_to_url(host)) if host.present?
 
-      subdomain = instance_data['subdomain']
+      subdomain = instance_data["subdomain"]
       normalize_url("https://#{subdomain}.#{default_subdomain_base}") if subdomain.present?
     end
 
     def host_to_url(host)
       value = host.to_s
-      return value if value.start_with?('http://', 'https://')
+      return value if value.start_with?("http://", "https://")
 
       "https://#{value}"
     end
@@ -110,17 +115,17 @@ module Clowk
       uri = URI.parse(configured)
       return DEFAULT_SUBDOMAIN_BASE if uri.host.blank?
 
-      uri.host.split('.').drop(1).join('.')
+      uri.host.split(".").drop(1).join(".")
     rescue URI::InvalidURIError
       DEFAULT_SUBDOMAIN_BASE
     end
 
     def normalize_url(value)
-      value.to_s.sub(%r{/$}, '')
+      value.to_s.sub(%r{/$}, "")
     end
 
     def client
-      @client ||= Clowk::SDK::Client.new(api_base_url: API_BASE_URL)
+      @client ||= Clowk::SDK::Client.new(api_base_url: Clowk.config.api_base_url)
     end
   end
 end

data/lib/clowk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clowk
-  VERSION = '0.3.0'
+  VERSION = "0.4.0"
 end

data/lib/clowk.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-require 'rails'
-require 'rails/engine'
-require 'action_controller/railtie'
-require 'active_support'
-require 'active_support/core_ext/hash'
-require 'active_support/core_ext/object/blank'
-require 'rack'
+require "rails"
+require "rails/engine"
+require "action_controller/railtie"
+require "active_support"
+require "active_support/core_ext/hash"
+require "active_support/core_ext/object/blank"
+require "rack"
 
-require_relative 'clowk/version'
-require_relative 'clowk/configuration'
+require_relative "clowk/version"
+require_relative "clowk/configuration"
 
 module Clowk
   class Error < StandardError; end
@@ -24,6 +24,7 @@ module Clowk
 
     def configure
       yield(config)
+      config.validate!
     end
 
     def reset!
@@ -33,25 +34,25 @@ module Clowk
   end
 end
 
-require_relative 'clowk/current'
-require_relative 'clowk/http/response'
-require_relative 'clowk/http/logger_middleware'
-require_relative 'clowk/http/retry_middleware'
-require_relative 'clowk/http/timeout_middleware'
-require_relative 'clowk/http/client'
-require_relative 'clowk/sdk/resource'
-require_relative 'clowk/sdk/user'
-require_relative 'clowk/sdk/session'
-require_relative 'clowk/sdk/subdomain'
-require_relative 'clowk/sdk/token'
-require_relative 'clowk/sdk/session_config'
-require_relative 'clowk/sdk/client'
-require_relative 'clowk/subdomain'
-require_relative 'clowk/jwt_verifier'
-require_relative 'clowk/helpers/url_helpers'
-require_relative 'clowk/middleware/token_extractor'
-require_relative 'clowk/authenticable'
-require_relative 'clowk/controllers/base_controller'
-require_relative 'clowk/controllers/callbacks_controller'
-require_relative 'clowk/controllers/sessions_controller'
-require_relative 'clowk/engine'
+require_relative "clowk/current"
+require_relative "clowk/http/response"
+require_relative "clowk/http/logger_middleware"
+require_relative "clowk/http/retry_middleware"
+require_relative "clowk/http/timeout_middleware"
+require_relative "clowk/http/client"
+require_relative "clowk/sdk/resource"
+require_relative "clowk/sdk/user"
+require_relative "clowk/sdk/session"
+require_relative "clowk/sdk/subdomain"
+require_relative "clowk/sdk/token"
+require_relative "clowk/sdk/session_config"
+require_relative "clowk/sdk/client"
+require_relative "clowk/subdomain"
+require_relative "clowk/jwt_verifier"
+require_relative "clowk/helpers/url_helpers"
+require_relative "clowk/middleware/token_extractor"
+require_relative "clowk/authenticable"
+require_relative "clowk/controllers/base_controller"
+require_relative "clowk/controllers/callbacks_controller"
+require_relative "clowk/controllers/sessions_controller"
+require_relative "clowk/engine"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: clowk
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Clowk
 bindir: bin
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -77,6 +77,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: Clowk Authentication, JWT verification, and future API access
 email:
 - support@clowk.in
@@ -114,7 +128,7 @@ files:
 - lib/clowk/version.rb
 homepage: https://clowk.in
 licenses:
-- AGPL-3.0
+- AGPL-3.0-only
 metadata:
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -131,7 +145,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Rails SDK for Clowk authentication
 test_files: []