hanko-ruby 0.1.1

data/lib/hanko/configuration.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Hanko
+  # Holds configuration options for the Hanko SDK.
+  #
+  # Set values via {Hanko.configure} or pass them directly to {Hanko::Client#initialize}.
+  #
+  # @example
+  #   Hanko.configure do |c|
+  #     c.api_url  = "https://example.hanko.io"
+  #     c.api_key  = "your-api-key"
+  #     c.timeout  = 10
+  #   end
+  class Configuration
+    ATTRIBUTES = %i[
+      api_url api_key timeout open_timeout retry_count
+      clock_skew jwks_cache_ttl logger log_level
+    ].freeze
+
+    # @!attribute [rw] api_url
+    #   @return [String, nil] the Hanko API base URL
+    # @!attribute [rw] api_key
+    #   @return [String, nil] the API key for admin endpoints
+    # @!attribute [rw] timeout
+    #   @return [Integer] request timeout in seconds (default: 5)
+    # @!attribute [rw] open_timeout
+    #   @return [Integer] connection open timeout in seconds (default: 2)
+    # @!attribute [rw] retry_count
+    #   @return [Integer] number of automatic retries (default: 1)
+    # @!attribute [rw] clock_skew
+    #   @return [Integer] allowed clock skew in seconds for token validation (default: 0)
+    # @!attribute [rw] jwks_cache_ttl
+    #   @return [Integer] JWKS cache time-to-live in seconds (default: 3600)
+    # @!attribute [rw] logger
+    #   @return [Logger, nil] optional logger instance
+    # @!attribute [rw] log_level
+    #   @return [Symbol] log level (default: :info)
+    attr_accessor(*ATTRIBUTES)
+
+    # Creates a new Configuration with sensible defaults.
+    #
+    # @return [Configuration]
+    def initialize
+      @timeout = 5
+      @open_timeout = 2
+      @retry_count = 1
+      @clock_skew = 0
+      @jwks_cache_ttl = 3600
+      @log_level = :info
+    end
+
+    # Returns a human-readable representation with the API key redacted.
+    #
+    # @return [String]
+    def inspect
+      attrs = ATTRIBUTES.map do |key|
+        value = send(key)
+        value = '[REDACTED]' if key == :api_key && value
+        "#{key}=#{value.inspect}"
+      end
+      "#<#{self.class} #{attrs.join(', ')}>"
+    end
+  end
+end

data/lib/hanko/connection.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require_relative 'middleware/raise_error'
+
+module Hanko
+  # Low-level HTTP wrapper around Faraday.
+  #
+  # Configures the Faraday connection with authentication headers,
+  # timeouts, and the {Middleware::RaiseError} middleware.
+  class Connection
+    # @return [Faraday::Connection] the underlying Faraday connection
+    attr_reader :connection
+
+    # Builds a new Connection from the given configuration.
+    #
+    # @param config [Configuration] SDK configuration
+    # @param adapter [Array, nil] optional Faraday adapter override (for testing)
+    # @return [Connection]
+    def initialize(config, adapter: nil)
+      @connection = build_connection(config, adapter)
+    end
+
+    # Performs an HTTP GET request.
+    #
+    # @param path [String] the request path
+    # @param params [Hash] query parameters
+    # @return [Faraday::Response]
+    def get(path, params = {})
+      connection.get(path, params)
+    end
+
+    # Performs an HTTP POST request with a JSON body.
+    #
+    # @param path [String] the request path
+    # @param body [Hash] the request body (serialized to JSON)
+    # @return [Faraday::Response]
+    def post(path, body = {})
+      connection.post(path, JSON.generate(body))
+    end
+
+    # Performs an HTTP PUT request with a JSON body.
+    #
+    # @param path [String] the request path
+    # @param body [Hash] the request body (serialized to JSON)
+    # @return [Faraday::Response]
+    def put(path, body = {})
+      connection.put(path, JSON.generate(body))
+    end
+
+    # Performs an HTTP PATCH request with a JSON body.
+    #
+    # @param path [String] the request path
+    # @param body [Hash] the request body (serialized to JSON)
+    # @return [Faraday::Response]
+    def patch(path, body = {})
+      connection.patch(path, JSON.generate(body))
+    end
+
+    # Performs an HTTP DELETE request.
+    #
+    # @param path [String] the request path
+    # @param params [Hash] query parameters
+    # @return [Faraday::Response]
+    def delete(path, params = {})
+      connection.delete(path, params)
+    end
+
+    private
+
+    def build_connection(config, adapter)
+      Faraday.new(url: config.api_url) do |f|
+        f.headers['Content-Type'] = 'application/json'
+        f.headers['Accept'] = 'application/json'
+        f.headers['Authorization'] = "Bearer #{config.api_key}" if config.api_key
+
+        f.options.timeout = config.timeout
+        f.options.open_timeout = config.open_timeout
+
+        f.use Middleware::RaiseError
+        f.request :json
+
+        if adapter
+          f.adapter(*adapter)
+        else
+          f.adapter Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/hanko/errors.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Hanko
+  # Base error class for all Hanko SDK errors.
+  class Error < StandardError; end
+
+  # Raised when the SDK configuration is invalid or incomplete.
+  class ConfigurationError < Error; end
+
+  # Raised when a JWT token cannot be decoded or has an invalid signature.
+  class InvalidTokenError < Error; end
+
+  # Raised when a JWT token has expired.
+  class ExpiredTokenError < Error; end
+
+  # Raised when JWKS fetching or parsing fails.
+  class JwksError < Error; end
+
+  # Raised when a network-level connection error occurs.
+  class ConnectionError < Error; end
+
+  # Raised when the Hanko API returns an HTTP 4xx or 5xx response.
+  class ApiError < Error
+    # @return [Integer, nil] the HTTP status code
+    attr_reader :status
+
+    # @return [Hash, nil] the parsed response body
+    attr_reader :body
+
+    # @param message [String, nil] the error message
+    # @param status [Integer, nil] the HTTP status code
+    # @param body [Hash, nil] the parsed response body
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message)
+    end
+  end
+
+  # Raised when the API returns HTTP 401 Unauthorized.
+  class AuthenticationError < ApiError; end
+
+  # Raised when the API returns HTTP 404 Not Found.
+  class NotFoundError < ApiError; end
+
+  # Raised when the API returns HTTP 429 Too Many Requests.
+  class RateLimitError < ApiError
+    # @return [Integer, nil] seconds to wait before retrying
+    attr_reader :retry_after
+
+    # @param message [String, nil] the error message
+    # @param status [Integer, nil] the HTTP status code
+    # @param body [Hash, nil] the parsed response body
+    # @param retry_after [Integer, nil] seconds to wait before retrying
+    def initialize(message = nil, status: nil, body: nil, retry_after: nil)
+      @retry_after = retry_after
+      super(message, status: status, body: body)
+    end
+  end
+end

data/lib/hanko/flow_response.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Hanko
+  # Structured response from a Hanko passkey flow endpoint.
+  #
+  # Wraps the raw response hash and provides convenience accessors
+  # for status, available actions, session token, and user ID.
+  class FlowResponse
+    # @return [Symbol, nil] the flow status (e.g. :completed, :error)
+    attr_reader :status
+
+    # @return [Array<Resource>] available actions in the current flow state
+    attr_reader :actions
+
+    # @return [String, nil] the session token, if present in the payload
+    attr_reader :session_token
+
+    # @return [String, nil] the user ID, if present in the payload
+    attr_reader :user_id
+
+    # @return [Hash] the raw response hash
+    attr_reader :raw
+
+    # Creates a new FlowResponse from a parsed response hash.
+    #
+    # @param data [Hash] the parsed JSON response from a flow endpoint
+    def initialize(data)
+      @raw = data
+      @status = data["status"]&.to_sym
+      @actions = (data["actions"] || []).map { |a| Resource.new(a) }
+      @session_token = data.dig("payload", "session_token")
+      @user_id = data.dig("payload", "user_id")
+    end
+
+    # Returns true when the flow has completed successfully.
+    #
+    # @return [Boolean]
+    def completed?
+      status == :completed
+    end
+
+    # Returns true when the flow has entered an error state.
+    #
+    # @return [Boolean]
+    def error?
+      status == :error
+    end
+
+    # Returns the raw response hash.
+    #
+    # @return [Hash]
+    def to_h
+      @raw
+    end
+  end
+end

data/lib/hanko/middleware/raise_error.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Hanko
+  module Middleware
+    # Faraday middleware that raises typed Hanko errors for HTTP 4xx/5xx responses.
+    #
+    # Maps specific HTTP status codes to error classes:
+    # - 401 -> {AuthenticationError}
+    # - 404 -> {NotFoundError}
+    # - 429 -> {RateLimitError}
+    # - All others -> {ApiError}
+    class RaiseError < Faraday::Middleware
+      # Called by Faraday after each request completes.
+      #
+      # @param env [Faraday::Env] the request/response environment
+      # @return [void]
+      # @raise [AuthenticationError] on HTTP 401
+      # @raise [NotFoundError] on HTTP 404
+      # @raise [RateLimitError] on HTTP 429
+      # @raise [ApiError] on any other HTTP 4xx/5xx
+      def on_complete(env)
+        return if env.status < 400
+
+        body = parse_body(env.body)
+        message = body['message'] || body['error'] || "HTTP #{env.status}"
+
+        raise error_for(env.status, message, body, env.response_headers)
+      end
+
+      private
+
+      def error_for(status, message, body, headers)
+        case status
+        when 401
+          AuthenticationError.new(message, status: status, body: body)
+        when 404
+          NotFoundError.new(message, status: status, body: body)
+        when 429
+          retry_after = headers['Retry-After']&.to_i
+          RateLimitError.new(message, status: status, body: body, retry_after: retry_after)
+        else
+          ApiError.new(message, status: status, body: body)
+        end
+      end
+
+      def parse_body(body)
+        return {} if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/hanko/resource.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Hanko
+  # Lightweight wrapper around a Hash that provides dot-notation access.
+  #
+  # Nested hashes are automatically wrapped in their own {Resource} instances.
+  #
+  # @example
+  #   resource = Hanko::Resource.new("id" => "abc", "email" => "a@b.com")
+  #   resource.id    #=> "abc"
+  #   resource[:email] #=> "a@b.com"
+  class Resource
+    # Creates a new Resource from a hash of attributes.
+    #
+    # @param attributes [Hash] the raw attribute hash
+    def initialize(attributes = {})
+      @attributes = normalize(attributes)
+    end
+
+    # Retrieves an attribute by key (string or symbol).
+    #
+    # @param key [String, Symbol] the attribute name
+    # @return [Object, nil] the attribute value
+    def [](key)
+      @attributes[key.to_s]
+    end
+
+    # Converts the resource (and any nested resources) to a plain Hash.
+    #
+    # @return [Hash]
+    def to_h
+      @attributes.transform_values do |v|
+        v.is_a?(Resource) ? v.to_h : v
+      end
+    end
+
+    # Returns a human-readable representation of the resource.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class} #{@attributes.inspect}>"
+    end
+
+    # Builds an array of Resource instances from an array of hashes.
+    #
+    # @param array [Array<Hash>] array of attribute hashes
+    # @return [Array<Resource>]
+    def self.from_array(array)
+      array.map { |attrs| new(attrs) }
+    end
+
+    # Returns true for all method names, enabling dynamic attribute access.
+    #
+    # @param _method_name [Symbol]
+    # @param _include_private [Boolean]
+    # @return [Boolean]
+    def respond_to_missing?(_method_name, _include_private = false)
+      true
+    end
+
+    private
+
+    def method_missing(method_name, *args)
+      if args.empty? && !block_given?
+        self[method_name]
+      else
+        super
+      end
+    end
+
+    def normalize(attributes)
+      attributes.each_with_object({}) do |(key, value), hash|
+        hash[key.to_s] = value.is_a?(Hash) ? self.class.new(value) : value
+      end
+    end
+  end
+end

data/lib/hanko/test_helper.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'openssl'
+require 'json'
+require 'webmock'
+
+module Hanko
+  # Test utilities for generating JWT tokens and stubbing Hanko endpoints.
+  #
+  # Provides helpers that make it easy to test Hanko authentication
+  # without hitting a real Hanko API.
+  #
+  # @example Generate a test token and stub JWKS
+  #   token = Hanko::TestHelper.generate_test_token(sub: "user-123", exp: Time.now.to_i + 3600)
+  #   Hanko::TestHelper.stub_jwks(api_url: "https://example.hanko.io")
+  module TestHelper
+    # A simple stub that returns a fixed payload instead of verifying a token.
+    class StubVerifier
+      # @param payload [Hash] the payload to return on verify
+      def initialize(payload)
+        @payload = payload
+      end
+
+      # Returns the fixed payload, ignoring the token.
+      #
+      # @param _token [String] ignored
+      # @return [Hash] the stub payload
+      def verify(_token)
+        @payload
+      end
+    end
+
+    class << self
+      # Generates a signed JWT test token using an ephemeral RSA key.
+      #
+      # @param sub [String] the subject claim (user ID)
+      # @param exp [Integer] the expiration time as a Unix timestamp
+      # @param extra_claims [Hash] additional claims to include in the payload
+      # @return [String] the encoded JWT token
+      #
+      # @example
+      #   token = Hanko::TestHelper.generate_test_token(sub: "user-123", exp: Time.now.to_i + 3600)
+      def generate_test_token(sub:, exp:, **extra_claims)
+        payload = { 'sub' => sub, 'exp' => exp }.merge(extra_claims.transform_keys(&:to_s))
+        JWT.encode(payload, test_key, 'RS256', kid: test_kid)
+      end
+
+      # Returns a JSON string containing the test JWKS (public key set).
+      #
+      # @return [String] JSON-encoded JWKS response body
+      def test_jwks_response
+        jwk = JWT::JWK.new(test_key, kid: test_kid)
+        { keys: [jwk.export] }.to_json
+      end
+
+      # Stubs the JWKS endpoint using WebMock so tokens from {generate_test_token} can be verified.
+      #
+      # @param api_url [String] the Hanko API base URL
+      # @return [WebMock::RequestStub] the WebMock stub
+      #
+      # @example
+      #   Hanko::TestHelper.stub_jwks(api_url: "https://example.hanko.io")
+      def stub_jwks(api_url:)
+        WebMock::API.stub_request(:get, "#{api_url}/.well-known/jwks.json")
+                    .to_return(status: 200, body: test_jwks_response)
+      end
+
+      # Creates a StubVerifier that returns a fixed session payload without cryptographic verification.
+      #
+      # @param sub [String] the subject claim (user ID)
+      # @param exp [Integer] the expiration time as a Unix timestamp
+      # @param extra_claims [Hash] additional claims to include in the payload
+      # @return [StubVerifier] a verifier that returns the given payload
+      #
+      # @example
+      #   verifier = Hanko::TestHelper.stub_session(sub: "user-123", exp: Time.now.to_i + 3600)
+      #   verifier.verify("any-token") #=> {"sub" => "user-123", "exp" => ...}
+      def stub_session(sub:, exp:, **extra_claims)
+        payload = { 'sub' => sub, 'exp' => exp }.merge(extra_claims.transform_keys(&:to_s))
+        StubVerifier.new(payload)
+      end
+
+      private
+
+      def test_key
+        @test_key ||= OpenSSL::PKey::RSA.generate(2048)
+      end
+
+      def test_kid
+        'hanko-test-kid'
+      end
+    end
+  end
+end

data/lib/hanko/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hanko
+  VERSION = '0.1.1'
+end

data/lib/hanko/webhook_verifier.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'faraday'
+require 'json'
+
+module Hanko
+  # Verifies Hanko webhook JWT tokens against a remote JWKS endpoint.
+  #
+  # @example Verify a webhook token
+  #   payload = Hanko::WebhookVerifier.verify(token, jwks_url: "https://example.hanko.io/.well-known/jwks.json")
+  #   puts payload["sub"]
+  class WebhookVerifier
+    ALGORITHM = 'RS256'
+
+    # Decodes and verifies a JWT token using keys from the given JWKS URL.
+    #
+    # @param token [String] the JWT token to verify
+    # @param jwks_url [String] URL of the JWKS endpoint
+    # @return [Hash] the decoded JWT payload
+    # @raise [ExpiredTokenError] if the token has expired
+    # @raise [InvalidTokenError] if the token is invalid or cannot be decoded
+    def self.verify(token, jwks_url:)
+      jwks = fetch_jwks(jwks_url)
+      decoded = JWT.decode(token, nil, true, algorithms: [ALGORITHM], jwks: jwks)
+      decoded.first
+    rescue JWT::ExpiredSignature => e
+      raise ExpiredTokenError, e.message
+    rescue JWT::DecodeError => e
+      raise InvalidTokenError, e.message
+    end
+
+    def self.fetch_jwks(url)
+      response = Faraday.get(url)
+      jwks_data = JSON.parse(response.body)
+      JWT::JWK::Set.new(jwks_data)
+    rescue JSON::ParserError, Faraday::Error => e
+      raise InvalidTokenError, "Failed to fetch JWKS: #{e.message}"
+    end
+
+    private_class_method :fetch_jwks
+  end
+end

data/lib/hanko.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'hanko/version'
+require_relative 'hanko/errors'
+require_relative 'hanko/resource'
+require_relative 'hanko/flow_response'
+require_relative 'hanko/configuration'
+require_relative 'hanko/middleware/raise_error'
+require_relative 'hanko/connection'
+require_relative 'hanko/api/base_resource'
+require_relative 'hanko/api/admin'
+require_relative 'hanko/api/public'
+require_relative 'hanko/client'
+require_relative 'hanko/webhook_verifier'
+require_relative 'hanko/test_helper'
+
+# Top-level module for the Hanko Ruby SDK.
+#
+# Provides authentication and user management via the Hanko API.
+# Use {.configure} to set global defaults shared across all {Client} instances.
+#
+# @example Configure global defaults
+#   Hanko.configure do |c|
+#     c.api_url  = "https://example.hanko.io"
+#     c.api_key  = "your-api-key"
+#     c.timeout  = 10
+#   end
+#
+# @example Create a client using global configuration
+#   client = Hanko::Client.new
+module Hanko
+  class << self
+    # Returns the global configuration instance.
+    #
+    # @return [Configuration] the current global configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the global configuration for modification.
+    #
+    # @yield [config] the global {Configuration} instance
+    # @yieldparam config [Configuration]
+    # @return [void]
+    #
+    # @example
+    #   Hanko.configure do |c|
+    #     c.api_url = "https://example.hanko.io"
+    #     c.api_key = "your-api-key"
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Resets the global configuration to defaults.
+    #
+    # @return [void]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end